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 Chapter 6, Libv4l Userspace Library supports the conversion of a V4L
API system call into a V4L2 one.

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.

The V4L 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.

Querying Capabilities

The name field in struct
video_capability became
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
introduction.

Applications can enumerate the supported image
formats with the VIDIOC_ENUM_FMT ioctl to determine if the device
supports grey scale capturing only. For more information on image
formats see Chapter 2, Image Formats.

Applications can enumerate the supported image
formats with the VIDIOC_ENUM_FMT ioctl to determine if the device
supports MPEG streams.

VID_TYPE_MPEG_ENCODER

-

See above.

VID_TYPE_MJPEG_DECODER

-

See above.

VID_TYPE_MJPEG_ENCODER

-

See above.

The audios field was replaced
by capabilities flag
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 the section called “Audio Inputs and Outputs”.

The maxwidth,
maxheight,
minwidth and
minheight fields 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.

Unlike the 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 tuner of
struct v4l2_input. Enumeration of tuners is discussed in the section called “Tuners and Modulators”.

The redundant VIDEO_VC_TUNER flag was
dropped. Video inputs associated with a tuner are of type
V4L2_INPUT_TYPE_TUNER. The
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”.

The 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
information.

The tuner field counting tuners
was renamed to index. The fields
name, rangelow
and rangehigh remained unchanged.

The VIDEO_TUNER_PAL,
VIDEO_TUNER_NTSC and
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 mode
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_PAL (0),
VIDEO_MODE_NTSC,
VIDEO_MODE_SECAM and
VIDEO_MODE_AUTO (3). Namely N/PAL Argentina,
M/PAL, N/PAL, and NTSC Japan with numbers 3-6 (sic).

The 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_RDS_ON and
VIDEO_TUNER_MBS_ON flags.

The VIDEO_TUNER_LOW flag was renamed
to V4L2_TUNER_CAP_LOW in the struct v4l2_tunercapability field.

Image Properties

V4L2 has no equivalent of the
VIDIOCGPICT and VIDIOCSPICT
ioctl and struct video_picture. The following
fields where replaced by V4L2 controls accessible with the
VIDIOC_QUERYCTRL, VIDIOC_G_CTRL and VIDIOC_S_CTRL ioctls:

struct video_picture

V4L2 Control ID

brightness

V4L2_CID_BRIGHTNESS

hue

V4L2_CID_HUE

colour

V4L2_CID_SATURATION

contrast

V4L2_CID_CONTRAST

whiteness

V4L2_CID_WHITENESS

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 VIDIOC_QUERYCTRL
ioctl. For general information about controls see the section called “User Controls”.

The 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 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”.

[c] VIDEO_PALETTE_YUV422
and VIDEO_PALETTE_YUYV are the same formats. Some
V4L drivers respond to one, some to the other.

[d] Not to be confused with
V4L2_PIX_FMT_YUV411P, which is a planar
format.

The audio "channel number"
field counting audio inputs was renamed to
index.

On VIDIOCSAUDIO the
mode field selects one
of the VIDEO_SOUND_MONO,
VIDEO_SOUND_STEREO,
VIDEO_SOUND_LANG1 or
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_tunerrxsubchans and
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.

To determine which of these controls are supported by a
driver V4L provides the flagsVIDEO_AUDIO_VOLUME,
VIDEO_AUDIO_BASS,
VIDEO_AUDIO_TREBLE and
VIDEO_AUDIO_BALANCE. In the V4L2 API the
VIDIOC_QUERYCTRL ioctl reports if the respective control is
supported. Accordingly the VIDEO_AUDIO_MUTABLE
and VIDEO_AUDIO_MUTE flags where replaced by the
boolean V4L2_CID_AUDIO_MUTE control.

All V4L2 controls have a step
attribute replacing the struct video_audiostep 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 VIDIOC_QUERYCTRL ioctl. For general information about
controls see the section called “User Controls”.

Frame Buffer Overlay

The V4L2 ioctls equivalent to
VIDIOCGFBUF and VIDIOCSFBUF
are VIDIOC_G_FBUF and VIDIOC_S_FBUF. The
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
struct v4l2_pix_formatfmt substructure of
struct v4l2_framebuffer. The depth field was
replaced by pixelformat. See the section called “RGB Formats” for a list of RGB formats and their
respective color depths.

Instead of the special ioctls
VIDIOCGWIN and VIDIOCSWIN
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 win
member of the fmt union is used, a
struct v4l2_window.

The x,
y, width and
height fields of struct
video_window moved into struct v4l2_rect
substructure w of struct
v4l2_window. The
chromakey,
clips, and
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.

The VIDEO_WINDOW_INTERLACE flag was
dropped. Instead applications must set the
field field to
V4L2_FIELD_ANY or
V4L2_FIELD_INTERLACED. The
VIDEO_WINDOW_CHROMAKEY flag moved into
struct v4l2_framebuffer, under the new name
V4L2_FBUF_FLAG_CHROMAKEY.

In V4L, storing a bitmap pointer in
clips and setting
clipcount to
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 w.width and
w.height.

The VIDIOCCAPTURE ioctl to enable or
disable overlay was renamed to VIDIOC_OVERLAY.

The x,
y, width and
height fields moved into struct v4l2_rect
substructure c of struct
v4l2_crop. The
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.

The VIDEO_CAPTURE_ODD
and VIDEO_CAPTURE_EVEN flags to capture only the
odd or even field, respectively, were replaced by
V4L2_FIELD_TOP and
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 VIDIOC_S_FMT ioctl.

Reading Images, Memory Mapping

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 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
VIDIOCSPICT and 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 v4l2_pix_format named
pix of its fmt
union is used.

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.

V4L

V4L2

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 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 VIDIOCGMBUF ioctl is
available to query the number of buffers, the offset of each buffer
from the start of the virtual file, and the overall amount of memory
used, which can be used as arguments for the mmap()
function.

Buffers are individually mapped. The
offset and size of each buffer can be determined with the
VIDIOC_QUERYBUF ioctl.

The VIDIOCMCAPTURE
ioctl prepares a buffer for capturing. It also determines the image
format for this buffer. The ioctl returns immediately, eventually with
an EAGAIN error code if no video signal had been detected. When the driver
supports more than one buffer applications can call the ioctl multiple
times and thus have multiple outstanding capture
requests.

The VIDIOCSYNC ioctl
suspends execution until a particular buffer has been
filled.

Drivers maintain an incoming and outgoing
queue. VIDIOC_QBUF 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
VIDIOC_STREAMON 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
VIDIOC_ENUMINPUT ioctl.

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:

[a] Old driver
versions used different values, eventually the custom
BTTV_VBISIZE ioctl was added to query the
correct values.

Undocumented in the V4L specification, in Linux 2.3 the
VIDIOCGVBIFMT and
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”.

An offset field does not
exist, 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 open() and
VIDIOCSVBIFMT always returns an EINVAL error code if the
parameters are invalid.

Miscellaneous

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 VIDIOCKEY,
and the V4L functions for microcode programming. A new interface for
MPEG compression and playback devices is documented in the section called “Extended Controls”.