Syntax
PXL_RETURN_CODE PxLGetClip ( HANDLE hCamera, U32 numberOfFramesToCapture, LPCSTR pFileName, U32 (__stdcall * pTerminationFunction) ( HANDLE hCamera, U32 numberOfFramesCaptured, PXL_RETURN_CODE retCode ) );
Description
This function saves a clip of video to a PixeLINK data stream (.pds) file. This file can be converted to another format using PxLFormatClipEx.
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 PixeLINK data stream file to be created.
pTerminationFunction is the pointer to the function to be called when:
the function has acquired 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).
hImager is the handle of the camera sending the data.
numberOfFramesCaptured is the actual number of frames captured into the clip.
retCode is the returned value indicating the status of the call. Per the reasons given above, the possible responses are:
“ApiSuccess” (function completed successfully),
“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.
// 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 = PxLGetClip(hCamera, numberOfFramesToCapture, pFileName, TerminationFunction);
if (!API_SUCCESS(rc)) {
printf("Unable to start PxLGetClip\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("PxLGetClip termination callback function returned 0x%8.8X\n", s_getClipReturnCode);
}
//
// Elsewhere in the code is our definition of
// the PxLGetClip termination callback function.
//
// Note the __stdcall calling convention.
//
U32 __stdcall
TerminationFunction(HANDLE hCamera, U32 numberOfFramesCaptured, PXL_RETURN_CODE retCode)
{
printf("PxLGetClip has reported termination: ");
switch(retCode)
{
case ApiSuccess:
printf("Success.\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
Before this function is called, the camera associated by the handle hCamera must be streaming. Use the PxLSetStreamState function with the stream state set to START_STREAM.
If the stream is stopped by the PxLSetStreamState function (with the stream state set to STOP_STREAM) before the PxLGetClip function can complete the clip, the clip will be saved with the number of frames captured up to the point that the stream is stopped.
The PixeLINK data stream file (.pds) that is created can be converted to an AVI file using PxLFormatClipEx.
In addition to video image data, the PixeLINK data stream file includes descriptors containing sets of properties for each frame in the file. For more information, go to descriptors.