| .. Permission is granted to copy, distribute and/or modify this |
| .. document under the terms of the GNU Free Documentation License, |
| .. Version 1.1 or any later version published by the Free Software |
| .. Foundation, with no Invariant Sections, no Front-Cover Texts |
| .. and no Back-Cover Texts. A copy of the license is included at |
| .. Documentation/userspace-api/media/fdl-appendix.rst. |
| .. |
| .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections |
| |
| .. include:: <isonum.txt> |
| .. _v4l2spec: |
| |
| ############################ |
| Part I - Video for Linux API |
| ############################ |
| |
| This part describes the Video for Linux API version 2 (V4L2 API) specification. |
| |
| **Revision 4.5** |
| |
| .. only:: html |
| |
| .. class:: toc-title |
| |
| Table of Contents |
| |
| .. toctree:: |
| :numbered: |
| :maxdepth: 5 |
| |
| common |
| pixfmt |
| io |
| devices |
| libv4l |
| compat |
| user-func |
| common-defs |
| videodev |
| capture-example |
| v4l2grab-example |
| biblio |
| |
| |
| ********************** |
| Revision and Copyright |
| ********************** |
| |
| Authors, in alphabetical order: |
| |
| - Ailus, Sakari <sakari.ailus@iki.fi> |
| |
| - Subdev selections API. |
| |
| - Carvalho Chehab, Mauro <mchehab+samsung@kernel.org> |
| |
| - Documented libv4l, designed and added v4l2grab example, Remote Controller chapter. |
| |
| - Dirks, Bill |
| |
| - Original author of the V4L2 API and documentation. |
| |
| - Figa, Tomasz <tfiga@chromium.org> |
| |
| - Documented the memory-to-memory decoder interface. |
| - Documented the memory-to-memory encoder interface. |
| |
| - H Schimek, Michael <mschimek@gmx.at> |
| |
| - Original author of the V4L2 API and documentation. |
| |
| - Karicheri, Muralidharan <m-karicheri2@ti.com> |
| |
| - Documented the Digital Video timings API. |
| |
| - Osciak, Pawel <posciak@chromium.org> |
| |
| - Documented the memory-to-memory decoder interface. |
| - Documented the memory-to-memory encoder interface. |
| |
| - Osciak, Pawel <pawel@osciak.com> |
| |
| - Designed and documented the multi-planar API. |
| |
| - Palosaari, Antti <crope@iki.fi> |
| |
| - SDR API. |
| |
| - Ribalda, Ricardo |
| |
| - Introduce HSV formats and other minor changes. |
| |
| - Rubli, Martin |
| |
| - Designed and documented the VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS ioctls. |
| |
| - Walls, Andy <awalls@md.metrocast.net> |
| |
| - Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV MPEG stream embedded, sliced VBI data format in this specification. |
| |
| - Verkuil, Hans <hverkuil@xs4all.nl> |
| |
| - 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. |
| |
| **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 |
| |
| Except when explicitly stated as GPL, programming examples within this |
| part can be used and distributed without restrictions. |
| |
| **************** |
| Revision History |
| **************** |
| |
| :revision: 4.10 / 2016-07-15 (*rr*) |
| |
| Introduce HSV formats. |
| |
| |
| :revision: 4.5 / 2015-10-29 (*rr*) |
| |
| Extend VIDIOC_G_EXT_CTRLS;. Replace ctrl_class with a new union with |
| ctrl_class and which. Which is used to select the current value of the |
| control or the default value. |
| |
| |
| :revision: 4.4 / 2015-05-26 (*ap*) |
| |
| Renamed V4L2_TUNER_ADC to V4L2_TUNER_SDR. Added |
| V4L2_CID_RF_TUNER_RF_GAIN control. Added transmitter support for |
| Software Defined Radio (SDR) Interface. |
| |
| |
| :revision: 4.1 / 2015-02-13 (*mcc*) |
| |
| Fix documentation for media controller device nodes and add support for |
| DVB device nodes. Add support for Tuner sub-device. |
| |
| |
| :revision: 3.19 / 2014-12-05 (*hv*) |
| |
| Rewrote Colorspace chapter, added new enum |
| :c:type:`v4l2_ycbcr_encoding` and enum |
| :c:type:`v4l2_quantization` fields to struct |
| :c:type:`v4l2_pix_format`, struct |
| :c:type:`v4l2_pix_format_mplane` and struct |
| :c:type:`v4l2_mbus_framefmt`. |
| |
| |
| :revision: 3.17 / 2014-08-04 (*lp, hv*) |
| |
| Extended struct :c:type:`v4l2_pix_format`. Added |
| format flags. Added compound control types and VIDIOC_QUERY_EXT_CTRL. |
| |
| |
| :revision: 3.15 / 2014-02-03 (*hv, ap*) |
| |
| Update several sections of "Common API Elements": "Opening and Closing |
| Devices" "Querying Capabilities", "Application Priority", "Video Inputs |
| and Outputs", "Audio Inputs and Outputs" "Tuners and Modulators", "Video |
| Standards" and "Digital Video (DV) Timings". Added SDR API. |
| |
| |
| :revision: 3.14 / 2013-11-25 (*rr*) |
| |
| Set width and height as unsigned on v4l2_rect. |
| |
| |
| :revision: 3.11 / 2013-05-26 (*hv*) |
| |
| Remove obsolete VIDIOC_DBG_G_CHIP_IDENT ioctl. |
| |
| |
| :revision: 3.10 / 2013-03-25 (*hv*) |
| |
| Remove obsolete and unused DV_PRESET ioctls: VIDIOC_G_DV_PRESET, |
| VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and |
| VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output |
| capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS. |
| Added VIDIOC_DBG_G_CHIP_INFO. |
| |
| |
| :revision: 3.9 / 2012-12-03 (*sa, sn*) |
| |
| Added timestamp types to v4l2_buffer. Added |
| V4L2_EVENT_CTRL_CH_RANGE control event changes flag. |
| |
| |
| :revision: 3.6 / 2012-07-02 (*hv*) |
| |
| Added VIDIOC_ENUM_FREQ_BANDS. |
| |
| |
| :revision: 3.5 / 2012-05-07 (*sa, sn, hv*) |
| |
| Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev selections API. |
| Improved the description of V4L2_CID_COLORFX control, added |
| V4L2_CID_COLORFX_CBCR control. Added camera controls |
| V4L2_CID_AUTO_EXPOSURE_BIAS, |
| V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE, |
| V4L2_CID_IMAGE_STABILIZATION, V4L2_CID_ISO_SENSITIVITY, |
| V4L2_CID_ISO_SENSITIVITY_AUTO, V4L2_CID_EXPOSURE_METERING, |
| V4L2_CID_SCENE_MODE, V4L2_CID_3A_LOCK, |
| V4L2_CID_AUTO_FOCUS_START, V4L2_CID_AUTO_FOCUS_STOP, |
| V4L2_CID_AUTO_FOCUS_STATUS and V4L2_CID_AUTO_FOCUS_RANGE. Added |
| VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and |
| VIDIOC_DV_TIMINGS_CAP. |
| |
| |
| :revision: 3.4 / 2012-01-25 (*sn*) |
| |
| Added :ref:`JPEG compression control class. <jpeg-controls>` |
| |
| |
| :revision: 3.3 / 2012-01-11 (*hv*) |
| |
| Added device_caps field to struct v4l2_capabilities. |
| |
| |
| :revision: 3.2 / 2011-08-26 (*hv*) |
| |
| Added V4L2_CTRL_FLAG_VOLATILE. |
| |
| |
| :revision: 3.1 / 2011-06-27 (*mcc, po, hv*) |
| |
| Documented that VIDIOC_QUERYCAP now returns a per-subsystem version |
| instead of a per-driver one. Standardize an error code for invalid |
| ioctl. Added V4L2_CTRL_TYPE_BITMASK. |
| |
| |
| :revision: 2.6.39 / 2011-03-01 (*mcc, po*) |
| |
| Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect |
| latest changes. Added the :ref:`multi-planar API <planar-apis>`. |
| |
| |
| :revision: 2.6.37 / 2010-08-06 (*hv*) |
| |
| Removed obsolete vtx (videotext) API. |
| |
| |
| :revision: 2.6.33 / 2009-12-03 (*mk*) |
| |
| Added documentation for the Digital Video timings API. |
| |
| |
| :revision: 2.6.32 / 2009-08-31 (*mcc*) |
| |
| Now, revisions will match the kernel version where the V4L2 API changes |
| will be used by the Linux Kernel. Also added Remote Controller chapter. |
| |
| |
| :revision: 0.29 / 2009-08-26 (*ev*) |
| |
| Added documentation for string controls and for FM Transmitter controls. |
| |
| |
| :revision: 0.28 / 2009-08-26 (*gl*) |
| |
| Added V4L2_CID_BAND_STOP_FILTER documentation. |
| |
| |
| :revision: 0.27 / 2009-08-15 (*mcc*) |
| |
| Added libv4l and Remote Controller documentation; added v4l2grab and |
| keytable application examples. |
| |
| |
| :revision: 0.26 / 2009-07-23 (*hv*) |
| |
| Finalized the RDS capture API. Added modulator and RDS encoder |
| capabilities. Added support for string controls. |
| |
| |
| :revision: 0.25 / 2009-01-18 (*hv*) |
| |
| Added pixel formats VYUY, NV16 and NV61, and changed the debug ioctls |
| VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT. Added camera |
| controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE, |
| V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY. |
| |
| |
| :revision: 0.24 / 2008-03-04 (*mhs*) |
| |
| Added pixel formats Y16 and SBGGR16, new controls and a camera controls |
| class. Removed VIDIOC_G/S_MPEGCOMP. |
| |
| |
| :revision: 0.23 / 2007-08-30 (*mhs*) |
| |
| Fixed a typo in VIDIOC_DBG_G/S_REGISTER. Clarified the byte order of |
| packed pixel formats. |
| |
| |
| :revision: 0.22 / 2007-08-29 (*mhs*) |
| |
| Added the Video Output Overlay interface, new MPEG controls, |
| V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT, |
| VIDIOC_DBG_G/S_REGISTER, VIDIOC\_(TRY\_)ENCODER_CMD, |
| VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats. |
| Clarifications in the cropping chapter, about RGB pixel formats, the |
| mmap(), poll(), select(), read() and write() functions. Typographical |
| fixes. |
| |
| |
| :revision: 0.21 / 2006-12-19 (*mhs*) |
| |
| Fixed a link in the VIDIOC_G_EXT_CTRLS section. |
| |
| |
| :revision: 0.20 / 2006-11-24 (*mhs*) |
| |
| Clarified the purpose of the audioset field in struct v4l2_input and |
| v4l2_output. |
| |
| |
| :revision: 0.19 / 2006-10-19 (*mhs*) |
| |
| Documented V4L2_PIX_FMT_RGB444. |
| |
| |
| :revision: 0.18 / 2006-10-18 (*mhs*) |
| |
| Added the description of extended controls by Hans Verkuil. Linked |
| V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE. |
| |
| |
| :revision: 0.17 / 2006-10-12 (*mhs*) |
| |
| Corrected V4L2_PIX_FMT_HM12 description. |
| |
| |
| :revision: 0.16 / 2006-10-08 (*mhs*) |
| |
| VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS are now part |
| of the API. |
| |
| |
| :revision: 0.15 / 2006-09-23 (*mhs*) |
| |
| Cleaned up the bibliography, added BT.653 and BT.1119. |
| capture.c/start_capturing() for user pointer I/O did not initialize the |
| buffer index. Documented the V4L MPEG and MJPEG VID_TYPEs and |
| V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel formats. See |
| the history chapter for API changes. |
| |
| |
| :revision: 0.14 / 2006-09-14 (*mr*) |
| |
| Added VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS proposal |
| for frame format enumeration of digital devices. |
| |
| |
| :revision: 0.13 / 2006-04-07 (*mhs*) |
| |
| Corrected the description of struct v4l2_window clips. New V4L2_STD\_ |
| and V4L2_TUNER_MODE_LANG1_LANG2 defines. |
| |
| |
| :revision: 0.12 / 2006-02-03 (*mhs*) |
| |
| Corrected the description of struct v4l2_captureparm and |
| v4l2_outputparm. |
| |
| |
| :revision: 0.11 / 2006-01-27 (*mhs*) |
| |
| Improved the description of struct v4l2_tuner. |
| |
| |
| :revision: 0.10 / 2006-01-10 (*mhs*) |
| |
| VIDIOC_G_INPUT and VIDIOC_S_PARM clarifications. |
| |
| |
| :revision: 0.9 / 2005-11-27 (*mhs*) |
| |
| Improved the 525 line numbering diagram. Hans Verkuil and I rewrote the |
| sliced VBI section. He also contributed a VIDIOC_LOG_STATUS page. |
| Fixed VIDIOC_S_STD call in the video standard selection example. |
| Various updates. |
| |
| |
| :revision: 0.8 / 2004-10-04 (*mhs*) |
| |
| Somehow a piece of junk slipped into the capture example, removed. |
| |
| |
| :revision: 0.7 / 2004-09-19 (*mhs*) |
| |
| Fixed video standard selection, control enumeration, downscaling and |
| aspect example. Added read and user pointer i/o to video capture |
| example. |
| |
| |
| :revision: 0.6 / 2004-08-01 (*mhs*) |
| |
| v4l2_buffer changes, added video capture example, various corrections. |
| |
| |
| :revision: 0.5 / 2003-11-05 (*mhs*) |
| |
| Pixel format erratum. |
| |
| |
| :revision: 0.4 / 2003-09-17 (*mhs*) |
| |
| Corrected source and Makefile to generate a PDF. SGML fixes. Added |
| latest API changes. Closed gaps in the history chapter. |
| |
| |
| :revision: 0.3 / 2003-02-05 (*mhs*) |
| |
| Another draft, more corrections. |
| |
| |
| :revision: 0.2 / 2003-01-15 (*mhs*) |
| |
| Second draft, with corrections pointed out by Gerd Knorr. |
| |
| |
| :revision: 0.1 / 2002-12-01 (*mhs*) |
| |
| First draft, based on documentation by Bill Dirks and discussions on the |
| V4L mailing list. |
