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