414 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. include:: <isonum.txt>3 4.. _v4l2spec:5 6############################7Part I - Video for Linux API8############################9 10This part describes the Video for Linux API version 2 (V4L2 API) specification.11 12**Revision 4.5**13 14.. toctree::15 :caption: Table of Contents16 :numbered:17 :maxdepth: 518 19 common20 pixfmt21 io22 devices23 libv4l24 compat25 user-func26 common-defs27 videodev28 capture-example29 v4l2grab-example30 biblio31 32 33**********************34Revision and Copyright35**********************36 37Authors, in alphabetical order:38 39- Ailus, Sakari <sakari.ailus@iki.fi>40 41 - Subdev selections API.42 43- Carvalho Chehab, Mauro <mchehab+samsung@kernel.org>44 45 - Documented libv4l, designed and added v4l2grab example, Remote Controller chapter.46 47- Dirks, Bill48 49 - Original author of the V4L2 API and documentation.50 51- Figa, Tomasz <tfiga@chromium.org>52 53 - Documented the memory-to-memory decoder interface.54 - Documented the memory-to-memory encoder interface.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 <posciak@chromium.org>65 66 - Documented the memory-to-memory decoder interface.67 - Documented the memory-to-memory encoder interface.68 69- Osciak, Pawel <pawel@osciak.com>70 71 - Designed and documented the multi-planar API.72 73- Palosaari, Antti <crope@iki.fi>74 75 - SDR API.76 77- Ribalda, Ricardo78 79 - Introduce HSV formats and other minor changes.80 81- Rubli, Martin82 83 - Designed and documented the VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS ioctls.84 85- Walls, Andy <awalls@md.metrocast.net>86 87 - Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV MPEG stream embedded, sliced VBI data format in this specification.88 89- Verkuil, Hans <hverkuil@xs4all.nl>90 91 - 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.92 93**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 Figa94 95Except when explicitly stated as GPL, programming examples within this96part can be used and distributed without restrictions.97 98****************99Revision History100****************101 102:revision: 4.10 / 2016-07-15 (*rr*)103 104Introduce HSV formats.105 106 107:revision: 4.5 / 2015-10-29 (*rr*)108 109Extend VIDIOC_G_EXT_CTRLS;. Replace ctrl_class with a new union with110ctrl_class and which. Which is used to select the current value of the111control or the default value.112 113 114:revision: 4.4 / 2015-05-26 (*ap*)115 116Renamed V4L2_TUNER_ADC to V4L2_TUNER_SDR. Added117V4L2_CID_RF_TUNER_RF_GAIN control. Added transmitter support for118Software Defined Radio (SDR) Interface.119 120 121:revision: 4.1 / 2015-02-13 (*mcc*)122 123Fix documentation for media controller device nodes and add support for124DVB device nodes. Add support for Tuner sub-device.125 126 127:revision: 3.19 / 2014-12-05 (*hv*)128 129Rewrote Colorspace chapter, added new enum130:c:type:`v4l2_ycbcr_encoding` and enum131:c:type:`v4l2_quantization` fields to struct132:c:type:`v4l2_pix_format`, struct133:c:type:`v4l2_pix_format_mplane` and struct134:c:type:`v4l2_mbus_framefmt`.135 136 137:revision: 3.17 / 2014-08-04 (*lp, hv*)138 139Extended struct :c:type:`v4l2_pix_format`. Added140format flags. Added compound control types and VIDIOC_QUERY_EXT_CTRL.141 142 143:revision: 3.15 / 2014-02-03 (*hv, ap*)144 145Update several sections of "Common API Elements": "Opening and Closing146Devices" "Querying Capabilities", "Application Priority", "Video Inputs147and Outputs", "Audio Inputs and Outputs" "Tuners and Modulators", "Video148Standards" and "Digital Video (DV) Timings". Added SDR API.149 150 151:revision: 3.14 / 2013-11-25 (*rr*)152 153Set width and height as unsigned on v4l2_rect.154 155 156:revision: 3.11 / 2013-05-26 (*hv*)157 158Remove obsolete VIDIOC_DBG_G_CHIP_IDENT ioctl.159 160 161:revision: 3.10 / 2013-03-25 (*hv*)162 163Remove obsolete and unused DV_PRESET ioctls: VIDIOC_G_DV_PRESET,164VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and165VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output166capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS.167Added VIDIOC_DBG_G_CHIP_INFO.168 169 170:revision: 3.9 / 2012-12-03 (*sa, sn*)171 172Added timestamp types to v4l2_buffer. Added173V4L2_EVENT_CTRL_CH_RANGE control event changes flag.174 175 176:revision: 3.6 / 2012-07-02 (*hv*)177 178Added VIDIOC_ENUM_FREQ_BANDS.179 180 181:revision: 3.5 / 2012-05-07 (*sa, sn, hv*)182 183Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev selections API.184Improved the description of V4L2_CID_COLORFX control, added185V4L2_CID_COLORFX_CBCR control. Added camera controls186V4L2_CID_AUTO_EXPOSURE_BIAS,187V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE,188V4L2_CID_IMAGE_STABILIZATION, V4L2_CID_ISO_SENSITIVITY,189V4L2_CID_ISO_SENSITIVITY_AUTO, V4L2_CID_EXPOSURE_METERING,190V4L2_CID_SCENE_MODE, V4L2_CID_3A_LOCK,191V4L2_CID_AUTO_FOCUS_START, V4L2_CID_AUTO_FOCUS_STOP,192V4L2_CID_AUTO_FOCUS_STATUS and V4L2_CID_AUTO_FOCUS_RANGE. Added193VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and194VIDIOC_DV_TIMINGS_CAP.195 196 197:revision: 3.4 / 2012-01-25 (*sn*)198 199Added :ref:`JPEG compression control class. <jpeg-controls>`200 201 202:revision: 3.3 / 2012-01-11 (*hv*)203 204Added device_caps field to struct v4l2_capabilities.205 206 207:revision: 3.2 / 2011-08-26 (*hv*)208 209Added V4L2_CTRL_FLAG_VOLATILE.210 211 212:revision: 3.1 / 2011-06-27 (*mcc, po, hv*)213 214Documented that VIDIOC_QUERYCAP now returns a per-subsystem version215instead of a per-driver one. Standardize an error code for invalid216ioctl. Added V4L2_CTRL_TYPE_BITMASK.217 218 219:revision: 2.6.39 / 2011-03-01 (*mcc, po*)220 221Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect222latest changes. Added the :ref:`multi-planar API <planar-apis>`.223 224 225:revision: 2.6.37 / 2010-08-06 (*hv*)226 227Removed obsolete vtx (videotext) API.228 229 230:revision: 2.6.33 / 2009-12-03 (*mk*)231 232Added documentation for the Digital Video timings API.233 234 235:revision: 2.6.32 / 2009-08-31 (*mcc*)236 237Now, revisions will match the kernel version where the V4L2 API changes238will be used by the Linux Kernel. Also added Remote Controller chapter.239 240 241:revision: 0.29 / 2009-08-26 (*ev*)242 243Added documentation for string controls and for FM Transmitter controls.244 245 246:revision: 0.28 / 2009-08-26 (*gl*)247 248Added V4L2_CID_BAND_STOP_FILTER documentation.249 250 251:revision: 0.27 / 2009-08-15 (*mcc*)252 253Added libv4l and Remote Controller documentation; added v4l2grab and254keytable application examples.255 256 257:revision: 0.26 / 2009-07-23 (*hv*)258 259Finalized the RDS capture API. Added modulator and RDS encoder260capabilities. Added support for string controls.261 262 263:revision: 0.25 / 2009-01-18 (*hv*)264 265Added pixel formats VYUY, NV16 and NV61, and changed the debug ioctls266VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT. Added camera267controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE,268V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY.269 270 271:revision: 0.24 / 2008-03-04 (*mhs*)272 273Added pixel formats Y16 and SBGGR16, new controls and a camera controls274class. Removed VIDIOC_G/S_MPEGCOMP.275 276 277:revision: 0.23 / 2007-08-30 (*mhs*)278 279Fixed a typo in VIDIOC_DBG_G/S_REGISTER. Clarified the byte order of280packed pixel formats.281 282 283:revision: 0.22 / 2007-08-29 (*mhs*)284 285Added the Video Output Overlay interface, new MPEG controls,286V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT,287VIDIOC_DBG_G/S_REGISTER, VIDIOC\_(TRY\_)ENCODER_CMD,288VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats.289Clarifications in the cropping chapter, about RGB pixel formats, the290mmap(), poll(), select(), read() and write() functions. Typographical291fixes.292 293 294:revision: 0.21 / 2006-12-19 (*mhs*)295 296Fixed a link in the VIDIOC_G_EXT_CTRLS section.297 298 299:revision: 0.20 / 2006-11-24 (*mhs*)300 301Clarified the purpose of the audioset field in struct v4l2_input and302v4l2_output.303 304 305:revision: 0.19 / 2006-10-19 (*mhs*)306 307Documented V4L2_PIX_FMT_RGB444.308 309 310:revision: 0.18 / 2006-10-18 (*mhs*)311 312Added the description of extended controls by Hans Verkuil. Linked313V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.314 315 316:revision: 0.17 / 2006-10-12 (*mhs*)317 318Corrected V4L2_PIX_FMT_HM12 description.319 320 321:revision: 0.16 / 2006-10-08 (*mhs*)322 323VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS are now part324of the API.325 326 327:revision: 0.15 / 2006-09-23 (*mhs*)328 329Cleaned up the bibliography, added BT.653 and BT.1119.330capture.c/start_capturing() for user pointer I/O did not initialize the331buffer index. Documented the V4L MPEG and MJPEG VID_TYPEs and332V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel formats. See333the history chapter for API changes.334 335 336:revision: 0.14 / 2006-09-14 (*mr*)337 338Added VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS proposal339for frame format enumeration of digital devices.340 341 342:revision: 0.13 / 2006-04-07 (*mhs*)343 344Corrected the description of struct v4l2_window clips. New V4L2_STD\_345and V4L2_TUNER_MODE_LANG1_LANG2 defines.346 347 348:revision: 0.12 / 2006-02-03 (*mhs*)349 350Corrected the description of struct v4l2_captureparm and351v4l2_outputparm.352 353 354:revision: 0.11 / 2006-01-27 (*mhs*)355 356Improved the description of struct v4l2_tuner.357 358 359:revision: 0.10 / 2006-01-10 (*mhs*)360 361VIDIOC_G_INPUT and VIDIOC_S_PARM clarifications.362 363 364:revision: 0.9 / 2005-11-27 (*mhs*)365 366Improved the 525 line numbering diagram. Hans Verkuil and I rewrote the367sliced VBI section. He also contributed a VIDIOC_LOG_STATUS page.368Fixed VIDIOC_S_STD call in the video standard selection example.369Various updates.370 371 372:revision: 0.8 / 2004-10-04 (*mhs*)373 374Somehow a piece of junk slipped into the capture example, removed.375 376 377:revision: 0.7 / 2004-09-19 (*mhs*)378 379Fixed video standard selection, control enumeration, downscaling and380aspect example. Added read and user pointer i/o to video capture381example.382 383 384:revision: 0.6 / 2004-08-01 (*mhs*)385 386v4l2_buffer changes, added video capture example, various corrections.387 388 389:revision: 0.5 / 2003-11-05 (*mhs*)390 391Pixel format erratum.392 393 394:revision: 0.4 / 2003-09-17 (*mhs*)395 396Corrected source and Makefile to generate a PDF. SGML fixes. Added397latest API changes. Closed gaps in the history chapter.398 399 400:revision: 0.3 / 2003-02-05 (*mhs*)401 402Another draft, more corrections.403 404 405:revision: 0.2 / 2003-01-15 (*mhs*)406 407Second draft, with corrections pointed out by Gerd Knorr.408 409 410:revision: 0.1 / 2002-12-01 (*mhs*)411 412First draft, based on documentation by Bill Dirks and discussions on the413V4L mailing list.414