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 mydriveralias char-major-81-1 mydriveralias 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).

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.1.2. Related Devices

Devices can support several related functions. For examplevideo capturing, video overlay and VBI capturing are related becausethese functions share, amongst other, the same video input and tunerfrequency. V4L and earlier versions of V4L2 used the same device nameand minor number for video capturing and overlay, but different onesfor VBI. Experience showed this approach has several problems[3], and to make things worse the V4L videodev moduleused to prohibit multiple opens of a device.

As a remedy the present version of the V4L2 API relaxed theconcept of device types with specific names and minor numbers. Forcompatibility with old applications drivers must still register differentminor numbers to assign a default function to the device. But if relatedfunctions are supported by the driver they must be available under allregistered minor numbers. The desired function can be selected afteropening the device as described inChapter 4.

Imagine a driver supporting video capturing, videooverlay, raw VBI capturing, and FM radio reception. It registers threedevices with minor number 0, 64 and 224 (this numbering scheme isinherited from the V4L API). Regardless if/dev/video (81, 0) or/dev/vbi (81, 224) is opened the application canselect any one of the video capturing, overlay or VBI capturingfunctions. Without programming (e. g. reading from the devicewithdd orcat)/dev/video captures video images, while/dev/vbi captures raw VBI data./dev/radio (81, 64) is invariable a radio device,unrelated to the video functions. Being unrelated does not imply thedevices can be used at the same time, however. Theopen()function may very well return anEBUSY error code.

Besides video input or output the hardware may alsosupport audio sampling or playback. If so, these functions areimplemented as OSS or ALSA PCM devices and eventually OSS or ALSAaudio mixer. The V4L2 API makes no provisions yet to find theserelated devices. If you have an idea please write to the Video4Linuxmailing list: https://listman.redhat.com/mailman/listinfo/video4linux-list.

1.1.3. Multiple Opens

In general, V4L2 devices can be opened more than once.When this is supported by the driver, users can for example start a"panel" application to change controls like brightness or audiovolume, while another application captures video and audio. In other words, panelapplications are comparable to an OSS or ALSA audio mixer application.When a device supports multiple functions like capturing and overlaysimultaneously, multiple opens allow concurrentuse of the device by forked processes or specialized applications.

Multiple opens are optional, although drivers shouldpermit at least concurrent accesses without data exchange, i. e. panelapplications. This impliesopen() can return anEBUSY error code when thedevice is already in use, as well asioctl() functions initiatingdata exchange (namely theVIDIOC_S_FMT ioctl), and theread()andwrite() functions.

Mere opening a V4L2 device does not grant exclusiveaccess.[4] Initiating data exchange however assigns the rightto read or write the requested type of data, and to change relatedproperties, to this file descriptor. Applications can requestadditional access privileges using the priority mechanism described inSection 1.3.

1.1.4. Shared Data Streams

V4L2 drivers should not support multiple applicationsreading or writing the same data stream on a device by copyingbuffers, time multiplexing or similar means. This is better handled bya proxy application in user space. When the driver supports streamsharing anyway it must be implemented transparently. The V4L2 API doesnot specify how conflicts are solved.

1.1.5. Functions

To open and close V4L2 devices applications use theopen() andclose() function, respectively. Devices areprogrammed using theioctl() function as explained in thefollowing sections.

Example 1-1. Information about the current video input

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);      

Example 1-2. Switching to the first video input

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

Example 1-3. Information about the current audio input

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);      

Example 1-4. Switching to the first audio input

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

Video input devices can have one or more tunersdemodulating a RF signal. Each tuner is associated with one or morevideo inputs, depending on the number of RF connectors on the tuner.Thetype field of the respectivestruct v4l2_input returned by theVIDIOC_ENUMINPUT ioctl is set toV4L2_INPUT_TYPE_TUNER and itstuner field contains the index number ofthe tuner.

Radio devices have exactly one tuner with index zero, novideo inputs.

To query and change tuner properties applications use theVIDIOC_G_TUNER andVIDIOC_S_TUNER ioctl, respectively. Thestruct v4l2_tuner returned byVIDIOC_G_TUNER alsocontains signal status information applicable when the tuner of thecurrent video input, or a radio tuner is queried. Note thatVIDIOC_S_TUNER does not switch the current tuner,when there is more than one at all. The tuner is solely determined bythe current video input. Drivers must support both ioctls and set theV4L2_CAP_TUNER flag in the struct v4l2_capabilityreturned by theVIDIOC_QUERYCAP ioctl when the device has one ormore tuners.

1.6.2. Modulators

Video output devices can have one or more modulators, uh,modulating a video signal for radiation or connection to the antennainput of a TV set or video recorder. Each modulator is associated withone or more video outputs, depending on the number of RF connectors onthe modulator. The type field of therespective struct v4l2_output returned by theVIDIOC_ENUMOUTPUT ioctl isset toV4L2_OUTPUT_TYPE_MODULATOR and itsmodulator field contains the index numberof the modulator. This specification does not define radio outputdevices.

To query and change modulator properties applications usethe VIDIOC_G_MODULATOR and VIDIOC_S_MODULATOR ioctl. Note thatVIDIOC_S_MODULATOR does not switch the currentmodulator, when there is more than one at all. The modulator is solelydetermined by the current video output. Drivers must support bothioctls and set the V4L2_CAP_TUNER (sic) flag inthe struct v4l2_capability returned by theVIDIOC_QUERYCAP ioctl when thedevice has one or more modulators.

1.6.3. Radio Frequency

To get and set the tuner or modulator radio frequencyapplications use the VIDIOC_G_FREQUENCY and VIDIOC_S_FREQUENCYioctl which both take a pointer to a struct v4l2_frequency. These ioctlsare used for TV and radio devices alike. Drivers must support bothioctls when the tuner or modulator ioctls are supported, orwhen the device is a radio device.

