1.1. Opening and Closing Devices

1.1.1. Device Naming

V4L2 drivers are implemented as kernel modules, loadedmanually by the system administrator or automatically when a device isfirst opened. The driver modules plug into the "videodev" kernelmodule. It provides helper functions and a common applicationinterface specified in this document.

Each driver thus loaded registers one or more device nodeswith major number 81 and a minor number between 0 and 255. Assigningminor numbers to V4L2 devices is entirely up to the system administrator,this is primarily intended to solve conflicts between devices.[1] The module options to select minor numbers are namedafter the device special file with a "_nr" suffix. For example "video_nr"for/dev/video video capture devices. The number isan offset to the base minor number associated with the device type.[2] When the driver supports multiple devices of the sametype more than one minor number can be assigned, separated by commas:

> insmod mydriver.o video_nr=0,1 radio_nr=0,1

In /etc/modules.conf this may bewritten as:

alias char-major-81-0 mydriver
alias char-major-81-1 mydriver
alias char-major-81-64 mydriver              

options mydriver video_nr=0,1 radio_nr=0,1   

When an application attempts to open a devicespecial file with major number 81 and minor number 0, 1, or 64, load"mydriver" (and the "videodev" module it depends upon).

Register the first two video capture devices withminor number 0 and 1 (base number is 0), the first two radio devicewith minor number 64 and 65 (base 64).

When no minor number is given as moduleoption the driver supplies a default. Chapter 4recommends the base minor numbers to be used for the various devicetypes. Obviously minor numbers must be unique. When the number isalready in use the offending device will not beregistered.

By convention system administrators create variouscharacter device special files with these major and minor numbers inthe/dev directory. The names recomended for thedifferent V4L2 device types are listed inChapter 4.

The creation of character special files (withmknod) is a privileged operation anddevices cannot be opened by major and minor number. That meansapplications cannotreliable scan for loaded orinstalled drivers. The user must enter a device name, or theapplication can try the conventional device names.

Under the device filesystem (devfs) the minor numberoptions are ignored. V4L2 drivers (or by proxy the "videodev" module)automatically create the required device files in the/dev/v4l directory using the conventional devicenames above.

1.2. Querying Capabilities

Because V4L2 covers a wide variety of devices not allaspects of the API are equally applicable to all types of devices.Furthermore devices of the same type have different capabilities andthis specification permits the omission of a few complicated and lessimportant parts of the API.

The VIDIOC_QUERYCAP ioctl is available to check if the kerneldevice is compatible with this specification, and to query thefunctions andI/Omethods supported by the device. Other features can be queriedby calling the respective ioctl, for exampleVIDIOC_ENUMINPUTto learn about the number, types and names of video connectors on thedevice. Although abstraction is a major objective of this API, theioctl also allows driver specific applications to reliable identifythe driver.

All V4L2 drivers must supportVIDIOC_QUERYCAP. Applications should always callthis ioctl after opening the device.

1.3. Application Priority

When multiple applications share a device it may bedesirable to assign them different priorities. Contrary to thetraditional "rm -rf /" school of thought a video recording applicationcould for example block other applications from changing videocontrols or switching the current TV channel. Another objective is topermit low priority applications working in background, which can bepreempted by user controlled applications and automatically regaincontrol of the device at a later time.

Since these features cannot be implemented entirely in userspace V4L2 defines theVIDIOC_G_PRIORITY andVIDIOC_S_PRIORITYioctls to request and query the access priority associate with a filedescriptor. Opening a device assigns a medium priority, compatiblewith earlier versions of V4L2 and drivers not supporting these ioctls.Applications requiring a different priority will usually callVIDIOC_S_PRIORITY after verifying the device withtheVIDIOC_QUERYCAP ioctl.

Ioctls changing driver properties, such as VIDIOC_S_INPUT,return an EBUSY error code after another application obtained higher priority.An event mechanism to notify applications about asynchronous propertychanges has been proposed but not added yet.

1.4. Video Inputs and Outputs

Video inputs and outputs are physical connectors of adevice. These can be for example RF connectors (antenna/cable), CVBSa.k.a. Composite Video, S-Video or RGB connectors. Only video and VBIcapture devices have inputs, output devices have outputs, at least oneeach. Radio devices have no video inputs or outputs.

To learn about the number and attributes of theavailable inputs and outputs applications can enumerate them with theVIDIOC_ENUMINPUT andVIDIOC_ENUMOUTPUT ioctl, respectively. Thestruct v4l2_input returned by theVIDIOC_ENUMINPUTioctl also contains signal status information applicable when thecurrent video input is queried.

The VIDIOC_G_INPUT and VIDIOC_G_OUTPUT ioctl return theindex of the current video input or output. To select a differentinput or output applications call theVIDIOC_S_INPUT andVIDIOC_S_OUTPUT ioctl. Drivers must implement all the input ioctlswhen the device has one or more inputs, all the output ioctls when thedevice has one or more outputs.

struct v4l2_input input;
int index;

if (-1 == ioctl (fd, VIDIOC_G_INPUT, &index)) {
        perror ("VIDIOC_G_INPUT");
        exit (EXIT_FAILURE);
}

memset (&input, 0, sizeof (input));
input.index = index;

if (-1 == ioctl (fd, VIDIOC_ENUMINPUT, &input)) {
        perror ("VIDIOC_ENUMINPUT");
        exit (EXIT_FAILURE);
}

printf ("Current input: %s\n", input.name);
      

int index;

index = 0;

if (-1 == ioctl (fd, VIDIOC_S_INPUT, &index)) {
        perror ("VIDIOC_S_INPUT");
        exit (EXIT_FAILURE);
}
      

1.5. Audio Inputs and Outputs

