PXL_RETURN_CODE PxLUpdateDescriptor ( HANDLE hCamera, HANDLE hDescriptor, U32 updateMode );
This function puts a specified descriptor in focus and sets its update state.
- hCamera is the camera handle. This value is returned by PxLInitialize.
- hDescriptor is the descriptor handle. This value is returned by PxLCreateDescriptor. Set to NULL to select all descriptors.
- updateMode indicates the update mode for this descriptor. Valid update modes are:
- PXL_UPDATE_CAMERA — Camera update mode.
- PXL_UPDATE_HOST — Host update mode.
These values are defined in the file PixeLINKTypes.h.
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.
A descriptor is applicable only to the camera for which it was created.
The specified descriptor is in focus that is, its settings can be changed using PxLSetFeature, or read using PxLGetFeature until one of the following occurs:
- a new descriptor is created using PxLCreateDescriptor,
- another descriptor is brought in focus using PxLUpdateDescriptor, or
- the descriptor is deleted using PxLRemoveDescriptor, in which case the focus reverts to the first descriptor created.
Bringing all descriptors into focus simultaneously
All descriptors may be brought in focus simultaneously by setting hDescriptor 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.
If updateMode is set to PXL_UPDATE_HOST, then the descriptor is updated on the host computer only. Changes will not be applied to the camera until PxLUpdateDescriptor is called for that descriptor with uUpdateMode set to PXL_UPDATE_CAMERA.
If updateMode is set to PXL_UPDATE_CAMERA, then the descriptor is updated on the host computer and changes are applied immediately to the camera.
If the descriptor update mode was originally set to PXL_UPDATE_HOST and updateMode is set to PXL_UPDATE_CAMERA, the descriptor is transferred to the camera and all the changes to settings are applied at once. This is done using the PixeLINK extension to IIDC.
Recommendation: Update the descriptor settings in PXL_UPDATE_HOST mode, then call PxLUpdateDescriptor with updateMode set to PXL_UPDATE_CAMERA to apply all changes to the camera settings at once. After this is done, return the descriptor to host mode by calling PxLUpdateDescriptor with updateMode set to PXL_UPDATE_HOST.