Based on kernel version 4.7.2. Page generated on 2016-08-22 22:44 EST.
1 <title>Common API Elements</title> 2 3 <para>Programming a V4L2 device consists of these 4 steps:</para> 5 6 <itemizedlist> 7 <listitem> 8 <para>Opening the device</para> 9 </listitem> 10 <listitem> 11 <para>Changing device properties, selecting a video and audio 12 input, video standard, picture brightness a. o.</para> 13 </listitem> 14 <listitem> 15 <para>Negotiating a data format</para> 16 </listitem> 17 <listitem> 18 <para>Negotiating an input/output method</para> 19 </listitem> 20 <listitem> 21 <para>The actual input/output loop</para> 22 </listitem> 23 <listitem> 24 <para>Closing the device</para> 25 </listitem> 26 </itemizedlist> 27 28 <para>In practice most steps are optional and can be executed out of 29 order. It depends on the V4L2 device type, you can read about the 30 details in <xref linkend="devices" />. In this chapter we will discuss 31 the basic concepts applicable to all devices.</para> 32 33 <section id="open"> 34 <title>Opening and Closing Devices</title> 35 36 <section> 37 <title>Device Naming</title> 38 39 <para>V4L2 drivers are implemented as kernel modules, loaded 40 manually by the system administrator or automatically when a device is 41 first discovered. The driver modules plug into the "videodev" kernel 42 module. It provides helper functions and a common application 43 interface specified in this document.</para> 44 45 <para>Each driver thus loaded registers one or more device nodes 46 with major number 81 and a minor number between 0 and 255. Minor numbers 47 are allocated dynamically unless the kernel is compiled with the kernel 48 option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers are 49 allocated in ranges depending on the device node type (video, radio, etc.).</para> 50 51 <para>Many drivers support "video_nr", "radio_nr" or "vbi_nr" 52 module options to select specific video/radio/vbi node numbers. This allows 53 the user to request that the device node is named e.g. /dev/video5 instead 54 of leaving it to chance. When the driver supports multiple devices of the same 55 type more than one device node number can be assigned, separated by commas: 56 <informalexample> 57 <screen> 58 > modprobe mydriver video_nr=0,1 radio_nr=0,1</screen> 59 </informalexample></para> 60 61 <para>In <filename>/etc/modules.conf</filename> this may be 62 written as: <informalexample> 63 <screen> 64 options mydriver video_nr=0,1 radio_nr=0,1 65 </screen> 66 </informalexample> When no device node number is given as module 67 option the driver supplies a default.</para> 68 69 <para>Normally udev will create the device nodes in /dev automatically 70 for you. If udev is not installed, then you need to enable the 71 CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to correctly 72 relate a minor number to a device node number. I.e., you need to be certain 73 that minor number 5 maps to device node name video5. With this kernel option 74 different device types have different minor number ranges. These ranges are 75 listed in <xref linkend="devices" />. 76 </para> 77 78 <para>The creation of character special files (with 79 <application>mknod</application>) is a privileged operation and 80 devices cannot be opened by major and minor number. That means 81 applications cannot <emphasis>reliable</emphasis> scan for loaded or 82 installed drivers. The user must enter a device name, or the 83 application can try the conventional device names.</para> 84 </section> 85 86 <section id="related"> 87 <title>Related Devices</title> 88 89 <para>Devices can support several functions. For example 90 video capturing, VBI capturing and radio support.</para> 91 92 <para>The V4L2 API creates different nodes for each of these functions.</para> 93 94 <para>The V4L2 API was designed with the idea that one device node could support 95 all functions. However, in practice this never worked: this 'feature' 96 was never used by applications and many drivers did not support it and if 97 they did it was certainly never tested. In addition, switching a device 98 node between different functions only works when using the streaming I/O 99 API, not with the read()/write() API.</para> 100 101 <para>Today each device node supports just one function.</para> 102 103 <para>Besides video input or output the hardware may also 104 support audio sampling or playback. If so, these functions are 105 implemented as ALSA PCM devices with optional ALSA audio mixer 106 devices.</para> 107 108 <para>One problem with all these devices is that the V4L2 API 109 makes no provisions to find these related devices. Some really 110 complex devices use the Media Controller (see <xref linkend="media_controller" />) 111 which can be used for this purpose. But most drivers do not use it, 112 and while some code exists that uses sysfs to discover related devices 113 (see libmedia_dev in the <ulink url="http://git.linuxtv.org/cgit.cgi/v4l-utils.git/">v4l-utils</ulink> 114 git repository), there is no library yet that can provide a single API towards 115 both Media Controller-based devices and devices that do not use the Media Controller. 116 If you want to work on this please write to the linux-media mailing list: &v4l-ml;.</para> 117 </section> 118 119 <section> 120 <title>Multiple Opens</title> 121 122 <para>V4L2 devices can be opened more than once.<footnote><para> 123 There are still some old and obscure drivers that have not been updated to 124 allow for multiple opens. This implies that for such drivers &func-open; can 125 return an &EBUSY; when the device is already in use.</para></footnote> 126 When this is supported by the driver, users can for example start a 127 "panel" application to change controls like brightness or audio 128 volume, while another application captures video and audio. In other words, panel 129 applications are comparable to an ALSA audio mixer application. 130 Just opening a V4L2 device should not change the state of the device.<footnote> 131 <para>Unfortunately, opening a radio device often switches the state of the 132 device to radio mode in many drivers. This behavior should be fixed eventually 133 as it violates the V4L2 specification.</para></footnote></para> 134 135 <para>Once an application has allocated the memory buffers needed for 136 streaming data (by calling the &VIDIOC-REQBUFS; or &VIDIOC-CREATE-BUFS; ioctls, 137 or implicitly by calling the &func-read; or &func-write; functions) that 138 application (filehandle) becomes the owner of the device. It is no longer 139 allowed to make changes that would affect the buffer sizes (e.g. by calling 140 the &VIDIOC-S-FMT; ioctl) and other applications are no longer allowed to allocate 141 buffers or start or stop streaming. The &EBUSY; will be returned instead.</para> 142 143 <para>Merely opening a V4L2 device does not grant exclusive 144 access.<footnote> 145 <para>Drivers could recognize the 146 <constant>O_EXCL</constant> open flag. Presently this is not required, 147 so applications cannot know if it really works.</para> 148 </footnote> Initiating data exchange however assigns the right 149 to read or write the requested type of data, and to change related 150 properties, to this file descriptor. Applications can request 151 additional access privileges using the priority mechanism described in 152 <xref linkend="app-pri" />.</para> 153 </section> 154 155 <section> 156 <title>Shared Data Streams</title> 157 158 <para>V4L2 drivers should not support multiple applications 159 reading or writing the same data stream on a device by copying 160 buffers, time multiplexing or similar means. This is better handled by 161 a proxy application in user space.</para> 162 </section> 163 164 <section> 165 <title>Functions</title> 166 167 <para>To open and close V4L2 devices applications use the 168 &func-open; and &func-close; function, respectively. Devices are 169 programmed using the &func-ioctl; function as explained in the 170 following sections.</para> 171 </section> 172 </section> 173 174 <section id="querycap"> 175 <title>Querying Capabilities</title> 176 177 <para>Because V4L2 covers a wide variety of devices not all 178 aspects of the API are equally applicable to all types of devices. 179 Furthermore devices of the same type have different capabilities and 180 this specification permits the omission of a few complicated and less 181 important parts of the API.</para> 182 183 <para>The &VIDIOC-QUERYCAP; ioctl is available to check if the kernel 184 device is compatible with this specification, and to query the <link 185 linkend="devices">functions</link> and <link linkend="io">I/O 186 methods</link> supported by the device.</para> 187 188 <para>Starting with kernel version 3.1, VIDIOC-QUERYCAP will return the 189 V4L2 API version used by the driver, with generally matches the Kernel version. 190 There's no need of using &VIDIOC-QUERYCAP; to check if a specific ioctl is 191 supported, the V4L2 core now returns ENOTTY if a driver doesn't provide 192 support for an ioctl.</para> 193 194 <para>Other features can be queried 195 by calling the respective ioctl, for example &VIDIOC-ENUMINPUT; 196 to learn about the number, types and names of video connectors on the 197 device. Although abstraction is a major objective of this API, the 198 &VIDIOC-QUERYCAP; ioctl also allows driver specific applications to reliably identify 199 the driver.</para> 200 201 <para>All V4L2 drivers must support 202 <constant>VIDIOC_QUERYCAP</constant>. Applications should always call 203 this ioctl after opening the device.</para> 204 </section> 205 206 <section id="app-pri"> 207 <title>Application Priority</title> 208 209 <para>When multiple applications share a device it may be 210 desirable to assign them different priorities. Contrary to the 211 traditional "rm -rf /" school of thought a video recording application 212 could for example block other applications from changing video 213 controls or switching the current TV channel. Another objective is to 214 permit low priority applications working in background, which can be 215 preempted by user controlled applications and automatically regain 216 control of the device at a later time.</para> 217 218 <para>Since these features cannot be implemented entirely in user 219 space V4L2 defines the &VIDIOC-G-PRIORITY; and &VIDIOC-S-PRIORITY; 220 ioctls to request and query the access priority associate with a file 221 descriptor. Opening a device assigns a medium priority, compatible 222 with earlier versions of V4L2 and drivers not supporting these ioctls. 223 Applications requiring a different priority will usually call 224 <constant>VIDIOC_S_PRIORITY</constant> after verifying the device with 225 the &VIDIOC-QUERYCAP; ioctl.</para> 226 227 <para>Ioctls changing driver properties, such as &VIDIOC-S-INPUT;, 228 return an &EBUSY; after another application obtained higher priority.</para> 229 </section> 230 231 <section id="video"> 232 <title>Video Inputs and Outputs</title> 233 234 <para>Video inputs and outputs are physical connectors of a 235 device. These can be for example RF connectors (antenna/cable), CVBS 236 a.k.a. Composite Video, S-Video or RGB connectors. Video and VBI 237 capture devices have inputs. Video and VBI output devices have outputs, 238 at least one each. Radio devices have no video inputs or outputs.</para> 239 240 <para>To learn about the number and attributes of the 241 available inputs and outputs applications can enumerate them with the 242 &VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; ioctl, respectively. The 243 &v4l2-input; returned by the <constant>VIDIOC_ENUMINPUT</constant> 244 ioctl also contains signal status information applicable when the 245 current video input is queried.</para> 246 247 <para>The &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; ioctls return the 248 index of the current video input or output. To select a different 249 input or output applications call the &VIDIOC-S-INPUT; and 250 &VIDIOC-S-OUTPUT; ioctls. Drivers must implement all the input ioctls 251 when the device has one or more inputs, all the output ioctls when the 252 device has one or more outputs.</para> 253 254 <example> 255 <title>Information about the current video input</title> 256 257 <programlisting> 258 &v4l2-input; input; 259 int index; 260 261 if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &index)) { 262 perror("VIDIOC_G_INPUT"); 263 exit(EXIT_FAILURE); 264 } 265 266 memset(&input, 0, sizeof(input)); 267 input.index = index; 268 269 if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &input)) { 270 perror("VIDIOC_ENUMINPUT"); 271 exit(EXIT_FAILURE); 272 } 273 274 printf("Current input: %s\n", input.name); 275 </programlisting> 276 </example> 277 278 <example> 279 <title>Switching to the first video input</title> 280 281 <programlisting> 282 int index; 283 284 index = 0; 285 286 if (-1 == ioctl(fd, &VIDIOC-S-INPUT;, &index)) { 287 perror("VIDIOC_S_INPUT"); 288 exit(EXIT_FAILURE); 289 } 290 </programlisting> 291 </example> 292 </section> 293 294 <section id="audio"> 295 <title>Audio Inputs and Outputs</title> 296 297 <para>Audio inputs and outputs are physical connectors of a 298 device. Video capture devices have inputs, output devices have 299 outputs, zero or more each. Radio devices have no audio inputs or 300 outputs. They have exactly one tuner which in fact 301 <emphasis>is</emphasis> an audio source, but this API associates 302 tuners with video inputs or outputs only, and radio devices have 303 none of these.<footnote> 304 <para>Actually &v4l2-audio; ought to have a 305 <structfield>tuner</structfield> field like &v4l2-input;, not only 306 making the API more consistent but also permitting radio devices with 307 multiple tuners.</para> 308 </footnote> A connector on a TV card to loop back the received 309 audio signal to a sound card is not considered an audio output.</para> 310 311 <para>Audio and video inputs and outputs are associated. Selecting 312 a video source also selects an audio source. This is most evident when 313 the video and audio source is a tuner. Further audio connectors can 314 combine with more than one video input or output. Assumed two 315 composite video inputs and two audio inputs exist, there may be up to 316 four valid combinations. The relation of video and audio connectors 317 is defined in the <structfield>audioset</structfield> field of the 318 respective &v4l2-input; or &v4l2-output;, where each bit represents 319 the index number, starting at zero, of one audio input or output.</para> 320 321 <para>To learn about the number and attributes of the 322 available inputs and outputs applications can enumerate them with the 323 &VIDIOC-ENUMAUDIO; and &VIDIOC-ENUMAUDOUT; ioctl, respectively. The 324 &v4l2-audio; returned by the <constant>VIDIOC_ENUMAUDIO</constant> ioctl 325 also contains signal status information applicable when the current 326 audio input is queried.</para> 327 328 <para>The &VIDIOC-G-AUDIO; and &VIDIOC-G-AUDOUT; ioctls report 329 the current audio input and output, respectively. Note that, unlike 330 &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; these ioctls return a structure 331 as <constant>VIDIOC_ENUMAUDIO</constant> and 332 <constant>VIDIOC_ENUMAUDOUT</constant> do, not just an index.</para> 333 334 <para>To select an audio input and change its properties 335 applications call the &VIDIOC-S-AUDIO; ioctl. To select an audio 336 output (which presently has no changeable properties) applications 337 call the &VIDIOC-S-AUDOUT; ioctl.</para> 338 339 <para>Drivers must implement all audio input ioctls when the device 340 has multiple selectable audio inputs, all audio output ioctls when the 341 device has multiple selectable audio outputs. When the device has any 342 audio inputs or outputs the driver must set the <constant>V4L2_CAP_AUDIO</constant> 343 flag in the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl.</para> 344 345 <example> 346 <title>Information about the current audio input</title> 347 348 <programlisting> 349 &v4l2-audio; audio; 350 351 memset(&audio, 0, sizeof(audio)); 352 353 if (-1 == ioctl(fd, &VIDIOC-G-AUDIO;, &audio)) { 354 perror("VIDIOC_G_AUDIO"); 355 exit(EXIT_FAILURE); 356 } 357 358 printf("Current input: %s\n", audio.name); 359 </programlisting> 360 </example> 361 362 <example> 363 <title>Switching to the first audio input</title> 364 365 <programlisting> 366 &v4l2-audio; audio; 367 368 memset(&audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */ 369 370 audio.index = 0; 371 372 if (-1 == ioctl(fd, &VIDIOC-S-AUDIO;, &audio)) { 373 perror("VIDIOC_S_AUDIO"); 374 exit(EXIT_FAILURE); 375 } 376 </programlisting> 377 </example> 378 </section> 379 380 <section id="tuner"> 381 <title>Tuners and Modulators</title> 382 383 <section> 384 <title>Tuners</title> 385 386 <para>Video input devices can have one or more tuners 387 demodulating a RF signal. Each tuner is associated with one or more 388 video inputs, depending on the number of RF connectors on the tuner. 389 The <structfield>type</structfield> field of the respective 390 &v4l2-input; returned by the &VIDIOC-ENUMINPUT; ioctl is set to 391 <constant>V4L2_INPUT_TYPE_TUNER</constant> and its 392 <structfield>tuner</structfield> field contains the index number of 393 the tuner.</para> 394 395 <para>Radio input devices have exactly one tuner with index zero, no 396 video inputs.</para> 397 398 <para>To query and change tuner properties applications use the 399 &VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctls, respectively. The 400 &v4l2-tuner; returned by <constant>VIDIOC_G_TUNER</constant> also 401 contains signal status information applicable when the tuner of the 402 current video or radio input is queried. Note that 403 <constant>VIDIOC_S_TUNER</constant> does not switch the current tuner, 404 when there is more than one at all. The tuner is solely determined by 405 the current video input. Drivers must support both ioctls and set the 406 <constant>V4L2_CAP_TUNER</constant> flag in the &v4l2-capability; 407 returned by the &VIDIOC-QUERYCAP; ioctl when the device has one or 408 more tuners.</para> 409 </section> 410 411 <section> 412 <title>Modulators</title> 413 414 <para>Video output devices can have one or more modulators, uh, 415 modulating a video signal for radiation or connection to the antenna 416 input of a TV set or video recorder. Each modulator is associated with 417 one or more video outputs, depending on the number of RF connectors on 418 the modulator. The <structfield>type</structfield> field of the 419 respective &v4l2-output; returned by the &VIDIOC-ENUMOUTPUT; ioctl is 420 set to <constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> and its 421 <structfield>modulator</structfield> field contains the index number 422 of the modulator.</para> 423 424 <para>Radio output devices have exactly one modulator with index 425 zero, no video outputs.</para> 426 427 <para>A video or radio device cannot support both a tuner and a 428 modulator. Two separate device nodes will have to be used for such 429 hardware, one that supports the tuner functionality and one that supports 430 the modulator functionality. The reason is a limitation with the 431 &VIDIOC-S-FREQUENCY; ioctl where you cannot specify whether the frequency 432 is for a tuner or a modulator.</para> 433 434 <para>To query and change modulator properties applications use 435 the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that 436 <constant>VIDIOC_S_MODULATOR</constant> does not switch the current 437 modulator, when there is more than one at all. The modulator is solely 438 determined by the current video output. Drivers must support both 439 ioctls and set the <constant>V4L2_CAP_MODULATOR</constant> flag in 440 the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl when the 441 device has one or more modulators.</para> 442 </section> 443 444 <section> 445 <title>Radio Frequency</title> 446 447 <para>To get and set the tuner or modulator radio frequency 448 applications use the &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY; 449 ioctl which both take a pointer to a &v4l2-frequency;. These ioctls 450 are used for TV and radio devices alike. Drivers must support both 451 ioctls when the tuner or modulator ioctls are supported, or 452 when the device is a radio device.</para> 453 </section> 454 </section> 455 456 <section id="standard"> 457 <title>Video Standards</title> 458 459 <para>Video devices typically support one or more different video 460 standards or variations of standards. Each video input and output may 461 support another set of standards. This set is reported by the 462 <structfield>std</structfield> field of &v4l2-input; and 463 &v4l2-output; returned by the &VIDIOC-ENUMINPUT; and 464 &VIDIOC-ENUMOUTPUT; ioctls, respectively.</para> 465 466 <para>V4L2 defines one bit for each analog video standard 467 currently in use worldwide, and sets aside bits for driver defined 468 standards, ⪚ hybrid standards to watch NTSC video tapes on PAL TVs 469 and vice versa. Applications can use the predefined bits to select a 470 particular standard, although presenting the user a menu of supported 471 standards is preferred. To enumerate and query the attributes of the 472 supported standards applications use the &VIDIOC-ENUMSTD; ioctl.</para> 473 474 <para>Many of the defined standards are actually just variations 475 of a few major standards. The hardware may in fact not distinguish 476 between them, or do so internal and switch automatically. Therefore 477 enumerated standards also contain sets of one or more standard 478 bits.</para> 479 480 <para>Assume a hypothetic tuner capable of demodulating B/PAL, 481 G/PAL and I/PAL signals. The first enumerated standard is a set of B 482 and G/PAL, switched automatically depending on the selected radio 483 frequency in UHF or VHF band. Enumeration gives a "PAL-B/G" or "PAL-I" 484 choice. Similar a Composite input may collapse standards, enumerating 485 "PAL-B/G/H/I", "NTSC-M" and "SECAM-D/K".<footnote> 486 <para>Some users are already confused by technical terms PAL, 487 NTSC and SECAM. There is no point asking them to distinguish between 488 B, G, D, or K when the software or hardware can do that 489 automatically.</para> 490 </footnote></para> 491 492 <para>To query and select the standard used by the current video 493 input or output applications call the &VIDIOC-G-STD; and 494 &VIDIOC-S-STD; ioctl, respectively. The <emphasis>received</emphasis> 495 standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note that the 496 parameter of all these ioctls is a pointer to a &v4l2-std-id; type 497 (a standard set), <emphasis>not</emphasis> an index into the standard 498 enumeration. Drivers must implement all video standard ioctls 499 when the device has one or more video inputs or outputs.</para> 500 501 <para>Special rules apply to devices such as USB cameras where the notion of video 502 standards makes little sense. More generally for any capture or output device 503 which is: <itemizedlist> 504 <listitem> 505 <para>incapable of capturing fields or frames at the nominal 506 rate of the video standard, or</para> 507 </listitem> 508 <listitem> 509 <para>that does not support the video standard formats at all.</para> 510 </listitem> 511 </itemizedlist> Here the driver shall set the 512 <structfield>std</structfield> field of &v4l2-input; and &v4l2-output; 513 to zero and the <constant>VIDIOC_G_STD</constant>, 514 <constant>VIDIOC_S_STD</constant>, 515 <constant>VIDIOC_QUERYSTD</constant> and 516 <constant>VIDIOC_ENUMSTD</constant> ioctls shall return the 517 &ENOTTY; or the &EINVAL;.</para> 518 <para>Applications can make use of the <xref linkend="input-capabilities" /> and 519 <xref linkend="output-capabilities"/> flags to determine whether the video standard ioctls 520 can be used with the given input or output.</para> 521 522 <example> 523 <title>Information about the current video standard</title> 524 525 <programlisting> 526 &v4l2-std-id; std_id; 527 &v4l2-standard; standard; 528 529 if (-1 == ioctl(fd, &VIDIOC-G-STD;, &std_id)) { 530 /* Note when VIDIOC_ENUMSTD always returns ENOTTY this 531 is no video device or it falls under the USB exception, 532 and VIDIOC_G_STD returning ENOTTY is no error. */ 533 534 perror("VIDIOC_G_STD"); 535 exit(EXIT_FAILURE); 536 } 537 538 memset(&standard, 0, sizeof(standard)); 539 standard.index = 0; 540 541 while (0 == ioctl(fd, &VIDIOC-ENUMSTD;, &standard)) { 542 if (standard.id & std_id) { 543 printf("Current video standard: %s\n", standard.name); 544 exit(EXIT_SUCCESS); 545 } 546 547 standard.index++; 548 } 549 550 /* EINVAL indicates the end of the enumeration, which cannot be 551 empty unless this device falls under the USB exception. */ 552 553 if (errno == EINVAL || standard.index == 0) { 554 perror("VIDIOC_ENUMSTD"); 555 exit(EXIT_FAILURE); 556 } 557 </programlisting> 558 </example> 559 560 <example> 561 <title>Listing the video standards supported by the current 562 input</title> 563 564 <programlisting> 565 &v4l2-input; input; 566 &v4l2-standard; standard; 567 568 memset(&input, 0, sizeof(input)); 569 570 if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &input.index)) { 571 perror("VIDIOC_G_INPUT"); 572 exit(EXIT_FAILURE); 573 } 574 575 if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &input)) { 576 perror("VIDIOC_ENUM_INPUT"); 577 exit(EXIT_FAILURE); 578 } 579 580 printf("Current input %s supports:\n", input.name); 581 582 memset(&standard, 0, sizeof(standard)); 583 standard.index = 0; 584 585 while (0 == ioctl(fd, &VIDIOC-ENUMSTD;, &standard)) { 586 if (standard.id & input.std) 587 printf("%s\n", standard.name); 588 589 standard.index++; 590 } 591 592 /* EINVAL indicates the end of the enumeration, which cannot be 593 empty unless this device falls under the USB exception. */ 594 595 if (errno != EINVAL || standard.index == 0) { 596 perror("VIDIOC_ENUMSTD"); 597 exit(EXIT_FAILURE); 598 } 599 </programlisting> 600 </example> 601 602 <example> 603 <title>Selecting a new video standard</title> 604 605 <programlisting> 606 &v4l2-input; input; 607 &v4l2-std-id; std_id; 608 609 memset(&input, 0, sizeof(input)); 610 611 if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &input.index)) { 612 perror("VIDIOC_G_INPUT"); 613 exit(EXIT_FAILURE); 614 } 615 616 if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &input)) { 617 perror("VIDIOC_ENUM_INPUT"); 618 exit(EXIT_FAILURE); 619 } 620 621 if (0 == (input.std & V4L2_STD_PAL_BG)) { 622 fprintf(stderr, "Oops. B/G PAL is not supported.\n"); 623 exit(EXIT_FAILURE); 624 } 625 626 /* Note this is also supposed to work when only B 627 <emphasis>or</emphasis> G/PAL is supported. */ 628 629 std_id = V4L2_STD_PAL_BG; 630 631 if (-1 == ioctl(fd, &VIDIOC-S-STD;, &std_id)) { 632 perror("VIDIOC_S_STD"); 633 exit(EXIT_FAILURE); 634 } 635 </programlisting> 636 </example> 637 </section> 638 <section id="dv-timings"> 639 <title>Digital Video (DV) Timings</title> 640 <para> 641 The video standards discussed so far have been dealing with Analog TV and the 642 corresponding video timings. Today there are many more different hardware interfaces 643 such as High Definition TV interfaces (HDMI), VGA, DVI connectors etc., that carry 644 video signals and there is a need to extend the API to select the video timings 645 for these interfaces. Since it is not possible to extend the &v4l2-std-id; due to 646 the limited bits available, a new set of ioctls was added to set/get video timings at 647 the input and output.</para> 648 649 <para>These ioctls deal with the detailed digital video timings that define 650 each video format. This includes parameters such as the active video width and height, 651 signal polarities, frontporches, backporches, sync widths etc. The <filename>linux/v4l2-dv-timings.h</filename> 652 header can be used to get the timings of the formats in the <xref linkend="cea861" /> and 653 <xref linkend="vesadmt" /> standards. 654 </para> 655 656 <para>To enumerate and query the attributes of the DV timings supported by a device 657 applications use the &VIDIOC-ENUM-DV-TIMINGS; and &VIDIOC-DV-TIMINGS-CAP; ioctls. 658 To set DV timings for the device applications use the 659 &VIDIOC-S-DV-TIMINGS; ioctl and to get current DV timings they use the 660 &VIDIOC-G-DV-TIMINGS; ioctl. To detect the DV timings as seen by the video receiver applications 661 use the &VIDIOC-QUERY-DV-TIMINGS; ioctl.</para> 662 <para>Applications can make use of the <xref linkend="input-capabilities" /> and 663 <xref linkend="output-capabilities"/> flags to determine whether the digital video ioctls 664 can be used with the given input or output.</para> 665 </section> 666 667 &sub-controls; 668 669 <section id="format"> 670 <title>Data Formats</title> 671 672 <section> 673 <title>Data Format Negotiation</title> 674 675 <para>Different devices exchange different kinds of data with 676 applications, for example video images, raw or sliced VBI data, RDS 677 datagrams. Even within one kind many different formats are possible, 678 in particular an abundance of image formats. Although drivers must 679 provide a default and the selection persists across closing and 680 reopening a device, applications should always negotiate a data format 681 before engaging in data exchange. Negotiation means the application 682 asks for a particular format and the driver selects and reports the 683 best the hardware can do to satisfy the request. Of course 684 applications can also just query the current selection.</para> 685 686 <para>A single mechanism exists to negotiate all data formats 687 using the aggregate &v4l2-format; and the &VIDIOC-G-FMT; and 688 &VIDIOC-S-FMT; ioctls. Additionally the &VIDIOC-TRY-FMT; ioctl can be 689 used to examine what the hardware <emphasis>could</emphasis> do, 690 without actually selecting a new data format. The data formats 691 supported by the V4L2 API are covered in the respective device section 692 in <xref linkend="devices" />. For a closer look at image formats see 693 <xref linkend="pixfmt" />.</para> 694 695 <para>The <constant>VIDIOC_S_FMT</constant> ioctl is a major 696 turning-point in the initialization sequence. Prior to this point 697 multiple panel applications can access the same device concurrently to 698 select the current input, change controls or modify other properties. 699 The first <constant>VIDIOC_S_FMT</constant> assigns a logical stream 700 (video data, VBI data etc.) exclusively to one file descriptor.</para> 701 702 <para>Exclusive means no other application, more precisely no 703 other file descriptor, can grab this stream or change device 704 properties inconsistent with the negotiated parameters. A video 705 standard change for example, when the new standard uses a different 706 number of scan lines, can invalidate the selected image format. 707 Therefore only the file descriptor owning the stream can make 708 invalidating changes. Accordingly multiple file descriptors which 709 grabbed different logical streams prevent each other from interfering 710 with their settings. When for example video overlay is about to start 711 or already in progress, simultaneous video capturing may be restricted 712 to the same cropping and image size.</para> 713 714 <para>When applications omit the 715 <constant>VIDIOC_S_FMT</constant> ioctl its locking side effects are 716 implied by the next step, the selection of an I/O method with the 717 &VIDIOC-REQBUFS; ioctl or implicit with the first &func-read; or 718 &func-write; call.</para> 719 720 <para>Generally only one logical stream can be assigned to a 721 file descriptor, the exception being drivers permitting simultaneous 722 video capturing and overlay using the same file descriptor for 723 compatibility with V4L and earlier versions of V4L2. Switching the 724 logical stream or returning into "panel mode" is possible by closing 725 and reopening the device. Drivers <emphasis>may</emphasis> support a 726 switch using <constant>VIDIOC_S_FMT</constant>.</para> 727 728 <para>All drivers exchanging data with 729 applications must support the <constant>VIDIOC_G_FMT</constant> and 730 <constant>VIDIOC_S_FMT</constant> ioctl. Implementation of the 731 <constant>VIDIOC_TRY_FMT</constant> is highly recommended but 732 optional.</para> 733 </section> 734 735 <section> 736 <title>Image Format Enumeration</title> 737 738 <para>Apart of the generic format negotiation functions 739 a special ioctl to enumerate all image formats supported by video 740 capture, overlay or output devices is available.<footnote> 741 <para>Enumerating formats an application has no a-priori 742 knowledge of (otherwise it could explicitly ask for them and need not 743 enumerate) seems useless, but there are applications serving as proxy 744 between drivers and the actual video applications for which this is 745 useful.</para> 746 </footnote></para> 747 748 <para>The &VIDIOC-ENUM-FMT; ioctl must be supported 749 by all drivers exchanging image data with applications.</para> 750 751 <important> 752 <para>Drivers are not supposed to convert image formats in 753 kernel space. They must enumerate only formats directly supported by 754 the hardware. If necessary driver writers should publish an example 755 conversion routine or library for integration into applications.</para> 756 </important> 757 </section> 758 </section> 759 760 &sub-planar-apis; 761 762 <section id="crop"> 763 <title>Image Cropping, Insertion and Scaling</title> 764 765 <para>Some video capture devices can sample a subsection of the 766 picture and shrink or enlarge it to an image of arbitrary size. We 767 call these abilities cropping and scaling. Some video output devices 768 can scale an image up or down and insert it at an arbitrary scan line 769 and horizontal offset into a video signal.</para> 770 771 <para>Applications can use the following API to select an area in 772 the video signal, query the default area and the hardware limits. 773 <emphasis>Despite their name, the &VIDIOC-CROPCAP;, &VIDIOC-G-CROP; 774 and &VIDIOC-S-CROP; ioctls apply to input as well as output 775 devices.</emphasis></para> 776 777 <para>Scaling requires a source and a target. On a video capture 778 or overlay device the source is the video signal, and the cropping 779 ioctls determine the area actually sampled. The target are images 780 read by the application or overlaid onto the graphics screen. Their 781 size (and position for an overlay) is negotiated with the 782 &VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls.</para> 783 784 <para>On a video output device the source are the images passed in 785 by the application, and their size is again negotiated with the 786 <constant>VIDIOC_G/S_FMT</constant> ioctls, or may be encoded in a 787 compressed video stream. The target is the video signal, and the 788 cropping ioctls determine the area where the images are 789 inserted.</para> 790 791 <para>Source and target rectangles are defined even if the device 792 does not support scaling or the <constant>VIDIOC_G/S_CROP</constant> 793 ioctls. Their size (and position where applicable) will be fixed in 794 this case. <emphasis>All capture and output device must support the 795 <constant>VIDIOC_CROPCAP</constant> ioctl such that applications can 796 determine if scaling takes place.</emphasis></para> 797 798 <section> 799 <title>Cropping Structures</title> 800 801 <figure id="crop-scale"> 802 <title>Image Cropping, Insertion and Scaling</title> 803 <mediaobject> 804 <imageobject> 805 <imagedata fileref="crop.pdf" format="PS" /> 806 </imageobject> 807 <imageobject> 808 <imagedata fileref="crop.gif" format="GIF" /> 809 </imageobject> 810 <textobject> 811 <phrase>The cropping, insertion and scaling process</phrase> 812 </textobject> 813 </mediaobject> 814 </figure> 815 816 <para>For capture devices the coordinates of the top left 817 corner, width and height of the area which can be sampled is given by 818 the <structfield>bounds</structfield> substructure of the 819 &v4l2-cropcap; returned by the <constant>VIDIOC_CROPCAP</constant> 820 ioctl. To support a wide range of hardware this specification does not 821 define an origin or units. However by convention drivers should 822 horizontally count unscaled samples relative to 0H (the leading edge 823 of the horizontal sync pulse, see <xref linkend="vbi-hsync" />). 824 Vertically ITU-R line 825 numbers of the first field (<xref linkend="vbi-525" />, <xref 826 linkend="vbi-625" />), multiplied by two if the driver can capture both 827 fields.</para> 828 829 <para>The top left corner, width and height of the source 830 rectangle, that is the area actually sampled, is given by &v4l2-crop; 831 using the same coordinate system as &v4l2-cropcap;. Applications can 832 use the <constant>VIDIOC_G_CROP</constant> and 833 <constant>VIDIOC_S_CROP</constant> ioctls to get and set this 834 rectangle. It must lie completely within the capture boundaries and 835 the driver may further adjust the requested size and/or position 836 according to hardware limitations.</para> 837 838 <para>Each capture device has a default source rectangle, given 839 by the <structfield>defrect</structfield> substructure of 840 &v4l2-cropcap;. The center of this rectangle shall align with the 841 center of the active picture area of the video signal, and cover what 842 the driver writer considers the complete picture. Drivers shall reset 843 the source rectangle to the default when the driver is first loaded, 844 but not later.</para> 845 846 <para>For output devices these structures and ioctls are used 847 accordingly, defining the <emphasis>target</emphasis> rectangle where 848 the images will be inserted into the video signal.</para> 849 850 </section> 851 852 <section> 853 <title>Scaling Adjustments</title> 854 855 <para>Video hardware can have various cropping, insertion and 856 scaling limitations. It may only scale up or down, support only 857 discrete scaling factors, or have different scaling abilities in 858 horizontal and vertical direction. Also it may not support scaling at 859 all. At the same time the &v4l2-crop; rectangle may have to be 860 aligned, and both the source and target rectangles may have arbitrary 861 upper and lower size limits. In particular the maximum 862 <structfield>width</structfield> and <structfield>height</structfield> 863 in &v4l2-crop; may be smaller than the 864 &v4l2-cropcap;.<structfield>bounds</structfield> area. Therefore, as 865 usual, drivers are expected to adjust the requested parameters and 866 return the actual values selected.</para> 867 868 <para>Applications can change the source or the target rectangle 869 first, as they may prefer a particular image size or a certain area in 870 the video signal. If the driver has to adjust both to satisfy hardware 871 limitations, the last requested rectangle shall take priority, and the 872 driver should preferably adjust the opposite one. The &VIDIOC-TRY-FMT; 873 ioctl however shall not change the driver state and therefore only 874 adjust the requested rectangle.</para> 875 876 <para>Suppose scaling on a video capture device is restricted to 877 a factor 1:1 or 2:1 in either direction and the target image size must 878 be a multiple of 16 × 16 pixels. The source cropping 879 rectangle is set to defaults, which are also the upper limit in this 880 example, of 640 × 400 pixels at offset 0, 0. An 881 application requests an image size of 300 × 225 882 pixels, assuming video will be scaled down from the "full picture" 883 accordingly. The driver sets the image size to the closest possible 884 values 304 × 224, then chooses the cropping rectangle 885 closest to the requested size, that is 608 × 224 886 (224 × 2:1 would exceed the limit 400). The offset 887 0, 0 is still valid, thus unmodified. Given the default cropping 888 rectangle reported by <constant>VIDIOC_CROPCAP</constant> the 889 application can easily propose another offset to center the cropping 890 rectangle.</para> 891 892 <para>Now the application may insist on covering an area using a 893 picture aspect ratio closer to the original request, so it asks for a 894 cropping rectangle of 608 × 456 pixels. The present 895 scaling factors limit cropping to 640 × 384, so the 896 driver returns the cropping size 608 × 384 and adjusts 897 the image size to closest possible 304 × 192.</para> 898 899 </section> 900 901 <section> 902 <title>Examples</title> 903 904 <para>Source and target rectangles shall remain unchanged across 905 closing and reopening a device, such that piping data into or out of a 906 device will work without special preparations. More advanced 907 applications should ensure the parameters are suitable before starting 908 I/O.</para> 909 910 <example> 911 <title>Resetting the cropping parameters</title> 912 913 <para>(A video capture device is assumed; change 914 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other 915 devices.)</para> 916 917 <programlisting> 918 &v4l2-cropcap; cropcap; 919 &v4l2-crop; crop; 920 921 memset (&cropcap, 0, sizeof (cropcap)); 922 cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; 923 924 if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &cropcap)) { 925 perror ("VIDIOC_CROPCAP"); 926 exit (EXIT_FAILURE); 927 } 928 929 memset (&crop, 0, sizeof (crop)); 930 crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; 931 crop.c = cropcap.defrect; 932 933 /* Ignore if cropping is not supported (EINVAL). */ 934 935 if (-1 == ioctl (fd, &VIDIOC-S-CROP;, &crop) 936 && errno != EINVAL) { 937 perror ("VIDIOC_S_CROP"); 938 exit (EXIT_FAILURE); 939 } 940 </programlisting> 941 </example> 942 943 <example> 944 <title>Simple downscaling</title> 945 946 <para>(A video capture device is assumed.)</para> 947 948 <programlisting> 949 &v4l2-cropcap; cropcap; 950 &v4l2-format; format; 951 952 reset_cropping_parameters (); 953 954 /* Scale down to 1/4 size of full picture. */ 955 956 memset (&format, 0, sizeof (format)); /* defaults */ 957 958 format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; 959 960 format.fmt.pix.width = cropcap.defrect.width >> 1; 961 format.fmt.pix.height = cropcap.defrect.height >> 1; 962 format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV; 963 964 if (-1 == ioctl (fd, &VIDIOC-S-FMT;, &format)) { 965 perror ("VIDIOC_S_FORMAT"); 966 exit (EXIT_FAILURE); 967 } 968 969 /* We could check the actual image size now, the actual scaling factor 970 or if the driver can scale at all. */ 971 </programlisting> 972 </example> 973 974 <example> 975 <title>Selecting an output area</title> 976 977 <programlisting> 978 &v4l2-cropcap; cropcap; 979 &v4l2-crop; crop; 980 981 memset (&cropcap, 0, sizeof (cropcap)); 982 cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; 983 984 if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &cropcap)) { 985 perror ("VIDIOC_CROPCAP"); 986 exit (EXIT_FAILURE); 987 } 988 989 memset (&crop, 0, sizeof (crop)); 990 991 crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; 992 crop.c = cropcap.defrect; 993 994 /* Scale the width and height to 50 % of their original size 995 and center the output. */ 996 997 crop.c.width /= 2; 998 crop.c.height /= 2; 999 crop.c.left += crop.c.width / 2; 1000 crop.c.top += crop.c.height / 2; 1001 1002 /* Ignore if cropping is not supported (EINVAL). */ 1003 1004 if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop) 1005 && errno != EINVAL) { 1006 perror ("VIDIOC_S_CROP"); 1007 exit (EXIT_FAILURE); 1008 } 1009 </programlisting> 1010 </example> 1011 1012 <example> 1013 <title>Current scaling factor and pixel aspect</title> 1014 1015 <para>(A video capture device is assumed.)</para> 1016 1017 <programlisting> 1018 &v4l2-cropcap; cropcap; 1019 &v4l2-crop; crop; 1020 &v4l2-format; format; 1021 double hscale, vscale; 1022 double aspect; 1023 int dwidth, dheight; 1024 1025 memset (&cropcap, 0, sizeof (cropcap)); 1026 cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; 1027 1028 if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &cropcap)) { 1029 perror ("VIDIOC_CROPCAP"); 1030 exit (EXIT_FAILURE); 1031 } 1032 1033 memset (&crop, 0, sizeof (crop)); 1034 crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; 1035 1036 if (-1 == ioctl (fd, &VIDIOC-G-CROP;, &crop)) { 1037 if (errno != EINVAL) { 1038 perror ("VIDIOC_G_CROP"); 1039 exit (EXIT_FAILURE); 1040 } 1041 1042 /* Cropping not supported. */ 1043 crop.c = cropcap.defrect; 1044 } 1045 1046 memset (&format, 0, sizeof (format)); 1047 format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; 1048 1049 if (-1 == ioctl (fd, &VIDIOC-G-FMT;, &format)) { 1050 perror ("VIDIOC_G_FMT"); 1051 exit (EXIT_FAILURE); 1052 } 1053 1054 /* The scaling applied by the driver. */ 1055 1056 hscale = format.fmt.pix.width / (double) crop.c.width; 1057 vscale = format.fmt.pix.height / (double) crop.c.height; 1058 1059 aspect = cropcap.pixelaspect.numerator / 1060 (double) cropcap.pixelaspect.denominator; 1061 aspect = aspect * hscale / vscale; 1062 1063 /* Devices following ITU-R BT.601 do not capture 1064 square pixels. For playback on a computer monitor 1065 we should scale the images to this size. */ 1066 1067 dwidth = format.fmt.pix.width / aspect; 1068 dheight = format.fmt.pix.height; 1069 </programlisting> 1070 </example> 1071 </section> 1072 </section> 1073 1074 &sub-selection-api; 1075 1076 <section id="streaming-par"> 1077 <title>Streaming Parameters</title> 1078 1079 <para>Streaming parameters are intended to optimize the video 1080 capture process as well as I/O. Presently applications can request a 1081 high quality capture mode with the &VIDIOC-S-PARM; ioctl.</para> 1082 1083 <para>The current video standard determines a nominal number of 1084 frames per second. If less than this number of frames is to be 1085 captured or output, applications can request frame skipping or 1086 duplicating on the driver side. This is especially useful when using 1087 the &func-read; or &func-write;, which are not augmented by timestamps 1088 or sequence counters, and to avoid unnecessary data copying.</para> 1089 1090 <para>Finally these ioctls can be used to determine the number of 1091 buffers used internally by a driver in read/write mode. For 1092 implications see the section discussing the &func-read; 1093 function.</para> 1094 1095 <para>To get and set the streaming parameters applications call 1096 the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; ioctl, respectively. They take 1097 a pointer to a &v4l2-streamparm;, which contains a union holding 1098 separate parameters for input and output devices.</para> 1099 1100 <para>These ioctls are optional, drivers need not implement 1101 them. If so, they return the &EINVAL;.</para> 1102 </section>
