This VI sets a callback VI to process the video stream data or to signal the termination of a video clip capture thread.  The VI can also be used to delete callbacks.



................................................................................................................................................................................


Controls and Indicators



         hCamera IN is the camera handle. This value is returned by Initialize.vi and is passed between Pixelink VIs as a reference.


           CallbackInfo IN is a structure containing information required to set the callback and parameters to pass to the callback VI.



          Occurence is a LabVIEW occurence that the driver will trigger when the callback function is to be executed. Each occurence should be distinct. For clip capture with no clip termination VI (Path is blank and bGetClip is TRUE), the main application can wait on this occurence to ensure the video clip capture process has completed before formatting the video or aborting the application.


          hCamera is the camera handle of the camera to which the callback function applies. It is set by SetCallback to match hCamera IN. It is ignored if uOverLayUse is set to OVERLAY_FORMAT_IMAGE or OVERLAY_FORMAT_CLIP.


         uOverlayUse is an enumerated list which defines when the overlay callback should be called. Valid flags are:

  • OVERLAY_PREVIEW - The callback is applied to the data before it is displayed in the preview window;


  • OVERLAY_FORMAT_IMAGE - The callback is applied to the data before it is converted by FormatImage; 


  • OVERLAY_FORMAT_CLIP - The callback is applied to the data before it is converted by FormatClip; and 


  • OVERLAY_FRAME - The callback is applied to the raw data received by the driver.


uOverlayUse is ignored if bGetClip is TRUE.



       Path - the full path and file name of the callback VI. This VI should be based on the LVCallbackThreadTemplate.vi if bGetClip is FALSE or LVClipTerminationFuncThreadTemplate.vi if bGetClip is TRUE. If Path is blank, the associated overlay callback will be deleted. However, for a clip Termination callback, a blank Path is an indication that there is no separate callback VI. 


      bGetClip is a boolean flag which indicates if the callback is an overlay callback (FALSE - default) or a clip temrination callback (TRUE). If bGetClip is TRUE, then uOverLayUse is ignored.


      uNumberofFrameCaptured is a read-only field that indicates the actual number of frames captured. It is set by the clip termination VI. If there is no clip termination VI, it will be null.


      error (Get Clip) is the read-only error status of the clip capture routine. It is set by the clip termination VI. If Path is blank, the error (Get Clip) will not be set. Valid only if bGetClip is TRUE. 


      TerminationOccurence - for clip capture, this occurence is used by the clip termination function to signal the end of the clip capture and processing. The main application can wait on this occurence to ensure the clip capture and processing completes. Once the occurence is triggered by the clip termination VI, the main application can process the video clip or safely shutdown.  


      PDS Clip Path is the path to the intermediate Pixelink Data Stream (*.pds) file. Required if bGetClip is set to TRUE.


     AVI Clip Path is the path to the processed AVI file. It would be useful if the clip termination VI could process the PDS file into an AVI file. However, there is a unknown problem with the windows libraries that does not allow the FormatClip VI to be run outside the main thread. Consider AVI Clip Path to be a place holder only.  


           hCamera OUT has the same value as hCamera IN.


           CallbackInfo OUT has the same structure and value as CallbackInfo IN. 



Details


Before using SetCallback, the callback system should be initialized by calling  InitializeSystem.vi.  At the end of application, the callback system should be uninitialized by calling UninitializeSystem.vi.


Subsequent calls to SetCallback will replace the current callback VI with a new one.  Setting Path to blank will cause the associated overlay callback to be deleted (only if bGetClip is FALSE).


Particular attention should be paid to ensure that the callback VIs operate efficiently.  Otherwise, the frame rate may drop.


While an overlay frame callback is in operation, calls to GetNextFrame will return an error.


Occurrences set with uOverlayUse set to OVERLAY_FORMAT_IMAGE or OVERLAY_FORMAT_CLIP are global.  There is only one occurrence for any number of cameras as the FormatImage and FormatClip VIs are not camera specific.


Note: There is a bug in the SetCallback vi and API that will result in an error when OVERLAY_FORMAT_IMAGE or OVERLAY_FORMAT_CLIP are used. This error can be ignored. See the example program GetClipwithExternalThread.vi included with the Pixelink software.


The results of the clip capture can be queried with the GetCallbackInfo VI.


Note: See Error Handling for error input and output information and error codes.