转自：https://www.linuxtv.org/downloads/legacy/video4linux/API/V4L2_API/spec-single/v4l2.html

Video for Linux Two API Specification

Revision 2.6.32

Michael H Schimek

    <mschimek@gmx.at>
  

Bill Dirks

Original author of the V4L2 API and
documentation. 

Hans Verkuil

Designed and documented the VIDIOC_LOG_STATUS ioctl,
the extended control ioctls and major parts of the sliced VBI
API. 

    <hverkuil@xs4all.nl>
  

Martin Rubli

Designed and documented the VIDIOC_ENUM_FRAMESIZES
and VIDIOC_ENUM_FRAMEINTERVALS ioctls. 

Andy Walls

Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV
MPEG stream embedded, sliced VBI data format in this specification.
 

    <awalls@radix.net>
  

Mauro Carvalho Chehab

Documented libv4l, designed and added v4l2grab example,
Remote Controller chapter
 

    <mchehab@redhat.com>
  

Copyright
1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Bill
Dirks, Michael H. Schimek, Hans Verkuil, Martin
Rubli, Andy Walls, Mauro Carvalho Chehab

This document is copyrighted 1999-2009 by Bill
Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls and
Mauro Carvalho Chehab.

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.9.5.1. Generic MPEG Controls

1.9.5.2. CX2341x MPEG Controls

1.9.6. Camera Control Reference

1.9.7. FM Transmitter Control Reference

1.10. Data Formats

1.10.1. Data Format Negotiation

1.10.2. Image Format Enumeration

1.11. Image Cropping, Insertion and Scaling

1.11.1. Cropping Structures

1.11.2. Scaling Adjustments

1.11.3. Examples

1.12. Streaming Parameters

2. Image Formats

2.1. Standard Image Formats

2.2. Colorspaces

2.3. Indexed Format

2.4. RGB Formats

2.5. YUV Formats

2.6. Compressed Formats

2.7. 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. Interfaces

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. Video Output Overlay Interface

4.4.1. Querying Capabilities

4.4.2. Framebuffer

4.4.3. Overlay Window and Scaling

4.4.4. Enabling Overlay

4.5. Codec Interface

4.6. Effect Devices Interface

4.7. Raw VBI Data Interface

4.7.1. Querying Capabilities

4.7.2. Supplemental Functions

4.7.3. Raw VBI Format Negotiation

4.7.4. Reading and writing VBI images

4.8. Sliced VBI Data Interface

4.8.1. Querying Capabilities

4.8.2. Supplemental Functions

4.8.3. Sliced VBI Format Negotiation

4.8.4. Reading and writing sliced VBI data

4.8.5. Sliced VBI Data in MPEG Streams

4.8.5.1. MPEG Stream Embedded, Sliced VBI Data Format: NONE

4.8.5.2. MPEG Stream Embedded, Sliced VBI Data Format: IVTV

4.9. Teletext Interface

4.10. Radio Interface

4.10.1. Querying Capabilities

4.10.2. Supplemental Functions

4.10.3. Programming

4.11. RDS Interface

4.11.1. Querying Capabilities

4.11.2. Reading RDS data

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_DBG_G_CHIP_IDENT — Identify the chips on a TV card

ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER — Read or write hardware registers

ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD — Execute an encoder command

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_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_ENC_INDEX — Get meta data about a compressed video stream

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_S_HW_FREQ_SEEK — Perform a hardware frequency seek

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. Libv4l Userspace Library

6.1. Introduction

6.1.1. libv4lconvert

6.1.2. libv4l1

6.1.3. libv4l2

6.1.3.1. Libv4l device control functions

6.1.4. v4l1compat.so wrapper library

7. Remote Controllers

7.1. Introduction

7.2. Changing default Remote Controller mappings

8. Changes

8.1. Differences between V4L and V4L2

8.1.1. Opening and Closing Devices

8.1.2. Querying Capabilities

8.1.3. Video Sources

8.1.4. Tuning

8.1.5. Image Properties

8.1.6. Audio

8.1.7. Frame Buffer Overlay

8.1.8. Cropping

8.1.9. Reading Images, Memory Mapping

8.1.9.1. Capturing using the read method

8.1.9.2. Capturing using memory mapping

8.1.10. Reading Raw VBI Data

8.1.11. Miscellaneous

8.2. Changes of the V4L2 API

8.2.1. Early Versions

8.2.2. V4L2 Version 0.16 1999-01-31

8.2.3. V4L2 Version 0.18 1999-03-16

8.2.4. V4L2 Version 0.19 1999-06-05

8.2.5. V4L2 Version 0.20 (1999-09-10)

8.2.6. V4L2 Version 0.20 incremental changes

8.2.7. V4L2 Version 0.20 2000-11-23

8.2.8. V4L2 Version 0.20 2002-07-25

8.2.9. V4L2 in Linux 2.5.46, 2002-10

8.2.10. V4L2 2003-06-19

8.2.11. V4L2 2003-11-05

8.2.12. V4L2 in Linux 2.6.6, 2004-05-09

8.2.13. V4L2 in Linux 2.6.8

8.2.14. V4L2 spec erratum 2004-08-01

8.2.15. V4L2 in Linux 2.6.14

8.2.16. V4L2 in Linux 2.6.15

8.2.17. V4L2 spec erratum 2005-11-27

8.2.18. V4L2 spec erratum 2006-01-10

8.2.19. V4L2 spec erratum 2006-02-03

8.2.20. V4L2 spec erratum 2006-02-04

8.2.21. V4L2 in Linux 2.6.17

8.2.22. V4L2 spec erratum 2006-09-23 (Draft 0.15)

8.2.23. V4L2 in Linux 2.6.18

8.2.24. V4L2 in Linux 2.6.19

8.2.25. V4L2 spec erratum 2006-10-12 (Draft 0.17)

8.2.26. V4L2 in Linux 2.6.21

8.2.27. V4L2 in Linux 2.6.22

8.2.28. V4L2 in Linux 2.6.24

8.2.29. V4L2 in Linux 2.6.25

8.2.30. V4L2 in Linux 2.6.26

8.2.31. V4L2 in Linux 2.6.27

8.2.32. V4L2 in Linux 2.6.28

8.2.33. V4L2 in Linux 2.6.29

8.2.34. V4L2 in Linux 2.6.30

8.2.35. V4L2 in Linux 2.6.32

8.3. Relation of V4L2 to other Linux multimedia APIs

8.3.1. X Video Extension

8.3.2. Digital Video

8.3.3. Audio Interfaces

8.4. Experimental API Elements

8.5. Obsolete API Elements

A. Video For Linux Two Header File

B. Video Capture Example

C. Video Grabber example using libv4l

D. GNU Free Documentation License

D.1. 0. PREAMBLE

D.2. 1. APPLICABILITY AND DEFINITIONS

D.3. 2. VERBATIM COPYING

D.4. 3. COPYING IN QUANTITY

D.5. 4. MODIFICATIONS

D.6. 5. COMBINING DOCUMENTS

D.7. 6. COLLECTIONS OF DOCUMENTS

D.8. 7. AGGREGATION WITH INDEPENDENT WORKS

D.9. 8. TRANSLATION

D.10. 9. TERMINATION

D.11. 10. FUTURE REVISIONS OF THIS LICENSE

D.12. Addendum

List of Types

References

List of Figures

1.1. Image Cropping, Insertion 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 Tables

1.1. Control IDs

1.2. MPEG Control IDs

1.3. CX2341x Control IDs

1.4. Camera Control IDs

1.5. FM_TX Control IDs

2.1. struct v4l2_pix_format

2.2. enum v4l2_colorspace

2.3. Indexed Image Format

2.4. Packed RGB Image Formats

2.5. Packed RGB Image Formats (corrected)

2.6. Packed YUV Image Formats

2.7. Compressed Image Formats

2.8. 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

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

4.9. struct v4l2_mpeg_vbi_fmt_ivtv

4.10. Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv
magic field

4.11. struct v4l2_mpeg_vbi_itv0

4.12. struct v4l2_mpeg_vbi_ITV0

4.13. struct v4l2_mpeg_vbi_itv0_line

4.14. Line Identifiers for struct
v4l2_mpeg_vbi_itv0_line id
field

4.15. struct
v4l2_rds_data

4.16. Block description

4.17. Block defines

39. struct v4l2_cropcap

40. struct v4l2_rect

41. struct v4l2_dbg_match

42. struct v4l2_dbg_chip_ident

43. Chip Match Types

44. Chip Identifiers

45. struct v4l2_dbg_match

46. struct v4l2_dbg_register

47. Chip Match Types

48. struct v4l2_encoder_cmd

49. Encoder Commands

50. Encoder Command Flags

51. struct v4l2_fmtdesc

52. Image Format Description Flags

53. struct v4l2_frmsize_discrete

54. struct v4l2_frmsize_stepwise

55. struct v4l2_frmsizeenum

56. enum v4l2_frmsizetypes

57. struct v4l2_frmival_stepwise

58. struct v4l2_frmivalenum

59. enum v4l2_frmivaltypes

60. struct v4l2_input

61. Input Types

62. Input Status Flags

63. struct v4l2_output

64. Output Type

65. struct v4l2_standard

66. struct v4l2_fract

67. typedef v4l2_std_id

68. Video Standards (based on [])

69. struct v4l2_audio

70. Audio Capability Flags

71. Audio Mode Flags

72. struct v4l2_audioout

73. struct v4l2_crop

74. struct v4l2_control

75. struct v4l2_enc_idx

76. struct v4l2_enc_idx_entry

77. Index Entry Flags

78. struct v4l2_ext_control

79. struct v4l2_ext_controls

80. Control classes

