Back to home page

OSCL-LXR

 
 

    


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.