capture_get_frame()

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

Get a frame from the video capture device

Synopsis:

#include <vcapture/capture.h>

int capture_get_frame(capture_context_t context,
                      uint64_t timeout,
                      uint32_t flags)

Arguments:

context

The pointer to the video capture context.

timeout

The wait before timing out. Set to any of:

The number of nanoseconds the function should wait for a frame before timing out. The function may return in less time than the period specified by this argument.
CAPTURE_TIMEOUT_INFINITE to wait indefinitely for a frame (never time out).
CAPTURE_TIMEOUT_NO_WAIT to return immediately, even if there is no frame.

flags

A bitmask to change the behavior of this function. Set to 0 or some combination of the following:

CAPTURE_FLAG_LATEST_FRAME to retrieve the latest frame, discarding all the other queued frames (the default behavior is to retrieve all queued frames in sequence).
CAPTURE_FLAG_FREE_BUFFER to retrieve a free buffer instead of a video frame. The capture_get_free_buffer() macro can be used to do the same thing.
CAPTURE_FLAG_ALLOW_UNBLOCK to indicate the call should return immediately when some device-specific event occurs, normally with errno set to EINTR.

Library:

libcapture

Description:

This function retrieves frames from the device. If more than one frame is in the queue, depending on the behavior specified by the flags argument, this function will either retrieve the first queued frame in sequence or retrieve only the latest frame, dropping the others.

The index returned by this function corresponds to the sequence number of the CAPTURE_PROPERTY_FRAME_SEQNO property, if this array is provided. The application can use this property and the index returned by this function to calculate the number of frames that have been dropped since the last call to capture_get_frame().

A thread blocked waiting for capture_get_frame() can be unblocked by setting CAPTURE_ENABLE to 0, followed by capture_update(), in a different thread. When this is done, or if capture_get_frame() is called with capture already disabled, the call will fail.

The buffer used to get a frame is locked for exclusive use by your application until capture_release_frame() releases it back to the capture driver. To avoid overwriting a frame before it has been displayed, your application should use at least three capture buffers to:

Call capture_get_frame() to get the index of the captured video frame.
Hand the frame buffer over for display by a call to a Screen function such as screen_post_window().
Call capture_get_frame() to get another frame.
When the frame in Step 1 is no longer being displayed, call capture_release_frame() to release the buffer for reuse by the capture driver.

Returns:

The index of the captured buffer (CAPTURE_PROPERTY_FRAME_BUFFERS) 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.

Page updated: March 05, 2025