Syntax


 

PXL_RETURN_CODE PxLCreateDescriptor ( 

HANDLE  hCamera,

HANDLE* pDescriptorHandle,

U32     updateMode );

 

Description


This function creates a descriptor on the host computer or on the camera, depending on the update mode specified.  This descriptor is created using the current settings on the host.

  • hCamera is the camera handle.  This value is returned by PxLInitialize.
  • pDescriptorHandle is a pointer to a variable receiving the descriptor handle.
  • updateMode is the initial update mode of the descriptor being created.  Valid update flags are:
     
    • PXL_UPDATE_CAMERA — Camera update mode.
    • PXL_UPDATE_HOST — Host update mode.


These values are defined in the file PixeLINKTypes.h.  See below for more information.


Default


PXL_UPDATE_CAMERA


Comments, Restrictions and Limitations


For more information about descriptors, including definitions of the terms used in this function description and examples, go to creating and using descriptors.


Descriptors are applied to the video stream in the order in which they were created.  That is, the first descriptor created is applied to the first frame returned after the start of the video stream, the second descriptor created is applied to the second frame, and so on.  If the number of frames exceeds the number of descriptors, the descriptors are applied to the remaining frames in a cyclic fashion (that is, after the last descriptor is applied, the first descriptor is applied to the next frame, then the second descriptor is applied to the following frame, and so on). 


A descriptor is applicable only to the camera for which it was created.


Focus


The newly created descriptor is in focus (that is, its settings can be changed using PxLSetFeature, or read using PxLGetFeature, until one of the following occurs:

All descriptors can be brought in focus simultaneously by calling PxLUpdateDescriptor with the descriptor handle set to NULL.  Otherwise, only one descriptor may be in focus at a time.  Note that if all descriptors are in focus at once (rather than just a single descriptor), calling PxLGetFeature will generate an error.


Update Mode


If updateMode is set to PXL_UPDATE_HOST, then the descriptor is created (cached) on the host computer only.  It will not be applied to the camera until PxLUpdateDescriptor is called with the update mode set to PXL_UPDATE_CAMERA.


If updateMode is set to PXL_UPDATE_CAMERA, then the descriptor is cached on the host computer and applied immediately to the camera. 


See PxLUpdateDescriptor for a more detailed description of the update modes.