[deliverable/linux.git] / Documentation / DocBook / media / v4l / v4l2.xml

 <partinfo>
    <authorgroup>
      <author>
	<firstname>Michael</firstname>
	<surname>Schimek</surname>
	<othername role="mi">H</othername>
	<affiliation>
	  <address>
	    <email>mschimek@gmx.at</email>
	  </address>
	</affiliation>
      </author>

      <author>
	<firstname>Bill</firstname>
	<surname>Dirks</surname>
	<!-- Commented until Bill opts in to be spammed.
	<affiliation>
	  <address>
	    <email>bill@thedirks.org</email>
	  </address>
	</affiliation> -->
	<contrib>Original author of the V4L2 API and
documentation.</contrib>
      </author>

      <author>
	<firstname>Hans</firstname>
	<surname>Verkuil</surname>
	<contrib>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.</contrib>
	<affiliation>
	  <address>
	    <email>hverkuil@xs4all.nl</email>
	  </address>
	</affiliation>
      </author>

      <author>
	<firstname>Martin</firstname>
	<surname>Rubli</surname>
	<!--
	<affiliation>
	  <address>
	    <email>martin_rubli@logitech.com</email>
	  </address>
	</affiliation> -->
	<contrib>Designed and documented the VIDIOC_ENUM_FRAMESIZES
and VIDIOC_ENUM_FRAMEINTERVALS ioctls.</contrib>
      </author>

      <author>
	<firstname>Andy</firstname>
	<surname>Walls</surname>
	<contrib>Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV
MPEG stream embedded, sliced VBI data format in this specification.
</contrib>
	<affiliation>
	  <address>
	    <email>awalls@md.metrocast.net</email>
	  </address>
	</affiliation>
      </author>

      <author>
	<firstname>Mauro</firstname>
	<surname>Carvalho Chehab</surname>
	<contrib>Documented libv4l, designed and added v4l2grab example,
Remote Controller chapter.</contrib>
	<affiliation>
	  <address>
	    <email>mchehab@redhat.com</email>
	  </address>
	</affiliation>
      </author>

      <author>
	<firstname>Muralidharan</firstname>
	<surname>Karicheri</surname>
	<contrib>Documented the Digital Video timings API.</contrib>
	<affiliation>
	  <address>
	    <email>m-karicheri2@ti.com</email>
	  </address>
	</affiliation>
      </author>

      <author>
	<firstname>Pawel</firstname>
	<surname>Osciak</surname>
	<contrib>Designed and documented the multi-planar API.</contrib>
	<affiliation>
	  <address>
	    <email>pawel AT osciak.com</email>
	  </address>
	</affiliation>
      </author>

      <author>
	<firstname>Sakari</firstname>
	<surname>Ailus</surname>
	<contrib>Subdev selections API.</contrib>
	<affiliation>
	  <address>
	    <email>sakari.ailus@iki.fi</email>
	  </address>
	</affiliation>
      </author>
    </authorgroup>

    <copyright>
      <year>1999</year>
      <year>2000</year>
      <year>2001</year>
      <year>2002</year>
      <year>2003</year>
      <year>2004</year>
      <year>2005</year>
      <year>2006</year>
      <year>2007</year>
      <year>2008</year>
      <year>2009</year>
      <year>2010</year>
      <year>2011</year>
      <year>2012</year>
      <holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin
Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab,
	Pawel Osciak</holder>
    </copyright>
    <legalnotice>
    <para>Except when explicitly stated as GPL, programming examples within
	    this part can be used and distributed without restrictions.</para>
    </legalnotice>
    <revhistory>
      <!-- Put document revisions here, newest first. -->
      <!-- API revisions (changes and additions of defines, enums,
structs, ioctls) must be noted in more detail in the history chapter
(compat.xml), along with the possible impact on existing drivers and
applications. -->

      <revision>
	<revnumber>3.5</revnumber>
	<date>2012-05-07</date>
	<authorinitials>sa, sn</authorinitials>
	<revremark>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.
	</revremark>
	<date>2012-05-01</date>
	<authorinitials>hv</authorinitials>
	<revremark>Added VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and
	VIDIOC_DV_TIMINGS_CAP.
	</revremark>
      </revision>

      <revision>
	<revnumber>3.4</revnumber>
	<date>2012-01-25</date>
	<authorinitials>sn</authorinitials>
	<revremark>Added <link linkend="jpeg-controls">JPEG compression
	    control class.</link>
	</revremark>
      </revision>

      <revision>
	<revnumber>3.3</revnumber>
	<date>2012-01-11</date>
	<authorinitials>hv</authorinitials>
	<revremark>Added device_caps field to struct v4l2_capabilities.</revremark>
      </revision>

      <revision>
	<revnumber>3.2</revnumber>
	<date>2011-08-26</date>
	<authorinitials>hv</authorinitials>
	<revremark>Added V4L2_CTRL_FLAG_VOLATILE.</revremark>
      </revision>

      <revision>
	<revnumber>3.1</revnumber>
	<date>2011-06-27</date>
	<authorinitials>mcc, po, hv</authorinitials>
	<revremark>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.</revremark>
      </revision>

      <revision>
	<revnumber>2.6.39</revnumber>
	<date>2011-03-01</date>
	<authorinitials>mcc, po</authorinitials>
	<revremark>Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect latest changes. Added the <link linkend="planar-apis">multi-planar API</link>.</revremark>
      </revision>

      <revision>
	<revnumber>2.6.37</revnumber>
	<date>2010-08-06</date>
	<authorinitials>hv</authorinitials>
	<revremark>Removed obsolete vtx (videotext) API.</revremark>
      </revision>

      <revision>
	<revnumber>2.6.33</revnumber>
	<date>2009-12-03</date>
	<authorinitials>mk</authorinitials>
	<revremark>Added documentation for the Digital Video timings API.</revremark>
      </revision>

      <revision>
	<revnumber>2.6.32</revnumber>
	<date>2009-08-31</date>
	<authorinitials>mcc</authorinitials>
	<revremark>Now, revisions will match the kernel version where