81. struct v4l2_framebuffer

82. Frame Buffer Capability Flags

83. Frame Buffer Flags

84. struct v4l2_format

85. struct v4l2_frequency

86. struct v4l2_jpegcompression

87. JPEG Markers Flags

88. struct v4l2_modulator

89. Modulator Audio Transmission Flags

90. struct v4l2_streamparm

91. struct v4l2_captureparm

92. struct v4l2_outputparm

93. Streaming Parameters Capabilites

94. Capture Parameters Flags

95. enum v4l2_priority

96. struct v4l2_sliced_vbi_cap

97. Sliced VBI services

98. struct v4l2_tuner

99. enum v4l2_tuner_type

100. Tuner and Modulator Capability Flags

101. Tuner Audio Reception Flags

102. Tuner Audio Modes

103. Tuner Audio Matrix

104. struct v4l2_capability

105. Device Capabilities Flags

106. struct v4l2_queryctrl

107. struct v4l2_querymenu

108. enum v4l2_ctrl_type

109. Control Flags

110. struct v4l2_requestbuffers

111. struct v4l2_hw_freq_seek

7.1. IR default keymapping

7.2. Notes

8.1. V4L Device Types, Names and Numbers

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. Selecting an output area

1.13. Current scaling factor and pixel aspect

2.1. ITU-R Rec. BT.601 color conversion

2.2. V4L2_PIX_FMT_BGR24 4 × 4 pixel
image

2.3. V4L2_PIX_FMT_SBGGR8 4 × 4
pixel image

2.4. V4L2_PIX_FMT_SGBRG8 4 × 4
pixel image

2.5. V4L2_PIX_FMT_SGRBG8 4 ×
4 pixel image

2.6. V4L2_PIX_FMT_SBGGR16 4 × 4
pixel image

2.7. V4L2_PIX_FMT_GREY 4 × 4
pixel image

2.8. V4L2_PIX_FMT_Y16 4 × 4
pixel image

2.9. V4L2_PIX_FMT_YUYV 4 × 4
pixel image

2.10. V4L2_PIX_FMT_UYVY 4 × 4
pixel image

2.11. V4L2_PIX_FMT_YVYU 4 × 4
pixel image

2.12. V4L2_PIX_FMT_VYUY 4 × 4
pixel image

2.13. V4L2_PIX_FMT_Y41P 8 × 4
pixel image

2.14. V4L2_PIX_FMT_YVU420 4 × 4
pixel image

2.15. V4L2_PIX_FMT_YVU410 4 × 4
pixel image

2.16. V4L2_PIX_FMT_YUV422P 4 × 4
pixel image

2.17. V4L2_PIX_FMT_YUV411P 4 × 4
pixel image

2.18. V4L2_PIX_FMT_NV12 4 × 4
pixel image

2.19. V4L2_PIX_FMT_NV16 4 × 4
pixel image

3.1. Mapping buffers

3.2. Initiating streaming I/O with user pointers

4.1. Finding a framebuffer device for OSD

Introduction

Video For Linux Two is the second version of the Video For
Linux API, a kernel interface for analog radio and video capture and
output drivers.

Early drivers used ad-hoc interfaces. These were replaced in
Linux 2.2 by Alan Cox' V4L API, based on the interface of the bttv
driver. In 1999 Bill Dirks started the development of V4L2 to fix some
shortcomings of V4L and to support a wider range of devices. The API
was revised again in 2002 prior to its inclusion in Linux 2.5/2.6, and
work continues on improvements and additions while maintaining
compatibility with existing drivers and applications. In 2006/2007
efforts began on FreeBSD drivers with a V4L2 interface.

This book documents the V4L2 API. Intended audience are
driver and application writers.

If you have questions or ideas regarding the API, please
write to the linux-media mailing list: https://linuxtv.org/lists.php.

The latest version of this document and the DocBook SGML
sources are part of the https://linuxtv.org/repo/ repository. The online version is
available here: https://linuxtv.org/downloads/video4linux/API/V4L2_API.

Chapter 1. Common API Elements

Table of Contents

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.9.5.1. Generic MPEG Controls

1.9.5.2. CX2341x MPEG Controls

1.9.6. Camera Control Reference

1.9.7. FM Transmitter Control Reference

1.10. Data Formats

1.10.1. Data Format Negotiation

1.10.2. Image Format Enumeration

1.11. Image Cropping, Insertion and Scaling

1.11.1. Cropping Structures

1.11.2. Scaling Adjustments

1.11.3. Examples

1.12. Streaming Parameters

Programming a V4L2 device consists of these
steps:

• Opening the device
• Changing device properties, selecting a video and audio
  input, video standard, picture brightness a. o.
• Negotiating a data format
• Negotiating an input/output method
• The actual input/output loop
• Closing the device

In practice most steps are optional and can be executed out of
order. It depends on the V4L2 device type, you can read about the
details in Chapter 4, Interfaces. In this chapter we will discuss
the basic concepts applicable to all devices.

1.1. Opening and Closing Devices

1.1.1. Device Naming

V4L2 drivers are implemented as kernel modules, loaded
manually by the system administrator or automatically when a device is
first opened. The driver modules plug into the "videodev" kernel
module. It provides helper functions and a common application
interface specified in this document.

Each driver thus loaded registers one or more device nodes
with major number 81 and a minor number between 0 and 255. Assigning
minor numbers to V4L2 devices is entirely up to the system administrator,
this is primarily intended to solve conflicts between devices.^[1] The module options to select minor numbers are named
after the device special file with a "_nr" suffix. For example "video_nr"
for /dev/video video capture devices. The number is
an offset to the base minor number associated with the device type.
^[2] When the driver supports multiple devices of the same
type more than one minor number can be assigned, separated by commas:

> insmod mydriver.o video_nr=0,1 radio_nr=0,1

In /etc/modules.conf this may be written as:

alias char-major-81-0 mydriver
alias char-major-81-1 mydriver
alias char-major-81-64 mydriver              

options mydriver video_nr=0,1 radio_nr=0,1   

	When an application attempts to open a device special file with major number 81 and minor number 0, 1, or 64, load "mydriver" (and the "videodev" module it depends upon).
	Register the first two video capture devices with minor number 0 and 1 (base number is 0), the first two radio device with minor number 64 and 65 (base 64).

When no minor number is given as module option the driver supplies a default. Chapter 4, Interfaces recommends the base minor numbers to be used for the various device types. Obviously minor numbers must be unique. When the number is already in use the offending device will not be registered.

By convention system administrators create various character device special files with these major and minor numbers in the /dev directory. The names recomended for the different V4L2 device types are listed in Chapter 4, Interfaces.

The creation of character special files (with mknod) is a privileged operation and devices cannot be opened by major and minor number. That means applications cannot reliable scan for loaded or installed drivers. The user must enter a device name, or the application can try the conventional device names.

Under the device filesystem (devfs) the minor number options are ignored. V4L2 drivers (or by proxy the "videodev" module) automatically create the required device files in the /dev/v4l directory using the conventional device names above.

1.1.2. Related Devices

Devices can support several related functions. For example video capturing, video overlay and VBI capturing are related because these functions share, amongst other, the same video input and tuner frequency. V4L and earlier versions of V4L2 used the same device name and minor number for video capturing and overlay, but different ones for VBI. Experience showed this approach has several problems^[3], and to make things worse the V4L videodev module used to prohibit multiple opens of a device.

As a remedy the present version of the V4L2 API relaxed the concept of device types with specific names and minor numbers. For compatibility with old applications drivers must still register different minor numbers to assign a default function to the device. But if related functions are supported by the driver they must be available under all registered minor numbers. The desired function can be selected after opening the device as described in Chapter 4, Interfaces.

Imagine a driver supporting video capturing, video overlay, raw VBI capturing, and FM radio reception. It registers three devices with minor number 0, 64 and 224 (this numbering scheme is inherited from the V4L API). Regardless if /dev/video (81, 0) or /dev/vbi (81, 224) is opened the application can select any one of the video capturing, overlay or VBI capturing functions. Without programming (e. g. reading from the device with dd or cat) /dev/video captures video images, while /dev/vbi captures raw VBI data. /dev/radio (81, 64) is invariable a radio device, unrelated to the video functions. Being unrelated does not imply the devices can be used at the same time, however. The open() function may very well return an EBUSY error code.

Besides video input or output the hardware may also support audio sampling or playback. If so, these functions are implemented as OSS or ALSA PCM devices and eventually OSS or ALSA audio mixer. The V4L2 API makes no provisions yet to find these related devices. If you have an idea please write to the linux-media mailing list: https://linuxtv.org/lists.php.

1.1.3. Multiple Opens

In general, V4L2 devices can be opened more than once. When this is supported by the driver, users can for example start a "panel" application to change controls like brightness or audio volume, while another application captures video and audio. In other words, panel applications are comparable to an OSS or ALSA audio mixer application. When a device supports multiple functions like capturing and overlay simultaneously, multiple opens allow concurrent use of the device by forked processes or specialized applications.

Multiple opens are optional, although drivers should permit at least concurrent accesses without data exchange, i. e. panel applications. This implies open() can return an EBUSY error code when the device is already in use, as well as ioctl() functions initiating data exchange (namely the VIDIOC_S_FMT ioctl), and the read() and write() functions.

Mere opening a V4L2 device does not grant exclusive access.^[4] Initiating data exchange however assigns the right to read or write the requested type of data, and to change related properties, to this file descriptor. Applications can request additional access privileges using the priority mechanism described in Section 1.3, “Application Priority”.

1.1.4. Shared Data Streams

