Supported by ...

PL-A series cameras with the following limits:

  1. PL-A740 Series: A maximum of 14 descriptors is permitted.

  2. PL-A770 Series: A maximum of 10 descriptors is permitted.

  3. PL-A780 Series: A maximum of 10 descriptors is permitted.

PL-B series cameras only support one descriptor.

Note: For information on the API Frame Descriptor, which contains the settings for a captured frame, please see Frame Descriptor


A descriptor is a list of all the camera parameters. For cameras that support more than one descriptor, the descriptor feature is a way to control camera settings between frames without the need to communicate between the host computer and the camera for every acquisition.   This allows for rapid changes of camera parameters in a deterministic manner.

Descriptors also provide information about the current camera settings.  Most of the camera settings will be known to the host computer, but a few, especially the features that are set to Auto, may change without the host’s knowledge.  The descriptor structure is set up in two parts so that the settings that are capable of changing, are in the first part and all the known and static settings are in the second. The complete descriptor can be written or read from camera memory. It is important to check the version of the descriptor structure in order to use the correct structure.

The first part of the descriptor structure is always appended to each frame. For more information on the manner and format in which the data is appended to the frame, refer to Video Formats.

For camera control, descriptors can be created and stored in camera memory.  The number of descriptors available is camera dependent (see table below).  The camera will apply each descriptor in turn when capturing images.  When multiple descriptors are in use, the camera will encode a synchronization number in the first 16 bytes of image data returned from the camera.  The format of the synchronization code is shown in Video Formats. When in rolling shutter mode, if the changes affect the sensor, the camera will drop a frame and send the next following frame, effectively halving the frame rate. 

Note: The PL-B series of cameras only support one descriptor so no inter-frame changes are possible.  The descriptor is used solely to convey information about the current camera settings.

API Control

The API uses special functions to control descriptors.  See PxLCreateDescriptor, PxLUpdateDescriptor and PxLRemoveDescriptor for more information. Also see the article on Creating and Using Custom Descriptors.