Merge branch 'akpm' (Andrew's patch-bomb)
[firefly-linux-kernel-4.4.55.git] / Documentation / DocBook / media / v4l / common.xml
1   <title>Common API Elements</title>
2
3   <para>Programming a V4L2 device consists of these
4 steps:</para>
5
6   <itemizedlist>
7     <listitem>
8       <para>Opening the device</para>
9     </listitem>
10     <listitem>
11       <para>Changing device properties, selecting a video and audio
12 input, video standard, picture brightness a.&nbsp;o.</para>
13     </listitem>
14     <listitem>
15       <para>Negotiating a data format</para>
16     </listitem>
17     <listitem>
18       <para>Negotiating an input/output method</para>
19     </listitem>
20     <listitem>
21       <para>The actual input/output loop</para>
22     </listitem>
23     <listitem>
24       <para>Closing the device</para>
25     </listitem>
26   </itemizedlist>
27
28   <para>In practice most steps are optional and can be executed out of
29 order. It depends on the V4L2 device type, you can read about the
30 details in <xref linkend="devices" />. In this chapter we will discuss
31 the basic concepts applicable to all devices.</para>
32
33   <section id="open">
34     <title>Opening and Closing Devices</title>
35
36     <section>
37       <title>Device Naming</title>
38
39       <para>V4L2 drivers are implemented as kernel modules, loaded
40 manually by the system administrator or automatically when a device is
41 first 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>
44
45       <para>Each driver thus loaded registers one or more device nodes
46 with major number 81 and a minor number between 0 and 255. 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.
59 <footnote>
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
65 into drivers.</para>
66         </footnote> When the driver supports multiple devices of the same
67 type more than one minor number can be assigned, separated by commas:
68 <informalexample>
69           <screen>
70 &gt; insmod mydriver.o video_nr=0,1 radio_nr=0,1</screen>
71         </informalexample></para>
72
73       <para>In <filename>/etc/modules.conf</filename> this may be
74 written as: <informalexample>
75           <screen>
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" />
80           </screen>
81           <calloutlist>
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>
86             </callout>
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>
91             </callout>
92           </calloutlist>
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>
100
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" />.
105 </para>
106
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>
113
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
118 names above.</para>
119     </section>
120
121     <section id="related">
122       <title>Related Devices</title>
123
124       <para>Devices can support several related functions. For example
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>
139
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>
147
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.&nbsp;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>
163
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>
170     </section>
171
172     <section>
173       <title>Multiple Opens</title>
174
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>
183
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>
190
191       <para>Mere opening a V4L2 device does not grant exclusive
192 access.<footnote>
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>
201     </section>
202
203     <section>
204       <title>Shared Data Streams</title>
205
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
214 match etc.--></para>
215     </section>
216
217     <section>
218       <title>Functions</title>
219
220     <para>To open and close V4L2 devices applications use the
221 &func-open; and &func-close; function, respectively. Devices are
222 programmed using the &func-ioctl; function as explained in the
223 following sections.</para>
224     </section>
225   </section>
226
227   <section id="querycap">
228     <title>Querying Capabilities</title>
229
230     <para>Because V4L2 covers a wide variety of devices not all
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>
235
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>
240
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>
246
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
252 the driver.</para>
253
254     <para>All V4L2 drivers must support
255 <constant>VIDIOC_QUERYCAP</constant>. Applications should always call
256 this ioctl after opening the device.</para>
257   </section>
258
259   <section id="app-pri">
260     <title>Application Priority</title>
261
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>
270
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>
279
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>
284   </section>
285
286   <section id="video">
287     <title>Video Inputs and Outputs</title>
288
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>
294
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>
301
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>
308
309     <!--
310     <figure id=io-tree>
311       <title>Input and output enumeration is the root of most device properties.</title>
312       <mediaobject>
313         <imageobject>
314           <imagedata fileref="links.pdf" format="ps" />
315         </imageobject>
316         <imageobject>
317           <imagedata fileref="links.gif" format="gif" />
318         </imageobject>
319         <textobject>
320           <phrase>Links between various device property structures.</phrase>
321         </textobject>
322       </mediaobject>
323     </figure>
324     -->
325
326     <example>
327       <title>Information about the current video input</title>
328
329       <programlisting>
330 &v4l2-input; input;
331 int index;
332
333 if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;index)) {
334         perror ("VIDIOC_G_INPUT");
335         exit (EXIT_FAILURE);
336 }
337
338 memset (&amp;input, 0, sizeof (input));
339 input.index = index;
340
341 if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
342         perror ("VIDIOC_ENUMINPUT");
343         exit (EXIT_FAILURE);
344 }
345
346 printf ("Current input: %s\n", input.name);
347       </programlisting>
348     </example>
349
350     <example>
351       <title>Switching to the first video input</title>
352
353       <programlisting>
354 int index;
355
356 index = 0;
357
358 if (-1 == ioctl (fd, &VIDIOC-S-INPUT;, &amp;index)) {
359         perror ("VIDIOC_S_INPUT");
360         exit (EXIT_FAILURE);
361 }
362       </programlisting>
363     </example>
364   </section>
365
366   <section id="audio">
367     <title>Audio Inputs and Outputs</title>
368
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>
382
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>
392
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>
399
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>
405
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>
410
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>
416
417     <example>
418       <title>Information about the current audio input</title>
419
420       <programlisting>
421 &v4l2-audio; audio;
422
423 memset (&amp;audio, 0, sizeof (audio));
424
425 if (-1 == ioctl (fd, &VIDIOC-G-AUDIO;, &amp;audio)) {
426         perror ("VIDIOC_G_AUDIO");
427         exit (EXIT_FAILURE);
428 }
429
430 printf ("Current input: %s\n", audio.name);
431       </programlisting>
432     </example>
433
434     <example>
435       <title>Switching to the first audio input</title>
436
437       <programlisting>
438 &v4l2-audio; audio;
439
440 memset (&amp;audio, 0, sizeof (audio)); /* clear audio.mode, audio.reserved */
441
442 audio.index = 0;
443
444 if (-1 == ioctl (fd, &VIDIOC-S-AUDIO;, &amp;audio)) {
445         perror ("VIDIOC_S_AUDIO");
446         exit (EXIT_FAILURE);
447 }
448       </programlisting>
449     </example>
450   </section>
451
452   <section id="tuner">
453     <title>Tuners and Modulators</title>
454
455     <section>
456       <title>Tuners</title>
457
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
465 the tuner.</para>
466
467       <para>Radio devices have exactly one tuner with index zero, no
468 video inputs.</para>
469
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 input, or a radio tuner 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
480 more tuners.</para>
481     </section>
482
483     <section>
484       <title>Modulators</title>
485
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. This specification does not define radio output
495 devices.</para>
496
497       <para>To query and change modulator properties applications use
498 the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that
499 <constant>VIDIOC_S_MODULATOR</constant> does not switch the current
500 modulator, when there is more than one at all. The modulator is solely
501 determined by the current video output. Drivers must support both
502 ioctls and set the <constant>V4L2_CAP_MODULATOR</constant> flag in
503 the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl when the
504 device has one or more modulators.</para>
505     </section>
506
507     <section>
508       <title>Radio Frequency</title>
509
510       <para>To get and set the tuner or modulator radio frequency
511 applications use the &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY;
512 ioctl which both take a pointer to a &v4l2-frequency;. These ioctls
513 are used for TV and radio devices alike. Drivers must support both
514 ioctls when the tuner or modulator ioctls are supported, or
515 when the device is a radio device.</para>
516     </section>
517   </section>
518
519   <section id="standard">
520     <title>Video Standards</title>
521
522     <para>Video devices typically support one or more different video
523 standards or variations of standards. Each video input and output may
524 support another set of standards. This set is reported by the
525 <structfield>std</structfield> field of &v4l2-input; and
526 &v4l2-output; returned by the &VIDIOC-ENUMINPUT; and
527 &VIDIOC-ENUMOUTPUT; ioctl, respectively.</para>
528
529     <para>V4L2 defines one bit for each analog video standard
530 currently in use worldwide, and sets aside bits for driver defined
531 standards, &eg; hybrid standards to watch NTSC video tapes on PAL TVs
532 and vice versa. Applications can use the predefined bits to select a
533 particular standard, although presenting the user a menu of supported
534 standards is preferred. To enumerate and query the attributes of the
535 supported standards applications use the &VIDIOC-ENUMSTD; ioctl.</para>
536
537     <para>Many of the defined standards are actually just variations
538 of a few major standards. The hardware may in fact not distinguish
539 between them, or do so internal and switch automatically. Therefore
540 enumerated standards also contain sets of one or more standard
541 bits.</para>
542
543     <para>Assume a hypothetic tuner capable of demodulating B/PAL,
544 G/PAL and I/PAL signals. The first enumerated standard is a set of B
545 and G/PAL, switched automatically depending on the selected radio
546 frequency in UHF or VHF band. Enumeration gives a "PAL-B/G" or "PAL-I"
547 choice. Similar a Composite input may collapse standards, enumerating
548 "PAL-B/G/H/I", "NTSC-M" and "SECAM-D/K".<footnote>
549         <para>Some users are already confused by technical terms PAL,
550 NTSC and SECAM. There is no point asking them to distinguish between
551 B, G, D, or K when the software or hardware can do that
552 automatically.</para>
553     </footnote></para>
554
555     <para>To query and select the standard used by the current video
556 input or output applications call the &VIDIOC-G-STD; and
557 &VIDIOC-S-STD; ioctl, respectively. The <emphasis>received</emphasis>
558 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>
559         <para>An alternative to the current scheme is to use pointers
560 to indices as arguments of <constant>VIDIOC_G_STD</constant> and
561 <constant>VIDIOC_S_STD</constant>, the &v4l2-input; and
562 &v4l2-output; <structfield>std</structfield> field would be a set of
563 indices like <structfield>audioset</structfield>.</para>
564         <para>Indices are consistent with the rest of the API
565 and identify the standard unambiguously. In the present scheme of
566 things an enumerated standard is looked up by &v4l2-std-id;. Now the
567 standards supported by the inputs of a device can overlap. Just
568 assume the tuner and composite input in the example above both
569 exist on a device. An enumeration of "PAL-B/G", "PAL-H/I" suggests
570 a choice which does not exist. We cannot merge or omit sets, because
571 applications would be unable to find the standards reported by
572 <constant>VIDIOC_G_STD</constant>. That leaves separate enumerations
573 for each input. Also selecting a standard by &v4l2-std-id; can be
574 ambiguous. Advantage of this method is that applications need not
575 identify the standard indirectly, after enumerating.</para><para>So in
576 summary, the lookup itself is unavoidable. The difference is only
577 whether the lookup is necessary to find an enumerated standard or to
578 switch to a standard by &v4l2-std-id;.</para>
579       </footnote> Drivers must implement all video standard ioctls
580 when the device has one or more video inputs or outputs.</para>
581
582     <para>Special rules apply to USB cameras where the notion of video
583 standards makes little sense. More generally any capture device,
584 output devices accordingly, which is <itemizedlist>
585         <listitem>
586           <para>incapable of capturing fields or frames at the nominal
587 rate of the video standard, or</para>
588         </listitem>
589         <listitem>
590           <para>where <link linkend="buffer">timestamps</link> refer
591 to the instant the field or frame was received by the driver, not the
592 capture time, or</para>
593         </listitem>
594         <listitem>
595           <para>where <link linkend="buffer">sequence numbers</link>
596 refer to the frames received by the driver, not the captured
597 frames.</para>
598         </listitem>
599       </itemizedlist> Here the driver shall set the
600 <structfield>std</structfield> field of &v4l2-input; and &v4l2-output;
601 to zero, the <constant>VIDIOC_G_STD</constant>,
602 <constant>VIDIOC_S_STD</constant>,
603 <constant>VIDIOC_QUERYSTD</constant> and
604 <constant>VIDIOC_ENUMSTD</constant> ioctls shall return the
605 &EINVAL;.<footnote>
606         <para>See <xref linkend="buffer" /> for a rationale. Probably
607 even USB cameras follow some well known video standard. It might have
608 been better to explicitly indicate elsewhere if a device cannot live
609 up to normal expectations, instead of this exception.</para>
610             </footnote></para>
611
612     <example>
613       <title>Information about the current video standard</title>
614
615       <programlisting>
616 &v4l2-std-id; std_id;
617 &v4l2-standard; standard;
618
619 if (-1 == ioctl (fd, &VIDIOC-G-STD;, &amp;std_id)) {
620         /* Note when VIDIOC_ENUMSTD always returns EINVAL this
621            is no video device or it falls under the USB exception,
622            and VIDIOC_G_STD returning EINVAL is no error. */
623
624         perror ("VIDIOC_G_STD");
625         exit (EXIT_FAILURE);
626 }
627
628 memset (&amp;standard, 0, sizeof (standard));
629 standard.index = 0;
630
631 while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
632         if (standard.id &amp; std_id) {
633                printf ("Current video standard: %s\n", standard.name);
634                exit (EXIT_SUCCESS);
635         }
636
637         standard.index++;
638 }
639
640 /* EINVAL indicates the end of the enumeration, which cannot be
641    empty unless this device falls under the USB exception. */
642
643 if (errno == EINVAL || standard.index == 0) {
644         perror ("VIDIOC_ENUMSTD");
645         exit (EXIT_FAILURE);
646 }
647       </programlisting>
648     </example>
649
650     <example>
651       <title>Listing the video standards supported by the current
652 input</title>
653
654       <programlisting>
655 &v4l2-input; input;
656 &v4l2-standard; standard;
657
658 memset (&amp;input, 0, sizeof (input));
659
660 if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
661         perror ("VIDIOC_G_INPUT");
662         exit (EXIT_FAILURE);
663 }
664
665 if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
666         perror ("VIDIOC_ENUM_INPUT");
667         exit (EXIT_FAILURE);
668 }
669
670 printf ("Current input %s supports:\n", input.name);
671
672 memset (&amp;standard, 0, sizeof (standard));
673 standard.index = 0;
674
675 while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
676         if (standard.id &amp; input.std)
677                 printf ("%s\n", standard.name);
678
679         standard.index++;
680 }
681
682 /* EINVAL indicates the end of the enumeration, which cannot be
683    empty unless this device falls under the USB exception. */
684
685 if (errno != EINVAL || standard.index == 0) {
686         perror ("VIDIOC_ENUMSTD");
687         exit (EXIT_FAILURE);
688 }
689       </programlisting>
690     </example>
691
692     <example>
693       <title>Selecting a new video standard</title>
694
695       <programlisting>
696 &v4l2-input; input;
697 &v4l2-std-id; std_id;
698
699 memset (&amp;input, 0, sizeof (input));
700
701 if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
702         perror ("VIDIOC_G_INPUT");
703         exit (EXIT_FAILURE);
704 }
705
706 if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
707         perror ("VIDIOC_ENUM_INPUT");
708         exit (EXIT_FAILURE);
709 }
710
711 if (0 == (input.std &amp; V4L2_STD_PAL_BG)) {
712         fprintf (stderr, "Oops. B/G PAL is not supported.\n");
713         exit (EXIT_FAILURE);
714 }
715
716 /* Note this is also supposed to work when only B
717    <emphasis>or</emphasis> G/PAL is supported. */
718
719 std_id = V4L2_STD_PAL_BG;
720
721 if (-1 == ioctl (fd, &VIDIOC-S-STD;, &amp;std_id)) {
722         perror ("VIDIOC_S_STD");
723         exit (EXIT_FAILURE);
724 }
725       </programlisting>
726     </example>
727   </section>
728   <section id="dv-timings">
729         <title>Digital Video (DV) Timings</title>
730         <para>
731         The video standards discussed so far have been dealing with Analog TV and the
732 corresponding video timings. Today there are many more different hardware interfaces
733 such as High Definition TV interfaces (HDMI), VGA, DVI connectors etc., that carry
734 video signals and there is a need to extend the API to select the video timings
735 for these interfaces. Since it is not possible to extend the &v4l2-std-id; due to
736 the limited bits available, a new set of IOCTLs was added to set/get video timings at
737 the input and output: </para><itemizedlist>
738         <listitem>
739         <para>DV Timings: This will allow applications to define detailed
740 video timings for the interface. This includes parameters such as width, height,
741 polarities, frontporch, backporch etc. The <filename>linux/v4l2-dv-timings.h</filename>
742 header can be used to get the timings of the formats in the <xref linkend="cea861" /> and
743 <xref linkend="vesadmt" /> standards.
744         </para>
745         </listitem>
746         <listitem>
747         <para>DV Presets: Digital Video (DV) presets (<emphasis role="bold">deprecated</emphasis>).
748         These are IDs representing a
749 video timing at the input/output. Presets are pre-defined timings implemented
750 by the hardware according to video standards. A __u32 data type is used to represent
751 a preset unlike the bit mask that is used in &v4l2-std-id; allowing future extensions
752 to support as many different presets as needed. This API is deprecated in favor of the DV Timings
753 API.</para>
754         </listitem>
755         </itemizedlist>
756         <para>To enumerate and query the attributes of the DV timings supported by a device,
757         applications use the &VIDIOC-ENUM-DV-TIMINGS; and &VIDIOC-DV-TIMINGS-CAP; ioctls.
758         To set DV timings for the device, applications use the
759 &VIDIOC-S-DV-TIMINGS; ioctl and to get current DV timings they use the
760 &VIDIOC-G-DV-TIMINGS; ioctl. To detect the DV timings as seen by the video receiver applications
761 use the &VIDIOC-QUERY-DV-TIMINGS; ioctl.</para>
762         <para>To enumerate and query the attributes of DV presets supported by a device,
763 applications use the &VIDIOC-ENUM-DV-PRESETS; ioctl. To get the current DV preset,
764 applications use the &VIDIOC-G-DV-PRESET; ioctl and to set a preset they use the
765 &VIDIOC-S-DV-PRESET; ioctl. To detect the preset as seen by the video receiver applications
766 use the &VIDIOC-QUERY-DV-PRESET; ioctl.</para>
767         <para>Applications can make use of the <xref linkend="input-capabilities" /> and
768 <xref linkend="output-capabilities"/> flags to decide what ioctls are available to set the
769 video timings for the device.</para>
770   </section>
771
772   &sub-controls;
773
774   <section id="format">
775     <title>Data Formats</title>
776
777     <section>
778       <title>Data Format Negotiation</title>
779
780       <para>Different devices exchange different kinds of data with
781 applications, for example video images, raw or sliced VBI data, RDS
782 datagrams. Even within one kind many different formats are possible,
783 in particular an abundance of image formats. Although drivers must
784 provide a default and the selection persists across closing and
785 reopening a device, applications should always negotiate a data format
786 before engaging in data exchange. Negotiation means the application
787 asks for a particular format and the driver selects and reports the
788 best the hardware can do to satisfy the request. Of course
789 applications can also just query the current selection.</para>
790
791       <para>A single mechanism exists to negotiate all data formats
792 using the aggregate &v4l2-format; and the &VIDIOC-G-FMT; and
793 &VIDIOC-S-FMT; ioctls. Additionally the &VIDIOC-TRY-FMT; ioctl can be
794 used to examine what the hardware <emphasis>could</emphasis> do,
795 without actually selecting a new data format. The data formats
796 supported by the V4L2 API are covered in the respective device section
797 in <xref linkend="devices" />. For a closer look at image formats see
798 <xref linkend="pixfmt" />.</para>
799
800       <para>The <constant>VIDIOC_S_FMT</constant> ioctl is a major
801 turning-point in the initialization sequence. Prior to this point
802 multiple panel applications can access the same device concurrently to
803 select the current input, change controls or modify other properties.
804 The first <constant>VIDIOC_S_FMT</constant> assigns a logical stream
805 (video data, VBI data etc.) exclusively to one file descriptor.</para>
806
807       <para>Exclusive means no other application, more precisely no
808 other file descriptor, can grab this stream or change device
809 properties inconsistent with the negotiated parameters. A video
810 standard change for example, when the new standard uses a different
811 number of scan lines, can invalidate the selected image format.
812 Therefore only the file descriptor owning the stream can make
813 invalidating changes. Accordingly multiple file descriptors which
814 grabbed different logical streams prevent each other from interfering
815 with their settings. When for example video overlay is about to start
816 or already in progress, simultaneous video capturing may be restricted
817 to the same cropping and image size.</para>
818
819       <para>When applications omit the
820 <constant>VIDIOC_S_FMT</constant> ioctl its locking side effects are
821 implied by the next step, the selection of an I/O method with the
822 &VIDIOC-REQBUFS; ioctl or implicit with the first &func-read; or
823 &func-write; call.</para>
824
825       <para>Generally only one logical stream can be assigned to a
826 file descriptor, the exception being drivers permitting simultaneous
827 video capturing and overlay using the same file descriptor for
828 compatibility with V4L and earlier versions of V4L2. Switching the
829 logical stream or returning into "panel mode" is possible by closing
830 and reopening the device. Drivers <emphasis>may</emphasis> support a
831 switch using <constant>VIDIOC_S_FMT</constant>.</para>
832
833       <para>All drivers exchanging data with
834 applications must support the <constant>VIDIOC_G_FMT</constant> and
835 <constant>VIDIOC_S_FMT</constant> ioctl. Implementation of the
836 <constant>VIDIOC_TRY_FMT</constant> is highly recommended but
837 optional.</para>
838     </section>
839
840     <section>
841       <title>Image Format Enumeration</title>
842
843       <para>Apart of the generic format negotiation functions
844 a special ioctl to enumerate all image formats supported by video
845 capture, overlay or output devices is available.<footnote>
846           <para>Enumerating formats an application has no a-priori
847 knowledge of (otherwise it could explicitly ask for them and need not
848 enumerate) seems useless, but there are applications serving as proxy
849 between drivers and the actual video applications for which this is
850 useful.</para>
851         </footnote></para>
852
853       <para>The &VIDIOC-ENUM-FMT; ioctl must be supported
854 by all drivers exchanging image data with applications.</para>
855
856       <important>
857         <para>Drivers are not supposed to convert image formats in
858 kernel space. They must enumerate only formats directly supported by
859 the hardware. If necessary driver writers should publish an example
860 conversion routine or library for integration into applications.</para>
861       </important>
862     </section>
863   </section>
864
865   &sub-planar-apis;
866
867   <section id="crop">
868     <title>Image Cropping, Insertion and Scaling</title>
869
870     <para>Some video capture devices can sample a subsection of the
871 picture and shrink or enlarge it to an image of arbitrary size. We
872 call these abilities cropping and scaling. Some video output devices
873 can scale an image up or down and insert it at an arbitrary scan line
874 and horizontal offset into a video signal.</para>
875
876     <para>Applications can use the following API to select an area in
877 the video signal, query the default area and the hardware limits.
878 <emphasis>Despite their name, the &VIDIOC-CROPCAP;, &VIDIOC-G-CROP;
879 and &VIDIOC-S-CROP; ioctls apply to input as well as output
880 devices.</emphasis></para>
881
882     <para>Scaling requires a source and a target. On a video capture
883 or overlay device the source is the video signal, and the cropping
884 ioctls determine the area actually sampled. The target are images
885 read by the application or overlaid onto the graphics screen. Their
886 size (and position for an overlay) is negotiated with the
887 &VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls.</para>
888
889     <para>On a video output device the source are the images passed in
890 by the application, and their size is again negotiated with the
891 <constant>VIDIOC_G/S_FMT</constant> ioctls, or may be encoded in a
892 compressed video stream. The target is the video signal, and the
893 cropping ioctls determine the area where the images are
894 inserted.</para>
895
896     <para>Source and target rectangles are defined even if the device
897 does not support scaling or the <constant>VIDIOC_G/S_CROP</constant>
898 ioctls. Their size (and position where applicable) will be fixed in
899 this case. <emphasis>All capture and output device must support the
900 <constant>VIDIOC_CROPCAP</constant> ioctl such that applications can
901 determine if scaling takes place.</emphasis></para>
902
903     <section>
904       <title>Cropping Structures</title>
905
906       <figure id="crop-scale">
907         <title>Image Cropping, Insertion and Scaling</title>
908         <mediaobject>
909           <imageobject>
910             <imagedata fileref="crop.pdf" format="PS" />
911           </imageobject>
912           <imageobject>
913             <imagedata fileref="crop.gif" format="GIF" />
914           </imageobject>
915           <textobject>
916             <phrase>The cropping, insertion and scaling process</phrase>
917           </textobject>
918         </mediaobject>
919       </figure>
920
921       <para>For capture devices the coordinates of the top left
922 corner, width and height of the area which can be sampled is given by
923 the <structfield>bounds</structfield> substructure of the
924 &v4l2-cropcap; returned by the <constant>VIDIOC_CROPCAP</constant>
925 ioctl. To support a wide range of hardware this specification does not
926 define an origin or units. However by convention drivers should
927 horizontally count unscaled samples relative to 0H (the leading edge
928 of the horizontal sync pulse, see <xref linkend="vbi-hsync" />).
929 Vertically ITU-R line
930 numbers of the first field (<xref linkend="vbi-525" />, <xref
931 linkend="vbi-625" />), multiplied by two if the driver can capture both
932 fields.</para>
933
934       <para>The top left corner, width and height of the source
935 rectangle, that is the area actually sampled, is given by &v4l2-crop;
936 using the same coordinate system as &v4l2-cropcap;. Applications can
937 use the <constant>VIDIOC_G_CROP</constant> and
938 <constant>VIDIOC_S_CROP</constant> ioctls to get and set this
939 rectangle. It must lie completely within the capture boundaries and
940 the driver may further adjust the requested size and/or position
941 according to hardware limitations.</para>
942
943       <para>Each capture device has a default source rectangle, given
944 by the <structfield>defrect</structfield> substructure of
945 &v4l2-cropcap;. The center of this rectangle shall align with the
946 center of the active picture area of the video signal, and cover what
947 the driver writer considers the complete picture. Drivers shall reset
948 the source rectangle to the default when the driver is first loaded,
949 but not later.</para>
950
951       <para>For output devices these structures and ioctls are used
952 accordingly, defining the <emphasis>target</emphasis> rectangle where
953 the images will be inserted into the video signal.</para>
954
955     </section>
956
957     <section>
958       <title>Scaling Adjustments</title>
959
960       <para>Video hardware can have various cropping, insertion and
961 scaling limitations. It may only scale up or down, support only
962 discrete scaling factors, or have different scaling abilities in
963 horizontal and vertical direction. Also it may not support scaling at
964 all. At the same time the &v4l2-crop; rectangle may have to be
965 aligned, and both the source and target rectangles may have arbitrary
966 upper and lower size limits. In particular the maximum
967 <structfield>width</structfield> and <structfield>height</structfield>
968 in &v4l2-crop; may be smaller than the
969 &v4l2-cropcap;.<structfield>bounds</structfield> area. Therefore, as
970 usual, drivers are expected to adjust the requested parameters and
971 return the actual values selected.</para>
972
973       <para>Applications can change the source or the target rectangle
974 first, as they may prefer a particular image size or a certain area in
975 the video signal. If the driver has to adjust both to satisfy hardware
976 limitations, the last requested rectangle shall take priority, and the
977 driver should preferably adjust the opposite one. The &VIDIOC-TRY-FMT;
978 ioctl however shall not change the driver state and therefore only
979 adjust the requested rectangle.</para>
980
981       <para>Suppose scaling on a video capture device is restricted to
982 a factor 1:1 or 2:1 in either direction and the target image size must
983 be a multiple of 16&nbsp;&times;&nbsp;16 pixels. The source cropping
984 rectangle is set to defaults, which are also the upper limit in this
985 example, of 640&nbsp;&times;&nbsp;400 pixels at offset 0,&nbsp;0. An
986 application requests an image size of 300&nbsp;&times;&nbsp;225
987 pixels, assuming video will be scaled down from the "full picture"
988 accordingly. The driver sets the image size to the closest possible
989 values 304&nbsp;&times;&nbsp;224, then chooses the cropping rectangle
990 closest to the requested size, that is 608&nbsp;&times;&nbsp;224
991 (224&nbsp;&times;&nbsp;2:1 would exceed the limit 400). The offset
992 0,&nbsp;0 is still valid, thus unmodified. Given the default cropping
993 rectangle reported by <constant>VIDIOC_CROPCAP</constant> the
994 application can easily propose another offset to center the cropping
995 rectangle.</para>
996
997       <para>Now the application may insist on covering an area using a
998 picture aspect ratio closer to the original request, so it asks for a
999 cropping rectangle of 608&nbsp;&times;&nbsp;456 pixels. The present
1000 scaling factors limit cropping to 640&nbsp;&times;&nbsp;384, so the
1001 driver returns the cropping size 608&nbsp;&times;&nbsp;384 and adjusts
1002 the image size to closest possible 304&nbsp;&times;&nbsp;192.</para>
1003
1004     </section>
1005
1006     <section>
1007       <title>Examples</title>
1008
1009       <para>Source and target rectangles shall remain unchanged across
1010 closing and reopening a device, such that piping data into or out of a
1011 device will work without special preparations. More advanced
1012 applications should ensure the parameters are suitable before starting
1013 I/O.</para>
1014
1015       <example>
1016         <title>Resetting the cropping parameters</title>
1017
1018         <para>(A video capture device is assumed; change
1019 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other
1020 devices.)</para>
1021
1022         <programlisting>
1023 &v4l2-cropcap; cropcap;
1024 &v4l2-crop; crop;
1025
1026 memset (&amp;cropcap, 0, sizeof (cropcap));
1027 cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1028
1029 if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
1030         perror ("VIDIOC_CROPCAP");
1031         exit (EXIT_FAILURE);
1032 }
1033
1034 memset (&amp;crop, 0, sizeof (crop));
1035 crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1036 crop.c = cropcap.defrect;
1037
1038 /* Ignore if cropping is not supported (EINVAL). */
1039
1040 if (-1 == ioctl (fd, &VIDIOC-S-CROP;, &amp;crop)
1041     &amp;&amp; errno != EINVAL) {
1042         perror ("VIDIOC_S_CROP");
1043         exit (EXIT_FAILURE);
1044 }
1045       </programlisting>
1046       </example>
1047
1048       <example>
1049         <title>Simple downscaling</title>
1050
1051         <para>(A video capture device is assumed.)</para>
1052
1053         <programlisting>
1054 &v4l2-cropcap; cropcap;
1055 &v4l2-format; format;
1056
1057 reset_cropping_parameters ();
1058
1059 /* Scale down to 1/4 size of full picture. */
1060
1061 memset (&amp;format, 0, sizeof (format)); /* defaults */
1062
1063 format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1064
1065 format.fmt.pix.width = cropcap.defrect.width &gt;&gt; 1;
1066 format.fmt.pix.height = cropcap.defrect.height &gt;&gt; 1;
1067 format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
1068
1069 if (-1 == ioctl (fd, &VIDIOC-S-FMT;, &amp;format)) {
1070         perror ("VIDIOC_S_FORMAT");
1071         exit (EXIT_FAILURE);
1072 }
1073
1074 /* We could check the actual image size now, the actual scaling factor
1075    or if the driver can scale at all. */
1076         </programlisting>
1077       </example>
1078
1079       <example>
1080         <title>Selecting an output area</title>
1081
1082         <programlisting>
1083 &v4l2-cropcap; cropcap;
1084 &v4l2-crop; crop;
1085
1086 memset (&amp;cropcap, 0, sizeof (cropcap));
1087 cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
1088
1089 if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &amp;cropcap)) {
1090         perror ("VIDIOC_CROPCAP");
1091         exit (EXIT_FAILURE);
1092 }
1093
1094 memset (&amp;crop, 0, sizeof (crop));
1095
1096 crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
1097 crop.c = cropcap.defrect;
1098
1099 /* Scale the width and height to 50 % of their original size
1100    and center the output. */
1101
1102 crop.c.width /= 2;
1103 crop.c.height /= 2;
1104 crop.c.left += crop.c.width / 2;
1105 crop.c.top += crop.c.height / 2;
1106
1107 /* Ignore if cropping is not supported (EINVAL). */
1108
1109 if (-1 == ioctl (fd, VIDIOC_S_CROP, &amp;crop)
1110     &amp;&amp; errno != EINVAL) {
1111         perror ("VIDIOC_S_CROP");
1112         exit (EXIT_FAILURE);
1113 }
1114 </programlisting>
1115       </example>
1116
1117       <example>
1118         <title>Current scaling factor and pixel aspect</title>
1119
1120         <para>(A video capture device is assumed.)</para>
1121
1122         <programlisting>
1123 &v4l2-cropcap; cropcap;
1124 &v4l2-crop; crop;
1125 &v4l2-format; format;
1126 double hscale, vscale;
1127 double aspect;
1128 int dwidth, dheight;
1129
1130 memset (&amp;cropcap, 0, sizeof (cropcap));
1131 cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1132
1133 if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
1134         perror ("VIDIOC_CROPCAP");
1135         exit (EXIT_FAILURE);
1136 }
1137
1138 memset (&amp;crop, 0, sizeof (crop));
1139 crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1140
1141 if (-1 == ioctl (fd, &VIDIOC-G-CROP;, &amp;crop)) {
1142         if (errno != EINVAL) {
1143                 perror ("VIDIOC_G_CROP");
1144                 exit (EXIT_FAILURE);
1145         }
1146
1147         /* Cropping not supported. */
1148         crop.c = cropcap.defrect;
1149 }
1150
1151 memset (&amp;format, 0, sizeof (format));
1152 format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1153
1154 if (-1 == ioctl (fd, &VIDIOC-G-FMT;, &amp;format)) {
1155         perror ("VIDIOC_G_FMT");
1156         exit (EXIT_FAILURE);
1157 }
1158
1159 /* The scaling applied by the driver. */
1160
1161 hscale = format.fmt.pix.width / (double) crop.c.width;
1162 vscale = format.fmt.pix.height / (double) crop.c.height;
1163
1164 aspect = cropcap.pixelaspect.numerator /
1165          (double) cropcap.pixelaspect.denominator;
1166 aspect = aspect * hscale / vscale;
1167
1168 /* Devices following ITU-R BT.601 do not capture
1169    square pixels. For playback on a computer monitor
1170    we should scale the images to this size. */
1171
1172 dwidth = format.fmt.pix.width / aspect;
1173 dheight = format.fmt.pix.height;
1174         </programlisting>
1175       </example>
1176     </section>
1177   </section>
1178
1179   &sub-selection-api;
1180
1181   <section id="streaming-par">
1182     <title>Streaming Parameters</title>
1183
1184     <para>Streaming parameters are intended to optimize the video
1185 capture process as well as I/O. Presently applications can request a
1186 high quality capture mode with the &VIDIOC-S-PARM; ioctl.</para>
1187
1188     <para>The current video standard determines a nominal number of
1189 frames per second. If less than this number of frames is to be
1190 captured or output, applications can request frame skipping or
1191 duplicating on the driver side. This is especially useful when using
1192 the &func-read; or &func-write;, which are not augmented by timestamps
1193 or sequence counters, and to avoid unnecessary data copying.</para>
1194
1195     <para>Finally these ioctls can be used to determine the number of
1196 buffers used internally by a driver in read/write mode. For
1197 implications see the section discussing the &func-read;
1198 function.</para>
1199
1200     <para>To get and set the streaming parameters applications call
1201 the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; ioctl, respectively. They take
1202 a pointer to a &v4l2-streamparm;, which contains a union holding
1203 separate parameters for input and output devices.</para>
1204
1205     <para>These ioctls are optional, drivers need not implement
1206 them. If so, they return the &EINVAL;.</para>
1207   </section>