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