Buffers

Updated: April 19, 2023

The driver or the client application can allocate memory for video frame data buffers. Only the client application can allocate metadata 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:
  1. creates a video capture context
  2. connects to video device
  3. 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:

Unintentional freeing of driver-allocated buffers

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

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.