V4L2 drivers should not support multiple applications reading or writing the same data stream on a device by copying buffers, time multiplexing or similar means. This is better handled by a proxy application in user space. When the driver supports stream sharing anyway it must be implemented transparently. The V4L2 API does not specify how conflicts are solved.

1.1.5. Functions

To open and close V4L2 devices applications use the open() and close() function, respectively. Devices are programmed using the ioctl() function as explained in the following sections.

1.2. Querying Capabilities

Because V4L2 covers a wide variety of devices not all aspects of the API are equally applicable to all types of devices. Furthermore devices of the same type have different capabilities and this specification permits the omission of a few complicated and less important parts of the API.

The VIDIOC_QUERYCAP ioctl is available to check if the kernel device is compatible with this specification, and to query the functions and I/O methods supported by the device. Other features can be queried by calling the respective ioctl, for example VIDIOC_ENUMINPUT to learn about the number, types and names of video connectors on the device. Although abstraction is a major objective of this API, the ioctl also allows driver specific applications to reliable identify the driver.

All V4L2 drivers must support VIDIOC_QUERYCAP. Applications should always call this ioctl after opening the device.

1.3. Application Priority

When multiple applications share a device it may be desirable to assign them different priorities. Contrary to the traditional "rm -rf /" school of thought a video recording application could for example block other applications from changing video controls or switching the current TV channel. Another objective is to permit low priority applications working in background, which can be preempted by user controlled applications and automatically regain control of the device at a later time.

Since these features cannot be implemented entirely in user space V4L2 defines the VIDIOC_G_PRIORITY and VIDIOC_S_PRIORITY ioctls to request and query the access priority associate with a file descriptor. Opening a device assigns a medium priority, compatible with earlier versions of V4L2 and drivers not supporting these ioctls. Applications requiring a different priority will usually call VIDIOC_S_PRIORITY after verifying the device with the VIDIOC_QUERYCAP ioctl.

Ioctls changing driver properties, such as VIDIOC_S_INPUT, return an EBUSY error code after another application obtained higher priority. An event mechanism to notify applications about asynchronous property changes has been proposed but not added yet.

1.4. Video Inputs and Outputs

Video inputs and outputs are physical connectors of a device. These can be for example RF connectors (antenna/cable), CVBS a.k.a. Composite Video, S-Video or RGB connectors. Only video and VBI capture devices have inputs, output devices have outputs, at least one each. Radio devices have no video inputs or outputs.

To learn about the number and attributes of the available inputs and outputs applications can enumerate them with the VIDIOC_ENUMINPUT and VIDIOC_ENUMOUTPUT ioctl, respectively. The struct v4l2_input returned by the VIDIOC_ENUMINPUT ioctl also contains signal status information applicable when the current video input is queried.

The VIDIOC_G_INPUT and VIDIOC_G_OUTPUT ioctl return the index of the current video input or output. To select a different input or output applications call the VIDIOC_S_INPUT and VIDIOC_S_OUTPUT ioctl. Drivers must implement all the input ioctls when the device has one or more inputs, all the output ioctls when the device has one or more outputs.

Example 1.1. Information about the current video input

struct v4l2_input input;
int index;

if (-1 == ioctl (fd, VIDIOC_G_INPUT, &index)) {
	perror ("VIDIOC_G_INPUT");
	exit (EXIT_FAILURE);
}

memset (&input, 0, sizeof (input));
input.index = index;

if (-1 == ioctl (fd, VIDIOC_ENUMINPUT, &input)) {
	perror ("VIDIOC_ENUMINPUT");
	exit (EXIT_FAILURE);
}

printf ("Current input: %s\n", input.name);
      

Example 1.2. Switching to the first video input

int index;

index = 0;

if (-1 == ioctl (fd, VIDIOC_S_INPUT, &index)) {
	perror ("VIDIOC_S_INPUT");
	exit (EXIT_FAILURE);
}
      

1.5. Audio Inputs and Outputs

Audio inputs and outputs are physical connectors of a device. Video capture devices have inputs, output devices have outputs, zero or more each. Radio devices have no audio inputs or outputs. They have exactly one tuner which in fact is an audio source, but this API associates tuners with video inputs or outputs only, and radio devices have none of these.^[5] A connector on a TV card to loop back the received audio signal to a sound card is not considered an audio output.

Audio and video inputs and outputs are associated. Selecting a video source also selects an audio source. This is most evident when the video and audio source is a tuner. Further audio connectors can combine with more than one video input or output. Assumed two composite video inputs and two audio inputs exist, there may be up to four valid combinations. The relation of video and audio connectors is defined in the audioset field of the respective struct v4l2_input or struct v4l2_output, where each bit represents the index number, starting at zero, of one audio input or output.

To learn about the number and attributes of the available inputs and outputs applications can enumerate them with the VIDIOC_ENUMAUDIO and VIDIOC_ENUMAUDOUT ioctl, respectively. The struct v4l2_audio returned by the VIDIOC_ENUMAUDIO ioctl also contains signal status information applicable when the current audio input is queried.

The VIDIOC_G_AUDIO and VIDIOC_G_AUDOUT ioctl report the current audio input and output, respectively. Note that, unlike VIDIOC_G_INPUT and VIDIOC_G_OUTPUT these ioctls return a structure as VIDIOC_ENUMAUDIO and VIDIOC_ENUMAUDOUT do, not just an index.

To select an audio input and change its properties applications call the VIDIOC_S_AUDIO ioctl. To select an audio output (which presently has no changeable properties) applications call the VIDIOC_S_AUDOUT ioctl.

Drivers must implement all input ioctls when the device has one or more inputs, all output ioctls when the device has one or more outputs. When the device has any audio inputs or outputs the driver must set the V4L2_CAP_AUDIO flag in the struct v4l2_capability returned by the VIDIOC_QUERYCAP ioctl.

Example 1.3. Information about the current audio input

struct v4l2_audio audio;

memset (&audio, 0, sizeof (audio));

if (-1 == ioctl (fd, VIDIOC_G_AUDIO, &audio)) {
	perror ("VIDIOC_G_AUDIO");
	exit (EXIT_FAILURE);
}

printf ("Current input: %s\n", audio.name);
      

Example 1.4. Switching to the first audio input

struct v4l2_audio audio;

memset (&audio, 0, sizeof (audio)); /* clear audio.mode, audio.reserved */

audio.index = 0;

if (-1 == ioctl (fd, VIDIOC_S_AUDIO, &audio)) {
	perror ("VIDIOC_S_AUDIO");
	exit (EXIT_FAILURE);
}
      

1.6. Tuners and Modulators

1.6.1. Tuners

Video input devices can have one or more tuners demodulating a RF signal. Each tuner is associated with one or more video inputs, depending on the number of RF connectors on the tuner. The type field of the respective struct v4l2_input returned by the VIDIOC_ENUMINPUT ioctl is set to V4L2_INPUT_TYPE_TUNER and its tuner field contains the index number of the tuner.

Radio devices have exactly one tuner with index zero, no video inputs.

To query and change tuner properties applications use the VIDIOC_G_TUNER and VIDIOC_S_TUNER ioctl, respectively. The struct v4l2_tuner returned by VIDIOC_G_TUNER also contains signal status information applicable when the tuner of the current video input, or a radio tuner is queried. Note that VIDIOC_S_TUNER does not switch the current tuner, when there is more than one at all. The tuner is solely determined by the current video input. Drivers must support both ioctls and set the V4L2_CAP_TUNER flag in the struct v4l2_capability returned by the VIDIOC_QUERYCAP ioctl when the device has one or more tuners.

1.6.2. Modulators

Video output devices can have one or more modulators, uh, modulating a video signal for radiation or connection to the antenna input of a TV set or video recorder. Each modulator is associated with one or more video outputs, depending on the number of RF connectors on the modulator. The type field of the respective struct v4l2_output returned by the VIDIOC_ENUMOUTPUT ioctl is set to V4L2_OUTPUT_TYPE_MODULATOR and its modulator field contains the index number of the modulator. This specification does not define radio output devices.

To query and change modulator properties applications use the VIDIOC_G_MODULATOR and VIDIOC_S_MODULATOR ioctl. Note that VIDIOC_S_MODULATOR does not switch the current modulator, when there is more than one at all. The modulator is solely determined by the current video output. Drivers must support both ioctls and set the V4L2_CAP_MODULATOR flag in the struct v4l2_capability returned by the VIDIOC_QUERYCAP ioctl when the device has one or more modulators.

1.6.3. Radio Frequency

To get and set the tuner or modulator radio frequency applications use the VIDIOC_G_FREQUENCY and VIDIOC_S_FREQUENCY ioctl which both take a pointer to a struct v4l2_frequency. These ioctls are used for TV and radio devices alike. Drivers must support both ioctls when the tuner or modulator ioctls are supported, or when the device is a radio device.

1.6.4. Satellite Receivers

To be discussed. See also proposals by Peter Schlaf, video4linux-list@redhat.com on 23 Oct 2002, subject: "Re: [V4L] Re: v4l2 api".

1.7. Video Standards

Video devices typically support one or more different video standards or variations of standards. Each video input and output may support another set of standards. This set is reported by the std field of struct v4l2_input and struct v4l2_output returned by the VIDIOC_ENUMINPUT and VIDIOC_ENUMOUTPUT ioctl, respectively.

V4L2 defines one bit for each analog video standard currently in use worldwide, and sets aside bits for driver defined standards, e. g. hybrid standards to watch NTSC video tapes on PAL TVs and vice versa. Applications can use the predefined bits to select a particular standard, although presenting the user a menu of supported standards is preferred. To enumerate and query the attributes of the supported standards applications use the VIDIOC_ENUMSTD ioctl.

