Buffers

Buffer allocation

Video capture uses frame buffers to store the video capture frame data and metadata buffers to store video capture metadata. Video frame buffers can be either driver-allocated or application-allocated. Metadata buffers can only be application-allocated. Both frame data and metadata buffers can also be not allocated.

Driver-allocated buffers

Driver-allocated memory is managed by the driver: the driver allocates and frees this memory. The application can use buffers using this memory only when capture_get_property_p() defines them as valid.

To allocate driver-controlled memory for video frame buffers or metadata buffers, call capture_create_buffers(). Calling this function:

creates a video capture context
connects to video device
allocates buffer memory for this video capture context

Allocation of memory for driver-allocated buffer memory differs, based on several conditions:

Hardware doesn't support dynamic buffer allocation: If the hardware doesn't support dynamic buffer allocation, then the driver must always re-use previously allocated buffers (for example, memory that was set aside for these buffers at startup).; Buffers may be at a predetermined (hard-coded) RAM address. The driver's allocate function merely returns a pointer to this memory that capture_get_property_p() mapped into the application's address space.
Hardware supports dynamic buffer allocation: If the hardware supports dynamic buffer allocation, the driver can either allocate new buffers or reuse buffers it has used previously, provided that these buffers were driver allocated and are suitable.; Application-allocated buffers and buffers that are not allocated can't be reused as driver-allocated buffers. (See “Not allocated” below.)

Application-allocated buffers

Application-allocated memory is managed by the application: the application allocates and frees this memory. The driver can use the memory when the video capture API marks it as valid.

Application-allocated memory includes any buffer that isn't allocated by the video capture driver. For example, the application using video capture might acquire a buffer from another component, such as Screen. Because the driver didn't allocate the buffer, it is considered an application-allocated driver.

If your application allocates memory for your video capture buffers, then the driver won't allocate any memory (unless the hardware requires such buffers to exist even when they are not used by the application).

Note: If the hardware doesn't support application-allocated memory, then your application should use capture_create_buffers() to create buffers.

Not allocated

There are several case where a buffer can be not allocated:

The client application expressly sets up the video capture context so that the video capture library does not capture the video frames, but can still get frame metadata. The application can call capture_get_frame() to get a frame index, then look up the metadata for the frame. The video frame buffers must not be looked up or used. See “Unintentional freeing of driver-allocated buffers” below.
The special case that can occur when the driver or application has allocated a buffer, but the driver later turns off an expensive (resource-intensive) hardware feature that was supposed to use this buffer. When the feature is turned off, the buffer becomes not allocated.

Unintentional freeing of driver-allocated buffers

Setting a buffer pointer to NULL sets the buffer to not allocated, which:

causes the driver to cease using application-allocated buffer memory
may cause the driver to free previously driver-allocated memory (e.g., in the case where the buffer was dynamically allocated)

DANGER

Do not get a pointer to a buffer with capture_get_property_p(), then set the same pointer with capture_set_property_p().

If the buffer is driver-allocated, this sequence of calls will cause the driver to free the buffer referenced by the pointer, then assume that the application owns the now nonexistent buffer, with unpredictable results.

If the buffer in question was initially application-allocated, then no ill effects occur.