Based on kernel version 3.9. Page generated on 2013-05-02 23:04 EST.
1 <partinfo> 2 <authorgroup> 3 <author> 4 <firstname>Michael</firstname> 5 <surname>Schimek</surname> 6 <othername role="mi">H</othername> 7 <affiliation> 8 <address> 9 <email>mschimek@gmx.at</email> 10 </address> 11 </affiliation> 12 </author> 13 14 <author> 15 <firstname>Bill</firstname> 16 <surname>Dirks</surname> 17 <!-- Commented until Bill opts in to be spammed. 18 <affiliation> 19 <address> 20 <email>bill@thedirks.org</email> 21 </address> 22 </affiliation> --> 23 <contrib>Original author of the V4L2 API and 24 documentation.</contrib> 25 </author> 26 27 <author> 28 <firstname>Hans</firstname> 29 <surname>Verkuil</surname> 30 <contrib>Designed and documented the VIDIOC_LOG_STATUS ioctl, 31 the extended control ioctls, major parts of the sliced VBI API, the 32 MPEG encoder and decoder APIs and the DV Timings API.</contrib> 33 <affiliation> 34 <address> 35 <email>hverkuil@xs4all.nl</email> 36 </address> 37 </affiliation> 38 </author> 39 40 <author> 41 <firstname>Martin</firstname> 42 <surname>Rubli</surname> 43 <!-- 44 <affiliation> 45 <address> 46 <email>martin_rubli@logitech.com</email> 47 </address> 48 </affiliation> --> 49 <contrib>Designed and documented the VIDIOC_ENUM_FRAMESIZES 50 and VIDIOC_ENUM_FRAMEINTERVALS ioctls.</contrib> 51 </author> 52 53 <author> 54 <firstname>Andy</firstname> 55 <surname>Walls</surname> 56 <contrib>Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV 57 MPEG stream embedded, sliced VBI data format in this specification. 58 </contrib> 59 <affiliation> 60 <address> 61 <email>awalls@md.metrocast.net</email> 62 </address> 63 </affiliation> 64 </author> 65 66 <author> 67 <firstname>Mauro</firstname> 68 <surname>Carvalho Chehab</surname> 69 <contrib>Documented libv4l, designed and added v4l2grab example, 70 Remote Controller chapter.</contrib> 71 <affiliation> 72 <address> 73 <email>mchehab@redhat.com</email> 74 </address> 75 </affiliation> 76 </author> 77 78 <author> 79 <firstname>Muralidharan</firstname> 80 <surname>Karicheri</surname> 81 <contrib>Documented the Digital Video timings API.</contrib> 82 <affiliation> 83 <address> 84 <email>m-karicheri2@ti.com</email> 85 </address> 86 </affiliation> 87 </author> 88 89 <author> 90 <firstname>Pawel</firstname> 91 <surname>Osciak</surname> 92 <contrib>Designed and documented the multi-planar API.</contrib> 93 <affiliation> 94 <address> 95 <email>pawel AT osciak.com</email> 96 </address> 97 </affiliation> 98 </author> 99 100 <author> 101 <firstname>Sakari</firstname> 102 <surname>Ailus</surname> 103 <contrib>Subdev selections API.</contrib> 104 <affiliation> 105 <address> 106 <email>sakari.ailus@iki.fi</email> 107 </address> 108 </affiliation> 109 </author> 110 </authorgroup> 111 112 <copyright> 113 <year>1999</year> 114 <year>2000</year> 115 <year>2001</year> 116 <year>2002</year> 117 <year>2003</year> 118 <year>2004</year> 119 <year>2005</year> 120 <year>2006</year> 121 <year>2007</year> 122 <year>2008</year> 123 <year>2009</year> 124 <year>2010</year> 125 <year>2011</year> 126 <year>2012</year> 127 <holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin 128 Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, 129 Pawel Osciak</holder> 130 </copyright> 131 <legalnotice> 132 <para>Except when explicitly stated as GPL, programming examples within 133 this part can be used and distributed without restrictions.</para> 134 </legalnotice> 135 <revhistory> 136 <!-- Put document revisions here, newest first. --> 137 <!-- API revisions (changes and additions of defines, enums, 138 structs, ioctls) must be noted in more detail in the history chapter 139 (compat.xml), along with the possible impact on existing drivers and 140 applications. --> 141 142 <revision> 143 <revnumber>3.9</revnumber> 144 <date>2012-12-03</date> 145 <authorinitials>sa, sn</authorinitials> 146 <revremark>Added timestamp types to v4l2_buffer. 147 Added <constant>V4L2_EVENT_CTRL_CH_RANGE</constant> control 148 event changes flag, see <xref linkend="changes-flags"/>. 149 </revremark> 150 </revision> 151 152 <revision> 153 <revnumber>3.6</revnumber> 154 <date>2012-07-02</date> 155 <authorinitials>hv</authorinitials> 156 <revremark>Added VIDIOC_ENUM_FREQ_BANDS. 157 </revremark> 158 </revision> 159 160 <revision> 161 <revnumber>3.5</revnumber> 162 <date>2012-05-07</date> 163 <authorinitials>sa, sn, hv</authorinitials> 164 <revremark>Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev 165 selections API. Improved the description of V4L2_CID_COLORFX 166 control, added V4L2_CID_COLORFX_CBCR control. 167 Added camera controls V4L2_CID_AUTO_EXPOSURE_BIAS, 168 V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE, V4L2_CID_IMAGE_STABILIZATION, 169 V4L2_CID_ISO_SENSITIVITY, V4L2_CID_ISO_SENSITIVITY_AUTO, 170 V4L2_CID_EXPOSURE_METERING, V4L2_CID_SCENE_MODE, 171 V4L2_CID_3A_LOCK, V4L2_CID_AUTO_FOCUS_START, 172 V4L2_CID_AUTO_FOCUS_STOP, V4L2_CID_AUTO_FOCUS_STATUS 173 and V4L2_CID_AUTO_FOCUS_RANGE. 174 Added VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and 175 VIDIOC_DV_TIMINGS_CAP. 176 </revremark> 177 </revision> 178 179 <revision> 180 <revnumber>3.4</revnumber> 181 <date>2012-01-25</date> 182 <authorinitials>sn</authorinitials> 183 <revremark>Added <link linkend="jpeg-controls">JPEG compression 184 control class.</link> 185 </revremark> 186 </revision> 187 188 <revision> 189 <revnumber>3.3</revnumber> 190 <date>2012-01-11</date> 191 <authorinitials>hv</authorinitials> 192 <revremark>Added device_caps field to struct v4l2_capabilities.</revremark> 193 </revision> 194 195 <revision> 196 <revnumber>3.2</revnumber> 197 <date>2011-08-26</date> 198 <authorinitials>hv</authorinitials> 199 <revremark>Added V4L2_CTRL_FLAG_VOLATILE.</revremark> 200 </revision> 201 202 <revision> 203 <revnumber>3.1</revnumber> 204 <date>2011-06-27</date> 205 <authorinitials>mcc, po, hv</authorinitials> 206 <revremark>Documented that VIDIOC_QUERYCAP now returns a per-subsystem version instead of a per-driver one. 207 Standardize an error code for invalid ioctl. 208 Added V4L2_CTRL_TYPE_BITMASK.</revremark> 209 </revision> 210 211 <revision> 212 <revnumber>2.6.39</revnumber> 213 <date>2011-03-01</date> 214 <authorinitials>mcc, po</authorinitials> 215 <revremark>Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect latest changes. Added the <link linkend="planar-apis">multi-planar API</link>.</revremark> 216 </revision> 217 218 <revision> 219 <revnumber>2.6.37</revnumber> 220 <date>2010-08-06</date> 221 <authorinitials>hv</authorinitials> 222 <revremark>Removed obsolete vtx (videotext) API.</revremark> 223 </revision> 224 225 <revision> 226 <revnumber>2.6.33</revnumber> 227 <date>2009-12-03</date> 228 <authorinitials>mk</authorinitials> 229 <revremark>Added documentation for the Digital Video timings API.</revremark> 230 </revision> 231 232 <revision> 233 <revnumber>2.6.32</revnumber> 234 <date>2009-08-31</date> 235 <authorinitials>mcc</authorinitials> 236 <revremark>Now, revisions will match the kernel version where 237 the V4L2 API changes will be used by the Linux Kernel. 238 Also added Remote Controller chapter.</revremark> 239 </revision> 240 241 <revision> 242 <revnumber>0.29</revnumber> 243 <date>2009-08-26</date> 244 <authorinitials>ev</authorinitials> 245 <revremark>Added documentation for string controls and for FM Transmitter controls.</revremark> 246 </revision> 247 248 <revision> 249 <revnumber>0.28</revnumber> 250 <date>2009-08-26</date> 251 <authorinitials>gl</authorinitials> 252 <revremark>Added V4L2_CID_BAND_STOP_FILTER documentation.</revremark> 253 </revision> 254 255 <revision> 256 <revnumber>0.27</revnumber> 257 <date>2009-08-15</date> 258 <authorinitials>mcc</authorinitials> 259 <revremark>Added libv4l and Remote Controller documentation; 260 added v4l2grab and keytable application examples.</revremark> 261 </revision> 262 263 <revision> 264 <revnumber>0.26</revnumber> 265 <date>2009-07-23</date> 266 <authorinitials>hv</authorinitials> 267 <revremark>Finalized the RDS capture API. Added modulator and RDS encoder 268 capabilities. Added support for string controls.</revremark> 269 </revision> 270 271 <revision> 272 <revnumber>0.25</revnumber> 273 <date>2009-01-18</date> 274 <authorinitials>hv</authorinitials> 275 <revremark>Added pixel formats VYUY, NV16 and NV61, and changed 276 the debug ioctls VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT. 277 Added camera controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE, 278 V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY.</revremark> 279 </revision> 280 281 <revision> 282 <revnumber>0.24</revnumber> 283 <date>2008-03-04</date> 284 <authorinitials>mhs</authorinitials> 285 <revremark>Added pixel formats Y16 and SBGGR16, new controls 286 and a camera controls class. Removed VIDIOC_G/S_MPEGCOMP.</revremark> 287 </revision> 288 289 <revision> 290 <revnumber>0.23</revnumber> 291 <date>2007-08-30</date> 292 <authorinitials>mhs</authorinitials> 293 <revremark>Fixed a typo in VIDIOC_DBG_G/S_REGISTER. 294 Clarified the byte order of packed pixel formats.</revremark> 295 </revision> 296 297 <revision> 298 <revnumber>0.22</revnumber> 299 <date>2007-08-29</date> 300 <authorinitials>mhs</authorinitials> 301 <revremark>Added the Video Output Overlay interface, new MPEG 302 controls, V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT, 303 VIDIOC_DBG_G/S_REGISTER, VIDIOC_(TRY_)ENCODER_CMD, 304 VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats. 305 Clarifications in the cropping chapter, about RGB pixel formats, the 306 mmap(), poll(), select(), read() and write() functions. Typographical 307 fixes.</revremark> 308 </revision> 309 310 <revision> 311 <revnumber>0.21</revnumber> 312 <date>2006-12-19</date> 313 <authorinitials>mhs</authorinitials> 314 <revremark>Fixed a link in the VIDIOC_G_EXT_CTRLS section.</revremark> 315 </revision> 316 317 <revision> 318 <revnumber>0.20</revnumber> 319 <date>2006-11-24</date> 320 <authorinitials>mhs</authorinitials> 321 <revremark>Clarified the purpose of the audioset field in 322 struct v4l2_input and v4l2_output.</revremark> 323 </revision> 324 325 <revision> 326 <revnumber>0.19</revnumber> 327 <date>2006-10-19</date> 328 <authorinitials>mhs</authorinitials> 329 <revremark>Documented V4L2_PIX_FMT_RGB444.</revremark> 330 </revision> 331 332 <revision> 333 <revnumber>0.18</revnumber> 334 <date>2006-10-18</date> 335 <authorinitials>mhs</authorinitials> 336 <revremark>Added the description of extended controls by Hans 337 Verkuil. Linked V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.</revremark> 338 </revision> 339 340 <revision> 341 <revnumber>0.17</revnumber> 342 <date>2006-10-12</date> 343 <authorinitials>mhs</authorinitials> 344 <revremark>Corrected V4L2_PIX_FMT_HM12 description.</revremark> 345 </revision> 346 347 <revision> 348 <revnumber>0.16</revnumber> 349 <date>2006-10-08</date> 350 <authorinitials>mhs</authorinitials> 351 <revremark>VIDIOC_ENUM_FRAMESIZES and 352 VIDIOC_ENUM_FRAMEINTERVALS are now part of the API.</revremark> 353 </revision> 354 355 <revision> 356 <revnumber>0.15</revnumber> 357 <date>2006-09-23</date> 358 <authorinitials>mhs</authorinitials> 359 <revremark>Cleaned up the bibliography, added BT.653 and 360 BT.1119. capture.c/start_capturing() for user pointer I/O did not 361 initialize the buffer index. Documented the V4L MPEG and MJPEG 362 VID_TYPEs and V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel 363 formats. See the history chapter for API changes.</revremark> 364 </revision> 365 366 <revision> 367 <revnumber>0.14</revnumber> 368 <date>2006-09-14</date> 369 <authorinitials>mr</authorinitials> 370 <revremark>Added VIDIOC_ENUM_FRAMESIZES and 371 VIDIOC_ENUM_FRAMEINTERVALS proposal for frame format enumeration of 372 digital devices.</revremark> 373 </revision> 374 375 <revision> 376 <revnumber>0.13</revnumber> 377 <date>2006-04-07</date> 378 <authorinitials>mhs</authorinitials> 379 <revremark>Corrected the description of struct v4l2_window 380 clips. New V4L2_STD_ and V4L2_TUNER_MODE_LANG1_LANG2 381 defines.</revremark> 382 </revision> 383 384 <revision> 385 <revnumber>0.12</revnumber> 386 <date>2006-02-03</date> 387 <authorinitials>mhs</authorinitials> 388 <revremark>Corrected the description of struct 389 v4l2_captureparm and v4l2_outputparm.</revremark> 390 </revision> 391 392 <revision> 393 <revnumber>0.11</revnumber> 394 <date>2006-01-27</date> 395 <authorinitials>mhs</authorinitials> 396 <revremark>Improved the description of struct 397 v4l2_tuner.</revremark> 398 </revision> 399 400 <revision> 401 <revnumber>0.10</revnumber> 402 <date>2006-01-10</date> 403 <authorinitials>mhs</authorinitials> 404 <revremark>VIDIOC_G_INPUT and VIDIOC_S_PARM 405 clarifications.</revremark> 406 </revision> 407 408 <revision> 409 <revnumber>0.9</revnumber> 410 <date>2005-11-27</date> 411 <authorinitials>mhs</authorinitials> 412 <revremark>Improved the 525 line numbering diagram. Hans 413 Verkuil and I rewrote the sliced VBI section. He also contributed a 414 VIDIOC_LOG_STATUS page. Fixed VIDIOC_S_STD call in the video standard 415 selection example. Various updates.</revremark> 416 </revision> 417 418 <revision> 419 <revnumber>0.8</revnumber> 420 <date>2004-10-04</date> 421 <authorinitials>mhs</authorinitials> 422 <revremark>Somehow a piece of junk slipped into the capture 423 example, removed.</revremark> 424 </revision> 425 426 <revision> 427 <revnumber>0.7</revnumber> 428 <date>2004-09-19</date> 429 <authorinitials>mhs</authorinitials> 430 <revremark>Fixed video standard selection, control 431 enumeration, downscaling and aspect example. Added read and user 432 pointer i/o to video capture example.</revremark> 433 </revision> 434 435 <revision> 436 <revnumber>0.6</revnumber> 437 <date>2004-08-01</date> 438 <authorinitials>mhs</authorinitials> 439 <revremark>v4l2_buffer changes, added video capture example, 440 various corrections.</revremark> 441 </revision> 442 443 <revision> 444 <revnumber>0.5</revnumber> 445 <date>2003-11-05</date> 446 <authorinitials>mhs</authorinitials> 447 <revremark>Pixel format erratum.</revremark> 448 </revision> 449 450 <revision> 451 <revnumber>0.4</revnumber> 452 <date>2003-09-17</date> 453 <authorinitials>mhs</authorinitials> 454 <revremark>Corrected source and Makefile to generate a PDF. 455 SGML fixes. Added latest API changes. Closed gaps in the history 456 chapter.</revremark> 457 </revision> 458 459 <revision> 460 <revnumber>0.3</revnumber> 461 <date>2003-02-05</date> 462 <authorinitials>mhs</authorinitials> 463 <revremark>Another draft, more corrections.</revremark> 464 </revision> 465 466 <revision> 467 <revnumber>0.2</revnumber> 468 <date>2003-01-15</date> 469 <authorinitials>mhs</authorinitials> 470 <revremark>Second draft, with corrections pointed out by Gerd 471 Knorr.</revremark> 472 </revision> 473 474 <revision> 475 <revnumber>0.1</revnumber> 476 <date>2002-12-01</date> 477 <authorinitials>mhs</authorinitials> 478 <revremark>First draft, based on documentation by Bill Dirks 479 and discussions on the V4L mailing list.</revremark> 480 </revision> 481 </revhistory> 482 </partinfo> 483 484 <title>Video for Linux Two API Specification</title> 485 <subtitle>Revision 3.9</subtitle> 486 487 <chapter id="common"> 488 &sub-common; 489 </chapter> 490 491 <chapter id="pixfmt"> 492 &sub-pixfmt; 493 </chapter> 494 495 <chapter id="io"> 496 &sub-io; 497 </chapter> 498 499 <chapter id="devices"> 500 <title>Interfaces</title> 501 502 <section id="capture"> &sub-dev-capture; </section> 503 <section id="overlay"> &sub-dev-overlay; </section> 504 <section id="output"> &sub-dev-output; </section> 505 <section id="osd"> &sub-dev-osd; </section> 506 <section id="codec"> &sub-dev-codec; </section> 507 <section id="effect"> &sub-dev-effect; </section> 508 <section id="raw-vbi"> &sub-dev-raw-vbi; </section> 509 <section id="sliced"> &sub-dev-sliced-vbi; </section> 510 <section id="ttx"> &sub-dev-teletext; </section> 511 <section id="radio"> &sub-dev-radio; </section> 512 <section id="rds"> &sub-dev-rds; </section> 513 <section id="event"> &sub-dev-event; </section> 514 <section id="subdev"> &sub-dev-subdev; </section> 515 </chapter> 516 517 <chapter id="driver"> 518 &sub-driver; 519 </chapter> 520 521 <chapter id="libv4l"> 522 &sub-libv4l; 523 </chapter> 524 525 <chapter id="compat"> 526 &sub-compat; 527 </chapter> 528 529 <appendix id="user-func"> 530 <title>Function Reference</title> 531 532 <!-- Keep this alphabetically sorted. --> 533 534 &sub-close; 535 &sub-ioctl; 536 <!-- All ioctls go here. --> 537 &sub-create-bufs; 538 &sub-cropcap; 539 &sub-dbg-g-chip-ident; 540 &sub-dbg-g-register; 541 &sub-decoder-cmd; 542 &sub-dqevent; 543 &sub-dv-timings-cap; 544 &sub-encoder-cmd; 545 &sub-enumaudio; 546 &sub-enumaudioout; 547 &sub-enum-dv-presets; 548 &sub-enum-dv-timings; 549 &sub-enum-fmt; 550 &sub-enum-framesizes; 551 &sub-enum-frameintervals; 552 &sub-enum-freq-bands; 553 &sub-enuminput; 554 &sub-enumoutput; 555 &sub-enumstd; 556 &sub-expbuf; 557 &sub-g-audio; 558 &sub-g-audioout; 559 &sub-g-crop; 560 &sub-g-ctrl; 561 &sub-g-dv-preset; 562 &sub-g-dv-timings; 563 &sub-g-enc-index; 564 &sub-g-ext-ctrls; 565 &sub-g-fbuf; 566 &sub-g-fmt; 567 &sub-g-frequency; 568 &sub-g-input; 569 &sub-g-jpegcomp; 570 &sub-g-modulator; 571 &sub-g-output; 572 &sub-g-parm; 573 &sub-g-priority; 574 &sub-g-selection; 575 &sub-g-sliced-vbi-cap; 576 &sub-g-std; 577 &sub-g-tuner; 578 &sub-log-status; 579 &sub-overlay; 580 &sub-prepare-buf; 581 &sub-qbuf; 582 &sub-querybuf; 583 &sub-querycap; 584 &sub-queryctrl; 585 &sub-query-dv-preset; 586 &sub-query-dv-timings; 587 &sub-querystd; 588 &sub-reqbufs; 589 &sub-s-hw-freq-seek; 590 &sub-streamon; 591 &sub-subdev-enum-frame-interval; 592 &sub-subdev-enum-frame-size; 593 &sub-subdev-enum-mbus-code; 594 &sub-subdev-g-crop; 595 &sub-subdev-g-edid; 596 &sub-subdev-g-fmt; 597 &sub-subdev-g-frame-interval; 598 &sub-subdev-g-selection; 599 &sub-subscribe-event; 600 <!-- End of ioctls. --> 601 &sub-mmap; 602 &sub-munmap; 603 &sub-open; 604 &sub-poll; 605 &sub-read; 606 &sub-select; 607 &sub-write; 608 </appendix> 609 610 <appendix> 611 <title>Common definitions for V4L2 and V4L2 subdev interfaces</title> 612 &sub-selections-common; 613 </appendix> 614 615 <appendix id="videodev"> 616 <title>Video For Linux Two Header File</title> 617 &sub-videodev2-h; 618 </appendix> 619 620 <appendix id="capture-example"> 621 <title>Video Capture Example</title> 622 &sub-capture-c; 623 </appendix> 624 625 <appendix id="v4l2grab-example"> 626 <title>Video Grabber example using libv4l</title> 627 <para>This program demonstrates how to grab V4L2 images in ppm format by 628 using libv4l handlers. The advantage is that this grabber can potentially work 629 with any V4L2 driver.</para> 630 &sub-v4l2grab-c; 631 </appendix> 632 633 &sub-media-indices; 634 635 &sub-biblio;