Overview
A descriptor is a collection of camera feature properties that is applied to a frame. You receive descriptor information on every frame as they are returned to the host. By defining multiple descriptors, the camera properties can be changed automatically on a frame-by-frame basis for each frame in the video stream. A copy of each descriptor is kept on the host computer and can be updated on the host before sending changes to the camera.
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).
Note that a descriptor is applicable only to the camera for which it was created.
Camera and Host Update Modes
Because of the time required to communicate and enable property changes between the host computer and the camera, the PixeLINK API offers the ability to change a set of descriptor properties on the host computer first, then update the new set of properties on the camera in a single operation. This greatly reduces the risk of streaming frames that incorporate partially applied property changes.
When including descriptor controls in an interactive GUI, the host update mode can act as a “scratch pad” while the user changes the descriptor properties within the GUI window. The set of properties can then be updated on the camera in one operation with a single button click. This technique is used in the Descriptor tab of the PixeLINK Developers Application.
The update mode is set when the descriptor is created. It can be changed by updating the descriptor.
Host Mode: All function calls to change or read the feature properties are done to or from a cache on the host computer. They do not affect the camera settings until the update mode is changed to camera mode.
Camera Mode: This is the default update mode. All function calls to change or read the feature properties are done to or from the camera itself. If the update mode is changed from host mode to camera mode when updating the descriptor, the camera is updated with the descriptor’s property set cached on the host computer.
Creating a Descriptor
Create a new descriptor using PxLCreateDescriptor. For information on update modes, see section above.
Bringing a Descriptor in Focus
To read or change the settings of a descriptor, it must be in focus. At any given time, either a single descriptor can be in focus or all descriptors can be in focus simultaneously.
A descriptor can be put in focus in one of three ways:
By calling PxLUpdateDescriptor and specifying the descriptor to be brought in focus (this function is also used bring all descriptors in focus simultaneously);
By creating a new descriptor using PxLCreateDescriptor —This descriptor stays in focus until another descriptor is created using PxLCreateDescriptor or brought in focus using PxLUpdateDescriptor; or
By deleting the descriptor currently in focus—the focus reverts to the first descriptor created. Descriptors are deleted using PxLRemoveDescriptor.
Reading Descriptor Settings
Bring the descriptor in focus using PxLUpdateDescriptor. A newly created descriptor is automatically in focus until PxLUpdateDescriptor or PxLCreateDescriptor is called.
Call PxLGetFeature to read the settings.
Note: that if all descriptors are in focus at once (rather than just a single descriptor), calling PxLGetFeature will generate an error.
Changing Descriptor Settings
Bring the descriptor in focus using PxLUpdateDescriptor. To bring all descriptors in focus simultaneously, set the descriptor handle to NULL. A new descriptor is automatically in focus until PxLUpdateDescriptor or PxLCreateDescriptor is called.
Call PxLSetFeature to change the settings.
PxLUpdateDescriptor is also used to change the descriptor’s update mode.
Deleting a Descriptor
Call PxLRemoveDescriptor to delete a descriptor.
Focus: If the descriptor currently in focus is deleted, the focus reverts to the first descriptor created.
All descriptors deleted: If all custom descriptors are deleted (that is, no descriptors are defined), the descriptor stored with any image data subsequently viewed or captured is constructed from the camera feature properties in effect at the time.
Features Not Controlled By Descriptors
Not all features can be controlled by descriptors.
If the FEATURE_FLAG_DESC_SUPPORTED flag is set for a feature, the feature can be controlled by descriptors. Otherwise, the feature will have the same properties in all descriptors.
Some features cannot have the FEATURE_FLAG_DESC_SUPPORTED flag set. (See Feature Flags). These features include FEATURE_LOOKUP_TABLE and FEATURE_AUTO_ROI (See Features).
Examples
Example 1 – Creating Two Simple Descriptors
// Create two descriptors PxLCreateDescriptor ( hCamera, &hDesc1, PXL_UPDATE_CAMERA ); PxLCreateDescriptor ( hCamera, &hDesc2, PXL_UPDATE_CAMERA ); // Set the focus to Descriptor 1 PxLUpdateDescriptor ( hCamera, hDesc1, PXL_UPDATE_CAMERA ); // Change the integration time to xx ms PxLSetFeature ( hCamera, FEATURE_SHUTTER, … ); // Set the focus to Descriptor 2 PxLUpdateDescriptor ( hCamera, hDesc2, PXL_UPDATE_CAMERA ); // Change the integration time to yy ms PxLSetFeature ( hCamera, FEATURE_SHUTTER, … ); // Start the camera streaming PxLSetStreamState ( hCamera, START_STREAM );
The camera will now be streaming data, alternating between two frames, one at xx ms of integration time and the other at yy ms of integration time.
Example 2 – Using a Descriptor to Change Many Settings At Once
// Create one descriptor PxLCreateDescriptor ( hCamera, &hDesc, PXL_UPDATE_CAMERA ); // Set the focus for the descriptor and set it to Host update mode PxLUpdateDescriptor ( hCamera, hDesc, PXL_UPDATE_HOST ); // Set several features in the descriptor PxLSetFeature ( hCamera, FEATURE_SHUTTER, … ); PxLSetFeature ( hCamera, FEATURE_GAMMA, … ); PxLSetFeature ( hCamera, FEATURE_ROI, … ); … // Set the descriptor to Camera update mode PxLUpdateDescriptor ( hCamera, hDesc, PXL_UPDATE_CAMERA ); [All the changes to the feature settings are applied at once here.] … // Remove the descriptor PxLRemoveDescriptor ( hCamera, &hDesc);