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.
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.
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
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.
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.
Table 7.1. V4L Device Types, Names and Numbers
Device Type
| File Name
| Minor Numbers
|
---|
Video capture and overlay
| /dev/video
and
/dev/bttv0
[
]
,
/dev/video0
to
/dev/video63
| 0-63
|
Radio receiver
| /dev/radio
[
]
,
/dev/radio0
to
/dev/radio63
| 64-127
|
Raw VBI capture
| /dev/vbi
,
/dev/vbi0
to
/dev/vbi31
| 224-255
|
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.
The V4L
VIDIOCGCAP
ioctl is
equivalent to V4L2's
VIDIOC_QUERYCAP
.
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.
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.
V4L provides the
VIDIOCGCHAN
and
VIDIOCSCHAN
ioctl using struct
video_channel
to enumerate
the video inputs of a V4L device. The equivalent V4L2 ioctls
are
VIDIOC_ENUMINPUT
,
VIDIOC_G_INPUT
and
VIDIOC_S_INPUT
using struct
v4l2_input
as discussed in
the section called “Video Inputs and Outputs”
.
The
channel
field counting
inputs was renamed to
index
, the video
input types were renamed as follows:
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 V4L
VIDIOCGTUNER
and
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_G_TUNER
and
VIDIOC_S_TUNER
using struct
v4l2_tuner
. Tuners are
covered in
the section called “Tuners and Modulators”
.
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_tuner
capability
field.
The
VIDIOCGFREQ
and
VIDIOCSFREQ
ioctl to change the tuner frequency
where renamed to
VIDIOC_G_FREQUENCY
and
VIDIOC_S_FREQUENCY
. They
take a pointer to a struct
v4l2_frequency
instead of an unsigned long
integer.
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:
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 explicitely 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
:
V4L2 image formats are defined in
Chapter 2,
Image Formats
. The image format can be selected with the
VIDIOC_S_FMT
ioctl.
The
VIDIOCGAUDIO
and
VIDIOCSAUDIO
ioctl and struct
video_audio
are used to enumerate the
audio inputs of a V4L device. The equivalent V4L2 ioctls are
VIDIOC_G_AUDIO
and
VIDIOC_S_AUDIO
using struct
v4l2_audio
as
discussed in
the section called “Audio Inputs and Outputs”
.
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_tuner
rxsubchans
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.
The following fields where replaced by V4L2 controls
accessible with the
VIDIOC_QUERYCTRL
,
VIDIOC_G_CTRL
and
VIDIOC_S_CTRL
ioctls:
To determine which of these controls are supported by a
driver V4L provides the
flags
VIDEO_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_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
with the
VIDIOC_QUERYCTRL
ioctl. For general information about
controls see
the section called “User Controls”
.
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_format
fmt
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
.
To capture only a subsection of the full picture V4L
defines the
VIDIOCGCAPTURE
and
VIDIOCSCAPTURE
ioctls using struct
video_capture
. The equivalent V4L2 ioctls are
VIDIOC_G_CROP
and
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.
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.
For more information about the V4L2 read interface see
the section called “Read/Write”
.
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.
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
/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:
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.
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”
.