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/userspace-api/media/fdl-appendix.rst. 7.. 8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections 9 10.. include:: <isonum.txt> 11.. _v4l2spec: 12 13############################ 14Part I - Video for Linux API 15############################ 16 17This part describes the Video for Linux API version 2 (V4L2 API) specification. 18 19**Revision 4.5** 20 21.. only:: html 22 23 .. class:: toc-title 24 25 Table of Contents 26 27.. toctree:: 28 :numbered: 29 :maxdepth: 5 30 31 common 32 pixfmt 33 io 34 devices 35 libv4l 36 compat 37 user-func 38 common-defs 39 videodev 40 capture-example 41 v4l2grab-example 42 biblio 43 44 45********************** 46Revision and Copyright 47********************** 48 49Authors, in alphabetical order: 50 51- Ailus, Sakari <sakari.ailus@iki.fi> 52 53 - Subdev selections API. 54 55- Carvalho Chehab, Mauro <mchehab+samsung@kernel.org> 56 57 - Documented libv4l, designed and added v4l2grab example, Remote Controller chapter. 58 59- Dirks, Bill 60 61 - Original author of the V4L2 API and documentation. 62 63- Figa, Tomasz <tfiga@chromium.org> 64 65 - Documented the memory-to-memory decoder interface. 66 67- H Schimek, Michael <mschimek@gmx.at> 68 69 - Original author of the V4L2 API and documentation. 70 71- Karicheri, Muralidharan <m-karicheri2@ti.com> 72 73 - Documented the Digital Video timings API. 74 75- Osciak, Pawel <posciak@chromium.org> 76 77 - Documented the memory-to-memory decoder interface. 78 79- Osciak, Pawel <pawel@osciak.com> 80 81 - Designed and documented the multi-planar API. 82 83- Palosaari, Antti <crope@iki.fi> 84 85 - SDR API. 86 87- Ribalda, Ricardo 88 89 - Introduce HSV formats and other minor changes. 90 91- Rubli, Martin 92 93 - Designed and documented the VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS ioctls. 94 95- Walls, Andy <awalls@md.metrocast.net> 96 97 - Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV MPEG stream embedded, sliced VBI data format in this specification. 98 99- Verkuil, Hans <hverkuil@xs4all.nl> 100 101 - 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. 102 103**Copyright** |copy| 1999-2018: Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, Pawel Osciak, Sakari Ailus & Antti Palosaari, Tomasz Figa 104 105Except when explicitly stated as GPL, programming examples within this 106part can be used and distributed without restrictions. 107 108**************** 109Revision History 110**************** 111 112:revision: 4.10 / 2016-07-15 (*rr*) 113 114Introduce HSV formats. 115 116 117:revision: 4.5 / 2015-10-29 (*rr*) 118 119Extend VIDIOC_G_EXT_CTRLS;. Replace ctrl_class with a new union with 120ctrl_class and which. Which is used to select the current value of the 121control or the default value. 122 123 124:revision: 4.4 / 2015-05-26 (*ap*) 125 126Renamed V4L2_TUNER_ADC to V4L2_TUNER_SDR. Added 127V4L2_CID_RF_TUNER_RF_GAIN control. Added transmitter support for 128Software Defined Radio (SDR) Interface. 129 130 131:revision: 4.1 / 2015-02-13 (*mcc*) 132 133Fix documentation for media controller device nodes and add support for 134DVB device nodes. Add support for Tuner sub-device. 135 136 137:revision: 3.19 / 2014-12-05 (*hv*) 138 139Rewrote Colorspace chapter, added new enum 140:c:type:`v4l2_ycbcr_encoding` and enum 141:c:type:`v4l2_quantization` fields to struct 142:c:type:`v4l2_pix_format`, struct 143:c:type:`v4l2_pix_format_mplane` and struct 144:c:type:`v4l2_mbus_framefmt`. 145 146 147:revision: 3.17 / 2014-08-04 (*lp, hv*) 148 149Extended struct :c:type:`v4l2_pix_format`. Added 150format flags. Added compound control types and VIDIOC_QUERY_EXT_CTRL. 151 152 153:revision: 3.15 / 2014-02-03 (*hv, ap*) 154 155Update several sections of "Common API Elements": "Opening and Closing 156Devices" "Querying Capabilities", "Application Priority", "Video Inputs 157and Outputs", "Audio Inputs and Outputs" "Tuners and Modulators", "Video 158Standards" and "Digital Video (DV) Timings". Added SDR API. 159 160 161:revision: 3.14 / 2013-11-25 (*rr*) 162 163Set width and height as unsigned on v4l2_rect. 164 165 166:revision: 3.11 / 2013-05-26 (*hv*) 167 168Remove obsolete VIDIOC_DBG_G_CHIP_IDENT ioctl. 169 170 171:revision: 3.10 / 2013-03-25 (*hv*) 172 173Remove obsolete and unused DV_PRESET ioctls: VIDIOC_G_DV_PRESET, 174VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and 175VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output 176capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS. 177Added VIDIOC_DBG_G_CHIP_INFO. 178 179 180:revision: 3.9 / 2012-12-03 (*sa, sn*) 181 182Added timestamp types to v4l2_buffer. Added 183V4L2_EVENT_CTRL_CH_RANGE control event changes flag. 184 185 186:revision: 3.6 / 2012-07-02 (*hv*) 187 188Added VIDIOC_ENUM_FREQ_BANDS. 189 190 191:revision: 3.5 / 2012-05-07 (*sa, sn, hv*) 192 193Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev selections API. 194Improved the description of V4L2_CID_COLORFX control, added 195V4L2_CID_COLORFX_CBCR control. Added camera controls 196V4L2_CID_AUTO_EXPOSURE_BIAS, 197V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE, 198V4L2_CID_IMAGE_STABILIZATION, V4L2_CID_ISO_SENSITIVITY, 199V4L2_CID_ISO_SENSITIVITY_AUTO, V4L2_CID_EXPOSURE_METERING, 200V4L2_CID_SCENE_MODE, V4L2_CID_3A_LOCK, 201V4L2_CID_AUTO_FOCUS_START, V4L2_CID_AUTO_FOCUS_STOP, 202V4L2_CID_AUTO_FOCUS_STATUS and V4L2_CID_AUTO_FOCUS_RANGE. Added 203VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and 204VIDIOC_DV_TIMINGS_CAP. 205 206 207:revision: 3.4 / 2012-01-25 (*sn*) 208 209Added :ref:`JPEG compression control class. <jpeg-controls>` 210 211 212:revision: 3.3 / 2012-01-11 (*hv*) 213 214Added device_caps field to struct v4l2_capabilities. 215 216 217:revision: 3.2 / 2011-08-26 (*hv*) 218 219Added V4L2_CTRL_FLAG_VOLATILE. 220 221 222:revision: 3.1 / 2011-06-27 (*mcc, po, hv*) 223 224Documented that VIDIOC_QUERYCAP now returns a per-subsystem version 225instead of a per-driver one. Standardize an error code for invalid 226ioctl. Added V4L2_CTRL_TYPE_BITMASK. 227 228 229:revision: 2.6.39 / 2011-03-01 (*mcc, po*) 230 231Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect 232latest changes. Added the :ref:`multi-planar API <planar-apis>`. 233 234 235:revision: 2.6.37 / 2010-08-06 (*hv*) 236 237Removed obsolete vtx (videotext) API. 238 239 240:revision: 2.6.33 / 2009-12-03 (*mk*) 241 242Added documentation for the Digital Video timings API. 243 244 245:revision: 2.6.32 / 2009-08-31 (*mcc*) 246 247Now, revisions will match the kernel version where the V4L2 API changes 248will be used by the Linux Kernel. Also added Remote Controller chapter. 249 250 251:revision: 0.29 / 2009-08-26 (*ev*) 252 253Added documentation for string controls and for FM Transmitter controls. 254 255 256:revision: 0.28 / 2009-08-26 (*gl*) 257 258Added V4L2_CID_BAND_STOP_FILTER documentation. 259 260 261:revision: 0.27 / 2009-08-15 (*mcc*) 262 263Added libv4l and Remote Controller documentation; added v4l2grab and 264keytable application examples. 265 266 267:revision: 0.26 / 2009-07-23 (*hv*) 268 269Finalized the RDS capture API. Added modulator and RDS encoder 270capabilities. Added support for string controls. 271 272 273:revision: 0.25 / 2009-01-18 (*hv*) 274 275Added pixel formats VYUY, NV16 and NV61, and changed the debug ioctls 276VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT. Added camera 277controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE, 278V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY. 279 280 281:revision: 0.24 / 2008-03-04 (*mhs*) 282 283Added pixel formats Y16 and SBGGR16, new controls and a camera controls 284class. Removed VIDIOC_G/S_MPEGCOMP. 285 286 287:revision: 0.23 / 2007-08-30 (*mhs*) 288 289Fixed a typo in VIDIOC_DBG_G/S_REGISTER. Clarified the byte order of 290packed pixel formats. 291 292 293:revision: 0.22 / 2007-08-29 (*mhs*) 294 295Added the Video Output Overlay interface, new MPEG controls, 296V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT, 297VIDIOC_DBG_G/S_REGISTER, VIDIOC\_(TRY\_)ENCODER_CMD, 298VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats. 299Clarifications in the cropping chapter, about RGB pixel formats, the 300mmap(), poll(), select(), read() and write() functions. Typographical 301fixes. 302 303 304:revision: 0.21 / 2006-12-19 (*mhs*) 305 306Fixed a link in the VIDIOC_G_EXT_CTRLS section. 307 308 309:revision: 0.20 / 2006-11-24 (*mhs*) 310 311Clarified the purpose of the audioset field in struct v4l2_input and 312v4l2_output. 313 314 315:revision: 0.19 / 2006-10-19 (*mhs*) 316 317Documented V4L2_PIX_FMT_RGB444. 318 319 320:revision: 0.18 / 2006-10-18 (*mhs*) 321 322Added the description of extended controls by Hans Verkuil. Linked 323V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE. 324 325 326:revision: 0.17 / 2006-10-12 (*mhs*) 327 328Corrected V4L2_PIX_FMT_HM12 description. 329 330 331:revision: 0.16 / 2006-10-08 (*mhs*) 332 333VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS are now part 334of the API. 335 336 337:revision: 0.15 / 2006-09-23 (*mhs*) 338 339Cleaned up the bibliography, added BT.653 and BT.1119. 340capture.c/start_capturing() for user pointer I/O did not initialize the 341buffer index. Documented the V4L MPEG and MJPEG VID_TYPEs and 342V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel formats. See 343the history chapter for API changes. 344 345 346:revision: 0.14 / 2006-09-14 (*mr*) 347 348Added VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS proposal 349for frame format enumeration of digital devices. 350 351 352:revision: 0.13 / 2006-04-07 (*mhs*) 353 354Corrected the description of struct v4l2_window clips. New V4L2_STD\_ 355and V4L2_TUNER_MODE_LANG1_LANG2 defines. 356 357 358:revision: 0.12 / 2006-02-03 (*mhs*) 359 360Corrected the description of struct v4l2_captureparm and 361v4l2_outputparm. 362 363 364:revision: 0.11 / 2006-01-27 (*mhs*) 365 366Improved the description of struct v4l2_tuner. 367 368 369:revision: 0.10 / 2006-01-10 (*mhs*) 370 371VIDIOC_G_INPUT and VIDIOC_S_PARM clarifications. 372 373 374:revision: 0.9 / 2005-11-27 (*mhs*) 375 376Improved the 525 line numbering diagram. Hans Verkuil and I rewrote the 377sliced VBI section. He also contributed a VIDIOC_LOG_STATUS page. 378Fixed VIDIOC_S_STD call in the video standard selection example. 379Various updates. 380 381 382:revision: 0.8 / 2004-10-04 (*mhs*) 383 384Somehow a piece of junk slipped into the capture example, removed. 385 386 387:revision: 0.7 / 2004-09-19 (*mhs*) 388 389Fixed video standard selection, control enumeration, downscaling and 390aspect example. Added read and user pointer i/o to video capture 391example. 392 393 394:revision: 0.6 / 2004-08-01 (*mhs*) 395 396v4l2_buffer changes, added video capture example, various corrections. 397 398 399:revision: 0.5 / 2003-11-05 (*mhs*) 400 401Pixel format erratum. 402 403 404:revision: 0.4 / 2003-09-17 (*mhs*) 405 406Corrected source and Makefile to generate a PDF. SGML fixes. Added 407latest API changes. Closed gaps in the history chapter. 408 409 410:revision: 0.3 / 2003-02-05 (*mhs*) 411 412Another draft, more corrections. 413 414 415:revision: 0.2 / 2003-01-15 (*mhs*) 416 417Second draft, with corrections pointed out by Gerd Knorr. 418 419 420:revision: 0.1 / 2002-12-01 (*mhs*) 421 422First draft, based on documentation by Bill Dirks and discussions on the 423V4L mailing list. 424