1.6.4. Satellite Receivers

To be discussed. See also proposals by Peter Schlaf, video4linux-list@redhat.com on 23 Oct 2002,subject: "Re: [V4L] Re: v4l2 api".

Example 1-5. Information about the current video standard

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);}      

Example 1-6. Listing the video standards supported by the currentinput

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);}      

Example 1-7. Selecting a new video standard

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);}      

Table 1-1. Control IDs

Example 1-8. Enumerating all controls

struct v4l2_queryctrl queryctrl;struct v4l2_querymenu querymenu;static voidenumerate_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);        }}

Example 1-9. Changing controls

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 = http://www.mamicode.com/queryctrl.default_value;"CONSTANT">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 = http://www.mamicode.com/TRUE; /* silence */>

1.9.1. Introduction

The control mechanism as originally designed was meantto be used for user settings (brightness, saturation, etc). However,it turned out to be a very useful model for implementing morecomplicated driver APIs where each driver implements only a subset ofa larger API.

The MPEG encoding API was the driving force behinddesigning and implementing this extended control mechanism: the MPEGstandard is quite large and the currently supported hardware MPEGencoders each only implement a subset of this standard. Further more,many parameters relating to how the video is encoded into an MPEGstream are specific to the MPEG encoding chip since the MPEG standardonly defines the format of the resulting MPEG stream, not how thevideo is actually encoded into that format.

Unfortunately, the original control API lacked somefeatures needed for these new uses and so it was extended into the(not terribly originally named) extended control API.

1.9.2. The Extended Control API

Three new ioctls are available: VIDIOC_G_EXT_CTRLS,VIDIOC_S_EXT_CTRLS andVIDIOC_TRY_EXT_CTRLS. These ioctls act onarrays of controls (as opposed to theVIDIOC_G_CTRL andVIDIOC_S_CTRL ioctls that act on a single control). This is neededsince it is often required to atomically change several controls atonce.

Each of the new ioctls expects a pointer to astruct v4l2_ext_controls. This structure contains a pointer to the controlarray, a count of the number of controls in that array and a controlclass. Control classes are used to group similar controls into asingle class. For example, control classV4L2_CTRL_CLASS_USER contains all user controls(i. e. all controls that can also be set using the oldVIDIOC_S_CTRL ioctl). Control classV4L2_CTRL_CLASS_MPEG contains all controlsrelating to MPEG encoding, etc.

All controls in the control array must belong to thespecified control class. An error is returned if this is not thecase.

It is also possible to use an empty control array (count== 0) to check whether the specified control class issupported.

The control array is a struct v4l2_ext_control array. Thev4l2_ext_control structure is very similar tostruct v4l2_control, except for the fact that it also allows for 64-bitvalues and pointers to be passed (although the latter is not yet usedanywhere).

It is important to realize that due to the flexibility ofcontrols it is necessary to check whether the control you want to setactually is supported in the driver and what the valid range of valuesis. So use theVIDIOC_QUERYCTRL andVIDIOC_QUERYMENU ioctls tocheck this. Also note that it is possible that some of the menuindices in a control of typeV4L2_CTRL_TYPE_MENUmay not be supported (VIDIOC_QUERYMENU willreturn an error). A good example is the list of supported MPEG audiobitrates. Some drivers only support one or two bitrates, otherssupport a wider range.

1.9.3. Enumerating Extended Controls

The recommended way to enumerate over the extendedcontrols is by using VIDIOC_QUERYCTRL in combination with theV4L2_CTRL_FLAG_NEXT_CTRL flag:

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;}

The initial control ID is set to 0 ORed with theV4L2_CTRL_FLAG_NEXT_CTRL flag. TheVIDIOC_QUERYCTRL ioctl will return the firstcontrol with a higher ID than the specified one. When no such controlsare found an error is returned.

If you want to get all controls within a specific controlclass, then you can set the initialqctrl.id value to the control class and addan extra check to break out of the loop when a control of anothercontrol class is found:

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;        }

The 32-bit qctrl.id value issubdivided into three bit ranges: the top 4 bits are reserved forflags (e. g.V4L2_CTRL_FLAG_NEXT_CTRL) and are notactually part of the ID. The remaining 28 bits form the control ID, ofwhich the most significant 12 bits define the control class and theleast significant 16 bits identify the control within the controlclass. It is guaranteed that these last 16 bits are always non-zerofor controls. The range of 0x1000 and up are reserved fordriver-specific controls. The macroV4L2_CTRL_ID2CLASS(id) returns the control classID based on a control ID.

If the driver does not support extended controls, thenVIDIOC_QUERYCTRL will fail when used incombination withV4L2_CTRL_FLAG_NEXT_CTRL. Inthat case the old method of enumerating control should be used (see1.8). But if it is supported, then it is guaranteed to enumerate overall controls, including driver-private controls.

1.9.4. Creating Control Panels

It is possible to create control panels for a graphicaluser interface where the user can select the various controls.Basically you will have to iterate over all controls using the methoddescribed above. Each control class starts with a control of typeV4L2_CTRL_TYPE_CTRL_CLASS.VIDIOC_QUERYCTRL will return the name of thiscontrol class which can be used as the title of a tab page within acontrol panel.

The flags field of struct v4l2_queryctrl also contains hints onthe behavior of the control. See theVIDIOC_QUERYCTRL documentationfor more details.

1.9.5. MPEG Control Reference

Below all controls within the MPEG control class aredescribed. First the generic controls, then controls specific forcertain hardware.

1.9.6. Camera Control Reference

The Camera class includes controls for mechanical (orequivalent digital) features of a device such as controllable lensesor sensors.

1.10.1. Data Format Negotiation

