Video for Linux Two API Specific…

Draft 0.21

Michael H Schimek

<mschimek@gmx.at>

Bill Dirks

Hans Verkuil

Martin Rubli

Copyright ©
1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 Bill Dirks, Michael
H. Schimek, Hans Verkuil, Martin Rubli

This document is copyrighted © 1999-2006 by Bill Dirks, Michael
H. Schimek, Hans Verkuil and Martin Rubli.

Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation; with no Invariant Sections, with no Front-Cover Texts,
and with no Back-Cover Texts. A copy of the license is included in
the appendix entitled "GNU Free Documentation License".

Programming examples can be used and distributed without
restrictions.

Table of Contents
Introduction
1. Common API
Elements

1.1. Opening and
Closing Devices

1.1.1. Device
Naming
1.1.2. Related
Devices
1.1.3. Multiple
Opens
1.1.4. Shared Data
Streams
1.1.5. Functions

1.2. Querying
Capabilities
1.3. Application
Priority
1.4. Video Inputs and
Outputs
1.5. Audio Inputs and
Outputs
1.6. Tuners and
Modulators

1.6.1. Tuners
1.6.2. Modulators
1.6.3. Radio
Frequency
1.6.4. Satellite
Receivers

1.7. Video
Standards
1.8. User
Controls
1.9. Extended
Controls

1.9.1. Introduction
1.9.2. The Extended
Control API
1.9.3. Enumerating
Extended Controls
1.9.4. Creating Control
Panels
1.9.5. MPEG Control
Reference

1.10. Data
Formats

1.10.1. Data Format
Negotiation
1.10.2. Image Format
Enumeration

1.11. Cropping and
Scaling
1.12. Streaming
Parameters

2. Image
Formats

2.1. Standard Image
Formats
2.2. Colorspaces
2.3. RGB
Formats

Packed RGB
formats -- Packed RGB
formats
V4L2_PIX_FMT_SBGGR8
('BA81') -- Bayer RGB
format.

2.4. YUV
Formats

V4L2_PIX_FMT_GREY
('GREY') -- Grey-scale
image.
V4L2_PIX_FMT_YUYV
('YUYV') -- Packed format
with ½ horizontal chroma resolution, also known as YUV 4:2:2.
V4L2_PIX_FMT_UYVY
('UYVY') -- Variation
of

V4L2_PIX_FMT_YUYV

with different
order of samples in memory.
V4L2_PIX_FMT_Y41P
('Y41P') -- Packed format
with ¼ horizontal chroma resolution, also known as YUV 4:1:1.
V4L2_PIX_FMT_YVU420
('YV12'), V4L2_PIX_FMT_YUV420
('YU12') -- Planar formats
with ½ horizontal and vertical chroma resolution, also known as YUV
4:2:0.
V4L2_PIX_FMT_YVU410
('YVU9'), V4L2_PIX_FMT_YUV410
('YUV9') -- Planar formats
with ¼ horizontal and vertical chroma resolution, also known as YUV
4:1:0.
V4L2_PIX_FMT_YUV422P
('422P') -- Format with ½
horizontal chroma resolution, also known as YUV 4:2:2. Planar
layout as opposed to

V4L2_PIX_FMT_YUYV

.
V4L2_PIX_FMT_YUV411P
('411P') -- Format with ¼
horizontal chroma resolution, also known as YUV 4:1:1. Planar
layout as opposed to

V4L2_PIX_FMT_Y41P

.
V4L2_PIX_FMT_NV12
('NV12'), V4L2_PIX_FMT_NV21
('NV21') -- Formats with ½
horizontal and vertical chroma resolution, also known as YUV 4:2:0.
One luminance and one chrominance plane with alternating chroma
samples as opposed to

V4L2_PIX_FMT_YVU420

.

2.5. Compressed
Formats
2.6. Reserved Format
Identifiers

3. Input/Output

3.1. Read/Write
3.2. Streaming I/O
(Memory Mapping)
3.3. Streaming I/O
(User Pointers)
3.4. Asynchronous
I/O
3.5. Buffers

3.5.1. Timecodes

3.6. Field
Order

4. Device
Types

4.1. Video Capture
Interface

4.1.1. Querying
Capabilities
4.1.2. Supplemental
Functions
4.1.3. Image Format
Negotiation
4.1.4. Reading
Images

4.2. Video Overlay
Interface

4.2.1. Querying
Capabilities
4.2.2. Supplemental
Functions
4.2.3. Setup
4.2.4. Overlay
Window
4.2.5. Enabling
Overlay

