{{{#!html

  1. Linux Video4Linux2 API (v4l2)
    1. v4l2-ctl utility
      1. video standards
      2. video inputs
      3. pixel formats, framesizes, and framerates
      4. capturing video frames
    2. v4l2 application code
    3. IMX6 Ventana mxc_v4l2_capture driver

Linux Video4Linux2 API (v4l2)

The Linux Video4Linux2 (v4l2) API is the kernel's video input and output interface.

v4l2-ctl utility

The v4l2-ctl userspace application can be used to query or configure a v4l2 device. For complete information, including output resolutions etc , use the following:

root@ventana:~# v4l2-ctl --device /dev/video3 --all # query all details about /dev/video3

See Also:

video standards

Analog video v4l2 capture devices will support one or more of the various analog video standards used throughout the world. For example the ADV7180 supports NTSC, PAL, and SECAM standards.

You can use the Video4Linux API to determine if an input is detected and what mode by using the v4l2-ctl --get-standard command which reports one of the following:

Example:

video inputs

Some capture devices have multiple video inputs. The v4l2-ctl application can be used to get or set the current input.

Examples:

pixel formats, framesizes, and framerates

You can use v4l2-ctl to show what pixel formats a video device supports and select a desired format. Note that v4l2 devices support one or more pixel formats, and various resolutions and framerates for each format. You must ask what resolutions are supported for a particular format, and what framerates are supported for a particular resolution/format.

Examples:

It is not uncommon for a v4l2 driver to not properly support the enumeration of various formats, resolutions, and framerates. If you find that a device is not returning anything useful for --list-formats --list-formats-ext --list-framesizes --list-framerates then you can try --all to get the default configuration of the device.

Examples:

capturing video frames

You can use v4l2-ctl to capture frames as well.

Examples:

Note that the convert tool from the ImageMagick package is useful for image format conversions as long as you know the specific details of the raw image.

Examples:

For an example v4l2 application for capturing frames see here

For capturing video we recommend using more full-featured applications such as GStreamer

v4l2 application code

If you are coding an application that uses the v4l2 API the best examples are the v4l2-util application. You can find its source at https://git.linuxtv.org/v4l-utils.git/tree/

The API documentation can be found at:

Examples:

As a rule of thumb it is best to configure all aspects of a device within your code to eliminate any dependence on the initial state of a video device and/or requiring configuring a device outside of your application with something like v4l2-ctl. For completeness set the following:

Be aware that the ioctl syscall can return a -1 result with errno = EINTR to indicate the syscall was interrupted in which case it should be tried again. Because of this you should consider providing a wrapper for ioctl such as:

static int xioctl(int fh, int request, void *arg)
{
        int r;

        do {
                r = ioctl(fh, request, arg);
        } while (-1 == r && EINTR == errno);

        return r;
}

IMX6 Ventana mxc_v4l2_capture driver

The Ventana product family based on the Freescale IMX6 System On Chip (SoC) has a Freescale provided capture driver (mxc_v4l2_capture) that is present in the Gateworks downstream vendor kernel used for the Yocto BSP.

This capture device driver implements two video inputs which represent different pipelines in the SoC:

If capturing frames be sure to skip the first frame as the CSI has not fully synchronized on its capture input.

To demonstrate a capture of a raw frame you can use the v4l2_ctl application:

# configure input 1 for CSI -> MEM (raw image capture)
v4l2-ctl --device /dev/video0 --set-input=1
# configure format
v4l2-ctl --device /dev/video0 --set-fmt-video=width=1920,height=1080,pixelformat=UYVY
# capture 2nd frame
v4l2-ctl --device /dev/video0 --stream-mmap --stream-skip=1 --stream-to=frame.raw --stream-count=1
# Use ImageMagick to convert it from raw 16-bit UYVY to PNG
convert -size 1920x1080 -depth 16 uyvy:frame.raw frame.png

Notes:

Code Example:

Example usage: