1 .. Permission is granted to copy, distribute and/or modify this
2 .. document under the terms of the GNU Free Documentation License,
3 .. Version 1.1 or any later version published by the Free Software
4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
5 .. and no Back-Cover Texts. A copy of the license is included at
6 .. Documentation/media/uapi/fdl-appendix.rst.
8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
10 .. include:: <isonum.txt>
13 ############################
14 Part I - Video for Linux API
15 ############################
17 This part describes the Video for Linux API version 2 (V4L2 API) specification.
45 **********************
46 Revision and Copyright
47 **********************
49 Authors, in alphabetical order:
51 - Ailus, Sakari <sakari.ailus@iki.fi>
53 - Subdev selections API.
55 - Carvalho Chehab, Mauro <mchehab+samsung@kernel.org>
57 - Documented libv4l, designed and added v4l2grab example, Remote Controller chapter.
61 - Original author of the V4L2 API and documentation.
63 - H Schimek, Michael <mschimek@gmx.at>
65 - Original author of the V4L2 API and documentation.
67 - Karicheri, Muralidharan <m-karicheri2@ti.com>
69 - Documented the Digital Video timings API.
71 - Osciak, Pawel <pawel@osciak.com>
73 - Designed and documented the multi-planar API.
75 - Palosaari, Antti <crope@iki.fi>
81 - Introduce HSV formats and other minor changes.
85 - Designed and documented the VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS ioctls.
87 - Walls, Andy <awalls@md.metrocast.net>
89 - Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV MPEG stream embedded, sliced VBI data format in this specification.
91 - Verkuil, Hans <hverkuil@xs4all.nl>
93 - Designed and documented the VIDIOC_LOG_STATUS ioctl, the extended control ioctls, major parts of the sliced VBI API, the MPEG encoder and decoder APIs and the DV Timings API.
95 **Copyright** |copy| 1999-2016: Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, Pawel Osciak, Sakari Ailus & Antti Palosaari.
97 Except when explicitly stated as GPL, programming examples within this
98 part can be used and distributed without restrictions.
104 :revision: 4.10 / 2016-07-15 (*rr*)
106 Introduce HSV formats.
109 :revision: 4.5 / 2015-10-29 (*rr*)
111 Extend VIDIOC_G_EXT_CTRLS;. Replace ctrl_class with a new union with
112 ctrl_class and which. Which is used to select the current value of the
113 control or the default value.
116 :revision: 4.4 / 2015-05-26 (*ap*)
118 Renamed V4L2_TUNER_ADC to V4L2_TUNER_SDR. Added
119 V4L2_CID_RF_TUNER_RF_GAIN control. Added transmitter support for
120 Software Defined Radio (SDR) Interface.
123 :revision: 4.1 / 2015-02-13 (*mcc*)
125 Fix documentation for media controller device nodes and add support for
126 DVB device nodes. Add support for Tuner sub-device.
129 :revision: 3.19 / 2014-12-05 (*hv*)
131 Rewrote Colorspace chapter, added new enum
132 :c:type:`v4l2_ycbcr_encoding` and enum
133 :c:type:`v4l2_quantization` fields to struct
134 :c:type:`v4l2_pix_format`, struct
135 :c:type:`v4l2_pix_format_mplane` and struct
136 :c:type:`v4l2_mbus_framefmt`.
139 :revision: 3.17 / 2014-08-04 (*lp, hv*)
141 Extended struct :c:type:`v4l2_pix_format`. Added
142 format flags. Added compound control types and VIDIOC_QUERY_EXT_CTRL.
145 :revision: 3.15 / 2014-02-03 (*hv, ap*)
147 Update several sections of "Common API Elements": "Opening and Closing
148 Devices" "Querying Capabilities", "Application Priority", "Video Inputs
149 and Outputs", "Audio Inputs and Outputs" "Tuners and Modulators", "Video
150 Standards" and "Digital Video (DV) Timings". Added SDR API.
153 :revision: 3.14 / 2013-11-25 (*rr*)
155 Set width and height as unsigned on v4l2_rect.
158 :revision: 3.11 / 2013-05-26 (*hv*)
160 Remove obsolete VIDIOC_DBG_G_CHIP_IDENT ioctl.
163 :revision: 3.10 / 2013-03-25 (*hv*)
165 Remove obsolete and unused DV_PRESET ioctls: VIDIOC_G_DV_PRESET,
166 VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and
167 VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output
168 capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS.
169 Added VIDIOC_DBG_G_CHIP_INFO.
172 :revision: 3.9 / 2012-12-03 (*sa, sn*)
174 Added timestamp types to v4l2_buffer. Added
175 V4L2_EVENT_CTRL_CH_RANGE control event changes flag.
178 :revision: 3.6 / 2012-07-02 (*hv*)
180 Added VIDIOC_ENUM_FREQ_BANDS.
183 :revision: 3.5 / 2012-05-07 (*sa, sn, hv*)
185 Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev selections API.
186 Improved the description of V4L2_CID_COLORFX control, added
187 V4L2_CID_COLORFX_CBCR control. Added camera controls
188 V4L2_CID_AUTO_EXPOSURE_BIAS,
189 V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE,
190 V4L2_CID_IMAGE_STABILIZATION, V4L2_CID_ISO_SENSITIVITY,
191 V4L2_CID_ISO_SENSITIVITY_AUTO, V4L2_CID_EXPOSURE_METERING,
192 V4L2_CID_SCENE_MODE, V4L2_CID_3A_LOCK,
193 V4L2_CID_AUTO_FOCUS_START, V4L2_CID_AUTO_FOCUS_STOP,
194 V4L2_CID_AUTO_FOCUS_STATUS and V4L2_CID_AUTO_FOCUS_RANGE. Added
195 VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and
196 VIDIOC_DV_TIMINGS_CAP.
199 :revision: 3.4 / 2012-01-25 (*sn*)
201 Added :ref:`JPEG compression control class. <jpeg-controls>`
204 :revision: 3.3 / 2012-01-11 (*hv*)
206 Added device_caps field to struct v4l2_capabilities.
209 :revision: 3.2 / 2011-08-26 (*hv*)
211 Added V4L2_CTRL_FLAG_VOLATILE.
214 :revision: 3.1 / 2011-06-27 (*mcc, po, hv*)
216 Documented that VIDIOC_QUERYCAP now returns a per-subsystem version
217 instead of a per-driver one. Standardize an error code for invalid
218 ioctl. Added V4L2_CTRL_TYPE_BITMASK.
221 :revision: 2.6.39 / 2011-03-01 (*mcc, po*)
223 Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect
224 latest changes. Added the :ref:`multi-planar API <planar-apis>`.
227 :revision: 2.6.37 / 2010-08-06 (*hv*)
229 Removed obsolete vtx (videotext) API.
232 :revision: 2.6.33 / 2009-12-03 (*mk*)
234 Added documentation for the Digital Video timings API.
237 :revision: 2.6.32 / 2009-08-31 (*mcc*)
239 Now, revisions will match the kernel version where the V4L2 API changes
240 will be used by the Linux Kernel. Also added Remote Controller chapter.
243 :revision: 0.29 / 2009-08-26 (*ev*)
245 Added documentation for string controls and for FM Transmitter controls.
248 :revision: 0.28 / 2009-08-26 (*gl*)
250 Added V4L2_CID_BAND_STOP_FILTER documentation.
253 :revision: 0.27 / 2009-08-15 (*mcc*)
255 Added libv4l and Remote Controller documentation; added v4l2grab and
256 keytable application examples.
259 :revision: 0.26 / 2009-07-23 (*hv*)
261 Finalized the RDS capture API. Added modulator and RDS encoder
262 capabilities. Added support for string controls.
265 :revision: 0.25 / 2009-01-18 (*hv*)
267 Added pixel formats VYUY, NV16 and NV61, and changed the debug ioctls
268 VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT. Added camera
269 controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE,
270 V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY.
273 :revision: 0.24 / 2008-03-04 (*mhs*)
275 Added pixel formats Y16 and SBGGR16, new controls and a camera controls
276 class. Removed VIDIOC_G/S_MPEGCOMP.
279 :revision: 0.23 / 2007-08-30 (*mhs*)
281 Fixed a typo in VIDIOC_DBG_G/S_REGISTER. Clarified the byte order of
282 packed pixel formats.
285 :revision: 0.22 / 2007-08-29 (*mhs*)
287 Added the Video Output Overlay interface, new MPEG controls,
288 V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT,
289 VIDIOC_DBG_G/S_REGISTER, VIDIOC\_(TRY\_)ENCODER_CMD,
290 VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats.
291 Clarifications in the cropping chapter, about RGB pixel formats, the
292 mmap(), poll(), select(), read() and write() functions. Typographical
296 :revision: 0.21 / 2006-12-19 (*mhs*)
298 Fixed a link in the VIDIOC_G_EXT_CTRLS section.
301 :revision: 0.20 / 2006-11-24 (*mhs*)
303 Clarified the purpose of the audioset field in struct v4l2_input and
307 :revision: 0.19 / 2006-10-19 (*mhs*)
309 Documented V4L2_PIX_FMT_RGB444.
312 :revision: 0.18 / 2006-10-18 (*mhs*)
314 Added the description of extended controls by Hans Verkuil. Linked
315 V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.
318 :revision: 0.17 / 2006-10-12 (*mhs*)
320 Corrected V4L2_PIX_FMT_HM12 description.
323 :revision: 0.16 / 2006-10-08 (*mhs*)
325 VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS are now part
329 :revision: 0.15 / 2006-09-23 (*mhs*)
331 Cleaned up the bibliography, added BT.653 and BT.1119.
332 capture.c/start_capturing() for user pointer I/O did not initialize the
333 buffer index. Documented the V4L MPEG and MJPEG VID_TYPEs and
334 V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel formats. See
335 the history chapter for API changes.
338 :revision: 0.14 / 2006-09-14 (*mr*)
340 Added VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS proposal
341 for frame format enumeration of digital devices.
344 :revision: 0.13 / 2006-04-07 (*mhs*)
346 Corrected the description of struct v4l2_window clips. New V4L2_STD\_
347 and V4L2_TUNER_MODE_LANG1_LANG2 defines.
350 :revision: 0.12 / 2006-02-03 (*mhs*)
352 Corrected the description of struct v4l2_captureparm and
356 :revision: 0.11 / 2006-01-27 (*mhs*)
358 Improved the description of struct v4l2_tuner.
361 :revision: 0.10 / 2006-01-10 (*mhs*)
363 VIDIOC_G_INPUT and VIDIOC_S_PARM clarifications.
366 :revision: 0.9 / 2005-11-27 (*mhs*)
368 Improved the 525 line numbering diagram. Hans Verkuil and I rewrote the
369 sliced VBI section. He also contributed a VIDIOC_LOG_STATUS page.
370 Fixed VIDIOC_S_STD call in the video standard selection example.
374 :revision: 0.8 / 2004-10-04 (*mhs*)
376 Somehow a piece of junk slipped into the capture example, removed.
379 :revision: 0.7 / 2004-09-19 (*mhs*)
381 Fixed video standard selection, control enumeration, downscaling and
382 aspect example. Added read and user pointer i/o to video capture
386 :revision: 0.6 / 2004-08-01 (*mhs*)
388 v4l2_buffer changes, added video capture example, various corrections.
391 :revision: 0.5 / 2003-11-05 (*mhs*)
393 Pixel format erratum.
396 :revision: 0.4 / 2003-09-17 (*mhs*)
398 Corrected source and Makefile to generate a PDF. SGML fixes. Added
399 latest API changes. Closed gaps in the history chapter.
402 :revision: 0.3 / 2003-02-05 (*mhs*)
404 Another draft, more corrections.
407 :revision: 0.2 / 2003-01-15 (*mhs*)
409 Second draft, with corrections pointed out by Gerd Knorr.
412 :revision: 0.1 / 2002-12-01 (*mhs*)
414 First draft, based on documentation by Bill Dirks and discussions on the