Audio inputs and outputs are physical connectors of adevice. Video capture devices have inputs, output devices haveoutputs, zero or more each. Radio devices have no audio inputs oroutputs. They have exactly one tuner which in factis an audio source, but this API associatestuners with video inputs or outputs only, and radio devices havenone of these.[5] A connector on a TV card to loop back the receivedaudio signal to a sound card is not considered an audio output.

Audio and video inputs and outputs are associated. Selectinga video source also selects an audio source. This is most evident whenthe video and audio source is a tuner. Further audio connectors cancombine with more than one video input or output. Assumed twocomposite video inputs and two audio inputs exist, there may be up tofour valid combinations. The relation of video and audio connectorsis defined in theaudioset field of therespective struct v4l2_input or struct v4l2_output, where each bit representsthe index number, starting at zero, of one audio input or output.

To learn about the number and attributes of theavailable inputs and outputs applications can enumerate them with theVIDIOC_ENUMAUDIO andVIDIOC_ENUMAUDOUT ioctl, respectively. Thestruct v4l2_audio returned by theVIDIOC_ENUMAUDIO ioctlalso contains signal status information applicable when the currentaudio input is queried.

The VIDIOC_G_AUDIO and VIDIOC_G_AUDOUT ioctl reportthe current audio input and output, respectively. Note that, unlikeVIDIOC_G_INPUT andVIDIOC_G_OUTPUT these ioctls return a structureasVIDIOC_ENUMAUDIO andVIDIOC_ENUMAUDOUT do, not just an index.

To select an audio input and change its propertiesapplications call the VIDIOC_S_AUDIO ioctl. To select an audiooutput (which presently has no changeable properties) applicationscall theVIDIOC_S_AUDOUT ioctl.

Drivers must implement all input ioctls when the devicehas one or more inputs, all output ioctls when the device has oneor more outputs. When the device has any audio inputs or outputs thedriver must set theV4L2_CAP_AUDIO flag in thestruct v4l2_capability returned by theVIDIOC_QUERYCAP ioctl.

struct v4l2_audio audio;

memset (&audio, 0, sizeof (audio));

if (-1 == ioctl (fd, VIDIOC_G_AUDIO, &audio)) {
        perror ("VIDIOC_G_AUDIO");
        exit (EXIT_FAILURE);
}

printf ("Current input: %s\n", audio.name);
      

struct v4l2_audio audio;

memset (&audio, 0, sizeof (audio)); /* clear audio.mode, audio.reserved */

audio.index = 0;

if (-1 == ioctl (fd, VIDIOC_S_AUDIO, &audio)) {
        perror ("VIDIOC_S_AUDIO");
        exit (EXIT_FAILURE);
}
      

1.6. Tuners and Modulators

1.7. Video Standards

Video devices typically support one or more different videostandards or variations of standards. Each video input and output maysupport another set of standards. This set is reported by thestd field of struct v4l2_input andstruct v4l2_output returned by theVIDIOC_ENUMINPUT andVIDIOC_ENUMOUTPUT ioctl, respectively.

V4L2 defines one bit for each analog video standardcurrently in use worldwide, and sets aside bits for driver definedstandards, e. g. hybrid standards to watch NTSC video tapes on PAL TVsand vice versa. Applications can use the predefined bits to select aparticular standard, although presenting the user a menu of supportedstandards is preferred. To enumerate and query the attributes of thesupported standards applications use theVIDIOC_ENUMSTD ioctl.

Many of the defined standards are actually just variationsof a few major standards. The hardware may in fact not distinguishbetween them, or do so internal and switch automatically. Thereforeenumerated standards also contain sets of one or more standardbits.

Assume a hypothetic tuner capable of demodulating B/PAL,G/PAL and I/PAL signals. The first enumerated standard is a set of Band G/PAL, switched automatically depending on the selected radiofrequency in UHF or VHF band. Enumeration gives a "PAL-B/G" or "PAL-I"choice. Similar a Composite input may collapse standards, enumerating"PAL-B/G/H/I", "NTSC-M" and "SECAM-D/K".[6]

To query and select the standard used by the current videoinput or output applications call theVIDIOC_G_STD andVIDIOC_S_STD ioctl, respectively. The receivedstandard can be sensed with theVIDIOC_QUERYSTD ioctl. Note parameter of all these ioctls is a pointer to av4l2_std_id type (a standard set),not an index into the standard enumeration.[7] Drivers must implement all video standard ioctlswhen the device has one or more video inputs or outputs.

Special rules apply to USB cameras where the notion of videostandards makes little sense. More generally any capture device,output devices accordingly, which is

• incapable of capturing fields or frames at the nominalrate of the video standard, or

• where timestamps referto the instant the field or frame was received by the driver, not thecapture time, or

• where sequence numbersrefer to the frames received by the driver, not the capturedframes.

v4l2_std_id std_id;
struct v4l2_standard standard;

if (-1 == ioctl (fd, VIDIOC_G_STD, &std_id)) {
        /* Note when VIDIOC_ENUMSTD always returns EINVAL this
           is no video device or it falls under the USB exception,
           and VIDIOC_G_STD returning EINVAL is no error. */

        perror ("VIDIOC_G_STD");
        exit (EXIT_FAILURE);
}

memset (&standard, 0, sizeof (standard));
standard.index = 0;

while (0 == ioctl (fd, VIDIOC_ENUMSTD, &standard)) {
        if (standard.id & std_id) {
               printf ("Current video standard: %s\n", standard.name);
               exit (EXIT_SUCCESS);
        }

        standard.index++;
}

/* EINVAL indicates the end of the enumeration, which cannot be
   empty unless this device falls under the USB exception. */

if (errno == EINVAL || standard.index == 0) {
        perror ("VIDIOC_ENUMSTD");
        exit (EXIT_FAILURE);
}
      

struct v4l2_input input;
struct v4l2_standard standard;

