Properties applied to arrays

About arrays

Your application must set pointers to the arrays for which it needs to set properties, or for which it needs the capture library to get data from the video capture device. These pointers are stored in the capture library's context, which the application created by calling capture_create_context(). For instance, your client application can use the access modifiers defined by the CAPTURE_PROPERTY_FRAME_* properties to access and set or get the contents of the arrays in the current context.

Array resources such as CAPTURE_PROPERTY_FRAME_FLAGS and CAPTURE_PROPERTY_FRAME_SEQNO are not allocated by default. They need to be set, then passed to the video capture driver. Your application must:

1. Allocate the CAPTURE_PROPERTY_FRAME_* arrays with sufficient memory to hold the information they need. The number of elements in each array must be at least equal to the number of buffers you are using (set in CAPTURE_PROPERTY_FRAME_NBUFFERS).
2. Call capture_set_property_p() to pass a pointer to the array to the capture library.

The capture library stores this pointer to the array and updates the array whenever appropriate. Your applciation should read the data from the array to get updates whenever appropriate.

To instruct the capture library to stop collecting and providing data for a property, set the value of the property to NULL.

Example

The code snippet below is an example of how to use arrays:

nbuffers = 3;
// allocate a seqno buffer.
uint32_t seqno[nbuffers];

// tell the capture library to use this array and update it when
// frames are captured.
capture_set_property_p( ctx, CAPTURE_PROPERTY_FRAME_SEQNO, &seqno );
...
// get a captured frame
int idx = capture_get_frame( ctx, ... );

// the frame data and the buffer of the 'idx' frame is locked.
if( -1 != idx ) {
// it is safe to access the contents of the seqno[idx]
printf( "captured a frame, seqno = %u\n", seqno[idx] );
}
...
capture_release_frame( ctx, idx );
...
// no longer safe to access seqno[idx], since the data may
// no longer be valid.