Many of the defined standards are actually just variations of a few major standards. The hardware may in fact not distinguish between them, or do so internal and switch automatically. Therefore enumerated standards also contain sets of one or more standard bits.

Assume a hypothetic tuner capable of demodulating B/PAL, G/PAL and I/PAL signals. The first enumerated standard is a set of B and G/PAL, switched automatically depending on the selected radio frequency in UHF or VHF band. Enumeration gives a "PAL-B/G" or "PAL-I" choice. Similar a Composite input may collapse standards, enumerating "PAL-B/G/H/I", "NTSC-M" and "SECAM-D/K".^[6]

To query and select the standard used by the current video input or output applications call the VIDIOC_G_STD and VIDIOC_S_STD ioctl, respectively. The received standard can be sensed with the VIDIOC_QUERYSTD ioctl. Note parameter of all these ioctls is a pointer to a v4l2_std_id type (a standard set), not an index into the standard enumeration.^[7] Drivers must implement all video standard ioctls when the device has one or more video inputs or outputs.

Special rules apply to USB cameras where the notion of video standards makes little sense. More generally any capture device, output devices accordingly, which is

• incapable of capturing fields or frames at the nominal rate of the video standard, or
• where timestamps refer to the instant the field or frame was received by the driver, not the capture time, or
• where sequence numbers refer to the frames received by the driver, not the captured frames.

Here the driver shall set the std field of struct v4l2_input and struct v4l2_output to zero, the VIDIOC_G_STD, VIDIOC_S_STD, VIDIOC_QUERYSTD and VIDIOC_ENUMSTD ioctls shall return the EINVAL error code.^[8]

Example 1.5. Information about the current video standard

v4l2_std_id std_id;
struct v4l2_standard standard;

if (-1 == ioctl (fd, VIDIOC_G_STD, &std_id)) {
	/* Note when VIDIOC_ENUMSTD always returns EINVAL this
	   is no video device or it falls under the USB exception,
	   and VIDIOC_G_STD returning EINVAL is no error. */

	perror ("VIDIOC_G_STD");
	exit (EXIT_FAILURE);
}

memset (&standard, 0, sizeof (standard));
standard.index = 0;

while (0 == ioctl (fd, VIDIOC_ENUMSTD, &standard)) {
	if (standard.id & std_id) {
	       printf ("Current video standard: %s\n", standard.name);
	       exit (EXIT_SUCCESS);
	}

	standard.index++;
}

/* EINVAL indicates the end of the enumeration, which cannot be
   empty unless this device falls under the USB exception. */

if (errno == EINVAL || standard.index == 0) {
	perror ("VIDIOC_ENUMSTD");
	exit (EXIT_FAILURE);
}
      

Example 1.6. Listing the video standards supported by the current
input

struct v4l2_input input;
struct v4l2_standard standard;

memset (&input, 0, sizeof (input));

if (-1 == ioctl (fd, VIDIOC_G_INPUT, &input.index)) {
	perror ("VIDIOC_G_INPUT");
	exit (EXIT_FAILURE);
}

if (-1 == ioctl (fd, VIDIOC_ENUMINPUT, &input)) {
	perror ("VIDIOC_ENUM_INPUT");
	exit (EXIT_FAILURE);
}

printf ("Current input %s supports:\n", input.name);

memset (&standard, 0, sizeof (standard));
standard.index = 0;

while (0 == ioctl (fd, VIDIOC_ENUMSTD, &standard)) {
	if (standard.id & input.std)
		printf ("%s\n", standard.name);

	standard.index++;
}

/* EINVAL indicates the end of the enumeration, which cannot be
   empty unless this device falls under the USB exception. */

if (errno != EINVAL || standard.index == 0) {
	perror ("VIDIOC_ENUMSTD");
	exit (EXIT_FAILURE);
}
      

Example 1.7. Selecting a new video standard

struct v4l2_input input;
v4l2_std_id std_id;

memset (&input, 0, sizeof (input));

if (-1 == ioctl (fd, VIDIOC_G_INPUT, &input.index)) {
	perror ("VIDIOC_G_INPUT");
	exit (EXIT_FAILURE);
}

if (-1 == ioctl (fd, VIDIOC_ENUMINPUT, &input)) {
	perror ("VIDIOC_ENUM_INPUT");
	exit (EXIT_FAILURE);
}

if (0 == (input.std & V4L2_STD_PAL_BG)) {
	fprintf (stderr, "Oops. B/G PAL is not supported.\n");
	exit (EXIT_FAILURE);
}

/* Note this is also supposed to work when only B
   or G/PAL is supported. */

std_id = V4L2_STD_PAL_BG;

if (-1 == ioctl (fd, VIDIOC_S_STD, &std_id)) {
	perror ("VIDIOC_S_STD");
	exit (EXIT_FAILURE);
}
      

1.8. User Controls

Devices typically have a number of user-settable controls such as brightness, saturation and so on, which would be presented to the user on a graphical user interface. But, different devices will have different controls available, and furthermore, the range of possible values, and the default value will vary from device to device. The control ioctls provide the information and a mechanism to create a nice user interface for these controls that will work correctly with any device.

All controls are accessed using an ID value. V4L2 defines several IDs for specific purposes. Drivers can also implement their own custom controls using V4L2_CID_PRIVATE_BASE and higher values. The pre-defined control IDs have the prefix V4L2_CID_, and are listed in Table 1.1, “Control IDs”. The ID is used when querying the attributes of a control, and when getting or setting the current value.

Generally applications should present controls to the user without assumptions about their purpose. Each control comes with a name string the user is supposed to understand. When the purpose is non-intuitive the driver writer should provide a user manual, a user interface plug-in or a driver specific panel application. Predefined IDs were introduced to change a few controls programmatically, for example to mute a device during a channel switch.

Drivers may enumerate different controls after switching the current video input or output, tuner or modulator, or audio input or output. Different in the sense of other bounds, another default and current value, step size or other menu items. A control with a certain custom ID can also change name and type.^[9] Control values are stored globally, they do not change when switching except to stay within the reported bounds. They also do not change e. g. when the device is opened or closed, when the tuner radio frequency is changed or generally never without application request. Since V4L2 specifies no event mechanism, panel applications intended to cooperate with other panel applications (be they built into a larger application, as a TV viewer) may need to regularly poll control values to update their user interface.^[10]

Table 1.1. Control IDs

Applications can enumerate the available controls with the
VIDIOC_QUERYCTRL and VIDIOC_QUERYMENU ioctls, get and set a
control value with the VIDIOC_G_CTRL and VIDIOC_S_CTRL ioctls.
Drivers must implement VIDIOC_QUERYCTRL,
VIDIOC_G_CTRL and
VIDIOC_S_CTRL when the device has one or more
controls, VIDIOC_QUERYMENU when it has one or
more menu type controls.

Example 1.8. Enumerating all controls

struct v4l2_queryctrl queryctrl;
struct v4l2_querymenu querymenu;

static void
enumerate_menu (void)
{
	printf ("  Menu items:\n");

	memset (&querymenu, 0, sizeof (querymenu));
	querymenu.id = queryctrl.id;

	for (querymenu.index = queryctrl.minimum;
	     querymenu.index <= queryctrl.maximum;
	      querymenu.index++) {
		if (0 == ioctl (fd, VIDIOC_QUERYMENU, &querymenu)) {
			printf ("  %s\n", querymenu.name);
		} else {
			perror ("VIDIOC_QUERYMENU");
			exit (EXIT_FAILURE);
		}
	}
}

memset (&queryctrl, 0, sizeof (queryctrl));

for (queryctrl.id = V4L2_CID_BASE;
     queryctrl.id < V4L2_CID_LASTP1;
     queryctrl.id++) {
	if (0 == ioctl (fd, VIDIOC_QUERYCTRL, &queryctrl)) {
		if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
			continue;

		printf ("Control %s\n", queryctrl.name);

		if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
			enumerate_menu ();
	} else {
		if (errno == EINVAL)
			continue;

		perror ("VIDIOC_QUERYCTRL");
		exit (EXIT_FAILURE);
	}
}

for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
     queryctrl.id++) {
	if (0 == ioctl (fd, VIDIOC_QUERYCTRL, &queryctrl)) {
		if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
			continue;

		printf ("Control %s\n", queryctrl.name);

		if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
			enumerate_menu ();
	} else {
		if (errno == EINVAL)
			break;

		perror ("VIDIOC_QUERYCTRL");
		exit (EXIT_FAILURE);
	}
}

Example 1.9. Changing controls

struct v4l2_queryctrl queryctrl;
struct v4l2_control control;

memset (&queryctrl, 0, sizeof (queryctrl));
queryctrl.id = V4L2_CID_BRIGHTNESS;

if (-1 == ioctl (fd, VIDIOC_QUERYCTRL, &queryctrl)) {
	if (errno != EINVAL) {
		perror ("VIDIOC_QUERYCTRL");
		exit (EXIT_FAILURE);
	} else {
		printf ("V4L2_CID_BRIGHTNESS is not supported\n");
	}
} else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) {
	printf ("V4L2_CID_BRIGHTNESS is not supported\n");
} else {
	memset (&control, 0, sizeof (control));
	control.id = V4L2_CID_BRIGHTNESS;
	control.value = queryctrl.default_value;

	if (-1 == ioctl (fd, VIDIOC_S_CTRL, &control)) {
		perror ("VIDIOC_S_CTRL");
		exit (EXIT_FAILURE);
	}
}

memset (&control, 0, sizeof (control));
control.id = V4L2_CID_CONTRAST;