the V4L2 API changes will be used by the Linux Kernel.
Also added Remote Controller chapter.</revremark>
      </revision>

      <revision>
	<revnumber>0.29</revnumber>
	<date>2009-08-26</date>
	<authorinitials>ev</authorinitials>
	<revremark>Added documentation for string controls and for FM Transmitter controls.</revremark>
      </revision>

      <revision>
	<revnumber>0.28</revnumber>
	<date>2009-08-26</date>
	<authorinitials>gl</authorinitials>
	<revremark>Added V4L2_CID_BAND_STOP_FILTER documentation.</revremark>
      </revision>

      <revision>
	<revnumber>0.27</revnumber>
	<date>2009-08-15</date>
	<authorinitials>mcc</authorinitials>
	<revremark>Added libv4l and Remote Controller documentation;
added v4l2grab and keytable application examples.</revremark>
      </revision>

      <revision>
	<revnumber>0.26</revnumber>
	<date>2009-07-23</date>
	<authorinitials>hv</authorinitials>
	<revremark>Finalized the RDS capture API. Added modulator and RDS encoder
capabilities. Added support for string controls.</revremark>
      </revision>

      <revision>
	<revnumber>0.25</revnumber>
	<date>2009-01-18</date>
	<authorinitials>hv</authorinitials>
	<revremark>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.</revremark>
      </revision>

      <revision>
	<revnumber>0.24</revnumber>
	<date>2008-03-04</date>
	<authorinitials>mhs</authorinitials>
	<revremark>Added pixel formats Y16 and SBGGR16, new controls
and a camera controls class. Removed VIDIOC_G/S_MPEGCOMP.</revremark>
      </revision>

      <revision>
	<revnumber>0.23</revnumber>
	<date>2007-08-30</date>
	<authorinitials>mhs</authorinitials>
	<revremark>Fixed a typo in VIDIOC_DBG_G/S_REGISTER.
Clarified the byte order of packed pixel formats.</revremark>
      </revision>

      <revision>
	<revnumber>0.22</revnumber>
	<date>2007-08-29</date>
	<authorinitials>mhs</authorinitials>
	<revremark>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.</revremark>
      </revision>

      <revision>
	<revnumber>0.21</revnumber>
	<date>2006-12-19</date>
	<authorinitials>mhs</authorinitials>
	<revremark>Fixed a link in the VIDIOC_G_EXT_CTRLS section.</revremark>
      </revision>

      <revision>
	<revnumber>0.20</revnumber>
	<date>2006-11-24</date>
	<authorinitials>mhs</authorinitials>
	<revremark>Clarified the purpose of the audioset field in
struct v4l2_input and v4l2_output.</revremark>
      </revision>

      <revision>
	<revnumber>0.19</revnumber>
	<date>2006-10-19</date>
	<authorinitials>mhs</authorinitials>
	<revremark>Documented V4L2_PIX_FMT_RGB444.</revremark>
      </revision>

      <revision>
	<revnumber>0.18</revnumber>
	<date>2006-10-18</date>
	<authorinitials>mhs</authorinitials>
	<revremark>Added the description of extended controls by Hans
Verkuil. Linked V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.</revremark>
      </revision>

      <revision>
	<revnumber>0.17</revnumber>
	<date>2006-10-12</date>
	<authorinitials>mhs</authorinitials>
	<revremark>Corrected V4L2_PIX_FMT_HM12 description.</revremark>
      </revision>

      <revision>
	<revnumber>0.16</revnumber>
	<date>2006-10-08</date>
	<authorinitials>mhs</authorinitials>
	<revremark>VIDIOC_ENUM_FRAMESIZES and
VIDIOC_ENUM_FRAMEINTERVALS are now part of the API.</revremark>
      </revision>

      <revision>
	<revnumber>0.15</revnumber>
	<date>2006-09-23</date>
	<authorinitials>mhs</authorinitials>
	<revremark>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.</revremark>
      </revision>

      <revision>
	<revnumber>0.14</revnumber>
	<date>2006-09-14</date>
	<authorinitials>mr</authorinitials>
	<revremark>Added VIDIOC_ENUM_FRAMESIZES and
VIDIOC_ENUM_FRAMEINTERVALS proposal for frame format enumeration of
digital devices.</revremark>
      </revision>

      <revision>
	<revnumber>0.13</revnumber>
	<date>2006-04-07</date>
	<authorinitials>mhs</authorinitials>
	<revremark>Corrected the description of struct v4l2_window
