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,
although existing drivers will continue to support V4L applications in
the future, either directly or through the V4L2 compatibility layer in
the videodev kernel module translating ioctls on
the fly. For a transition period not all drivers will support the V4L2
API.
For compatibility reasons the character device file names recommended for V4L2 video capture, overlay, radio, teletext 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 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 |
| 0-63 |
| Radio receiver |
| 64-127 |
| Teletext decoder |
| 192-223 |
| 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. The
compatibility layer in the V4L2 videodev module
can translate V4L ioctl requests to their V4L2 counterpart, however a
V4L2 driver usually needs more preparation to become fully V4L
compatible. This is covered in more detail in Chapter 5, V4L2 Driver Programming.
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.
struct
video_capability
type | struct v4l2_capability
capabilities flags | Purpose |
|---|---|---|
VID_TYPE_CAPTURE | V4L2_CAP_VIDEO_CAPTURE | The video capture interface is supported. |
VID_TYPE_TUNER | V4L2_CAP_TUNER | The device has a tuner or modulator. |
VID_TYPE_TELETEXT | V4L2_CAP_VBI_CAPTURE | The raw VBI capture interface is supported. |
VID_TYPE_OVERLAY | V4L2_CAP_VIDEO_OVERLAY | The video overlay interface is supported. |
VID_TYPE_CHROMAKEY | V4L2_FBUF_CAP_CHROMAKEY in
field capability of
struct v4l2_framebuffer | Whether chromakey overlay is supported. For more information on overlay see the section called “Video Overlay Interface”. |
VID_TYPE_CLIPPING | V4L2_FBUF_CAP_LIST_CLIPPING
and V4L2_FBUF_CAP_BITMAP_CLIPPING in field
capability of struct v4l2_framebuffer | Whether clipping the overlaid image is supported, see the section called “Video Overlay Interface”. |
VID_TYPE_FRAMERAM | V4L2_FBUF_CAP_EXTERNOVERLAY
not set in field
capability of struct v4l2_framebuffer | Whether overlay overwrites frame buffer memory, see the section called “Video Overlay Interface”. |
VID_TYPE_SCALES | - | 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 the section called “Image Cropping, Insertion and Scaling”. |
VID_TYPE_MONOCHROME | - | 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. |
VID_TYPE_SUBCAPTURE | - | 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 returns the EINVAL error code.
For more information on cropping and scaling see the section called “Image Cropping, Insertion and Scaling”. |
VID_TYPE_MPEG_DECODER | - | 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.
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:
struct video_channel
type | struct v4l2_input
type |
|---|---|
VIDEO_TYPE_TV | V4L2_INPUT_TYPE_TUNER |
VIDEO_TYPE_CAMERA | V4L2_INPUT_TYPE_CAMERA |
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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">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 in"constant">VIDIOCSFREQ ioctl to change the tuner frequency
where renamed to VIDIOC_G_FREQUENCY and VIDIOC_S_FREQUENCY. They
take a pointer to a struct