Documentation/userspace-api/media/v4l/v4l2.rst

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