Documentation/linux_tv/media/v4l/v4l2.rst

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