clips. New V4L2_STD_ and V4L2_TUNER_MODE_LANG1_LANG2
defines.</revremark>
      </revision>

      <revision>
	<revnumber>0.12</revnumber>
	<date>2006-02-03</date>
	<authorinitials>mhs</authorinitials>
	<revremark>Corrected the description of struct
v4l2_captureparm and v4l2_outputparm.</revremark>
      </revision>

      <revision>
	<revnumber>0.11</revnumber>
	<date>2006-01-27</date>
	<authorinitials>mhs</authorinitials>
	<revremark>Improved the description of struct
v4l2_tuner.</revremark>
      </revision>

      <revision>
	<revnumber>0.10</revnumber>
	<date>2006-01-10</date>
	<authorinitials>mhs</authorinitials>
	<revremark>VIDIOC_G_INPUT and VIDIOC_S_PARM
clarifications.</revremark>
      </revision>

      <revision>
	<revnumber>0.9</revnumber>
	<date>2005-11-27</date>
	<authorinitials>mhs</authorinitials>
	<revremark>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.</revremark>
      </revision>

      <revision>
	<revnumber>0.8</revnumber>
	<date>2004-10-04</date>
	<authorinitials>mhs</authorinitials>
	<revremark>Somehow a piece of junk slipped into the capture
example, removed.</revremark>
      </revision>

      <revision>
	<revnumber>0.7</revnumber>
	<date>2004-09-19</date>
	<authorinitials>mhs</authorinitials>
	<revremark>Fixed video standard selection, control
enumeration, downscaling and aspect example. Added read and user
pointer i/o to video capture example.</revremark>
      </revision>

      <revision>
	<revnumber>0.6</revnumber>
	<date>2004-08-01</date>
	<authorinitials>mhs</authorinitials>
	<revremark>v4l2_buffer changes, added video capture example,
various corrections.</revremark>
      </revision>

      <revision>
	<revnumber>0.5</revnumber>
	<date>2003-11-05</date>
	<authorinitials>mhs</authorinitials>
	<revremark>Pixel format erratum.</revremark>
      </revision>

      <revision>
	<revnumber>0.4</revnumber>
	<date>2003-09-17</date>
	<authorinitials>mhs</authorinitials>
	<revremark>Corrected source and Makefile to generate a PDF.
SGML fixes. Added latest API changes. Closed gaps in the history
chapter.</revremark>
      </revision>

      <revision>
	<revnumber>0.3</revnumber>
	<date>2003-02-05</date>
	<authorinitials>mhs</authorinitials>
	<revremark>Another draft, more corrections.</revremark>
      </revision>

      <revision>
	<revnumber>0.2</revnumber>
	<date>2003-01-15</date>
	<authorinitials>mhs</authorinitials>
	<revremark>Second draft, with corrections pointed out by Gerd
Knorr.</revremark>
      </revision>

      <revision>
	<revnumber>0.1</revnumber>
	<date>2002-12-01</date>
	<authorinitials>mhs</authorinitials>
	<revremark>First draft, based on documentation by Bill Dirks
and discussions on the V4L mailing list.</revremark>
      </revision>
    </revhistory>
</partinfo>

<title>Video for Linux Two API Specification</title>
 <subtitle>Revision 3.5</subtitle>

  <chapter id="common">
    &sub-common;
  </chapter>

  <chapter id="pixfmt">
    &sub-pixfmt;
  </chapter>

  <chapter id="io">
    &sub-io;
  </chapter>

  <chapter id="devices">
    <title>Interfaces</title>

    <section id="capture"> &sub-dev-capture; </section>
    <section id="overlay"> &sub-dev-overlay; </section>
    <section id="output"> &sub-dev-output; </section>
    <section id="osd"> &sub-dev-osd; </section>
    <section id="codec"> &sub-dev-codec; </section>
    <section id="effect"> &sub-dev-effect; </section>
    <section id="raw-vbi"> &sub-dev-raw-vbi; </section>
    <section id="sliced"> &sub-dev-sliced-vbi; </section>
    <section id="ttx"> &sub-dev-teletext; </section>
    <section id="radio"> &sub-dev-radio; </section>
    <section id="rds"> &sub-dev-rds; </section>
    <section id="event"> &sub-dev-event; </section>
    <section id="subdev"> &sub-dev-subdev; </section>
  </chapter>

  <chapter id="driver">
	  &sub-driver;
  </chapter>

  <chapter id="libv4l">
	  &sub-libv4l;
  </chapter>

  <chapter id="compat">
	  &sub-compat;
  </chapter>

  <appendix id="user-func">
  <title>Function Reference</title>

    <!-- Keep this alphabetically sorted. -->

    &sub-close;
    &sub-ioctl;
    <!-- All ioctls go here. -->
    &sub-create-bufs;
    &sub-cropcap;
    &sub-dbg-g-chip-ident;
    &sub-dbg-g-register;
    &sub-decoder-cmd;
    &sub-dqevent;
    &sub-dv-timings-cap;
    &sub-encoder-cmd;
    &sub-enumaudio;
    &sub-enumaudioout;
    &sub-enum-dv-presets;
    &sub-enum-dv-timings;
    &sub-enum-fmt;
    &sub-enum-framesizes;
    &sub-enum-frameintervals;
    &sub-enuminput;
    &sub-enumoutput;
    &sub-enumstd;
    &sub-g-audio;
    &sub-g-audioout;
    &sub-g-crop;
    &sub-g-ctrl;
    &sub-g-dv-preset;
    &sub-g-dv-timings;
    &sub-g-enc-index;
    &sub-g-ext-ctrls;
    &sub-g-fbuf;
    &sub-g-fmt;
    &sub-g-frequency;
    &sub-g-input;
    &sub-g-jpegcomp;
    &sub-g-modulator;
    &sub-g-output;
    &sub-g-parm;
    &sub-g-priority;
    &sub-g-selection;
    &sub-g-sliced-vbi-cap;
    &sub-g-std;
    &sub-g-tuner;
    &sub-log-status;
    &sub-overlay;
    &sub-prepare-buf;
    &sub-qbuf;
    &sub-querybuf;
    &sub-querycap;
    &sub-queryctrl;
    &sub-query-dv-preset;
    &sub-query-dv-timings;
    &sub-querystd;
    &sub-reqbufs;
    &sub-s-hw-freq-seek;
    &sub-streamon;
    &sub-subdev-enum-frame-interval;
    &sub-subdev-enum-frame-size;
    &sub-subdev-enum-mbus-code;
    &sub-subdev-g-crop;
    &sub-subdev-g-fmt;
    &sub-subdev-g-frame-interval;
    &sub-subdev-g-selection;
    &sub-subscribe-event;
    <!-- End of ioctls. -->
    &sub-mmap;
    &sub-munmap;
    &sub-open;
    &sub-poll;
    &sub-read;
    &sub-select;
    &sub-write;
  </appendix>

  <appendix id="videodev">
    <title>Video For Linux Two Header File</title>
    &sub-videodev2-h;
  </appendix>

  <appendix id="capture-example">
    <title>Video Capture Example</title>
    &sub-capture-c;
  </appendix>

  <appendix id="v4l2grab-example">
    <title>Video Grabber example using libv4l</title>
    <para>This program demonstrates how to grab V4L2 images in ppm format by
using libv4l handlers. The advantage is that this grabber can potentially work
with any V4L2 driver.</para>
    &sub-v4l2grab-c;
  </appendix>

  &sub-media-indices;

  &sub-biblio;
Commit	Line	Data
8e080c2e MCC	1	<partinfo>
	2	<authorgroup>
	3	<author>
	4	<firstname>Michael</firstname>
	5	<surname>Schimek</surname>
	6	<othername role="mi">H</othername>
	7	<affiliation>
	8	<address>
	9	<email>mschimek@gmx.at</email>
	10	</address>
	11	</affiliation>
	12	</author>
	13
	14	<author>
	15	<firstname>Bill</firstname>
	16	<surname>Dirks</surname>
	17	<!-- Commented until Bill opts in to be spammed.
	18	<affiliation>
	19	<address>
	20	<email>bill@thedirks.org</email>
	21	</address>
	22	</affiliation> -->
	23	<contrib>Original author of the V4L2 API and
	24	documentation.</contrib>
	25	</author>
	26
	27	<author>
	28	<firstname>Hans</firstname>
	29	<surname>Verkuil</surname>
	30	<contrib>Designed and documented the VIDIOC_LOG_STATUS ioctl,
7dcc606b HV	31	the extended control ioctls, major parts of the sliced VBI API, the
7dcc606b HV	32	MPEG encoder and decoder APIs and the DV Timings API.</contrib>
8e080c2e MCC	33	<affiliation>
	34	<address>
	35	<email>hverkuil@xs4all.nl</email>
	36	</address>
	37	</affiliation>
	38	</author>
	39
	40	<author>
	41	<firstname>Martin</firstname>
	42	<surname>Rubli</surname>
	43	<!--
	44	<affiliation>
	45	<address>
	46	<email>martin_rubli@logitech.com</email>
	47	</address>
	48	</affiliation> -->
	49	<contrib>Designed and documented the VIDIOC_ENUM_FRAMESIZES
	50	and VIDIOC_ENUM_FRAMEINTERVALS ioctls.</contrib>
	51	</author>
	52
	53	<author>
	54	<firstname>Andy</firstname>
	55	<surname>Walls</surname>
	56	<contrib>Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV
	57	MPEG stream embedded, sliced VBI data format in this specification.
	58	</contrib>
	59	<affiliation>
	60	<address>
6afdeaf8	61	<email>awalls@md.metrocast.net</email>
8e080c2e MCC	62	</address>
	63	</affiliation>
	64	</author>
	65
	66	<author>
	67	<firstname>Mauro</firstname>
	68	<surname>Carvalho Chehab</surname>
	69	<contrib>Documented libv4l, designed and added v4l2grab example,
	70	Remote Controller chapter.</contrib>
	71	<affiliation>
	72	<address>
	73	<email>mchehab@redhat.com</email>
	74	</address>
	75	</affiliation>
	76	</author>
b33f5f8a HV	77
	78	<author>
	79	<firstname>Muralidharan</firstname>
	80	<surname>Karicheri</surname>
	81	<contrib>Documented the Digital Video timings API.</contrib>
	82	<affiliation>
	83	<address>
	84	<email>m-karicheri2@ti.com</email>
	85	</address>
	86	</affiliation>
	87	</author>
