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