memset (&input, 0, sizeof (input));

if (-1 == ioctl (fd, VIDIOC_G_INPUT, &input.index)) {
        perror ("VIDIOC_G_INPUT");
        exit (EXIT_FAILURE);
}

if (-1 == ioctl (fd, VIDIOC_ENUMINPUT, &input)) {
        perror ("VIDIOC_ENUM_INPUT");
        exit (EXIT_FAILURE);
}

printf ("Current input %s supports:\n", input.name);

memset (&standard, 0, sizeof (standard));
standard.index = 0;

while (0 == ioctl (fd, VIDIOC_ENUMSTD, &standard)) {
        if (standard.id & input.std)
                printf ("%s\n", standard.name);

        standard.index++;
}

/* EINVAL indicates the end of the enumeration, which cannot be
   empty unless this device falls under the USB exception. */

if (errno != EINVAL || standard.index == 0) {
        perror ("VIDIOC_ENUMSTD");
        exit (EXIT_FAILURE);
}
      

struct v4l2_input input;
v4l2_std_id std_id;

memset (&input, 0, sizeof (input));

if (-1 == ioctl (fd, VIDIOC_G_INPUT, &input.index)) {
        perror ("VIDIOC_G_INPUT");
        exit (EXIT_FAILURE);
}

if (-1 == ioctl (fd, VIDIOC_ENUMINPUT, &input)) {
        perror ("VIDIOC_ENUM_INPUT");
        exit (EXIT_FAILURE);
}

if (0 == (input.std & V4L2_STD_PAL_BG)) {
        fprintf (stderr, "Oops. B/G PAL is not supported.\n");
        exit (EXIT_FAILURE);
}

/* Note this is also supposed to work when only B
   or G/PAL is supported. */

std_id = V4L2_STD_PAL_BG;

if (-1 == ioctl (fd, VIDIOC_S_STD, &std_id)) {
        perror ("VIDIOC_S_STD");
        exit (EXIT_FAILURE);
}
      

1.8. User Controls

Devices typically have a number of user-settable controlssuch as brightness, saturation and so on, which would be presented tothe user on a graphical user interface. But, different deviceswill have different controls available, and furthermore, the range ofpossible values, and the default value will vary from device todevice. The control ioctls provide the information and a mechanism tocreate a nice user interface for these controls that will workcorrectly with any device.

All controls are accessed using an ID value. V4L2 definesseveral IDs for specific purposes. Drivers can also implement theirown custom controls usingV4L2_CID_PRIVATE_BASEand higher values. The pre-defined control IDs have the prefixV4L2_CID_, and are listed inTable 1-1. The ID is used when querying the attributes ofa control, and when getting or setting the current value.

Generally applications should present controls to the userwithout assumptions about their purpose. Each control comes with aname string the user is supposed to understand. When the purpose isnon-intuitive the driver writer should provide a user manual, a userinterface plug-in or a driver specific panel application. PredefinedIDs were introduced to change a few controls programmatically, forexample to mute a device during a channel switch.

Drivers may enumerate different controls after switchingthe current video input or output, tuner or modulator, or audio inputor output. Different in the sense of other bounds, another default andcurrent value, step size or other menu items. A control with a certaincustom ID can also change name andtype.[9] Control values are stored globally, they do notchange when switching except to stay within the reported bounds. Theyalso do not change e. g. when the device is opened or closed, when thetuner radio frequency is changed or generally never withoutapplication request. Since V4L2 specifies no event mechanism, panelapplications intended to cooperate with other panel applications (bethey built into a larger application, as a TV viewer) may need toregularly poll control values to update their userinterface.[10]

Applications can enumerate the available controls with theVIDIOC_QUERYCTRL andVIDIOC_QUERYMENU ioctls, get and set acontrol value with theVIDIOC_G_CTRL andVIDIOC_S_CTRL ioctls.Drivers must implementVIDIOC_QUERYCTRL,VIDIOC_G_CTRL andVIDIOC_S_CTRL when the device has one or morecontrols,VIDIOC_QUERYMENU when it has one ormore menu type controls.

struct v4l2_queryctrl queryctrl;
struct v4l2_querymenu querymenu;

static void
enumerate_menu (void)
{
        printf ("  Menu items:\n");

        memset (&querymenu, 0, sizeof (querymenu));
        querymenu.id = queryctrl.id;

        for (querymenu.index = queryctrl.minimum;
             querymenu.index <= queryctrl.maximum;
              querymenu.index++) {
                if (0 == ioctl (fd, VIDIOC_QUERYMENU, &querymenu)) {
                        printf ("  %s\n", querymenu.name);
                } else {
                        perror ("VIDIOC_QUERYMENU");
                        exit (EXIT_FAILURE);
                }
        }
}

memset (&queryctrl, 0, sizeof (queryctrl));

for (queryctrl.id = V4L2_CID_BASE;
     queryctrl.id < V4L2_CID_LASTP1;
     queryctrl.id++) {
        if (0 == ioctl (fd, VIDIOC_QUERYCTRL, &queryctrl)) {
                if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
                        continue;

                printf ("Control %s\n", queryctrl.name);

                if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
                        enumerate_menu ();
        } else {
                if (errno == EINVAL)
                        continue;

                perror ("VIDIOC_QUERYCTRL");
                exit (EXIT_FAILURE);
        }
}

for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
     queryctrl.id++) {
        if (0 == ioctl (fd, VIDIOC_QUERYCTRL, &queryctrl)) {
                if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
                        continue;

                printf ("Control %s\n", queryctrl.name);

                if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
                        enumerate_menu ();
        } else {
                if (errno == EINVAL)
                        break;

                perror ("VIDIOC_QUERYCTRL");
                exit (EXIT_FAILURE);
        }
}