4.3. Video Output
Interface

4.3.1. Querying
Capabilities
4.3.2. Supplemental
Functions
4.3.3. Image Format
Negotiation
4.3.4. Writing
Images

4.4. Codec
Interface
4.5. Effect Devices
Interface
4.6. Raw VBI Data
Interface

4.6.1. Querying
Capabilities
4.6.2. Supplemental
Functions
4.6.3. Raw VBI Format
Negotiation
4.6.4. Reading and
writing VBI images

4.7. Sliced VBI Data
Interface

4.7.1. Querying
Capabilities
4.7.2. Supplemental
Functions
4.7.3. Sliced VBI
Format Negotiation
4.7.4. Reading and
writing sliced VBI data

4.8. Teletext
Interface
4.9. Radio
Interface

4.9.1. Querying
Capabilities
4.9.2. Supplemental
Functions
4.9.3. Programming

4.10. RDS
Interface

I. Function
Reference

V4L2
close() -- Close a V4L2
device
V4L2
ioctl() -- Program a V4L2
device
ioctl
VIDIOC_CROPCAP -- Information
about the video cropping and scaling abilities.
ioctl
VIDIOC_ENUMAUDIO -- Enumerate
audio inputs
ioctl
VIDIOC_ENUMAUDOUT -- Enumerate
audio outputs
ioctl
VIDIOC_ENUM_FMT -- Enumerate
image formats
ioctl
VIDIOC_ENUM_FRAMESIZES -- Enumerate
frame sizes
ioctl
VIDIOC_ENUM_FRAMEINTERVALS -- Enumerate
frame intervals
ioctl
VIDIOC_ENUMINPUT -- Enumerate
video inputs
ioctl
VIDIOC_ENUMOUTPUT -- Enumerate
video outputs
ioctl
VIDIOC_ENUMSTD -- Enumerate
supported video standards
ioctl
VIDIOC_G_AUDIO,
VIDIOC_S_AUDIO -- Query or
select the current audio input and its attributes
ioctl
VIDIOC_G_AUDOUT,
VIDIOC_S_AUDOUT -- Query or
select the current audio output
ioctl
VIDIOC_G_MPEGCOMP,
VIDIOC_S_MPEGCOMP -- Get or
set compression parameters
ioctl
VIDIOC_G_CROP,
VIDIOC_S_CROP -- Get or set
the current cropping rectangle
ioctl
VIDIOC_G_CTRL,
VIDIOC_S_CTRL -- Get or set
the value of a control
ioctl
VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS,
VIDIOC_TRY_EXT_CTRLS -- Get
or set the value of several controls, try control values.
ioctl
VIDIOC_G_FBUF,
VIDIOC_S_FBUF -- Get or set
frame buffer overlay parameters.
ioctl
VIDIOC_G_FMT, VIDIOC_S_FMT,
VIDIOC_TRY_FMT -- Get or set
the data format, try a format.
ioctl
VIDIOC_G_FREQUENCY,
VIDIOC_S_FREQUENCY -- Get or
set tuner or modulator radio frequency
ioctl
VIDIOC_G_INPUT,
VIDIOC_S_INPUT -- Query or
select the current video input
ioctl
VIDIOC_G_JPEGCOMP,
VIDIOC_S_JPEGCOMP --
ioctl
VIDIOC_G_MODULATOR,
VIDIOC_S_MODULATOR -- Get or
set modulator attributes
ioctl
VIDIOC_G_OUTPUT,
VIDIOC_S_OUTPUT -- Query or
select the current video output
ioctl
VIDIOC_G_PARM,
VIDIOC_S_PARM -- Get or set
streaming parameters
ioctl
VIDIOC_G_PRIORITY,
VIDIOC_S_PRIORITY -- Query or
request the access priority associated with a file descriptor
ioctl
VIDIOC_G_SLICED_VBI_CAP -- Query
sliced VBI capabilities
ioctl
VIDIOC_G_STD,
VIDIOC_S_STD -- Query or
select the video standard of the current input
ioctl
VIDIOC_G_TUNER,
VIDIOC_S_TUNER -- Get or set
tuner attributes
ioctl
VIDIOC_LOG_STATUS -- Log
driver status information
ioctl
VIDIOC_OVERLAY -- Start or
stop video overlay
ioctl
VIDIOC_QBUF,
VIDIOC_DQBUF -- Exchange a
buffer with the driver
ioctl
VIDIOC_QUERYBUF -- Query the
status of a buffer
ioctl
VIDIOC_QUERYCAP -- Query
device capabilities
ioctl
VIDIOC_QUERYCTRL,
VIDIOC_QUERYMENU -- Enumerate
controls and menu control items
ioctl
VIDIOC_QUERYSTD -- Sense the
video standard received by the current input
ioctl
VIDIOC_REQBUFS -- Initiate
Memory Mapping or User Pointer I/O
ioctl
VIDIOC_STREAMON,
VIDIOC_STREAMOFF -- Start or
stop streaming I/O
V4L2
mmap() -- Map device memory
into application address space
V4L2
munmap() -- Unmap device
memory
V4L2
open() -- Open a V4L2
device
V4L2
poll() -- Wait for some event
on a file descriptor
V4L2
read() -- Read from a V4L2
device
V4L2
select() -- Synchronous I/O
multiplexing
V4L2
write() -- Write to a V4L2
device

