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