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