0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. include:: <isonum.txt>
0003
0004 .. _v4l2spec:
0005
0006 ############################
0007 Part I - Video for Linux API
0008 ############################
0009
0010 This part describes the Video for Linux API version 2 (V4L2 API) specification.
0011
0012 **Revision 4.5**
0013
0014 .. only:: html
0015
0016 .. class:: toc-title
0017
0018 Table of Contents
0019
0020 .. toctree::
0021 :numbered:
0022 :maxdepth: 5
0023
0024 common
0025 pixfmt
0026 io
0027 devices
0028 libv4l
0029 compat
0030 user-func
0031 common-defs
0032 videodev
0033 capture-example
0034 v4l2grab-example
0035 biblio
0036
0037
0038 **********************
0039 Revision and Copyright
0040 **********************
0041
0042 Authors, in alphabetical order:
0043
0044 - Ailus, Sakari <sakari.ailus@iki.fi>
0045
0046 - Subdev selections API.
0047
0048 - Carvalho Chehab, Mauro <mchehab+samsung@kernel.org>
0049
0050 - Documented libv4l, designed and added v4l2grab example, Remote Controller chapter.
0051
0052 - Dirks, Bill
0053
0054 - Original author of the V4L2 API and documentation.
0055
0056 - Figa, Tomasz <tfiga@chromium.org>
0057
0058 - Documented the memory-to-memory decoder interface.
0059 - Documented the memory-to-memory encoder interface.
0060
0061 - H Schimek, Michael <mschimek@gmx.at>
0062
0063 - Original author of the V4L2 API and documentation.
0064
0065 - Karicheri, Muralidharan <m-karicheri2@ti.com>
0066
0067 - Documented the Digital Video timings API.
0068
0069 - Osciak, Pawel <posciak@chromium.org>
0070
0071 - Documented the memory-to-memory decoder interface.
0072 - Documented the memory-to-memory encoder interface.
0073
0074 - Osciak, Pawel <pawel@osciak.com>
0075
0076 - Designed and documented the multi-planar API.
0077
0078 - Palosaari, Antti <crope@iki.fi>
0079
0080 - SDR API.
0081
0082 - Ribalda, Ricardo
0083
0084 - Introduce HSV formats and other minor changes.
0085
0086 - Rubli, Martin
0087
0088 - Designed and documented the VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS ioctls.
0089
0090 - Walls, Andy <awalls@md.metrocast.net>
0091
0092 - Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV MPEG stream embedded, sliced VBI data format in this specification.
0093
0094 - Verkuil, Hans <hverkuil@xs4all.nl>
0095
0096 - 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.
0097
0098 **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
0099
0100 Except when explicitly stated as GPL, programming examples within this
0101 part can be used and distributed without restrictions.
0102
0103 ****************
0104 Revision History
0105 ****************
0106
0107 :revision: 4.10 / 2016-07-15 (*rr*)
0108
0109 Introduce HSV formats.
0110
0111
0112 :revision: 4.5 / 2015-10-29 (*rr*)
0113
0114 Extend VIDIOC_G_EXT_CTRLS;. Replace ctrl_class with a new union with
0115 ctrl_class and which. Which is used to select the current value of the
0116 control or the default value.
0117
0118
0119 :revision: 4.4 / 2015-05-26 (*ap*)
0120
0121 Renamed V4L2_TUNER_ADC to V4L2_TUNER_SDR. Added
0122 V4L2_CID_RF_TUNER_RF_GAIN control. Added transmitter support for
0123 Software Defined Radio (SDR) Interface.
0124
0125
0126 :revision: 4.1 / 2015-02-13 (*mcc*)
0127
0128 Fix documentation for media controller device nodes and add support for
0129 DVB device nodes. Add support for Tuner sub-device.
0130
0131
0132 :revision: 3.19 / 2014-12-05 (*hv*)
0133
0134 Rewrote Colorspace chapter, added new enum
0135 :c:type:`v4l2_ycbcr_encoding` and enum
0136 :c:type:`v4l2_quantization` fields to struct
0137 :c:type:`v4l2_pix_format`, struct
0138 :c:type:`v4l2_pix_format_mplane` and struct
0139 :c:type:`v4l2_mbus_framefmt`.
0140
0141
0142 :revision: 3.17 / 2014-08-04 (*lp, hv*)
0143
0144 Extended struct :c:type:`v4l2_pix_format`. Added
0145 format flags. Added compound control types and VIDIOC_QUERY_EXT_CTRL.
0146
0147
0148 :revision: 3.15 / 2014-02-03 (*hv, ap*)
0149
0150 Update several sections of "Common API Elements": "Opening and Closing
0151 Devices" "Querying Capabilities", "Application Priority", "Video Inputs
0152 and Outputs", "Audio Inputs and Outputs" "Tuners and Modulators", "Video
0153 Standards" and "Digital Video (DV) Timings". Added SDR API.
0154
0155
0156 :revision: 3.14 / 2013-11-25 (*rr*)
0157
0158 Set width and height as unsigned on v4l2_rect.
0159
0160
0161 :revision: 3.11 / 2013-05-26 (*hv*)
0162
0163 Remove obsolete VIDIOC_DBG_G_CHIP_IDENT ioctl.
0164
0165
0166 :revision: 3.10 / 2013-03-25 (*hv*)
0167
0168 Remove obsolete and unused DV_PRESET ioctls: VIDIOC_G_DV_PRESET,
0169 VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and
0170 VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output
0171 capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS.
0172 Added VIDIOC_DBG_G_CHIP_INFO.
0173
0174
0175 :revision: 3.9 / 2012-12-03 (*sa, sn*)
0176
0177 Added timestamp types to v4l2_buffer. Added
0178 V4L2_EVENT_CTRL_CH_RANGE control event changes flag.
0179
0180
0181 :revision: 3.6 / 2012-07-02 (*hv*)
0182
0183 Added VIDIOC_ENUM_FREQ_BANDS.
0184
0185
0186 :revision: 3.5 / 2012-05-07 (*sa, sn, hv*)
0187
0188 Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev selections API.
0189 Improved the description of V4L2_CID_COLORFX control, added
0190 V4L2_CID_COLORFX_CBCR control. Added camera controls
0191 V4L2_CID_AUTO_EXPOSURE_BIAS,
0192 V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE,
0193 V4L2_CID_IMAGE_STABILIZATION, V4L2_CID_ISO_SENSITIVITY,
0194 V4L2_CID_ISO_SENSITIVITY_AUTO, V4L2_CID_EXPOSURE_METERING,
0195 V4L2_CID_SCENE_MODE, V4L2_CID_3A_LOCK,
0196 V4L2_CID_AUTO_FOCUS_START, V4L2_CID_AUTO_FOCUS_STOP,
0197 V4L2_CID_AUTO_FOCUS_STATUS and V4L2_CID_AUTO_FOCUS_RANGE. Added
0198 VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and
0199 VIDIOC_DV_TIMINGS_CAP.
0200
0201
0202 :revision: 3.4 / 2012-01-25 (*sn*)
0203
0204 Added :ref:`JPEG compression control class. <jpeg-controls>`
0205
0206
0207 :revision: 3.3 / 2012-01-11 (*hv*)
0208
0209 Added device_caps field to struct v4l2_capabilities.
0210
0211
0212 :revision: 3.2 / 2011-08-26 (*hv*)
0213
0214 Added V4L2_CTRL_FLAG_VOLATILE.
0215
0216
0217 :revision: 3.1 / 2011-06-27 (*mcc, po, hv*)
0218
0219 Documented that VIDIOC_QUERYCAP now returns a per-subsystem version
0220 instead of a per-driver one. Standardize an error code for invalid
0221 ioctl. Added V4L2_CTRL_TYPE_BITMASK.
0222
0223
0224 :revision: 2.6.39 / 2011-03-01 (*mcc, po*)
0225
0226 Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect
0227 latest changes. Added the :ref:`multi-planar API <planar-apis>`.
0228
0229
0230 :revision: 2.6.37 / 2010-08-06 (*hv*)
0231
0232 Removed obsolete vtx (videotext) API.
0233
0234
0235 :revision: 2.6.33 / 2009-12-03 (*mk*)
0236
0237 Added documentation for the Digital Video timings API.
0238
0239
0240 :revision: 2.6.32 / 2009-08-31 (*mcc*)
0241
0242 Now, revisions will match the kernel version where the V4L2 API changes
0243 will be used by the Linux Kernel. Also added Remote Controller chapter.
0244
0245
0246 :revision: 0.29 / 2009-08-26 (*ev*)
0247
0248 Added documentation for string controls and for FM Transmitter controls.
0249
0250
0251 :revision: 0.28 / 2009-08-26 (*gl*)
0252
0253 Added V4L2_CID_BAND_STOP_FILTER documentation.
0254
0255
0256 :revision: 0.27 / 2009-08-15 (*mcc*)
0257
0258 Added libv4l and Remote Controller documentation; added v4l2grab and
0259 keytable application examples.
0260
0261
0262 :revision: 0.26 / 2009-07-23 (*hv*)
0263
0264 Finalized the RDS capture API. Added modulator and RDS encoder
0265 capabilities. Added support for string controls.
0266
0267
0268 :revision: 0.25 / 2009-01-18 (*hv*)
0269
0270 Added pixel formats VYUY, NV16 and NV61, and changed the debug ioctls
0271 VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT. Added camera
0272 controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE,
0273 V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY.
0274
0275
0276 :revision: 0.24 / 2008-03-04 (*mhs*)
0277
0278 Added pixel formats Y16 and SBGGR16, new controls and a camera controls
0279 class. Removed VIDIOC_G/S_MPEGCOMP.
0280
0281
0282 :revision: 0.23 / 2007-08-30 (*mhs*)
0283
0284 Fixed a typo in VIDIOC_DBG_G/S_REGISTER. Clarified the byte order of
0285 packed pixel formats.
0286
0287
0288 :revision: 0.22 / 2007-08-29 (*mhs*)
0289
0290 Added the Video Output Overlay interface, new MPEG controls,
0291 V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT,
0292 VIDIOC_DBG_G/S_REGISTER, VIDIOC\_(TRY\_)ENCODER_CMD,
0293 VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats.
0294 Clarifications in the cropping chapter, about RGB pixel formats, the
0295 mmap(), poll(), select(), read() and write() functions. Typographical
0296 fixes.
0297
0298
0299 :revision: 0.21 / 2006-12-19 (*mhs*)
0300
0301 Fixed a link in the VIDIOC_G_EXT_CTRLS section.
0302
0303
0304 :revision: 0.20 / 2006-11-24 (*mhs*)
0305
0306 Clarified the purpose of the audioset field in struct v4l2_input and
0307 v4l2_output.
0308
0309
0310 :revision: 0.19 / 2006-10-19 (*mhs*)
0311
0312 Documented V4L2_PIX_FMT_RGB444.
0313
0314
0315 :revision: 0.18 / 2006-10-18 (*mhs*)
0316
0317 Added the description of extended controls by Hans Verkuil. Linked
0318 V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.
0319
0320
0321 :revision: 0.17 / 2006-10-12 (*mhs*)
0322
0323 Corrected V4L2_PIX_FMT_HM12 description.
0324
0325
0326 :revision: 0.16 / 2006-10-08 (*mhs*)
0327
0328 VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS are now part
0329 of the API.
0330
0331
0332 :revision: 0.15 / 2006-09-23 (*mhs*)
0333
0334 Cleaned up the bibliography, added BT.653 and BT.1119.
0335 capture.c/start_capturing() for user pointer I/O did not initialize the
0336 buffer index. Documented the V4L MPEG and MJPEG VID_TYPEs and
0337 V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel formats. See
0338 the history chapter for API changes.
0339
0340
0341 :revision: 0.14 / 2006-09-14 (*mr*)
0342
0343 Added VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS proposal
0344 for frame format enumeration of digital devices.
0345
0346
0347 :revision: 0.13 / 2006-04-07 (*mhs*)
0348
0349 Corrected the description of struct v4l2_window clips. New V4L2_STD\_
0350 and V4L2_TUNER_MODE_LANG1_LANG2 defines.
0351
0352
0353 :revision: 0.12 / 2006-02-03 (*mhs*)
0354
0355 Corrected the description of struct v4l2_captureparm and
0356 v4l2_outputparm.
0357
0358
0359 :revision: 0.11 / 2006-01-27 (*mhs*)
0360
0361 Improved the description of struct v4l2_tuner.
0362
0363
0364 :revision: 0.10 / 2006-01-10 (*mhs*)
0365
0366 VIDIOC_G_INPUT and VIDIOC_S_PARM clarifications.
0367
0368
0369 :revision: 0.9 / 2005-11-27 (*mhs*)
0370
0371 Improved the 525 line numbering diagram. Hans Verkuil and I rewrote the
0372 sliced VBI section. He also contributed a VIDIOC_LOG_STATUS page.
0373 Fixed VIDIOC_S_STD call in the video standard selection example.
0374 Various updates.
0375
0376
0377 :revision: 0.8 / 2004-10-04 (*mhs*)
0378
0379 Somehow a piece of junk slipped into the capture example, removed.
0380
0381
0382 :revision: 0.7 / 2004-09-19 (*mhs*)
0383
0384 Fixed video standard selection, control enumeration, downscaling and
0385 aspect example. Added read and user pointer i/o to video capture
0386 example.
0387
0388
0389 :revision: 0.6 / 2004-08-01 (*mhs*)
0390
0391 v4l2_buffer changes, added video capture example, various corrections.
0392
0393
0394 :revision: 0.5 / 2003-11-05 (*mhs*)
0395
0396 Pixel format erratum.
0397
0398
0399 :revision: 0.4 / 2003-09-17 (*mhs*)
0400
0401 Corrected source and Makefile to generate a PDF. SGML fixes. Added
0402 latest API changes. Closed gaps in the history chapter.
0403
0404
0405 :revision: 0.3 / 2003-02-05 (*mhs*)
0406
0407 Another draft, more corrections.
0408
0409
0410 :revision: 0.2 / 2003-01-15 (*mhs*)
0411
0412 Second draft, with corrections pointed out by Gerd Knorr.
0413
0414
0415 :revision: 0.1 / 2002-12-01 (*mhs*)
0416
0417 First draft, based on documentation by Bill Dirks and discussions on the
0418 V4L mailing list.