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