Video capture involves several tasks, including reserving memory, connecting to a capture device, and
releasing memory once the capture is finished.
Overview
To capture video, you need to:
- reserve memory for the video frame and metadata buffers
- connect to the capture device and set up the capture context
- validate the capture device's properties
- set the capture parameters
- start the video capture
- stop the capture
- destroy the buffers to release the memory they use
Note:
Note the following about video capture:
- The processes that use capture must be privileged processes.
- The video capture service does not handle displaying the captured video. For this, you need to
use another resource, such a Screen.
Video capture code that you can use for reference is available in "Sample video capture program".
Preparation
Before it starts video
capture, your program needs to:
- Set up your video capture input, using the combination of CAPTURE_PROPERTY_DEVICE and
CAPTURE_PROPERTY_SRC_INDEX appropriate for your board.
- Connect to a screen and create a window. See the Screen Graphics Subsystem Developer's Guide for more information.
- Use your Screen API to create buffers and get pointers to these
buffers, which you can pass to the video capture functions.
If your hardware doesn't support dynamic memory allocation and it requires you to use memory in a
preallocated location, you will need to use capture_create_buffers() to create your buffers. For more information
about this special case, see "Video capture buffers"
in this guide.
Video capture tasks
To capture video, you need to
perform the following tasks:
- Set up context
- Video capture requires a video capture context to which you can connect your input
device. To create a video capture context, call capture_create_context(). This function returns a
pointer to the capture context in the capture_context_t data structure, which you will
then pass to your other functions during the video capture session.
- Validate capture device properties
-
- Call capture_get_property_p() to get information about the
capture device.
- Call capture_is_property() to check if the driver supports
a property. Call this function once for each property you need to check.
- Set the capture parameters
-
- Call capture_set_property_i() for each capture property
you need to set, using the CAPTURE_PROPERTY_* constants to set the
device, brightness, destination buffers, etc.
- Call capture_set_property_p() to hand the pointer to your
properties array to the video capture library.
- Capture the video frames
-
- Make a final call to capture_set_property_i() with the second
argument set to CAPTURE_ENABLE and the third argument set to
1 (one) to instruct the driver to start video capture when
capture_update() is called.
- Call capture_update() to start the video capture.
- Create a loop to call capture_get_frame() to get the video frames from the
hardware.
- You can use the Screen function screen_post_window() to post the video frame
for display in your screen window.
- After you have posted a frame, mark the buffer that was used for the frame as available
for reuse by calling capture_release_frame().
- Stop and clean up
-
- When you want to stop video capture, call capture_set_property_i()
with the second argument set to CAPTURE_ENABLE and the third argument set
to 0 (zero) to disable video capture.
- Call capture_update() to stop video capture.
- If you will not restart video capture again immediately (the session is stopped rather
than paused), your application must call capture_destroy_context() to destroy all
contexts before it releases the capture buffers and exits.
Note:
- The capture_destroy_context() function is not
signal handler safe! For recommendations on how to use
capture_destroy_context() see the documentation for
this function.
- You can't count on the OS being able to adequately clean up after your
application exits, if the application does not destroy all the contexts it
created for video capture. Failure to destroy a context before exiting can
lead to memory corruption and unpredicatable system behavior.