struct v4l2_queryctrl queryctrl;
struct v4l2_control control;

memset (&queryctrl, 0, sizeof (queryctrl));
queryctrl.id = V4L2_CID_BRIGHTNESS;

if (-1 == ioctl (fd, VIDIOC_QUERYCTRL, &queryctrl)) {
        if (errno != EINVAL) {
                perror ("VIDIOC_QUERYCTRL");
                exit (EXIT_FAILURE);
        } else {
                printf ("V4L2_CID_BRIGHTNESS is not supported\n");
        }
} else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) {
        printf ("V4L2_CID_BRIGHTNESS is not supported\n");
} else {
        memset (&control, 0, sizeof (control));
        control.id = V4L2_CID_BRIGHTNESS;
        control.value = queryctrl.default_value;

        if (-1 == ioctl (fd, VIDIOC_S_CTRL, &control)) {
                perror ("VIDIOC_S_CTRL");
                exit (EXIT_FAILURE);
        }
}

memset (&control, 0, sizeof (control));
control.id = V4L2_CID_CONTRAST;

if (0 == ioctl (fd, VIDIOC_G_CTRL, &control)) {
        control.value += 1;

        /* The driver may clamp the value or return ERANGE, ignored here */

        if (-1 == ioctl (fd, VIDIOC_S_CTRL, &control)
            && errno != ERANGE) {
                perror ("VIDIOC_S_CTRL");
                exit (EXIT_FAILURE);
        }
/* Ignore if V4L2_CID_CONTRAST is unsupported */
} else if (errno != EINVAL) {
        perror ("VIDIOC_G_CTRL");
        exit (EXIT_FAILURE);
}

control.id = V4L2_CID_AUDIO_MUTE;
control.value = TRUE; /* silence */

/* Errors ignored */
ioctl (fd, VIDIOC_S_CTRL, &control);

1.9. Extended Controls

struct v4l2_queryctrl qctrl;

qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
while (0 == ioctl (fd, VIDIOC_QUERYCTRL, &qctrl)) {
        /* ... */
        qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
}

qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL;
while (0 == ioctl (fd, VIDIOC_QUERYCTRL, &qctrl)) {
        if (V4L2_CTRL_ID2CLASS (qctrl.id) != V4L2_CTRL_CLASS_MPEG)
                break;
                /* ... */
                qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
        }

1.10. Data Formats

1.11. Image Cropping, Insertion and Scaling

Some video capture devices can sample a subsection of thepicture and shrink or enlarge it to an image of arbitrary size. Wecall these abilities cropping and scaling. Some video output devicescan scale an image up or down and insert it at an arbitrary scan lineand horizontal offset into a video signal.

Applications can use the following API to select an area inthe video signal, query the default area and the hardware limits.Despite their name, theVIDIOC_CROPCAP,VIDIOC_G_CROPandVIDIOC_S_CROP ioctls apply to input as well as outputdevices.

Scaling requires a source and a target. On a video captureor overlay device the source is the video signal, and the croppingioctls determine the area actually sampled. The target are imagesread by the application or overlaid onto the graphics screen. Theirsize (and position for an overlay) is negotiated with theVIDIOC_G_FMT andVIDIOC_S_FMT ioctls.

On a video output device the source are the images passed inby the application, and their size is again negotiated with theVIDIOC_G/S_FMT ioctls, or may be encoded in acompressed video stream. The target is the video signal, and thecropping ioctls determine the area where the images areinserted.

Source and target rectangles are defined even if the devicedoes not support scaling or theVIDIOC_G/S_CROPioctls. Their size (and position where applicable) will be fixed inthis case.All capture and output device must support theVIDIOC_CROPCAP ioctl such that applications candetermine if scaling takes place.

struct v4l2_cropcap cropcap;
struct v4l2_crop crop;

memset (&cropcap, 0, sizeof (cropcap));
cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;

if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) {
        perror ("VIDIOC_CROPCAP");
        exit (EXIT_FAILURE);
}

memset (&crop, 0, sizeof (crop));
crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
crop.c = cropcap.defrect; 

/* Ignore if cropping is not supported (EINVAL). */

if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
    && errno != EINVAL) {
        perror ("VIDIOC_S_CROP");
        exit (EXIT_FAILURE);
}
      

struct v4l2_cropcap cropcap;
struct v4l2_format format;

reset_cropping_parameters ();

/* Scale down to 1/4 size of full picture. */

memset (&format, 0, sizeof (format)); /* defaults */

format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;

format.fmt.pix.width = cropcap.defrect.width >> 1;
format.fmt.pix.height = cropcap.defrect.height >> 1;
format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;

if (-1 == ioctl (fd, VIDIOC_S_FMT, &format)) {
        perror ("VIDIOC_S_FORMAT");
        exit (EXIT_FAILURE);
}

/* We could check the actual image size now, the actual scaling factor
   or if the driver can scale at all. */
        

struct v4l2_cropcap cropcap;
struct v4l2_crop crop;

memset (&cropcap, 0, sizeof (cropcap));
cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;

if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) {
        perror ("VIDIOC_CROPCAP");
        exit (EXIT_FAILURE);
}

memset (&crop, 0, sizeof (crop));

crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
crop.c = cropcap.defrect;

/* Scale the width and height to 50 % of their original size
   and center the output. */

crop.c.width /= 2;
crop.c.height /= 2;
crop.c.left += crop.c.width / 2;
crop.c.top += crop.c.height / 2;

/* Ignore if cropping is not supported (EINVAL). */

if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
    && errno != EINVAL) {
        perror ("VIDIOC_S_CROP");
        exit (EXIT_FAILURE);
}

struct v4l2_cropcap cropcap;
struct v4l2_crop crop;
struct v4l2_format format;
double hscale, vscale;
double aspect;
int dwidth, dheight;

