A descriptor is the set of feature properties that characterize a frame of image data by recording the camera features in effect at the time that frame was delivered from the camera.  Under the PixeLINK Camera API Version 4, each frame has a descriptor as metadata.  Descriptors are returned and passed by function calls, and custom descriptors may be constructed and applied automatically on a frame-by-frame basis to captured images (including clips) or to the preview window. 

If a custom descriptor is not applied to a frame, then the frame’s descriptor is constructed from the current camera properties at the time that the frame is delivered.  Contents of the descriptor are defined in the descriptor structure.

When a frame or video clip is captured using PxLGetNextFrame or PxLGetClip, the descriptor for each frame is stored with it.  When the frame or clip is converted to an end-user format using PxLFormatImage or PxLFormatClip, a custom descriptor can be applied to change the image’s width, height, decimation, or pixel format.  The end-user file does not contain a statement of the descriptor data.

For many applications, descriptors are informative only and do not play an active role, needing only to be passed from function to function.

Creating and Applying Custom Descriptors 

Some applications require specific, automatic changes to frame properties on a frame-by-frame basis for display or storage purposes.  This can be achieved by creating and applying custom descriptors to the video stream. 

Descriptors are applied, in order, on a frame-by-frame basis.  If more than one frame is being previewed or captured, the descriptors are applied 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).  Up to 16 descriptors can be managed at a time.