Syntax
PXL_RETURN_CODE PxLGetEncodedClip ( HANDLE hCamera, U32 numberOfFramesToCapture, LPCSTR pFileName, PCLIP_ENCODING_INFO pClipInfo, U32 (__stdcall * pTerminationFunction) ( HANDLE hCamera, U32 numberOfFrameBlocksStreamed, PXL_RETURN_CODE retCode ) );
Description
This function saves clip as an raw encoded (compressed) video file. Currently, the supported encoding strategies are H264 and H265. Once the video clip file is created, it can be converted to a more traditional encoded video format (such as .mp4) suitable for playback with video players, using the PxLFormatClipEx function.
hCamera is the camera handle. This value is returned by PxLInitializeEx.
numberOfFramesToCapture is the number of frames to be captured in the clip.
pFileName is the name of the raw encoded video file to be created.
pClipInfo points to a data structure describing the characteristics to be used for the encoded video clip. See PCLIP_ENCODING_INFO
pTerminationFunction is the pointer to the function to be called when:
the camera has streamed (for capture) the required number of frames,
the operating system reported disk full while writing to the clip,
the operating system reported problems while writing to the clip,
the application requests termination by stopping the video stream (using the PxLSetStreamState function with the stream state set to STOP_STREAM).
numberOfFrameBlocksStreamed is the number of frame blocks the camera sent during the capture period. A frame block is a set of ‘clipDecimationFactor’ frames. So, if clipDecimationFactor is 1 (the default), then a frame block is equivalent to a frame. If clipdecimationFactor is 2, then a frame block consists of 2 frame, and so on. Ordinarily, this value is equal to numberOfFramesToCapture. Circumstances when this value may be different than numberOfFramesToCapture are described in the comments section below.
retCode is the returned value indicating the status of the call. Per the reasons given above, the possible responses are:
“ApiSuccess” (function completed successfully),
“ApiSuccessWithFrameLoss” (video captured OK, but some frames from the camera were skipped),
“ApiDiskFullError” (process forced to halt because of disk full),
“ApiIOError” (process forced to halt because of problems writing to the clip file), or
“ApiStreamStoppedError” (the application has stopped the stream).
Usage
// Somewhere in the file we declare some static variables
static volatile int s_getClipFinished = 0; // will be set to 1 by the callback function
static PXL_RETURN_CODE s_getClipReturnCode = ApiUnknownError;
// Somewhere in the code, we initiate the video capture
s_getClipFinished = 0; // Will poll this for termination of PxLGetClip.
CLIP_ENCODING_INFO clipInfo;
clipInfo.uStreamEncoding = CLIP_ENCODING_H264;
clipInfo.uDecimationFactor = CLIP_DECIMATON_NONE; //No decimation
clipInfo.playbackFrameRate = CLIP_PLAYBACK_FRAMERATE_CAPTURE;
clipInfo.playbackBitRate = CLIP_PLAYBACK_BITRATE_DEFAULT;
// Initiate the clip capture
// NOTE: This is not a blocking call!
// Remember that we can specify a function pointer just by using the name of the function
PXL_RETURN_CODE rc = PxLGetEncodedClip (hCamera, numImages, &h264File[0], &clipInfo, CaptureDoneCallback);
if (! API_SUCCESS(rc)) {
printf("Unable to start PxLGetEncodedClip\n");
// Your error handling here
} else {
// May want to use polling, or just continue on doing whatever needs to be done.
// If using polling, will need to use a volatile variable to communicate between
// the termination callback function and here.
while(!s_getClipFinished) {
Sleep(100);
}
printf("PxLGetEncodedClip termination callback function returned 0x%8.8X\n", s_getClipReturnCode);
}
//
// Elsewhere in the code is our definition of
// the PxLGetEncodedClip termination callback function.
//
// Note the __stdcall calling convention.
//
U32 __stdcall
CaptureDoneCallback (HANDLE hCamera, U32 numberOfFramesCaptured, PXL_RETURN_CODE retCode)
{
printf("PxLGetEncodedClip has reported termination: ");
switch(retCode)
{
case ApiSuccess:
printf("Success.\n");
break;
case ApiSuccessWithFrameLoss:
printf("Success, but had some frame loss.\n");
break;
case ApiDiskFullError:
printf("Error - problems writing to disk (disk full?).\n");
break;
case ApiIOError:
printf("Error - problems writing to disk.\n");
break;
case ApiStreamStoppedError:
printf("Application requested termination.\n");
break;
default:
printf("Error 0x%8.8X\n", uRetCode);
break;
}
s_getClipReturnCode = retCode;
s_getClipFinished = 1;
return 0; // Termination function finished.
}
Comments, Restrictions and Limitations
To use this function, cameras must be using PIXEL_FORMAT_MONO8 (monochrome camera) or PIXEL_FORMAT_YUV422 (color camera). Using any other pixel format will return an ApiUnsupportedPixelFormatError.
This function can be used to capture normal speed (real-time), high speed (slow-motion), or slow speed (fast motion, or time-lapse) video. The video speed is controlled via the pClipInfo -> playbackFrameRate field; the video will be high speed when this field is less than the camera's current frame rate (FEATURE_ACTUAL_FRAME_RATE), and slow speed when this field is lower than the cameras current frame rate. To capture a normal (real-time) speed video, match pClipInfo -> playbackFrameRate to the camera's frame rate, by supplying a playbackFrameRate of CLIP_PLAYBACK_FRAMERATE_CATURE (0.0f).
pClipInfo->playbackBitRate specifies the estimated ‘output capacity’ of the video decoder (the video player). In practice, this number is used to provide guidance to the compression engine, of how much compression should be attempted on the video. Higher pClipInfo -> playbackBitRates will result in larger compressed video files, and generally contain higher quality images that are ‘easier’ to encode and decode. An application can use this parameter to ‘tune’ the video capture to their particular system. If your system has a lot of computing power but a relatively slow disk, or if disk storage is at a premium, consider specifying a lower pClipInfo -> playbackBitRate. If your system has a fast disk (such as a solid state drive), you could specify a higher pClipInfo -> playbackBitRate, and economize on CPU resources needed to encode/decode the video. The default CLIP_PLAYBACK_BITRATE_DEFAULT (1,000,000) will work for most systems, but a pClipInfo -> playbackBitRate value that is not tuned to your system could result in capture returning a ApiSuccessWithFrameLoss return code.
The ApiSuccessWithFrameLoss return code indicates that video capture mechanism was not able to keep pace with camera’s current stream. How many frames that were lost during the capture can be determined by looking at numberOfFrameBlocksStreamed parameter. There can be several factors that contribute to this number being greater than the expected numberOfFramesToCapture value:
There is simply too much target data. That is, the images contain too much data to process at the current capture rate. Consider reducing the size of the image using FEATURE_ROI or FEATURE_PIXEL_ADDRESSING
The capture rate is too high. Consider reducing FEATURE_FRAME_RATE
If the amount of target data is too high, and cannot be reduced using FEATURE_ROI, FEATURE_PIXEL_ADDRESSING, or FEATURE_FRAME_RATE, then consider increasing captureDecimationFactor.
The target data is ‘difficult’ to compress. Often times, there is not much the application can do about this, but sometimes simple adjustments in parameters like exposure or gain settings, can have a significant impact.
The compression engine cannot keep pace because it is CPU limited – consider increasing playbackBitRate
The compression engine cannot keep pace because it is disk limited – consider decreasing playbackBitRate
Please note, it is possible that numberOfFrameBlocksStreamed could be less than numberOfFramesToCapture. This would occur if the stream is stopped before the camera has sent numberOfFramesToCapture images; thus aborting the capture.