Different devices exchange different kinds of data withapplications, for example video images, raw or sliced VBI data, RDSdatagrams. Even within one kind many different formats are possible,in particular an abundance of image formats. Although drivers mustprovide a default and the selection persists across closing andreopening a device, applications should always negotiate a data formatbefore engaging in data exchange. Negotiation means the applicationasks for a particular format and the driver selects and reports thebest the hardware can do to satisfy the request. Of courseapplications can also just query the current selection.

A single mechanism exists to negotiate all data formatsusing the aggregate struct v4l2_format and theVIDIOC_G_FMT andVIDIOC_S_FMT ioctls. Additionally theVIDIOC_TRY_FMT ioctl can beused to examine what the hardwarecould do,without actually selecting a new data format. The data formatssupported by the V4L2 API are covered in the respective device sectioninChapter 4. For a closer look at image formats seeChapter 2.

The VIDIOC_S_FMT ioctl is a majorturning-point in the initialization sequence. Prior to this pointmultiple panel applications can access the same device concurrently toselect the current input, change controls or modify other properties.The first VIDIOC_S_FMT assigns a logical stream(video data, VBI data etc.) exclusively to one file descriptor.

Exclusive means no other application, more precisely noother file descriptor, can grab this stream or change deviceproperties inconsistent with the negotiated parameters. A videostandard change for example, when the new standard uses a differentnumber of scan lines, can invalidate the selected image format.Therefore only the file descriptor owning the stream can makeinvalidating changes. Accordingly multiple file descriptors whichgrabbed different logical streams prevent each other from interferingwith their settings. When for example video overlay is about to startor already in progress, simultaneous video capturing may be restrictedto the same cropping and image size.

When applications omit theVIDIOC_S_FMT ioctl its locking side effects areimplied by the next step, the selection of an I/O method with theVIDIOC_REQBUFS ioctl or implicit with the first read() orwrite() call.

Generally only one logical stream can be assigned to afile descriptor, the exception being drivers permitting simultaneousvideo capturing and overlay using the same file descriptor forcompatibility with V4L and earlier versions of V4L2. Switching thelogical stream or returning into "panel mode" is possible by closingand reopening the device. Driversmay support aswitch usingVIDIOC_S_FMT.

All drivers exchanging data withapplications must support the VIDIOC_G_FMT andVIDIOC_S_FMT ioctl. Implementation of theVIDIOC_TRY_FMT is highly recommended butoptional.

1.10.2. Image Format Enumeration

Apart of the generic format negotiation functionsa special ioctl to enumerate all image formats supported by videocapture, overlay or output devices is available.[11]

The VIDIOC_ENUM_FMT ioctl must be supportedby all drivers exchanging image data with applications.

1.11.1. Cropping Structures

For capture devices the coordinates of the top leftcorner, width and height of the area which can be sampled is given bythebounds substructure of thestruct v4l2_cropcap returned by theVIDIOC_CROPCAPioctl. To support a wide range of hardware this specification does notdefine an origin or units. However by convention drivers shouldhorizontally count unscaled samples relative to 0H (the leading edgeof the horizontal sync pulse, see Figure 4-1).Vertically ITU-R linenumbers of the first field (Figure 4-2,Figure 4-3), multiplied by two if the driver can capture bothfields.

The top left corner, width and height of the sourcerectangle, that is the area actually sampled, is given by struct v4l2_cropusing the same coordinate system as struct v4l2_cropcap. Applications canuse the VIDIOC_G_CROP andVIDIOC_S_CROP ioctls to get and set thisrectangle. It must lie completely within the capture boundaries andthe driver may further adjust the requested size and/or positionaccording to hardware limitations.

Each capture device has a default source rectangle, givenby the defrect substructure ofstruct v4l2_cropcap. The center of this rectangle shall align with thecenter of the active picture area of the video signal, and cover whatthe driver writer considers the complete picture. Drivers shall resetthe source rectangle to the default when the driver is first loaded,but not later.

For output devices these structures and ioctls are usedaccordingly, defining thetarget rectangle wherethe images will be inserted into the video signal.

1.11.2. Scaling Adjustments

Video hardware can have various cropping, insertion andscaling limitations. It may only scale up or down, support onlydiscrete scaling factors, or have different scaling abilities inhorizontal and vertical direction. Also it may not support scaling atall. At the same time the struct v4l2_crop rectangle may have to bealigned, and both the source and target rectangles may have arbitraryupper and lower size limits. In particular the maximumwidth and heightin struct v4l2_crop may be smaller than thestruct v4l2_cropcap.bounds area. Therefore, asusual, drivers are expected to adjust the requested parameters andreturn the actual values selected.

Applications can change the source or the target rectanglefirst, as they may prefer a particular image size or a certain area inthe video signal. If the driver has to adjust both to satisfy hardwarelimitations, the last requested rectangle shall take priority, and thedriver should preferably adjust the opposite one. The VIDIOC_TRY_FMTioctl however shall not change the driver state and therefore onlyadjust the requested rectangle.

Suppose scaling on a video capture device is restricted toa factor 1:1 or 2:1 in either direction and the target image size mustbe a multiple of 16 × 16 pixels. The source croppingrectangle is set to defaults, which are also the upper limit in thisexample, of 640 × 400 pixels at offset 0, 0. Anapplication requests an image size of 300 × 225pixels, assuming video will be scaled down from the "full picture"accordingly. The driver sets the image size to the closest possiblevalues 304 × 224, then chooses the cropping rectangleclosest to the requested size, that is 608 × 224(224 × 2:1 would exceed the limit 400). The offset0, 0 is still valid, thus unmodified. Given the default croppingrectangle reported byVIDIOC_CROPCAP theapplication can easily propose another offset to center the croppingrectangle.

Now the application may insist on covering an area using apicture aspect ratio closer to the original request, so it asks for acropping rectangle of 608 × 456 pixels. The presentscaling factors limit cropping to 640 × 384, so thedriver returns the cropping size 608 × 384 and adjuststhe image size to closest possible 304 × 192.