53b5d574 PO	88
53b5d574 PO	89	<author>
aec67f05	90	<firstname>Pawel</firstname>
53b5d574 PO	91	<surname>Osciak</surname>
	92	<contrib>Designed and documented the multi-planar API.</contrib>
	93	<affiliation>
	94	<address>
	95	<email>pawel AT osciak.com</email>
	96	</address>
	97	</affiliation>
	98	</author>
955f645a SA	99
	100	<author>
	101	<firstname>Sakari</firstname>
	102	<surname>Ailus</surname>
	103	<contrib>Subdev selections API.</contrib>
	104	<affiliation>
	105	<address>
	106	<email>sakari.ailus@iki.fi</email>
	107	</address>
	108	</affiliation>
	109	</author>
8e080c2e MCC	110	</authorgroup>
	111
	112	<copyright>
	113	<year>1999</year>
	114	<year>2000</year>
	115	<year>2001</year>
	116	<year>2002</year>
	117	<year>2003</year>
	118	<year>2004</year>
	119	<year>2005</year>
	120	<year>2006</year>
	121	<year>2007</year>
	122	<year>2008</year>
	123	<year>2009</year>
f44026db	124	<year>2010</year>
bda50bcd	125	<year>2011</year>
7dcc606b	126	<year>2012</year>
8e080c2e	127	<holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin
53b5d574 PO	128	Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab,
53b5d574 PO	129	Pawel Osciak</holder>
8e080c2e MCC	130	</copyright>
	131	<legalnotice>
	132	<para>Except when explicitly stated as GPL, programming examples within
	133	this part can be used and distributed without restrictions.</para>
	134	</legalnotice>
	135	<revhistory>
	136	<!-- Put document revisions here, newest first. -->
	137	<!-- API revisions (changes and additions of defines, enums,
	138	structs, ioctls) must be noted in more detail in the history chapter
f44026db	139	(compat.xml), along with the possible impact on existing drivers and
8e080c2e MCC	140	applications. -->
8e080c2e MCC	141
6ec299f3 SA	142	<revision>
6ec299f3 SA	143	<revnumber>3.5</revnumber>
2272ab65	144	<date>2012-05-07</date>
6491d1ad	145	<authorinitials>sa, sn</authorinitials>
955f645a	146	<revremark>Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev
6491d1ad SN	147	selections API. Improved the description of V4L2_CID_COLORFX
6491d1ad SN	148	control, added V4L2_CID_COLORFX_CBCR control.
2272ab65 SN	149	Added camera controls V4L2_CID_AUTO_EXPOSURE_BIAS,
	150	V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE, V4L2_CID_IMAGE_STABILIZATION,
	151	V4L2_CID_ISO_SENSITIVITY, V4L2_CID_ISO_SENSITIVITY_AUTO,
	152	V4L2_CID_EXPOSURE_METERING, V4L2_CID_SCENE_MODE,
	153	V4L2_CID_3A_LOCK, V4L2_CID_AUTO_FOCUS_START,
	154	V4L2_CID_AUTO_FOCUS_STOP, V4L2_CID_AUTO_FOCUS_STATUS
	155	and V4L2_CID_AUTO_FOCUS_RANGE.
6ec299f3	156	</revremark>
7dcc606b HV	157	<date>2012-05-01</date>
	158	<authorinitials>hv</authorinitials>
	159	<revremark>Added VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and
	160	VIDIOC_DV_TIMINGS_CAP.
	161	</revremark>
6ec299f3 SA	162	</revision>
6ec299f3 SA	163
29fa0eed SN	164	<revision>
	165	<revnumber>3.4</revnumber>
	166	<date>2012-01-25</date>
	167	<authorinitials>sn</authorinitials>
	168	<revremark>Added <link linkend="jpeg-controls">JPEG compression
	169	control class.</link>
	170	</revremark>
	171	</revision>
	172
583aa3a9 HV	173	<revision>
	174	<revnumber>3.3</revnumber>
	175	<date>2012-01-11</date>
	176	<authorinitials>hv</authorinitials>
	177	<revremark>Added device_caps field to struct v4l2_capabilities.</revremark>
	178	</revision>
	179
74a45790 HV	180	<revision>
	181	<revnumber>3.2</revnumber>
	182	<date>2011-08-26</date>
	183	<authorinitials>hv</authorinitials>
	184	<revremark>Added V4L2_CTRL_FLAG_VOLATILE.</revremark>
	185	</revision>
	186
c20eb18c MCC	187	<revision>
	188	<revnumber>3.1</revnumber>
	189	<date>2011-06-27</date>
aec67f05 HV	190	<authorinitials>mcc, po, hv</authorinitials>
	191	<revremark>Documented that VIDIOC_QUERYCAP now returns a per-subsystem version instead of a per-driver one.
	192	Standardize an error code for invalid ioctl.
	193	Added V4L2_CTRL_TYPE_BITMASK.</revremark>
c20eb18c	194	</revision>
9190d191	195
3822f18d MCC	196	<revision>
	197	<revnumber>2.6.39</revnumber>
	198	<date>2011-03-01</date>
f0e3b646 PO	199	<authorinitials>mcc, po</authorinitials>
f0e3b646 PO	200	<revremark>Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect latest changes. Added the <link linkend="planar-apis">multi-planar API</link>.</revremark>
53b5d574 PO	201	</revision>
53b5d574 PO	202
f44026db HV	203	<revision>
	204	<revnumber>2.6.37</revnumber>
	205	<date>2010-08-06</date>
	206	<authorinitials>hv</authorinitials>
	207	<revremark>Removed obsolete vtx (videotext) API.</revremark>
	208	</revision>
	209
