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