memset (&cropcap, 0, sizeof (cropcap));
cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;

if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) {
        perror ("VIDIOC_CROPCAP");
        exit (EXIT_FAILURE);
}

memset (&crop, 0, sizeof (crop));
crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;

if (-1 == ioctl (fd, VIDIOC_G_CROP, &crop)) {
        if (errno != EINVAL) {
                perror ("VIDIOC_G_CROP");
                exit (EXIT_FAILURE);
        }

        /* Cropping not supported. */
        crop.c = cropcap.defrect;
}

memset (&format, 0, sizeof (format));
format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;

if (-1 == ioctl (fd, VIDIOC_G_FMT, &format)) {
        perror ("VIDIOC_G_FMT");
        exit (EXIT_FAILURE);
}

/* The scaling applied by the driver. */

hscale = format.fmt.pix.width / (double) crop.c.width;
vscale = format.fmt.pix.height / (double) crop.c.height;

aspect = cropcap.pixelaspect.numerator /
         (double) cropcap.pixelaspect.denominator;
aspect = aspect * hscale / vscale;

/* Devices following ITU-R BT.601 do not capture
   square pixels. For playback on a computer monitor
   we should scale the images to this size. */

dwidth = format.fmt.pix.width / aspect;
dheight = format.fmt.pix.height;
        

1.12. Streaming Parameters

Streaming parameters are intended to optimize the videocapture process as well as I/O. Presently applications can request ahigh quality capture mode with theVIDIOC_S_PARM ioctl.

The current video standard determines a nominal number offrames per second. If less than this number of frames is to becaptured or output, applications can request frame skipping orduplicating on the driver side. This is especially useful when usingtheread() orwrite(), which are not augmented by timestampsor sequence counters, and to avoid unneccessary data copying.

Finally these ioctls can be used to determine the number ofbuffers used internally by a driver in read/write mode. Forimplications see the section discussing theread()function.

To get and set the streaming parameters applications callthe VIDIOC_G_PARM and VIDIOC_S_PARM ioctl, respectively. They takea pointer to a struct v4l2_streamparm, which contains a union holdingseparate parameters for input and output devices.

These ioctls are optional, drivers need not implementthem. If so, they return theEINVAL error code.

2.1. Standard Image Formats

In order to exchange images between drivers andapplications, it is necessary to have standard image data formatswhich both sides will interpret the same way. V4L2 includes severalsuch formats, and this section is intended to be an unambiguousspecification of the standard image data formats in V4L2.

V4L2 drivers are not limited to these formats, however.Driver-specific formats are possible. In that case the application maydepend on a codec to convert images to one of the standard formatswhen needed. But the data can still be stored and retrieved in theproprietary format. For example, a device may support a proprietarycompressed format. Applications can still capture and save the data inthe compressed format, saving much disk space, and later use a codecto convert the images to the X Windows screen format when the video isto be displayed.

Even so, ultimately, some standard formats are needed, sothe V4L2 specification would not be complete without well-definedstandard formats.

The V4L2 standard formats are mainly uncompressed formats. Thepixels are always arranged in memory from left to right, and from topto bottom. The first byte of data in the image buffer is always forthe leftmost pixel of the topmost row. Following that is the pixelimmediately to its right, and so on until the end of the top row ofpixels. Following the rightmost pixel of the row there may be zero ormore bytes of padding to guarantee that each row of pixel data has acertain alignment. Following the pad bytes, if any, is data for theleftmost pixel of the second row from the top, and so on. The last rowhas just as many pad bytes after it as the other rows.

In V4L2 each format has an identifier which looks likePIX_FMT_XXX, defined in thevideodev.h header file. These identifiersrepresentfour character codeswhich are also listed below, however they are not the same as thoseused in the Windows world.

2.2. Colorspaces

[intro]

int ER, EG, EB;         /* gamma corrected RGB input [0;255] */
int Y1, Cb, Cr;         /* output [0;255] */

double r, g, b;         /* temporaries */
double y1, pb, pr;

int
clamp (double x)
{
        int r = x;      /* round to nearest */

        if (r < 0)         return 0;
        else if (r > 255)  return 255;
        else               return r;
}

r = ER / 255.0;
g = EG / 255.0;
b = EB / 255.0;

y1  =  0.299  * r + 0.587 * g + 0.114  * b;
pb  = -0.169  * r - 0.331 * g + 0.5    * b;
pr  =  0.5    * r - 0.419 * g - 0.081  * b;

Y1 = clamp (219 * y1 + 16);
Cb = clamp (224 * pb + 128);
Cr = clamp (224 * pr + 128);

/* or shorter */

y1 = 0.299 * ER + 0.587 * EG + 0.114 * EB;

Y1 = clamp ( (219 / 255.0)                    *       y1  + 16);
Cb = clamp (((224 / 255.0) / (2 - 2 * 0.114)) * (EB - y1) + 128);
Cr = clamp (((224 / 255.0) / (2 - 2 * 0.299)) * (ER - y1) + 128);
      

int Y1, Cb, Cr;         /* gamma pre-corrected input [0;255] */
int ER, EG, EB;         /* output [0;255] */

double r, g, b;         /* temporaries */
double y1, pb, pr;

int
clamp (double x)
{
        int r = x;      /* round to nearest */

        if (r < 0)         return 0;
        else if (r > 255)  return 255;
        else               return r;
}

y1 = (255 / 219.0) * (Y1 - 16);
pb = (255 / 224.0) * (Cb - 128);
pr = (255 / 224.0) * (Cr - 128);

r = 1.0 * y1 + 0     * pb + 1.402 * pr;
g = 1.0 * y1 - 0.344 * pb - 0.714 * pr;
b = 1.0 * y1 + 1.772 * pb + 0     * pr;

