PxLSetCallback

Syntax

 PXL_RETURN_CODE PxLSetCallback (

  HANDLE hCamera,
  U32    callbackType,
  void*  pContext,
  U32 (__stdcall * pDataProcessFunction)(

      HANDLE             hCamera,
      void*              pFrameData,
      U32                dataFormat,
      FRAME_DESC const * pFrameDesc,
      void*              pContext ) );

 Description

This function installs a user-defined callback that will be called by the API in one of four circumstances, depending on the value of the callbackType parameter.  The possible values of callbackType are defined in the header file PixeLINKTypes.h, and described in Callback Flags.  The callback types are:

• CALLBACK_PREVIEW – The callback is called just before a frame is displayed in the preview window.  The pixel data will have already been converted into either RGB24 or MONO8 format for display, so your callback should be prepared to handle these data formats.  The data is writable, and any changes made will be reflected in the preview window.

• CALLBACK_FRAME  - The callback is called as each frame arrives from the driver.  The pixel data will be in the raw format received from the camera (e.g. BAYER8_GRBG, etc.).  The data should be considered read-only.  If the callback function does modify the pixel data, those changes are not guaranteed to be propagated – that is, the changes may not be reflected in the preview window, or in images captured with PxLGetNextFrame.  The exact behavior depends on the version of the API being used, and is subject to change.

• CALLBACK_FORMAT_IMAGE – The callback is called just before a frame is formatted by the PxLFormatImage function.  The pixel data will have already been converted into an intermediate format (e.g.  RGB24 or MONO8) when the callback is called.  The data is writable, and any changes made will be reflected in the formatted image.

• CALLBACK_FORMAT_CLIP – The callback is called just before each frame from a PDS file is added to the AVI file during a call to PxLFormatClip.  The data is writable, and any changes made will be reflected in the AVI file.

Callbacks are generally used to analyze or modify image data.  Examples include:

• Calculating a histogram.

• Applying a filter or other form of image processing to the data – e.g.: Smoothing, sharpening, Thresholding, etc.

• Overlaying a bitmap onto the image data – e.g. a corporate logo or a timestamp.

Two of the four callback types – CALLBACK_PREVIEW and CALLBACK_FRAME – are camera-specific.  This means that the callback will only be called for frames received from the specific camera for which the callback was installed, based on the hCamera parameter to PxLSetCallback.

The other two callback types, CALLBACK_FORMAT_CLIP and CALLBACK_FORMAT_IMAGE, are API-global – i.e., they are not camera-specific.

Parameters

• hCamera determines which camera frames a CALLBACK_PREVIEW or CALLBACK_FRAME callback will be applied to.  When installing CALLBACK_FORMAT_IMAGE or CALLBACK_FORMAT_CLIP callbacks, the hCamera parameter passed is ignored. WARNING: In earlier versions of the API, a valid camera handle had to be supplied, or an error code was returned.  This has been corrected in later versions of the API.

  
  

• callbackType provides the case(s) in which this callback function should be used.  See Callback Flags for valid flags.

• pContext is a parameter that can be used to have additional information passed to your callback function.  It is optional, and can be NULL. However, for CALLBACK_COMPRESSED_FRAME, it is not optional. Specifically, it must be supplied, and it must provide a pointer to a data structure that has a COMPRESSION_INFO structure at the beginning. Furthermore, the COMPRESSION_INFO.compressionStrategy field must specify the compression strategy to which the callback is being applied (currently, the only support strategy is FEATURE_COMPRESSION_STRATEGY_PIXELINK10). The C/C++ demo application 'callbackCompressed' demonstrates a technique how to do it. The callback function will have the COMPRESSION_INFO.commpressionDesc filled in by the Pixelink API (this information will be required by PxLDecompressFrame to do the decompression) for each (compressed) frame returned to the callback. The data structure supplied by this pointer, may have additional (user defined) data following the COMPRESSION_INFO.

  
  

• pDataProcessFunction is a function pointer to a user-defined callback function.  This function will be called by the API with the following parameters:

  • hCamera is the handle of the camera sending the data.  In the CALLBACK_FORMAT_IMAGE and CALLBACK_FORMAT_CLIP callbacks, this parameter will be NULL.

  • pFrameData is the pointer to the pixel data.  The data can be in one of several different data formats, depending on when this function is called.  The format of the data is determined by the dataFormat parameter.  The size of the memory block pointed to can be calculated based on the contents of the FRAME_DESC structure in the pDescriptor parameter.

  • dataFormat is the format of the frame data.  Possible values are described in Pixel Formats. 

  • pFrameDesc is a  pointer to a FRAME_DESC structure that describes the current frame.

  • pContext is the value that was passed as the pContext parameter to PxLSetCallback.

Usage

 //
 // Function that is called before a frame is sent to the preview window.
 //

 U32 __stdcall MyPreviewCallback(HANDLE           hCamera,
 void*              pFrameData,
 U32                dataFormat,
 FRAME_DESC const * pFrameDesc,
 void*              pContext)
 {

     // Process the frame here. 
     // NOTE: For preview callbacks, the frame data is writable.  
     // NOTE: The frame descriptor provided is const.

     return ApiSuccess;

 }


 int main(char *argv[], int argc)
 {

     HANDLE hCamera;

     // Initialization (initialization, start stream, start preview, etc.) omitted.

     // Set the callback function

     PxLSetCallback(hCamera, CALLBACK_PREVIEW, NULL, MyPreviewCallback);

     // error handling omitted


     // Watch the preview for a few seconds...

     Sleep(3000); 


     // Disable the preview callback by setting the callback function to NULL

     PxLSetCallback(hCamera, CALLBACK_PREVIEW, NULL, NULL);
 

     // Uninitialization (stop preview, stop stream, uninitialize, etc.) omitted

 
     return 0;

 }

Comments, Restrictions and Limitations

If the pDataProcessFunction parameter is set to NULL, then the callback function will be removed for the specified case(s). Otherwise, the current callback function will be replaced with the new one.
 

You should limit the amount of time spent in CALLBACK_PREVIEW and CALLBACK_FRAME callback functions.  If the callback function takes too long, frames will be missed.

PxLGetNextFrame cannot be called for a camera if a CALLBACK_FRAME callback is set. The typical use for CALLBACK_FRAME is:

• Register a CALLBACK_FRAME callback function.

• Start streaming.

• Process received images in the CALLBACK_FRAME callback function.

• Stop streaming when done.

Note that CALLBACK_PREVIEW and CALLBACK_FRAME callback functions will be called in the context of a worker thread started by the API.  If your callback function accesses any data structures that are shared with the application’s other threads, you should synchronise access to that data.

The FRAME_DESC structure is defined in the file PixeLINKTypes.h.

 
Summary