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