Get a frame from the video capture device.
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.