capture_get_frame()

Updated: April 19, 2023

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:

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().

It's safe to call this function even if capturing hasn't started (i.e., you haven't set the CAPTURE_ENABLE property and called capture_update()) yet. Your application must ensure that another thread will enable and disable capturing when required.

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:
  1. Call capture_get_frame() to get the index of the captured video frame.
  2. Hand the frame buffer over for display by a call to a Screen function such as screen_post_window().
  3. Call capture_get_frame() to get another frame.
  4. 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.