if (0 == ioctl (fd, VIDIOC_G_CTRL, &control)) {
	control.value += 1;

	/* The driver may clamp the value or return ERANGE, ignored here */

	if (-1 == ioctl (fd, VIDIOC_S_CTRL, &control)
	    && errno != ERANGE) {
		perror ("VIDIOC_S_CTRL");
		exit (EXIT_FAILURE);
	}
/* Ignore if V4L2_CID_CONTRAST is unsupported */
} else if (errno != EINVAL) {
	perror ("VIDIOC_G_CTRL");
	exit (EXIT_FAILURE);
}

control.id = V4L2_CID_AUDIO_MUTE;
control.value = TRUE; /* silence */

/* Errors ignored */
ioctl (fd, VIDIOC_S_CTRL, &control);

1.9. Extended Controls

1.9.1. Introduction

The control mechanism as originally designed was meant to be used for user settings (brightness, saturation, etc). However, it turned out to be a very useful model for implementing more complicated driver APIs where each driver implements only a subset of a larger API.

The MPEG encoding API was the driving force behind designing and implementing this extended control mechanism: the MPEG standard is quite large and the currently supported hardware MPEG encoders each only implement a subset of this standard. Further more, many parameters relating to how the video is encoded into an MPEG stream are specific to the MPEG encoding chip since the MPEG standard only defines the format of the resulting MPEG stream, not how the video is actually encoded into that format.

Unfortunately, the original control API lacked some features needed for these new uses and so it was extended into the (not terribly originally named) extended control API.

Even though the MPEG encoding API was the first effort to use the Extended Control API, nowadays there are also other classes of Extended Controls, such as Camera Controls and FM Transmitter Controls. The Extended Controls API as well as all Extended Controls classes are described in the following text.

1.9.2. The Extended Control API

Three new ioctls are available: VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS and VIDIOC_TRY_EXT_CTRLS. These ioctls act on arrays of controls (as opposed to the VIDIOC_G_CTRL and VIDIOC_S_CTRL ioctls that act on a single control). This is needed since it is often required to atomically change several controls at once.

Each of the new ioctls expects a pointer to a struct v4l2_ext_controls. This structure contains a pointer to the control array, a count of the number of controls in that array and a control class. Control classes are used to group similar controls into a single class. For example, control class V4L2_CTRL_CLASS_USER contains all user controls (i. e. all controls that can also be set using the old VIDIOC_S_CTRL ioctl). Control class V4L2_CTRL_CLASS_MPEG contains all controls relating to MPEG encoding, etc.

All controls in the control array must belong to the specified control class. An error is returned if this is not the case.

It is also possible to use an empty control array (count == 0) to check whether the specified control class is supported.

The control array is a struct v4l2_ext_control array. The v4l2_ext_control structure is very similar to struct v4l2_control, except for the fact that it also allows for 64-bit values and pointers to be passed.

It is important to realize that due to the flexibility of controls it is necessary to check whether the control you want to set actually is supported in the driver and what the valid range of values is. So use the VIDIOC_QUERYCTRL and VIDIOC_QUERYMENU ioctls to check this. Also note that it is possible that some of the menu indices in a control of type V4L2_CTRL_TYPE_MENU may not be supported (VIDIOC_QUERYMENU will return an error). A good example is the list of supported MPEG audio bitrates. Some drivers only support one or two bitrates, others support a wider range.

1.9.3. Enumerating Extended Controls

The recommended way to enumerate over the extended controls is by using VIDIOC_QUERYCTRL in combination with the V4L2_CTRL_FLAG_NEXT_CTRL flag:

struct v4l2_queryctrl qctrl;

qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
while (0 == ioctl (fd, VIDIOC_QUERYCTRL, &qctrl)) {
	/* ... */
	qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
}

The initial control ID is set to 0 ORed with the V4L2_CTRL_FLAG_NEXT_CTRL flag. The VIDIOC_QUERYCTRL ioctl will return the first control with a higher ID than the specified one. When no such controls are found an error is returned.

If you want to get all controls within a specific control class, then you can set the initial qctrl.id value to the control class and add an extra check to break out of the loop when a control of another control class is found:

qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL;
while (0 == ioctl (fd, VIDIOC_QUERYCTRL, &qctrl)) {
	if (V4L2_CTRL_ID2CLASS (qctrl.id) != V4L2_CTRL_CLASS_MPEG)
		break;
		/* ... */
		qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
	}

The 32-bit qctrl.id value is subdivided into three bit ranges: the top 4 bits are reserved for flags (e. g. V4L2_CTRL_FLAG_NEXT_CTRL) and are not actually part of the ID. The remaining 28 bits form the control ID, of which the most significant 12 bits define the control class and the least significant 16 bits identify the control within the control class. It is guaranteed that these last 16 bits are always non-zero for controls. The range of 0x1000 and up are reserved for driver-specific controls. The macro V4L2_CTRL_ID2CLASS(id) returns the control class ID based on a control ID.

If the driver does not support extended controls, then VIDIOC_QUERYCTRL will fail when used in combination with V4L2_CTRL_FLAG_NEXT_CTRL. In that case the old method of enumerating control should be used (see 1.8). But if it is supported, then it is guaranteed to enumerate over all controls, including driver-private controls.

1.9.4. Creating Control Panels

It is possible to create control panels for a graphical user interface where the user can select the various controls. Basically you will have to iterate over all controls using the method described above. Each control class starts with a control of type V4L2_CTRL_TYPE_CTRL_CLASS. VIDIOC_QUERYCTRL will return the name of this control class which can be used as the title of a tab page within a control panel.

The flags field of struct v4l2_queryctrl also contains hints on the behavior of the control. See the VIDIOC_QUERYCTRL documentation for more details.

1.9.5. MPEG Control Reference

Below all controls within the MPEG control class are described. First the generic controls, then controls specific for certain hardware.

1.9.5.1. Generic MPEG Controls

Table 1.2. MPEG Control IDs

1.9.5.2. CX2341x MPEG Controls

The following MPEG class controls deal with MPEG encoding settings that are specific to the Conexant CX23415 and CX23416 MPEG encoding chips.

Table 1.3. CX2341x Control IDs

1.9.6. Camera Control Reference

The Camera class includes controls for mechanical (or equivalent digital) features of a device such as controllable lenses or sensors.

Table 1.4. Camera Control IDs

1.9.7. FM Transmitter Control Reference

The FM Transmitter (FM_TX) class includes controls for common features of FM transmissions capable devices. Currently this class includes parameters for audio compression, pilot tone generation, audio deviation limiter, RDS transmission and tuning power features.

Table 1.5. FM_TX Control IDs

For more details about RDS specification, refer to
[EN 50067] document, from CENELEC.

1.10. Data Formats

1.10.1. Data Format Negotiation

Different devices exchange different kinds of data with
applications, for example video images, raw or sliced VBI data, RDS
datagrams. Even within one kind many different formats are possible,
in particular an abundance of image formats. Although drivers must
provide a default and the selection persists across closing and
reopening a device, applications should always negotiate a data format
before engaging in data exchange. Negotiation means the application
asks for a particular format and the driver selects and reports the
best the hardware can do to satisfy the request. Of course
applications can also just query the current selection.

A single mechanism exists to negotiate all data formats
using the aggregate struct v4l2_format and the VIDIOC_G_FMT and
VIDIOC_S_FMT ioctls. Additionally the VIDIOC_TRY_FMT ioctl can be
used to examine what the hardware could do,
without actually selecting a new data format. The data formats
supported by the V4L2 API are covered in the respective device section
in Chapter 4, Interfaces. For a closer look at image formats see
Chapter 2, Image Formats.

The VIDIOC_S_FMT ioctl is a major
turning-point in the initialization sequence. Prior to this point
multiple panel applications can access the same device concurrently to
select the current input, change controls or modify other properties.
The first VIDIOC_S_FMT assigns a logical stream
(video data, VBI data etc.) exclusively to one file descriptor.

Exclusive means no other application, more precisely no
other file descriptor, can grab this stream or change device
properties inconsistent with the negotiated parameters. A video
standard change for example, when the new standard uses a different
number of scan lines, can invalidate the selected image format.
Therefore only the file descriptor owning the stream can make
invalidating changes. Accordingly multiple file descriptors which
grabbed different logical streams prevent each other from interfering
with their settings. When for example video overlay is about to start
or already in progress, simultaneous video capturing may be restricted
to the same cropping and image size.

When applications omit the
VIDIOC_S_FMT ioctl its locking side effects are
implied by the next step, the selection of an I/O method with the
VIDIOC_REQBUFS ioctl or implicit with the first read() or
write() call.

Generally only one logical stream can be assigned to a
file descriptor, the exception being drivers permitting simultaneous
video capturing and overlay using the same file descriptor for
compatibility with V4L and earlier versions of V4L2. Switching the
logical stream or returning into "panel mode" is possible by closing
and reopening the device. Drivers may support a
switch using VIDIOC_S_FMT.

All drivers exchanging data with
applications must support the VIDIOC_G_FMT and
VIDIOC_S_FMT ioctl. Implementation of the
VIDIOC_TRY_FMT is highly recommended but
optional.

1.10.2. Image Format Enumeration

Apart of the generic format negotiation functions
a special ioctl to enumerate all image formats supported by video
capture, overlay or output devices is available.^[11]

The VIDIOC_ENUM_FMT ioctl must be supported
by all drivers exchanging image data with applications.

Important

Drivers are not supposed to convert image formats in
kernel space. They must enumerate only formats directly supported by
the hardware. If necessary driver writers should publish an example
conversion routine or library for integration into applications.

1.11. Image Cropping, Insertion and Scaling

Some video capture devices can sample a subsection of the
picture and shrink or enlarge it to an image of arbitrary size. We
call these abilities cropping and scaling. Some video output devices
can scale an image up or down and insert it at an arbitrary scan line
and horizontal offset into a video signal.