b33f5f8a HV	210	<revision>
	211	<revnumber>2.6.33</revnumber>
	212	<date>2009-12-03</date>
	213	<authorinitials>mk</authorinitials>
	214	<revremark>Added documentation for the Digital Video timings API.</revremark>
	215	</revision>
	216
8e080c2e MCC	217	<revision>
	218	<revnumber>2.6.32</revnumber>
	219	<date>2009-08-31</date>
	220	<authorinitials>mcc</authorinitials>
	221	<revremark>Now, revisions will match the kernel version where
	222	the V4L2 API changes will be used by the Linux Kernel.
	223	Also added Remote Controller chapter.</revremark>
	224	</revision>
	225
	226	<revision>
	227	<revnumber>0.29</revnumber>
	228	<date>2009-08-26</date>
	229	<authorinitials>ev</authorinitials>
	230	<revremark>Added documentation for string controls and for FM Transmitter controls.</revremark>
	231	</revision>
	232
	233	<revision>
	234	<revnumber>0.28</revnumber>
	235	<date>2009-08-26</date>
	236	<authorinitials>gl</authorinitials>
	237	<revremark>Added V4L2_CID_BAND_STOP_FILTER documentation.</revremark>
	238	</revision>
	239
	240	<revision>
	241	<revnumber>0.27</revnumber>
	242	<date>2009-08-15</date>
	243	<authorinitials>mcc</authorinitials>
	244	<revremark>Added libv4l and Remote Controller documentation;
	245	added v4l2grab and keytable application examples.</revremark>
	246	</revision>
	247
	248	<revision>
	249	<revnumber>0.26</revnumber>
	250	<date>2009-07-23</date>
	251	<authorinitials>hv</authorinitials>
	252	<revremark>Finalized the RDS capture API. Added modulator and RDS encoder
	253	capabilities. Added support for string controls.</revremark>
	254	</revision>
	255
	256	<revision>
	257	<revnumber>0.25</revnumber>
	258	<date>2009-01-18</date>
	259	<authorinitials>hv</authorinitials>
	260	<revremark>Added pixel formats VYUY, NV16 and NV61, and changed
	261	the debug ioctls VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT.
	262	Added camera controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE,
	263	V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY.</revremark>
	264	</revision>
	265
	266	<revision>
	267	<revnumber>0.24</revnumber>
	268	<date>2008-03-04</date>
	269	<authorinitials>mhs</authorinitials>
	270	<revremark>Added pixel formats Y16 and SBGGR16, new controls
	271	and a camera controls class. Removed VIDIOC_G/S_MPEGCOMP.</revremark>
	272	</revision>
	273
	274	<revision>
	275	<revnumber>0.23</revnumber>
	276	<date>2007-08-30</date>
	277	<authorinitials>mhs</authorinitials>
	278	<revremark>Fixed a typo in VIDIOC_DBG_G/S_REGISTER.
	279	Clarified the byte order of packed pixel formats.</revremark>
	280	</revision>
