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