Applications can use the following API to select an area in
the video signal, query the default area and the hardware limits.
Despite their name, the VIDIOC_CROPCAP, VIDIOC_G_CROP
and VIDIOC_S_CROP ioctls apply to input as well as output
devices.

Scaling requires a source and a target. On a video capture
or overlay device the source is the video signal, and the cropping
ioctls determine the area actually sampled. The target are images
read by the application or overlaid onto the graphics screen. Their
size (and position for an overlay) is negotiated with the
VIDIOC_G_FMT and VIDIOC_S_FMT ioctls.

On a video output device the source are the images passed in
by the application, and their size is again negotiated with the
VIDIOC_G/S_FMT ioctls, or may be encoded in a
compressed video stream. The target is the video signal, and the
cropping ioctls determine the area where the images are
inserted.

Source and target rectangles are defined even if the device
does not support scaling or the VIDIOC_G/S_CROP
ioctls. Their size (and position where applicable) will be fixed in
this case. All capture and output device must support the
VIDIOC_CROPCAP ioctl such that applications can
determine if scaling takes place.

1.11.1. Cropping Structures

Figure 1.1. Image Cropping, Insertion and Scaling

For capture devices the coordinates of the top left
corner, width and height of the area which can be sampled is given by
the bounds substructure of the
struct v4l2_cropcap returned by the VIDIOC_CROPCAP
ioctl. To support a wide range of hardware this specification does not
define an origin or units. However by convention drivers should
horizontally count unscaled samples relative to 0H (the leading edge
of the horizontal sync pulse, see Figure 4.1, “Line synchronization”).
Vertically ITU-R line
numbers of the first field (Figure 4.2, “ITU-R 525 line numbering (M/NTSC and M/PAL)”, Figure 4.3, “ITU-R 625 line numbering”), multiplied by two if the driver can capture both
fields.

The top left corner, width and height of the source
rectangle, that is the area actually sampled, is given by struct v4l2_crop
using the same coordinate system as struct v4l2_cropcap. Applications can
use the VIDIOC_G_CROP and
VIDIOC_S_CROP ioctls to get and set this
rectangle. It must lie completely within the capture boundaries and
the driver may further adjust the requested size and/or position
according to hardware limitations.

Each capture device has a default source rectangle, given
by the defrect substructure of
struct v4l2_cropcap. The center of this rectangle shall align with the
center of the active picture area of the video signal, and cover what
the driver writer considers the complete picture. Drivers shall reset
the source rectangle to the default when the driver is first loaded,
but not later.

For output devices these structures and ioctls are used
accordingly, defining the target rectangle where
the images will be inserted into the video signal.

1.11.2. Scaling Adjustments

Video hardware can have various cropping, insertion and
scaling limitations. It may only scale up or down, support only
discrete scaling factors, or have different scaling abilities in
horizontal and vertical direction. Also it may not support scaling at
all. At the same time the struct v4l2_crop rectangle may have to be
aligned, and both the source and target rectangles may have arbitrary
upper and lower size limits. In particular the maximum
width and height
in struct v4l2_crop may be smaller than the
struct v4l2_cropcap.bounds area. Therefore, as
usual, drivers are expected to adjust the requested parameters and
return the actual values selected.

Applications can change the source or the target rectangle
first, as they may prefer a particular image size or a certain area in
the video signal. If the driver has to adjust both to satisfy hardware
limitations, the last requested rectangle shall take priority, and the
driver should preferably adjust the opposite one. The VIDIOC_TRY_FMT
ioctl however shall not change the driver state and therefore only
adjust the requested rectangle.

Suppose scaling on a video capture device is restricted to
a factor 1:1 or 2:1 in either direction and the target image size must
be a multiple of 16 × 16 pixels. The source cropping
rectangle is set to defaults, which are also the upper limit in this
example, of 640 × 400 pixels at offset 0, 0. An
application requests an image size of 300 × 225
pixels, assuming video will be scaled down from the "full picture"
accordingly. The driver sets the image size to the closest possible
values 304 × 224, then chooses the cropping rectangle
closest to the requested size, that is 608 × 224
(224 × 2:1 would exceed the limit 400). The offset
0, 0 is still valid, thus unmodified. Given the default cropping
rectangle reported by VIDIOC_CROPCAP the
application can easily propose another offset to center the cropping
rectangle.

Now the application may insist on covering an area using a
picture aspect ratio closer to the original request, so it asks for a
cropping rectangle of 608 × 456 pixels. The present
scaling factors limit cropping to 640 × 384, so the
driver returns the cropping size 608 × 384 and adjusts
the image size to closest possible 304 × 192.

1.11.3. Examples

Source and target rectangles shall remain unchanged across
closing and reopening a device, such that piping data into or out of a
device will work without special preparations. More advanced
applications should ensure the parameters are suitable before starting
I/O.

Example 1.10. Resetting the cropping parameters

(A video capture device is assumed; change
V4L2_BUF_TYPE_VIDEO_CAPTURE for other
devices.)

struct v4l2_cropcap cropcap;
struct v4l2_crop crop;

memset (&cropcap, 0, sizeof (cropcap));
cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;

if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) {
	perror ("VIDIOC_CROPCAP");
	exit (EXIT_FAILURE);
}

memset (&crop, 0, sizeof (crop));
crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
crop.c = cropcap.defrect;

/* Ignore if cropping is not supported (EINVAL). */

if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
    && errno != EINVAL) {
	perror ("VIDIOC_S_CROP");
	exit (EXIT_FAILURE);
}
      

Example 1.11. Simple downscaling

(A video capture device is assumed.)

struct v4l2_cropcap cropcap;
struct v4l2_format format;

reset_cropping_parameters ();

/* Scale down to 1/4 size of full picture. */

memset (&format, 0, sizeof (format)); /* defaults */

format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;

format.fmt.pix.width = cropcap.defrect.width >> 1;
format.fmt.pix.height = cropcap.defrect.height >> 1;
format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;

if (-1 == ioctl (fd, VIDIOC_S_FMT, &format)) {
	perror ("VIDIOC_S_FORMAT");
	exit (EXIT_FAILURE);
}

/* We could check the actual image size now, the actual scaling factor
   or if the driver can scale at all. */
	

Example 1.12. Selecting an output area

struct v4l2_cropcap cropcap;
struct v4l2_crop crop;

memset (&cropcap, 0, sizeof (cropcap));
cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;

if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &cropcap)) {
	perror ("VIDIOC_CROPCAP");
	exit (EXIT_FAILURE);
}

memset (&crop, 0, sizeof (crop));

crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
crop.c = cropcap.defrect;

/* Scale the width and height to 50 % of their original size
   and center the output. */

crop.c.width /= 2;
crop.c.height /= 2;
crop.c.left += crop.c.width / 2;
crop.c.top += crop.c.height / 2;

/* Ignore if cropping is not supported (EINVAL). */

if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
    && errno != EINVAL) {
	perror ("VIDIOC_S_CROP");
	exit (EXIT_FAILURE);
}

Example 1.13. Current scaling factor and pixel aspect

(A video capture device is assumed.)

struct v4l2_cropcap cropcap;
struct v4l2_crop crop;
struct v4l2_format format;
double hscale, vscale;
double aspect;
int dwidth, dheight;

memset (&cropcap, 0, sizeof (cropcap));
cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;

if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) {
	perror ("VIDIOC_CROPCAP");
	exit (EXIT_FAILURE);
}

memset (&crop, 0, sizeof (crop));
crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;

if (-1 == ioctl (fd, VIDIOC_G_CROP, &crop)) {
	if (errno != EINVAL) {
		perror ("VIDIOC_G_CROP");
		exit (EXIT_FAILURE);
	}

	/* Cropping not supported. */
	crop.c = cropcap.defrect;
}

memset (&format, 0, sizeof (format));
format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;

if (-1 == ioctl (fd, VIDIOC_G_FMT, &format)) {
	perror ("VIDIOC_G_FMT");
	exit (EXIT_FAILURE);
}

/* The scaling applied by the driver. */

hscale = format.fmt.pix.width / (double) crop.c.width;
vscale = format.fmt.pix.height / (double) crop.c.height;

aspect = cropcap.pixelaspect.numerator /
	 (double) cropcap.pixelaspect.denominator;
aspect = aspect * hscale / vscale;

/* Devices following ITU-R BT.601 do not capture
   square pixels. For playback on a computer monitor
   we should scale the images to this size. */

dwidth = format.fmt.pix.width / aspect;
dheight = format.fmt.pix.height;
	

1.12. Streaming Parameters

Streaming parameters are intended to optimize the video capture process as well as I/O. Presently applications can request a high quality capture mode with the VIDIOC_S_PARM ioctl.

The current video standard determines a nominal number of frames per second. If less than this number of frames is to be captured or output, applications can request frame skipping or duplicating on the driver side. This is especially useful when using the read() or write(), which are not augmented by timestamps or sequence counters, and to avoid unneccessary data copying.

Finally these ioctls can be used to determine the number of buffers used internally by a driver in read/write mode. For implications see the section discussing the read() function.

To get and set the streaming parameters applications call the VIDIOC_G_PARM and VIDIOC_S_PARM ioctl, respectively. They take a pointer to a struct v4l2_streamparm, which contains a union holding separate parameters for input and output devices.

These ioctls are optional, drivers need not implement them. If so, they return the EINVAL error code.

^[1] Access permissions are associated with character
device special files, hence we must ensure device numbers cannot
change with the module load order. To this end minor numbers are no
longer automatically assigned by the "videodev" module as in V4L but
requested by the driver. The defaults will suffice for most people
unless two drivers compete for the same minor numbers.

