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