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