^[2] In earlier versions of the V4L2 API the module options
where named after the device special file with a "unit_" prefix, expressing
the minor number itself, not an offset. Rationale for this change is unknown.
Lastly the naming and semantics are just a convention among driver writers,
the point to note is that minor numbers are not supposed to be hardcoded
into drivers.

^[3] Given a device file name one cannot reliable find
related devices. For once names are arbitrary and in a system with
multiple devices, where only some support VBI capturing, a
/dev/video2 is not necessarily related to
/dev/vbi2. The V4L
VIDIOCGUNIT ioctl would require a search for a
device file with a particular major and minor number.

^[4] Drivers could recognize the
O_EXCL open flag. Presently this is not required,
so applications cannot know if it really works.

^[5] Actually struct v4l2_audio ought to have a
tuner field like struct v4l2_input, not only
making the API more consistent but also permitting radio devices with
multiple tuners.

^[6] Some users are already confused by technical terms PAL,
NTSC and SECAM. There is no point asking them to distinguish between
B, G, D, or K when the software or hardware can do that
automatically.

^[7] An alternative to the current scheme is to use pointers
to indices as arguments of VIDIOC_G_STD and
VIDIOC_S_STD, the struct v4l2_input and
struct v4l2_output std field would be a set of
indices like audioset.

Indices are consistent with the rest of the API
and identify the standard unambiguously. In the present scheme of
things an enumerated standard is looked up by v4l2_std_id. Now the
standards supported by the inputs of a device can overlap. Just
assume the tuner and composite input in the example above both
exist on a device. An enumeration of "PAL-B/G", "PAL-H/I" suggests
a choice which does not exist. We cannot merge or omit sets, because
applications would be unable to find the standards reported by
VIDIOC_G_STD. That leaves separate enumerations
for each input. Also selecting a standard by v4l2_std_id can be
ambiguous. Advantage of this method is that applications need not
identify the standard indirectly, after enumerating.

So in
summary, the lookup itself is unavoidable. The difference is only
whether the lookup is necessary to find an enumerated standard or to
switch to a standard by v4l2_std_id.

^[8] See Section 3.5, “Buffers” for a rationale. Probably
even USB cameras follow some well known video standard. It might have
been better to explicitly indicate elsewhere if a device cannot live
up to normal expectations, instead of this exception.

^[9] It will be more convenient for applications if drivers
make use of the V4L2_CTRL_FLAG_DISABLED flag, but
that was never required.

^[10] Applications could call an ioctl to request events.
After another process called VIDIOC_S_CTRL or another ioctl changing
shared properties the select() function would indicate
readability until any ioctl (querying the properties) is
called.

^[11] Enumerating formats an application has no a-priori
knowledge of (otherwise it could explicitely ask for them and need not
enumerate) seems useless, but there are applications serving as proxy
between drivers and the actual video applications for which this is
useful.

Chapter 2. Image Formats

Table of Contents

2.1. Standard Image Formats

2.2. Colorspaces

2.3. Indexed Format

2.4. RGB Formats

2.5. YUV Formats

2.6. Compressed Formats

2.7. Reserved Format Identifiers

The V4L2 API was primarily designed for devices exchanging
image data with applications. The
v4l2_pix_format structure defines the format
and layout of an image in memory. Image formats are negotiated with
the VIDIOC_S_FMT ioctl. (The explanations here focus on video
capturing and output, for overlay frame buffer formats see also
VIDIOC_G_FBUF.)

Table 2.1. struct v4l2_pix_format

2.1. Standard Image Formats

In order to exchange images between drivers and
applications, it is necessary to have standard image data formats
which both sides will interpret the same way. V4L2 includes several
such formats, and this section is intended to be an unambiguous
specification of the standard image data formats in V4L2.

V4L2 drivers are not limited to these formats, however.
Driver-specific formats are possible. In that case the application may
depend on a codec to convert images to one of the standard formats
when needed. But the data can still be stored and retrieved in the
proprietary format. For example, a device may support a proprietary
compressed format. Applications can still capture and save the data in
the compressed format, saving much disk space, and later use a codec
to convert the images to the X Windows screen format when the video is
to be displayed.

Even so, ultimately, some standard formats are needed, so
the V4L2 specification would not be complete without well-defined
standard formats.

The V4L2 standard formats are mainly uncompressed formats. The
pixels are always arranged in memory from left to right, and from top
to bottom. The first byte of data in the image buffer is always for
the leftmost pixel of the topmost row. Following that is the pixel
immediately to its right, and so on until the end of the top row of
pixels. Following the rightmost pixel of the row there may be zero or
more bytes of padding to guarantee that each row of pixel data has a
certain alignment. Following the pad bytes, if any, is data for the
leftmost pixel of the second row from the top, and so on. The last row
has just as many pad bytes after it as the other rows.

In V4L2 each format has an identifier which looks like
PIX_FMT_XXX, defined in the videodev.h header file. These identifiers
represent four character codes
which are also listed below, however they are not the same as those
used in the Windows world.

2.2. Colorspaces

[intro]

Gamma Correction

[to do]

E'_R = f(R)

E'_G = f(G)

E'_B = f(B)

Construction of luminance and color-difference
signals

[to do]

E'_Y =
Coeff_R E'_R
+ Coeff_G E'_G
+ Coeff_B E'_B

(E'_R - E'_Y) = E'_R
- Coeff_R E'_R
- Coeff_G E'_G
- Coeff_B E'_B

(E'_B - E'_Y) = E'_B
- Coeff_R E'_R
- Coeff_G E'_G
- Coeff_B E'_B

Re-normalized color-difference signals

The color-difference signals are scaled back to unity
range [-0.5;+0.5]:

K_B = 0.5 / (1 - Coeff_B)

K_R = 0.5 / (1 - Coeff_R)

P_B =
K_B (E'_B - E'_Y) =
0.5 (Coeff_R / Coeff_B) E'_R
+ 0.5 (Coeff_G / Coeff_B) E'_G
+ 0.5 E'_B

P_R =
K_R (E'_R - E'_Y) =
0.5 E'_R
+ 0.5 (Coeff_G / Coeff_R) E'_G
+ 0.5 (Coeff_B / Coeff_R) E'_B

Quantization

[to do]

Y' = (Lum. Levels - 1) · E'_Y + Lum. Offset

C_B = (Chrom. Levels - 1)
· P_B + Chrom. Offset

C_R = (Chrom. Levels - 1)
· P_R + Chrom. Offset

Rounding to the nearest integer and clamping to the range
[0;255] finally yields the digital color components Y'CbCr
stored in YUV images.

Example 2.1. ITU-R Rec. BT.601 color conversion

Forward Transformation

int ER, EG, EB;         /* gamma corrected RGB input [0;255] */
int Y1, Cb, Cr;         /* output [0;255] */

double r, g, b;         /* temporaries */
double y1, pb, pr;

int
clamp (double x)
{
	int r = x;      /* round to nearest */

	if (r < 0)         return 0;
	else if (r > 255)  return 255;
	else               return r;
}

r = ER / 255.0;
g = EG / 255.0;
b = EB / 255.0;

y1  =  0.299  * r + 0.587 * g + 0.114  * b;
pb  = -0.169  * r - 0.331 * g + 0.5    * b;
pr  =  0.5    * r - 0.419 * g - 0.081  * b;

Y1 = clamp (219 * y1 + 16);
Cb = clamp (224 * pb + 128);
Cr = clamp (224 * pr + 128);

/* or shorter */

y1 = 0.299 * ER + 0.587 * EG + 0.114 * EB;

Y1 = clamp ( (219 / 255.0)                    *       y1  + 16);
Cb = clamp (((224 / 255.0) / (2 - 2 * 0.114)) * (EB - y1) + 128);
Cr = clamp (((224 / 255.0) / (2 - 2 * 0.299)) * (ER - y1) + 128);
      

Inverse Transformation

int Y1, Cb, Cr;         /* gamma pre-corrected input [0;255] */
int ER, EG, EB;         /* output [0;255] */

double r, g, b;         /* temporaries */
double y1, pb, pr;

int
clamp (double x)
{
	int r = x;      /* round to nearest */

	if (r < 0)         return 0;
	else if (r > 255)  return 255;
	else               return r;
}

y1 = (255 / 219.0) * (Y1 - 16);
pb = (255 / 224.0) * (Cb - 128);
pr = (255 / 224.0) * (Cr - 128);

r = 1.0 * y1 + 0     * pb + 1.402 * pr;
g = 1.0 * y1 - 0.344 * pb - 0.714 * pr;
b = 1.0 * y1 + 1.772 * pb + 0     * pr;

ER = clamp (r * 255); /* [ok? one should prob. limit y1,pb,pr] */
EG = clamp (g * 255);
EB = clamp (b * 255);
      

Table 2.2. enum v4l2_colorspace

2.3. Indexed Format

In this format each pixel is represented by an 8 bit index
into a 256 entry ARGB palette. It is intended for Video Output Overlays only. There are no ioctls to
access the palette, this must be done with ioctls of the Linux framebuffer API.

Table 2.3. Indexed Image Format

2.4. RGB Formats

Name

Packed RGB formats — Packed RGB formats

Description

These formats are designed to match the pixel formats of
typical PC graphics frame buffers. They occupy 8, 16, 24 or 32 bits
per pixel. These are all packed-pixel formats, meaning all the data
for a pixel lie next to each other in memory.

When one of these formats is used, drivers shall report the
colorspace V4L2_COLORSPACE_SRGB.

Table 2.4. Packed RGB Image Formats

