7.1. Differences between V4L and V4L2¶
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 Libv4l Userspace Library supports the conversion of a V4L API system call into a V4L2 one.
7.1.1. Opening and Closing Devices¶
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 Interfaces and below in 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.
|Device Type||File Name||Minor Numbers|
|Video capture and overlay||
|Raw VBI capture||
V4L prohibits (or used to prohibit) multiple opens of a device file. V4L2 drivers may support multiple opens, see Opening and Closing Devices for details and consequences.
V4L drivers respond to V4L2 ioctls with an
EINVAL error code.
7.1.2. Querying Capabilities¶
VIDIOCGCAP ioctl is equivalent to V4L2’s
name field in struct
card in struct
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 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 Video Overlay Interface.|
||Whether clipping the overlaid image is supported, see Video Overlay Interface.|
||Whether overlay overwrites frame buffer memory, see 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 VIDIOC_S_CROP and VIDIOC_S_FMT ioctl, respectively. The driver returns the closest sizes possible. For more information on cropping and scaling see Image Cropping, Insertion and Scaling.|
||Applications can enumerate the supported image formats with the ioctl VIDIOC_ENUM_FMT ioctl to determine if the device supports grey scale capturing only. For more information on image formats see Image Formats.|
||Applications can call the VIDIOC_G_CROP
ioctl to determine if the device supports capturing a subsection
of the full picture (“cropping” in V4L2). If not, the ioctl
||Applications can enumerate the supported image formats with the ioctl VIDIOC_ENUM_FMT ioctl to determine if the device supports MPEG streams.|
audios field was replaced by
V4L2_CAP_AUDIO, indicating if the device has any audio inputs or
outputs. To determine their number applications can enumerate audio
inputs with the VIDIOC_G_AUDIO ioctl. The
audio ioctls are described in Audio Inputs and Outputs.
were removed. Calling the VIDIOC_S_FMT or
VIDIOC_TRY_FMT ioctl with the desired
dimensions returns the closest size possible, taking into account the
current video standard, cropping and scaling limitations.
7.1.3. Video Sources¶
V4L provides the
VIDIOCSCHAN ioctl using struct
video_channel to enumerate the video inputs of a V4L
device. The equivalent V4L2 ioctls are
VIDIOC_S_INPUT using struct
v4l2_input as discussed in Video Inputs and Outputs.
channel field counting inputs was renamed to
video input types were renamed as follows:
tuners field 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
v4l2_input. Enumeration of tuners is
discussed in 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 Audio Inputs and Outputs.
norm field describing the supported video standards was replaced
std. The V4L specification mentions a flag
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 Video Standards for more information.
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 Tuners and Modulators.
tuner field counting tuners was renamed to
index. The fields
rangehigh remained unchanged.
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
mode field to select a different video standard was
replaced by a whole new set of ioctls and structures described in
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).
VIDEO_TUNER_STEREO_ON flag 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 to
VIDIOCSFREQ ioctl to change the tuner
frequency where renamed to
VIDIOC_S_FREQUENCY. They take a pointer
to a struct
v4l2_frequency instead of an
unsigned long integer.
7.1.5. Image Properties¶
V4L2 has no equivalent of the
video_picture. The following fields where
replaced by V4L2 controls accessible with the
ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU,
||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 ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU ioctl. For general information about controls see 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
palette field moved
into the struct
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 Audio Inputs and Outputs.
audio “channel number” field counting audio inputs was renamed
mode field selects one of the
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
audmode fields, respectively. See 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.
The following fields where replaced by V4L2 controls accessible with the ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU, VIDIOC_G_CTRL and VIDIOC_S_CTRL ioctls:
||V4L2 Control ID|
To determine which of these controls are supported by a driver V4L
VIDEO_AUDIO_BALANCE. In the V4L2 API the
ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU ioctl reports if the
respective control is supported. Accordingly the
VIDEO_AUDIO_MUTE flags where replaced by the boolean
All V4L2 controls have a
step attribute replacing the struct
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 with
the ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU ioctl. For general
information about controls see User Controls.
7.1.7. Frame Buffer Overlay¶
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
pointer. All other fields moved into the struct
fmt substructure of
field was replaced by
pixelformat. See RGB Formats for a
list of RGB formats and their respective color depths.
Instead of the special ioctls
uses the general-purpose data format negotiation ioctls
VIDIOC_S_FMT. They take a pointer to a struct
v4l2_format as argument. Here the
fmt union is used, a struct
height fields of struct
video_window moved into struct
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
v4l2_framebuffer, under the new
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
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 defines the
VIDIOCSCAPTURE ioctls using struct
video_capture. The equivalent V4L2 ioctls are
VIDIOC_S_CROP using struct
v4l2_crop, and the related
ioctl VIDIOC_CROPCAP ioctl. This is a rather
complex matter, see Image Cropping, Insertion and Scaling for details.
height fields moved into struct
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_window. These structures are used to
select a capture or overlay format with the
7.1.9. Reading Images, Memory Mapping¶
220.127.116.11. Capturing using the read method¶
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 VIDIOC_QUERYCAP ioctl. All V4L2 devices exchanging data with applications must support the select() and poll() functions.
To select an image format and size, V4L provides the
VIDIOCSWIN ioctls. V4L2 uses the general-purpose data format
negotiation ioctls VIDIOC_G_FMT and
VIDIOC_S_FMT. They take a pointer to a struct
v4l2_format as argument, here the struct
pix of its
fmt union is used.
For more information about the V4L2 read interface see Read/Write.
18.104.22.168. Capturing using memory mapping¶
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 VIDIOC_S_FMT ioctl. When no format is selected the driver may use the last, possibly by another application requested format.|
|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.||The ioctl VIDIOC_REQBUFS ioctl allocates the desired number of buffers, this is a required step in the initialization sequence.|
|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 ioctl VIDIOC_QUERYBUF ioctl.|
|Drivers maintain an incoming and outgoing queue. ioctl VIDIOC_QBUF, VIDIOC_DQBUF enqueues any empty buffer into the incoming queue. Filled buffers are dequeued from the outgoing queue with the VIDIOC_DQBUF ioctl. To wait until filled buffers become available this function, select() or poll() can be used. The ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF ioctl must be called once after enqueuing one or more buffers to start capturing. Its counterpart VIDIOC_STREAMOFF stops capturing and dequeues all buffers from both queues. Applications can query the signal status, if known, with the ioctl VIDIOC_ENUMINPUT ioctl.|
For a more in-depth discussion of memory mapping and examples, see Streaming I/O (Memory Mapping).
7.1.10. Reading Raw VBI Data¶
Originally the V4L API did not specify a raw VBI capture interface, only
the device file
/dev/vbi was 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 parameters:
||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|
|count||16, 16 |
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 Raw VBI Data Interface.
offset field does not exist,
sample_format is supposed to be
VIDEO_PALETTE_RAW, equivalent to
remaining fields are probably equivalent to struct
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 open() and
VIDIOCSVBIFMT always returns an
EINVAL error code if the parameters
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
Opening and Closing Devices.
No replacement exists for
VIDIOCKEY, and the V4L functions for
microcode programming. A new interface for MPEG compression and playback
devices is documented in Extended Controls.
|||According to Documentation/admin-guide/devices.rst these should be symbolic links
|||According to |
|||This is a custom format used by the BTTV driver, not one of the V4L2 standard formats.|
|||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 RGB Formats.|
|||Not to be confused with |
|||V4L explains this as: “RAW capture (BT848)”|
|||Not to be confused with |
|||Old driver versions used different values, eventually the custom