1.11.3. Examples

Source and target rectangles shall remain unchanged acrossclosing and reopening a device, such that piping data into or out of adevice will work without special preparations. More advancedapplications should ensure the parameters are suitable before startingI/O.

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;        

Gamma Correction

[to do]

E‘_R = f(R)

E‘_G = f(G)

E‘_B = f(B)

Construction of luminance and color-differencesignals

[to do]

E‘_Y =Coeff_R E‘_R+ Coeff_G E‘_G+ Coeff_B E‘_B

(E‘_R - E‘_Y) = E‘_R- Coeff_R E‘_R- Coeff_G E‘_G- Coeff_B E‘_B

(E‘_B - E‘_Y) = E‘_B- Coeff_R E‘_R- Coeff_G E‘_G- Coeff_B E‘_B

Re-normalized color-difference signals

The color-difference signals are scaled back to unityrange [-0.5;+0.5]:

K_B = 0.5 / (1 - Coeff_B)

K_R = 0.5 / (1 - Coeff_R)

P_B =K_B (E‘_B - E‘_Y) = 0.5 (Coeff_R / Coeff_B) E‘_R+ 0.5 (Coeff_G / Coeff_B) E‘_G+ 0.5 E‘_B

P_R =K_R (E‘_R - E‘_Y) = 0.5 E‘_R+ 0.5 (Coeff_G / Coeff_R) E‘_G+ 0.5 (Coeff_B / Coeff_R) E‘_B

Quantization

[to do]

Y‘ = (Lum. Levels - 1) · E‘_Y + Lum. Offset

C_B = (Chrom. Levels - 1)· P_B + Chrom. Offset

C_R = (Chrom. Levels - 1)· P_R + Chrom. Offset

Rounding to the nearest integer and clamping to the range[0;255] finally yields the digital color components Y‘CbCrstored in YUV images.

Example 2-1. ITU-R Rec. BT.601 color conversion

Forward Transformation

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;intclamp (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);      

Inverse Transformation

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;intclamp (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);      

Table 2-2. enum v4l2_colorspace

Table 2-3. Indexed Image Format

Table of Contents

Packed RGB formats -- Packed RGB formats

V4L2_PIX_FMT_SBGGR8 (‘BA81‘) -- Bayer RGB format

V4L2_PIX_FMT_SBGGR16 (‘BA82‘) -- Bayer RGB format

Name

Description

These formats are designed to match the pixel formats oftypical PC graphics frame buffers. They occupy 8, 16, 24 or 32 bitsper pixel. These are all packed-pixel formats, meaning all the datafor a pixel lie next to each other in memory.

When one of these formats is used, drivers shall report thecolorspace V4L2_COLORSPACE_SRGB.

Bit 7 is the most significant bit. The value of a = alphabits is undefined when reading from the driver, ignored when writingto the driver, except when alpha blending has been negotiated for aVideo Overlay or Video Output Overlay.

Some RGB formats above are uncommon and were probablydefined in error. Drivers may interpret them as inTable 2-2.

A test utility to determine which RGB formats a driveractually supports is available from the LinuxTV v4l-dvb repository.Seehttp://linuxtv.org/repo/ for access instructions.

Name

Description

This is commonly the native format of digital cameras,reflecting the arrangement of sensors on the CCD device. Only one red,green or blue value is given for each pixel. Missing components mustbe interpolated from neighbouring pixels. From left to right the firstrow consists of a blue and green value, the second row of a green andred value. This scheme repeats to the right and down for every twocolumns and rows.

Name

Description

This format is similar to V4L2_PIX_FMT_SBGGR8, except each pixel hasa depth of 16 bits. The least significant byte is stored at lowermemory addresses (little-endian). Note the actual sampling precisionmay be lower than 16 bits, for example 10 bits per pixel with valuesin range 0 to 1023.

Table of Contents

Packed YUV formats -- Packed YUV formats

V4L2_PIX_FMT_GREY (‘GREY‘) -- Grey-scale image

V4L2_PIX_FMT_Y16 (‘Y16 ‘) -- Grey-scale image

V4L2_PIX_FMT_YUYV (‘YUYV‘) -- Packed format with ½ horizontal chromaresolution, also known as YUV 4:2:2

V4L2_PIX_FMT_UYVY (‘UYVY‘) -- Variation ofV4L2_PIX_FMT_YUYV with different order of samplesin memory

V4L2_PIX_FMT_Y41P (‘Y41P‘) -- Format with ¼ horizontal chromaresolution, also known as YUV 4:1:1

V4L2_PIX_FMT_YVU420 (‘YV12‘), V4L2_PIX_FMT_YUV420 (‘YU12‘) -- Planar formats with ½ horizontal andvertical chroma resolution, also known as YUV 4:2:0

V4L2_PIX_FMT_YVU410 (‘YVU9‘), V4L2_PIX_FMT_YUV410 (‘YUV9‘) -- Planar formats with ¼ horizontal andvertical chroma resolution, also known as YUV 4:1:0

V4L2_PIX_FMT_YUV422P (‘422P‘) -- Format with ½ horizontal chroma resolution,also known as YUV 4:2:2. Planar layout as opposed toV4L2_PIX_FMT_YUYV

V4L2_PIX_FMT_YUV411P (‘411P‘) -- Format with ¼ horizontal chroma resolution,also known as YUV 4:1:1. Planar layout as opposed toV4L2_PIX_FMT_Y41P

V4L2_PIX_FMT_NV12 (‘NV12‘), V4L2_PIX_FMT_NV21 (‘NV21‘) -- Formats with ½ horizontal and verticalchroma resolution, also known as YUV 4:2:0. One luminance and onechrominance plane with alternating chroma samples as opposed toV4L2_PIX_FMT_YVU420

Name

Description

Similar to the packed RGB formats these formats storethe Y, Cb and Cr component of each pixel in one 16 or 32 bitword.

Bit 7 is the most significant bit. The value of a = alphabits is undefined when reading from the driver, ignored when writingto the driver, except when alpha blending has been negotiated for aVideo Overlay or Video Output Overlay.

Name

Description

This is a grey-scale image. It is really a degenerateY‘CbCr format which simply contains no Cb or Cr data.

Name

Description

This is a grey-scale image with a depth of 16 bits perpixel. The least significant byte is stored at lower memory addresses(little-endian). Note the actual sampling precision may be lower than16 bits, for example 10 bits per pixel with values in range 0 to1023.

Name

Description

In this format each four bytes is two pixels. Each fourbytes is two Y‘s, a Cb and a Cr. Each Y goes to one of the pixels, andthe Cb and Cr belong to both pixels. As you can see, the Cr and Cbcomponents have half the horizontal resolution of the Y component.V4L2_PIX_FMT_YUYVis known in the Windowsenvironment as YUY2.

Name

Description

In this format each four bytes is two pixels. Each fourbytes is two Y‘s, a Cb and a Cr. Each Y goes to one of the pixels, andthe Cb and Cr belong to both pixels. As you can see, the Cr and Cbcomponents have half the horizontal resolution of the Ycomponent.

Name

Description

In this format each 12 bytes is eight pixels. In thetwelve bytes are two CbCr pairs and eight Y‘s. The first CbCr pairgoes with the first four Y‘s, and the second CbCr pair goes with theother four Y‘s. The Cb and Cr components have one fourth thehorizontal resolution of the Y component.

Do not confuse this format with V4L2_PIX_FMT_YUV411P. Y41P is derived from "YUV 4:1:1packed", whileYUV411P stands for "YUV 4:1:1planar".

Name

Description

These are planar formats, as opposed to a packed format.The three components are separated into three sub- images or planes.The Y plane is first. The Y plane has one byte per pixel. ForV4L2_PIX_FMT_YVU420, the Cr plane immediatelyfollows the Y plane in memory. The Cr plane is half the width and halfthe height of the Y plane (and of the image). Each Cr belongs to fourpixels, a two-by-two square of the image. For example,Cr₀ belongs to Y‘₀₀,Y‘₀₁, Y‘₁₀, andY‘₁₁. Following the Cr plane is the Cb plane,just like the Cr plane.V4L2_PIX_FMT_YUV420 isthe same except the Cb plane comes first, then the Cr plane.

If the Y plane has pad bytes after each row, then the Crand Cb planes have half as many pad bytes after their rows. In otherwords, two Cx rows (including padding) is exactly as long as one Y row(including padding).

Name

Description

These are planar formats, as opposed to a packed format.The three components are separated into three sub-images or planes.The Y plane is first. The Y plane has one byte per pixel. ForV4L2_PIX_FMT_YVU410, the Cr plane immediatelyfollows the Y plane in memory. The Cr plane is ¼ the width and¼ the height of the Y plane (and of the image). Each Cr belongsto 16 pixels, a four-by-four square of the image. Following the Crplane is the Cb plane, just like the Cr plane.V4L2_PIX_FMT_YUV410 is the same, except the Cbplane comes first, then the Cr plane.

If the Y plane has pad bytes after each row, then the Crand Cb planes have ¼ as many pad bytes after their rows. Inother words, four Cx rows (including padding) are exactly as long asone Y row (including padding).

Name

Description

This format is not commonly used. This is a planarversion of the YUYV format. The three components are separated intothree sub-images or planes. The Y plane is first. The Y plane has onebyte per pixel. The Cb plane immediately follows the Y plane inmemory. The Cb plane is half the width of the Y plane (and of theimage). Each Cb belongs to two pixels. For example,Cb₀ belongs to Y‘₀₀,Y‘₀₁. Following the Cb plane is the Cr plane,just like the Cb plane.

If the Y plane has pad bytes after each row, then the Crand Cb planes have half as many pad bytes after their rows. In otherwords, two Cx rows (including padding) is exactly as long as one Y row(including padding).

Name

Description

This format is not commonly used. This is a planarformat similar to the 4:2:2 planar format except with half as manychroma. The three components are separated into three sub-images orplanes. The Y plane is first. The Y plane has one byte per pixel. TheCb plane immediately follows the Y plane in memory. The Cb plane is¼ the width of the Y plane (and of the image). Each Cb belongsto 4 pixels all on the same row. For example,Cb₀ belongs to Y‘₀₀,Y‘₀₁, Y‘₀₂ andY‘₀₃. Following the Cb plane is the Cr plane,just like the Cb plane.

If the Y plane has pad bytes after each row, then the Crand Cb planes have ¼ as many pad bytes after their rows. Inother words, four C x rows (including padding) is exactly as long asone Y row (including padding).

Name

Description

These are two-plane versions of the YUV 4:2:0 format.The three components are separated into two sub-images or planes. TheY plane is first. The Y plane has one byte per pixel. ForV4L2_PIX_FMT_NV12, a combined CbCr planeimmediately follows the Y plane in memory. The CbCr plane is the samewidth, in bytes, as the Y plane (and of the image), but is half astall in pixels. Each CbCr pair belongs to four pixels. For example,Cb₀/Cr₀ belongs toY‘₀₀, Y‘₀₁,Y‘₁₀, Y‘₁₁.V4L2_PIX_FMT_NV21 is the same except the Cb andCr bytes are swapped, the CrCb plane starts with a Cr byte.

If the Y plane has pad bytes after each row, then theCbCr plane has as many pad bytes after its rows.

Table 2-7. Compressed Image Formats

Table 2-8. Reserved Image Formats

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

Example 3-1. Mapping buffers

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);      

Example 3-2. Initiating streaming I/O with user pointers

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);}      

Table 3-1. struct v4l2_buffer

Table 3-2. enum v4l2_buf_type

Table 3-3. Buffer Flags

Table 3-4. enum v4l2_memory

3.5.1. Timecodes

The v4l2_timecode structure isdesigned to hold aSMPTE 12M or similar timecode.(structtimeval timestamps are stored instruct v4l2_buffer fieldtimestamp.)

Table 3-8. enum v4l2_field

Figure 3-1. Field Order, Top Field First Transmitted

Figure 3-2. Field Order, Bottom Field First Transmitted

4.1.1. Querying Capabilities

Devices supporting the video capture interface set theV4L2_CAP_VIDEO_CAPTURE flag in thecapabilities field of struct v4l2_capabilityreturned by the VIDIOC_QUERYCAP ioctl. As secondary device functionsthey may also support thevideo overlay(V4L2_CAP_VIDEO_OVERLAY) and theraw VBI capture(V4L2_CAP_VBI_CAPTURE) interface. At least one ofthe read/write or streaming I/O methods must be supported. Tuners andaudio inputs are optional.

4.1.2. Supplemental Functions

Video capture devices shall support audio input, tuner, controls,cropping and scaling andstreaming parameter ioctls as needed.Thevideo input andvideo standard ioctls must be supported byall video capture devices.

4.1.3. Image Format Negotiation

The result of a capture operation is determined bycropping and image format parameters. The former select an area of thevideo picture to capture, the latter how images are stored in memory,i. e. in RGB or YUV format, the number of bits per pixel or width andheight. Together they also define how images are scaled in theprocess.

As usual these parameters are not resetatopen() time to permit Unix tool chains, programming a deviceand then reading from it as if it was a plain file. Well written V4L2applications ensure they really get what they want, including croppingand scaling.

Cropping initialization at minimum requires to reset theparameters to defaults. An example is given inSection 1.11.

To query the current image format applications set thetype field of a struct v4l2_format toV4L2_BUF_TYPE_VIDEO_CAPTURE and call theVIDIOC_G_FMT ioctl with a pointer to this structure. Drivers fillthe struct v4l2_pix_formatpix member of thefmt union.

To request different parameters applications set thetype field of a struct v4l2_format as above andinitialize all fields of the struct v4l2_pix_formatvbi member of thefmt union, or better just modify theresults ofVIDIOC_G_FMT, and call theVIDIOC_S_FMT ioctl with a pointer to this structure. Drivers mayadjust the parameters and finally return the actual parameters asVIDIOC_G_FMT does.

Like VIDIOC_S_FMT theVIDIOC_TRY_FMT ioctl can be used to learn about hardware limitationswithout disabling I/O or possibly time consuming hardwarepreparations.

The contents of struct v4l2_pix_format are discussed inChapter 2. See also the specification of theVIDIOC_G_FMT,VIDIOC_S_FMTandVIDIOC_TRY_FMT ioctls for details. Videocapture devices must implement both theVIDIOC_G_FMT andVIDIOC_S_FMT ioctl, even ifVIDIOC_S_FMT ignores all requests and alwaysreturns default parameters asVIDIOC_G_FMT does.VIDIOC_TRY_FMT is optional.

4.1.4. Reading Images

A video capture device may support the read() function and/or streaming (memory mapping oruser pointer) I/O. SeeChapter 3 for details.

4.2.1. Querying Capabilities

Devices supporting the video overlay interface set theV4L2_CAP_VIDEO_OVERLAY flag in thecapabilities field of struct v4l2_capabilityreturned by the VIDIOC_QUERYCAP ioctl. The overlay I/O method specifiedbelow must be supported. Tuners and audio inputs are optional.

4.2.2. Supplemental Functions

Video overlay devices shall support audio input, tuner, controls,cropping and scaling andstreaming parameter ioctls as needed.Thevideo input andvideo standard ioctls must be supported byall video overlay devices.

4.2.3. Setup

Before overlay can commence applications must program thedriver with frame buffer parameters, namely the address and size ofthe frame buffer and the image format, for example RGB 5:6:5. TheVIDIOC_G_FBUF and VIDIOC_S_FBUF ioctls are available to getand set these parameters, respectively. TheVIDIOC_S_FBUF ioctl is privileged because itallows to set up DMA into physical memory, bypassing the memoryprotection mechanisms of the kernel. Only the superuser can change theframe buffer address and size. Users are not supposed to run TVapplications as root or with SUID bit set. A small helper applicationwith suitable privileges should query the graphics system and programthe V4L2 driver at the appropriate time.

Some devices add the video overlay to the output signalof the graphics card. In this case the frame buffer is not modified bythe video device, and the frame buffer address and pixel format arenot needed by the driver. TheVIDIOC_S_FBUF ioctlis not privileged. An application can check for this type of device bycalling theVIDIOC_G_FBUF ioctl.

A driver may support any (or none) of five clipping/blendingmethods:

1. Chroma-keying displays the overlaid image only wherepixels in the primary graphics surface assume a certain color.

2. A bitmap can be specified where each bit correspondsto a pixel in the overlaid image. When the bit is set, thecorresponding video pixel is displayed, otherwise a pixel of thegraphics surface.

3. A list of clipping rectangles can be specified. Inthese regions no video is displayed, so thegraphics surface can be seen here.

4. The framebuffer has an alpha channel that can be usedto clip or blend the framebuffer with the video.

5. A global alpha value can be specified to blend theframebuffer contents with video images.

When simultaneous capturing and overlay is supported andthe hardware prohibits different image and frame buffer formats, theformat requested first takes precedence. The attempt to capture(VIDIOC_S_FMT) or overlay (VIDIOC_S_FBUF) may fail with anEBUSY error code or return accordingly modified parameters..

4.2.4. Overlay Window

The overlaid image is determined by cropping and overlaywindow parameters. The former select an area of the video picture tocapture, the latter how images are overlaid and clipped. Croppinginitialization at minimum requires to reset the parameters todefaults. An example is given in Section 1.11.

The overlay window is described by a struct v4l2_window. Itdefines the size of the image, its position over the graphics surfaceand the clipping to be applied. To get the current parametersapplications set the type field of astruct v4l2_format toV4L2_BUF_TYPE_VIDEO_OVERLAY andcall theVIDIOC_G_FMT ioctl. The driver fills thev4l2_window substructure namedwin. It is not possible to retrieve apreviously programmed clipping list or bitmap.

To program the overlay window applications set thetype field of a struct v4l2_format toV4L2_BUF_TYPE_VIDEO_OVERLAY, initialize thewin substructure and call theVIDIOC_S_FMT ioctl. The driver adjusts the parameters againsthardware limits and returns the actual parameters asVIDIOC_G_FMT does. LikeVIDIOC_S_FMT, theVIDIOC_TRY_FMT ioctl can beused to learn about driver capabilities without actually changingdriver state. UnlikeVIDIOC_S_FMT this also worksafter the overlay has been enabled.

The scaling factor of the overlaid image is implied by thewidth and height given in struct v4l2_window and the size of the croppingrectangle. For more information seeSection 1.11.

When simultaneous capturing and overlay is supported andthe hardware prohibits different image and window sizes, the sizerequested first takes precedence. The attempt to capture or overlay aswell (VIDIOC_S_FMT) may fail with an EBUSY error code or return accordinglymodified parameters.

((__u8 *) bitmap)[w.width * y + x / 8] & (1 << (x & 7))

4.2.5. Enabling Overlay

To start or stop the frame buffer overlay applications callthe VIDIOC_OVERLAY ioctl.

4.3.1. Querying Capabilities

Devices supporting the video output interface set theV4L2_CAP_VIDEO_OUTPUT flag in thecapabilities field of struct v4l2_capabilityreturned by the VIDIOC_QUERYCAP ioctl. As secondary device functionsthey may also support theraw VBIoutput (V4L2_CAP_VBI_OUTPUT) interface. Atleast one of the read/write or streaming I/O methods must besupported. Modulators and audio outputs are optional.

4.3.2. Supplemental Functions

Video output devices shall support audio output, modulator, controls,cropping and scaling andstreaming parameter ioctls as needed.Thevideo output andvideo standard ioctls must be supported byall video output devices.

4.3.3. Image Format Negotiation

The output is determined by cropping and image formatparameters. The former select an area of the video picture where theimage will appear, the latter how images are stored in memory, i. e. inRGB or YUV format, the number of bits per pixel or width and height.Together they also define how images are scaled in the process.

As usual these parameters are not resetatopen() time to permit Unix tool chains, programming a deviceand then writing to it as if it was a plain file. Well written V4L2applications ensure they really get what they want, including croppingand scaling.

Cropping initialization at minimum requires to reset theparameters to defaults. An example is given inSection 1.11.

To query the current image format applications set thetype field of a struct v4l2_format toV4L2_BUF_TYPE_VIDEO_OUTPUT and call theVIDIOC_G_FMT ioctl with a pointer to this structure. Drivers fillthe struct v4l2_pix_formatpix member of thefmt union.

To request different parameters applications set thetype field of a struct v4l2_format as above andinitialize all fields of the struct v4l2_pix_formatvbi member of thefmt union, or better just modify theresults ofVIDIOC_G_FMT, and call theVIDIOC_S_FMT ioctl with a pointer to this structure. Drivers mayadjust the parameters and finally return the actual parameters asVIDIOC_G_FMT does.

Like VIDIOC_S_FMT theVIDIOC_TRY_FMT ioctl can be used to learn about hardware limitationswithout disabling I/O or possibly time consuming hardwarepreparations.

The contents of struct v4l2_pix_format are discussed inChapter 2. See also the specification of theVIDIOC_G_FMT,VIDIOC_S_FMTandVIDIOC_TRY_FMT ioctls for details. Videooutput devices must implement both theVIDIOC_G_FMT andVIDIOC_S_FMT ioctl, even ifVIDIOC_S_FMT ignores all requests and alwaysreturns default parameters asVIDIOC_G_FMT does.VIDIOC_TRY_FMT is optional.

4.3.4. Writing Images

A video output device may support the write() function and/or streaming (memory mapping oruser pointer) I/O. SeeChapter 3 for details.

Experimental: This is an experimentalinterface and may change in the future.

4.4.1. Querying Capabilities

Devices supporting the Video OutputOverlay interface set theV4L2_CAP_VIDEO_OUTPUT_OVERLAY flag in thecapabilities field of struct v4l2_capabilityreturned by the VIDIOC_QUERYCAP ioctl.

4.4.2. Framebuffer

Contrary to the Video Overlayinterface the framebuffer is normally implemented on the TV card andnot the graphics card. On Linux it is accessible as a framebufferdevice (/dev/fbN). Given a V4L2 device,applications can find the corresponding framebuffer device by callingthe VIDIOC_G_FBUF ioctl. It returns, amongst other information, thephysical address of the framebuffer in thebase field of struct v4l2_framebuffer. Theframebuffer device ioctl FBIOGET_FSCREENINFOreturns the same address in thesmem_startfield of structfb_fix_screeninfo. TheFBIOGET_FSCREENINFO ioctl and structfb_fix_screeninfo are defined in thelinux/fb.h header file.

The width and height of the framebuffer depends on thecurrent video standard. A V4L2 driver may reject attempts to changethe video standard (or any other ioctl which would imply a framebuffersize change) with anEBUSY error code until all applications closed theframebuffer device.

#include <linux/fb.h>struct v4l2_framebuffer fbuf;unsigned int i;int fb_fd;if (-1 == ioctl (fd, VIDIOC_G_FBUF, &fbuf)) {        perror ("VIDIOC_G_FBUF");        exit (EXIT_FAILURE);}for (i = 0; i < 30; ++i) {        char dev_name[16];        struct fb_fix_screeninfo si;        snprintf (dev_name, sizeof (dev_name), "/dev/fb%u", i);        fb_fd = open (dev_name, O_RDWR);        if (-1 == fb_fd) {                switch (errno) {                case ENOENT: /* no such file */                case ENXIO:  /* no driver */                        continue;                default:                        perror ("open");                        exit (EXIT_FAILURE);                }        }        if (0 == ioctl (fb_fd, FBIOGET_FSCREENINFO, &si)) {                if (si.smem_start == (unsigned long) fbuf.base)                        break;        } else {                /* Apparently not a framebuffer device. */        }        close (fb_fd);        fb_fd = -1;}/* fb_fd is the file descriptor of the framebuffer device   for the video output overlay, or -1 if no device was found. */

4.4.3. Overlay Window and Scaling

The overlay is controlled by source and target rectangles.The source rectangle selects a subsection of the framebuffer image tobe overlaid, the target rectangle an area in the outgoing video signalwhere the image will appear. Drivers may or may not support scaling,and arbitrary sizes and positions of these rectangles. Further driversmay support any (or none) of the clipping/blending methods defined fortheVideo Overlay interface.

A struct v4l2_window defines the size of the source rectangle,its position in the framebuffer and the clipping/blending method to beused for the overlay. To get the current parameters applications setthe type field of a struct v4l2_format toV4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY and call theVIDIOC_G_FMT ioctl. The driver fills thev4l2_window substructure namedwin. It is not possible to retrieve apreviously programmed clipping list or bitmap.

To program the source rectangle applications set thetype field of a struct v4l2_format toV4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY, initializethe win substructure and call theVIDIOC_S_FMT ioctl. The driver adjusts the parameters againsthardware limits and returns the actual parameters asVIDIOC_G_FMT does. LikeVIDIOC_S_FMT, theVIDIOC_TRY_FMT ioctl can beused to learn about driver capabilities without actually changingdriver state. UnlikeVIDIOC_S_FMT this also worksafter the overlay has been enabled.

A struct v4l2_crop defines the size and position of the targetrectangle. The scaling factor of the overlay is implied by the widthand height given in struct v4l2_window and struct v4l2_crop. The cropping APIapplies toVideo Output andVideoOutput Overlay devices in the same way as toVideo Capture andVideoOverlay devices, merely reversing the direction of thedata flow. For more information seeSection 1.11.

4.4.4. Enabling Overlay

There is no V4L2 ioctl to enable or disable the overlay,however the framebuffer interface of the driver may support theFBIOBLANK ioctl.

Suspended: This interface has been be suspended from the V4L2 APIimplemented in Linux 2.6 until we have more experience with codecdevice interfaces.

Suspended: This interface has been be suspended from the V4L2 APIimplemented in Linux 2.6 until we have more experience with effectdevice interfaces.

4.7.1. Querying Capabilities

Devices supporting the raw VBI capturing or output API setthe V4L2_CAP_VBI_CAPTURE orV4L2_CAP_VBI_OUTPUT flags, respectively, in thecapabilities field of struct v4l2_capabilityreturned by the VIDIOC_QUERYCAP ioctl. At least one of theread/write, streaming or asynchronous I/O methods must besupported. VBI devices may or may not have a tuner or modulator.

4.7.2. Supplemental Functions

VBI devices shall support videoinput or output, tuner ormodulator, and controls ioctlsas needed. The video standard ioctls provideinformation vital to program a VBI device, therefore must besupported.

4.7.3. Raw VBI Format Negotiation

Raw VBI sampling abilities can vary, in particular thesampling frequency. To properly interpret the data V4L2 specifies anioctl to query the sampling parameters. Moreover, to allow for someflexibility applications can also suggest different parameters.

As usual these parameters are notreset atopen() time to permit Unix tool chains, programming adevice and then reading from it as if it was a plain file. Wellwritten V4L2 applications should always ensure they really get whatthey want, requesting reasonable parameters and then checking if theactual parameters are suitable.

To query the current raw VBI capture parametersapplications set the type field of astruct v4l2_format toV4L2_BUF_TYPE_VBI_CAPTURE orV4L2_BUF_TYPE_VBI_OUTPUT, and call theVIDIOC_G_FMT ioctl with a pointer to this structure. Drivers fillthe struct v4l2_vbi_formatvbi member of thefmt union.

To request different parameters applications set thetype field of a struct v4l2_format as above andinitialize all fields of the struct v4l2_vbi_formatvbi member of thefmt union, or better just modify theresults ofVIDIOC_G_FMT, and call theVIDIOC_S_FMT ioctl with a pointer to this structure. Drivers returnanEINVAL error code only when the given parameters are ambiguous, otherwisethey modify the parameters according to the hardware capabilites andreturn the actual parameters. When the driver allocates resources atthis point, it may return an EBUSY error code to indicate the returnedparameters are valid but the required resources are currently notavailable. That may happen for instance when the video and VBI areasto capture would overlap, or when the driver supports multiple opensand another process already requested VBI capturing or output. Anyway,applications must expect other resource allocation points which mayreturnEBUSY, at theVIDIOC_STREAMON ioctland the first read(), write() and select() call.

VBI devices must implement both theVIDIOC_G_FMT andVIDIOC_S_FMT ioctl, even ifVIDIOC_S_FMT ignores all requests and alwaysreturns default parameters asVIDIOC_G_FMT does.VIDIOC_TRY_FMT is optional.