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 recomended 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. Other features can be queried
240 by calling the respective ioctl, for example &VIDIOC-ENUMINPUT;
241 to learn about the number, types and names of video connectors on the
242 device. Although abstraction is a major objective of this API, the
243 ioctl also allows driver specific applications to reliable identify
246 <para>All V4L2 drivers must support
247 <constant>VIDIOC_QUERYCAP
</constant>. Applications should always call
248 this ioctl after opening the device.
</para>
251 <section id=
"app-pri">
252 <title>Application Priority
</title>
254 <para>When multiple applications share a device it may be
255 desirable to assign them different priorities. Contrary to the
256 traditional
"rm -rf /" school of thought a video recording application
257 could for example block other applications from changing video
258 controls or switching the current TV channel. Another objective is to
259 permit low priority applications working in background, which can be
260 preempted by user controlled applications and automatically regain
261 control of the device at a later time.
</para>
263 <para>Since these features cannot be implemented entirely in user
264 space V4L2 defines the &VIDIOC-G-PRIORITY; and &VIDIOC-S-PRIORITY;
265 ioctls to request and query the access priority associate with a file
266 descriptor. Opening a device assigns a medium priority, compatible
267 with earlier versions of V4L2 and drivers not supporting these ioctls.
268 Applications requiring a different priority will usually call
269 <constant>VIDIOC_S_PRIORITY
</constant> after verifying the device with
270 the &VIDIOC-QUERYCAP; ioctl.
</para>
272 <para>Ioctls changing driver properties, such as &VIDIOC-S-INPUT;,
273 return an
&EBUSY; after another application obtained higher priority.
274 An event mechanism to notify applications about asynchronous property
275 changes has been proposed but not added yet.
</para>
279 <title>Video Inputs and Outputs
</title>
281 <para>Video inputs and outputs are physical connectors of a
282 device. These can be for example RF connectors (antenna/cable), CVBS
283 a.k.a. Composite Video, S-Video or RGB connectors. Only video and VBI
284 capture devices have inputs, output devices have outputs, at least one
285 each. Radio devices have no video inputs or outputs.
</para>
287 <para>To learn about the number and attributes of the
288 available 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>
291 ioctl also contains signal status information applicable when the
292 current video input is queried.
</para>
294 <para>The &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; ioctl return the
295 index of the current video input or output. To select a different
296 input or output applications call the &VIDIOC-S-INPUT; and
297 &VIDIOC-S-OUTPUT; ioctl. Drivers must implement all the input ioctls
298 when the device has one or more inputs, all the output ioctls when the
299 device has one or more outputs.
</para>
303 <title>Input and output enumeration is the root of most device properties.</title>
306 <imagedata fileref="links.pdf" format="ps" />
309 <imagedata fileref="links.gif" format="gif" />
312 <phrase>Links between various device property structures.</phrase>
319 <title>Information about the current video input
</title>
325 if (-
1 == ioctl (fd, &VIDIOC-G-INPUT;,
&index)) {
326 perror (
"VIDIOC_G_INPUT");
330 memset (
&input,
0, sizeof (input));
333 if (-
1 == ioctl (fd, &VIDIOC-ENUMINPUT;,
&input)) {
334 perror (
"VIDIOC_ENUMINPUT");
338 printf (
"Current input: %s\n", input.name);
343 <title>Switching to the first video input
</title>
350 if (-
1 == ioctl (fd, &VIDIOC-S-INPUT;,
&index)) {
351 perror (
"VIDIOC_S_INPUT");
359 <title>Audio Inputs and Outputs
</title>
361 <para>Audio inputs and outputs are physical connectors of a
362 device. Video capture devices have inputs, output devices have
363 outputs, zero or more each. Radio devices have no audio inputs or
364 outputs. They have exactly one tuner which in fact
365 <emphasis>is
</emphasis> an audio source, but this API associates
366 tuners with video inputs or outputs only, and radio devices have
367 none of these.
<footnote>
368 <para>Actually &v4l2-audio; ought to have a
369 <structfield>tuner
</structfield> field like &v4l2-input;, not only
370 making the API more consistent but also permitting radio devices with
371 multiple tuners.
</para>
372 </footnote> A connector on a TV card to loop back the received
373 audio signal to a sound card is not considered an audio output.
</para>
375 <para>Audio and video inputs and outputs are associated. Selecting
376 a video source also selects an audio source. This is most evident when
377 the video and audio source is a tuner. Further audio connectors can
378 combine with more than one video input or output. Assumed two
379 composite video inputs and two audio inputs exist, there may be up to
380 four valid combinations. The relation of video and audio connectors
381 is defined in the
<structfield>audioset
</structfield> field of the
382 respective &v4l2-input; or &v4l2-output;, where each bit represents
383 the index number, starting at zero, of one audio input or output.
</para>
385 <para>To learn about the number and attributes of the
386 available 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
389 also contains signal status information applicable when the current
390 audio input is queried.
</para>
392 <para>The &VIDIOC-G-AUDIO; and &VIDIOC-G-AUDOUT; ioctl report
393 the current audio input and output, respectively. Note that, unlike
394 &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; these ioctls return a structure
395 as
<constant>VIDIOC_ENUMAUDIO
</constant> and
396 <constant>VIDIOC_ENUMAUDOUT
</constant> do, not just an index.
</para>
398 <para>To select an audio input and change its properties
399 applications call the &VIDIOC-S-AUDIO; ioctl. To select an audio
400 output (which presently has no changeable properties) applications
401 call the &VIDIOC-S-AUDOUT; ioctl.
</para>
403 <para>Drivers must implement all input ioctls when the device
404 has one or more inputs, all output ioctls when the device has one
405 or more outputs. When the device has any audio inputs or outputs the
406 driver must set the
<constant>V4L2_CAP_AUDIO
</constant> flag in the
407 &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl.
</para>
410 <title>Information about the current audio input
</title>
415 memset (
&audio,
0, sizeof (audio));
417 if (-
1 == ioctl (fd, &VIDIOC-G-AUDIO;,
&audio)) {
418 perror (
"VIDIOC_G_AUDIO");
422 printf (
"Current input: %s\n", audio.name);
427 <title>Switching to the first audio input
</title>
432 memset (
&audio,
0, sizeof (audio)); /* clear audio.mode, audio.reserved */
436 if (-
1 == ioctl (fd, &VIDIOC-S-AUDIO;,
&audio)) {
437 perror (
"VIDIOC_S_AUDIO");
445 <title>Tuners and Modulators
</title>
448 <title>Tuners
</title>
450 <para>Video input devices can have one or more tuners
451 demodulating a RF signal. Each tuner is associated with one or more
452 video inputs, depending on the number of RF connectors on the tuner.
453 The
<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
459 <para>Radio devices have exactly one tuner with index zero, no
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
465 contains signal status information applicable when the tuner of the
466 current video input, or a radio tuner is queried. Note that
467 <constant>VIDIOC_S_TUNER
</constant> does not switch the current tuner,
468 when there is more than one at all. The tuner is solely determined by
469 the current video input. Drivers must support both ioctls and set the
470 <constant>V4L2_CAP_TUNER
</constant> flag in the &v4l2-capability;
471 returned by the &VIDIOC-QUERYCAP; ioctl when the device has one or
476 <title>Modulators
</title>
478 <para>Video output devices can have one or more modulators, uh,
479 modulating a video signal for radiation or connection to the antenna
480 input of a TV set or video recorder. Each modulator is associated with
481 one or more video outputs, depending on the number of RF connectors on
482 the modulator. The
<structfield>type
</structfield> field of the
483 respective &v4l2-output; returned by the &VIDIOC-ENUMOUTPUT; ioctl is
484 set to
<constant>V4L2_OUTPUT_TYPE_MODULATOR
</constant> and its
485 <structfield>modulator
</structfield> field contains the index number
486 of the modulator. This specification does not define radio output
489 <para>To query and change modulator properties applications use
490 the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that
491 <constant>VIDIOC_S_MODULATOR
</constant> does not switch the current
492 modulator, when there is more than one at all. The modulator is solely
493 determined by the current video output. Drivers must support both
494 ioctls and set the
<constant>V4L2_CAP_MODULATOR
</constant> flag in
495 the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl when the
496 device has one or more modulators.
</para>
500 <title>Radio Frequency
</title>
502 <para>To get and set the tuner or modulator radio frequency
503 applications use the &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY;
504 ioctl which both take a pointer to a &v4l2-frequency;. These ioctls
505 are used for TV and radio devices alike. Drivers must support both
506 ioctls when the tuner or modulator ioctls are supported, or
507 when the device is a radio device.
</para>
511 <title>Satellite Receivers
</title>
513 <para>To be discussed. See also
<!-- private discussions of
514 Peter Schlaf, BD & MHS on 23 Jun 1999 ff., subject "v4l2 and satellit" and -->
515 proposals by Peter Schlaf, video4linux-list@redhat.com on
23 Oct
2002,
516 subject:
"Re: [V4L] Re: v4l2 api".
</para>
520 <section id=
"standard">
521 <title>Video Standards
</title>
523 <para>Video devices typically support one or more different video
524 standards or variations of standards. Each video input and output may
525 support another set of standards. This set is reported by the
526 <structfield>std
</structfield> field of &v4l2-input; and
527 &v4l2-output; returned by the &VIDIOC-ENUMINPUT; and
528 &VIDIOC-ENUMOUTPUT; ioctl, respectively.
</para>
530 <para>V4L2 defines one bit for each analog video standard
531 currently in use worldwide, and sets aside bits for driver defined
532 standards,
⪚ hybrid standards to watch NTSC video tapes on PAL TVs
533 and vice versa. Applications can use the predefined bits to select a
534 particular standard, although presenting the user a menu of supported
535 standards is preferred. To enumerate and query the attributes of the
536 supported standards applications use the &VIDIOC-ENUMSTD; ioctl.
</para>
538 <para>Many of the defined standards are actually just variations
539 of a few major standards. The hardware may in fact not distinguish
540 between them, or do so internal and switch automatically. Therefore
541 enumerated standards also contain sets of one or more standard
544 <para>Assume a hypothetic tuner capable of demodulating B/PAL,
545 G/PAL and I/PAL signals. The first enumerated standard is a set of B
546 and G/PAL, switched automatically depending on the selected radio
547 frequency in UHF or VHF band. Enumeration gives a
"PAL-B/G" or
"PAL-I"
548 choice. Similar a Composite input may collapse standards, enumerating
549 "PAL-B/G/H/I",
"NTSC-M" and
"SECAM-D/K".
<footnote>
550 <para>Some users are already confused by technical terms PAL,
551 NTSC and SECAM. There is no point asking them to distinguish between
552 B, G, D, or K when the software or hardware can do that
553 automatically.
</para>
556 <para>To query and select the standard used by the current video
557 input or output applications call the &VIDIOC-G-STD; and
558 &VIDIOC-S-STD; ioctl, respectively. The
<emphasis>received
</emphasis>
559 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>
560 <para>An alternative to the current scheme is to use pointers
561 to indices as arguments of
<constant>VIDIOC_G_STD
</constant> and
562 <constant>VIDIOC_S_STD
</constant>, the &v4l2-input; and
563 &v4l2-output;
<structfield>std
</structfield> field would be a set of
564 indices like
<structfield>audioset
</structfield>.
</para>
565 <para>Indices are consistent with the rest of the API
566 and identify the standard unambiguously. In the present scheme of
567 things an enumerated standard is looked up by &v4l2-std-id;. Now the
568 standards supported by the inputs of a device can overlap. Just
569 assume the tuner and composite input in the example above both
570 exist on a device. An enumeration of
"PAL-B/G",
"PAL-H/I" suggests
571 a choice which does not exist. We cannot merge or omit sets, because
572 applications would be unable to find the standards reported by
573 <constant>VIDIOC_G_STD
</constant>. That leaves separate enumerations
574 for each input. Also selecting a standard by &v4l2-std-id; can be
575 ambiguous. Advantage of this method is that applications need not
576 identify the standard indirectly, after enumerating.
</para><para>So in
577 summary, the lookup itself is unavoidable. The difference is only
578 whether the lookup is necessary to find an enumerated standard or to
579 switch to a standard by &v4l2-std-id;.
</para>
580 </footnote> Drivers must implement all video standard ioctls
581 when the device has one or more video inputs or outputs.
</para>
583 <para>Special rules apply to USB cameras where the notion of video
584 standards makes little sense. More generally any capture device,
585 output devices accordingly, which is
<itemizedlist>
587 <para>incapable of capturing fields or frames at the nominal
588 rate of the video standard, or
</para>
591 <para>where
<link linkend=
"buffer">timestamps
</link> refer
592 to the instant the field or frame was received by the driver, not the
593 capture time, or
</para>
596 <para>where
<link linkend=
"buffer">sequence numbers
</link>
597 refer to the frames received by the driver, not the captured
600 </itemizedlist> Here the driver shall set the
601 <structfield>std
</structfield> field of &v4l2-input; and &v4l2-output;
602 to zero, the
<constant>VIDIOC_G_STD
</constant>,
603 <constant>VIDIOC_S_STD
</constant>,
604 <constant>VIDIOC_QUERYSTD
</constant> and
605 <constant>VIDIOC_ENUMSTD
</constant> ioctls shall return the
607 <para>See
<xref linkend=
"buffer" /> for a rationale. Probably
608 even USB cameras follow some well known video standard. It might have
609 been better to explicitly indicate elsewhere if a device cannot live
610 up to normal expectations, instead of this exception.
</para>
614 <title>Information about the current video standard
</title>
617 &v4l2-std-id; std_id;
618 &v4l2-standard; standard;
620 if (-
1 == ioctl (fd, &VIDIOC-G-STD;,
&std_id)) {
621 /* Note when VIDIOC_ENUMSTD always returns EINVAL this
622 is no video device or it falls under the USB exception,
623 and VIDIOC_G_STD returning EINVAL is no error. */
625 perror (
"VIDIOC_G_STD");
629 memset (
&standard,
0, sizeof (standard));
632 while (
0 == ioctl (fd, &VIDIOC-ENUMSTD;,
&standard)) {
633 if (standard.id
& std_id) {
634 printf (
"Current video standard: %s\n", standard.name);
641 /* EINVAL indicates the end of the enumeration, which cannot be
642 empty unless this device falls under the USB exception. */
644 if (errno == EINVAL || standard.index ==
0) {
645 perror (
"VIDIOC_ENUMSTD");
652 <title>Listing the video standards supported by the current
657 &v4l2-standard; standard;
659 memset (
&input,
0, sizeof (input));
661 if (-
1 == ioctl (fd, &VIDIOC-G-INPUT;,
&input.index)) {
662 perror (
"VIDIOC_G_INPUT");
666 if (-
1 == ioctl (fd, &VIDIOC-ENUMINPUT;,
&input)) {
667 perror (
"VIDIOC_ENUM_INPUT");
671 printf (
"Current input %s supports:\n", input.name);
673 memset (
&standard,
0, sizeof (standard));
676 while (
0 == ioctl (fd, &VIDIOC-ENUMSTD;,
&standard)) {
677 if (standard.id
& input.std)
678 printf (
"%s\n", standard.name);
683 /* EINVAL indicates the end of the enumeration, which cannot be
684 empty unless this device falls under the USB exception. */
686 if (errno != EINVAL || standard.index ==
0) {
687 perror (
"VIDIOC_ENUMSTD");
694 <title>Selecting a new video standard
</title>
698 &v4l2-std-id; std_id;
700 memset (
&input,
0, sizeof (input));
702 if (-
1 == ioctl (fd, &VIDIOC-G-INPUT;,
&input.index)) {
703 perror (
"VIDIOC_G_INPUT");
707 if (-
1 == ioctl (fd, &VIDIOC-ENUMINPUT;,
&input)) {
708 perror (
"VIDIOC_ENUM_INPUT");
712 if (
0 == (input.std
& V4L2_STD_PAL_BG)) {
713 fprintf (stderr,
"Oops. B/G PAL is not supported.\n");
717 /* Note this is also supposed to work when only B
718 <emphasis>or
</emphasis> G/PAL is supported. */
720 std_id = V4L2_STD_PAL_BG;
722 if (-
1 == ioctl (fd, &VIDIOC-S-STD;,
&std_id)) {
723 perror (
"VIDIOC_S_STD");
732 <section id=
"format">
733 <title>Data Formats
</title>
736 <title>Data Format Negotiation
</title>
738 <para>Different devices exchange different kinds of data with
739 applications, for example video images, raw or sliced VBI data, RDS
740 datagrams. Even within one kind many different formats are possible,
741 in particular an abundance of image formats. Although drivers must
742 provide a default and the selection persists across closing and
743 reopening a device, applications should always negotiate a data format
744 before engaging in data exchange. Negotiation means the application
745 asks for a particular format and the driver selects and reports the
746 best the hardware can do to satisfy the request. Of course
747 applications can also just query the current selection.
</para>
749 <para>A single mechanism exists to negotiate all data formats
750 using the aggregate &v4l2-format; and the &VIDIOC-G-FMT; and
751 &VIDIOC-S-FMT; ioctls. Additionally the &VIDIOC-TRY-FMT; ioctl can be
752 used to examine what the hardware
<emphasis>could
</emphasis> do,
753 without actually selecting a new data format. The data formats
754 supported by the V4L2 API are covered in the respective device section
755 in
<xref linkend=
"devices" />. For a closer look at image formats see
756 <xref linkend=
"pixfmt" />.
</para>
758 <para>The
<constant>VIDIOC_S_FMT
</constant> ioctl is a major
759 turning-point in the initialization sequence. Prior to this point
760 multiple panel applications can access the same device concurrently to
761 select the current input, change controls or modify other properties.
762 The first
<constant>VIDIOC_S_FMT
</constant> assigns a logical stream
763 (video data, VBI data etc.) exclusively to one file descriptor.
</para>
765 <para>Exclusive means no other application, more precisely no
766 other file descriptor, can grab this stream or change device
767 properties inconsistent with the negotiated parameters. A video
768 standard change for example, when the new standard uses a different
769 number of scan lines, can invalidate the selected image format.
770 Therefore only the file descriptor owning the stream can make
771 invalidating changes. Accordingly multiple file descriptors which
772 grabbed different logical streams prevent each other from interfering
773 with their settings. When for example video overlay is about to start
774 or already in progress, simultaneous video capturing may be restricted
775 to the same cropping and image size.
</para>
777 <para>When applications omit the
778 <constant>VIDIOC_S_FMT
</constant> ioctl its locking side effects are
779 implied by the next step, the selection of an I/O method with the
780 &VIDIOC-REQBUFS; ioctl or implicit with the first &func-read; or
781 &func-write; call.
</para>
783 <para>Generally only one logical stream can be assigned to a
784 file descriptor, the exception being drivers permitting simultaneous
785 video capturing and overlay using the same file descriptor for
786 compatibility with V4L and earlier versions of V4L2. Switching the
787 logical stream or returning into
"panel mode" is possible by closing
788 and reopening the device. Drivers
<emphasis>may
</emphasis> support a
789 switch using
<constant>VIDIOC_S_FMT
</constant>.
</para>
791 <para>All drivers exchanging data with
792 applications must support the
<constant>VIDIOC_G_FMT
</constant> and
793 <constant>VIDIOC_S_FMT
</constant> ioctl. Implementation of the
794 <constant>VIDIOC_TRY_FMT
</constant> is highly recommended but
799 <title>Image Format Enumeration
</title>
801 <para>Apart of the generic format negotiation functions
802 a special ioctl to enumerate all image formats supported by video
803 capture, overlay or output devices is available.
<footnote>
804 <para>Enumerating formats an application has no a-priori
805 knowledge of (otherwise it could explicitely ask for them and need not
806 enumerate) seems useless, but there are applications serving as proxy
807 between drivers and the actual video applications for which this is
811 <para>The &VIDIOC-ENUM-FMT; ioctl must be supported
812 by all drivers exchanging image data with applications.
</para>
815 <para>Drivers are not supposed to convert image formats in
816 kernel space. They must enumerate only formats directly supported by
817 the hardware. If necessary driver writers should publish an example
818 conversion routine or library for integration into applications.
</para>
824 <title>Image Cropping, Insertion and Scaling
</title>
826 <para>Some video capture devices can sample a subsection of the
827 picture and shrink or enlarge it to an image of arbitrary size. We
828 call these abilities cropping and scaling. Some video output devices
829 can scale an image up or down and insert it at an arbitrary scan line
830 and horizontal offset into a video signal.
</para>
832 <para>Applications can use the following API to select an area in
833 the video signal, query the default area and the hardware limits.
834 <emphasis>Despite their name, the &VIDIOC-CROPCAP;, &VIDIOC-G-CROP;
835 and &VIDIOC-S-CROP; ioctls apply to input as well as output
836 devices.
</emphasis></para>
838 <para>Scaling requires a source and a target. On a video capture
839 or overlay device the source is the video signal, and the cropping
840 ioctls determine the area actually sampled. The target are images
841 read by the application or overlaid onto the graphics screen. Their
842 size (and position for an overlay) is negotiated with the
843 &VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls.
</para>
845 <para>On a video output device the source are the images passed in
846 by the application, and their size is again negotiated with the
847 <constant>VIDIOC_G/S_FMT
</constant> ioctls, or may be encoded in a
848 compressed video stream. The target is the video signal, and the
849 cropping ioctls determine the area where the images are
852 <para>Source and target rectangles are defined even if the device
853 does not support scaling or the
<constant>VIDIOC_G/S_CROP
</constant>
854 ioctls. Their size (and position where applicable) will be fixed in
855 this case.
<emphasis>All capture and output device must support the
856 <constant>VIDIOC_CROPCAP
</constant> ioctl such that applications can
857 determine if scaling takes place.
</emphasis></para>
860 <title>Cropping Structures
</title>
862 <figure id=
"crop-scale">
863 <title>Image Cropping, Insertion and Scaling
</title>
866 <imagedata fileref=
"crop.pdf" format=
"PS" />
869 <imagedata fileref=
"crop.gif" format=
"GIF" />
872 <phrase>The cropping, insertion and scaling process
</phrase>
877 <para>For capture devices the coordinates of the top left
878 corner, width and height of the area which can be sampled is given by
879 the
<structfield>bounds
</structfield> substructure of the
880 &v4l2-cropcap; returned by the
<constant>VIDIOC_CROPCAP
</constant>
881 ioctl. To support a wide range of hardware this specification does not
882 define an origin or units. However by convention drivers should
883 horizontally count unscaled samples relative to
0H (the leading edge
884 of the horizontal sync pulse, see
<xref linkend=
"vbi-hsync" />).
885 Vertically ITU-R line
886 numbers of the first field (
<xref linkend=
"vbi-525" />,
<xref
887 linkend=
"vbi-625" />), multiplied by two if the driver can capture both
890 <para>The top left corner, width and height of the source
891 rectangle, that is the area actually sampled, is given by &v4l2-crop;
892 using the same coordinate system as &v4l2-cropcap;. Applications can
893 use the
<constant>VIDIOC_G_CROP
</constant> and
894 <constant>VIDIOC_S_CROP
</constant> ioctls to get and set this
895 rectangle. It must lie completely within the capture boundaries and
896 the driver may further adjust the requested size and/or position
897 according to hardware limitations.
</para>
899 <para>Each capture device has a default source rectangle, given
900 by the
<structfield>defrect
</structfield> substructure of
901 &v4l2-cropcap;. The center of this rectangle shall align with the
902 center of the active picture area of the video signal, and cover what
903 the driver writer considers the complete picture. Drivers shall reset
904 the source rectangle to the default when the driver is first loaded,
905 but not later.
</para>
907 <para>For output devices these structures and ioctls are used
908 accordingly, defining the
<emphasis>target
</emphasis> rectangle where
909 the images will be inserted into the video signal.
</para>
914 <title>Scaling Adjustments
</title>
916 <para>Video hardware can have various cropping, insertion and
917 scaling limitations. It may only scale up or down, support only
918 discrete scaling factors, or have different scaling abilities in
919 horizontal and vertical direction. Also it may not support scaling at
920 all. At the same time the &v4l2-crop; rectangle may have to be
921 aligned, and both the source and target rectangles may have arbitrary
922 upper and lower size limits. In particular the maximum
923 <structfield>width
</structfield> and
<structfield>height
</structfield>
924 in &v4l2-crop; may be smaller than the
925 &v4l2-cropcap;.
<structfield>bounds
</structfield> area. Therefore, as
926 usual, drivers are expected to adjust the requested parameters and
927 return the actual values selected.
</para>
929 <para>Applications can change the source or the target rectangle
930 first, as they may prefer a particular image size or a certain area in
931 the video signal. If the driver has to adjust both to satisfy hardware
932 limitations, the last requested rectangle shall take priority, and the
933 driver should preferably adjust the opposite one. The &VIDIOC-TRY-FMT;
934 ioctl however shall not change the driver state and therefore only
935 adjust the requested rectangle.
</para>
937 <para>Suppose scaling on a video capture device is restricted to
938 a factor
1:
1 or
2:
1 in either direction and the target image size must
939 be a multiple of
16 × 16 pixels. The source cropping
940 rectangle is set to defaults, which are also the upper limit in this
941 example, of
640 × 400 pixels at offset
0,
0. An
942 application requests an image size of
300 × 225
943 pixels, assuming video will be scaled down from the
"full picture"
944 accordingly. The driver sets the image size to the closest possible
945 values
304 × 224, then chooses the cropping rectangle
946 closest to the requested size, that is
608 × 224
947 (
224 × 2:
1 would exceed the limit
400). The offset
948 0,
0 is still valid, thus unmodified. Given the default cropping
949 rectangle reported by
<constant>VIDIOC_CROPCAP
</constant> the
950 application can easily propose another offset to center the cropping
953 <para>Now the application may insist on covering an area using a
954 picture aspect ratio closer to the original request, so it asks for a
955 cropping rectangle of
608 × 456 pixels. The present
956 scaling factors limit cropping to
640 × 384, so the
957 driver returns the cropping size
608 × 384 and adjusts
958 the image size to closest possible
304 × 192.
</para>
963 <title>Examples
</title>
965 <para>Source and target rectangles shall remain unchanged across
966 closing and reopening a device, such that piping data into or out of a
967 device will work without special preparations. More advanced
968 applications should ensure the parameters are suitable before starting
972 <title>Resetting the cropping parameters
</title>
974 <para>(A video capture device is assumed; change
975 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE
</constant> for other
979 &v4l2-cropcap; cropcap;
982 memset (
&cropcap,
0, sizeof (cropcap));
983 cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
985 if (-
1 == ioctl (fd, &VIDIOC-CROPCAP;,
&cropcap)) {
986 perror (
"VIDIOC_CROPCAP");
990 memset (
&crop,
0, sizeof (crop));
991 crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
992 crop.c = cropcap.defrect;
994 /* Ignore if cropping is not supported (EINVAL). */
996 if (-
1 == ioctl (fd, &VIDIOC-S-CROP;,
&crop)
997 && errno != EINVAL) {
998 perror (
"VIDIOC_S_CROP");
1005 <title>Simple downscaling
</title>
1007 <para>(A video capture device is assumed.)
</para>
1010 &v4l2-cropcap; cropcap;
1011 &v4l2-format; format;
1013 reset_cropping_parameters ();
1015 /* Scale down to
1/
4 size of full picture. */
1017 memset (
&format,
0, sizeof (format)); /* defaults */
1019 format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1021 format.fmt.pix.width = cropcap.defrect.width
>> 1;
1022 format.fmt.pix.height = cropcap.defrect.height
>> 1;
1023 format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
1025 if (-
1 == ioctl (fd, &VIDIOC-S-FMT;,
&format)) {
1026 perror (
"VIDIOC_S_FORMAT");
1027 exit (EXIT_FAILURE);
1030 /* We could check the actual image size now, the actual scaling factor
1031 or if the driver can scale at all. */
1036 <title>Selecting an output area
</title>
1039 &v4l2-cropcap; cropcap;
1042 memset (
&cropcap,
0, sizeof (cropcap));
1043 cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
1045 if (-
1 == ioctl (fd, VIDIOC_CROPCAP;,
&cropcap)) {
1046 perror (
"VIDIOC_CROPCAP");
1047 exit (EXIT_FAILURE);
1050 memset (
&crop,
0, sizeof (crop));
1052 crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
1053 crop.c = cropcap.defrect;
1055 /* Scale the width and height to
50 % of their original size
1056 and center the output. */
1060 crop.c.left += crop.c.width /
2;
1061 crop.c.top += crop.c.height /
2;
1063 /* Ignore if cropping is not supported (EINVAL). */
1065 if (-
1 == ioctl (fd, VIDIOC_S_CROP,
&crop)
1066 && errno != EINVAL) {
1067 perror (
"VIDIOC_S_CROP");
1068 exit (EXIT_FAILURE);
1074 <title>Current scaling factor and pixel aspect
</title>
1076 <para>(A video capture device is assumed.)
</para>
1079 &v4l2-cropcap; cropcap;
1081 &v4l2-format; format;
1082 double hscale, vscale;
1084 int dwidth, dheight;
1086 memset (
&cropcap,
0, sizeof (cropcap));
1087 cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1089 if (-
1 == ioctl (fd, &VIDIOC-CROPCAP;,
&cropcap)) {
1090 perror (
"VIDIOC_CROPCAP");
1091 exit (EXIT_FAILURE);
1094 memset (
&crop,
0, sizeof (crop));
1095 crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1097 if (-
1 == ioctl (fd, &VIDIOC-G-CROP;,
&crop)) {
1098 if (errno != EINVAL) {
1099 perror (
"VIDIOC_G_CROP");
1100 exit (EXIT_FAILURE);
1103 /* Cropping not supported. */
1104 crop.c = cropcap.defrect;
1107 memset (
&format,
0, sizeof (format));
1108 format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1110 if (-
1 == ioctl (fd, &VIDIOC-G-FMT;,
&format)) {
1111 perror (
"VIDIOC_G_FMT");
1112 exit (EXIT_FAILURE);
1115 /* The scaling applied by the driver. */
1117 hscale = format.fmt.pix.width / (double) crop.c.width;
1118 vscale = format.fmt.pix.height / (double) crop.c.height;
1120 aspect = cropcap.pixelaspect.numerator /
1121 (double) cropcap.pixelaspect.denominator;
1122 aspect = aspect * hscale / vscale;
1124 /* Devices following ITU-R BT
.601 do not capture
1125 square pixels. For playback on a computer monitor
1126 we should scale the images to this size. */
1128 dwidth = format.fmt.pix.width / aspect;
1129 dheight = format.fmt.pix.height;
1135 <section id=
"streaming-par">
1136 <title>Streaming Parameters
</title>
1138 <para>Streaming parameters are intended to optimize the video
1139 capture process as well as I/O. Presently applications can request a
1140 high quality capture mode with the &VIDIOC-S-PARM; ioctl.
</para>
1142 <para>The current video standard determines a nominal number of
1143 frames per second. If less than this number of frames is to be
1144 captured or output, applications can request frame skipping or
1145 duplicating on the driver side. This is especially useful when using
1146 the &func-read; or &func-write;, which are not augmented by timestamps
1147 or sequence counters, and to avoid unneccessary data copying.
</para>
1149 <para>Finally these ioctls can be used to determine the number of
1150 buffers used internally by a driver in read/write mode. For
1151 implications see the section discussing the &func-read;
1154 <para>To get and set the streaming parameters applications call
1155 the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; ioctl, respectively. They take
1156 a pointer to a &v4l2-streamparm;, which contains a union holding
1157 separate parameters for input and output devices.
</para>
1159 <para>These ioctls are optional, drivers need not implement
1160 them. If so, they return the
&EINVAL;.
</para>
1166 sgml-parent-document: "v4l2.sgml"
1167 indent-tabs-mode: nil