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