About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / media / v4l / compat.xml




Custom Search

Based on kernel version 3.16. Page generated on 2014-08-06 21:38 EST.

1	  <title>Changes</title>
2	
3	  <para>The following chapters document the evolution of the V4L2 API,
4	errata or extensions. They are also intended to help application and
5	driver writers to port or update their code.</para>
6	
7	  <section id="diff-v4l">
8	    <title>Differences between V4L and V4L2</title>
9	
10	    <para>The Video For Linux API was first introduced in Linux 2.1 to
11	unify and replace various TV and radio device related interfaces,
12	developed independently by driver writers in prior years. Starting
13	with Linux 2.5 the much improved V4L2 API replaces the V4L API.
14	The support for the old V4L calls were removed from Kernel, but the
15	library <xref linkend="libv4l" /> supports the conversion of a V4L
16	API system call into a V4L2 one.</para>
17	
18	    <section>
19	      <title>Opening and Closing Devices</title>
20	
21	      <para>For compatibility reasons the character device file names
22	recommended for V4L2 video capture, overlay, radio and raw
23	vbi capture devices did not change from those used by V4L. They are
24	listed in <xref linkend="devices" /> and below in <xref
25		  linkend="v4l-dev" />.</para>
26	
27	      <para>The teletext devices (minor range 192-223) have been removed in
28	V4L2 and no longer exist. There is no hardware available anymore for handling
29	pure teletext. Instead raw or sliced VBI is used.</para>
30	
31	      <para>The V4L <filename>videodev</filename> module automatically
32	assigns minor numbers to drivers in load order, depending on the
33	registered device type. We recommend that V4L2 drivers by default
34	register devices with the same numbers, but the system administrator
35	can assign arbitrary minor numbers using driver module options. The
36	major device number remains 81.</para>
37	
38	      <table id="v4l-dev">
39		<title>V4L Device Types, Names and Numbers</title>
40		<tgroup cols="3">
41		  <thead>
42		    <row>
43		      <entry>Device Type</entry>
44		      <entry>File Name</entry>
45		      <entry>Minor Numbers</entry>
46		    </row>
47		  </thead>
48		  <tbody valign="top">
49		    <row>
50		      <entry>Video capture and overlay</entry>
51		      <entry><para><filename>/dev/video</filename> and
52	<filename>/dev/bttv0</filename><footnote> <para>According to
53	Documentation/devices.txt these should be symbolic links to
54	<filename>/dev/video0</filename>. Note the original bttv interface is
55	not compatible with V4L or V4L2.</para> </footnote>,
56	<filename>/dev/video0</filename> to
57	<filename>/dev/video63</filename></para></entry>
58		      <entry>0-63</entry>
59		    </row>
60		    <row>
61		      <entry>Radio receiver</entry>
62		      <entry><para><filename>/dev/radio</filename><footnote>
63			    <para>According to
64	<filename>Documentation/devices.txt</filename> a symbolic link to
65	<filename>/dev/radio0</filename>.</para>
66			  </footnote>, <filename>/dev/radio0</filename> to
67	<filename>/dev/radio63</filename></para></entry>
68		      <entry>64-127</entry>
69		    </row>
70		    <row>
71		      <entry>Raw VBI capture</entry>
72		      <entry><para><filename>/dev/vbi</filename>,
73	<filename>/dev/vbi0</filename> to
74	<filename>/dev/vbi31</filename></para></entry>
75		      <entry>224-255</entry>
76		    </row>
77		  </tbody>
78		</tgroup>
79	      </table>
80	
81	      <para>V4L prohibits (or used to prohibit) multiple opens of a
82	device file. V4L2 drivers <emphasis>may</emphasis> support multiple
83	opens, see <xref linkend="open" /> for details and consequences.</para>
84	
85	      <para>V4L drivers respond to V4L2 ioctls with an &EINVAL;.</para>
86	    </section>
87	
88	    <section>
89	      <title>Querying Capabilities</title>
90	
91	      <para>The V4L <constant>VIDIOCGCAP</constant> ioctl is
92	equivalent to V4L2's &VIDIOC-QUERYCAP;.</para>
93	
94	      <para>The <structfield>name</structfield> field in struct
95	<structname>video_capability</structname> became
96	<structfield>card</structfield> in &v4l2-capability;,
97	<structfield>type</structfield> was replaced by
98	<structfield>capabilities</structfield>. Note V4L2 does not
99	distinguish between device types like this, better think of basic
100	video input, video output and radio devices supporting a set of
101	related functions like video capturing, video overlay and VBI
102	capturing. See <xref linkend="open" /> for an
103	introduction.<informaltable>
104		  <tgroup cols="3">
105		    <thead>
106		      <row>
107			<entry>struct
108	<structname>video_capability</structname>
109	<structfield>type</structfield></entry>
110			<entry>&v4l2-capability;
111	<structfield>capabilities</structfield> flags</entry>
112			<entry>Purpose</entry>
113		      </row>
114		    </thead>
115		    <tbody valign="top">
116		      <row>
117			<entry><constant>VID_TYPE_CAPTURE</constant></entry>
118			<entry><constant>V4L2_CAP_VIDEO_CAPTURE</constant></entry>
119			<entry>The <link linkend="capture">video
120	capture</link> interface is supported.</entry>
121		      </row>
122		      <row>
123			<entry><constant>VID_TYPE_TUNER</constant></entry>
124			<entry><constant>V4L2_CAP_TUNER</constant></entry>
125			<entry>The device has a <link linkend="tuner">tuner or
126	modulator</link>.</entry>
127		      </row>
128		      <row>
129			<entry><constant>VID_TYPE_TELETEXT</constant></entry>
130			<entry><constant>V4L2_CAP_VBI_CAPTURE</constant></entry>
131			<entry>The <link linkend="raw-vbi">raw VBI
132	capture</link> interface is supported.</entry>
133		      </row>
134		      <row>
135			<entry><constant>VID_TYPE_OVERLAY</constant></entry>
136			<entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry>
137			<entry>The <link linkend="overlay">video
138	overlay</link> interface is supported.</entry>
139		      </row>
140		      <row>
141			<entry><constant>VID_TYPE_CHROMAKEY</constant></entry>
142			<entry><constant>V4L2_FBUF_CAP_CHROMAKEY</constant> in
143	field <structfield>capability</structfield> of
144	&v4l2-framebuffer;</entry>
145			<entry>Whether chromakey overlay is supported. For
146	more information on overlay see
147	<xref linkend="overlay" />.</entry>
148		      </row>
149		      <row>
150			<entry><constant>VID_TYPE_CLIPPING</constant></entry>
151			<entry><constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant>
152	and <constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant> in field
153	<structfield>capability</structfield> of &v4l2-framebuffer;</entry>
154			<entry>Whether clipping the overlaid image is
155	supported, see <xref linkend="overlay" />.</entry>
156		      </row>
157		      <row>
158			<entry><constant>VID_TYPE_FRAMERAM</constant></entry>
159			<entry><constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant>
160	<emphasis>not set</emphasis> in field
161	<structfield>capability</structfield> of &v4l2-framebuffer;</entry>
162			<entry>Whether overlay overwrites frame buffer memory,
163	see <xref linkend="overlay" />.</entry>
164		      </row>
165		      <row>
166			<entry><constant>VID_TYPE_SCALES</constant></entry>
167			<entry><constant>-</constant></entry>
168			<entry>This flag indicates if the hardware can scale
169	images. The V4L2 API implies the scale factor by setting the cropping
170	dimensions and image size with the &VIDIOC-S-CROP; and &VIDIOC-S-FMT;
171	ioctl, respectively. The driver returns the closest sizes possible.
172	For more information on cropping and scaling see <xref
173			    linkend="crop" />.</entry>
174		      </row>
175		      <row>
176			<entry><constant>VID_TYPE_MONOCHROME</constant></entry>
177			<entry><constant>-</constant></entry>
178			<entry>Applications can enumerate the supported image
179	formats with the &VIDIOC-ENUM-FMT; ioctl to determine if the device
180	supports grey scale capturing only. For more information on image
181	formats see <xref linkend="pixfmt" />.</entry>
182		      </row>
183		      <row>
184			<entry><constant>VID_TYPE_SUBCAPTURE</constant></entry>
185			<entry><constant>-</constant></entry>
186			<entry>Applications can call the &VIDIOC-G-CROP; ioctl
187	to determine if the device supports capturing a subsection of the full
188	picture ("cropping" in V4L2). If not, the ioctl returns the &EINVAL;.
189	For more information on cropping and scaling see <xref
190			    linkend="crop" />.</entry>
191		      </row>
192		      <row>
193			<entry><constant>VID_TYPE_MPEG_DECODER</constant></entry>
194			<entry><constant>-</constant></entry>
195			<entry>Applications can enumerate the supported image
196	formats with the &VIDIOC-ENUM-FMT; ioctl to determine if the device
197	supports MPEG streams.</entry>
198		      </row>
199		      <row>
200			<entry><constant>VID_TYPE_MPEG_ENCODER</constant></entry>
201			<entry><constant>-</constant></entry>
202			<entry>See above.</entry>
203		      </row>
204		      <row>
205			<entry><constant>VID_TYPE_MJPEG_DECODER</constant></entry>
206			<entry><constant>-</constant></entry>
207			<entry>See above.</entry>
208		      </row>
209		      <row>
210			<entry><constant>VID_TYPE_MJPEG_ENCODER</constant></entry>
211			<entry><constant>-</constant></entry>
212			<entry>See above.</entry>
213		      </row>
214		    </tbody>
215		  </tgroup>
216		</informaltable></para>
217	
218	      <para>The <structfield>audios</structfield> field was replaced
219	by <structfield>capabilities</structfield> flag
220	<constant>V4L2_CAP_AUDIO</constant>, indicating
221	<emphasis>if</emphasis> the device has any audio inputs or outputs. To
222	determine their number applications can enumerate audio inputs with
223	the &VIDIOC-G-AUDIO; ioctl. The audio ioctls are described in <xref
224		  linkend="audio" />.</para>
225	
226	      <para>The <structfield>maxwidth</structfield>,
227	<structfield>maxheight</structfield>,
228	<structfield>minwidth</structfield> and
229	<structfield>minheight</structfield> fields were removed. Calling the
230	&VIDIOC-S-FMT; or &VIDIOC-TRY-FMT; ioctl with the desired dimensions
231	returns the closest size possible, taking into account the current
232	video standard, cropping and scaling limitations.</para>
233	    </section>
234	
235	    <section>
236	      <title>Video Sources</title>
237	
238	      <para>V4L provides the <constant>VIDIOCGCHAN</constant> and
239	<constant>VIDIOCSCHAN</constant> ioctl using struct
240	<structname>video_channel</structname> to enumerate
241	the video inputs of a V4L device. The equivalent V4L2 ioctls
242	are &VIDIOC-ENUMINPUT;, &VIDIOC-G-INPUT; and &VIDIOC-S-INPUT;
243	using &v4l2-input; as discussed in <xref linkend="video" />.</para>
244	
245	      <para>The <structfield>channel</structfield> field counting
246	inputs was renamed to <structfield>index</structfield>, the video
247	input types were renamed as follows: <informaltable>
248		  <tgroup cols="2">
249		    <thead>
250		      <row>
251			<entry>struct <structname>video_channel</structname>
252	<structfield>type</structfield></entry>
253			<entry>&v4l2-input;
254	<structfield>type</structfield></entry>
255		      </row>
256		    </thead>
257		    <tbody valign="top">
258		      <row>
259			<entry><constant>VIDEO_TYPE_TV</constant></entry>
260			<entry><constant>V4L2_INPUT_TYPE_TUNER</constant></entry>
261		      </row>
262		      <row>
263			<entry><constant>VIDEO_TYPE_CAMERA</constant></entry>
264			<entry><constant>V4L2_INPUT_TYPE_CAMERA</constant></entry>
265		      </row>
266		    </tbody>
267		  </tgroup>
268		</informaltable></para>
269	
270	      <para>Unlike the <structfield>tuners</structfield> field
271	expressing the number of tuners of this input, V4L2 assumes each video
272	input is connected to at most one tuner. However a tuner can have more
273	than one input, &ie; RF connectors, and a device can have multiple
274	tuners. The index number of the tuner associated with the input, if
275	any, is stored in field <structfield>tuner</structfield> of
276	&v4l2-input;. Enumeration of tuners is discussed in <xref
277		  linkend="tuner" />.</para>
278	
279	      <para>The redundant <constant>VIDEO_VC_TUNER</constant> flag was
280	dropped. Video inputs associated with a tuner are of type
281	<constant>V4L2_INPUT_TYPE_TUNER</constant>. The
282	<constant>VIDEO_VC_AUDIO</constant> flag was replaced by the
283	<structfield>audioset</structfield> field. V4L2 considers devices with
284	up to 32 audio inputs. Each set bit in the
285	<structfield>audioset</structfield> field represents one audio input
286	this video input combines with. For information about audio inputs and
287	how to switch between them see <xref linkend="audio" />.</para>
288	
289	      <para>The <structfield>norm</structfield> field describing the
290	supported video standards was replaced by
291	<structfield>std</structfield>. The V4L specification mentions a flag
292	<constant>VIDEO_VC_NORM</constant> indicating whether the standard can
293	be changed. This flag was a later addition together with the
294	<structfield>norm</structfield> field and has been removed in the
295	meantime. V4L2 has a similar, albeit more comprehensive approach
296	to video standards, see <xref linkend="standard" /> for more
297	information.</para>
298	    </section>
299	
300	    <section>
301	      <title>Tuning</title>
302	
303	      <para>The V4L <constant>VIDIOCGTUNER</constant> and
304	<constant>VIDIOCSTUNER</constant> ioctl and struct
305	<structname>video_tuner</structname> can be used to enumerate the
306	tuners of a V4L TV or radio device. The equivalent V4L2 ioctls are
307	&VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; using &v4l2-tuner;. Tuners are
308	covered in <xref linkend="tuner" />.</para>
309	
310	      <para>The <structfield>tuner</structfield> field counting tuners
311	was renamed to <structfield>index</structfield>. The fields
312	<structfield>name</structfield>, <structfield>rangelow</structfield>
313	and <structfield>rangehigh</structfield> remained unchanged.</para>
314	
315	      <para>The <constant>VIDEO_TUNER_PAL</constant>,
316	<constant>VIDEO_TUNER_NTSC</constant> and
317	<constant>VIDEO_TUNER_SECAM</constant> flags indicating the supported
318	video standards were dropped. This information is now contained in the
319	associated &v4l2-input;. No replacement exists for the
320	<constant>VIDEO_TUNER_NORM</constant> flag indicating whether the
321	video standard can be switched. The <structfield>mode</structfield>
322	field to select a different video standard was replaced by a whole new
323	set of ioctls and structures described in <xref linkend="standard" />.
324	Due to its ubiquity it should be mentioned the BTTV driver supports
325	several standards in addition to the regular
326	<constant>VIDEO_MODE_PAL</constant> (0),
327	<constant>VIDEO_MODE_NTSC</constant>,
328	<constant>VIDEO_MODE_SECAM</constant> and
329	<constant>VIDEO_MODE_AUTO</constant> (3). Namely N/PAL Argentina,
330	M/PAL, N/PAL, and NTSC Japan with numbers 3-6 (sic).</para>
331	
332	      <para>The <constant>VIDEO_TUNER_STEREO_ON</constant> flag
333	indicating stereo reception became
334	<constant>V4L2_TUNER_SUB_STEREO</constant> in field
335	<structfield>rxsubchans</structfield>. This field also permits the
336	detection of monaural and bilingual audio, see the definition of
337	&v4l2-tuner; for details. Presently no replacement exists for the
338	<constant>VIDEO_TUNER_RDS_ON</constant> and
339	<constant>VIDEO_TUNER_MBS_ON</constant> flags.</para>
340	
341	      <para> The <constant>VIDEO_TUNER_LOW</constant> flag was renamed
342	to <constant>V4L2_TUNER_CAP_LOW</constant> in the &v4l2-tuner;
343	<structfield>capability</structfield> field.</para>
344	
345	      <para>The <constant>VIDIOCGFREQ</constant> and
346	<constant>VIDIOCSFREQ</constant> ioctl to change the tuner frequency
347	where renamed to &VIDIOC-G-FREQUENCY; and  &VIDIOC-S-FREQUENCY;. They
348	take a pointer to a &v4l2-frequency; instead of an unsigned long
349	integer.</para>
350	    </section>
351	
352	    <section id="v4l-image-properties">
353	      <title>Image Properties</title>
354	
355	      <para>V4L2 has no equivalent of the
356	<constant>VIDIOCGPICT</constant> and <constant>VIDIOCSPICT</constant>
357	ioctl and struct <structname>video_picture</structname>. The following
358	fields where replaced by V4L2 controls accessible with the
359	&VIDIOC-QUERYCTRL;, &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls:<informaltable>
360		  <tgroup cols="2">
361		    <thead>
362		      <row>
363			<entry>struct <structname>video_picture</structname></entry>
364			<entry>V4L2 Control ID</entry>
365		      </row>
366		    </thead>
367		    <tbody valign="top">
368		      <row>
369			<entry><structfield>brightness</structfield></entry>
370			<entry><constant>V4L2_CID_BRIGHTNESS</constant></entry>
371		      </row>
372		      <row>
373			<entry><structfield>hue</structfield></entry>
374			<entry><constant>V4L2_CID_HUE</constant></entry>
375		      </row>
376		      <row>
377			<entry><structfield>colour</structfield></entry>
378			<entry><constant>V4L2_CID_SATURATION</constant></entry>
379		      </row>
380		      <row>
381			<entry><structfield>contrast</structfield></entry>
382			<entry><constant>V4L2_CID_CONTRAST</constant></entry>
383		      </row>
384		      <row>
385			<entry><structfield>whiteness</structfield></entry>
386			<entry><constant>V4L2_CID_WHITENESS</constant></entry>
387		      </row>
388		    </tbody>
389		  </tgroup>
390		</informaltable></para>
391	
392	      <para>The V4L picture controls are assumed to range from 0 to
393	65535 with no particular reset value. The V4L2 API permits arbitrary
394	limits and defaults which can be queried with the &VIDIOC-QUERYCTRL;
395	ioctl. For general information about controls see <xref
396	linkend="control" />.</para>
397	
398	      <para>The <structfield>depth</structfield> (average number of
399	bits per pixel) of a video image is implied by the selected image
400	format. V4L2 does not explicitly provide such information assuming
401	applications recognizing the format are aware of the image depth and
402	others need not know. The <structfield>palette</structfield> field
403	moved into the &v4l2-pix-format;:<informaltable>
404		  <tgroup cols="2">
405		    <thead>
406		      <row>
407			<entry>struct <structname>video_picture</structname>
408	<structfield>palette</structfield></entry>
409			<entry>&v4l2-pix-format;
410	<structfield>pixfmt</structfield></entry>
411		      </row>
412		    </thead>
413		    <tbody valign="top">
414		      <row>
415			<entry><constant>VIDEO_PALETTE_GREY</constant></entry>
416			<entry><para><link
417	linkend="V4L2-PIX-FMT-GREY"><constant>V4L2_PIX_FMT_GREY</constant></link></para></entry>
418		      </row>
419		      <row>
420			<entry><constant>VIDEO_PALETTE_HI240</constant></entry>
421			<entry><para><link
422	linkend="pixfmt-reserved"><constant>V4L2_PIX_FMT_HI240</constant></link><footnote>
423			      <para>This is a custom format used by the BTTV
424	driver, not one of the V4L2 standard formats.</para>
425			    </footnote></para></entry>
426		      </row>
427		      <row>
428			<entry><constant>VIDEO_PALETTE_RGB565</constant></entry>
429			<entry><para><link
430	linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_RGB565</constant></link></para></entry>
431		      </row>
432		      <row>
433			<entry><constant>VIDEO_PALETTE_RGB555</constant></entry>
434			<entry><para><link
435	linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_RGB555</constant></link></para></entry>
436		      </row>
437		      <row>
438			<entry><constant>VIDEO_PALETTE_RGB24</constant></entry>
439			<entry><para><link
440	linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_BGR24</constant></link></para></entry>
441		      </row>
442		      <row>
443			<entry><constant>VIDEO_PALETTE_RGB32</constant></entry>
444			<entry><para><link
445	linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_BGR32</constant></link><footnote>
446			      <para>Presumably all V4L RGB formats are
447	little-endian, although some drivers might interpret them according to machine endianness. V4L2 defines little-endian, big-endian and red/blue
448	swapped variants. For details see <xref linkend="pixfmt-rgb" />.</para>
449			    </footnote></para></entry>
450		      </row>
451		      <row>
452			<entry><constant>VIDEO_PALETTE_YUV422</constant></entry>
453			<entry><para><link
454	linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link></para></entry>
455		      </row>
456		      <row>
457			<entry><para><constant>VIDEO_PALETTE_YUYV</constant><footnote>
458			      <para><constant>VIDEO_PALETTE_YUV422</constant>
459	and <constant>VIDEO_PALETTE_YUYV</constant> are the same formats. Some
460	V4L drivers respond to one, some to the other.</para>
461			    </footnote></para></entry>
462			<entry><para><link
463	linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link></para></entry>
464		      </row>
465		      <row>
466			<entry><constant>VIDEO_PALETTE_UYVY</constant></entry>
467			<entry><para><link
468	linkend="V4L2-PIX-FMT-UYVY"><constant>V4L2_PIX_FMT_UYVY</constant></link></para></entry>
469		      </row>
470		      <row>
471			<entry><constant>VIDEO_PALETTE_YUV420</constant></entry>
472			<entry>None</entry>
473		      </row>
474		      <row>
475			<entry><constant>VIDEO_PALETTE_YUV411</constant></entry>
476			<entry><para><link
477	linkend="V4L2-PIX-FMT-Y41P"><constant>V4L2_PIX_FMT_Y41P</constant></link><footnote>
478			      <para>Not to be confused with
479	<constant>V4L2_PIX_FMT_YUV411P</constant>, which is a planar
480	format.</para> </footnote></para></entry>
481		      </row>
482		      <row>
483			<entry><constant>VIDEO_PALETTE_RAW</constant></entry>
484			<entry><para>None<footnote> <para>V4L explains this
485	as: "RAW capture (BT848)"</para> </footnote></para></entry>
486		      </row>
487		      <row>
488			<entry><constant>VIDEO_PALETTE_YUV422P</constant></entry>
489			<entry><para><link
490	linkend="V4L2-PIX-FMT-YUV422P"><constant>V4L2_PIX_FMT_YUV422P</constant></link></para></entry>
491		      </row>
492		      <row>
493			<entry><constant>VIDEO_PALETTE_YUV411P</constant></entry>
494			<entry><para><link
495	linkend="V4L2-PIX-FMT-YUV411P"><constant>V4L2_PIX_FMT_YUV411P</constant></link><footnote>
496			      <para>Not to be confused with
497	<constant>V4L2_PIX_FMT_Y41P</constant>, which is a packed
498	format.</para> </footnote></para></entry>
499		      </row>
500		      <row>
501			<entry><constant>VIDEO_PALETTE_YUV420P</constant></entry>
502			<entry><para><link
503	linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link></para></entry>
504		      </row>
505		      <row>
506			<entry><constant>VIDEO_PALETTE_YUV410P</constant></entry>
507			<entry><para><link
508	linkend="V4L2-PIX-FMT-YVU410"><constant>V4L2_PIX_FMT_YVU410</constant></link></para></entry>
509		      </row>
510		    </tbody>
511		  </tgroup>
512		</informaltable></para>
513	
514	      <para>V4L2 image formats are defined in <xref
515	linkend="pixfmt" />. The image format can be selected with the
516	&VIDIOC-S-FMT; ioctl.</para>
517	    </section>
518	
519	    <section>
520	      <title>Audio</title>
521	
522	      <para>The <constant>VIDIOCGAUDIO</constant> and
523	<constant>VIDIOCSAUDIO</constant> ioctl and struct
524	<structname>video_audio</structname> are used to enumerate the
525	audio inputs of a V4L device. The equivalent V4L2 ioctls are
526	&VIDIOC-G-AUDIO; and &VIDIOC-S-AUDIO; using &v4l2-audio; as
527	discussed in <xref linkend="audio" />.</para>
528	
529	      <para>The <structfield>audio</structfield> "channel number"
530	field counting audio inputs was renamed to
531	<structfield>index</structfield>.</para>
532	
533	      <para>On <constant>VIDIOCSAUDIO</constant> the
534	<structfield>mode</structfield> field selects <emphasis>one</emphasis>
535	of the <constant>VIDEO_SOUND_MONO</constant>,
536	<constant>VIDEO_SOUND_STEREO</constant>,
537	<constant>VIDEO_SOUND_LANG1</constant> or
538	<constant>VIDEO_SOUND_LANG2</constant> audio demodulation modes. When
539	the current audio standard is BTSC
540	<constant>VIDEO_SOUND_LANG2</constant> refers to SAP and
541	<constant>VIDEO_SOUND_LANG1</constant> is meaningless. Also
542	undocumented in the V4L specification, there is no way to query the
543	selected mode. On <constant>VIDIOCGAUDIO</constant> the driver returns
544	the <emphasis>actually received</emphasis> audio programmes in this
545	field. In the V4L2 API this information is stored in the &v4l2-tuner;
546	<structfield>rxsubchans</structfield> and
547	<structfield>audmode</structfield> fields, respectively. See <xref
548	linkend="tuner" /> for more information on tuners. Related to audio
549	modes &v4l2-audio; also reports if this is a mono or stereo
550	input, regardless if the source is a tuner.</para>
551	
552	      <para>The following fields where replaced by V4L2 controls
553	accessible with the &VIDIOC-QUERYCTRL;, &VIDIOC-G-CTRL; and
554	&VIDIOC-S-CTRL; ioctls:<informaltable>
555		  <tgroup cols="2">
556		    <thead>
557		      <row>
558			<entry>struct
559	<structname>video_audio</structname></entry>
560			<entry>V4L2 Control ID</entry>
561		      </row>
562		    </thead>
563		    <tbody valign="top">
564		      <row>
565			<entry><structfield>volume</structfield></entry>
566			<entry><constant>V4L2_CID_AUDIO_VOLUME</constant></entry>
567		      </row>
568		      <row>
569			<entry><structfield>bass</structfield></entry>
570			<entry><constant>V4L2_CID_AUDIO_BASS</constant></entry>
571		      </row>
572		      <row>
573			<entry><structfield>treble</structfield></entry>
574			<entry><constant>V4L2_CID_AUDIO_TREBLE</constant></entry>
575		      </row>
576		      <row>
577			<entry><structfield>balance</structfield></entry>
578			<entry><constant>V4L2_CID_AUDIO_BALANCE</constant></entry>
579		      </row>
580		    </tbody>
581		  </tgroup>
582		</informaltable></para>
583	
584	      <para>To determine which of these controls are supported by a
585	driver V4L provides the <structfield>flags</structfield>
586	<constant>VIDEO_AUDIO_VOLUME</constant>,
587	<constant>VIDEO_AUDIO_BASS</constant>,
588	<constant>VIDEO_AUDIO_TREBLE</constant> and
589	<constant>VIDEO_AUDIO_BALANCE</constant>. In the V4L2 API the
590	&VIDIOC-QUERYCTRL; ioctl reports if the respective control is
591	supported. Accordingly the <constant>VIDEO_AUDIO_MUTABLE</constant>
592	and <constant>VIDEO_AUDIO_MUTE</constant> flags where replaced by the
593	boolean <constant>V4L2_CID_AUDIO_MUTE</constant> control.</para>
594	
595	      <para>All V4L2 controls have a <structfield>step</structfield>
596	attribute replacing the struct <structname>video_audio</structname>
597	<structfield>step</structfield> field. The V4L audio controls are
598	assumed to range from 0 to 65535 with no particular reset value. The
599	V4L2 API permits arbitrary limits and defaults which can be queried
600	with the &VIDIOC-QUERYCTRL; ioctl. For general information about
601	controls see <xref linkend="control" />.</para>
602	    </section>
603	
604	    <section>
605	      <title>Frame Buffer Overlay</title>
606	
607	      <para>The V4L2 ioctls equivalent to
608	<constant>VIDIOCGFBUF</constant> and <constant>VIDIOCSFBUF</constant>
609	are &VIDIOC-G-FBUF; and &VIDIOC-S-FBUF;. The
610	<structfield>base</structfield> field of struct
611	<structname>video_buffer</structname> remained unchanged, except V4L2
612	defines a flag to indicate non-destructive overlays instead of a
613	<constant>NULL</constant> pointer. All other fields moved into the
614	&v4l2-pix-format; <structfield>fmt</structfield> substructure of
615	&v4l2-framebuffer;. The <structfield>depth</structfield> field was
616	replaced by <structfield>pixelformat</structfield>. See <xref
617		  linkend="pixfmt-rgb" /> for a list of RGB formats and their
618	respective color depths.</para>
619	
620	      <para>Instead of the special ioctls
621	<constant>VIDIOCGWIN</constant> and <constant>VIDIOCSWIN</constant>
622	V4L2 uses the general-purpose data format negotiation ioctls
623	&VIDIOC-G-FMT; and &VIDIOC-S-FMT;. They take a pointer to a
624	&v4l2-format; as argument. Here the <structfield>win</structfield>
625	member of the <structfield>fmt</structfield> union is used, a
626	&v4l2-window;.</para>
627	
628	      <para>The <structfield>x</structfield>,
629	<structfield>y</structfield>, <structfield>width</structfield> and
630	<structfield>height</structfield> fields of struct
631	<structname>video_window</structname> moved into &v4l2-rect;
632	substructure <structfield>w</structfield> of struct
633	<structname>v4l2_window</structname>. The
634	<structfield>chromakey</structfield>,
635	<structfield>clips</structfield>, and
636	<structfield>clipcount</structfield> fields remained unchanged. Struct
637	<structname>video_clip</structname> was renamed to &v4l2-clip;, also
638	containing a struct <structname>v4l2_rect</structname>, but the
639	semantics are still the same.</para>
640	
641	      <para>The <constant>VIDEO_WINDOW_INTERLACE</constant> flag was
642	dropped. Instead applications must set the
643	<structfield>field</structfield> field to
644	<constant>V4L2_FIELD_ANY</constant> or
645	<constant>V4L2_FIELD_INTERLACED</constant>. The
646	<constant>VIDEO_WINDOW_CHROMAKEY</constant> flag moved into
647	&v4l2-framebuffer;, under the new name
648	<constant>V4L2_FBUF_FLAG_CHROMAKEY</constant>.</para>
649	
650	      <para>In V4L, storing a bitmap pointer in
651	<structfield>clips</structfield> and setting
652	<structfield>clipcount</structfield> to
653	<constant>VIDEO_CLIP_BITMAP</constant> (-1) requests bitmap
654	clipping, using a fixed size bitmap of 1024 &times; 625 bits. Struct
655	<structname>v4l2_window</structname> has a separate
656	<structfield>bitmap</structfield> pointer field for this purpose and
657	the bitmap size is determined by <structfield>w.width</structfield> and
658	<structfield>w.height</structfield>.</para>
659	
660	      <para>The <constant>VIDIOCCAPTURE</constant> ioctl to enable or
661	disable overlay was renamed to &VIDIOC-OVERLAY;.</para>
662	    </section>
663	
664	    <section>
665	      <title>Cropping</title>
666	
667	      <para>To capture only a subsection of the full picture V4L
668	defines the <constant>VIDIOCGCAPTURE</constant> and
669	<constant>VIDIOCSCAPTURE</constant> ioctls using struct
670	<structname>video_capture</structname>. The equivalent V4L2 ioctls are
671	&VIDIOC-G-CROP; and &VIDIOC-S-CROP; using &v4l2-crop;, and the related
672	&VIDIOC-CROPCAP; ioctl. This is a rather complex matter, see
673	<xref linkend="crop" /> for details.</para>
674	
675	      <para>The <structfield>x</structfield>,
676	<structfield>y</structfield>, <structfield>width</structfield> and
677	<structfield>height</structfield> fields moved into &v4l2-rect;
678	substructure <structfield>c</structfield> of struct
679	<structname>v4l2_crop</structname>. The
680	<structfield>decimation</structfield> field was dropped. In the V4L2
681	API the scaling factor is implied by the size of the cropping
682	rectangle and the size of the captured or overlaid image.</para>
683	
684	      <para>The <constant>VIDEO_CAPTURE_ODD</constant>
685	and <constant>VIDEO_CAPTURE_EVEN</constant> flags to capture only the
686	odd or even field, respectively, were replaced by
687	<constant>V4L2_FIELD_TOP</constant> and
688	<constant>V4L2_FIELD_BOTTOM</constant> in the field named
689	<structfield>field</structfield> of &v4l2-pix-format; and
690	&v4l2-window;. These structures are used to select a capture or
691	overlay format with the &VIDIOC-S-FMT; ioctl.</para>
692	    </section>
693	
694	    <section>
695	      <title>Reading Images, Memory Mapping</title>
696	
697	      <section>
698		<title>Capturing using the read method</title>
699	
700		<para>There is no essential difference between reading images
701	from a V4L or V4L2 device using the &func-read; function, however V4L2
702	drivers are not required to support this I/O method. Applications can
703	determine if the function is available with the &VIDIOC-QUERYCAP;
704	ioctl. All V4L2 devices exchanging data with applications must support
705	the &func-select; and &func-poll; functions.</para>
706	
707		<para>To select an image format and size, V4L provides the
708	<constant>VIDIOCSPICT</constant> and <constant>VIDIOCSWIN</constant>
709	ioctls. V4L2 uses the general-purpose data format negotiation ioctls
710	&VIDIOC-G-FMT; and &VIDIOC-S-FMT;. They take a pointer to a
711	&v4l2-format; as argument, here the &v4l2-pix-format; named
712	<structfield>pix</structfield> of its <structfield>fmt</structfield>
713	union is used.</para>
714	
715		<para>For more information about the V4L2 read interface see
716	<xref linkend="rw" />.</para>
717	      </section>
718	      <section>
719		<title>Capturing using memory mapping</title>
720	
721		<para>Applications can read from V4L devices by mapping
722	buffers in device memory, or more often just buffers allocated in
723	DMA-able system memory, into their address space. This avoids the data
724	copying overhead of the read method. V4L2 supports memory mapping as
725	well, with a few differences.</para>
726	
727		<informaltable>
728		  <tgroup cols="2">
729		    <thead>
730		      <row>
731			<entry>V4L</entry>
732			<entry>V4L2</entry>
733		      </row>
734		    </thead>
735		    <tbody valign="top">
736		      <row>
737			<entry></entry>
738			<entry>The image format must be selected before
739	buffers are allocated, with the &VIDIOC-S-FMT; ioctl. When no format
740	is selected the driver may use the last, possibly by another
741	application requested format.</entry>
742		      </row>
743		      <row>
744			<entry><para>Applications cannot change the number of
745	buffers. The it is built into the driver, unless it has a module
746	option to change the number when the driver module is
747	loaded.</para></entry>
748			<entry><para>The &VIDIOC-REQBUFS; ioctl allocates the
749	desired number of buffers, this is a required step in the initialization
750	sequence.</para></entry>
751		      </row>
752		      <row>
753			<entry><para>Drivers map all buffers as one contiguous
754	range of memory. The <constant>VIDIOCGMBUF</constant> ioctl is
755	available to query the number of buffers, the offset of each buffer
756	from the start of the virtual file, and the overall amount of memory
757	used, which can be used as arguments for the &func-mmap;
758	function.</para></entry>
759			<entry><para>Buffers are individually mapped. The
760	offset and size of each buffer can be determined with the
761	&VIDIOC-QUERYBUF; ioctl.</para></entry>
762		      </row>
763		      <row>
764			<entry><para>The <constant>VIDIOCMCAPTURE</constant>
765	ioctl prepares a buffer for capturing. It also determines the image
766	format for this buffer. The ioctl returns immediately, eventually with
767	an &EAGAIN; if no video signal had been detected. When the driver
768	supports more than one buffer applications can call the ioctl multiple
769	times and thus have multiple outstanding capture
770	requests.</para><para>The <constant>VIDIOCSYNC</constant> ioctl
771	suspends execution until a particular buffer has been
772	filled.</para></entry>
773			<entry><para>Drivers maintain an incoming and outgoing
774	queue. &VIDIOC-QBUF; enqueues any empty buffer into the incoming
775	queue. Filled buffers are dequeued from the outgoing queue with the
776	&VIDIOC-DQBUF; ioctl. To wait until filled buffers become available this
777	function, &func-select; or &func-poll; can be used. The
778	&VIDIOC-STREAMON; ioctl must be called once after enqueuing one or
779	more buffers to start capturing. Its counterpart
780	&VIDIOC-STREAMOFF; stops capturing and dequeues all buffers from both
781	queues. Applications can query the signal status, if known, with the
782	&VIDIOC-ENUMINPUT; ioctl.</para></entry>
783		      </row>
784		    </tbody>
785		  </tgroup>
786		</informaltable>
787	
788		<para>For a more in-depth discussion of memory mapping and
789	examples, see <xref linkend="mmap" />.</para>
790	      </section>
791	    </section>
792	
793	    <section>
794	      <title>Reading Raw VBI Data</title>
795	
796	      <para>Originally the V4L API did not specify a raw VBI capture
797	interface, only the device file <filename>/dev/vbi</filename> was
798	reserved for this purpose. The only driver supporting this interface
799	was the BTTV driver, de-facto defining the V4L VBI interface. Reading
800	from the device yields a raw VBI image with the following
801	parameters:<informaltable>
802		    <tgroup cols="2">
803		      <thead>
804			<row>
805			  <entry>&v4l2-vbi-format;</entry>
806			  <entry>V4L, BTTV driver</entry>
807			</row>
808		      </thead>
809		      <tbody valign="top">
810			<row>
811			  <entry>sampling_rate</entry>
812			  <entry>28636363&nbsp;Hz NTSC (or any other 525-line
813	standard); 35468950&nbsp;Hz PAL and SECAM (625-line standards)</entry>
814			</row>
815			<row>
816			  <entry>offset</entry>
817			  <entry>?</entry>
818			</row>
819			<row>
820			  <entry>samples_per_line</entry>
821			  <entry>2048</entry>
822			</row>
823			<row>
824			  <entry>sample_format</entry>
825			  <entry>V4L2_PIX_FMT_GREY. The last four bytes (a
826	machine endianness integer) contain a frame counter.</entry>
827			</row>
828			<row>
829			  <entry>start[]</entry>
830			  <entry>10, 273 NTSC; 22, 335 PAL and SECAM</entry>
831			</row>
832			<row>
833			  <entry>count[]</entry>
834			  <entry><para>16, 16<footnote><para>Old driver
835	versions used different values, eventually the custom
836	<constant>BTTV_VBISIZE</constant> ioctl was added to query the
837	correct values.</para></footnote></para></entry>
838			</row>
839			<row>
840			  <entry>flags</entry>
841			  <entry>0</entry>
842			</row>
843		      </tbody>
844		    </tgroup>
845		</informaltable></para>
846	
847	      <para>Undocumented in the V4L specification, in Linux 2.3 the
848	<constant>VIDIOCGVBIFMT</constant> and
849	<constant>VIDIOCSVBIFMT</constant> ioctls using struct
850	<structname>vbi_format</structname> were added to determine the VBI
851	image parameters. These ioctls are only partially compatible with the
852	V4L2 VBI interface specified in <xref linkend="raw-vbi" />.</para>
853	
854	      <para>An <structfield>offset</structfield> field does not
855	exist, <structfield>sample_format</structfield> is supposed to be
856	<constant>VIDEO_PALETTE_RAW</constant>, equivalent to
857	<constant>V4L2_PIX_FMT_GREY</constant>. The remaining fields are
858	probably equivalent to &v4l2-vbi-format;.</para>
859	
860	      <para>Apparently only the Zoran (ZR 36120) driver implements
861	these ioctls. The semantics differ from those specified for V4L2 in two
862	ways. The parameters are reset on &func-open; and
863	<constant>VIDIOCSVBIFMT</constant> always returns an &EINVAL; if the
864	parameters are invalid.</para>
865	    </section>
866	
867	    <section>
868	      <title>Miscellaneous</title>
869	
870	      <para>V4L2 has no equivalent of the
871	<constant>VIDIOCGUNIT</constant> ioctl. Applications can find the VBI
872	device associated with a video capture device (or vice versa) by
873	reopening the device and requesting VBI data. For details see
874	<xref linkend="open" />.</para>
875	
876	      <para>No replacement exists for <constant>VIDIOCKEY</constant>,
877	and the V4L functions for microcode programming. A new interface for
878	MPEG compression and playback devices is documented in <xref
879		  linkend="extended-controls" />.</para>
880	    </section>
881	
882	  </section>
883	
884	  <section id="hist-v4l2">
885	    <title>Changes of the V4L2 API</title>
886	
887	    <para>Soon after the V4L API was added to the kernel it was
888	criticised as too inflexible. In August 1998 Bill Dirks proposed a
889	number of improvements and began to work on documentation, example
890	drivers and applications. With the help of other volunteers this
891	eventually became the V4L2 API, not just an extension but a
892	replacement for the V4L API. However it took another four years and
893	two stable kernel releases until the new API was finally accepted for
894	inclusion into the kernel in its present form.</para>
895	
896	    <section>
897	      <title>Early Versions</title>
898	      <para>1998-08-20: First version.</para>
899	
900	      <para>1998-08-27: The &func-select; function was introduced.</para>
901	
902	      <para>1998-09-10: New video standard interface.</para>
903	
904	      <para>1998-09-18: The <constant>VIDIOC_NONCAP</constant> ioctl
905	was replaced by the otherwise meaningless <constant>O_TRUNC</constant>
906	&func-open; flag, and the aliases <constant>O_NONCAP</constant> and
907	<constant>O_NOIO</constant> were defined. Applications can set this
908	flag if they intend to access controls only, as opposed to capture
909	applications which need exclusive access. The
910	<constant>VIDEO_STD_XXX</constant> identifiers are now ordinals
911	instead of flags, and the <function>video_std_construct()</function>
912	helper function takes id and transmission arguments.</para>
913	
914	      <para>1998-09-28: Revamped video standard. Made video controls
915	individually enumerable.</para>
916	
917	      <para>1998-10-02: The <structfield>id</structfield> field was
918	removed from struct <structname>video_standard</structname> and the
919	color subcarrier fields were renamed. The &VIDIOC-QUERYSTD; ioctl was
920	renamed to &VIDIOC-ENUMSTD;, &VIDIOC-G-INPUT; to &VIDIOC-ENUMINPUT;. A
921	first draft of the Codec API was released.</para>
922	
923	      <para>1998-11-08: Many minor changes. Most symbols have been
924	renamed. Some material changes to &v4l2-capability;.</para>
925	
926	      <para>1998-11-12: The read/write directon of some ioctls was misdefined.</para>
927	
928	      <para>1998-11-14: <constant>V4L2_PIX_FMT_RGB24</constant>
929	changed to <constant>V4L2_PIX_FMT_BGR24</constant>, and
930	<constant>V4L2_PIX_FMT_RGB32</constant> changed to
931	<constant>V4L2_PIX_FMT_BGR32</constant>. Audio controls are now
932	accessible with the &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls under
933	names starting with <constant>V4L2_CID_AUDIO</constant>. The
934	<constant>V4L2_MAJOR</constant> define was removed from
935	<filename>videodev.h</filename> since it was only used once in the
936	<filename>videodev</filename> kernel module. The
937	<constant>YUV422</constant> and <constant>YUV411</constant> planar
938	image formats were added.</para>
939	
940	      <para>1998-11-28: A few ioctl symbols changed. Interfaces for codecs and
941	video output devices were added.</para>
942	
943	      <para>1999-01-14: A raw VBI capture interface was added.</para>
944	
945	      <para>1999-01-19: The <constant>VIDIOC_NEXTBUF</constant> ioctl
946	      was removed.</para>
947	    </section>
948	
949	    <section>
950	      <title>V4L2 Version 0.16 1999-01-31</title>
951	      <para>1999-01-27: There is now one QBUF ioctl, VIDIOC_QWBUF and VIDIOC_QRBUF
952	are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added
953	digital zoom (cropping) controls.</para>
954	    </section>
955	
956	    <!-- Where's 0.17? mhs couldn't find that videodev.h, perhaps Bill
957		 forgot to bump the version number or never released it. -->
958	
959	    <section>
960	      <title>V4L2 Version 0.18 1999-03-16</title>
961	      <para>Added a v4l to V4L2 ioctl compatibility layer to
962	videodev.c. Driver writers, this changes how you implement your ioctl
963	handler. See the Driver Writer's Guide. Added some more control id
964	codes.</para>
965	    </section>
966	
967	    <section>
968	      <title>V4L2 Version 0.19 1999-06-05</title>
969	      <para>1999-03-18: Fill in the category and catname fields of
970	v4l2_queryctrl objects before passing them to the driver. Required a
971	minor change to the VIDIOC_QUERYCTRL handlers in the sample
972	drivers.</para>
973	      <para>1999-03-31: Better compatibility for v4l memory capture
974	ioctls. Requires changes to drivers to fully support new compatibility
975	features, see Driver Writer's Guide and v4l2cap.c. Added new control
976	IDs: V4L2_CID_HFLIP, _VFLIP. Changed V4L2_PIX_FMT_YUV422P to _YUV422P,
977	and _YUV411P to _YUV411P.</para>
978	      <para>1999-04-04: Added a few more control IDs.</para>
979	      <para>1999-04-07: Added the button control type.</para>
980	      <para>1999-05-02: Fixed a typo in videodev.h, and added the
981	V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag.</para>
982	      <para>1999-05-20: Definition of VIDIOC_G_CTRL was wrong causing
983	a malfunction of this ioctl.</para>
984	      <para>1999-06-05: Changed the value of
985	V4L2_CID_WHITENESS.</para>
986	    </section>
987	
988	    <section>
989	      <title>V4L2 Version 0.20 (1999-09-10)</title>
990	
991	      <para>Version 0.20 introduced a number of changes which were
992	<emphasis>not backward compatible</emphasis> with 0.19 and earlier
993	versions. Purpose of these changes was to simplify the API, while
994	making it more extensible and following common Linux driver API
995	conventions.</para>
996	
997	      <orderedlist>
998		<listitem>
999		  <para>Some typos in <constant>V4L2_FMT_FLAG</constant>
1000	symbols were fixed. &v4l2-clip; was changed for compatibility with
1001	v4l. (1999-08-30)</para>
1002		</listitem>
1003	
1004		<listitem>
1005		  <para><constant>V4L2_TUNER_SUB_LANG1</constant> was added.
1006	(1999-09-05)</para>
1007		</listitem>
1008	
1009		<listitem>
1010		  <para>All ioctl() commands that used an integer argument now
1011	take a pointer to an integer. Where it makes sense, ioctls will return
1012	the actual new value in the integer pointed to by the argument, a
1013	common convention in the V4L2 API. The affected ioctls are:
1014	VIDIOC_PREVIEW, VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ,
1015	VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example
1016	<programlisting>
1017	err = ioctl (fd, VIDIOC_XXX, V4L2_XXX);
1018	</programlisting> becomes <programlisting>
1019	int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &amp;a);
1020	</programlisting>
1021		  </para>
1022		</listitem>
1023	
1024		<listitem>
1025		  <para>All the different get- and set-format commands were
1026	swept into one &VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctl taking a union
1027	and a type field selecting the union member as parameter. Purpose is to
1028	simplify the API by eliminating several ioctls and to allow new and
1029	driver private data streams without adding new ioctls.</para>
1030	
1031		  <para>This change obsoletes the following ioctls:
1032	<constant>VIDIOC_S_INFMT</constant>,
1033	<constant>VIDIOC_G_INFMT</constant>,
1034	<constant>VIDIOC_S_OUTFMT</constant>,
1035	<constant>VIDIOC_G_OUTFMT</constant>,
1036	<constant>VIDIOC_S_VBIFMT</constant> and
1037	<constant>VIDIOC_G_VBIFMT</constant>. The image format structure
1038	<structname>v4l2_format</structname> was renamed to &v4l2-pix-format;,
1039	while &v4l2-format; is now the envelopping structure for all format
1040	negotiations.</para>
1041		</listitem>
1042	
1043		<listitem>
1044		  <para>Similar to the changes above, the
1045	<constant>VIDIOC_G_PARM</constant> and
1046	<constant>VIDIOC_S_PARM</constant> ioctls were merged with
1047	<constant>VIDIOC_G_OUTPARM</constant> and
1048	<constant>VIDIOC_S_OUTPARM</constant>. A
1049	<structfield>type</structfield> field in the new &v4l2-streamparm;
1050	selects the respective union member.</para>
1051	
1052		  <para>This change obsoletes the
1053	<constant>VIDIOC_G_OUTPARM</constant> and
1054	<constant>VIDIOC_S_OUTPARM</constant> ioctls.</para>
1055		</listitem>
1056	
1057		<listitem>
1058		  <para>Control enumeration was simplified, and two new
1059	control flags were introduced and one dropped. The
1060	<structfield>catname</structfield> field was replaced by a
1061	<structfield>group</structfield> field.</para>
1062	
1063		  <para>Drivers can now flag unsupported and temporarily
1064	unavailable controls with <constant>V4L2_CTRL_FLAG_DISABLED</constant>
1065	and <constant>V4L2_CTRL_FLAG_GRABBED</constant> respectively. The
1066	<structfield>group</structfield> name indicates a possibly narrower
1067	classification than the <structfield>category</structfield>. In other
1068	words, there may be multiple groups within a category. Controls within
1069	a group would typically be drawn within a group box. Controls in
1070	different categories might have a greater separation, or may even
1071	appear in separate windows.</para>
1072		</listitem>
1073	
1074		<listitem>
1075		  <para>The &v4l2-buffer; <structfield>timestamp</structfield>
1076	was changed to a 64 bit integer, containing the sampling or output
1077	time of the frame in nanoseconds. Additionally timestamps will be in
1078	absolute system time, not starting from zero at the beginning of a
1079	stream. The data type name for timestamps is stamp_t, defined as a
1080	signed 64-bit integer. Output devices should not send a buffer out
1081	until the time in the timestamp field has arrived. I would like to
1082	follow SGI's lead, and adopt a multimedia timestamping system like
1083	their UST (Unadjusted System Time). See
1084	http://web.archive.org/web/*/http://reality.sgi.com
1085	/cpirazzi_engr/lg/time/intro.html.
1086	UST uses timestamps that are 64-bit signed integers
1087	(not struct timeval's) and given in nanosecond units. The UST clock
1088	starts at zero when the system is booted and runs continuously and
1089	uniformly. It takes a little over 292 years for UST to overflow. There
1090	is no way to set the UST clock. The regular Linux time-of-day clock
1091	can be changed periodically, which would cause errors if it were being
1092	used for timestamping a multimedia stream. A real UST style clock will
1093	require some support in the kernel that is not there yet. But in
1094	anticipation, I will change the timestamp field to a 64-bit integer,
1095	and I will change the v4l2_masterclock_gettime() function (used only
1096	by drivers) to return a 64-bit integer.</para>
1097		</listitem>
1098	
1099		<listitem>
1100		  <para>A <structfield>sequence</structfield> field was added
1101	to &v4l2-buffer;. The <structfield>sequence</structfield> field counts
1102	captured frames, it is ignored by output devices. When a capture
1103	driver drops a frame, the sequence number of that frame is
1104	skipped.</para>
1105		</listitem>
1106	      </orderedlist>
1107	    </section>
1108	
1109	    <section>
1110	      <title>V4L2 Version 0.20 incremental changes</title>
1111	      <!-- Version number didn't change anymore, reason unknown. -->
1112	
1113	      <para>1999-12-23: In &v4l2-vbi-format; the
1114	<structfield>reserved1</structfield> field became
1115	<structfield>offset</structfield>. Previously drivers were required to
1116	clear the <structfield>reserved1</structfield> field.</para>
1117	
1118	      <para>2000-01-13: The
1119	      <constant>V4L2_FMT_FLAG_NOT_INTERLACED</constant> flag was added.</para>
1120	
1121	      <para>2000-07-31: The <filename>linux/poll.h</filename> header
1122	is now included by <filename>videodev.h</filename> for compatibility
1123	with the original <filename>videodev.h</filename> file.</para>
1124	
1125	      <para>2000-11-20: <constant>V4L2_TYPE_VBI_OUTPUT</constant> and
1126	<constant>V4L2_PIX_FMT_Y41P</constant> were added.</para>
1127	
1128	      <para>2000-11-25: <constant>V4L2_TYPE_VBI_INPUT</constant> was
1129	added.</para>
1130	
1131	      <para>2000-12-04: A couple typos in symbol names were fixed.</para>
1132	
1133	      <para>2001-01-18: To avoid namespace conflicts the
1134	<constant>fourcc</constant> macro defined in the
1135	<filename>videodev.h</filename> header file was renamed to
1136	<constant>v4l2_fourcc</constant>.</para>
1137	
1138	      <para>2001-01-25: A possible driver-level compatibility problem
1139	between the <filename>videodev.h</filename> file in Linux 2.4.0 and
1140	the <filename>videodev.h</filename> file included in the
1141	<filename>videodevX</filename> patch was fixed. Users of an earlier
1142	version of <filename>videodevX</filename> on Linux 2.4.0 should
1143	recompile their V4L and V4L2 drivers.</para>
1144	
1145	      <para>2001-01-26: A possible kernel-level incompatibility
1146	between the <filename>videodev.h</filename> file in the
1147	<filename>videodevX</filename> patch and the
1148	<filename>videodev.h</filename> file in Linux 2.2.x with devfs patches
1149	applied was fixed.</para>
1150	
1151	      <para>2001-03-02: Certain V4L ioctls which pass data in both
1152	direction although they are defined with read-only parameter, did not
1153	work correctly through the backward compatibility layer.
1154	[Solution?]</para>
1155	
1156	      <para>2001-04-13: Big endian 16-bit RGB formats were added.</para>
1157	
1158	      <para>2001-09-17: New YUV formats and the &VIDIOC-G-FREQUENCY; and
1159	&VIDIOC-S-FREQUENCY; ioctls were added. (The old
1160	<constant>VIDIOC_G_FREQ</constant> and
1161	<constant>VIDIOC_S_FREQ</constant> ioctls did not take multiple tuners
1162	into account.)</para>
1163	
1164	      <para>2000-09-18: <constant>V4L2_BUF_TYPE_VBI</constant> was
1165	added. This may <emphasis>break compatibility</emphasis> as the
1166	&VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls may fail now if the struct
1167	<structname>v4l2_fmt</structname> <structfield>type</structfield>
1168	field does not contain <constant>V4L2_BUF_TYPE_VBI</constant>. In the
1169	documentation of the &v4l2-vbi-format;
1170	<structfield>offset</structfield> field the ambiguous phrase "rising
1171	edge" was changed to "leading edge".</para>
1172	    </section>
1173	
1174	    <section>
1175	      <title>V4L2 Version 0.20 2000-11-23</title>
1176	
1177	      <para>A number of changes were made to the raw VBI
1178	interface.</para>
1179	
1180	      <orderedlist>
1181		<listitem>
1182		  <para>Figures clarifying the line numbering scheme were
1183	added to the V4L2 API specification. The
1184	<structfield>start</structfield>[0] and
1185	<structfield>start</structfield>[1] fields no longer count line
1186	numbers beginning at zero. Rationale: a) The previous definition was
1187	unclear. b) The <structfield>start</structfield>[] values are ordinal
1188	numbers. c) There is no point in inventing a new line numbering
1189	scheme. We now use line number as defined by ITU-R, period.
1190	Compatibility: Add one to the start values. Applications depending on
1191	the previous semantics may not function correctly.</para>
1192		</listitem>
1193	
1194		<listitem>
1195		  <para>The restriction "count[0] &gt; 0 and count[1] &gt; 0"
1196	has been relaxed  to "(count[0] + count[1]) &gt; 0". Rationale:
1197	Drivers may allocate resources at scan line granularity and some data
1198	services are transmitted only on the first field. The comment that
1199	both <structfield>count</structfield> values will usually be equal is
1200	misleading and pointless and has been removed. This change
1201	<emphasis>breaks compatibility</emphasis> with earlier versions:
1202	Drivers may return EINVAL, applications may not function
1203	correctly.</para>
1204		</listitem>
1205	
1206		<listitem>
1207		  <para>Drivers are again permitted to return negative
1208	(unknown) start values as proposed earlier. Why this feature was
1209	dropped is unclear. This change may <emphasis>break
1210	compatibility</emphasis> with applications depending on the start
1211	values being positive. The use of <constant>EBUSY</constant> and
1212	<constant>EINVAL</constant> error codes with the &VIDIOC-S-FMT; ioctl
1213	was clarified. The &EBUSY; was finally documented, and the
1214	<structfield>reserved2</structfield> field which was previously
1215	mentioned only in the <filename>videodev.h</filename> header
1216	file.</para>
1217		</listitem>
1218	
1219		<listitem>
1220		  <para>New buffer types
1221	<constant>V4L2_TYPE_VBI_INPUT</constant> and
1222	<constant>V4L2_TYPE_VBI_OUTPUT</constant> were added. The former is an
1223	alias for the old <constant>V4L2_TYPE_VBI</constant>, the latter was
1224	missing in the <filename>videodev.h</filename> file.</para>
1225		</listitem>
1226	      </orderedlist>
1227	    </section>
1228	
1229	    <section>
1230	      <title>V4L2 Version 0.20 2002-07-25</title>
1231	      <para>Added sliced VBI interface proposal.</para>
1232	    </section>
1233	
1234	    <section>
1235	      <title>V4L2 in Linux 2.5.46, 2002-10</title>
1236	
1237	      <para>Around October-November 2002, prior to an announced
1238	feature freeze of Linux 2.5, the API was revised, drawing from
1239	experience with V4L2 0.20. This unnamed version was finally merged
1240	into Linux 2.5.46.</para>
1241	
1242	      <orderedlist>
1243		<listitem>
1244		  <para>As specified in <xref linkend="related" />, drivers
1245	must make related device functions available under all minor device
1246	numbers.</para>
1247		</listitem>
1248	
1249		<listitem>
1250		  <para>The &func-open; function requires access mode
1251	<constant>O_RDWR</constant> regardless of the device type. All V4L2
1252	drivers exchanging data with applications must support the
1253	<constant>O_NONBLOCK</constant> flag. The <constant>O_NOIO</constant>
1254	flag, a V4L2 symbol which aliased the meaningless
1255	<constant>O_TRUNC</constant> to indicate accesses without data
1256	exchange (panel applications) was dropped. Drivers must stay in "panel
1257	mode" until the application attempts to initiate a data exchange, see
1258	<xref linkend="open" />.</para>
1259		</listitem>
1260	
1261		<listitem>
1262		  <para>The &v4l2-capability; changed dramatically. Note that
1263	also the size of the structure changed, which is encoded in the ioctl
1264	request code, thus older V4L2 devices will respond with an &EINVAL; to
1265	the new &VIDIOC-QUERYCAP; ioctl.</para>
1266	
1267		  <para>There are new fields to identify the driver, a new RDS
1268	device function <constant>V4L2_CAP_RDS_CAPTURE</constant>, the
1269	<constant>V4L2_CAP_AUDIO</constant> flag indicates if the device has
1270	any audio connectors, another I/O capability
1271	<constant>V4L2_CAP_ASYNCIO</constant> can be flagged. In response to
1272	these changes the <structfield>type</structfield> field became a bit
1273	set and was merged into the <structfield>flags</structfield> field.
1274	<constant>V4L2_FLAG_TUNER</constant> was renamed to
1275	<constant>V4L2_CAP_TUNER</constant>,
1276	<constant>V4L2_CAP_VIDEO_OVERLAY</constant> replaced
1277	<constant>V4L2_FLAG_PREVIEW</constant> and
1278	<constant>V4L2_CAP_VBI_CAPTURE</constant> and
1279	<constant>V4L2_CAP_VBI_OUTPUT</constant> replaced
1280	<constant>V4L2_FLAG_DATA_SERVICE</constant>.
1281	<constant>V4L2_FLAG_READ</constant> and
1282	<constant>V4L2_FLAG_WRITE</constant> were merged into
1283	<constant>V4L2_CAP_READWRITE</constant>.</para>
1284	
1285		  <para>The redundant fields
1286	<structfield>inputs</structfield>, <structfield>outputs</structfield>
1287	and <structfield>audios</structfield> were removed. These properties
1288	can be determined as described in <xref linkend="video" /> and <xref
1289	linkend="audio" />.</para>
1290	
1291		  <para>The somewhat volatile and therefore barely useful
1292	fields <structfield>maxwidth</structfield>,
1293	<structfield>maxheight</structfield>,
1294	<structfield>minwidth</structfield>,
1295	<structfield>minheight</structfield>,
1296	<structfield>maxframerate</structfield> were removed. This information
1297	is available as described in <xref linkend="format" /> and
1298	<xref linkend="standard" />.</para>
1299	
1300		  <para><constant>V4L2_FLAG_SELECT</constant> was removed. We
1301	believe the select() function is important enough to require support
1302	of it in all V4L2 drivers exchanging data with applications. The
1303	redundant <constant>V4L2_FLAG_MONOCHROME</constant> flag was removed,
1304	this information is available as described in <xref
1305		      linkend="format" />.</para>
1306		</listitem>
1307	
1308		<listitem>
1309		  <para>In &v4l2-input; the
1310	<structfield>assoc_audio</structfield> field and the
1311	<structfield>capability</structfield> field and its only flag
1312	<constant>V4L2_INPUT_CAP_AUDIO</constant> was replaced by the new
1313	<structfield>audioset</structfield> field. Instead of linking one
1314	video input to one audio input this field reports all audio inputs
1315	this video input combines with.</para>
1316	
1317		  <para>New fields are <structfield>tuner</structfield>
1318	(reversing the former link from tuners to video inputs),
1319	<structfield>std</structfield> and
1320	<structfield>status</structfield>.</para>
1321	
1322		  <para>Accordingly &v4l2-output; lost its
1323	<structfield>capability</structfield> and
1324	<structfield>assoc_audio</structfield> fields.
1325	<structfield>audioset</structfield>,
1326	<structfield>modulator</structfield> and
1327	<structfield>std</structfield> where added instead.</para>
1328		</listitem>
1329	
1330		<listitem>
1331		  <para>The &v4l2-audio; field
1332	<structfield>audio</structfield> was renamed to
1333	<structfield>index</structfield>, for consistency with other
1334	structures. A new capability flag
1335	<constant>V4L2_AUDCAP_STEREO</constant> was added to indicated if the
1336	audio input in question supports stereo sound.
1337	<constant>V4L2_AUDCAP_EFFECTS</constant> and the corresponding
1338	<constant>V4L2_AUDMODE</constant> flags where removed. This can be
1339	easily implemented using controls. (However the same applies to AVL
1340	which is still there.)</para>
1341	
1342		  <para>Again for consistency the &v4l2-audioout; field
1343	<structfield>audio</structfield> was renamed to
1344	<structfield>index</structfield>.</para>
1345		</listitem>
1346	
1347		<listitem>
1348		  <para>The &v4l2-tuner;
1349	<structfield>input</structfield> field was replaced by an
1350	<structfield>index</structfield> field, permitting devices with
1351	multiple tuners. The link between video inputs and tuners is now
1352	reversed, inputs point to their tuner. The
1353	<structfield>std</structfield> substructure became a
1354	simple set (more about this below) and moved into &v4l2-input;. A
1355	<structfield>type</structfield> field was added.</para>
1356	
1357		  <para>Accordingly in &v4l2-modulator; the
1358	<structfield>output</structfield> was replaced by an
1359	<structfield>index</structfield> field.</para>
1360	
1361		  <para>In &v4l2-frequency; the
1362	<structfield>port</structfield> field was replaced by a
1363	<structfield>tuner</structfield> field containing the respective tuner
1364	or modulator index number. A tuner <structfield>type</structfield>
1365	field was added and the <structfield>reserved</structfield> field
1366	became larger for future extensions (satellite tuners in
1367	particular).</para>
1368		</listitem>
1369	
1370		<listitem>
1371		  <para>The idea of completely transparent video standards was
1372	dropped. Experience showed that applications must be able to work with
1373	video standards beyond presenting the user a menu. Instead of
1374	enumerating supported standards with an ioctl applications can now
1375	refer to standards by &v4l2-std-id; and symbols defined in the
1376	<filename>videodev2.h</filename> header file. For details see <xref
1377		      linkend="standard" />. The &VIDIOC-G-STD; and
1378	&VIDIOC-S-STD; now take a pointer to this type as argument.
1379	&VIDIOC-QUERYSTD; was added to autodetect the received standard, if
1380	the hardware has this capability. In &v4l2-standard; an
1381	<structfield>index</structfield> field was added for &VIDIOC-ENUMSTD;.
1382	A &v4l2-std-id; field named <structfield>id</structfield> was added as
1383	machine readable identifier, also replacing the
1384	<structfield>transmission</structfield> field. The misleading
1385	<structfield>framerate</structfield> field was renamed
1386	to <structfield>frameperiod</structfield>. The now obsolete
1387	<structfield>colorstandard</structfield> information, originally
1388	needed to distguish between variations of standards, were
1389	removed.</para>
1390	
1391		  <para>Struct <structname>v4l2_enumstd</structname> ceased to
1392	be. &VIDIOC-ENUMSTD; now takes a pointer to a &v4l2-standard;
1393	directly. The information which standards are supported by a
1394	particular video input or output moved into &v4l2-input; and
1395	&v4l2-output; fields named <structfield>std</structfield>,
1396	respectively.</para>
1397		</listitem>
1398	
1399		<listitem>
1400		  <para>The &v4l2-queryctrl; fields
1401	<structfield>category</structfield> and
1402	<structfield>group</structfield> did not catch on and/or were not
1403	implemented as expected and therefore removed.</para>
1404		</listitem>
1405	
1406		<listitem>
1407		  <para>The &VIDIOC-TRY-FMT; ioctl was added to negotiate data
1408	formats as with &VIDIOC-S-FMT;, but without the overhead of
1409	programming the hardware and regardless of I/O in progress.</para>
1410	
1411		  <para>In &v4l2-format; the <structfield>fmt</structfield>
1412	union was extended to contain &v4l2-window;. All image format
1413	negotiations are now possible with <constant>VIDIOC_G_FMT</constant>,
1414	<constant>VIDIOC_S_FMT</constant> and
1415	<constant>VIDIOC_TRY_FMT</constant>; ioctl. The
1416	<constant>VIDIOC_G_WIN</constant> and
1417	<constant>VIDIOC_S_WIN</constant> ioctls to prepare for a video
1418	overlay were removed. The <structfield>type</structfield> field
1419	changed to type &v4l2-buf-type; and the buffer type names changed as
1420	follows.<informaltable>
1421		      <tgroup cols="2">
1422			<thead>
1423			  <row>
1424			    <entry>Old defines</entry>
1425			    <entry>&v4l2-buf-type;</entry>
1426			  </row>
1427			</thead>
1428			<tbody valign="top">
1429			  <row>
1430			    <entry><constant>V4L2_BUF_TYPE_CAPTURE</constant></entry>
1431			    <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry>
1432			  </row>
1433			  <row>
1434			    <entry><constant>V4L2_BUF_TYPE_CODECIN</constant></entry>
1435			    <entry>Omitted for now</entry>
1436			  </row>
1437			  <row>
1438			    <entry><constant>V4L2_BUF_TYPE_CODECOUT</constant></entry>
1439			    <entry>Omitted for now</entry>
1440			  </row>
1441			  <row>
1442			    <entry><constant>V4L2_BUF_TYPE_EFFECTSIN</constant></entry>
1443			    <entry>Omitted for now</entry>
1444			  </row>
1445			  <row>
1446			    <entry><constant>V4L2_BUF_TYPE_EFFECTSIN2</constant></entry>
1447			    <entry>Omitted for now</entry>
1448			  </row>
1449			  <row>
1450			    <entry><constant>V4L2_BUF_TYPE_EFFECTSOUT</constant></entry>
1451			    <entry>Omitted for now</entry>
1452			  </row>
1453			  <row>
1454			    <entry><constant>V4L2_BUF_TYPE_VIDEOOUT</constant></entry>
1455			    <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry>
1456			  </row>
1457			  <row>
1458			    <entry><constant>-</constant></entry>
1459			    <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry>
1460			  </row>
1461			  <row>
1462			    <entry><constant>-</constant></entry>
1463			    <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry>
1464			  </row>
1465			  <row>
1466			    <entry><constant>-</constant></entry>
1467			    <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry>
1468			  </row>
1469			  <row>
1470			    <entry><constant>-</constant></entry>
1471			    <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry>
1472			  </row>
1473			  <row>
1474			    <entry><constant>-</constant></entry>
1475			    <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry>
1476			  </row>
1477			  <row>
1478			    <entry><constant>V4L2_BUF_TYPE_PRIVATE_BASE</constant></entry>
1479			    <entry><constant>V4L2_BUF_TYPE_PRIVATE</constant> (but this is deprecated)</entry>
1480			  </row>
1481			</tbody>
1482		      </tgroup>
1483		    </informaltable></para>
1484		</listitem>
1485	
1486		<listitem>
1487		  <para>In &v4l2-fmtdesc; a &v4l2-buf-type; field named
1488	<structfield>type</structfield> was added as in &v4l2-format;. The
1489	<constant>VIDIOC_ENUM_FBUFFMT</constant> ioctl is no longer needed and
1490	was removed. These calls can be replaced by &VIDIOC-ENUM-FMT; with
1491	type <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>.</para>
1492		</listitem>
1493	
1494		<listitem>
1495		  <para>In &v4l2-pix-format; the
1496	<structfield>depth</structfield> field was removed, assuming
1497	applications which recognize the format by its four-character-code
1498	already know the color depth, and others do not care about it. The
1499	same rationale lead to the removal of the
1500	<constant>V4L2_FMT_FLAG_COMPRESSED</constant> flag. The
1501	<constant>V4L2_FMT_FLAG_SWCONVECOMPRESSED</constant> flag was removed
1502	because drivers are not supposed to convert images in kernel space. A
1503	user library of conversion functions should be provided instead. The
1504	<constant>V4L2_FMT_FLAG_BYTESPERLINE</constant> flag was redundant.
1505	Applications can set the <structfield>bytesperline</structfield> field
1506	to zero to get a reasonable default. Since the remaining flags were
1507	replaced as well, the <structfield>flags</structfield> field itself
1508	was removed.</para>
1509		  <para>The interlace flags were replaced by a &v4l2-field;
1510	value in a newly added <structfield>field</structfield>
1511	field.<informaltable>
1512		      <tgroup cols="2">
1513			<thead>
1514			  <row>
1515			    <entry>Old flag</entry>
1516			    <entry>&v4l2-field;</entry>
1517			  </row>
1518			</thead>
1519			<tbody valign="top">
1520			  <row>
1521			    <entry><constant>V4L2_FMT_FLAG_NOT_INTERLACED</constant></entry>
1522			    <entry>?</entry>
1523			  </row>
1524			  <row>
1525			    <entry><constant>V4L2_FMT_FLAG_INTERLACED</constant>
1526	= <constant>V4L2_FMT_FLAG_COMBINED</constant></entry>
1527			    <entry><constant>V4L2_FIELD_INTERLACED</constant></entry>
1528			  </row>
1529			  <row>
1530			    <entry><constant>V4L2_FMT_FLAG_TOPFIELD</constant>
1531	= <constant>V4L2_FMT_FLAG_ODDFIELD</constant></entry>
1532			    <entry><constant>V4L2_FIELD_TOP</constant></entry>
1533			  </row>
1534			  <row>
1535			    <entry><constant>V4L2_FMT_FLAG_BOTFIELD</constant>
1536	= <constant>V4L2_FMT_FLAG_EVENFIELD</constant></entry>
1537			    <entry><constant>V4L2_FIELD_BOTTOM</constant></entry>
1538			  </row>
1539			  <row>
1540			    <entry><constant>-</constant></entry>
1541			    <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry>
1542			  </row>
1543			  <row>
1544			    <entry><constant>-</constant></entry>
1545			    <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry>
1546			  </row>
1547			  <row>
1548			    <entry><constant>-</constant></entry>
1549			    <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry>
1550			  </row>
1551			</tbody>
1552		      </tgroup>
1553		    </informaltable></para>
1554	
1555		  <para>The color space flags were replaced by a
1556	&v4l2-colorspace; value in a newly added
1557	<structfield>colorspace</structfield> field, where one of
1558	<constant>V4L2_COLORSPACE_SMPTE170M</constant>,
1559	<constant>V4L2_COLORSPACE_BT878</constant>,
1560	<constant>V4L2_COLORSPACE_470_SYSTEM_M</constant> or
1561	<constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant> replaces
1562	<constant>V4L2_FMT_CS_601YUV</constant>.</para>
1563		</listitem>
1564	
1565		<listitem>
1566		  <para>In &v4l2-requestbuffers; the
1567	<structfield>type</structfield> field was properly defined as
1568	&v4l2-buf-type;. Buffer types changed as mentioned above. A new
1569	<structfield>memory</structfield> field of type &v4l2-memory; was
1570	added to distinguish between I/O methods using buffers allocated
1571	by the driver or the application. See <xref linkend="io" /> for
1572	details.</para>
1573		</listitem>
1574	
1575		<listitem>
1576		  <para>In &v4l2-buffer; the <structfield>type</structfield>
1577	field was properly defined as &v4l2-buf-type;. Buffer types changed as
1578	mentioned above. A <structfield>field</structfield> field of type
1579	&v4l2-field; was added to indicate if a buffer contains a top or
1580	bottom field. The old field flags were removed. Since no unadjusted
1581	system time clock was added to the kernel as planned, the
1582	<structfield>timestamp</structfield> field changed back from type
1583	stamp_t, an unsigned 64 bit integer expressing the sample time in
1584	nanoseconds, to struct <structname>timeval</structname>. With the
1585	addition of a second memory mapping method the
1586	<structfield>offset</structfield> field moved into union
1587	<structfield>m</structfield>, and a new
1588	<structfield>memory</structfield> field of type &v4l2-memory; was
1589	added to distinguish between I/O methods. See <xref linkend="io" />
1590	for details.</para>
1591	
1592		  <para>The <constant>V4L2_BUF_REQ_CONTIG</constant>
1593	flag was used by the V4L compatibility layer, after changes to this
1594	code it was no longer needed. The
1595	<constant>V4L2_BUF_ATTR_DEVICEMEM</constant> flag would indicate if
1596	the buffer was indeed allocated in device memory rather than DMA-able
1597	system memory. It was barely useful and so was removed.</para>
1598		</listitem>
1599	
1600		<listitem>
1601		  <para>In &v4l2-framebuffer; the
1602	<structfield>base[3]</structfield> array anticipating double- and
1603	triple-buffering in off-screen video memory, however without defining
1604	a synchronization mechanism, was replaced by a single pointer. The
1605	<constant>V4L2_FBUF_CAP_SCALEUP</constant> and
1606	<constant>V4L2_FBUF_CAP_SCALEDOWN</constant> flags were removed.
1607	Applications can determine this capability more accurately using the
1608	new cropping and scaling interface. The
1609	<constant>V4L2_FBUF_CAP_CLIPPING</constant> flag was replaced by
1610	<constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant> and
1611	<constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant>.</para>
1612		</listitem>
1613	
1614		<listitem>
1615		  <para>In &v4l2-clip; the <structfield>x</structfield>,
1616	<structfield>y</structfield>, <structfield>width</structfield> and
1617	<structfield>height</structfield> field moved into a
1618	<structfield>c</structfield> substructure of type &v4l2-rect;. The
1619	<structfield>x</structfield> and <structfield>y</structfield> fields
1620	were renamed to <structfield>left</structfield> and
1621	<structfield>top</structfield>, &ie; offsets to a context dependent
1622	origin.</para>
1623		</listitem>
1624	
1625		<listitem>
1626		  <para>In &v4l2-window; the <structfield>x</structfield>,
1627	<structfield>y</structfield>, <structfield>width</structfield> and
1628	<structfield>height</structfield> field moved into a
1629	<structfield>w</structfield> substructure as above. A
1630	<structfield>field</structfield> field of type %v4l2-field; was added
1631	to distinguish between field and frame (interlaced) overlay.</para>
1632		</listitem>
1633	
1634		<listitem>
1635		  <para>The digital zoom interface, including struct
1636	<structname>v4l2_zoomcap</structname>, struct
1637	<structname>v4l2_zoom</structname>,
1638	<constant>V4L2_ZOOM_NONCAP</constant> and
1639	<constant>V4L2_ZOOM_WHILESTREAMING</constant> was replaced by a new
1640	cropping and scaling interface. The previously unused struct
1641	<structname>v4l2_cropcap</structname> and
1642	<structname>v4l2_crop</structname> where redefined for this purpose.
1643	See <xref linkend="crop" /> for details.</para>
1644		</listitem>
1645	
1646		<listitem>
1647		  <para>In &v4l2-vbi-format; the
1648	<structfield>SAMPLE_FORMAT</structfield> field now contains a
1649	four-character-code as used to identify video image formats and
1650	<constant>V4L2_PIX_FMT_GREY</constant> replaces the
1651	<constant>V4L2_VBI_SF_UBYTE</constant> define. The
1652	<structfield>reserved</structfield> field was extended.</para>
1653		</listitem>
1654	
1655		<listitem>
1656		  <para>In &v4l2-captureparm; the type of the
1657	<structfield>timeperframe</structfield> field changed from unsigned
1658	long to &v4l2-fract;. This allows the accurate expression of multiples
1659	of the NTSC-M frame rate 30000 / 1001. A new field
1660	<structfield>readbuffers</structfield> was added to control the driver
1661	behaviour in read I/O mode.</para>
1662	
1663		  <para>Similar changes were made to &v4l2-outputparm;.</para>
1664		</listitem>
1665	
1666		<listitem>
1667		  <para>The struct <structname>v4l2_performance</structname>
1668	and <constant>VIDIOC_G_PERF</constant> ioctl were dropped. Except when
1669	using the <link linkend="rw">read/write I/O method</link>, which is
1670	limited anyway, this information is already available to
1671	applications.</para>
1672		</listitem>
1673	
1674		<listitem>
1675		  <para>The example transformation from RGB to YCbCr color
1676	space in the old V4L2 documentation was inaccurate, this has been
1677	corrected in <xref linkend="pixfmt" />.<!-- 0.5670G should be
1678	0.587, and 127/112 != 255/224 --></para>
1679		</listitem>
1680	      </orderedlist>
1681	    </section>
1682	
1683	    <section>
1684	      <title>V4L2 2003-06-19</title>
1685	
1686	      <orderedlist>
1687		<listitem>
1688		  <para>A new capability flag
1689	<constant>V4L2_CAP_RADIO</constant> was added for radio devices. Prior
1690	to this change radio devices would identify solely by having exactly one
1691	tuner whose type field reads <constant>V4L2_TUNER_RADIO</constant>.</para>
1692		</listitem>
1693	
1694		<listitem>
1695		  <para>An optional driver access priority mechanism was
1696	added, see <xref linkend="app-pri" /> for details.</para>
1697		</listitem>
1698	
1699		<listitem>
1700		  <para>The audio input and output interface was found to be
1701	incomplete.</para>
1702		  <para>Previously the &VIDIOC-G-AUDIO;
1703	ioctl would enumerate the available audio inputs. An ioctl to
1704	determine the current audio input, if more than one combines with the
1705	current video input, did not exist. So
1706	<constant>VIDIOC_G_AUDIO</constant> was renamed to
1707	<constant>VIDIOC_G_AUDIO_OLD</constant>, this ioctl was removed on
1708	Kernel 2.6.39. The &VIDIOC-ENUMAUDIO; ioctl was added to enumerate
1709	audio inputs, while &VIDIOC-G-AUDIO; now reports the current audio
1710	input.</para>
1711		  <para>The same changes were made to &VIDIOC-G-AUDOUT; and
1712	&VIDIOC-ENUMAUDOUT;.</para>
1713		  <para>Until further the "videodev" module will automatically
1714	translate between the old and new ioctls, but drivers and applications
1715	must be updated to successfully compile again.</para>
1716		</listitem>
1717	
1718		<listitem>
1719		  <para>The &VIDIOC-OVERLAY; ioctl was incorrectly defined with
1720	write-read parameter. It was changed to write-only, while the write-read
1721	version was renamed to <constant>VIDIOC_OVERLAY_OLD</constant>. The old
1722	ioctl was removed on Kernel 2.6.39. Until further the "videodev"
1723	kernel module will automatically translate to the new version, so drivers
1724	must be recompiled, but not applications.</para>
1725		</listitem>
1726	
1727		<listitem>
1728		  <para><xref linkend="overlay" /> incorrectly stated that
1729	clipping rectangles define regions where the video can be seen.
1730	Correct is that clipping rectangles define regions where
1731	<emphasis>no</emphasis> video shall be displayed and so the graphics
1732	surface can be seen.</para>
1733		</listitem>
1734	
1735		<listitem>
1736		  <para>The &VIDIOC-S-PARM; and &VIDIOC-S-CTRL; ioctls were
1737	defined with write-only parameter, inconsistent with other ioctls
1738	modifying their argument. They were changed to write-read, while a
1739	<constant>_OLD</constant> suffix was added to the write-only versions.
1740	The old ioctls were removed on Kernel 2.6.39. Drivers and
1741	applications assuming a constant parameter need an update.</para>
1742		</listitem>
1743	      </orderedlist>
1744	    </section>
1745	
1746	    <section>
1747	      <title>V4L2 2003-11-05</title>
1748	      <orderedlist>
1749		<listitem>
1750		  <para>In <xref linkend="pixfmt-rgb" /> the following pixel
1751	formats were incorrectly transferred from Bill Dirks' V4L2
1752	specification. Descriptions below refer to bytes in memory, in
1753	ascending address order.<informaltable>
1754		      <tgroup cols="3">
1755			<thead>
1756			  <row>
1757			    <entry>Symbol</entry>
1758			    <entry>In this document prior to revision
1759	0.5</entry>
1760			    <entry>Corrected</entry>
1761			  </row>
1762			</thead>
1763			<tbody valign="top">
1764			  <row>
1765			    <entry><constant>V4L2_PIX_FMT_RGB24</constant></entry>
1766			    <entry>B, G, R</entry>
1767			    <entry>R, G, B</entry>
1768			  </row>
1769			  <row>
1770			    <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry>
1771			    <entry>R, G, B</entry>
1772			    <entry>B, G, R</entry>
1773			  </row>
1774			  <row>
1775			    <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry>
1776			    <entry>B, G, R, X</entry>
1777			    <entry>R, G, B, X</entry>
1778			  </row>
1779			  <row>
1780			    <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry>
1781			    <entry>R, G, B, X</entry>
1782			    <entry>B, G, R, X</entry>
1783			  </row>
1784			</tbody>
1785		      </tgroup>
1786		    </informaltable> The
1787	<constant>V4L2_PIX_FMT_BGR24</constant> example was always
1788	correct.</para>
1789		  <para>In <xref linkend="v4l-image-properties" /> the mapping
1790	of the V4L <constant>VIDEO_PALETTE_RGB24</constant> and
1791	<constant>VIDEO_PALETTE_RGB32</constant> formats to V4L2 pixel formats
1792	was accordingly corrected.</para>
1793		</listitem>
1794	
1795		<listitem>
1796		  <para>Unrelated to the fixes above, drivers may still
1797	interpret some V4L2 RGB pixel formats differently. These issues have
1798	yet to be addressed, for details see <xref
1799		      linkend="pixfmt-rgb" />.</para>
1800		</listitem>
1801	      </orderedlist>
1802	    </section>
1803	
1804	    <section>
1805	      <title>V4L2 in Linux 2.6.6, 2004-05-09</title>
1806	      <orderedlist>
1807		<listitem>
1808		  <para>The &VIDIOC-CROPCAP; ioctl was incorrectly defined
1809	with read-only parameter. It is now defined as write-read ioctl, while
1810	the read-only version was renamed to
1811	<constant>VIDIOC_CROPCAP_OLD</constant>. The old ioctl was removed
1812	on Kernel 2.6.39.</para>
1813		</listitem>
1814	      </orderedlist>
1815	    </section>
1816	
1817	    <section>
1818	      <title>V4L2 in Linux 2.6.8</title>
1819	      <orderedlist>
1820		<listitem>
1821		  <para>A new field <structfield>input</structfield> (former
1822	<structfield>reserved[0]</structfield>) was added to the &v4l2-buffer;
1823	structure. Purpose of this field is to alternate between video inputs
1824	(&eg; cameras) in step with the video capturing process. This function
1825	must be enabled with the new <constant>V4L2_BUF_FLAG_INPUT</constant>
1826	flag. The <structfield>flags</structfield> field is no longer
1827	read-only.</para>
1828		</listitem>
1829	      </orderedlist>
1830	    </section>
1831	
1832	    <section>
1833	      <title>V4L2 spec erratum 2004-08-01</title>
1834	
1835	      <orderedlist>
1836		<listitem>
1837		  <para>The return value of the
1838	<xref linkend="func-open" /> function was incorrectly documented.</para>
1839		</listitem>
1840	
1841		<listitem>
1842		  <para>Audio output ioctls end in -AUDOUT, not -AUDIOOUT.</para>
1843		</listitem>
1844	
1845		<listitem>
1846		  <para>In the Current Audio Input example the
1847	<constant>VIDIOC_G_AUDIO</constant> ioctl took the wrong
1848	argument.</para>
1849		</listitem>
1850	
1851		<listitem>
1852		  <para>The documentation of the &VIDIOC-QBUF; and
1853	&VIDIOC-DQBUF; ioctls did not mention the &v4l2-buffer;
1854	<structfield>memory</structfield> field. It was also missing from
1855	examples. Also on the <constant>VIDIOC_DQBUF</constant> page the &EIO;
1856	was not documented.</para>
1857		</listitem>
1858	      </orderedlist>
1859	    </section>
1860	
1861	    <section>
1862	      <title>V4L2 in Linux 2.6.14</title>
1863	      <orderedlist>
1864		<listitem>
1865		  <para>A new sliced VBI interface was added. It is documented
1866	in <xref linkend="sliced" /> and replaces the interface first
1867	proposed in V4L2 specification 0.8.</para>
1868		</listitem>
1869	      </orderedlist>
1870	    </section>
1871	
1872	    <section>
1873	      <title>V4L2 in Linux 2.6.15</title>
1874	      <orderedlist>
1875		<listitem>
1876		  <para>The &VIDIOC-LOG-STATUS; ioctl was added.</para>
1877		</listitem>
1878	
1879		<listitem>
1880		  <para>New video standards
1881	<constant>V4L2_STD_NTSC_443</constant>,
1882	<constant>V4L2_STD_SECAM_LC</constant>,
1883	<constant>V4L2_STD_SECAM_DK</constant> (a set of SECAM D, K and K1),
1884	and <constant>V4L2_STD_ATSC</constant> (a set of
1885	<constant>V4L2_STD_ATSC_8_VSB</constant> and
1886	<constant>V4L2_STD_ATSC_16_VSB</constant>) were defined. Note the
1887	<constant>V4L2_STD_525_60</constant> set now includes
1888	<constant>V4L2_STD_NTSC_443</constant>. See also <xref
1889		      linkend="v4l2-std-id" />.</para>
1890		</listitem>
1891	
1892		<listitem>
1893		  <para>The <constant>VIDIOC_G_COMP</constant> and
1894	<constant>VIDIOC_S_COMP</constant> ioctl were renamed to
1895	<constant>VIDIOC_G_MPEGCOMP</constant> and
1896	<constant>VIDIOC_S_MPEGCOMP</constant> respectively. Their argument
1897	was replaced by a struct
1898	<structname>v4l2_mpeg_compression</structname> pointer. (The
1899	<constant>VIDIOC_G_MPEGCOMP</constant> and
1900	<constant>VIDIOC_S_MPEGCOMP</constant> ioctls where removed in Linux
1901	2.6.25.)</para>
1902		</listitem>
1903	      </orderedlist>
1904	    </section>
1905	
1906	    <section>
1907	      <title>V4L2 spec erratum 2005-11-27</title>
1908	      <para>The capture example in <xref linkend="capture-example" />
1909	called the &VIDIOC-S-CROP; ioctl without checking if cropping is
1910	supported. In the video standard selection example in
1911	<xref linkend="standard" /> the &VIDIOC-S-STD; call used the wrong
1912	argument type.</para>
1913	    </section>
1914	
1915	    <section>
1916	      <title>V4L2 spec erratum 2006-01-10</title>
1917	      <orderedlist>
1918		<listitem>
1919		  <para>The <constant>V4L2_IN_ST_COLOR_KILL</constant> flag in
1920	&v4l2-input; not only indicates if the color killer is enabled, but
1921	also if it is active. (The color killer disables color decoding when
1922	it detects no color in the video signal to improve the image
1923	quality.)</para>
1924		</listitem>
1925	
1926		<listitem>
1927		  <para>&VIDIOC-S-PARM; is a write-read ioctl, not write-only as
1928	stated on its reference page. The ioctl changed in 2003 as noted above.</para>
1929		</listitem>
1930	      </orderedlist>
1931	    </section>
1932	
1933	    <section>
1934	      <title>V4L2 spec erratum 2006-02-03</title>
1935	      <orderedlist>
1936		<listitem>
1937		  <para>In &v4l2-captureparm; and &v4l2-outputparm; the
1938	<structfield>timeperframe</structfield> field gives the time in
1939	seconds, not microseconds.</para>
1940		</listitem>
1941	      </orderedlist>
1942	    </section>
1943	
1944	    <section>
1945	      <title>V4L2 spec erratum 2006-02-04</title>
1946	      <orderedlist>
1947		<listitem>
1948		  <para>The <structfield>clips</structfield> field in
1949	&v4l2-window; must point to an array of &v4l2-clip;, not a linked
1950	list, because drivers ignore the struct
1951	<structname>v4l2_clip</structname>.<structfield>next</structfield>
1952	pointer.</para>
1953		</listitem>
1954	      </orderedlist>
1955	    </section>
1956	
1957	    <section>
1958	      <title>V4L2 in Linux 2.6.17</title>
1959	      <orderedlist>
1960		<listitem>
1961		  <para>New video standard macros were added:
1962	<constant>V4L2_STD_NTSC_M_KR</constant> (NTSC M South Korea), and the
1963	sets <constant>V4L2_STD_MN</constant>,
1964	<constant>V4L2_STD_B</constant>, <constant>V4L2_STD_GH</constant> and
1965	<constant>V4L2_STD_DK</constant>. The
1966	<constant>V4L2_STD_NTSC</constant> and
1967	<constant>V4L2_STD_SECAM</constant> sets now include
1968	<constant>V4L2_STD_NTSC_M_KR</constant> and
1969	<constant>V4L2_STD_SECAM_LC</constant> respectively.</para>
1970		</listitem>
1971	
1972		<listitem>
1973		  <para>A new <constant>V4L2_TUNER_MODE_LANG1_LANG2</constant>
1974	was defined to record both languages of a bilingual program. The
1975	use of <constant>V4L2_TUNER_MODE_STEREO</constant> for this purpose
1976	is deprecated now. See the &VIDIOC-G-TUNER; section for
1977	details.</para>
1978		</listitem>
1979	      </orderedlist>
1980	    </section>
1981	
1982	    <section>
1983	      <title>V4L2 spec erratum 2006-09-23 (Draft 0.15)</title>
1984	      <orderedlist>
1985		<listitem>
1986		  <para>In various places
1987	<constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> and
1988	<constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant> of the sliced VBI
1989	interface were not mentioned along with other buffer types.</para>
1990		</listitem>
1991	
1992		<listitem>
1993		  <para>In <xref linkend="vidioc-g-audio" /> it was clarified
1994	that the &v4l2-audio; <structfield>mode</structfield> field is a flags
1995	field.</para>
1996		</listitem>
1997	
1998		<listitem>
1999		  <para><xref linkend="vidioc-querycap" /> did not mention the
2000	sliced VBI and radio capability flags.</para>
2001		</listitem>
2002	
2003		<listitem>
2004		  <para>In <xref linkend="vidioc-g-frequency" /> it was
2005	clarified that applications must initialize the tuner
2006	<structfield>type</structfield> field of &v4l2-frequency; before
2007	calling &VIDIOC-S-FREQUENCY;.</para>
2008		</listitem>
2009	
2010		<listitem>
2011		  <para>The <structfield>reserved</structfield> array
2012	in &v4l2-requestbuffers; has 2 elements, not 32.</para>
2013		</listitem>
2014	
2015		<listitem>
2016		  <para>In <xref linkend="output" /> and <xref
2017		      linkend="raw-vbi" /> the device file names
2018	<filename>/dev/vout</filename> which never caught on were replaced
2019	by <filename>/dev/video</filename>.</para>
2020		</listitem>
2021	
2022		<listitem>
2023		  <para>With Linux 2.6.15 the possible range for VBI device minor
2024	numbers was extended from 224-239 to 224-255. Accordingly device file names
2025	<filename>/dev/vbi0</filename> to <filename>/dev/vbi31</filename> are
2026	possible now.</para>
2027		</listitem>
2028	      </orderedlist>
2029	    </section>
2030	
2031	    <section>
2032	      <title>V4L2 in Linux 2.6.18</title>
2033	      <orderedlist>
2034		<listitem>
2035		  <para>New ioctls &VIDIOC-G-EXT-CTRLS;, &VIDIOC-S-EXT-CTRLS;
2036	and &VIDIOC-TRY-EXT-CTRLS; were added, a flag to skip unsupported
2037	controls with &VIDIOC-QUERYCTRL;, new control types
2038	<constant>V4L2_CTRL_TYPE_INTEGER64</constant> and
2039	<constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant> (<xref
2040		      linkend="v4l2-ctrl-type" />), and new control flags
2041	<constant>V4L2_CTRL_FLAG_READ_ONLY</constant>,
2042	<constant>V4L2_CTRL_FLAG_UPDATE</constant>,
2043	<constant>V4L2_CTRL_FLAG_INACTIVE</constant> and
2044	<constant>V4L2_CTRL_FLAG_SLIDER</constant> (<xref
2045		      linkend="control-flags" />). See <xref
2046		      linkend="extended-controls" /> for details.</para>
2047		</listitem>
2048	      </orderedlist>
2049	    </section>
2050	
2051	    <section>
2052	      <title>V4L2 in Linux 2.6.19</title>
2053	      <orderedlist>
2054		<listitem>
2055		  <para>In &v4l2-sliced-vbi-cap; a buffer type field was added
2056	replacing a reserved field. Note on architectures where the size of
2057	enum types differs from int types the size of the structure changed.
2058	The &VIDIOC-G-SLICED-VBI-CAP; ioctl was redefined from being read-only
2059	to write-read. Applications must initialize the type field and clear
2060	the reserved fields now. These changes may <emphasis>break the
2061	compatibility</emphasis> with older drivers and applications.</para>
2062		</listitem>
2063	
2064		<listitem>
2065		  <para>The ioctls &VIDIOC-ENUM-FRAMESIZES; and
2066	&VIDIOC-ENUM-FRAMEINTERVALS; were added.</para>
2067		</listitem>
2068	
2069		<listitem>
2070		  <para>A new pixel format <constant>V4L2_PIX_FMT_RGB444</constant> (<xref
2071	linkend="rgb-formats" />) was added.</para>
2072		</listitem>
2073	      </orderedlist>
2074	    </section>
2075	
2076	    <section>
2077	      <title>V4L2 spec erratum 2006-10-12 (Draft 0.17)</title>
2078	      <orderedlist>
2079		<listitem>
2080		  <para><constant>V4L2_PIX_FMT_HM12</constant> (<xref
2081	linkend="reserved-formats" />) is a YUV 4:2:0, not 4:2:2 format.</para>
2082		</listitem>
2083	      </orderedlist>
2084	    </section>
2085	
2086	    <section>
2087	      <title>V4L2 in Linux 2.6.21</title>
2088	      <orderedlist>
2089		<listitem>
2090		  <para>The <filename>videodev2.h</filename> header file is
2091	now dual licensed under GNU General Public License version two or
2092	later, and under a 3-clause BSD-style license.</para>
2093		</listitem>
2094	      </orderedlist>
2095	    </section>
2096	
2097	    <section>
2098	      <title>V4L2 in Linux 2.6.22</title>
2099	      <orderedlist>
2100		<listitem>
2101		  <para>Two new field orders
2102		  <constant>V4L2_FIELD_INTERLACED_TB</constant> and
2103		  <constant>V4L2_FIELD_INTERLACED_BT</constant> were
2104		  added. See <xref linkend="v4l2-field" /> for details.</para>
2105		</listitem>
2106	
2107		<listitem>
2108		  <para>Three new clipping/blending methods with a global or
2109	straight or inverted local alpha value were added to the video overlay
2110	interface. See the description of the &VIDIOC-G-FBUF; and
2111	&VIDIOC-S-FBUF; ioctls for details.</para>
2112		  <para>A new <structfield>global_alpha</structfield> field
2113	was added to <link
2114	linkend="v4l2-window"><structname>v4l2_window</structname></link>,
2115	extending the structure. This may <emphasis>break
2116	compatibility</emphasis> with applications using a struct
2117	<structname>v4l2_window</structname> directly. However the <link
2118	linkend="vidioc-g-fmt">VIDIOC_G/S/TRY_FMT</link> ioctls, which take a
2119	pointer to a <link linkend="v4l2-format">v4l2_format</link> parent
2120	structure with padding bytes at the end, are not affected.</para>
2121		</listitem>
2122	
2123		<listitem>
2124		  <para>The format of the <structfield>chromakey</structfield>
2125	field in &v4l2-window; changed from "host order RGB32" to a pixel
2126	value in the same format as the framebuffer. This may <emphasis>break
2127	compatibility</emphasis> with existing applications. Drivers
2128	supporting the "host order RGB32" format are not known.</para>
2129		</listitem>
2130	
2131	      </orderedlist>
2132	    </section>
2133	
2134	    <section>
2135	      <title>V4L2 in Linux 2.6.24</title>
2136	      <orderedlist>
2137		<listitem>
2138		  <para>The pixel formats
2139	<constant>V4L2_PIX_FMT_PAL8</constant>,
2140	<constant>V4L2_PIX_FMT_YUV444</constant>,
2141	<constant>V4L2_PIX_FMT_YUV555</constant>,
2142	<constant>V4L2_PIX_FMT_YUV565</constant> and
2143	<constant>V4L2_PIX_FMT_YUV32</constant> were added.</para>
2144		</listitem>
2145	      </orderedlist>
2146	    </section>
2147	
2148	    <section>
2149	      <title>V4L2 in Linux 2.6.25</title>
2150	      <orderedlist>
2151		<listitem>
2152		  <para>The pixel formats <link linkend="V4L2-PIX-FMT-Y16">
2153	<constant>V4L2_PIX_FMT_Y16</constant></link> and <link
2154	linkend="V4L2-PIX-FMT-SBGGR16">
2155	<constant>V4L2_PIX_FMT_SBGGR16</constant></link> were added.</para>
2156		</listitem>
2157		<listitem>
2158		  <para>New <link linkend="control">controls</link>
2159	<constant>V4L2_CID_POWER_LINE_FREQUENCY</constant>,
2160	<constant>V4L2_CID_HUE_AUTO</constant>,
2161	<constant>V4L2_CID_WHITE_BALANCE_TEMPERATURE</constant>,
2162	<constant>V4L2_CID_SHARPNESS</constant> and
2163	<constant>V4L2_CID_BACKLIGHT_COMPENSATION</constant> were added. The
2164	controls <constant>V4L2_CID_BLACK_LEVEL</constant>,
2165	<constant>V4L2_CID_WHITENESS</constant>,
2166	<constant>V4L2_CID_HCENTER</constant> and
2167	<constant>V4L2_CID_VCENTER</constant> were deprecated.
2168	</para>
2169		</listitem>
2170		<listitem>
2171		  <para>A <link linkend="camera-controls">Camera controls
2172	class</link> was added, with the new controls
2173	<constant>V4L2_CID_EXPOSURE_AUTO</constant>,
2174	<constant>V4L2_CID_EXPOSURE_ABSOLUTE</constant>,
2175	<constant>V4L2_CID_EXPOSURE_AUTO_PRIORITY</constant>,
2176	<constant>V4L2_CID_PAN_RELATIVE</constant>,
2177	<constant>V4L2_CID_TILT_RELATIVE</constant>,
2178	<constant>V4L2_CID_PAN_RESET</constant>,
2179	<constant>V4L2_CID_TILT_RESET</constant>,
2180	<constant>V4L2_CID_PAN_ABSOLUTE</constant>,
2181	<constant>V4L2_CID_TILT_ABSOLUTE</constant>,
2182	<constant>V4L2_CID_FOCUS_ABSOLUTE</constant>,
2183	<constant>V4L2_CID_FOCUS_RELATIVE</constant> and
2184	<constant>V4L2_CID_FOCUS_AUTO</constant>.</para>
2185		</listitem>
2186		<listitem>
2187		  <para>The <constant>VIDIOC_G_MPEGCOMP</constant> and
2188	<constant>VIDIOC_S_MPEGCOMP</constant> ioctls, which were superseded
2189	by the <link linkend="extended-controls">extended controls</link>
2190	interface in Linux 2.6.18, where finally removed from the
2191	<filename>videodev2.h</filename> header file.</para>
2192		</listitem>
2193	      </orderedlist>
2194	    </section>
2195	
2196	    <section>
2197	      <title>V4L2 in Linux 2.6.26</title>
2198	      <orderedlist>
2199		<listitem>
2200		  <para>The pixel formats
2201	<constant>V4L2_PIX_FMT_Y16</constant> and
2202	<constant>V4L2_PIX_FMT_SBGGR16</constant> were added.</para>
2203		</listitem>
2204		<listitem>
2205		  <para>Added user controls
2206	<constant>V4L2_CID_CHROMA_AGC</constant> and
2207	<constant>V4L2_CID_COLOR_KILLER</constant>.</para>
2208		</listitem>
2209	      </orderedlist>
2210	    </section>
2211	
2212	    <section>
2213	      <title>V4L2 in Linux 2.6.27</title>
2214	      <orderedlist>
2215		<listitem>
2216		  <para>The &VIDIOC-S-HW-FREQ-SEEK; ioctl and the
2217	<constant>V4L2_CAP_HW_FREQ_SEEK</constant> capability were added.</para>
2218		</listitem>
2219		<listitem>
2220		  <para>The pixel formats
2221	<constant>V4L2_PIX_FMT_YVYU</constant>,
2222	<constant>V4L2_PIX_FMT_PCA501</constant>,
2223	<constant>V4L2_PIX_FMT_PCA505</constant>,
2224	<constant>V4L2_PIX_FMT_PCA508</constant>,
2225	<constant>V4L2_PIX_FMT_PCA561</constant>,
2226	<constant>V4L2_PIX_FMT_SGBRG8</constant>,
2227	<constant>V4L2_PIX_FMT_PAC207</constant> and
2228	<constant>V4L2_PIX_FMT_PJPG</constant> were added.</para>
2229		</listitem>
2230	      </orderedlist>
2231	    </section>
2232	
2233	    <section>
2234	      <title>V4L2 in Linux 2.6.28</title>
2235	      <orderedlist>
2236		<listitem>
2237		  <para>Added <constant>V4L2_MPEG_AUDIO_ENCODING_AAC</constant> and
2238	<constant>V4L2_MPEG_AUDIO_ENCODING_AC3</constant> MPEG audio encodings.</para>
2239		</listitem>
2240		<listitem>
2241		  <para>Added <constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC</constant> MPEG
2242	video encoding.</para>
2243		</listitem>
2244		<listitem>
2245		  <para>The pixel formats
2246	<constant>V4L2_PIX_FMT_SGRBG10</constant> and
2247	<constant>V4L2_PIX_FMT_SGRBG10DPCM8</constant> were added.</para>
2248		</listitem>
2249	      </orderedlist>
2250	    </section>
2251	
2252	    <section>
2253	      <title>V4L2 in Linux 2.6.29</title>
2254	      <orderedlist>
2255		<listitem>
2256		  <para>The <constant>VIDIOC_G_CHIP_IDENT</constant> ioctl was renamed
2257	to <constant>VIDIOC_G_CHIP_IDENT_OLD</constant> and <constant>VIDIOC_DBG_G_CHIP_IDENT</constant>
2258	was introduced in its place. The old struct <structname>v4l2_chip_ident</structname>
2259	was renamed to <structname id="v4l2-chip-ident-old">v4l2_chip_ident_old</structname>.</para>
2260		</listitem>
2261		<listitem>
2262		  <para>The pixel formats
2263	<constant>V4L2_PIX_FMT_VYUY</constant>,
2264	<constant>V4L2_PIX_FMT_NV16</constant> and
2265	<constant>V4L2_PIX_FMT_NV61</constant> were added.</para>
2266		</listitem>
2267		<listitem>
2268		  <para>Added camera controls
2269	<constant>V4L2_CID_ZOOM_ABSOLUTE</constant>,
2270	<constant>V4L2_CID_ZOOM_RELATIVE</constant>,
2271	<constant>V4L2_CID_ZOOM_CONTINUOUS</constant> and
2272	<constant>V4L2_CID_PRIVACY</constant>.</para>
2273		</listitem>
2274	      </orderedlist>
2275	    </section>
2276	    <section>
2277	      <title>V4L2 in Linux 2.6.30</title>
2278	      <orderedlist>
2279		<listitem>
2280		  <para>New control flag <constant>V4L2_CTRL_FLAG_WRITE_ONLY</constant> was added.</para>
2281		</listitem>
2282		<listitem>
2283		  <para>New control <constant>V4L2_CID_COLORFX</constant> was added.</para>
2284		</listitem>
2285	      </orderedlist>
2286	    </section>
2287	    <section>
2288	      <title>V4L2 in Linux 2.6.32</title>
2289	      <orderedlist>
2290		<listitem>
2291		  <para>In order to be easier to compare a V4L2 API and a kernel
2292	version, now V4L2 API is numbered using the Linux Kernel version numeration.</para>
2293		</listitem>
2294		<listitem>
2295		  <para>Finalized the RDS capture API. See <xref linkend="rds" /> for
2296	more information.</para>
2297		</listitem>
2298		<listitem>
2299		  <para>Added new capabilities for modulators and RDS encoders.</para>
2300		</listitem>
2301		<listitem>
2302		  <para>Add description for libv4l API.</para>
2303		</listitem>
2304		<listitem>
2305		  <para>Added support for string controls via new type <constant>V4L2_CTRL_TYPE_STRING</constant>.</para>
2306		</listitem>
2307		<listitem>
2308		  <para>Added <constant>V4L2_CID_BAND_STOP_FILTER</constant> documentation.</para>
2309		</listitem>
2310		<listitem>
2311		  <para>Added FM Modulator (FM TX) Extended Control Class: <constant>V4L2_CTRL_CLASS_FM_TX</constant> and their Control IDs.</para>
2312		</listitem>
2313	<listitem>
2314		  <para>Added FM Receiver (FM RX) Extended Control Class: <constant>V4L2_CTRL_CLASS_FM_RX</constant> and their Control IDs.</para>
2315		</listitem>
2316		<listitem>
2317		  <para>Added Remote Controller chapter, describing the default Remote Controller mapping for media devices.</para>
2318		</listitem>
2319	      </orderedlist>
2320	    </section>
2321	    <section>
2322	      <title>V4L2 in Linux 2.6.33</title>
2323	      <orderedlist>
2324		<listitem>
2325		  <para>Added support for Digital Video timings in order to support HDTV receivers and transmitters.</para>
2326		</listitem>
2327	      </orderedlist>
2328	    </section>
2329	    <section>
2330	      <title>V4L2 in Linux 2.6.34</title>
2331	      <orderedlist>
2332		<listitem>
2333		  <para>Added
2334	<constant>V4L2_CID_IRIS_ABSOLUTE</constant> and
2335	<constant>V4L2_CID_IRIS_RELATIVE</constant> controls to the
2336		    <link linkend="camera-controls">Camera controls class</link>.
2337		  </para>
2338		</listitem>
2339	      </orderedlist>
2340	    </section>
2341	    <section>
2342	      <title>V4L2 in Linux 2.6.37</title>
2343	      <orderedlist>
2344		<listitem>
2345		  <para>Remove the vtx (videotext/teletext) API. This API was no longer
2346	used and no hardware exists to verify the API. Nor were any userspace applications found
2347	that used it. It was originally scheduled for removal in 2.6.35.
2348		  </para>
2349		</listitem>
2350	      </orderedlist>
2351	    </section>
2352	    <section>
2353	      <title>V4L2 in Linux 2.6.39</title>
2354	      <orderedlist>
2355	        <listitem>
2356	          <para>The old VIDIOC_*_OLD symbols and V4L1 support were removed.</para>
2357	        </listitem>
2358	        <listitem>
2359	          <para>Multi-planar API added. Does not affect the compatibility of
2360	          current drivers and applications. See
2361	          <link linkend="planar-apis">multi-planar API</link>
2362	          for details.</para>
2363	        </listitem>
2364	      </orderedlist>
2365	    </section>
2366	    <section>
2367	      <title>V4L2 in Linux 3.1</title>
2368	      <orderedlist>
2369	        <listitem>
2370		  <para>VIDIOC_QUERYCAP now returns a per-subsystem version instead of a per-driver one.</para>
2371		  <para>Standardize an error code for invalid ioctl.</para>
2372	          <para>Added V4L2_CTRL_TYPE_BITMASK.</para>
2373	        </listitem>
2374	      </orderedlist>
2375	    </section>
2376	    <section>
2377	      <title>V4L2 in Linux 3.2</title>
2378	      <orderedlist>
2379	        <listitem>
2380		  <para>V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to userspace.</para>
2381	        </listitem>
2382	        <listitem>
2383		  <para>Add selection API for extended control over cropping
2384		  and composing. Does not affect the compatibility of current
2385		  drivers and applications. See <link
2386		  linkend="selection-api"> selection API </link> for
2387		  details.</para>
2388	        </listitem>
2389	      </orderedlist>
2390	    </section>
2391	
2392	    <section>
2393	      <title>V4L2 in Linux 3.3</title>
2394	      <orderedlist>
2395	        <listitem>
2396		  <para>Added <constant>V4L2_CID_ALPHA_COMPONENT</constant> control
2397		    to the <link linkend="control">User controls class</link>.
2398		  </para>
2399	        </listitem>
2400	        <listitem>
2401		  <para>Added the device_caps field to struct v4l2_capabilities and added the new
2402		  V4L2_CAP_DEVICE_CAPS capability.</para>
2403	        </listitem>
2404	      </orderedlist>
2405	    </section>
2406	
2407	    <section>
2408	      <title>V4L2 in Linux 3.4</title>
2409	      <orderedlist>
2410	        <listitem>
2411		  <para>Added <link linkend="jpeg-controls">JPEG compression control
2412		  class</link>.</para>
2413	        </listitem>
2414	        <listitem>
2415		  <para>Extended the DV Timings API:
2416		  &VIDIOC-ENUM-DV-TIMINGS;, &VIDIOC-QUERY-DV-TIMINGS; and
2417		  &VIDIOC-DV-TIMINGS-CAP;.</para>
2418	        </listitem>
2419	      </orderedlist>
2420	    </section>
2421	
2422	    <section>
2423	      <title>V4L2 in Linux 3.5</title>
2424	      <orderedlist>
2425	        <listitem>
2426		  <para>Added integer menus, the new type will be
2427		  V4L2_CTRL_TYPE_INTEGER_MENU.</para>
2428	        </listitem>
2429	        <listitem>
2430		  <para>Added selection API for V4L2 subdev interface:
2431		  &VIDIOC-SUBDEV-G-SELECTION; and
2432		  &VIDIOC-SUBDEV-S-SELECTION;.</para>
2433	        </listitem>
2434	        <listitem>
2435		  <para> Added <constant>V4L2_COLORFX_ANTIQUE</constant>,
2436		  <constant>V4L2_COLORFX_ART_FREEZE</constant>,
2437		  <constant>V4L2_COLORFX_AQUA</constant>,
2438		  <constant>V4L2_COLORFX_SILHOUETTE</constant>,
2439		  <constant>V4L2_COLORFX_SOLARIZATION</constant>,
2440		  <constant>V4L2_COLORFX_VIVID</constant> and
2441		  <constant>V4L2_COLORFX_ARBITRARY_CBCR</constant> menu items
2442		  to the <constant>V4L2_CID_COLORFX</constant> control.</para>
2443	        </listitem>
2444	        <listitem>
2445		  <para> Added <constant>V4L2_CID_COLORFX_CBCR</constant> control.</para>
2446	        </listitem>
2447	        <listitem>
2448		  <para> Added camera controls <constant>V4L2_CID_AUTO_EXPOSURE_BIAS</constant>,
2449		  <constant>V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE</constant>,
2450		  <constant>V4L2_CID_IMAGE_STABILIZATION</constant>,
2451		  <constant>V4L2_CID_ISO_SENSITIVITY</constant>,
2452		  <constant>V4L2_CID_ISO_SENSITIVITY_AUTO</constant>,
2453		  <constant>V4L2_CID_EXPOSURE_METERING</constant>,
2454		  <constant>V4L2_CID_SCENE_MODE</constant>,
2455		  <constant>V4L2_CID_3A_LOCK</constant>,
2456		  <constant>V4L2_CID_AUTO_FOCUS_START</constant>,
2457		  <constant>V4L2_CID_AUTO_FOCUS_STOP</constant>,
2458		  <constant>V4L2_CID_AUTO_FOCUS_STATUS</constant> and
2459		  <constant>V4L2_CID_AUTO_FOCUS_RANGE</constant>.
2460		  </para>
2461	        </listitem>
2462	      </orderedlist>
2463	    </section>
2464	
2465	    <section>
2466	      <title>V4L2 in Linux 3.6</title>
2467	      <orderedlist>
2468		<listitem>
2469		  <para>Replaced <structfield>input</structfield> in
2470		  <structname>v4l2_buffer</structname> by
2471		  <structfield>reserved2</structfield> and removed
2472		  <constant>V4L2_BUF_FLAG_INPUT</constant>.</para>
2473		</listitem>
2474	        <listitem>
2475		  <para>Added V4L2_CAP_VIDEO_M2M and V4L2_CAP_VIDEO_M2M_MPLANE capabilities.</para>
2476	        </listitem>
2477	        <listitem>
2478		  <para>Added support for frequency band enumerations: &VIDIOC-ENUM-FREQ-BANDS;.</para>
2479	        </listitem>
2480	      </orderedlist>
2481	    </section>
2482	
2483	    <section>
2484	      <title>V4L2 in Linux 3.9</title>
2485	      <orderedlist>
2486	        <listitem>
2487		  <para>Added timestamp types to
2488		  <structfield>flags</structfield> field in
2489		  <structname>v4l2_buffer</structname>. See <xref
2490		  linkend="buffer-flags" />.</para>
2491	        </listitem>
2492	        <listitem>
2493		  <para>Added <constant>V4L2_EVENT_CTRL_CH_RANGE</constant> control event
2494		  changes flag. See <xref linkend="changes-flags"/>.</para>
2495	        </listitem>
2496	      </orderedlist>
2497	    </section>
2498	
2499	    <section>
2500	      <title>V4L2 in Linux 3.10</title>
2501	      <orderedlist>
2502	        <listitem>
2503		  <para>Removed obsolete and unused DV_PRESET ioctls
2504		  VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and
2505		  VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output capability
2506		  flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS.
2507		  </para>
2508	        </listitem>
2509	        <listitem>
2510		  <para>Added new debugging ioctl &VIDIOC-DBG-G-CHIP-INFO;.
2511		  </para>
2512	        </listitem>
2513	      </orderedlist>
2514	    </section>
2515	
2516	    <section>
2517	      <title>V4L2 in Linux 3.11</title>
2518	      <orderedlist>
2519	        <listitem>
2520		  <para>Remove obsolete <constant>VIDIOC_DBG_G_CHIP_IDENT</constant> ioctl.
2521		  </para>
2522	        </listitem>
2523	      </orderedlist>
2524	    </section>
2525	
2526	    <section>
2527	      <title>V4L2 in Linux 3.14</title>
2528	      <orderedlist>
2529	        <listitem>
2530			<para> In struct <structname>v4l2_rect</structname>, the type
2531	of <structfield>width</structfield> and <structfield>height</structfield>
2532	fields changed from _s32 to _u32.
2533		  </para>
2534	        </listitem>
2535	      </orderedlist>
2536	    </section>
2537	
2538	    <section>
2539	      <title>V4L2 in Linux 3.15</title>
2540	      <orderedlist>
2541	        <listitem>
2542		  <para>Added Software Defined Radio (SDR) Interface.
2543		  </para>
2544	        </listitem>
2545	      </orderedlist>
2546	    </section>
2547	
2548	    <section id="other">
2549	      <title>Relation of V4L2 to other Linux multimedia APIs</title>
2550	
2551	      <section id="xvideo">
2552	        <title>X Video Extension</title>
2553	
2554	        <para>The X Video Extension (abbreviated XVideo or just Xv) is
2555	an extension of the X Window system, implemented for example by the
2556	XFree86 project. Its scope is similar to V4L2, an API to video capture
2557	and output devices for X clients. Xv allows applications to display
2558	live video in a window, send window contents to a TV output, and
2559	capture or output still images in XPixmaps<footnote>
2560		  <para>This is not implemented in XFree86.</para>
2561		</footnote>. With their implementation XFree86 makes the
2562	extension available across many operating systems and
2563	architectures.</para>
2564	
2565	        <para>Because the driver is embedded into the X server Xv has a
2566	number of advantages over the V4L2 <link linkend="overlay">video
2567	overlay interface</link>. The driver can easily determine the overlay
2568	target, &ie; visible graphics memory or off-screen buffers for a
2569	destructive overlay. It can program the RAMDAC for a non-destructive
2570	overlay, scaling or color-keying, or the clipping functions of the
2571	video capture hardware, always in sync with drawing operations or
2572	windows moving or changing their stacking order.</para>
2573	
2574	        <para>To combine the advantages of Xv and V4L a special Xv
2575	driver exists in XFree86 and XOrg, just programming any overlay capable
2576	Video4Linux device it finds. To enable it
2577	<filename>/etc/X11/XF86Config</filename> must contain these lines:</para>
2578	        <para><screen>
2579	Section "Module"
2580	    Load "v4l"
2581	EndSection</screen></para>
2582	
2583	        <para>As of XFree86 4.2 this driver still supports only V4L
2584	ioctls, however it should work just fine with all V4L2 devices through
2585	the V4L2 backward-compatibility layer. Since V4L2 permits multiple
2586	opens it is possible (if supported by the V4L2 driver) to capture
2587	video while an X client requested video overlay. Restrictions of
2588	simultaneous capturing and overlay are discussed in <xref
2589		  linkend="overlay" /> apply.</para>
2590	
2591	        <para>Only marginally related to V4L2, XFree86 extended Xv to
2592	support hardware YUV to RGB conversion and scaling for faster video
2593	playback, and added an interface to MPEG-2 decoding hardware. This API
2594	is useful to display images captured with V4L2 devices.</para>
2595	      </section>
2596	
2597	      <section>
2598	        <title>Digital Video</title>
2599	
2600	        <para>V4L2 does not support digital terrestrial, cable or
2601	satellite broadcast. A separate project aiming at digital receivers
2602	exists. You can find its homepage at <ulink
2603	url="http://linuxtv.org">http://linuxtv.org</ulink>. The Linux DVB API
2604	has no connection to the V4L2 API except that drivers for hybrid
2605	hardware may support both.</para>
2606	      </section>
2607	
2608	      <section>
2609	        <title>Audio Interfaces</title>
2610	
2611	        <para>[to do - OSS/ALSA]</para>
2612	      </section>
2613	    </section>
2614	
2615	    <section id="experimental">
2616	      <title>Experimental API Elements</title>
2617	
2618	      <para>The following V4L2 API elements are currently experimental
2619	and may change in the future.</para>
2620	
2621	      <itemizedlist>
2622	        <listitem>
2623		  <para>Video Output Overlay (OSD) Interface, <xref
2624		    linkend="osd" />.</para>
2625	        </listitem>
2626	        <listitem>
2627		  <para>&VIDIOC-DBG-G-REGISTER; and &VIDIOC-DBG-S-REGISTER;
2628	ioctls.</para>
2629	        </listitem>
2630	        <listitem>
2631		  <para>&VIDIOC-DBG-G-CHIP-INFO; ioctl.</para>
2632	        </listitem>
2633	        <listitem>
2634		  <para>&VIDIOC-ENUM-DV-TIMINGS;, &VIDIOC-QUERY-DV-TIMINGS; and
2635		  &VIDIOC-DV-TIMINGS-CAP; ioctls.</para>
2636	        </listitem>
2637	        <listitem>
2638		  <para>Flash API. <xref linkend="flash-controls" /></para>
2639	        </listitem>
2640	        <listitem>
2641		  <para>&VIDIOC-CREATE-BUFS; and &VIDIOC-PREPARE-BUF; ioctls.</para>
2642	        </listitem>
2643	        <listitem>
2644		  <para>Selection API. <xref linkend="selection-api" /></para>
2645	        </listitem>
2646	        <listitem>
2647		  <para>Sub-device selection API: &VIDIOC-SUBDEV-G-SELECTION;
2648		  and &VIDIOC-SUBDEV-S-SELECTION; ioctls.</para>
2649	        </listitem>
2650	        <listitem>
2651		  <para>Support for frequency band enumeration: &VIDIOC-ENUM-FREQ-BANDS; ioctl.</para>
2652	        </listitem>
2653	        <listitem>
2654		  <para>Vendor and device specific media bus pixel formats.
2655		    <xref linkend="v4l2-mbus-vendor-spec-fmts" />.</para>
2656	        </listitem>
2657	        <listitem>
2658		  <para>Importing DMABUF file descriptors as a new IO method described
2659		  in <xref linkend="dmabuf" />.</para>
2660	        </listitem>
2661	        <listitem>
2662		  <para>Exporting DMABUF files using &VIDIOC-EXPBUF; ioctl.</para>
2663	        </listitem>
2664	        <listitem>
2665		  <para>Software Defined Radio (SDR) Interface, <xref linkend="sdr" />.</para>
2666	        </listitem>
2667	      </itemizedlist>
2668	    </section>
2669	
2670	    <section id="obsolete">
2671	      <title>Obsolete API Elements</title>
2672	
2673	      <para>The following V4L2 API elements were superseded by new
2674	interfaces and should not be implemented in new drivers.</para>
2675	
2676	      <itemizedlist>
2677	        <listitem>
2678		  <para><constant>VIDIOC_G_MPEGCOMP</constant> and
2679	<constant>VIDIOC_S_MPEGCOMP</constant> ioctls. Use Extended Controls,
2680	<xref linkend="extended-controls" />.</para>
2681	        </listitem>
2682	        <listitem>
2683		  <para>VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET, VIDIOC_ENUM_DV_PRESETS and
2684		  VIDIOC_QUERY_DV_PRESET ioctls. Use the DV Timings API (<xref linkend="dv-timings" />).</para>
2685	        </listitem>
2686	        <listitem>
2687		  <para><constant>VIDIOC_SUBDEV_G_CROP</constant> and
2688		  <constant>VIDIOC_SUBDEV_S_CROP</constant> ioctls. Use
2689		  <constant>VIDIOC_SUBDEV_G_SELECTION</constant> and
2690		  <constant>VIDIOC_SUBDEV_S_SELECTION</constant>, <xref
2691		  linkend="vidioc-subdev-g-selection" />.</para>
2692	        </listitem>
2693	      </itemizedlist>
2694	    </section>
2695	  </section>
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.