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

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