2009-09-14 09:16:04 +08:00
<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,
2012-05-15 19:04:28 +08:00
the extended control ioctls, major parts of the sliced VBI API, the
MPEG encoder and decoder APIs and the DV Timings API.</contrib>
2009-09-14 09:16:04 +08:00
<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 >
2010-05-24 05:53:35 +08:00
<email > awalls@md.metrocast.net</email>
2009-09-14 09:16:04 +08:00
</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>
2009-12-03 12:32:12 +08:00
<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>
2011-01-07 12:41:33 +08:00
<author >
2011-05-23 18:36:55 +08:00
<firstname > Pawel</firstname>
2011-01-07 12:41:33 +08:00
<surname > Osciak</surname>
<contrib > Designed and documented the multi-planar API.</contrib>
<affiliation >
<address >
<email > pawel AT osciak.com</email>
</address>
</affiliation>
</author>
2011-12-13 05:17:25 +08:00
<author >
<firstname > Sakari</firstname>
<surname > Ailus</surname>
<contrib > Subdev selections API.</contrib>
<affiliation >
<address >
<email > sakari.ailus@iki.fi</email>
</address>
</affiliation>
</author>
2009-09-14 09:16:04 +08:00
</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>
2010-08-06 23:52:43 +08:00
<year > 2010</year>
2011-01-17 04:44:17 +08:00
<year > 2011</year>
2012-05-15 19:04:28 +08:00
<year > 2012</year>
2009-09-14 09:16:04 +08:00
<holder > Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin
2011-01-07 12:41:33 +08:00
Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab,
Pawel Osciak</holder>
2009-09-14 09:16:04 +08:00
</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
2010-08-06 23:52:43 +08:00
(compat.xml), along with the possible impact on existing drivers and
2009-09-14 09:16:04 +08:00
applications. -->
2011-08-07 03:13:47 +08:00
<revision >
2012-07-05 17:54:38 +08:00
<revnumber > 3.6</revnumber>
<date > 2012-07-02</date>
<authorinitials > hv</authorinitials>
<revremark > Added VIDIOC_ENUM_FREQ_BANDS.
</revremark>
2011-08-07 03:13:47 +08:00
<revnumber > 3.5</revnumber>
2012-05-11 17:37:03 +08:00
<date > 2012-05-07</date>
2012-04-02 17:40:19 +08:00
<authorinitials > sa, sn</authorinitials>
2011-12-13 05:17:25 +08:00
<revremark > Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev
2012-04-02 17:40:19 +08:00
selections API. Improved the description of V4L2_CID_COLORFX
control, added V4L2_CID_COLORFX_CBCR control.
2012-05-11 17:37:03 +08:00
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.
2011-08-07 03:13:47 +08:00
</revremark>
2012-05-15 19:04:28 +08:00
<date > 2012-05-01</date>
<authorinitials > hv</authorinitials>
<revremark > Added VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and
VIDIOC_DV_TIMINGS_CAP.
</revremark>
2011-08-07 03:13:47 +08:00
</revision>
2012-01-21 02:38:50 +08:00
<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>
2012-01-11 17:45:05 +08:00
<revision >
<revnumber > 3.3</revnumber>
<date > 2012-01-11</date>
<authorinitials > hv</authorinitials>
<revremark > Added device_caps field to struct v4l2_capabilities.</revremark>
</revision>
2011-08-26 18:31:13 +08:00
<revision >
<revnumber > 3.2</revnumber>
<date > 2011-08-26</date>
<authorinitials > hv</authorinitials>
<revremark > Added V4L2_CTRL_FLAG_VOLATILE.</revremark>
</revision>
2011-06-26 01:11:52 +08:00
<revision >
<revnumber > 3.1</revnumber>
<date > 2011-06-27</date>
2011-05-23 18:36:55 +08:00
<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>
2011-06-26 01:11:52 +08:00
</revision>
2011-07-07 01:08:08 +08:00
2011-03-02 03:03:11 +08:00
<revision >
<revnumber > 2.6.39</revnumber>
<date > 2011-03-01</date>
2011-03-14 02:20:22 +08:00
<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>
2011-01-07 12:41:33 +08:00
</revision>
2010-08-06 23:52:43 +08:00
<revision >
<revnumber > 2.6.37</revnumber>
<date > 2010-08-06</date>
<authorinitials > hv</authorinitials>
<revremark > Removed obsolete vtx (videotext) API.</revremark>
</revision>
2009-12-03 12:32:12 +08:00
<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>
2009-09-14 09:16:04 +08:00
<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>
2012-05-15 19:04:28 +08:00
<subtitle > Revision 3.5</subtitle>
2009-09-14 09:16:04 +08:00
<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>
2010-03-27 21:58:24 +08:00
<section id= "event" > &sub-dev-event; </section>
2010-03-16 07:26:04 +08:00
<section id= "subdev" > &sub-dev-subdev; </section>
2009-09-14 09:16:04 +08:00
</chapter>
<chapter id= "driver" >
&sub-driver;
</chapter>
<chapter id= "libv4l" >
&sub-libv4l;
</chapter>
<chapter id= "compat" >
&sub-compat;
</chapter>
2009-09-17 12:44:22 +08:00
<appendix id= "user-func" >
2009-09-14 09:16:04 +08:00
<title > Function Reference</title>
<!-- Keep this alphabetically sorted. -->
&sub-close;
&sub-ioctl;
<!-- All ioctls go here. -->
2011-09-28 19:10:58 +08:00
&sub-create-bufs;
2009-09-14 09:16:04 +08:00
&sub-cropcap;
&sub-dbg-g-chip-ident;
&sub-dbg-g-register;
2011-11-24 20:55:53 +08:00
&sub-decoder-cmd;
2010-03-27 21:58:24 +08:00
&sub-dqevent;
2012-05-15 19:04:28 +08:00
&sub-dv-timings-cap;
2009-09-14 09:16:04 +08:00
&sub-encoder-cmd;
&sub-enumaudio;
&sub-enumaudioout;
2009-12-03 12:13:17 +08:00
&sub-enum-dv-presets;
2012-05-15 19:04:28 +08:00
&sub-enum-dv-timings;
2009-09-14 09:16:04 +08:00
&sub-enum-fmt;
&sub-enum-framesizes;
&sub-enum-frameintervals;
2012-07-05 17:54:38 +08:00
&sub-enum-freq-bands;
2009-09-14 09:16:04 +08:00
&sub-enuminput;
&sub-enumoutput;
&sub-enumstd;
&sub-g-audio;
&sub-g-audioout;
&sub-g-crop;
&sub-g-ctrl;
2009-12-03 12:13:17 +08:00
&sub-g-dv-preset;
&sub-g-dv-timings;
2009-09-14 09:16:04 +08:00
&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;
2011-08-19 18:00:04 +08:00
&sub-g-selection;
2009-09-14 09:16:04 +08:00
&sub-g-sliced-vbi-cap;
&sub-g-std;
&sub-g-tuner;
&sub-log-status;
&sub-overlay;
2012-06-07 04:48:46 +08:00
&sub-prepare-buf;
2009-09-14 09:16:04 +08:00
&sub-qbuf;
&sub-querybuf;
&sub-querycap;
&sub-queryctrl;
2009-12-03 12:13:17 +08:00
&sub-query-dv-preset;
2012-05-15 19:04:28 +08:00
&sub-query-dv-timings;
2009-09-14 09:16:04 +08:00
&sub-querystd;
&sub-reqbufs;
&sub-s-hw-freq-seek;
&sub-streamon;
2010-05-05 22:38:35 +08:00
&sub-subdev-enum-frame-interval;
2010-03-16 07:26:04 +08:00
&sub-subdev-enum-frame-size;
&sub-subdev-enum-mbus-code;
2010-06-23 16:03:42 +08:00
&sub-subdev-g-crop;
2010-03-16 07:26:04 +08:00
&sub-subdev-g-fmt;
2010-05-05 22:38:35 +08:00
&sub-subdev-g-frame-interval;
2011-12-13 05:17:25 +08:00
&sub-subdev-g-selection;
2010-03-27 21:58:24 +08:00
&sub-subscribe-event;
2009-09-14 09:16:04 +08:00
<!-- End of ioctls. -->
&sub-mmap;
&sub-munmap;
&sub-open;
&sub-poll;
&sub-read;
&sub-select;
&sub-write;
</appendix>
2012-06-02 00:56:53 +08:00
<appendix >
<title > Common definitions for V4L2 and V4L2 subdev interfaces</title>
&sub-selections-common;
</appendix>
2009-09-14 09:16:04 +08:00
<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;