capture_get_frame()

Synopsis:

#include <vcapture/capture.h>
 
int capture_get_frame( capture_context_t context,
    uint64_t timeout, uint_32_t flags )

Arguments:

context

Pointer to the video capture context.

timeout

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 indefinitey for a frame (never time out).
CAPTURE_TIMEOUT_NO_WAIT to return immediately, even if there is no frame.

flags

Flag specifying how to handled queued frames. Set to one of:

0 (zero) to retrieve all queued frames in sequence.
CAPTURE_FLAG_LATEST_FRAME to retrieve the latest frame, discarding all the other queued frames.

Library:

libcapture

Description:

The function capture_get_frame() 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 all queued frames in sequence or retrieve only the latest frame, dropping the others. The function maintains the dropped frame counter.

The buffer used to get a frame is locked for exclusive use by the client app 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 has been displayed, call capture_release_frame() to release the buffer for reuse by the capture driver.

Returns:

≥0: Success: the index of the captured buffer.
-1: An error occurred, or the function has timed out (errno is set).

Errors:

ECANCELED: The capture was disabled. This error occurs when one thread calls capture_get_frame() while capturing is enabled, then another thread disables capturing before capture_get_frame() has finished.
EINVAL: Invalid argument.
EIO: Hardware input or output error.
ENOMEM: Capturing isn't possible because the client application has locked all buffers; it has not released any buffers for use by the capture library.
ETIMEDOUT: The request for a frame has timed out; no frame was captured.