ER = clamp (r * 255); /* [ok? one should prob. limit y1,pb,pr] */
EG = clamp (g * 255);
EB = clamp (b * 255);
      

2.3. Indexed Format

In this format each pixel is represented by an 8 bit indexinto a 256 entry ARGB palette. It is intended forVideo Output Overlays only. There are no ioctls toaccess the palette, this must be done with ioctls of the Linux framebuffer API.

2.4. RGB Formats

Packed RGB formats

V4L2_PIX_FMT_SBGGR8 ('BA81')

V4L2_PIX_FMT_SBGGR16 ('BA82')

2.5. YUV Formats

YUV is the format native to TV broadcast and composite videosignals. It separates the brightness information (Y) from the colorinformation (U and V or Cb and Cr). The color information consists ofred and bluecolor difference signals, this waythe green component can be reconstructed by subtracting from thebrightness component. SeeSection 2.2 for conversionexamples. YUV was chosen because early television would only transmitbrightness information. To add color in a way compatible with existingreceivers a new signal carrier was added to transmit the colordifference signals. Secondary in the YUV format the U and V componentsusually have lower resolution than the Y component. This is an analogvideo compression technique taking advantage of a property of thehuman visual system, being more sensitive to brightnessinformation.

Packed YUV formats

V4L2_PIX_FMT_GREY ('GREY')

V4L2_PIX_FMT_Y16 ('Y16 ')

V4L2_PIX_FMT_YUYV ('YUYV')

V4L2_PIX_FMT_UYVY ('UYVY')

V4L2_PIX_FMT_Y41P ('Y41P')

V4L2_PIX_FMT_YVU420 ('YV12'), V4L2_PIX_FMT_YUV420 ('YU12')

V4L2_PIX_FMT_YVU410 ('YVU9'), V4L2_PIX_FMT_YUV410 ('YUV9')

V4L2_PIX_FMT_YUV422P ('422P')

V4L2_PIX_FMT_YUV411P ('411P')

V4L2_PIX_FMT_NV12 ('NV12'), V4L2_PIX_FMT_NV21 ('NV21')

2.6. Compressed Formats

2.7. Reserved Format Identifiers

These formats are not defined by this specification, theyare just listed for reference and to avoid naming conflicts. If youwant to register your own format, send an e-mail to the V4L mailinglisthttps://listman.redhat.com/mailman/listinfo/video4linux-list for inclusion in thevideodev.hfile. If you want to share your format with other developers add alink to your documentation and send a copy to the maintainer of thisdocument, Michael Schimek<mschimek@gmx.at>, forinclusion in this section. If you think your format should be listedin a standard format section please make a proposal on the V4L mailinglist.

3.1. Read/Write

Input and output devices support theread() and write() function,respectively, when the V4L2_CAP_READWRITE flag inthecapabilities field of struct v4l2_capabilityreturned by theVIDIOC_QUERYCAP ioctl is set.

Drivers may need the CPU to copy the data, but they may alsosupport DMA to or from user memory, so this I/O method is notnecessarily less efficient than other methods merely exchanging bufferpointers. It is considered inferior though because no meta-informationlike frame counters or timestamps are passed. This information isnecessary to recognize frame dropping and to synchronize with otherdata streams. However this is also the simplest I/O method, requiringlittle or no setup to exchange data. It permits command line stuntslike this (the vidctrl tool isfictitious):

> vidctrl /dev/video --input=0 --format=YUYV --size=352x288
> dd if=/dev/video of=myimage.422 bs=202752 count=1

To read from the device applications use theread() function, to write thewrite() function.Drivers must implement one I/O method if theyexchange data with applications, but it need not be this.[12] When reading or writing is supported, the drivermust also support the select() and poll()function.[13]

3.2. Streaming I/O (Memory Mapping)

Input and output devices support this I/O method when theV4L2_CAP_STREAMING flag in thecapabilities field of struct v4l2_capabilityreturned by the VIDIOC_QUERYCAP ioctl is set. There are twostreaming methods, to determine if the memory mapping flavor issupported applications must call theVIDIOC_REQBUFS ioctl.

Streaming is an I/O method where only pointers to buffersare exchanged between application and driver, the data itself is notcopied. Memory mapping is primarily intended to map buffers in devicememory into the application's address space. Device memory can be forexample the video memory on a graphics card with a video captureadd-on. However, being the most efficient I/O method available for along time, many other drivers support streaming as well, allocatingbuffers in DMA-able main memory.

A driver can support many sets of buffers. Each set isidentified by a unique buffer type value. The sets are independent andeach set can hold a different type of data. To access different setsat the same time different file descriptors must be used.[14]

To allocate device buffers applications call theVIDIOC_REQBUFS ioctl with the desired number of buffers and buffertype, for exampleV4L2_BUF_TYPE_VIDEO_CAPTURE.This ioctl can also be used to change the number of buffers or to freethe allocated memory, provided none of the buffers are stillmapped.

Before applications can access the buffers they must mapthem into their address space with themmap() function. Thelocation of the buffers in device memory can be determined with theVIDIOC_QUERYBUF ioctl. Them.offset andlength returned in a struct v4l2_buffer arepassed as sixth and second parameter to themmap() function. The offset and length valuesmust not be modified. Remember the buffers are allocated in physicalmemory, as opposed to virtual memory which can be swapped out to disk.Applications should free the buffers as soon as possible with themunmap() function.

struct v4l2_requestbuffers reqbuf;
struct {
        void *start;
        size_t length;
} *buffers;
unsigned int i;

memset (&reqbuf, 0, sizeof (reqbuf));
reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
reqbuf.memory = V4L2_MEMORY_MMAP;
reqbuf.count = 20;

