capture_create_buffers()

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.