Implementing video capture

Overview

Preparation

Before it starts video capture, your program needs to:

• 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

1. 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

1. Call capture_get_property_p() to get information about the capture device.
2. 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

1. Set up your video capture input that's appropriate for your board by calling capture_set_property_i() on each of the following properties:
   • CAPTURE_PROPERTY_DEVICE
   • CAPTURE_PROPERTY_SRC_INDEX
2. Call capture_set_property_i() for each capture property (of type integer) you need to set (e.g., CAPTURE_PROPERTY_DEVICE) to the video capture library.
3. Call capture_set_property_p() for each capture property (of type void pointer) you need to set (e.g., CAPTURE_PROPERTY_FRAME_FLAGS) to the video capture library.

Capture the video frames

1. 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.
2. Call capture_update() to start the video capture.
3. Create a loop to call capture_get_frame() to get the video frames from the hardware.
4. You can use the Screen function screen_post_window() to post the video frame for display in your screen window.
5. 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

1. 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.
2. Call capture_update() to stop video capture.
3. If you don't 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.
4. If your restart video capture (i.e., call capture_set_property_i() with the second argument set to >CAPTURE_ENABLE and the third argument set to 1 (one), and then call capture_update()) after stopping, then the Video capture framework reclaims all buffers. These buffers include even those that aren't released by the application (i.e., the application hasn't yet called capture_release_frame() for these buffers).