if (-1 == ioctl (fd, VIDIOC_REQBUFS, &reqbuf)) {
        if (errno == EINVAL)
                printf ("Video capturing or mmap-streaming is not supported\n");
        else
                perror ("VIDIOC_REQBUFS");

        exit (EXIT_FAILURE);
}

/* We want at least five buffers. */

if (reqbuf.count < 5) {
        /* You may need to free the buffers here. */
        printf ("Not enough buffer memory\n");
        exit (EXIT_FAILURE);
}

buffers = calloc (reqbuf.count, sizeof (*buffers));
assert (buffers != NULL);

for (i = 0; i < reqbuf.count; i++) {
        struct v4l2_buffer buffer;

        memset (&buffer, 0, sizeof (buffer));
        buffer.type = reqbuf.type;
	buffer.memory = V4L2_MEMORY_MMAP;
        buffer.index = i;

        if (-1 == ioctl (fd, VIDIOC_QUERYBUF, &buffer)) {
                perror ("VIDIOC_QUERYBUF");
                exit (EXIT_FAILURE);
        }

        buffers[i].length = buffer.length; /* remember for munmap() */

        buffers[i].start = mmap (NULL, buffer.length,
                                 PROT_READ | PROT_WRITE, /* recommended */
                                 MAP_SHARED,             /* recommended */
                                 fd, buffer.m.offset);

        if (MAP_FAILED == buffers[i].start) {
                /* If you do not exit here you should unmap() and free()
                   the buffers mapped so far. */
                perror ("mmap");
                exit (EXIT_FAILURE);
        }
}

/* Cleanup. */

for (i = 0; i < reqbuf.count; i++)
        munmap (buffers[i].start, buffers[i].length);
      

Conceptually streaming drivers maintain two buffer queues, an incomingand an outgoing queue. They separate the synchronous capture or outputoperation locked to a video clock from the application which issubject to random disk or network delays and preemption byother processes, thereby reducing the probability of data loss.The queues are organized as FIFOs, buffers will beoutput in the order enqueued in the incoming FIFO, and werecaptured in the order dequeued from the outgoing FIFO.

The driver may require a minimum number of buffers enqueuedat all times to function, apart of this no limit exists on the numberof buffers applications can enqueue in advance, or dequeue andprocess. They can also enqueue in a different order than buffers havebeen dequeued, and the driver can fill enqueuedempty buffers in any order.[15] The index number of a buffer (struct v4l2_bufferindex) plays no role here, it onlyidentifies the buffer.

Initially all mapped buffers are in dequeued state,inaccessible by the driver. For capturing applications it is customaryto first enqueue all mapped buffers, then to start capturing and enterthe read loop. Here the application waits until a filled buffer can bedequeued, and re-enqueues the buffer when the data is no longerneeded. Output applications fill and enqueue buffers, when enoughbuffers are stacked up the output is started withVIDIOC_STREAMON. In the write loop, whenthe application runs out of free buffers, it must wait until an emptybuffer can be dequeued and reused.

To enqueue and dequeue a buffer applications use theVIDIOC_QBUF andVIDIOC_DQBUF ioctl. The status of a buffer beingmapped, enqueued, full or empty can be determined at any time using theVIDIOC_QUERYBUF ioctl. Two methods exist to suspend execution of theapplication until one or more buffers can be dequeued. By defaultVIDIOC_DQBUF blocks when no buffer is in theoutgoing queue. When theO_NONBLOCK flag wasgiven to theopen() function,VIDIOC_DQBUFreturns immediately with anEAGAIN error code when no buffer is available. Theselect() orpoll() function are always available.

To start and stop capturing or output applications call theVIDIOC_STREAMON andVIDIOC_STREAMOFF ioctl. NoteVIDIOC_STREAMOFF removes all buffers from bothqueues as a side effect. Since there is no notion of doing anything"now" on a multitasking system, if an application needs to synchronizewith another event it should examine the struct v4l2_buffertimestamp of captured buffers, or set thefield before enqueuing buffers for output.

Drivers implementing memory mapping I/O mustsupport the VIDIOC_REQBUFS,VIDIOC_QUERYBUF,VIDIOC_QBUF,VIDIOC_DQBUF,VIDIOC_STREAMON andVIDIOC_STREAMOFF ioctl, themmap(),munmap(),select() andpoll()function.[16]

[capture example]

3.3. Streaming I/O (User Pointers)

Input and output devices support this I/O method when theV4L2_CAP_STREAMING flag in thecapabilities field of struct v4l2_capabilityreturned by the VIDIOC_QUERYCAP ioctl is set. If the particular userpointer method (not only memory mapping) is supported must bedetermined by calling theVIDIOC_REQBUFS ioctl.

This I/O method combines advantages of the read/write andmemory mapping methods. Buffers are allocated by the applicationitself, and can reside for example in virtual or shared memory. Onlypointers to data are exchanged, these pointers and meta-informationare passed in struct v4l2_buffer. The driver must be switchedinto user pointer I/O mode by calling theVIDIOC_REQBUFS with thedesired buffer type. No buffers are allocated beforehands,consequently they are not indexed and cannot be queried like mappedbuffers with theVIDIOC_QUERYBUF ioctl.

struct v4l2_requestbuffers reqbuf;

memset (&reqbuf, 0, sizeof (reqbuf));
reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
reqbuf.memory = V4L2_MEMORY_USERPTR;

if (ioctl (fd, VIDIOC_REQBUFS, &reqbuf) == -1) {
        if (errno == EINVAL)
                printf ("Video capturing or user pointer streaming is not supported\n");
        else
                perror ("VIDIOC_REQBUFS");

        exit (EXIT_FAILURE);
}
      