Bit 7 is the most significant bit. The value of a = alpha
bits is undefined when reading from the driver, ignored when writing
to the driver, except when alpha blending has been negotiated for a
Video Overlay or Video Output Overlay.

Example 2.2. V4L2_PIX_FMT_BGR24 4 × 4 pixel
image

Byte Order. Each cell is one byte.

Important

Drivers may interpret these formats differently.

Some RGB formats above are uncommon and were probably
defined in error. Drivers may interpret them as in Table 2.5, “Packed RGB Image Formats (corrected)”.

Table 2.5. Packed RGB Image Formats (corrected)

A test utility to determine which RGB formats a driver
actually supports is available from the LinuxTV v4l-dvb repository.
See https://linuxtv.org/repo/ for access instructions.

Name

V4L2_PIX_FMT_SBGGR8 — Bayer RGB format

Description

This is commonly the native format of digital cameras,
reflecting the arrangement of sensors on the CCD device. Only one red,
green or blue value is given for each pixel. Missing components must
be interpolated from neighbouring pixels. From left to right the first
row consists of a blue and green value, the second row of a green and
red value. This scheme repeats to the right and down for every two
columns and rows.

Example 2.3. V4L2_PIX_FMT_SBGGR8 4 × 4
pixel image

Byte Order. Each cell is one byte.

Name

V4L2_PIX_FMT_SGBRG8 — Bayer RGB format

Description

This is commonly the native format of digital cameras,
reflecting the arrangement of sensors on the CCD device. Only one red,
green or blue value is given for each pixel. Missing components must
be interpolated from neighbouring pixels. From left to right the first
row consists of a green and blue value, the second row of a red and
green value. This scheme repeats to the right and down for every two
columns and rows.

Example 2.4. V4L2_PIX_FMT_SGBRG8 4 × 4
pixel image

Byte Order. Each cell is one byte.

Name

V4L2_PIX_FMT_SGRBG8 — Bayer RGB format

Description

This is commonly the native format of digital cameras,
reflecting the arrangement of sensors on the CCD device. Only one red,
green or blue value is given for each pixel. Missing components must
be interpolated from neighbouring pixels. From left to right the first
row consists of a green and blue value, the second row of a red and
green value. This scheme repeats to the right and down for every two
columns and rows.

Example 2.5. V4L2_PIX_FMT_SGRBG8 4 ×
4 pixel image

Byte Order. Each cell is one byte.

Name

V4L2_PIX_FMT_SBGGR16 — Bayer RGB format

Description

This format is similar to V4L2_PIX_FMT_SBGGR8, except each pixel has
a depth of 16 bits. The least significant byte is stored at lower
memory addresses (little-endian). Note the actual sampling precision
may be lower than 16 bits, for example 10 bits per pixel with values
in range 0 to 1023.

Example 2.6. V4L2_PIX_FMT_SBGGR16 4 × 4
pixel image

Byte Order. Each cell is one byte.

2.5. YUV Formats

YUV is the format native to TV broadcast and composite video
signals. It separates the brightness information (Y) from the color
information (U and V or Cb and Cr). The color information consists of
red and blue color difference signals, this way
the green component can be reconstructed by subtracting from the
brightness component. See Section 2.2, “Colorspaces” for conversion
examples. YUV was chosen because early television would only transmit
brightness information. To add color in a way compatible with existing
receivers a new signal carrier was added to transmit the color
difference signals. Secondary in the YUV format the U and V components
usually have lower resolution than the Y component. This is an analog
video compression technique taking advantage of a property of the
human visual system, being more sensitive to brightness
information.

Name

Packed YUV formats — Packed YUV formats

Description

Similar to the packed RGB formats these formats store
the Y, Cb and Cr component of each pixel in one 16 or 32 bit
word.

Table 2.6. Packed YUV Image Formats

Bit 7 is the most significant bit. The value of a = alpha
bits is undefined when reading from the driver, ignored when writing
to the driver, except when alpha blending has been negotiated for a
Video Overlay or Video Output Overlay.

Name

V4L2_PIX_FMT_GREY — Grey-scale image

Description

This is a grey-scale image. It is really a degenerate
Y'CbCr format which simply contains no Cb or Cr data.

Example 2.7. V4L2_PIX_FMT_GREY 4 × 4
pixel image

Byte Order. Each cell is one byte.

Name

V4L2_PIX_FMT_Y16 — Grey-scale image

Description

This is a grey-scale image with a depth of 16 bits per
pixel. The least significant byte is stored at lower memory addresses
(little-endian). Note the actual sampling precision may be lower than
16 bits, for example 10 bits per pixel with values in range 0 to
1023.

Example 2.8. V4L2_PIX_FMT_Y16 4 × 4
pixel image

Byte Order. Each cell is one byte.

Name

V4L2_PIX_FMT_YUYV — Packed format with ½ horizontal chroma
resolution, also known as YUV 4:2:2

Description

In this format each four bytes is two pixels. Each four
bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and
the Cb and Cr belong to both pixels. As you can see, the Cr and Cb
components have half the horizontal resolution of the Y component.
V4L2_PIX_FMT_YUYV is known in the Windows
environment as YUY2.

Example 2.9. V4L2_PIX_FMT_YUYV 4 × 4
pixel image

Byte Order. Each cell is one byte.

Color Sample Location. 

Name

V4L2_PIX_FMT_UYVY — Variation of
V4L2_PIX_FMT_YUYV with different order of samples
in memory

Description

In this format each four bytes is two pixels. Each four
bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and
the Cb and Cr belong to both pixels. As you can see, the Cr and Cb
components have half the horizontal resolution of the Y
component.

Example 2.10. V4L2_PIX_FMT_UYVY 4 × 4
pixel image

Byte Order. Each cell is one byte.

Color Sample Location. 

Name

V4L2_PIX_FMT_YVYU — Variation of
V4L2_PIX_FMT_YUYV with different order of samples
in memory

Description

In this format each four bytes is two pixels. Each four
bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and
the Cb and Cr belong to both pixels. As you can see, the Cr and Cb
components have half the horizontal resolution of the Y
component.

Example 2.11. V4L2_PIX_FMT_YVYU 4 × 4
pixel image

Byte Order. Each cell is one byte.

Color Sample Location. 

Name

V4L2_PIX_FMT_VYUY — Variation of
V4L2_PIX_FMT_YUYV with different order of samples
in memory

Description

In this format each four bytes is two pixels. Each four
bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and
the Cb and Cr belong to both pixels. As you can see, the Cr and Cb
components have half the horizontal resolution of the Y
component.

Example 2.12. V4L2_PIX_FMT_VYUY 4 × 4
pixel image

Byte Order. Each cell is one byte.

Color Sample Location. 

Name

V4L2_PIX_FMT_Y41P — Format with ¼ horizontal chroma
resolution, also known as YUV 4:1:1

Description

In this format each 12 bytes is eight pixels. In the
twelve bytes are two CbCr pairs and eight Y's. The first CbCr pair
goes with the first four Y's, and the second CbCr pair goes with the
other four Y's. The Cb and Cr components have one fourth the
horizontal resolution of the Y component.

Do not confuse this format with V4L2_PIX_FMT_YUV411P.
Y41P is derived from "YUV 4:1:1 packed", while
YUV411P stands for "YUV 4:1:1 planar".

Example 2.13. V4L2_PIX_FMT_Y41P 8 × 4
pixel image

Byte Order. Each cell is one byte.

Color Sample Location. 

Name

V4L2_PIX_FMT_YVU420, V4L2_PIX_FMT_YUV420 — Planar formats with ½ horizontal and
vertical chroma resolution, also known as YUV 4:2:0

Description

These are planar formats, as opposed to a packed format.
The three components are separated into three sub- images or planes.
The Y plane is first. The Y plane has one byte per pixel. For
V4L2_PIX_FMT_YVU420, the Cr plane immediately
follows the Y plane in memory. The Cr plane is half the width and half
the height of the Y plane (and of the image). Each Cr belongs to four
pixels, a two-by-two square of the image. For example,
Cr₀ belongs to Y'₀₀,
Y'₀₁, Y'₁₀, and
Y'₁₁. Following the Cr plane is the Cb plane,
just like the Cr plane. V4L2_PIX_FMT_YUV420 is
the same except the Cb plane comes first, then the Cr plane.

If the Y plane has pad bytes after each row, then the Cr
and Cb planes have half as many pad bytes after their rows. In other
words, two Cx rows (including padding) is exactly as long as one Y row
(including padding).

Example 2.14. V4L2_PIX_FMT_YVU420 4 × 4
pixel image

Byte Order. Each cell is one byte.

Color Sample Location. 

Name

V4L2_PIX_FMT_YVU410, V4L2_PIX_FMT_YUV410 — Planar formats with ¼ horizontal and
vertical chroma resolution, also known as YUV 4:1:0

Description

These are planar formats, as opposed to a packed format.
The three components are separated into three sub-images or planes.
The Y plane is first. The Y plane has one byte per pixel. For
V4L2_PIX_FMT_YVU410, the Cr plane immediately
follows the Y plane in memory. The Cr plane is ¼ the width and
¼ the height of the Y plane (and of the image). Each Cr belongs
to 16 pixels, a four-by-four square of the image. Following the Cr
plane is the Cb plane, just like the Cr plane.
V4L2_PIX_FMT_YUV410 is the same, except the Cb
plane comes first, then the Cr plane.

If the Y plane has pad bytes after each row, then the Cr
and Cb planes have ¼ as many pad bytes after their rows. In
other words, four Cx rows (including padding) are exactly as long as
one Y row (including padding).

Example 2.15. V4L2_PIX_FMT_YVU410 4 × 4
pixel image

Byte Order. Each cell is one byte.