mirror of https://gitee.com/openkylin/linux.git
399 lines
9.8 KiB
ReStructuredText
399 lines
9.8 KiB
ReStructuredText
.. -*- coding: utf-8; mode: rst -*-
|
|
|
|
.. 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**
|
|
|
|
.. class:: toc-title
|
|
|
|
Table of Contents
|
|
|
|
.. toctree::
|
|
:numbered:
|
|
:maxdepth: 5
|
|
|
|
common
|
|
pixfmt
|
|
io
|
|
devices
|
|
driver
|
|
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 <m.chehab@kernel.org>
|
|
|
|
- Documented libv4l, designed and added v4l2grab example, Remote Controller chapter.
|
|
|
|
- Dirks, Bill
|
|
|
|
- Original author of the V4L2 API and documentation.
|
|
|
|
- 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 <pawel@osciak.com>
|
|
|
|
- Designed and documented the multi-planar API.
|
|
|
|
- Palosaari, Antti <crope@iki.fi>
|
|
|
|
- SDR API.
|
|
|
|
- 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-2016: Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, Pawel Osciak, Sakari Ailus & Antti Palosaari.
|
|
|
|
Except when explicitly stated as GPL, programming examples within this
|
|
part can be used and distributed without restrictions.
|
|
|
|
****************
|
|
Revision History
|
|
****************
|
|
|
|
: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
|
|
:ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>` and enum
|
|
:ref:`v4l2_quantization <v4l2-quantization>` fields to struct
|
|
:ref:`v4l2_pix_format <v4l2-pix-format>`, struct
|
|
:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` and struct
|
|
:ref:`v4l2_mbus_framefmt <v4l2-mbus-framefmt>`.
|
|
|
|
|
|
:revision: 3.17 / 2014-08-04 (*lp, hv*)
|
|
|
|
Extended struct :ref:`v4l2_pix_format <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.
|