5. V4L2 Driver
Programming
6. History

6.1. Differences
between V4L and V4L2

6.1.1. Opening and
Closing Devices
6.1.2. Querying
Capabilities
6.1.3. Video
Sources
6.1.4. Tuning
6.1.5. Image
Properties
6.1.6. Audio
6.1.7. Frame Buffer
Overlay
6.1.8. Cropping
6.1.9. Reading Images,
Memory Mapping
6.1.10. Reading Raw VBI
Data
6.1.11. Miscellaneous

6.2. History of the
V4L2 API

6.2.1. Early
Versions
6.2.2. V4L2 Version
0.16 1999-01-31
6.2.3. V4L2 Version
0.18 1999-03-16
6.2.4. V4L2 Version
0.19 1999-06-05
6.2.5. V4L2 Version
0.20 1999-09-10
6.2.6. V4L2 Version
0.20 incremental changes
6.2.7. V4L2 Version
0.20 2000-11-23
6.2.8. V4L2 Version
0.20 2002-07-25
6.2.9. V4L2 in Linux
2.5.46, 2002-10
6.2.10. V4L2
2003-06-19
6.2.11. V4L2
2003-11-05
6.2.12. V4L2 in Linux
2.6.6, 2004-05-09
6.2.13. V4L2 in Linux
2.6.8
6.2.14. V4L2 spec
erratum 2004-08-01
6.2.15. V4L2 in Linux
2.6.14
6.2.16. V4L2 in Linux
2.6.15
6.2.17. V4L2 spec
erratum 2005-11-27
6.2.18. V4L2 spec
erratum 2006-01-10
6.2.19. V4L2 spec
erratum 2006-02-03
6.2.20. V4L2 spec
erratum 2006-02-04
6.2.21. V4L2 in Linux
2.6.17
6.2.22. V4L2 spec
erratum 2006-09-23 (Draft 0.15)
6.2.23. V4L2 in Linux
2.6.18
6.2.24. V4L2 in Linux
2.6.19
6.2.25. V4L2 spec
erratum 2006-10-12 (Draft 0.17)

6.3. Relation of V4L2
to other Linux multimedia APIs

6.3.1. X Video
Extension
6.3.2. Digital
Video
6.3.3. Audio
Interfaces

A. Video For Linux
Two Header File
B. Video Capture
Example
C. GNU Free
Documentation License

C.1. 0.
PREAMBLE
C.2. 1. APPLICABILITY
AND DEFINITIONS
C.3. 2. VERBATIM
COPYING
C.4. 3. COPYING IN
QUANTITY
C.5. 4.
MODIFICATIONS
C.6. 5. COMBINING
DOCUMENTS
C.7. 6. COLLECTIONS
OF DOCUMENTS
C.8. 7. AGGREGATION
WITH INDEPENDENT WORKS
C.9. 8.
TRANSLATION
C.10. 9.
TERMINATION
C.11. 10. FUTURE
REVISIONS OF THIS LICENSE
C.12. Addendum

Bibliography

List of Tables
1-1. Control
IDs
1-2. MPEG Control
IDs
1-3. CX2341x
Control IDs
2-1. struct

v4l2_pix_format

2-2. enum
v4l2_colorspace
2-1. Packed RGB Image
Formats
2-4. Compressed
Image Formats
2-5. Reserved
Image Formats
3-1. struct

v4l2_buffer

3-2. enum
v4l2_buf_type
3-3. Buffer
Flags
3-4. enum
v4l2_memory
3-5. struct

v4l2_timecode

3-6. Timecode
Types
3-7. Timecode
Flags
3-8. enum
v4l2_field
4-1. struct

v4l2_window

