Allocate memory for video capture.
Synopsis:
#include <vcapture/capture.h>
int capture_create_buffers(capture_context_t context,
uint32_t property)
Arguments:
- context
- Pointer to the video capture context.
- property
- The video capture frame properties set by capture_set_property_i().
Library:
libcapture
Description:
The
capture_create_buffers() function reserves memory for video capture:
- If your hardware supports dynamic memory allocation, you can simply use your Screen API to create buffers for video
capture.
- If your hardware doesn't support dynamic memory allocation and requires you to use memory in a
preallocated location, you will need to use capture_create_buffers() to create
your buffers. For more information about buffers, see "Buffers".
Calls to
capture_create_buffers are synchronous. The function frees old buffers,
creates the new buffers, and returns immediately.
To free an existing buffer without creating a new one:
- Call capture_set_property_p() to set the buffer property to
NULL.
- Call capture_create_buffers().
Note:
- Call this function only when video capture is not in progress.
- If the hardware doesn't support application-allocated memory, calling this function will fail if
it is called with a buffer pointer property set to anything other than NULL.
- Systems with hardware that supports only driver-allocated memory can simply reject any attempt
to take a buffer out of driver-allocated state. On these systems, setting a buffer property to
NULL returns success, but has no effect on memory allocation.
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.
Example:
The code snippet below may be a useful reference on how to use
capture_create_buffers().
capture_set_property_i( context, CAPTURE_PROPERTY_DST_NBYTES, 320 * 240 * 4 );
capture_set_property_i( context, CAPTURE_PROPERTY_FRAME_NBUFFERS, 5 );
// create 5 frame buffers with 320x240x4 bytes each.
capture_create_buffers( context, CAPTURE_PROPERTY_FRAME_BUFFERS );
// get the buffers..
void **frame_buffers;
capture_get_property_p( context, CAPTURE_PROPERTY_FRAME_BUFFERS, (void**)&frame_buffers );
Returns:
- 0
- Success.
- -1
- An error occurred (errno is set).
Errors:
- EINVAL
- Invalid argument, or the argument is not a buffer property.
- ENOMEM
- Unable to allocate requested memory.
- ENOSYS
- The driver doesn't support buffer allocation.