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