capture_create_buffers()

Graphics and Screen4.0 (8.x)Video Capture Developer's GuideAPIProgramming

Allocate driver-controlled memory for video capture

Synopsis:

#include <vcapture/capture.h>
int capture_create_buffers(capture_context_t context,
                           uint32_t property)

Arguments:

context
The pointer to the video capture context.
property
The video capture frame properties by capture_set_property_i().

Library:

libcapture

Description:

This function allocates memory for video capture. Allocation of memory for driver allocated buffer memory differs based on whether your hardware supports dynamic buffer allocation. If your hardware doesn't support dynamically-allocated memory, calling capture_create_buffer() will fail if CAPTURE_PROPERTY_FRAME_BUFFERS is set to anything other than NULL. Refer to Buffers from the Video Capture Developer's Guide for more information.

Calls to capture_create_buffers() are synchronous. The function frees old buffers and creates the new buffers.

To free an existing buffer without creating a new one:
  1. Call capture_set_property_p() to set the buffer property CAPTURE_PROPERTY_FRAME_BUFFERS to NULL.
  2. Call capture_update().
The following code snippet can be 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 );
   ...

Call this function only when video capture is not in progress.

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 non-existent buffer, with unpredictable results.
  • If the buffer in question was initially application-allocated, then no ill effects occur.

Returns:

0 if successful; or -1 if an error occurred (errno is set; refer to errno.h for more details). The return value and the value that's observed for errno may vary as they are dependent on the implementation by the library that handles your hardware. For example, most drivers return an errno value of ENOTSUP if they do not support this function.

Page updated: