Table of Contents
The following chapters document the evolution of the V4L2 API, errata or extensions. They are also intended to help application and driver writers to port or update their code.
The Video For Linux API was first introduced in Linux 2.1 to unify and replace various TV and radio device related interfaces, developed independently by driver writers in prior years. Starting with Linux 2.5 the much improved V4L2 API replaces the V4L API. The support for the old V4L calls were removed from Kernel, but the library Chapter 6, Libv4l Userspace Library supports the conversion of a V4L API system call into a V4L2 one.
For compatibility reasons the character device file names recommended for V4L2 video capture, overlay, radio and raw vbi capture devices did not change from those used by V4L. They are listed in Chapter 4, Interfaces and below in Table 7.1, “V4L Device Types, Names and Numbers”.
The teletext devices (minor range 192-223) have been removed in V4L2 and no longer exist. There is no hardware available anymore for handling pure teletext. Instead raw or sliced VBI is used.
videodev module automatically
assigns minor numbers to drivers in load order, depending on the
registered device type. We recommend that V4L2 drivers by default
register devices with the same numbers, but the system administrator
can assign arbitrary minor numbers using driver module options. The
major device number remains 81.
Table 7.1. V4L Device Types, Names and Numbers
|Device Type||File Name||Minor Numbers|
|Video capture and overlay||0-63|
|Raw VBI capture||224-255|
[a] According to
Documentation/devices.txt these should be symbolic links to
[b] According to
V4L prohibits (or used to prohibit) multiple opens of a device file. V4L2 drivers may support multiple opens, see the section called “Opening and Closing Devices” for details and consequences.
V4L drivers respond to V4L2 ioctls with an EINVAL error code.
VIDIOCGCAP ioctl is
equivalent to V4L2's
name field in struct
card in struct v4l2_capability,
type was replaced by
capabilities. Note V4L2 does not
distinguish between device types like this, better think of basic
video input, video output and radio devices supporting a set of
related functions like video capturing, video overlay and VBI
capturing. See the section called “Opening and Closing Devices” for an
|The video capture interface is supported.|
|The device has a tuner or modulator.|
|The raw VBI capture interface is supported.|
|The video overlay interface is supported.|
|Whether chromakey overlay is supported. For more information on overlay see the section called “Video Overlay Interface”.|
|Whether clipping the overlaid image is supported, see the section called “Video Overlay Interface”.|
|Whether overlay overwrites frame buffer memory, see the section called “Video Overlay Interface”.|
|This flag indicates if the hardware can scale
images. The V4L2 API implies the scale factor by setting the cropping
dimensions and image size with the |
|Applications can enumerate the supported image
formats with the |
|Applications can call the |
|Applications can enumerate the supported image
formats with the |
audios field was replaced
if the device has any audio inputs or outputs. To
determine their number applications can enumerate audio inputs with
VIDIOC_G_AUDIO ioctl. The audio ioctls are described in the section called “Audio Inputs and Outputs”.
minheight fields were removed. Calling the
VIDIOC_TRY_FMT ioctl with the desired dimensions
returns the closest size possible, taking into account the current
video standard, cropping and scaling limitations.
V4L provides the
VIDIOCSCHAN ioctl using struct
video_channel to enumerate
the video inputs of a V4L device. The equivalent V4L2 ioctls
using struct v4l2_input as discussed in the section called “Video Inputs and Outputs”.
channel field counting
inputs was renamed to
index, the video
input types were renamed as follows:
expressing the number of tuners of this input, V4L2 assumes each video
input is connected to at most one tuner. However a tuner can have more
than one input, i. e. RF connectors, and a device can have multiple
tuners. The index number of the tuner associated with the input, if
any, is stored in field
struct v4l2_input. Enumeration of tuners is discussed in the section called “Tuners and Modulators”.
VIDEO_VC_TUNER flag was
dropped. Video inputs associated with a tuner are of type
VIDEO_VC_AUDIO flag was replaced by the
audioset field. V4L2 considers devices with
up to 32 audio inputs. Each set bit in the
audioset field represents one audio input
this video input combines with. For information about audio inputs and
how to switch between them see the section called “Audio Inputs and Outputs”.
norm field describing the
supported video standards was replaced by
std. The V4L specification mentions a flag
VIDEO_VC_NORM indicating whether the standard can
be changed. This flag was a later addition together with the
norm field and has been removed in the
meantime. V4L2 has a similar, albeit more comprehensive approach
to video standards, see the section called “Video Standards” for more
VIDIOCSTUNER ioctl and struct
video_tuner can be used to enumerate the
tuners of a V4L TV or radio device. The equivalent V4L2 ioctls are
VIDIOC_S_TUNER using struct v4l2_tuner. Tuners are
covered in the section called “Tuners and Modulators”.
tuner field counting tuners
was renamed to
index. The fields
rangehigh remained unchanged.
VIDEO_TUNER_SECAM flags indicating the supported
video standards were dropped. This information is now contained in the
associated struct v4l2_input. No replacement exists for the
VIDEO_TUNER_NORM flag indicating whether the
video standard can be switched. The
field to select a different video standard was replaced by a whole new
set of ioctls and structures described in the section called “Video Standards”.
Due to its ubiquity it should be mentioned the BTTV driver supports
several standards in addition to the regular
VIDEO_MODE_AUTO (3). Namely N/PAL Argentina,
M/PAL, N/PAL, and NTSC Japan with numbers 3-6 (sic).
indicating stereo reception became
V4L2_TUNER_SUB_STEREO in field
rxsubchans. This field also permits the
detection of monaural and bilingual audio, see the definition of
struct v4l2_tuner for details. Presently no replacement exists for the
VIDEO_TUNER_LOW flag was renamed
V4L2_TUNER_CAP_LOW in the struct v4l2_tuner
VIDIOCSFREQ ioctl to change the tuner frequency
where renamed to
take a pointer to a struct v4l2_frequency instead of an unsigned long
V4L2 has no equivalent of the
ioctl and struct video_picture. The following
fields where replaced by V4L2 controls accessible with the
|struct video_picture||V4L2 Control ID|
The V4L picture controls are assumed to range from 0 to
65535 with no particular reset value. The V4L2 API permits arbitrary
limits and defaults which can be queried with the
ioctl. For general information about controls see the section called “User Controls”.
depth (average number of
bits per pixel) of a video image is implied by the selected image
format. V4L2 does not explicitly provide such information assuming
applications recognizing the format are aware of the image depth and
others need not know. The
moved into the struct v4l2_pix_format:
[a] This is a custom format used by the BTTV driver, not one of the V4L2 standard formats.
[b] Presumably all V4L RGB formats are little-endian, although some drivers might interpret them according to machine endianness. V4L2 defines little-endian, big-endian and red/blue swapped variants. For details see the section called “RGB Formats”.
[d] Not to be confused with
[e] V4L explains this as: "RAW capture (BT848)"
[f] Not to be confused with
VIDIOCSAUDIO ioctl and struct
video_audio are used to enumerate the
audio inputs of a V4L device. The equivalent V4L2 ioctls are
VIDIOC_S_AUDIO using struct v4l2_audio as
discussed in the section called “Audio Inputs and Outputs”.
audio "channel number"
field counting audio inputs was renamed to
mode field selects one
VIDEO_SOUND_LANG2 audio demodulation modes. When
the current audio standard is BTSC
VIDEO_SOUND_LANG2 refers to SAP and
VIDEO_SOUND_LANG1 is meaningless. Also
undocumented in the V4L specification, there is no way to query the
selected mode. On
VIDIOCGAUDIO the driver returns
the actually received audio programmes in this
field. In the V4L2 API this information is stored in the struct v4l2_tuner
audmode fields, respectively. See the section called “Tuners and Modulators” for more information on tuners. Related to audio
modes struct v4l2_audio also reports if this is a mono or stereo
input, regardless if the source is a tuner.
|struct video_audio||V4L2 Control ID|
To determine which of these controls are supported by a
driver V4L provides the
VIDEO_AUDIO_BALANCE. In the V4L2 API the
VIDIOC_QUERYCTRL ioctl reports if the respective control is
supported. Accordingly the
VIDEO_AUDIO_MUTE flags where replaced by the
All V4L2 controls have a
attribute replacing the struct video_audio
step field. The V4L audio controls are
assumed to range from 0 to 65535 with no particular reset value. The
V4L2 API permits arbitrary limits and defaults which can be queried
VIDIOC_QUERYCTRL ioctl. For general information about
controls see the section called “User Controls”.
The V4L2 ioctls equivalent to
base field of struct
video_buffer remained unchanged, except V4L2
defines a flag to indicate non-destructive overlays instead of a
NULL pointer. All other fields moved into the
fmt substructure of
struct v4l2_framebuffer. The
depth field was
pixelformat. See the section called “RGB Formats” for a list of RGB formats and their
respective color depths.
Instead of the special ioctls
V4L2 uses the general-purpose data format negotiation ioctls
VIDIOC_S_FMT. They take a pointer to a
struct v4l2_format as argument. Here the
member of the
fmt union is used, a
height fields of struct
video_window moved into struct v4l2_rect
w of struct
clipcount fields remained unchanged. Struct
video_clip was renamed to struct v4l2_clip, also
containing a struct v4l2_rect, but the
semantics are still the same.
VIDEO_WINDOW_INTERLACE flag was
dropped. Instead applications must set the
field field to
VIDEO_WINDOW_CHROMAKEY flag moved into
struct v4l2_framebuffer, under the new name
In V4L, storing a bitmap pointer in
clips and setting
VIDEO_CLIP_BITMAP (-1) requests bitmap
clipping, using a fixed size bitmap of 1024 × 625 bits. Struct
v4l2_window has a separate
bitmap pointer field for this purpose and
the bitmap size is determined by
VIDIOCCAPTURE ioctl to enable or
disable overlay was renamed to
To capture only a subsection of the full picture V4L
VIDIOCSCAPTURE ioctls using struct
video_capture. The equivalent V4L2 ioctls are
VIDIOC_S_CROP using struct v4l2_crop, and the related
VIDIOC_CROPCAP ioctl. This is a rather complex matter, see
the section called “Image Cropping, Insertion and Scaling” for details.
height fields moved into struct v4l2_rect
c of struct
decimation field was dropped. In the V4L2
API the scaling factor is implied by the size of the cropping
rectangle and the size of the captured or overlaid image.
VIDEO_CAPTURE_EVEN flags to capture only the
odd or even field, respectively, were replaced by
V4L2_FIELD_BOTTOM in the field named
field of struct v4l2_pix_format and
struct v4l2_window. These structures are used to select a capture or
overlay format with the
There is no essential difference between reading images
from a V4L or V4L2 device using the
read() function, however V4L2
drivers are not required to support this I/O method. Applications can
determine if the function is available with the
ioctl. All V4L2 devices exchanging data with applications must support
To select an image format and size, V4L provides the
ioctls. V4L2 uses the general-purpose data format negotiation ioctls
VIDIOC_S_FMT. They take a pointer to a
struct v4l2_format as argument, here the struct v4l2_pix_format named
pix of its
union is used.
For more information about the V4L2 read interface see the section called “Read/Write”.
Applications can read from V4L devices by mapping buffers in device memory, or more often just buffers allocated in DMA-able system memory, into their address space. This avoids the data copying overhead of the read method. V4L2 supports memory mapping as well, with a few differences.
|The image format must be selected before
buffers are allocated, with the |
Applications cannot change the number of buffers. The it is built into the driver, unless it has a module option to change the number when the driver module is loaded.
Drivers map all buffers as one contiguous
range of memory. The
Buffers are individually mapped. The
offset and size of each buffer can be determined with the
Drivers maintain an incoming and outgoing
For a more in-depth discussion of memory mapping and examples, see the section called “Streaming I/O (Memory Mapping)”.
Originally the V4L API did not specify a raw VBI capture
interface, only the device file
reserved for this purpose. The only driver supporting this interface
was the BTTV driver, de-facto defining the V4L VBI interface. Reading
from the device yields a raw VBI image with the following
|struct v4l2_vbi_format||V4L, BTTV driver|
|sampling_rate||28636363 Hz NTSC (or any other 525-line standard); 35468950 Hz PAL and SECAM (625-line standards)|
|sample_format||V4L2_PIX_FMT_GREY. The last four bytes (a machine endianness integer) contain a frame counter.|
|start||10, 273 NTSC; 22, 335 PAL and SECAM|
[a] Old driver
versions used different values, eventually the custom
Undocumented in the V4L specification, in Linux 2.3 the
VIDIOCSVBIFMT ioctls using struct
vbi_format were added to determine the VBI
image parameters. These ioctls are only partially compatible with the
V4L2 VBI interface specified in the section called “Raw VBI Data Interface”.
offset field does not
sample_format is supposed to be
VIDEO_PALETTE_RAW, equivalent to
V4L2_PIX_FMT_GREY. The remaining fields are
probably equivalent to struct v4l2_vbi_format.
Apparently only the Zoran (ZR 36120) driver implements
these ioctls. The semantics differ from those specified for V4L2 in two
ways. The parameters are reset on
VIDIOCSVBIFMT always returns an EINVAL error code if the
parameters are invalid.
V4L2 has no equivalent of the
VIDIOCGUNIT ioctl. Applications can find the VBI
device associated with a video capture device (or vice versa) by
reopening the device and requesting VBI data. For details see
the section called “Opening and Closing Devices”.
No replacement exists for
and the V4L functions for microcode programming. A new interface for
MPEG compression and playback devices is documented in the section called “Extended Controls”.