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