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