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 PxLFormatClip.


  • hCamera is the camera handle.  This value is returned by PxLInitialize

  • 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 PxLFormatClip.


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.