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.

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).

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)