281
282	<revision>
283	<revnumber>0.22</revnumber>
284	<date>2007-08-29</date>
285	<authorinitials>mhs</authorinitials>
286	<revremark>Added the Video Output Overlay interface, new MPEG
287	controls, V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT,
288	VIDIOC_DBG_G/S_REGISTER, VIDIOC_(TRY_)ENCODER_CMD,
289	VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats.
290	Clarifications in the cropping chapter, about RGB pixel formats, the
291	mmap(), poll(), select(), read() and write() functions. Typographical
292	fixes.</revremark>
293	</revision>
294
295	<revision>
296	<revnumber>0.21</revnumber>
297	<date>2006-12-19</date>
298	<authorinitials>mhs</authorinitials>
299	<revremark>Fixed a link in the VIDIOC_G_EXT_CTRLS section.</revremark>
300	</revision>
301
302	<revision>
303	<revnumber>0.20</revnumber>
304	<date>2006-11-24</date>
305	<authorinitials>mhs</authorinitials>
306	<revremark>Clarified the purpose of the audioset field in
307	struct v4l2_input and v4l2_output.</revremark>
308	</revision>
309
310	<revision>
311	<revnumber>0.19</revnumber>
312	<date>2006-10-19</date>
313	<authorinitials>mhs</authorinitials>
314	<revremark>Documented V4L2_PIX_FMT_RGB444.</revremark>
315	</revision>
316
317	<revision>
318	<revnumber>0.18</revnumber>
319	<date>2006-10-18</date>
320	<authorinitials>mhs</authorinitials>
321	<revremark>Added the description of extended controls by Hans
322	Verkuil. Linked V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.</revremark>
323	</revision>
324
325	<revision>
326	<revnumber>0.17</revnumber>
327	<date>2006-10-12</date>
328	<authorinitials>mhs</authorinitials>
329	<revremark>Corrected V4L2_PIX_FMT_HM12 description.</revremark>
330	</revision>
331
332	<revision>
333	<revnumber>0.16</revnumber>
334	<date>2006-10-08</date>
335	<authorinitials>mhs</authorinitials>
336	<revremark>VIDIOC_ENUM_FRAMESIZES and
337	VIDIOC_ENUM_FRAMEINTERVALS are now part of the API.</revremark>
338	</revision>
339
340	<revision>
341	<revnumber>0.15</revnumber>
342	<date>2006-09-23</date>
343	<authorinitials>mhs</authorinitials>
344	<revremark>Cleaned up the bibliography, added BT.653 and
345	BT.1119. capture.c/start_capturing() for user pointer I/O did not
346	initialize the buffer index. Documented the V4L MPEG and MJPEG
347	VID_TYPEs and V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel
348	formats. See the history chapter for API changes.</revremark>
349	</revision>
350
351	<revision>
352	<revnumber>0.14</revnumber>
353	<date>2006-09-14</date>
354	<authorinitials>mr</authorinitials>
355	<revremark>Added VIDIOC_ENUM_FRAMESIZES and
356	VIDIOC_ENUM_FRAMEINTERVALS proposal for frame format enumeration of
357	digital devices.</revremark>
358	</revision>
359
360	<revision>
361	<revnumber>0.13</revnumber>
362	<date>2006-04-07</date>
363	<authorinitials>mhs</authorinitials>
364	<revremark>Corrected the description of struct v4l2_window
365	clips. New V4L2_STD_ and V4L2_TUNER_MODE_LANG1_LANG2
366	defines.</revremark>
367	</revision>
368
369	<revision>
370	<revnumber>0.12</revnumber>
371	<date>2006-02-03</date>
372	<authorinitials>mhs</authorinitials>
373	<revremark>Corrected the description of struct
374	v4l2_captureparm and v4l2_outputparm.</revremark>
375	</revision>
376
377	<revision>
378	<revnumber>0.11</revnumber>
379	<date>2006-01-27</date>
380	<authorinitials>mhs</authorinitials>
381	<revremark>Improved the description of struct
382	v4l2_tuner.</revremark>
383	</revision>
384
385	<revision>
386	<revnumber>0.10</revnumber>
387	<date>2006-01-10</date>
388	<authorinitials>mhs</authorinitials>
389	<revremark>VIDIOC_G_INPUT and VIDIOC_S_PARM
390	clarifications.</revremark>
391	</revision>
392
393	<revision>
394	<revnumber>0.9</revnumber>
395	<date>2005-11-27</date>
396	<authorinitials>mhs</authorinitials>
397	<revremark>Improved the 525 line numbering diagram. Hans
398	Verkuil and I rewrote the sliced VBI section. He also contributed a
399	VIDIOC_LOG_STATUS page. Fixed VIDIOC_S_STD call in the video standard
400	selection example. Various updates.</revremark>
401	</revision>
402
403	<revision>
404	<revnumber>0.8</revnumber>
405	<date>2004-10-04</date>
406	<authorinitials>mhs</authorinitials>
407	<revremark>Somehow a piece of junk slipped into the capture
408	example, removed.</revremark>
409	</revision>
410
411	<revision>
412	<revnumber>0.7</revnumber>
413	<date>2004-09-19</date>
414	<authorinitials>mhs</authorinitials>
415	<revremark>Fixed video standard selection, control
416	enumeration, downscaling and aspect example. Added read and user
417	pointer i/o to video capture example.</revremark>
418	</revision>
419
420	<revision>
421	<revnumber>0.6</revnumber>
422	<date>2004-08-01</date>
423	<authorinitials>mhs</authorinitials>
424	<revremark>v4l2_buffer changes, added video capture example,
425	various corrections.</revremark>
426	</revision>
427
428	<revision>
429	<revnumber>0.5</revnumber>
430	<date>2003-11-05</date>
431	<authorinitials>mhs</authorinitials>
432	<revremark>Pixel format erratum.</revremark>
433	</revision>
434
435	<revision>
436	<revnumber>0.4</revnumber>
437	<date>2003-09-17</date>
438	<authorinitials>mhs</authorinitials>
439	<revremark>Corrected source and Makefile to generate a PDF.
440	SGML fixes. Added latest API changes. Closed gaps in the history
441	chapter.</revremark>
442	</revision>
443
444	<revision>
445	<revnumber>0.3</revnumber>
446	<date>2003-02-05</date>
447	<authorinitials>mhs</authorinitials>
448	<revremark>Another draft, more corrections.</revremark>
449	</revision>
450
451	<revision>
452	<revnumber>0.2</revnumber>
453	<date>2003-01-15</date>
454	<authorinitials>mhs</authorinitials>
455	<revremark>Second draft, with corrections pointed out by Gerd
456	Knorr.</revremark>
457	</revision>
458
459	<revision>
460	<revnumber>0.1</revnumber>
461	<date>2002-12-01</date>
462	<authorinitials>mhs</authorinitials>
463	<revremark>First draft, based on documentation by Bill Dirks
464	and discussions on the V4L mailing list.</revremark>
465	</revision>
466	</revhistory>
467	</partinfo>
468
469	<title>Video for Linux Two API Specification</title>
7dcc606b	470	<subtitle>Revision 3.5</subtitle>
8e080c2e MCC	471
	472	<chapter id="common">
	473	&sub-common;
	474	</chapter>
	475
	476	<chapter id="pixfmt">
	477	&sub-pixfmt;
	478	</chapter>
	479
	480	<chapter id="io">
	481	&sub-io;
	482	</chapter>
	483
	484	<chapter id="devices">
	485	<title>Interfaces</title>
	486
	487	<section id="capture"> &sub-dev-capture; </section>
	488	<section id="overlay"> &sub-dev-overlay; </section>
	489	<section id="output"> &sub-dev-output; </section>
	490	<section id="osd"> &sub-dev-osd; </section>
	491	<section id="codec"> &sub-dev-codec; </section>
	492	<section id="effect"> &sub-dev-effect; </section>
	493	<section id="raw-vbi"> &sub-dev-raw-vbi; </section>
	494	<section id="sliced"> &sub-dev-sliced-vbi; </section>
	495	<section id="ttx"> &sub-dev-teletext; </section>
	496	<section id="radio"> &sub-dev-radio; </section>
	497	<section id="rds"> &sub-dev-rds; </section>
