Documentation/media/uapi/v4l/v4l2.rst

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