1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Chapter 7. Changes</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="LINUX MEDIA INFRASTRUCTURE API"><link rel="up" href="v4l2spec.html" title="Part I. Video for Linux Two API Specification"><link rel="prev" href="libv4l.html" title="Chapter 6. Libv4l Userspace Library"><link rel="next" href="hist-v4l2.html" title="Changes of the V4L2 API"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 7. Changes</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="libv4l.html">Prev</a> </td><th width="60%" align="center">Part I. Video for Linux Two API Specification</th><td width="20%" align="right"> <a accesskey="n" href="hist-v4l2.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="compat"></a>Chapter 7. Changes</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="compat.html#diff-v4l">Differences between V4L and V4L2</a></span></dt><dd><dl><dt><span class="section"><a href="compat.html#idp1110676308">Opening and Closing Devices</a></span></dt><dt><span class="section"><a href="compat.html#idp1110770580">Querying Capabilities</a></span></dt><dt><span class="section"><a href="compat.html#idp1110803716">Video Sources</a></span></dt><dt><span class="section"><a href="compat.html#idp1110817132">Tuning</a></span></dt><dt><span class="section"><a href="compat.html#v4l-image-properties">Image Properties</a></span></dt><dt><span class="section"><a href="compat.html#idp1110865172">Audio</a></span></dt><dt><span class="section"><a href="compat.html#idp1110884268">Frame Buffer Overlay</a></span></dt><dt><span class="section"><a href="compat.html#idp1110900244">Cropping</a></span></dt><dt><span class="section"><a href="compat.html#idp1110908652">Reading Images, Memory Mapping</a></span></dt><dt><span class="section"><a href="compat.html#idp1110929332">Reading Raw VBI Data</a></span></dt><dt><span class="section"><a href="compat.html#idp1110942012">Miscellaneous</a></span></dt></dl></dd><dt><span class="section"><a href="hist-v4l2.html">Changes of the V4L2 API</a></span></dt><dd><dl><dt><span class="section"><a href="hist-v4l2.html#idp1110945676">Early Versions</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1110958468">V4L2 Version 0.16 1999-01-31</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1110959340">V4L2 Version 0.18 1999-03-16</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1110960348">V4L2 Version 0.19 1999-06-05</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1110962996">V4L2 Version 0.20 (1999-09-10)</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1110980828">V4L2 Version 0.20 incremental changes</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1110995620">V4L2 Version 0.20 2000-11-23</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111004332">V4L2 Version 0.20 2002-07-25</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111004996">V4L2 in Linux 2.5.46, 2002-10</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111100852">V4L2 2003-06-19</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111111820">V4L2 2003-11-05</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111121164">V4L2 in Linux 2.6.6, 2004-05-09</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111123236">V4L2 in Linux 2.6.8</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111125988">V4L2 spec erratum 2004-08-01</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111130996">V4L2 in Linux 2.6.14</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111133420">V4L2 in Linux 2.6.15</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111140396">V4L2 spec erratum 2005-11-27</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111142844">V4L2 spec erratum 2006-01-10</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111145788">V4L2 spec erratum 2006-02-03</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111148124">V4L2 spec erratum 2006-02-04</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111150884">V4L2 in Linux 2.6.17</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111155580">V4L2 spec erratum 2006-09-23 (Draft 0.15)</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111165556">V4L2 in Linux 2.6.18</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111171276">V4L2 in Linux 2.6.19</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111177612">V4L2 spec erratum 2006-10-12 (Draft 0.17)</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111179340">V4L2 in Linux 2.6.21</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111181100">V4L2 in Linux 2.6.22</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111188468">V4L2 in Linux 2.6.24</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111190876">V4L2 in Linux 2.6.25</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111201596">V4L2 in Linux 2.6.26</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111204236">V4L2 in Linux 2.6.27</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111208412">V4L2 in Linux 2.6.28</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111211764">V4L2 in Linux 2.6.29</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111216916">V4L2 in Linux 2.6.30</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111219084">V4L2 in Linux 2.6.32</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111225356">V4L2 in Linux 2.6.33</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111226724">V4L2 in Linux 2.6.34</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111228972">V4L2 in Linux 2.6.37</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111230468">V4L2 in Linux 2.6.39</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111232748">V4L2 in Linux 3.1</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111234556">V4L2 in Linux 3.2</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111236916">V4L2 in Linux 3.3</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111239372">V4L2 in Linux 3.4</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111242884">V4L2 in Linux 3.5</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111252356">V4L2 in Linux 3.6</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111255244">V4L2 in Linux 3.9</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111259452">V4L2 in Linux 3.10</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111261356">V4L2 in Linux 3.11</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111263564">V4L2 in Linux 3.14</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111265788">V4L2 in Linux 3.15</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111267100">V4L2 in Linux 3.16</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111268356">V4L2 in Linux 3.17</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111270876">V4L2 in Linux 3.18</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#idp1111272724">V4L2 in Linux 3.19</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#other">Relation of V4L2 to other Linux multimedia APIs</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#experimental">Experimental API Elements</a></span></dt><dt><span class="section"><a href="hist-v4l2.html#obsolete">Obsolete API Elements</a></span></dt></dl></dd></dl></div><p>The following chapters document the evolution of the V4L2 API, 2errata or extensions. They are also intended to help application and 3driver writers to port or update their code.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="diff-v4l"></a>Differences between V4L and V4L2</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="compat.html#idp1110676308">Opening and Closing Devices</a></span></dt><dt><span class="section"><a href="compat.html#idp1110770580">Querying Capabilities</a></span></dt><dt><span class="section"><a href="compat.html#idp1110803716">Video Sources</a></span></dt><dt><span class="section"><a href="compat.html#idp1110817132">Tuning</a></span></dt><dt><span class="section"><a href="compat.html#v4l-image-properties">Image Properties</a></span></dt><dt><span class="section"><a href="compat.html#idp1110865172">Audio</a></span></dt><dt><span class="section"><a href="compat.html#idp1110884268">Frame Buffer Overlay</a></span></dt><dt><span class="section"><a href="compat.html#idp1110900244">Cropping</a></span></dt><dt><span class="section"><a href="compat.html#idp1110908652">Reading Images, Memory Mapping</a></span></dt><dt><span class="section"><a href="compat.html#idp1110929332">Reading Raw VBI Data</a></span></dt><dt><span class="section"><a href="compat.html#idp1110942012">Miscellaneous</a></span></dt></dl></div><p>The Video For Linux API was first introduced in Linux 2.1 to 4unify and replace various TV and radio device related interfaces, 5developed independently by driver writers in prior years. Starting 6with Linux 2.5 the much improved V4L2 API replaces the V4L API. 7The support for the old V4L calls were removed from Kernel, but the 8library <a class="xref" href="libv4l.html" title="Chapter 6. Libv4l Userspace Library">Chapter 6, <i>Libv4l Userspace Library</i></a> supports the conversion of a V4L 9API system call into a V4L2 one.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1110676308"></a>Opening and Closing Devices</h3></div></div></div><p>For compatibility reasons the character device file names 10recommended for V4L2 video capture, overlay, radio and raw 11vbi capture devices did not change from those used by V4L. They are 12listed in <a class="xref" href="devices.html" title="Chapter 4. Interfaces">Chapter 4, <i>Interfaces</i></a> and below in <a class="xref" href="compat.html#v4l-dev" title="Table 7.1. V4L Device Types, Names and Numbers">Table 7.1, “V4L Device Types, Names and Numbers”</a>.</p><p>The teletext devices (minor range 192-223) have been removed in 13V4L2 and no longer exist. There is no hardware available anymore for handling 14pure teletext. Instead raw or sliced VBI is used.</p><p>The V4L <code class="filename">videodev</code> module automatically 15assigns minor numbers to drivers in load order, depending on the 16registered device type. We recommend that V4L2 drivers by default 17register devices with the same numbers, but the system administrator 18can assign arbitrary minor numbers using driver module options. The 19major device number remains 81.</p><div class="table"><a name="v4l-dev"></a><p class="title"><b>Table 7.1. V4L Device Types, Names and Numbers</b></p><div class="table-contents"><table summary="V4L Device Types, Names and Numbers" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Device Type</th><th>File Name</th><th>Minor Numbers</th></tr></thead><tbody valign="top"><tr><td valign="top">Video capture and overlay</td><td valign="top"><p><code class="filename">/dev/video</code> and 20<code class="filename">/dev/bttv0</code><a href="#ftn.idp1110762068" class="footnote" name="idp1110762068"><sup class="footnote">[a]</sup></a>, 21<code class="filename">/dev/video0</code> to 22<code class="filename">/dev/video63</code></p></td><td valign="top">0-63</td></tr><tr><td valign="top">Radio receiver</td><td valign="top"><p><code class="filename">/dev/radio</code><a href="#ftn.idp1110764956" class="footnote" name="idp1110764956"><sup class="footnote">[b]</sup></a>, <code class="filename">/dev/radio0</code> to 23<code class="filename">/dev/radio63</code></p></td><td valign="top">64-127</td></tr><tr><td valign="top">Raw VBI capture</td><td valign="top"><p><code class="filename">/dev/vbi</code>, 24<code class="filename">/dev/vbi0</code> to 25<code class="filename">/dev/vbi31</code></p></td><td valign="top">224-255</td></tr></tbody><tbody class="footnotes"><tr><td colspan="3"><div id="ftn.idp1110762068" class="footnote"><p><a href="#idp1110762068" class="para"><sup class="para">[a] </sup></a>According to 26Documentation/devices.txt these should be symbolic links to 27<code class="filename">/dev/video0</code>. Note the original bttv interface is 28not compatible with V4L or V4L2.</p></div><div id="ftn.idp1110764956" class="footnote"><p><a href="#idp1110764956" class="para"><sup class="para">[b] </sup></a>According to 29<code class="filename">Documentation/devices.txt</code> a symbolic link to 30<code class="filename">/dev/radio0</code>.</p></div></td></tr></tbody></table></div></div><br class="table-break"><p>V4L prohibits (or used to prohibit) multiple opens of a 31device file. V4L2 drivers <span class="emphasis"><em>may</em></span> support multiple 32opens, see <a class="xref" href="common.html#open" title="Opening and Closing Devices">the section called “Opening and Closing Devices”</a> for details and consequences.</p><p>V4L drivers respond to V4L2 ioctls with an <span class="errorcode">EINVAL</span> error code.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1110770580"></a>Querying Capabilities</h3></div></div></div><p>The V4L <code class="constant">VIDIOCGCAP</code> ioctl is 33equivalent to V4L2's <a class="link" href="vidioc-querycap.html" title="ioctl VIDIOC_QUERYCAP"><code class="constant">VIDIOC_QUERYCAP</code></a>.</p><p>The <em class="structfield"><code>name</code></em> field in struct 34<span class="structname">video_capability</span> became 35<em class="structfield"><code>card</code></em> in struct <a class="link" href="vidioc-querycap.html#v4l2-capability" title="Table A.93. struct v4l2_capability">v4l2_capability</a>, 36<em class="structfield"><code>type</code></em> was replaced by 37<em class="structfield"><code>capabilities</code></em>. Note V4L2 does not 38distinguish between device types like this, better think of basic 39video input, video output and radio devices supporting a set of 40related functions like video capturing, video overlay and VBI 41capturing. See <a class="xref" href="common.html#open" title="Opening and Closing Devices">the section called “Opening and Closing Devices”</a> for an 42introduction.</p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>struct 43<span class="structname">video_capability</span> 44<em class="structfield"><code>type</code></em></th><th>struct <a class="link" href="vidioc-querycap.html#v4l2-capability" title="Table A.93. struct v4l2_capability">v4l2_capability</a> 45<em class="structfield"><code>capabilities</code></em> flags</th><th>Purpose</th></tr></thead><tbody valign="top"><tr><td valign="top"><code class="constant">VID_TYPE_CAPTURE</code></td><td valign="top"><code class="constant">V4L2_CAP_VIDEO_CAPTURE</code></td><td valign="top">The <a class="link" href="devices.html#capture" title="Video Capture Interface">video 46capture</a> interface is supported.</td></tr><tr><td valign="top"><code class="constant">VID_TYPE_TUNER</code></td><td valign="top"><code class="constant">V4L2_CAP_TUNER</code></td><td valign="top">The device has a <a class="link" href="tuner.html" title="Tuners and Modulators">tuner or 47modulator</a>.</td></tr><tr><td valign="top"><code class="constant">VID_TYPE_TELETEXT</code></td><td valign="top"><code class="constant">V4L2_CAP_VBI_CAPTURE</code></td><td valign="top">The <a class="link" href="raw-vbi.html" title="Raw VBI Data Interface">raw VBI 48capture</a> interface is supported.</td></tr><tr><td valign="top"><code class="constant">VID_TYPE_OVERLAY</code></td><td valign="top"><code class="constant">V4L2_CAP_VIDEO_OVERLAY</code></td><td valign="top">The <a class="link" href="overlay.html" title="Video Overlay Interface">video 49overlay</a> interface is supported.</td></tr><tr><td valign="top"><code class="constant">VID_TYPE_CHROMAKEY</code></td><td valign="top"><code class="constant">V4L2_FBUF_CAP_CHROMAKEY</code> in 50field <em class="structfield"><code>capability</code></em> of 51struct <a class="link" href="vidioc-g-fbuf.html#v4l2-framebuffer" title="Table A.69. struct v4l2_framebuffer">v4l2_framebuffer</a></td><td valign="top">Whether chromakey overlay is supported. For 52more information on overlay see 53<a class="xref" href="overlay.html" title="Video Overlay Interface">the section called “Video Overlay Interface”</a>.</td></tr><tr><td valign="top"><code class="constant">VID_TYPE_CLIPPING</code></td><td valign="top"><code class="constant">V4L2_FBUF_CAP_LIST_CLIPPING</code> 54and <code class="constant">V4L2_FBUF_CAP_BITMAP_CLIPPING</code> in field 55<em class="structfield"><code>capability</code></em> of struct <a class="link" href="vidioc-g-fbuf.html#v4l2-framebuffer" title="Table A.69. struct v4l2_framebuffer">v4l2_framebuffer</a></td><td valign="top">Whether clipping the overlaid image is 56supported, see <a class="xref" href="overlay.html" title="Video Overlay Interface">the section called “Video Overlay Interface”</a>.</td></tr><tr><td valign="top"><code class="constant">VID_TYPE_FRAMERAM</code></td><td valign="top"><code class="constant">V4L2_FBUF_CAP_EXTERNOVERLAY</code> 57<span class="emphasis"><em>not set</em></span> in field 58<em class="structfield"><code>capability</code></em> of struct <a class="link" href="vidioc-g-fbuf.html#v4l2-framebuffer" title="Table A.69. struct v4l2_framebuffer">v4l2_framebuffer</a></td><td valign="top">Whether overlay overwrites frame buffer memory, 59see <a class="xref" href="overlay.html" title="Video Overlay Interface">the section called “Video Overlay Interface”</a>.</td></tr><tr><td valign="top"><code class="constant">VID_TYPE_SCALES</code></td><td valign="top"><code class="constant">-</code></td><td valign="top">This flag indicates if the hardware can scale 60images. The V4L2 API implies the scale factor by setting the cropping 61dimensions and image size with the <a class="link" href="vidioc-g-crop.html" title="ioctl VIDIOC_G_CROP, VIDIOC_S_CROP"><code class="constant">VIDIOC_S_CROP</code></a> and <a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a> 62ioctl, respectively. The driver returns the closest sizes possible. 63For more information on cropping and scaling see <a class="xref" href="crop.html" title="Image Cropping, Insertion and Scaling">the section called “Image Cropping, Insertion and Scaling”</a>.</td></tr><tr><td valign="top"><code class="constant">VID_TYPE_MONOCHROME</code></td><td valign="top"><code class="constant">-</code></td><td valign="top">Applications can enumerate the supported image 64formats with the <a class="link" href="vidioc-enum-fmt.html" title="ioctl VIDIOC_ENUM_FMT"><code class="constant">VIDIOC_ENUM_FMT</code></a> ioctl to determine if the device 65supports grey scale capturing only. For more information on image 66formats see <a class="xref" href="pixfmt.html" title="Chapter 2. Image Formats">Chapter 2, <i>Image Formats</i></a>.</td></tr><tr><td valign="top"><code class="constant">VID_TYPE_SUBCAPTURE</code></td><td valign="top"><code class="constant">-</code></td><td valign="top">Applications can call the <a class="link" href="vidioc-g-crop.html" title="ioctl VIDIOC_G_CROP, VIDIOC_S_CROP"><code class="constant">VIDIOC_G_CROP</code></a> ioctl 67to determine if the device supports capturing a subsection of the full 68picture ("cropping" in V4L2). If not, the ioctl returns the <span class="errorcode">EINVAL</span> error code. 69For more information on cropping and scaling see <a class="xref" href="crop.html" title="Image Cropping, Insertion and Scaling">the section called “Image Cropping, Insertion and Scaling”</a>.</td></tr><tr><td valign="top"><code class="constant">VID_TYPE_MPEG_DECODER</code></td><td valign="top"><code class="constant">-</code></td><td valign="top">Applications can enumerate the supported image 70formats with the <a class="link" href="vidioc-enum-fmt.html" title="ioctl VIDIOC_ENUM_FMT"><code class="constant">VIDIOC_ENUM_FMT</code></a> ioctl to determine if the device 71supports MPEG streams.</td></tr><tr><td valign="top"><code class="constant">VID_TYPE_MPEG_ENCODER</code></td><td valign="top"><code class="constant">-</code></td><td valign="top">See above.</td></tr><tr><td valign="top"><code class="constant">VID_TYPE_MJPEG_DECODER</code></td><td valign="top"><code class="constant">-</code></td><td valign="top">See above.</td></tr><tr><td valign="top"><code class="constant">VID_TYPE_MJPEG_ENCODER</code></td><td valign="top"><code class="constant">-</code></td><td valign="top">See above.</td></tr></tbody></table></div><p>The <em class="structfield"><code>audios</code></em> field was replaced 72by <em class="structfield"><code>capabilities</code></em> flag 73<code class="constant">V4L2_CAP_AUDIO</code>, indicating 74<span class="emphasis"><em>if</em></span> the device has any audio inputs or outputs. To 75determine their number applications can enumerate audio inputs with 76the <a class="link" href="vidioc-g-audio.html" title="ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO"><code class="constant">VIDIOC_G_AUDIO</code></a> ioctl. The audio ioctls are described in <a class="xref" href="audio.html" title="Audio Inputs and Outputs">the section called “Audio Inputs and Outputs”</a>.</p><p>The <em class="structfield"><code>maxwidth</code></em>, 77<em class="structfield"><code>maxheight</code></em>, 78<em class="structfield"><code>minwidth</code></em> and 79<em class="structfield"><code>minheight</code></em> fields were removed. Calling the 80<a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a> or <a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_TRY_FMT</code></a> ioctl with the desired dimensions 81returns the closest size possible, taking into account the current 82video standard, cropping and scaling limitations.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1110803716"></a>Video Sources</h3></div></div></div><p>V4L provides the <code class="constant">VIDIOCGCHAN</code> and 83<code class="constant">VIDIOCSCHAN</code> ioctl using struct 84<span class="structname">video_channel</span> to enumerate 85the video inputs of a V4L device. The equivalent V4L2 ioctls 86are <a class="link" href="vidioc-enuminput.html" title="ioctl VIDIOC_ENUMINPUT"><code class="constant">VIDIOC_ENUMINPUT</code></a>, <a class="link" href="vidioc-g-input.html" title="ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT"><code class="constant">VIDIOC_G_INPUT</code></a> and <a class="link" href="vidioc-g-input.html" title="ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT"><code class="constant">VIDIOC_S_INPUT</code></a> 87using struct <a class="link" href="vidioc-enuminput.html#v4l2-input" title="Table A.39. struct v4l2_input">v4l2_input</a> as discussed in <a class="xref" href="video.html" title="Video Inputs and Outputs">the section called “Video Inputs and Outputs”</a>.</p><p>The <em class="structfield"><code>channel</code></em> field counting 88inputs was renamed to <em class="structfield"><code>index</code></em>, the video 89input types were renamed as follows: </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>struct <span class="structname">video_channel</span> 90<em class="structfield"><code>type</code></em></th><th>struct <a class="link" href="vidioc-enuminput.html#v4l2-input" title="Table A.39. struct v4l2_input">v4l2_input</a> 91<em class="structfield"><code>type</code></em></th></tr></thead><tbody valign="top"><tr><td valign="top"><code class="constant">VIDEO_TYPE_TV</code></td><td valign="top"><code class="constant">V4L2_INPUT_TYPE_TUNER</code></td></tr><tr><td valign="top"><code class="constant">VIDEO_TYPE_CAMERA</code></td><td valign="top"><code class="constant">V4L2_INPUT_TYPE_CAMERA</code></td></tr></tbody></table></div><p>Unlike the <em class="structfield"><code>tuners</code></em> field 92expressing the number of tuners of this input, V4L2 assumes each video 93input is connected to at most one tuner. However a tuner can have more 94than one input, i. e. RF connectors, and a device can have multiple 95tuners. The index number of the tuner associated with the input, if 96any, is stored in field <em class="structfield"><code>tuner</code></em> of 97struct <a class="link" href="vidioc-enuminput.html#v4l2-input" title="Table A.39. struct v4l2_input">v4l2_input</a>. Enumeration of tuners is discussed in <a class="xref" href="tuner.html" title="Tuners and Modulators">the section called “Tuners and Modulators”</a>.</p><p>The redundant <code class="constant">VIDEO_VC_TUNER</code> flag was 98dropped. Video inputs associated with a tuner are of type 99<code class="constant">V4L2_INPUT_TYPE_TUNER</code>. The 100<code class="constant">VIDEO_VC_AUDIO</code> flag was replaced by the 101<em class="structfield"><code>audioset</code></em> field. V4L2 considers devices with 102up to 32 audio inputs. Each set bit in the 103<em class="structfield"><code>audioset</code></em> field represents one audio input 104this video input combines with. For information about audio inputs and 105how to switch between them see <a class="xref" href="audio.html" title="Audio Inputs and Outputs">the section called “Audio Inputs and Outputs”</a>.</p><p>The <em class="structfield"><code>norm</code></em> field describing the 106supported video standards was replaced by 107<em class="structfield"><code>std</code></em>. The V4L specification mentions a flag 108<code class="constant">VIDEO_VC_NORM</code> indicating whether the standard can 109be changed. This flag was a later addition together with the 110<em class="structfield"><code>norm</code></em> field and has been removed in the 111meantime. V4L2 has a similar, albeit more comprehensive approach 112to video standards, see <a class="xref" href="standard.html" title="Video Standards">the section called “Video Standards”</a> for more 113information.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1110817132"></a>Tuning</h3></div></div></div><p>The V4L <code class="constant">VIDIOCGTUNER</code> and 114<code class="constant">VIDIOCSTUNER</code> ioctl and struct 115<span class="structname">video_tuner</span> can be used to enumerate the 116tuners of a V4L TV or radio device. The equivalent V4L2 ioctls are 117<a class="link" href="vidioc-g-tuner.html" title="ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER"><code class="constant">VIDIOC_G_TUNER</code></a> and <a class="link" href="vidioc-g-tuner.html" title="ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER"><code class="constant">VIDIOC_S_TUNER</code></a> using struct <a class="link" href="vidioc-g-tuner.html#v4l2-tuner" title="Table A.87. struct v4l2_tuner">v4l2_tuner</a>. Tuners are 118covered in <a class="xref" href="tuner.html" title="Tuners and Modulators">the section called “Tuners and Modulators”</a>.</p><p>The <em class="structfield"><code>tuner</code></em> field counting tuners 119was renamed to <em class="structfield"><code>index</code></em>. The fields 120<em class="structfield"><code>name</code></em>, <em class="structfield"><code>rangelow</code></em> 121and <em class="structfield"><code>rangehigh</code></em> remained unchanged.</p><p>The <code class="constant">VIDEO_TUNER_PAL</code>, 122<code class="constant">VIDEO_TUNER_NTSC</code> and 123<code class="constant">VIDEO_TUNER_SECAM</code> flags indicating the supported 124video standards were dropped. This information is now contained in the 125associated struct <a class="link" href="vidioc-enuminput.html#v4l2-input" title="Table A.39. struct v4l2_input">v4l2_input</a>. No replacement exists for the 126<code class="constant">VIDEO_TUNER_NORM</code> flag indicating whether the 127video standard can be switched. The <em class="structfield"><code>mode</code></em> 128field to select a different video standard was replaced by a whole new 129set of ioctls and structures described in <a class="xref" href="standard.html" title="Video Standards">the section called “Video Standards”</a>. 130Due to its ubiquity it should be mentioned the BTTV driver supports 131several standards in addition to the regular 132<code class="constant">VIDEO_MODE_PAL</code> (0), 133<code class="constant">VIDEO_MODE_NTSC</code>, 134<code class="constant">VIDEO_MODE_SECAM</code> and 135<code class="constant">VIDEO_MODE_AUTO</code> (3). Namely N/PAL Argentina, 136M/PAL, N/PAL, and NTSC Japan with numbers 3-6 (sic).</p><p>The <code class="constant">VIDEO_TUNER_STEREO_ON</code> flag 137indicating stereo reception became 138<code class="constant">V4L2_TUNER_SUB_STEREO</code> in field 139<em class="structfield"><code>rxsubchans</code></em>. This field also permits the 140detection of monaural and bilingual audio, see the definition of 141struct <a class="link" href="vidioc-g-tuner.html#v4l2-tuner" title="Table A.87. struct v4l2_tuner">v4l2_tuner</a> for details. Presently no replacement exists for the 142<code class="constant">VIDEO_TUNER_RDS_ON</code> and 143<code class="constant">VIDEO_TUNER_MBS_ON</code> flags.</p><p> The <code class="constant">VIDEO_TUNER_LOW</code> flag was renamed 144to <code class="constant">V4L2_TUNER_CAP_LOW</code> in the struct <a class="link" href="vidioc-g-tuner.html#v4l2-tuner" title="Table A.87. struct v4l2_tuner">v4l2_tuner</a> 145<em class="structfield"><code>capability</code></em> field.</p><p>The <code class="constant">VIDIOCGFREQ</code> and 146<code class="constant">VIDIOCSFREQ</code> ioctl to change the tuner frequency 147where renamed to <a class="link" href="vidioc-g-frequency.html" title="ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY"><code class="constant">VIDIOC_G_FREQUENCY</code></a> and <a class="link" href="vidioc-g-frequency.html" title="ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY"><code class="constant">VIDIOC_S_FREQUENCY</code></a>. They 148take a pointer to a struct <a class="link" href="vidioc-g-frequency.html#v4l2-frequency" title="Table A.73. struct v4l2_frequency">v4l2_frequency</a> instead of an unsigned long 149integer.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="v4l-image-properties"></a>Image Properties</h3></div></div></div><p>V4L2 has no equivalent of the 150<code class="constant">VIDIOCGPICT</code> and <code class="constant">VIDIOCSPICT</code> 151ioctl and struct <span class="structname">video_picture</span>. The following 152fields where replaced by V4L2 controls accessible with the 153<a class="link" href="vidioc-queryctrl.html" title="ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU"><code class="constant">VIDIOC_QUERYCTRL</code></a>, <a class="link" href="vidioc-g-ctrl.html" title="ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL"><code class="constant">VIDIOC_G_CTRL</code></a> and <a class="link" href="vidioc-g-ctrl.html" title="ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL"><code class="constant">VIDIOC_S_CTRL</code></a> ioctls:</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>struct <span class="structname">video_picture</span></th><th>V4L2 Control ID</th></tr></thead><tbody valign="top"><tr><td valign="top"><em class="structfield"><code>brightness</code></em></td><td valign="top"><code class="constant">V4L2_CID_BRIGHTNESS</code></td></tr><tr><td valign="top"><em class="structfield"><code>hue</code></em></td><td valign="top"><code class="constant">V4L2_CID_HUE</code></td></tr><tr><td valign="top"><em class="structfield"><code>colour</code></em></td><td valign="top"><code class="constant">V4L2_CID_SATURATION</code></td></tr><tr><td valign="top"><em class="structfield"><code>contrast</code></em></td><td valign="top"><code class="constant">V4L2_CID_CONTRAST</code></td></tr><tr><td valign="top"><em class="structfield"><code>whiteness</code></em></td><td valign="top"><code class="constant">V4L2_CID_WHITENESS</code></td></tr></tbody></table></div><p>The V4L picture controls are assumed to range from 0 to 15465535 with no particular reset value. The V4L2 API permits arbitrary 155limits and defaults which can be queried with the <a class="link" href="vidioc-queryctrl.html" title="ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU"><code class="constant">VIDIOC_QUERYCTRL</code></a> 156ioctl. For general information about controls see <a class="xref" href="control.html" title="User Controls">the section called “User Controls”</a>.</p><p>The <em class="structfield"><code>depth</code></em> (average number of 157bits per pixel) of a video image is implied by the selected image 158format. V4L2 does not explicitly provide such information assuming 159applications recognizing the format are aware of the image depth and 160others need not know. The <em class="structfield"><code>palette</code></em> field 161moved into the struct <a class="link" href="pixfmt.html#v4l2-pix-format" title="Table 2.1. struct v4l2_pix_format">v4l2_pix_format</a>:</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>struct <span class="structname">video_picture</span> 162<em class="structfield"><code>palette</code></em></th><th>struct <a class="link" href="pixfmt.html#v4l2-pix-format" title="Table 2.1. struct v4l2_pix_format">v4l2_pix_format</a> 163<em class="structfield"><code>pixfmt</code></em></th></tr></thead><tbody valign="top"><tr><td valign="top"><code class="constant">VIDEO_PALETTE_GREY</code></td><td valign="top"><p><a class="link" href="V4L2-PIX-FMT-GREY.html" title="V4L2_PIX_FMT_GREY ('GREY')"><code class="constant">V4L2_PIX_FMT_GREY</code></a></p></td></tr><tr><td valign="top"><code class="constant">VIDEO_PALETTE_HI240</code></td><td valign="top"><p><a class="link" href="pixfmt-reserved.html" title="Reserved Format Identifiers"><code class="constant">V4L2_PIX_FMT_HI240</code></a><a href="#ftn.idp1110845300" class="footnote" name="idp1110845300"><sup class="footnote">[a]</sup></a></p></td></tr><tr><td valign="top"><code class="constant">VIDEO_PALETTE_RGB565</code></td><td valign="top"><p><a class="link" href="pixfmt-rgb.html" title="RGB Formats"><code class="constant">V4L2_PIX_FMT_RGB565</code></a></p></td></tr><tr><td valign="top"><code class="constant">VIDEO_PALETTE_RGB555</code></td><td valign="top"><p><a class="link" href="pixfmt-rgb.html" title="RGB Formats"><code class="constant">V4L2_PIX_FMT_RGB555</code></a></p></td></tr><tr><td valign="top"><code class="constant">VIDEO_PALETTE_RGB24</code></td><td valign="top"><p><a class="link" href="pixfmt-rgb.html" title="RGB Formats"><code class="constant">V4L2_PIX_FMT_BGR24</code></a></p></td></tr><tr><td valign="top"><code class="constant">VIDEO_PALETTE_RGB32</code></td><td valign="top"><p><a class="link" href="pixfmt-rgb.html" title="RGB Formats"><code class="constant">V4L2_PIX_FMT_BGR32</code></a><a href="#ftn.idp1110850100" class="footnote" name="idp1110850100"><sup class="footnote">[b]</sup></a></p></td></tr><tr><td valign="top"><code class="constant">VIDEO_PALETTE_YUV422</code></td><td valign="top"><p><a class="link" href="V4L2-PIX-FMT-YUYV.html" title="V4L2_PIX_FMT_YUYV ('YUYV')"><code class="constant">V4L2_PIX_FMT_YUYV</code></a></p></td></tr><tr><td valign="top"><p><code class="constant">VIDEO_PALETTE_YUYV</code><a href="#ftn.idp1110852580" class="footnote" name="idp1110852580"><sup class="footnote">[c]</sup></a></p></td><td valign="top"><p><a class="link" href="V4L2-PIX-FMT-YUYV.html" title="V4L2_PIX_FMT_YUYV ('YUYV')"><code class="constant">V4L2_PIX_FMT_YUYV</code></a></p></td></tr><tr><td valign="top"><code class="constant">VIDEO_PALETTE_UYVY</code></td><td valign="top"><p><a class="link" href="V4L2-PIX-FMT-UYVY.html" title="V4L2_PIX_FMT_UYVY ('UYVY')"><code class="constant">V4L2_PIX_FMT_UYVY</code></a></p></td></tr><tr><td valign="top"><code class="constant">VIDEO_PALETTE_YUV420</code></td><td valign="top">None</td></tr><tr><td valign="top"><code class="constant">VIDEO_PALETTE_YUV411</code></td><td valign="top"><p><a class="link" href="V4L2-PIX-FMT-Y41P.html" title="V4L2_PIX_FMT_Y41P ('Y41P')"><code class="constant">V4L2_PIX_FMT_Y41P</code></a><a href="#ftn.idp1110856924" class="footnote" name="idp1110856924"><sup class="footnote">[d]</sup></a></p></td></tr><tr><td valign="top"><code class="constant">VIDEO_PALETTE_RAW</code></td><td valign="top"><p>None<a href="#ftn.idp1110858276" class="footnote" name="idp1110858276"><sup class="footnote">[e]</sup></a></p></td></tr><tr><td valign="top"><code class="constant">VIDEO_PALETTE_YUV422P</code></td><td valign="top"><p><a class="link" href="V4L2-PIX-FMT-YUV422P.html" title="V4L2_PIX_FMT_YUV422P ('422P')"><code class="constant">V4L2_PIX_FMT_YUV422P</code></a></p></td></tr><tr><td valign="top"><code class="constant">VIDEO_PALETTE_YUV411P</code></td><td valign="top"><p><a class="link" href="V4L2-PIX-FMT-YUV411P.html" title="V4L2_PIX_FMT_YUV411P ('411P')"><code class="constant">V4L2_PIX_FMT_YUV411P</code></a><a href="#ftn.idp1110860916" class="footnote" name="idp1110860916"><sup class="footnote">[f]</sup></a></p></td></tr><tr><td valign="top"><code class="constant">VIDEO_PALETTE_YUV420P</code></td><td valign="top"><p><a class="link" href="re24.html#V4L2-PIX-FMT-YVU420"><code class="constant">V4L2_PIX_FMT_YVU420</code></a></p></td></tr><tr><td valign="top"><code class="constant">VIDEO_PALETTE_YUV410P</code></td><td valign="top"><p><a class="link" href="re27.html#V4L2-PIX-FMT-YVU410"><code class="constant">V4L2_PIX_FMT_YVU410</code></a></p></td></tr></tbody><tbody class="footnotes"><tr><td colspan="2"><div id="ftn.idp1110845300" class="footnote"><p><a href="#idp1110845300" class="para"><sup class="para">[a] </sup></a>This is a custom format used by the BTTV 164driver, not one of the V4L2 standard formats.</p></div><div id="ftn.idp1110850100" class="footnote"><p><a href="#idp1110850100" class="para"><sup class="para">[b] </sup></a>Presumably all V4L RGB formats are 165little-endian, although some drivers might interpret them according to machine endianness. V4L2 defines little-endian, big-endian and red/blue 166swapped variants. For details see <a class="xref" href="pixfmt-rgb.html" title="RGB Formats">the section called “RGB Formats”</a>.</p></div><div id="ftn.idp1110852580" class="footnote"><p><a href="#idp1110852580" class="para"><sup class="para">[c] </sup></a><code class="constant">VIDEO_PALETTE_YUV422</code> 167and <code class="constant">VIDEO_PALETTE_YUYV</code> are the same formats. Some 168V4L drivers respond to one, some to the other.</p></div><div id="ftn.idp1110856924" class="footnote"><p><a href="#idp1110856924" class="para"><sup class="para">[d] </sup></a>Not to be confused with 169<code class="constant">V4L2_PIX_FMT_YUV411P</code>, which is a planar 170format.</p></div><div id="ftn.idp1110858276" class="footnote"><p><a href="#idp1110858276" class="para"><sup class="para">[e] </sup></a>V4L explains this 171as: "RAW capture (BT848)"</p></div><div id="ftn.idp1110860916" class="footnote"><p><a href="#idp1110860916" class="para"><sup class="para">[f] </sup></a>Not to be confused with 172<code class="constant">V4L2_PIX_FMT_Y41P</code>, which is a packed 173format.</p></div></td></tr></tbody></table></div><p>V4L2 image formats are defined in <a class="xref" href="pixfmt.html" title="Chapter 2. Image Formats">Chapter 2, <i>Image Formats</i></a>. The image format can be selected with the 174<a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a> ioctl.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1110865172"></a>Audio</h3></div></div></div><p>The <code class="constant">VIDIOCGAUDIO</code> and 175<code class="constant">VIDIOCSAUDIO</code> ioctl and struct 176<span class="structname">video_audio</span> are used to enumerate the 177audio inputs of a V4L device. The equivalent V4L2 ioctls are 178<a class="link" href="vidioc-g-audio.html" title="ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO"><code class="constant">VIDIOC_G_AUDIO</code></a> and <a class="link" href="vidioc-g-audio.html" title="ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO"><code class="constant">VIDIOC_S_AUDIO</code></a> using struct <a class="link" href="vidioc-g-audio.html#v4l2-audio" title="Table A.51. struct v4l2_audio">v4l2_audio</a> as 179discussed in <a class="xref" href="audio.html" title="Audio Inputs and Outputs">the section called “Audio Inputs and Outputs”</a>.</p><p>The <em class="structfield"><code>audio</code></em> "channel number" 180field counting audio inputs was renamed to 181<em class="structfield"><code>index</code></em>.</p><p>On <code class="constant">VIDIOCSAUDIO</code> the 182<em class="structfield"><code>mode</code></em> field selects <span class="emphasis"><em>one</em></span> 183of the <code class="constant">VIDEO_SOUND_MONO</code>, 184<code class="constant">VIDEO_SOUND_STEREO</code>, 185<code class="constant">VIDEO_SOUND_LANG1</code> or 186<code class="constant">VIDEO_SOUND_LANG2</code> audio demodulation modes. When 187the current audio standard is BTSC 188<code class="constant">VIDEO_SOUND_LANG2</code> refers to SAP and 189<code class="constant">VIDEO_SOUND_LANG1</code> is meaningless. Also 190undocumented in the V4L specification, there is no way to query the 191selected mode. On <code class="constant">VIDIOCGAUDIO</code> the driver returns 192the <span class="emphasis"><em>actually received</em></span> audio programmes in this 193field. In the V4L2 API this information is stored in the struct <a class="link" href="vidioc-g-tuner.html#v4l2-tuner" title="Table A.87. struct v4l2_tuner">v4l2_tuner</a> 194<em class="structfield"><code>rxsubchans</code></em> and 195<em class="structfield"><code>audmode</code></em> fields, respectively. See <a class="xref" href="tuner.html" title="Tuners and Modulators">the section called “Tuners and Modulators”</a> for more information on tuners. Related to audio 196modes struct <a class="link" href="vidioc-g-audio.html#v4l2-audio" title="Table A.51. struct v4l2_audio">v4l2_audio</a> also reports if this is a mono or stereo 197input, regardless if the source is a tuner.</p><p>The following fields where replaced by V4L2 controls 198accessible with the <a class="link" href="vidioc-queryctrl.html" title="ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU"><code class="constant">VIDIOC_QUERYCTRL</code></a>, <a class="link" href="vidioc-g-ctrl.html" title="ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL"><code class="constant">VIDIOC_G_CTRL</code></a> and 199<a class="link" href="vidioc-g-ctrl.html" title="ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL"><code class="constant">VIDIOC_S_CTRL</code></a> ioctls:</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>struct 200<span class="structname">video_audio</span></th><th>V4L2 Control ID</th></tr></thead><tbody valign="top"><tr><td valign="top"><em class="structfield"><code>volume</code></em></td><td valign="top"><code class="constant">V4L2_CID_AUDIO_VOLUME</code></td></tr><tr><td valign="top"><em class="structfield"><code>bass</code></em></td><td valign="top"><code class="constant">V4L2_CID_AUDIO_BASS</code></td></tr><tr><td valign="top"><em class="structfield"><code>treble</code></em></td><td valign="top"><code class="constant">V4L2_CID_AUDIO_TREBLE</code></td></tr><tr><td valign="top"><em class="structfield"><code>balance</code></em></td><td valign="top"><code class="constant">V4L2_CID_AUDIO_BALANCE</code></td></tr></tbody></table></div><p>To determine which of these controls are supported by a 201driver V4L provides the <em class="structfield"><code>flags</code></em> 202<code class="constant">VIDEO_AUDIO_VOLUME</code>, 203<code class="constant">VIDEO_AUDIO_BASS</code>, 204<code class="constant">VIDEO_AUDIO_TREBLE</code> and 205<code class="constant">VIDEO_AUDIO_BALANCE</code>. In the V4L2 API the 206<a class="link" href="vidioc-queryctrl.html" title="ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU"><code class="constant">VIDIOC_QUERYCTRL</code></a> ioctl reports if the respective control is 207supported. Accordingly the <code class="constant">VIDEO_AUDIO_MUTABLE</code> 208and <code class="constant">VIDEO_AUDIO_MUTE</code> flags where replaced by the 209boolean <code class="constant">V4L2_CID_AUDIO_MUTE</code> control.</p><p>All V4L2 controls have a <em class="structfield"><code>step</code></em> 210attribute replacing the struct <span class="structname">video_audio</span> 211<em class="structfield"><code>step</code></em> field. The V4L audio controls are 212assumed to range from 0 to 65535 with no particular reset value. The 213V4L2 API permits arbitrary limits and defaults which can be queried 214with the <a class="link" href="vidioc-queryctrl.html" title="ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU"><code class="constant">VIDIOC_QUERYCTRL</code></a> ioctl. For general information about 215controls see <a class="xref" href="control.html" title="User Controls">the section called “User Controls”</a>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1110884268"></a>Frame Buffer Overlay</h3></div></div></div><p>The V4L2 ioctls equivalent to 216<code class="constant">VIDIOCGFBUF</code> and <code class="constant">VIDIOCSFBUF</code> 217are <a class="link" href="vidioc-g-fbuf.html" title="ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF"><code class="constant">VIDIOC_G_FBUF</code></a> and <a class="link" href="vidioc-g-fbuf.html" title="ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF"><code class="constant">VIDIOC_S_FBUF</code></a>. The 218<em class="structfield"><code>base</code></em> field of struct 219<span class="structname">video_buffer</span> remained unchanged, except V4L2 220defines a flag to indicate non-destructive overlays instead of a 221<code class="constant">NULL</code> pointer. All other fields moved into the 222struct <a class="link" href="pixfmt.html#v4l2-pix-format" title="Table 2.1. struct v4l2_pix_format">v4l2_pix_format</a> <em class="structfield"><code>fmt</code></em> substructure of 223struct <a class="link" href="vidioc-g-fbuf.html#v4l2-framebuffer" title="Table A.69. struct v4l2_framebuffer">v4l2_framebuffer</a>. The <em class="structfield"><code>depth</code></em> field was 224replaced by <em class="structfield"><code>pixelformat</code></em>. See <a class="xref" href="pixfmt-rgb.html" title="RGB Formats">the section called “RGB Formats”</a> for a list of RGB formats and their 225respective color depths.</p><p>Instead of the special ioctls 226<code class="constant">VIDIOCGWIN</code> and <code class="constant">VIDIOCSWIN</code> 227V4L2 uses the general-purpose data format negotiation ioctls 228<a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_G_FMT</code></a> and <a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a>. They take a pointer to a 229struct <a class="link" href="vidioc-g-fmt.html#v4l2-format" title="Table A.72. struct v4l2_format">v4l2_format</a> as argument. Here the <em class="structfield"><code>win</code></em> 230member of the <em class="structfield"><code>fmt</code></em> union is used, a 231struct <a class="link" href="overlay.html#v4l2-window" title="Table 4.1. struct v4l2_window">v4l2_window</a>.</p><p>The <em class="structfield"><code>x</code></em>, 232<em class="structfield"><code>y</code></em>, <em class="structfield"><code>width</code></em> and 233<em class="structfield"><code>height</code></em> fields of struct 234<span class="structname">video_window</span> moved into struct <a class="link" href="overlay.html#v4l2-rect" title="Table 4.3. struct v4l2_rect">v4l2_rect</a> 235substructure <em class="structfield"><code>w</code></em> of struct 236<span class="structname">v4l2_window</span>. The 237<em class="structfield"><code>chromakey</code></em>, 238<em class="structfield"><code>clips</code></em>, and 239<em class="structfield"><code>clipcount</code></em> fields remained unchanged. Struct 240<span class="structname">video_clip</span> was renamed to struct <a class="link" href="overlay.html#v4l2-clip" title="Table 4.2. struct v4l2_clip">v4l2_clip</a>, also 241containing a struct <span class="structname">v4l2_rect</span>, but the 242semantics are still the same.</p><p>The <code class="constant">VIDEO_WINDOW_INTERLACE</code> flag was 243dropped. Instead applications must set the 244<em class="structfield"><code>field</code></em> field to 245<code class="constant">V4L2_FIELD_ANY</code> or 246<code class="constant">V4L2_FIELD_INTERLACED</code>. The 247<code class="constant">VIDEO_WINDOW_CHROMAKEY</code> flag moved into 248struct <a class="link" href="vidioc-g-fbuf.html#v4l2-framebuffer" title="Table A.69. struct v4l2_framebuffer">v4l2_framebuffer</a>, under the new name 249<code class="constant">V4L2_FBUF_FLAG_CHROMAKEY</code>.</p><p>In V4L, storing a bitmap pointer in 250<em class="structfield"><code>clips</code></em> and setting 251<em class="structfield"><code>clipcount</code></em> to 252<code class="constant">VIDEO_CLIP_BITMAP</code> (-1) requests bitmap 253clipping, using a fixed size bitmap of 1024 × 625 bits. Struct 254<span class="structname">v4l2_window</span> has a separate 255<em class="structfield"><code>bitmap</code></em> pointer field for this purpose and 256the bitmap size is determined by <em class="structfield"><code>w.width</code></em> and 257<em class="structfield"><code>w.height</code></em>.</p><p>The <code class="constant">VIDIOCCAPTURE</code> ioctl to enable or 258disable overlay was renamed to <a class="link" href="vidioc-overlay.html" title="ioctl VIDIOC_OVERLAY"><code class="constant">VIDIOC_OVERLAY</code></a>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1110900244"></a>Cropping</h3></div></div></div><p>To capture only a subsection of the full picture V4L 259defines the <code class="constant">VIDIOCGCAPTURE</code> and 260<code class="constant">VIDIOCSCAPTURE</code> ioctls using struct 261<span class="structname">video_capture</span>. The equivalent V4L2 ioctls are 262<a class="link" href="vidioc-g-crop.html" title="ioctl VIDIOC_G_CROP, VIDIOC_S_CROP"><code class="constant">VIDIOC_G_CROP</code></a> and <a class="link" href="vidioc-g-crop.html" title="ioctl VIDIOC_G_CROP, VIDIOC_S_CROP"><code class="constant">VIDIOC_S_CROP</code></a> using struct <a class="link" href="vidioc-g-crop.html#v4l2-crop" title="Table A.55. struct v4l2_crop">v4l2_crop</a>, and the related 263<a class="link" href="vidioc-cropcap.html" title="ioctl VIDIOC_CROPCAP"><code class="constant">VIDIOC_CROPCAP</code></a> ioctl. This is a rather complex matter, see 264<a class="xref" href="crop.html" title="Image Cropping, Insertion and Scaling">the section called “Image Cropping, Insertion and Scaling”</a> for details.</p><p>The <em class="structfield"><code>x</code></em>, 265<em class="structfield"><code>y</code></em>, <em class="structfield"><code>width</code></em> and 266<em class="structfield"><code>height</code></em> fields moved into struct <a class="link" href="overlay.html#v4l2-rect" title="Table 4.3. struct v4l2_rect">v4l2_rect</a> 267substructure <em class="structfield"><code>c</code></em> of struct 268<span class="structname">v4l2_crop</span>. The 269<em class="structfield"><code>decimation</code></em> field was dropped. In the V4L2 270API the scaling factor is implied by the size of the cropping 271rectangle and the size of the captured or overlaid image.</p><p>The <code class="constant">VIDEO_CAPTURE_ODD</code> 272and <code class="constant">VIDEO_CAPTURE_EVEN</code> flags to capture only the 273odd or even field, respectively, were replaced by 274<code class="constant">V4L2_FIELD_TOP</code> and 275<code class="constant">V4L2_FIELD_BOTTOM</code> in the field named 276<em class="structfield"><code>field</code></em> of struct <a class="link" href="pixfmt.html#v4l2-pix-format" title="Table 2.1. struct v4l2_pix_format">v4l2_pix_format</a> and 277struct <a class="link" href="overlay.html#v4l2-window" title="Table 4.1. struct v4l2_window">v4l2_window</a>. These structures are used to select a capture or 278overlay format with the <a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a> ioctl.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1110908652"></a>Reading Images, Memory Mapping</h3></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="compat.html#idp1110909012">Capturing using the read method</a></span></dt><dt><span class="section"><a href="compat.html#idp1110915524">Capturing using memory mapping</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="idp1110909012"></a>Capturing using the read method</h4></div></div></div><p>There is no essential difference between reading images 279from a V4L or V4L2 device using the <a class="link" href="func-read.html" title="V4L2 read()"><code class="function">read()</code></a> function, however V4L2 280drivers are not required to support this I/O method. Applications can 281determine if the function is available with the <a class="link" href="vidioc-querycap.html" title="ioctl VIDIOC_QUERYCAP"><code class="constant">VIDIOC_QUERYCAP</code></a> 282ioctl. All V4L2 devices exchanging data with applications must support 283the <a class="link" href="func-select.html" title="V4L2 select()"><code class="function">select()</code></a> and <a class="link" href="func-poll.html" title="V4L2 poll()"><code class="function">poll()</code></a> functions.</p><p>To select an image format and size, V4L provides the 284<code class="constant">VIDIOCSPICT</code> and <code class="constant">VIDIOCSWIN</code> 285ioctls. V4L2 uses the general-purpose data format negotiation ioctls 286<a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_G_FMT</code></a> and <a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a>. They take a pointer to a 287struct <a class="link" href="vidioc-g-fmt.html#v4l2-format" title="Table A.72. struct v4l2_format">v4l2_format</a> as argument, here the struct <a class="link" href="pixfmt.html#v4l2-pix-format" title="Table 2.1. struct v4l2_pix_format">v4l2_pix_format</a> named 288<em class="structfield"><code>pix</code></em> of its <em class="structfield"><code>fmt</code></em> 289union is used.</p><p>For more information about the V4L2 read interface see 290<a class="xref" href="io.html#rw" title="Read/Write">the section called “Read/Write”</a>.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="idp1110915524"></a>Capturing using memory mapping</h4></div></div></div><p>Applications can read from V4L devices by mapping 291buffers in device memory, or more often just buffers allocated in 292DMA-able system memory, into their address space. This avoids the data 293copying overhead of the read method. V4L2 supports memory mapping as 294well, with a few differences.</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>V4L</th><th>V4L2</th></tr></thead><tbody valign="top"><tr><td valign="top"> </td><td valign="top">The image format must be selected before 295buffers are allocated, with the <a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a> ioctl. When no format 296is selected the driver may use the last, possibly by another 297application requested format.</td></tr><tr><td valign="top"><p>Applications cannot change the number of 298buffers. The it is built into the driver, unless it has a module 299option to change the number when the driver module is 300loaded.</p></td><td valign="top"><p>The <a class="link" href="vidioc-reqbufs.html" title="ioctl VIDIOC_REQBUFS"><code class="constant">VIDIOC_REQBUFS</code></a> ioctl allocates the 301desired number of buffers, this is a required step in the initialization 302sequence.</p></td></tr><tr><td valign="top"><p>Drivers map all buffers as one contiguous 303range of memory. The <code class="constant">VIDIOCGMBUF</code> ioctl is 304available to query the number of buffers, the offset of each buffer 305from the start of the virtual file, and the overall amount of memory 306used, which can be used as arguments for the <a class="link" href="func-mmap.html" title="V4L2 mmap()"><code class="function">mmap()</code></a> 307function.</p></td><td valign="top"><p>Buffers are individually mapped. The 308offset and size of each buffer can be determined with the 309<a class="link" href="vidioc-querybuf.html" title="ioctl VIDIOC_QUERYBUF"><code class="constant">VIDIOC_QUERYBUF</code></a> ioctl.</p></td></tr><tr><td valign="top"><p>The <code class="constant">VIDIOCMCAPTURE</code> 310ioctl prepares a buffer for capturing. It also determines the image 311format for this buffer. The ioctl returns immediately, eventually with 312an <span class="errorcode">EAGAIN</span> error code if no video signal had been detected. When the driver 313supports more than one buffer applications can call the ioctl multiple 314times and thus have multiple outstanding capture 315requests.</p><p>The <code class="constant">VIDIOCSYNC</code> ioctl 316suspends execution until a particular buffer has been 317filled.</p></td><td valign="top"><p>Drivers maintain an incoming and outgoing 318queue. <a class="link" href="vidioc-qbuf.html" title="ioctl VIDIOC_QBUF, VIDIOC_DQBUF"><code class="constant">VIDIOC_QBUF</code></a> enqueues any empty buffer into the incoming 319queue. Filled buffers are dequeued from the outgoing queue with the 320<a class="link" href="vidioc-qbuf.html" title="ioctl VIDIOC_QBUF, VIDIOC_DQBUF"><code class="constant">VIDIOC_DQBUF</code></a> ioctl. To wait until filled buffers become available this 321function, <a class="link" href="func-select.html" title="V4L2 select()"><code class="function">select()</code></a> or <a class="link" href="func-poll.html" title="V4L2 poll()"><code class="function">poll()</code></a> can be used. The 322<a class="link" href="vidioc-streamon.html" title="ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF"><code class="constant">VIDIOC_STREAMON</code></a> ioctl must be called once after enqueuing one or 323more buffers to start capturing. Its counterpart 324<a class="link" href="vidioc-streamon.html" title="ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF"><code class="constant">VIDIOC_STREAMOFF</code></a> stops capturing and dequeues all buffers from both 325queues. Applications can query the signal status, if known, with the 326<a class="link" href="vidioc-enuminput.html" title="ioctl VIDIOC_ENUMINPUT"><code class="constant">VIDIOC_ENUMINPUT</code></a> ioctl.</p></td></tr></tbody></table></div><p>For a more in-depth discussion of memory mapping and 327examples, see <a class="xref" href="mmap.html" title="Streaming I/O (Memory Mapping)">the section called “Streaming I/O (Memory Mapping)”</a>.</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1110929332"></a>Reading Raw VBI Data</h3></div></div></div><p>Originally the V4L API did not specify a raw VBI capture 328interface, only the device file <code class="filename">/dev/vbi</code> was 329reserved for this purpose. The only driver supporting this interface 330was the BTTV driver, de-facto defining the V4L VBI interface. Reading 331from the device yields a raw VBI image with the following 332parameters:</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>struct <a class="link" href="raw-vbi.html#v4l2-vbi-format" title="Table 4.4. struct v4l2_vbi_format">v4l2_vbi_format</a></th><th>V4L, BTTV driver</th></tr></thead><tbody valign="top"><tr><td valign="top">sampling_rate</td><td valign="top">28636363 Hz NTSC (or any other 525-line 333standard); 35468950 Hz PAL and SECAM (625-line standards)</td></tr><tr><td valign="top">offset</td><td valign="top">?</td></tr><tr><td valign="top">samples_per_line</td><td valign="top">2048</td></tr><tr><td valign="top">sample_format</td><td valign="top">V4L2_PIX_FMT_GREY. The last four bytes (a 334machine endianness integer) contain a frame counter.</td></tr><tr><td valign="top">start[]</td><td valign="top">10, 273 NTSC; 22, 335 PAL and SECAM</td></tr><tr><td valign="top">count[]</td><td valign="top"><p>16, 16<a href="#ftn.idp1110935948" class="footnote" name="idp1110935948"><sup class="footnote">[a]</sup></a></p></td></tr><tr><td valign="top">flags</td><td valign="top">0</td></tr></tbody><tbody class="footnotes"><tr><td colspan="2"><div id="ftn.idp1110935948" class="footnote"><p><a href="#idp1110935948" class="para"><sup class="para">[a] </sup></a>Old driver 335versions used different values, eventually the custom 336<code class="constant">BTTV_VBISIZE</code> ioctl was added to query the 337correct values.</p></div></td></tr></tbody></table></div><p>Undocumented in the V4L specification, in Linux 2.3 the 338<code class="constant">VIDIOCGVBIFMT</code> and 339<code class="constant">VIDIOCSVBIFMT</code> ioctls using struct 340<span class="structname">vbi_format</span> were added to determine the VBI 341image parameters. These ioctls are only partially compatible with the 342V4L2 VBI interface specified in <a class="xref" href="raw-vbi.html" title="Raw VBI Data Interface">the section called “Raw VBI Data Interface”</a>.</p><p>An <em class="structfield"><code>offset</code></em> field does not 343exist, <em class="structfield"><code>sample_format</code></em> is supposed to be 344<code class="constant">VIDEO_PALETTE_RAW</code>, equivalent to 345<code class="constant">V4L2_PIX_FMT_GREY</code>. The remaining fields are 346probably equivalent to struct <a class="link" href="raw-vbi.html#v4l2-vbi-format" title="Table 4.4. struct v4l2_vbi_format">v4l2_vbi_format</a>.</p><p>Apparently only the Zoran (ZR 36120) driver implements 347these ioctls. The semantics differ from those specified for V4L2 in two 348ways. The parameters are reset on <a class="link" href="func-open.html" title="V4L2 open()"><code class="function">open()</code></a> and 349<code class="constant">VIDIOCSVBIFMT</code> always returns an <span class="errorcode">EINVAL</span> error code if the 350parameters are invalid.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1110942012"></a>Miscellaneous</h3></div></div></div><p>V4L2 has no equivalent of the 351<code class="constant">VIDIOCGUNIT</code> ioctl. Applications can find the VBI 352device associated with a video capture device (or vice versa) by 353reopening the device and requesting VBI data. For details see 354<a class="xref" href="common.html#open" title="Opening and Closing Devices">the section called “Opening and Closing Devices”</a>.</p><p>No replacement exists for <code class="constant">VIDIOCKEY</code>, 355and the V4L functions for microcode programming. A new interface for 356MPEG compression and playback devices is documented in <a class="xref" href="extended-controls.html" title="Extended Controls">the section called “Extended Controls”</a>.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libv4l.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="v4l2spec.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="hist-v4l2.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 6. Libv4l Userspace Library </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Changes of the V4L2 API</td></tr></table></div></body></html> 357