dd966083	498	<section id="event"> &sub-dev-event; </section>
333c8b97	499	<section id="subdev"> &sub-dev-subdev; </section>
8e080c2e MCC	500	</chapter>
	501
	502	<chapter id="driver">
	503	&sub-driver;
	504	</chapter>
	505
	506	<chapter id="libv4l">
	507	&sub-libv4l;
	508	</chapter>
	509
	510	<chapter id="compat">
	511	&sub-compat;
	512	</chapter>
	513
db17ab98	514	<appendix id="user-func">
8e080c2e	515	<title>Function Reference</title>
8e080c2e MCC	516
	517	<!-- Keep this alphabetically sorted. -->
	518
	519	&sub-close;
	520	&sub-ioctl;
	521	<!-- All ioctls go here. -->
55093284	522	&sub-create-bufs;
8e080c2e MCC	523	&sub-cropcap;
	524	&sub-dbg-g-chip-ident;
	525	&sub-dbg-g-register;
6b4f1252	526	&sub-decoder-cmd;
dd966083	527	&sub-dqevent;
7dcc606b	528	&sub-dv-timings-cap;
8e080c2e MCC	529	&sub-encoder-cmd;
	530	&sub-enumaudio;
	531	&sub-enumaudioout;
007701e2	532	&sub-enum-dv-presets;
7dcc606b	533	&sub-enum-dv-timings;
8e080c2e MCC	534	&sub-enum-fmt;
	535	&sub-enum-framesizes;
	536	&sub-enum-frameintervals;
	537	&sub-enuminput;
	538	&sub-enumoutput;
	539	&sub-enumstd;
	540	&sub-g-audio;
	541	&sub-g-audioout;
	542	&sub-g-crop;
	543	&sub-g-ctrl;
007701e2 MK	544	&sub-g-dv-preset;
007701e2 MK	545	&sub-g-dv-timings;
8e080c2e MCC	546	&sub-g-enc-index;
	547	&sub-g-ext-ctrls;
	548	&sub-g-fbuf;
	549	&sub-g-fmt;
	550	&sub-g-frequency;
	551	&sub-g-input;
	552	&sub-g-jpegcomp;
	553	&sub-g-modulator;
	554	&sub-g-output;
	555	&sub-g-parm;
	556	&sub-g-priority;
8af4922f	557	&sub-g-selection;
8e080c2e MCC	558	&sub-g-sliced-vbi-cap;
	559	&sub-g-std;
	560	&sub-g-tuner;
	561	&sub-log-status;
	562	&sub-overlay;
87736df2	563	&sub-prepare-buf;
8e080c2e MCC	564	&sub-qbuf;
	565	&sub-querybuf;
	566	&sub-querycap;
	567	&sub-queryctrl;
007701e2	568	&sub-query-dv-preset;
7dcc606b	569	&sub-query-dv-timings;
8e080c2e MCC	570	&sub-querystd;
	571	&sub-reqbufs;
	572	&sub-s-hw-freq-seek;
	573	&sub-streamon;
35c3017a	574	&sub-subdev-enum-frame-interval;
333c8b97 LP	575	&sub-subdev-enum-frame-size;
333c8b97 LP	576	&sub-subdev-enum-mbus-code;
f6a5cb1b	577	&sub-subdev-g-crop;
333c8b97	578	&sub-subdev-g-fmt;
35c3017a	579	&sub-subdev-g-frame-interval;
955f645a	580	&sub-subdev-g-selection;
dd966083	581	&sub-subscribe-event;
8e080c2e MCC	582	<!-- End of ioctls. -->
	583	&sub-mmap;
	584	&sub-munmap;
	585	&sub-open;
	586	&sub-poll;
	587	&sub-read;
	588	&sub-select;
	589	&sub-write;
8e080c2e MCC	590	</appendix>
	591
	592	<appendix id="videodev">
	593	<title>Video For Linux Two Header File</title>
	594	&sub-videodev2-h;
	595	</appendix>
	596
	597	<appendix id="capture-example">
	598	<title>Video Capture Example</title>
	599	&sub-capture-c;
	600	</appendix>
	601
	602	<appendix id="v4l2grab-example">
	603	<title>Video Grabber example using libv4l</title>
	604	<para>This program demonstrates how to grab V4L2 images in ppm format by
	605	using libv4l handlers. The advantage is that this grabber can potentially work
	606	with any V4L2 driver.</para>
	607	&sub-v4l2grab-c;
	608	</appendix>
	609
	610	&sub-media-indices;
	611
	612	&sub-biblio;
	613