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