1 <title>Common API Elements</title>
3 <para>Programming a V4L2 device consists of these
8 <para>Opening the device</para>
11 <para>Changing device properties, selecting a video and audio
12 input, video standard, picture brightness a. o.</para>
15 <para>Negotiating a data format</para>
18 <para>Negotiating an input/output method</para>
21 <para>The actual input/output loop</para>
24 <para>Closing the device</para>
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>
34 <title>Opening and Closing Devices</title>
37 <title>Device Naming</title>
39 <para>V4L2 drivers are implemented as kernel modules, loaded
40 manually by the system administrator or automatically when a device is
41 first opened. 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>
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. Assigning
47 minor numbers to V4L2 devices is entirely up to the system administrator,
48 this is primarily intended to solve conflicts between devices.<footnote>
49 <para>Access permissions are associated with character
50 device special files, hence we must ensure device numbers cannot
51 change with the module load order. To this end minor numbers are no
52 longer automatically assigned by the "videodev" module as in V4L but
53 requested by the driver. The defaults will suffice for most people
54 unless two drivers compete for the same minor numbers.</para>
55 </footnote> The module options to select minor numbers are named
56 after the device special file with a "_nr" suffix. For example "video_nr"
57 for <filename>/dev/video</filename> video capture devices. The number is
58 an offset to the base minor number associated with the device type.
60 <para>In earlier versions of the V4L2 API the module options
61 where named after the device special file with a "unit_" prefix, expressing
62 the minor number itself, not an offset. Rationale for this change is unknown.
63 Lastly the naming and semantics are just a convention among driver writers,
64 the point to note is that minor numbers are not supposed to be hardcoded
66 </footnote> When the driver supports multiple devices of the same
67 type more than one minor number can be assigned, separated by commas:
70 > insmod mydriver.o video_nr=0,1 radio_nr=0,1</screen>
71 </informalexample></para>
73 <para>In <filename>/etc/modules.conf</filename> this may be
74 written as: <informalexample>
76 alias char-major-81-0 mydriver
77 alias char-major-81-1 mydriver
78 alias char-major-81-64 mydriver <co id="alias" />
79 options mydriver video_nr=0,1 radio_nr=0,1 <co id="options" />
82 <callout arearefs="alias">
83 <para>When an application attempts to open a device
84 special file with major number 81 and minor number 0, 1, or 64, load
85 "mydriver" (and the "videodev" module it depends upon).</para>
87 <callout arearefs="options">
88 <para>Register the first two video capture devices with
89 minor number 0 and 1 (base number is 0), the first two radio device
90 with minor number 64 and 65 (base 64).</para>
93 </informalexample> When no minor number is given as module
94 option the driver supplies a default. <xref linkend="devices" />
95 recommends the base minor numbers to be used for the various device
96 types. Obviously minor numbers must be unique. When the number is
97 already in use the <emphasis>offending device</emphasis> will not be
98 registered. <!-- Blessed by Linus Torvalds on
99 linux-kernel@vger.kernel.org, 2002-11-20. --></para>
101 <para>By convention system administrators create various
102 character device special files with these major and minor numbers in
103 the <filename>/dev</filename> directory. The names recommended for the
104 different V4L2 device types are listed in <xref linkend="devices" />.
107 <para>The creation of character special files (with
108 <application>mknod</application>) is a privileged operation and
109 devices cannot be opened by major and minor number. That means
110 applications cannot <emphasis>reliable</emphasis> scan for loaded or
111 installed drivers. The user must enter a device name, or the
112 application can try the conventional device names.</para>
114 <para>Under the device filesystem (devfs) the minor number
115 options are ignored. V4L2 drivers (or by proxy the "videodev" module)
116 automatically create the required device files in the
117 <filename>/dev/v4l</filename> directory using the conventional device
121 <section id="related">
122 <title>Related Devices</title>
124 <para>Devices can support several related functions. For example
125 video capturing, video overlay and VBI capturing are related because
126 these functions share, amongst other, the same video input and tuner
127 frequency. V4L and earlier versions of V4L2 used the same device name
128 and minor number for video capturing and overlay, but different ones
129 for VBI. Experience showed this approach has several problems<footnote>
130 <para>Given a device file name one cannot reliable find
131 related devices. For once names are arbitrary and in a system with
132 multiple 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
136 device file with a particular major and minor number.</para>
137 </footnote>, and to make things worse the V4L videodev module
138 used to prohibit multiple opens of a device.</para>
140 <para>As a remedy the present version of the V4L2 API relaxed the
141 concept of device types with specific names and minor numbers. For
142 compatibility with old applications drivers must still register different
143 minor numbers to assign a default function to the device. But if related
144 functions are supported by the driver they must be available under all
145 registered minor numbers. The desired function can be selected after
146 opening the device as described in <xref linkend="devices" />.</para>
148 <para>Imagine a driver supporting video capturing, video
149 overlay, raw VBI capturing, and FM radio reception. It registers three
150 devices with minor number 0, 64 and 224 (this numbering scheme is
151 inherited 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
154 select any one of the video capturing, overlay or VBI capturing
155 functions. Without programming (e. g. reading from the device
156 with <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,
160 unrelated to the video functions. Being unrelated does not imply the
161 devices can be used at the same time, however. The &func-open;
162 function may very well return an &EBUSY;.</para>
164 <para>Besides video input or output the hardware may also
165 support audio sampling or playback. If so, these functions are
166 implemented as OSS or ALSA PCM devices and eventually OSS or ALSA
167 audio mixer. The V4L2 API makes no provisions yet to find these
168 related devices. If you have an idea please write to the linux-media
169 mailing list: &v4l-ml;.</para>
173 <title>Multiple Opens</title>
175 <para>In general, V4L2 devices can be opened more than once.
176 When this is supported by the driver, users can for example start a
177 "panel" application to change controls like brightness or audio
178 volume, while another application captures video and audio. In other words, panel
179 applications are comparable to an OSS or ALSA audio mixer application.
180 When a device supports multiple functions like capturing and overlay
181 <emphasis>simultaneously</emphasis>, multiple opens allow concurrent
182 use of the device by forked processes or specialized applications.</para>
184 <para>Multiple opens are optional, although drivers should
185 permit at least concurrent accesses without data exchange, &ie; panel
186 applications. This implies &func-open; can return an &EBUSY; when the
187 device is already in use, as well as &func-ioctl; functions initiating
188 data exchange (namely the &VIDIOC-S-FMT; ioctl), and the &func-read;
189 and &func-write; functions.</para>
191 <para>Mere opening a V4L2 device does not grant exclusive
193 <para>Drivers could recognize the
194 <constant>O_EXCL</constant> open flag. Presently this is not required,
195 so applications cannot know if it really works.</para>
196 </footnote> Initiating data exchange however assigns the right
197 to read or write the requested type of data, and to change related
198 properties, to this file descriptor. Applications can request
199 additional access privileges using the priority mechanism described in
200 <xref linkend="app-pri" />.</para>
204 <title>Shared Data Streams</title>
206 <para>V4L2 drivers should not support multiple applications
207 reading or writing the same data stream on a device by copying
208 buffers, time multiplexing or similar means. This is better handled by
209 a proxy application in user space. When the driver supports stream
210 sharing anyway it must be implemented transparently. The V4L2 API does
211 not specify how conflicts are solved. <!-- For example O_EXCL when the
212 application does not want to be preempted, PROT_READ mmapped buffers
213 which can be mapped twice, what happens when image formats do not
218 <title>Functions</title>
220 <para>To open and close V4L2 devices applications use the
221 &func-open; and &func-close; function, respectively. Devices are
222 programmed using the &func-ioctl; function as explained in the
223 following sections.</para>
227 <section id="querycap">
228 <title>Querying Capabilities</title>
230 <para>Because V4L2 covers a wide variety of devices not all
231 aspects of the API are equally applicable to all types of devices.
232 Furthermore devices of the same type have different capabilities and
233 this specification permits the omission of a few complicated and less
234 important parts of the API.</para>
236 <para>The &VIDIOC-QUERYCAP; ioctl is available to check if the kernel
237 device is compatible with this specification, and to query the <link
238 linkend="devices">functions</link> and <link linkend="io">I/O
239 methods</link> supported by the device.</para>
241 <para>Starting with kernel version 3.1, VIDIOC-QUERYCAP will return the
242 V4L2 API version used by the driver, with generally matches the Kernel version.
243 There's no need of using &VIDIOC-QUERYCAP; to check if an specific ioctl is
244 supported, the V4L2 core now returns ENOIOCTLCMD if a driver doesn't provide
245 support for an ioctl.</para>
247 <para>Other features can be queried
248 by calling the respective ioctl, for example &VIDIOC-ENUMINPUT;
249 to learn about the number, types and names of video connectors on the
250 device. Although abstraction is a major objective of this API, the
251 ioctl also allows driver specific applications to reliable identify
254 <para>All V4L2 drivers must support
255 <constant>VIDIOC_QUERYCAP</constant>. Applications should always call
256 this ioctl after opening the device.</para>
259 <section id="app-pri">
260 <title>Application Priority</title>
262 <para>When multiple applications share a device it may be
263 desirable to assign them different priorities. Contrary to the
264 traditional "rm -rf /" school of thought a video recording application
265 could for example block other applications from changing video
266 controls or switching the current TV channel. Another objective is to
267 permit low priority applications working in background, which can be
268 preempted by user controlled applications and automatically regain
269 control of the device at a later time.</para>
271 <para>Since these features cannot be implemented entirely in user
272 space V4L2 defines the &VIDIOC-G-PRIORITY; and &VIDIOC-S-PRIORITY;
273 ioctls to request and query the access priority associate with a file
274 descriptor. Opening a device assigns a medium priority, compatible
275 with earlier versions of V4L2 and drivers not supporting these ioctls.
276 Applications requiring a different priority will usually call
277 <constant>VIDIOC_S_PRIORITY</constant> after verifying the device with
278 the &VIDIOC-QUERYCAP; ioctl.</para>
280 <para>Ioctls changing driver properties, such as &VIDIOC-S-INPUT;,
281 return an &EBUSY; after another application obtained higher priority.
282 An event mechanism to notify applications about asynchronous property
283 changes has been proposed but not added yet.</para>
287 <title>Video Inputs and Outputs</title>
289 <para>Video inputs and outputs are physical connectors of a
290 device. These can be for example RF connectors (antenna/cable), CVBS
291 a.k.a. Composite Video, S-Video or RGB connectors. Only video and VBI
292 capture devices have inputs, output devices have outputs, at least one
293 each. Radio devices have no video inputs or outputs.</para>
295 <para>To learn about the number and attributes of the
296 available inputs and outputs applications can enumerate them with the
297 &VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; ioctl, respectively. The
298 &v4l2-input; returned by the <constant>VIDIOC_ENUMINPUT</constant>
299 ioctl also contains signal status information applicable when the
300 current video input is queried.</para>
302 <para>The &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; ioctl return the
303 index of the current video input or output. To select a different
304 input or output applications call the &VIDIOC-S-INPUT; and
305 &VIDIOC-S-OUTPUT; ioctl. Drivers must implement all the input ioctls
306 when the device has one or more inputs, all the output ioctls when the
307 device has one or more outputs.</para>
311 <title>Input and output enumeration is the root of most device properties.</title>
314 <imagedata fileref="links.pdf" format="ps" />
317 <imagedata fileref="links.gif" format="gif" />
320 <phrase>Links between various device property structures.</phrase>
327 <title>Information about the current video input</title>
333 if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &index)) {
334 perror ("VIDIOC_G_INPUT");
338 memset (&input, 0, sizeof (input));
341 if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &input)) {
342 perror ("VIDIOC_ENUMINPUT");
346 printf ("Current input: %s\n", input.name);
351 <title>Switching to the first video input</title>
358 if (-1 == ioctl (fd, &VIDIOC-S-INPUT;, &index)) {
359 perror ("VIDIOC_S_INPUT");
367 <title>Audio Inputs and Outputs</title>
369 <para>Audio inputs and outputs are physical connectors of a
370 device. Video capture devices have inputs, output devices have
371 outputs, zero or more each. Radio devices have no audio inputs or
372 outputs. They have exactly one tuner which in fact
373 <emphasis>is</emphasis> an audio source, but this API associates
374 tuners with video inputs or outputs only, and radio devices have
375 none of these.<footnote>
376 <para>Actually &v4l2-audio; ought to have a
377 <structfield>tuner</structfield> field like &v4l2-input;, not only
378 making the API more consistent but also permitting radio devices with
379 multiple tuners.</para>
380 </footnote> A connector on a TV card to loop back the received
381 audio signal to a sound card is not considered an audio output.</para>
383 <para>Audio and video inputs and outputs are associated. Selecting
384 a video source also selects an audio source. This is most evident when
385 the video and audio source is a tuner. Further audio connectors can
386 combine with more than one video input or output. Assumed two
387 composite video inputs and two audio inputs exist, there may be up to
388 four valid combinations. The relation of video and audio connectors
389 is defined in the <structfield>audioset</structfield> field of the
390 respective &v4l2-input; or &v4l2-output;, where each bit represents
391 the index number, starting at zero, of one audio input or output.</para>
393 <para>To learn about the number and attributes of the
394 available inputs and outputs applications can enumerate them with the
395 &VIDIOC-ENUMAUDIO; and &VIDIOC-ENUMAUDOUT; ioctl, respectively. The
396 &v4l2-audio; returned by the <constant>VIDIOC_ENUMAUDIO</constant> ioctl
397 also contains signal status information applicable when the current
398 audio input is queried.</para>
400 <para>The &VIDIOC-G-AUDIO; and &VIDIOC-G-AUDOUT; ioctl report
401 the current audio input and output, respectively. Note that, unlike
402 &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; these ioctls return a structure
403 as <constant>VIDIOC_ENUMAUDIO</constant> and
404 <constant>VIDIOC_ENUMAUDOUT</constant> do, not just an index.</para>
406 <para>To select an audio input and change its properties
407 applications call the &VIDIOC-S-AUDIO; ioctl. To select an audio
408 output (which presently has no changeable properties) applications
409 call the &VIDIOC-S-AUDOUT; ioctl.</para>
411 <para>Drivers must implement all input ioctls when the device
412 has one or more inputs, all output ioctls when the device has one
413 or more outputs. When the device has any audio inputs or outputs the
414 driver must set the <constant>V4L2_CAP_AUDIO</constant> flag in the
415 &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl.</para>
418 <title>Information about the current audio input</title>
423 memset (&audio, 0, sizeof (audio));
425 if (-1 == ioctl (fd, &VIDIOC-G-AUDIO;, &audio)) {
426 perror ("VIDIOC_G_AUDIO");
430 printf ("Current input: %s\n", audio.name);
435 <title>Switching to the first audio input</title>
440 memset (&audio, 0, sizeof (audio)); /* clear audio.mode, audio.reserved */
444 if (-1 == ioctl (fd, &VIDIOC-S-AUDIO;, &audio)) {
445 perror ("VIDIOC_S_AUDIO");
453 <title>Tuners and Modulators</title>
456 <title>Tuners</title>
458 <para>Video input devices can have one or more tuners
459 demodulating a RF signal. Each tuner is associated with one or more
460 video inputs, depending on the number of RF connectors on the tuner.
461 The <structfield>type</structfield> field of the respective
462 &v4l2-input; returned by the &VIDIOC-ENUMINPUT; ioctl is set to
463 <constant>V4L2_INPUT_TYPE_TUNER</constant> and its
464 <structfield>tuner</structfield> field contains the index number of
467 <para>Radio input devices have exactly one tuner with index zero, no
470 <para>To query and change tuner properties applications use the
471 &VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctl, respectively. The
472 &v4l2-tuner; returned by <constant>VIDIOC_G_TUNER</constant> also
473 contains signal status information applicable when the tuner of the
474 current video or radio input is queried. Note that
475 <constant>VIDIOC_S_TUNER</constant> does not switch the current tuner,
476 when there is more than one at all. The tuner is solely determined by
477 the current video input. Drivers must support both ioctls and set the
478 <constant>V4L2_CAP_TUNER</constant> flag in the &v4l2-capability;
479 returned by the &VIDIOC-QUERYCAP; ioctl when the device has one or
484 <title>Modulators</title>
486 <para>Video output devices can have one or more modulators, uh,
487 modulating a video signal for radiation or connection to the antenna
488 input of a TV set or video recorder. Each modulator is associated with
489 one or more video outputs, depending on the number of RF connectors on
490 the modulator. The <structfield>type</structfield> field of the
491 respective &v4l2-output; returned by the &VIDIOC-ENUMOUTPUT; ioctl is
492 set to <constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> and its
493 <structfield>modulator</structfield> field contains the index number
494 of the modulator.</para>
496 <para>Radio output devices have exactly one modulator with index
497 zero, no video outputs.</para>
499 <para>A video or radio device cannot support both a tuner and a
500 modulator. Two separate device nodes will have to be used for such
501 hardware, one that supports the tuner functionality and one that supports
502 the modulator functionality. The reason is a limitation with the
503 &VIDIOC-S-FREQUENCY; ioctl where you cannot specify whether the frequency
504 is for a tuner or a modulator.</para>
506 <para>To query and change modulator properties applications use
507 the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that
508 <constant>VIDIOC_S_MODULATOR</constant> does not switch the current
509 modulator, when there is more than one at all. The modulator is solely
510 determined by the current video output. Drivers must support both
511 ioctls and set the <constant>V4L2_CAP_MODULATOR</constant> flag in
512 the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl when the
513 device has one or more modulators.</para>
517 <title>Radio Frequency</title>
519 <para>To get and set the tuner or modulator radio frequency
520 applications use the &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY;
521 ioctl which both take a pointer to a &v4l2-frequency;. These ioctls
522 are used for TV and radio devices alike. Drivers must support both
523 ioctls when the tuner or modulator ioctls are supported, or
524 when the device is a radio device.</para>
528 <section id="standard">
529 <title>Video Standards</title>
531 <para>Video devices typically support one or more different video
532 standards or variations of standards. Each video input and output may
533 support another set of standards. This set is reported by the
534 <structfield>std</structfield> field of &v4l2-input; and
535 &v4l2-output; returned by the &VIDIOC-ENUMINPUT; and
536 &VIDIOC-ENUMOUTPUT; ioctl, respectively.</para>
538 <para>V4L2 defines one bit for each analog video standard
539 currently in use worldwide, and sets aside bits for driver defined
540 standards, ⪚ hybrid standards to watch NTSC video tapes on PAL TVs
541 and vice versa. Applications can use the predefined bits to select a
542 particular standard, although presenting the user a menu of supported
543 standards is preferred. To enumerate and query the attributes of the
544 supported standards applications use the &VIDIOC-ENUMSTD; ioctl.</para>
546 <para>Many of the defined standards are actually just variations
547 of a few major standards. The hardware may in fact not distinguish
548 between them, or do so internal and switch automatically. Therefore
549 enumerated standards also contain sets of one or more standard
552 <para>Assume a hypothetic tuner capable of demodulating B/PAL,
553 G/PAL and I/PAL signals. The first enumerated standard is a set of B
554 and G/PAL, switched automatically depending on the selected radio
555 frequency in UHF or VHF band. Enumeration gives a "PAL-B/G" or "PAL-I"
556 choice. Similar a Composite input may collapse standards, enumerating
557 "PAL-B/G/H/I", "NTSC-M" and "SECAM-D/K".<footnote>
558 <para>Some users are already confused by technical terms PAL,
559 NTSC and SECAM. There is no point asking them to distinguish between
560 B, G, D, or K when the software or hardware can do that
561 automatically.</para>
564 <para>To query and select the standard used by the current video
565 input or output applications call the &VIDIOC-G-STD; and
566 &VIDIOC-S-STD; ioctl, respectively. The <emphasis>received</emphasis>
567 standard 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>
568 <para>An alternative to the current scheme is to use pointers
569 to indices as arguments of <constant>VIDIOC_G_STD</constant> and
570 <constant>VIDIOC_S_STD</constant>, the &v4l2-input; and
571 &v4l2-output; <structfield>std</structfield> field would be a set of
572 indices like <structfield>audioset</structfield>.</para>
573 <para>Indices are consistent with the rest of the API
574 and identify the standard unambiguously. In the present scheme of
575 things an enumerated standard is looked up by &v4l2-std-id;. Now the
576 standards supported by the inputs of a device can overlap. Just
577 assume the tuner and composite input in the example above both
578 exist on a device. An enumeration of "PAL-B/G", "PAL-H/I" suggests
579 a choice which does not exist. We cannot merge or omit sets, because
580 applications would be unable to find the standards reported by
581 <constant>VIDIOC_G_STD</constant>. That leaves separate enumerations
582 for each input. Also selecting a standard by &v4l2-std-id; can be
583 ambiguous. Advantage of this method is that applications need not
584 identify the standard indirectly, after enumerating.</para><para>So in
585 summary, the lookup itself is unavoidable. The difference is only
586 whether the lookup is necessary to find an enumerated standard or to
587 switch to a standard by &v4l2-std-id;.</para>
588 </footnote> Drivers must implement all video standard ioctls
589 when the device has one or more video inputs or outputs.</para>
591 <para>Special rules apply to USB cameras where the notion of video
592 standards makes little sense. More generally any capture device,
593 output devices accordingly, which is <itemizedlist>
595 <para>incapable of capturing fields or frames at the nominal
596 rate of the video standard, or</para>
599 <para>where <link linkend="buffer">timestamps</link> refer
600 to the instant the field or frame was received by the driver, not the
601 capture time, or</para>
604 <para>where <link linkend="buffer">sequence numbers</link>
605 refer to the frames received by the driver, not the captured
608 </itemizedlist> Here the driver shall set the
609 <structfield>std</structfield> field of &v4l2-input; and &v4l2-output;
610 to zero, the <constant>VIDIOC_G_STD</constant>,
611 <constant>VIDIOC_S_STD</constant>,
612 <constant>VIDIOC_QUERYSTD</constant> and
613 <constant>VIDIOC_ENUMSTD</constant> ioctls shall return the
615 <para>See <xref linkend="buffer" /> for a rationale. Probably
616 even USB cameras follow some well known video standard. It might have
617 been better to explicitly indicate elsewhere if a device cannot live
618 up to normal expectations, instead of this exception.</para>
622 <title>Information about the current video standard</title>
625 &v4l2-std-id; std_id;
626 &v4l2-standard; standard;
628 if (-1 == ioctl (fd, &VIDIOC-G-STD;, &std_id)) {
629 /* Note when VIDIOC_ENUMSTD always returns EINVAL this
630 is no video device or it falls under the USB exception,
631 and VIDIOC_G_STD returning EINVAL is no error. */
633 perror ("VIDIOC_G_STD");
637 memset (&standard, 0, sizeof (standard));
640 while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &standard)) {
641 if (standard.id & std_id) {
642 printf ("Current video standard: %s\n", standard.name);
649 /* EINVAL indicates the end of the enumeration, which cannot be
650 empty unless this device falls under the USB exception. */
652 if (errno == EINVAL || standard.index == 0) {
653 perror ("VIDIOC_ENUMSTD");
660 <title>Listing the video standards supported by the current
665 &v4l2-standard; standard;
667 memset (&input, 0, sizeof (input));
669 if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &input.index)) {
670 perror ("VIDIOC_G_INPUT");
674 if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &input)) {
675 perror ("VIDIOC_ENUM_INPUT");
679 printf ("Current input %s supports:\n", input.name);
681 memset (&standard, 0, sizeof (standard));
684 while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &standard)) {
685 if (standard.id & input.std)
686 printf ("%s\n", standard.name);
691 /* EINVAL indicates the end of the enumeration, which cannot be
692 empty unless this device falls under the USB exception. */
694 if (errno != EINVAL || standard.index == 0) {
695 perror ("VIDIOC_ENUMSTD");
702 <title>Selecting a new video standard</title>
706 &v4l2-std-id; std_id;
708 memset (&input, 0, sizeof (input));
710 if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &input.index)) {
711 perror ("VIDIOC_G_INPUT");
715 if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &input)) {
716 perror ("VIDIOC_ENUM_INPUT");
720 if (0 == (input.std & V4L2_STD_PAL_BG)) {
721 fprintf (stderr, "Oops. B/G PAL is not supported.\n");
725 /* Note this is also supposed to work when only B
726 <emphasis>or</emphasis> G/PAL is supported. */
728 std_id = V4L2_STD_PAL_BG;
730 if (-1 == ioctl (fd, &VIDIOC-S-STD;, &std_id)) {
731 perror ("VIDIOC_S_STD");
737 <section id="dv-timings">
738 <title>Digital Video (DV) Timings</title>
740 The video standards discussed so far have been dealing with Analog TV and the
741 corresponding video timings. Today there are many more different hardware interfaces
742 such as High Definition TV interfaces (HDMI), VGA, DVI connectors etc., that carry
743 video signals and there is a need to extend the API to select the video timings
744 for these interfaces. Since it is not possible to extend the &v4l2-std-id; due to
745 the limited bits available, a new set of IOCTLs was added to set/get video timings at
746 the input and output: </para><itemizedlist>
748 <para>DV Timings: This will allow applications to define detailed
749 video timings for the interface. This includes parameters such as width, height,
750 polarities, frontporch, backporch etc. The <filename>linux/v4l2-dv-timings.h</filename>
751 header can be used to get the timings of the formats in the <xref linkend="cea861" /> and
752 <xref linkend="vesadmt" /> standards.
756 <para>DV Presets: Digital Video (DV) presets (<emphasis role="bold">deprecated</emphasis>).
757 These are IDs representing a
758 video timing at the input/output. Presets are pre-defined timings implemented
759 by the hardware according to video standards. A __u32 data type is used to represent
760 a preset unlike the bit mask that is used in &v4l2-std-id; allowing future extensions
761 to support as many different presets as needed. This API is deprecated in favor of the DV Timings
765 <para>To enumerate and query the attributes of the DV timings supported by a device,
766 applications use the &VIDIOC-ENUM-DV-TIMINGS; and &VIDIOC-DV-TIMINGS-CAP; ioctls.
767 To set DV timings for the device, applications use the
768 &VIDIOC-S-DV-TIMINGS; ioctl and to get current DV timings they use the
769 &VIDIOC-G-DV-TIMINGS; ioctl. To detect the DV timings as seen by the video receiver applications
770 use the &VIDIOC-QUERY-DV-TIMINGS; ioctl.</para>
771 <para>To enumerate and query the attributes of DV presets supported by a device,
772 applications use the &VIDIOC-ENUM-DV-PRESETS; ioctl. To get the current DV preset,
773 applications use the &VIDIOC-G-DV-PRESET; ioctl and to set a preset they use the
774 &VIDIOC-S-DV-PRESET; ioctl. To detect the preset as seen by the video receiver applications
775 use the &VIDIOC-QUERY-DV-PRESET; ioctl.</para>
776 <para>Applications can make use of the <xref linkend="input-capabilities" /> and
777 <xref linkend="output-capabilities"/> flags to decide what ioctls are available to set the
778 video timings for the device.</para>
783 <section id="format">
784 <title>Data Formats</title>
787 <title>Data Format Negotiation</title>
789 <para>Different devices exchange different kinds of data with
790 applications, for example video images, raw or sliced VBI data, RDS
791 datagrams. Even within one kind many different formats are possible,
792 in particular an abundance of image formats. Although drivers must
793 provide a default and the selection persists across closing and
794 reopening a device, applications should always negotiate a data format
795 before engaging in data exchange. Negotiation means the application
796 asks for a particular format and the driver selects and reports the
797 best the hardware can do to satisfy the request. Of course
798 applications can also just query the current selection.</para>
800 <para>A single mechanism exists to negotiate all data formats
801 using the aggregate &v4l2-format; and the &VIDIOC-G-FMT; and
802 &VIDIOC-S-FMT; ioctls. Additionally the &VIDIOC-TRY-FMT; ioctl can be
803 used to examine what the hardware <emphasis>could</emphasis> do,
804 without actually selecting a new data format. The data formats
805 supported by the V4L2 API are covered in the respective device section
806 in <xref linkend="devices" />. For a closer look at image formats see
807 <xref linkend="pixfmt" />.</para>
809 <para>The <constant>VIDIOC_S_FMT</constant> ioctl is a major
810 turning-point in the initialization sequence. Prior to this point
811 multiple panel applications can access the same device concurrently to
812 select the current input, change controls or modify other properties.
813 The first <constant>VIDIOC_S_FMT</constant> assigns a logical stream
814 (video data, VBI data etc.) exclusively to one file descriptor.</para>
816 <para>Exclusive means no other application, more precisely no
817 other file descriptor, can grab this stream or change device
818 properties inconsistent with the negotiated parameters. A video
819 standard change for example, when the new standard uses a different
820 number of scan lines, can invalidate the selected image format.
821 Therefore only the file descriptor owning the stream can make
822 invalidating changes. Accordingly multiple file descriptors which
823 grabbed different logical streams prevent each other from interfering
824 with their settings. When for example video overlay is about to start
825 or already in progress, simultaneous video capturing may be restricted
826 to the same cropping and image size.</para>
828 <para>When applications omit the
829 <constant>VIDIOC_S_FMT</constant> ioctl its locking side effects are
830 implied by the next step, the selection of an I/O method with the
831 &VIDIOC-REQBUFS; ioctl or implicit with the first &func-read; or
832 &func-write; call.</para>
834 <para>Generally only one logical stream can be assigned to a
835 file descriptor, the exception being drivers permitting simultaneous
836 video capturing and overlay using the same file descriptor for
837 compatibility with V4L and earlier versions of V4L2. Switching the
838 logical stream or returning into "panel mode" is possible by closing
839 and reopening the device. Drivers <emphasis>may</emphasis> support a
840 switch using <constant>VIDIOC_S_FMT</constant>.</para>
842 <para>All drivers exchanging data with
843 applications must support the <constant>VIDIOC_G_FMT</constant> and
844 <constant>VIDIOC_S_FMT</constant> ioctl. Implementation of the
845 <constant>VIDIOC_TRY_FMT</constant> is highly recommended but
850 <title>Image Format Enumeration</title>
852 <para>Apart of the generic format negotiation functions
853 a special ioctl to enumerate all image formats supported by video
854 capture, overlay or output devices is available.<footnote>
855 <para>Enumerating formats an application has no a-priori
856 knowledge of (otherwise it could explicitly ask for them and need not
857 enumerate) seems useless, but there are applications serving as proxy
858 between drivers and the actual video applications for which this is
862 <para>The &VIDIOC-ENUM-FMT; ioctl must be supported
863 by all drivers exchanging image data with applications.</para>
866 <para>Drivers are not supposed to convert image formats in
867 kernel space. They must enumerate only formats directly supported by
868 the hardware. If necessary driver writers should publish an example
869 conversion routine or library for integration into applications.</para>
877 <title>Image Cropping, Insertion and Scaling</title>
879 <para>Some video capture devices can sample a subsection of the
880 picture and shrink or enlarge it to an image of arbitrary size. We
881 call these abilities cropping and scaling. Some video output devices
882 can scale an image up or down and insert it at an arbitrary scan line
883 and horizontal offset into a video signal.</para>
885 <para>Applications can use the following API to select an area in
886 the video signal, query the default area and the hardware limits.
887 <emphasis>Despite their name, the &VIDIOC-CROPCAP;, &VIDIOC-G-CROP;
888 and &VIDIOC-S-CROP; ioctls apply to input as well as output
889 devices.</emphasis></para>
891 <para>Scaling requires a source and a target. On a video capture
892 or overlay device the source is the video signal, and the cropping
893 ioctls determine the area actually sampled. The target are images
894 read by the application or overlaid onto the graphics screen. Their
895 size (and position for an overlay) is negotiated with the
896 &VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls.</para>
898 <para>On a video output device the source are the images passed in
899 by the application, and their size is again negotiated with the
900 <constant>VIDIOC_G/S_FMT</constant> ioctls, or may be encoded in a
901 compressed video stream. The target is the video signal, and the
902 cropping ioctls determine the area where the images are
905 <para>Source and target rectangles are defined even if the device
906 does not support scaling or the <constant>VIDIOC_G/S_CROP</constant>
907 ioctls. Their size (and position where applicable) will be fixed in
908 this case. <emphasis>All capture and output device must support the
909 <constant>VIDIOC_CROPCAP</constant> ioctl such that applications can
910 determine if scaling takes place.</emphasis></para>
913 <title>Cropping Structures</title>
915 <figure id="crop-scale">
916 <title>Image Cropping, Insertion and Scaling</title>
919 <imagedata fileref="crop.pdf" format="PS" />
922 <imagedata fileref="crop.gif" format="GIF" />
925 <phrase>The cropping, insertion and scaling process</phrase>
930 <para>For capture devices the coordinates of the top left
931 corner, width and height of the area which can be sampled is given by
932 the <structfield>bounds</structfield> substructure of the
933 &v4l2-cropcap; returned by the <constant>VIDIOC_CROPCAP</constant>
934 ioctl. To support a wide range of hardware this specification does not
935 define an origin or units. However by convention drivers should
936 horizontally count unscaled samples relative to 0H (the leading edge
937 of the horizontal sync pulse, see <xref linkend="vbi-hsync" />).
938 Vertically ITU-R line
939 numbers of the first field (<xref linkend="vbi-525" />, <xref
940 linkend="vbi-625" />), multiplied by two if the driver can capture both
943 <para>The top left corner, width and height of the source
944 rectangle, that is the area actually sampled, is given by &v4l2-crop;
945 using the same coordinate system as &v4l2-cropcap;. Applications can
946 use the <constant>VIDIOC_G_CROP</constant> and
947 <constant>VIDIOC_S_CROP</constant> ioctls to get and set this
948 rectangle. It must lie completely within the capture boundaries and
949 the driver may further adjust the requested size and/or position
950 according to hardware limitations.</para>
952 <para>Each capture device has a default source rectangle, given
953 by the <structfield>defrect</structfield> substructure of
954 &v4l2-cropcap;. The center of this rectangle shall align with the
955 center of the active picture area of the video signal, and cover what
956 the driver writer considers the complete picture. Drivers shall reset
957 the source rectangle to the default when the driver is first loaded,
958 but not later.</para>
960 <para>For output devices these structures and ioctls are used
961 accordingly, defining the <emphasis>target</emphasis> rectangle where
962 the images will be inserted into the video signal.</para>
967 <title>Scaling Adjustments</title>
969 <para>Video hardware can have various cropping, insertion and
970 scaling limitations. It may only scale up or down, support only
971 discrete scaling factors, or have different scaling abilities in
972 horizontal and vertical direction. Also it may not support scaling at
973 all. At the same time the &v4l2-crop; rectangle may have to be
974 aligned, and both the source and target rectangles may have arbitrary
975 upper and lower size limits. In particular the maximum
976 <structfield>width</structfield> and <structfield>height</structfield>
977 in &v4l2-crop; may be smaller than the
978 &v4l2-cropcap;.<structfield>bounds</structfield> area. Therefore, as
979 usual, drivers are expected to adjust the requested parameters and
980 return the actual values selected.</para>
982 <para>Applications can change the source or the target rectangle
983 first, as they may prefer a particular image size or a certain area in
984 the video signal. If the driver has to adjust both to satisfy hardware
985 limitations, the last requested rectangle shall take priority, and the
986 driver should preferably adjust the opposite one. The &VIDIOC-TRY-FMT;
987 ioctl however shall not change the driver state and therefore only
988 adjust the requested rectangle.</para>
990 <para>Suppose scaling on a video capture device is restricted to
991 a factor 1:1 or 2:1 in either direction and the target image size must
992 be a multiple of 16 × 16 pixels. The source cropping
993 rectangle is set to defaults, which are also the upper limit in this
994 example, of 640 × 400 pixels at offset 0, 0. An
995 application requests an image size of 300 × 225
996 pixels, assuming video will be scaled down from the "full picture"
997 accordingly. The driver sets the image size to the closest possible
998 values 304 × 224, then chooses the cropping rectangle
999 closest to the requested size, that is 608 × 224
1000 (224 × 2:1 would exceed the limit 400). The offset
1001 0, 0 is still valid, thus unmodified. Given the default cropping
1002 rectangle reported by <constant>VIDIOC_CROPCAP</constant> the
1003 application can easily propose another offset to center the cropping
1006 <para>Now the application may insist on covering an area using a
1007 picture aspect ratio closer to the original request, so it asks for a
1008 cropping rectangle of 608 × 456 pixels. The present
1009 scaling factors limit cropping to 640 × 384, so the
1010 driver returns the cropping size 608 × 384 and adjusts
1011 the image size to closest possible 304 × 192.</para>
1016 <title>Examples</title>
1018 <para>Source and target rectangles shall remain unchanged across
1019 closing and reopening a device, such that piping data into or out of a
1020 device will work without special preparations. More advanced
1021 applications should ensure the parameters are suitable before starting
1025 <title>Resetting the cropping parameters</title>
1027 <para>(A video capture device is assumed; change
1028 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other
1032 &v4l2-cropcap; cropcap;
1035 memset (&cropcap, 0, sizeof (cropcap));
1036 cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1038 if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &cropcap)) {
1039 perror ("VIDIOC_CROPCAP");
1040 exit (EXIT_FAILURE);
1043 memset (&crop, 0, sizeof (crop));
1044 crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1045 crop.c = cropcap.defrect;
1047 /* Ignore if cropping is not supported (EINVAL). */
1049 if (-1 == ioctl (fd, &VIDIOC-S-CROP;, &crop)
1050 && errno != EINVAL) {
1051 perror ("VIDIOC_S_CROP");
1052 exit (EXIT_FAILURE);
1058 <title>Simple downscaling</title>
1060 <para>(A video capture device is assumed.)</para>
1063 &v4l2-cropcap; cropcap;
1064 &v4l2-format; format;
1066 reset_cropping_parameters ();
1068 /* Scale down to 1/4 size of full picture. */
1070 memset (&format, 0, sizeof (format)); /* defaults */
1072 format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1074 format.fmt.pix.width = cropcap.defrect.width >> 1;
1075 format.fmt.pix.height = cropcap.defrect.height >> 1;
1076 format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
1078 if (-1 == ioctl (fd, &VIDIOC-S-FMT;, &format)) {
1079 perror ("VIDIOC_S_FORMAT");
1080 exit (EXIT_FAILURE);
1083 /* We could check the actual image size now, the actual scaling factor
1084 or if the driver can scale at all. */
1089 <title>Selecting an output area</title>
1092 &v4l2-cropcap; cropcap;
1095 memset (&cropcap, 0, sizeof (cropcap));
1096 cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
1098 if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &cropcap)) {
1099 perror ("VIDIOC_CROPCAP");
1100 exit (EXIT_FAILURE);
1103 memset (&crop, 0, sizeof (crop));
1105 crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
1106 crop.c = cropcap.defrect;
1108 /* Scale the width and height to 50 % of their original size
1109 and center the output. */
1113 crop.c.left += crop.c.width / 2;
1114 crop.c.top += crop.c.height / 2;
1116 /* Ignore if cropping is not supported (EINVAL). */
1118 if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
1119 && errno != EINVAL) {
1120 perror ("VIDIOC_S_CROP");
1121 exit (EXIT_FAILURE);
1127 <title>Current scaling factor and pixel aspect</title>
1129 <para>(A video capture device is assumed.)</para>
1132 &v4l2-cropcap; cropcap;
1134 &v4l2-format; format;
1135 double hscale, vscale;
1137 int dwidth, dheight;
1139 memset (&cropcap, 0, sizeof (cropcap));
1140 cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1142 if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &cropcap)) {
1143 perror ("VIDIOC_CROPCAP");
1144 exit (EXIT_FAILURE);
1147 memset (&crop, 0, sizeof (crop));
1148 crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1150 if (-1 == ioctl (fd, &VIDIOC-G-CROP;, &crop)) {
1151 if (errno != EINVAL) {
1152 perror ("VIDIOC_G_CROP");
1153 exit (EXIT_FAILURE);
1156 /* Cropping not supported. */
1157 crop.c = cropcap.defrect;
1160 memset (&format, 0, sizeof (format));
1161 format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1163 if (-1 == ioctl (fd, &VIDIOC-G-FMT;, &format)) {
1164 perror ("VIDIOC_G_FMT");
1165 exit (EXIT_FAILURE);
1168 /* The scaling applied by the driver. */
1170 hscale = format.fmt.pix.width / (double) crop.c.width;
1171 vscale = format.fmt.pix.height / (double) crop.c.height;
1173 aspect = cropcap.pixelaspect.numerator /
1174 (double) cropcap.pixelaspect.denominator;
1175 aspect = aspect * hscale / vscale;
1177 /* Devices following ITU-R BT.601 do not capture
1178 square pixels. For playback on a computer monitor
1179 we should scale the images to this size. */
1181 dwidth = format.fmt.pix.width / aspect;
1182 dheight = format.fmt.pix.height;
1190 <section id="streaming-par">
1191 <title>Streaming Parameters</title>
1193 <para>Streaming parameters are intended to optimize the video
1194 capture process as well as I/O. Presently applications can request a
1195 high quality capture mode with the &VIDIOC-S-PARM; ioctl.</para>
1197 <para>The current video standard determines a nominal number of
1198 frames per second. If less than this number of frames is to be
1199 captured or output, applications can request frame skipping or
1200 duplicating on the driver side. This is especially useful when using
1201 the &func-read; or &func-write;, which are not augmented by timestamps
1202 or sequence counters, and to avoid unnecessary data copying.</para>
1204 <para>Finally these ioctls can be used to determine the number of
1205 buffers used internally by a driver in read/write mode. For
1206 implications see the section discussing the &func-read;
1209 <para>To get and set the streaming parameters applications call
1210 the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; ioctl, respectively. They take
1211 a pointer to a &v4l2-streamparm;, which contains a union holding
1212 separate parameters for input and output devices.</para>
1214 <para>These ioctls are optional, drivers need not implement
1215 them. If so, they return the &EINVAL;.</para>