4-2. struct

v4l2_clip

[2]
4-3. struct

v4l2_rect

4-4. struct

v4l2_vbi_format

4-5. Raw VBI Format
Flags
4-6. struct

v4l2_sliced_vbi_format

4-7. Sliced VBI
services
4-8. struct

v4l2_sliced_vbi_data

1. struct

v4l2_cropcap

2. struct

v4l2_rect

1. struct

v4l2_fmtdesc

2. Image Format
Description Flags
1. struct

v4l2_frmsize_discrete

2. struct

v4l2_frmsize_stepwise

3. struct

v4l2_frmsizeenum

4. enum

v4l2_frmsizetypes

1. struct

v4l2_frmival_stepwise

2. struct

v4l2_frmivalenum

3. enum

v4l2_frmivaltypes

1. struct

v4l2_input

2. Input
Types
3. Input Status
Flags
1. struct

v4l2_output

2. Output
Type
1. struct

v4l2_standard

2. struct

v4l2_fract

3. typedef

v4l2_std_id

4. Video Standards
(based on [ITU BT.470])
1. struct

v4l2_audio

2. Audio
Capability Flags
3. Audio Mode
Flags
1. struct

v4l2_audioout

1. struct

v4l2_mpeg_compression

1. struct

v4l2_crop

1. struct

v4l2_control

1. struct

v4l2_ext_control

2. struct

v4l2_ext_controls

3. Control
classes
1. struct

v4l2_framebuffer

2. Frame Buffer
Capability Flags
3. Frame
Buffer Flags
1. struct

v4l2_format

1. struct

v4l2_frequency

1. struct

v4l2_jpegcompression

2. JPEG Markers
Flags
1. struct

v4l2_modulator

2. Modulator
Audio Transmission Flags
1. struct

v4l2_streamparm

2. struct

v4l2_captureparm

3. struct

v4l2_outputparm

4. Streaming
Parameters Capabilites
5. Capture
Parameters Flags
1. enum
v4l2_priority
1. struct

v4l2_sliced_vbi_cap

2. Sliced VBI
services
1. struct

v4l2_tuner

2. enum
v4l2_tuner_type
3. Tuner and
Modulator Capability Flags
4. Tuner
Audio Reception Flags
5. Tuner Audio
Modes
6. Tuner Audio
Matrix
1. struct

v4l2_capability

2. Device
Capabilities Flags
1. struct

v4l2_queryctrl

2. struct

v4l2_querymenu

3. enum
v4l2_ctrl_type
4. Control
Flags
1. struct

v4l2_requestbuffers

6-1. V4L Device
Types, Names and Numbers

List of Figures
1-1. Cropping and
Scaling
3-1. Field Order, Top
Field First Transmitted
3-2. Field Order,
Bottom Field First Transmitted
4-1. Line
synchronization
4-2. ITU-R 525 line
numbering (M/NTSC and M/PAL)
4-3. ITU-R 625 line
numbering

List of Examples
1-1. Information
about the current video input
1-2. Switching to the
first video input
1-3. Information
about the current audio input
1-4. Switching to the
first audio input
1-5. Information
about the current video standard
1-6. Listing the
video standards supported by the current input
1-7. Selecting a new
video standard
1-8. Enumerating all
controls
1-9. Changing
controls
1-10. Resetting the
cropping parameters
1-11. Simple
downscaling
1-12. Current scaling
factor and pixel aspect
2-1. ITU-R Rec.
BT.601 color conversion
2-1.

V4L2_PIX_FMT_BGR24

4 × 4 pixel
image
2-1.

V4L2_PIX_FMT_SBGGR8

4 × 4 pixel
image
2-1.

V4L2_PIX_FMT_GREY

4 × 4 pixel
image
2-1.

V4L2_PIX_FMT_YUYV

4 × 4 pixel
image
2-1.

V4L2_PIX_FMT_UYVY

4 × 4 pixel
image
2-1.

V4L2_PIX_FMT_Y41P

8 × 4 pixel
image
2-1.

V4L2_PIX_FMT_YVU420

4 × 4 pixel
image
2-1.

V4L2_PIX_FMT_YVU410

4 × 4 pixel
image
2-1.

V4L2_PIX_FMT_YUV422P

4 × 4 pixel
image
2-1.

V4L2_PIX_FMT_YUV411P

4 × 4 pixel
image
2-1.

V4L2_PIX_FMT_NV12

4 × 4 pixel
image
3-1. Mapping
buffers
3-2. Initiating
streaming I/O with user pointers