Buffer addresses and sizes are passed on the fly with theVIDIOC_QBUF ioctl. Although buffers are commonly cycled,applications can pass different addresses and sizes at eachVIDIOC_QBUF call. If required by the hardware thedriver swaps memory pages within physical memory to create acontinuous area of memory. This happens transparently to theapplication in the virtual memory subsystem of the kernel. When bufferpages have been swapped out to disk they are brought back and finallylocked in physical memory for DMA.[17]

Filled or displayed buffers are dequeued with theVIDIOC_DQBUF ioctl. The driver can unlock the memory pages at anytime between the completion of the DMA and this ioctl. The memory isalso unlocked when VIDIOC_STREAMOFF is called, VIDIOC_REQBUFS, orwhen the device is closed. Applications must take care not to freebuffers without dequeuing. For once, the buffers remain locked untilfurther, wasting physical memory. Second the driver will not benotified when the memory is returned to the application's free listand subsequently reused for other purposes, possibly completing therequested DMA and overwriting valuable data.

For capturing applications it is customary to enqueue anumber of empty buffers, to start capturing and enter the read loop.Here the application waits until a filled buffer can be dequeued, andre-enqueues the buffer when the data is no longer needed. Outputapplications fill and enqueue buffers, when enough buffers are stackedup output is started. In the write loop, when the applicationruns out of free buffers it must wait until an empty buffer can bedequeued and reused. Two methods exist to suspend execution of theapplication until one or more buffers can be dequeued. By defaultVIDIOC_DQBUF blocks when no buffer is in theoutgoing queue. When theO_NONBLOCK flag wasgiven to theopen() function,VIDIOC_DQBUFreturns immediately with anEAGAIN error code when no buffer is available. Theselect() orpoll() function are always available.

To start and stop capturing or output applications call theVIDIOC_STREAMON andVIDIOC_STREAMOFF ioctl. NoteVIDIOC_STREAMOFF removes all buffers from bothqueues and unlocks all buffers as a side effect. Since there is nonotion of doing anything "now" on a multitasking system, if anapplication needs to synchronize with another event it should examinethe struct v4l2_buffertimestamp of capturedbuffers, or set the field before enqueuing buffers for output.

Drivers implementing user pointer I/O mustsupport the VIDIOC_REQBUFS,VIDIOC_QBUF,VIDIOC_DQBUF,VIDIOC_STREAMON andVIDIOC_STREAMOFF ioctl, theselect() andpoll() function.[18]

3.4. Asynchronous I/O

This method is not defined yet.

3.5. Buffers

A buffer contains data exchanged by application anddriver using one of the Streaming I/O methods. Only pointers tobuffers are exchanged, the data itself is not copied. These pointers,together with meta-information like timestamps or field parity, arestored in a struct v4l2_buffer, argument tothe VIDIOC_QUERYBUF, VIDIOC_QBUF and VIDIOC_DQBUF ioctl.

Nominally timestamps refer to the first data byte transmitted.In practice however the wide range of hardware covered by the V4L2 APIlimits timestamp accuracy. Often an interrupt routine willsample the system clock shortly after the field or frame was storedcompletely in memory. So applications must expect a constantdifference up to one field or frame period plus a small (few scanlines) random error. The delay and error can be muchlarger due to compression or transmission over an external bus whenthe frames are not properly stamped by the sender. This is frequentlythe case with USB cameras. Here timestamps refer to the instant thefield or frame was received by the driver, not the capture time. Thesedevices identify by not enumerating any video standards, seeSection 1.7.

Similar limitations apply to output timestamps. Typicallythe video hardware locks to a clock controlling the video timing, thehorizontal and vertical synchronization pulses. At some point in theline sequence, possibly the vertical blanking, an interrupt routinesamples the system clock, compares against the timestamp and programsthe hardware to repeat the previous field or frame, or to display thebuffer contents.

Apart of limitations of the video device and naturalinaccuracies of all clocks, it should be noted system time itself isnot perfectly stable. It can be affected by power saving cycles,warped to insert leap seconds, or even turned back or forth by thesystem administrator affecting long term measurements. [19]

3.6. Field Order

We have to distinguish between progressive and interlacedvideo. Progressive video transmits all lines of a video imagesequentially. Interlaced video divides an image into two fields,containing only the odd and even lines of the image, respectively.Alternating the so called odd and even field are transmitted, and dueto a small delay between fields a cathode ray TV displays the linesinterleaved, yielding the original frame. This curious technique wasinvented because at refresh rates similar to film the image wouldfade out too quickly. Transmitting fields reduces the flicker withoutthe necessity of doubling the frame rate and with it the bandwidthrequired for each channel.

It is important to understand a video camera does not exposeone frame at a time, merely transmitting the frames separated intofields. The fields are in fact captured at two different instances intime. An object on screen may well move between one field and thenext. For applications analysing motion it is of paramount importanceto recognize which field of a frame is older, thetemporalorder.

When the driver provides or accepts images field by fieldrather than interleaved, it is also important applications understandhow the fields combine to frames. We distinguish between top andbottom fields, thespatial order: The first lineof the top field is the first line of an interlaced frame, the firstline of the bottom field is the second line of that frame.

However because fields were captured one after the other,arguing whether a frame commences with the top or bottom field ispointless. Any two successive top and bottom, or bottom and top fieldsyield a valid frame. Only when the source was progressive to beginwith, e. g. when transferring film to video, two fields may come fromthe same frame, creating a natural order.

Counter to intuition the top field is not necessarily theolder field. Whether the older field contains the top or bottom linesis a convention determined by the video standard. Hence thedistinction between temporal and spatial order of fields. The diagramsbelow should make this clearer.

All video capture and output devices must report the currentfield order. Some drivers may permit the selection of a differentorder, to this end applications initialize thefield field of struct v4l2_pix_format beforecalling the VIDIOC_S_FMT ioctl. If this is not desired it shouldhave the valueV4L2_FIELD_ANY (0).