Merge branch 'v4l_for_linus' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab...
[linux-2.6.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 id="dv-timings">
728         <title>Digital Video (DV) Timings</title>
729         <para>
730         The video standards discussed so far has been dealing with Analog TV and the
731 corresponding video timings. Today there are many more different hardware interfaces
732 such as High Definition TV interfaces (HDMI), VGA, DVI connectors etc., that carry
733 video signals and there is a need to extend the API to select the video timings
734 for these interfaces. Since it is not possible to extend the &v4l2-std-id; due to
735 the limited bits available, a new set of IOCTLs is added to set/get video timings at
736 the input and output: </para><itemizedlist>
737         <listitem>
738         <para>DV Presets: Digital Video (DV) presets. These are IDs representing a
739 video timing at the input/output. Presets are pre-defined timings implemented
740 by the hardware according to video standards. A __u32 data type is used to represent
741 a preset unlike the bit mask that is used in &v4l2-std-id; allowing future extensions
742 to support as many different presets as needed.</para>
743         </listitem>
744         <listitem>
745         <para>Custom DV Timings: This will allow applications to define more detailed
746 custom video timings for the interface. This includes parameters such as width, height,
747 polarities, frontporch, backporch etc.
748         </para>
749         </listitem>
750         </itemizedlist>
751         <para>To enumerate and query the attributes of DV presets supported by a device,
752 applications use the &VIDIOC-ENUM-DV-PRESETS; ioctl. To get the current DV preset,
753 applications use the &VIDIOC-G-DV-PRESET; ioctl and to set a preset they use the
754 &VIDIOC-S-DV-PRESET; ioctl.</para>
755         <para>To set custom DV timings for the device, applications use the
756 &VIDIOC-S-DV-TIMINGS; ioctl and to get current custom DV timings they use the
757 &VIDIOC-G-DV-TIMINGS; ioctl.</para>
758         <para>Applications can make use of the <xref linkend="input-capabilities" /> and
759 <xref linkend="output-capabilities"/> flags to decide what ioctls are available to set the
760 video timings for the device.</para>
761         </section>
762   </section>
763
764   &sub-controls;
765
766   <section id="format">
767     <title>Data Formats</title>
768
769     <section>
770       <title>Data Format Negotiation</title>
771
772       <para>Different devices exchange different kinds of data with
773 applications, for example video images, raw or sliced VBI data, RDS
774 datagrams. Even within one kind many different formats are possible,
775 in particular an abundance of image formats. Although drivers must
776 provide a default and the selection persists across closing and
777 reopening a device, applications should always negotiate a data format
778 before engaging in data exchange. Negotiation means the application
779 asks for a particular format and the driver selects and reports the
780 best the hardware can do to satisfy the request. Of course
781 applications can also just query the current selection.</para>
782
783       <para>A single mechanism exists to negotiate all data formats
784 using the aggregate &v4l2-format; and the &VIDIOC-G-FMT; and
785 &VIDIOC-S-FMT; ioctls. Additionally the &VIDIOC-TRY-FMT; ioctl can be
786 used to examine what the hardware <emphasis>could</emphasis> do,
787 without actually selecting a new data format. The data formats
788 supported by the V4L2 API are covered in the respective device section
789 in <xref linkend="devices" />. For a closer look at image formats see
790 <xref linkend="pixfmt" />.</para>
791
792       <para>The <constant>VIDIOC_S_FMT</constant> ioctl is a major
793 turning-point in the initialization sequence. Prior to this point
794 multiple panel applications can access the same device concurrently to
795 select the current input, change controls or modify other properties.
796 The first <constant>VIDIOC_S_FMT</constant> assigns a logical stream
797 (video data, VBI data etc.) exclusively to one file descriptor.</para>
798
799       <para>Exclusive means no other application, more precisely no
800 other file descriptor, can grab this stream or change device
801 properties inconsistent with the negotiated parameters. A video
802 standard change for example, when the new standard uses a different
803 number of scan lines, can invalidate the selected image format.
804 Therefore only the file descriptor owning the stream can make
805 invalidating changes. Accordingly multiple file descriptors which
806 grabbed different logical streams prevent each other from interfering
807 with their settings. When for example video overlay is about to start
808 or already in progress, simultaneous video capturing may be restricted
809 to the same cropping and image size.</para>
810
811       <para>When applications omit the
812 <constant>VIDIOC_S_FMT</constant> ioctl its locking side effects are
813 implied by the next step, the selection of an I/O method with the
814 &VIDIOC-REQBUFS; ioctl or implicit with the first &func-read; or
815 &func-write; call.</para>
816
817       <para>Generally only one logical stream can be assigned to a
818 file descriptor, the exception being drivers permitting simultaneous
819 video capturing and overlay using the same file descriptor for
820 compatibility with V4L and earlier versions of V4L2. Switching the
821 logical stream or returning into "panel mode" is possible by closing
822 and reopening the device. Drivers <emphasis>may</emphasis> support a
823 switch using <constant>VIDIOC_S_FMT</constant>.</para>
824
825       <para>All drivers exchanging data with
826 applications must support the <constant>VIDIOC_G_FMT</constant> and
827 <constant>VIDIOC_S_FMT</constant> ioctl. Implementation of the
828 <constant>VIDIOC_TRY_FMT</constant> is highly recommended but
829 optional.</para>
830     </section>
831
832     <section>
833       <title>Image Format Enumeration</title>
834
835       <para>Apart of the generic format negotiation functions
836 a special ioctl to enumerate all image formats supported by video
837 capture, overlay or output devices is available.<footnote>
838           <para>Enumerating formats an application has no a-priori
839 knowledge of (otherwise it could explicitly ask for them and need not
840 enumerate) seems useless, but there are applications serving as proxy
841 between drivers and the actual video applications for which this is
842 useful.</para>
843         </footnote></para>
844
845       <para>The &VIDIOC-ENUM-FMT; ioctl must be supported
846 by all drivers exchanging image data with applications.</para>
847
848       <important>
849         <para>Drivers are not supposed to convert image formats in
850 kernel space. They must enumerate only formats directly supported by
851 the hardware. If necessary driver writers should publish an example
852 conversion routine or library for integration into applications.</para>
853       </important>
854     </section>
855   </section>
856
857   &sub-planar-apis;
858
859   <section id="crop">
860     <title>Image Cropping, Insertion and Scaling</title>
861
862     <para>Some video capture devices can sample a subsection of the
863 picture and shrink or enlarge it to an image of arbitrary size. We
864 call these abilities cropping and scaling. Some video output devices
865 can scale an image up or down and insert it at an arbitrary scan line
866 and horizontal offset into a video signal.</para>
867
868     <para>Applications can use the following API to select an area in
869 the video signal, query the default area and the hardware limits.
870 <emphasis>Despite their name, the &VIDIOC-CROPCAP;, &VIDIOC-G-CROP;
871 and &VIDIOC-S-CROP; ioctls apply to input as well as output
872 devices.</emphasis></para>
873
874     <para>Scaling requires a source and a target. On a video capture
875 or overlay device the source is the video signal, and the cropping
876 ioctls determine the area actually sampled. The target are images
877 read by the application or overlaid onto the graphics screen. Their
878 size (and position for an overlay) is negotiated with the
879 &VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls.</para>
880
881     <para>On a video output device the source are the images passed in
882 by the application, and their size is again negotiated with the
883 <constant>VIDIOC_G/S_FMT</constant> ioctls, or may be encoded in a
884 compressed video stream. The target is the video signal, and the
885 cropping ioctls determine the area where the images are
886 inserted.</para>
887
888     <para>Source and target rectangles are defined even if the device
889 does not support scaling or the <constant>VIDIOC_G/S_CROP</constant>
890 ioctls. Their size (and position where applicable) will be fixed in
891 this case. <emphasis>All capture and output device must support the
892 <constant>VIDIOC_CROPCAP</constant> ioctl such that applications can
893 determine if scaling takes place.</emphasis></para>
894
895     <section>
896       <title>Cropping Structures</title>
897
898       <figure id="crop-scale">
899         <title>Image Cropping, Insertion and Scaling</title>
900         <mediaobject>
901           <imageobject>
902             <imagedata fileref="crop.pdf" format="PS" />
903           </imageobject>
904           <imageobject>
905             <imagedata fileref="crop.gif" format="GIF" />
906           </imageobject>
907           <textobject>
908             <phrase>The cropping, insertion and scaling process</phrase>
909           </textobject>
910         </mediaobject>
911       </figure>
912
913       <para>For capture devices the coordinates of the top left
914 corner, width and height of the area which can be sampled is given by
915 the <structfield>bounds</structfield> substructure of the
916 &v4l2-cropcap; returned by the <constant>VIDIOC_CROPCAP</constant>
917 ioctl. To support a wide range of hardware this specification does not
918 define an origin or units. However by convention drivers should
919 horizontally count unscaled samples relative to 0H (the leading edge
920 of the horizontal sync pulse, see <xref linkend="vbi-hsync" />).
921 Vertically ITU-R line
922 numbers of the first field (<xref linkend="vbi-525" />, <xref
923 linkend="vbi-625" />), multiplied by two if the driver can capture both
924 fields.</para>
925
926       <para>The top left corner, width and height of the source
927 rectangle, that is the area actually sampled, is given by &v4l2-crop;
928 using the same coordinate system as &v4l2-cropcap;. Applications can
929 use the <constant>VIDIOC_G_CROP</constant> and
930 <constant>VIDIOC_S_CROP</constant> ioctls to get and set this
931 rectangle. It must lie completely within the capture boundaries and
932 the driver may further adjust the requested size and/or position
933 according to hardware limitations.</para>
934
935       <para>Each capture device has a default source rectangle, given
936 by the <structfield>defrect</structfield> substructure of
937 &v4l2-cropcap;. The center of this rectangle shall align with the
938 center of the active picture area of the video signal, and cover what
939 the driver writer considers the complete picture. Drivers shall reset
940 the source rectangle to the default when the driver is first loaded,
941 but not later.</para>
942
943       <para>For output devices these structures and ioctls are used
944 accordingly, defining the <emphasis>target</emphasis> rectangle where
945 the images will be inserted into the video signal.</para>
946
947     </section>
948
949     <section>
950       <title>Scaling Adjustments</title>
951
952       <para>Video hardware can have various cropping, insertion and
953 scaling limitations. It may only scale up or down, support only
954 discrete scaling factors, or have different scaling abilities in
955 horizontal and vertical direction. Also it may not support scaling at
956 all. At the same time the &v4l2-crop; rectangle may have to be
957 aligned, and both the source and target rectangles may have arbitrary
958 upper and lower size limits. In particular the maximum
959 <structfield>width</structfield> and <structfield>height</structfield>
960 in &v4l2-crop; may be smaller than the
961 &v4l2-cropcap;.<structfield>bounds</structfield> area. Therefore, as
962 usual, drivers are expected to adjust the requested parameters and
963 return the actual values selected.</para>
964
965       <para>Applications can change the source or the target rectangle
966 first, as they may prefer a particular image size or a certain area in
967 the video signal. If the driver has to adjust both to satisfy hardware
968 limitations, the last requested rectangle shall take priority, and the
969 driver should preferably adjust the opposite one. The &VIDIOC-TRY-FMT;
970 ioctl however shall not change the driver state and therefore only
971 adjust the requested rectangle.</para>
972
973       <para>Suppose scaling on a video capture device is restricted to
974 a factor 1:1 or 2:1 in either direction and the target image size must
975 be a multiple of 16&nbsp;&times;&nbsp;16 pixels. The source cropping
976 rectangle is set to defaults, which are also the upper limit in this
977 example, of 640&nbsp;&times;&nbsp;400 pixels at offset 0,&nbsp;0. An
978 application requests an image size of 300&nbsp;&times;&nbsp;225
979 pixels, assuming video will be scaled down from the "full picture"
980 accordingly. The driver sets the image size to the closest possible
981 values 304&nbsp;&times;&nbsp;224, then chooses the cropping rectangle
982 closest to the requested size, that is 608&nbsp;&times;&nbsp;224
983 (224&nbsp;&times;&nbsp;2:1 would exceed the limit 400). The offset
984 0,&nbsp;0 is still valid, thus unmodified. Given the default cropping
985 rectangle reported by <constant>VIDIOC_CROPCAP</constant> the
986 application can easily propose another offset to center the cropping
987 rectangle.</para>
988
989       <para>Now the application may insist on covering an area using a
990 picture aspect ratio closer to the original request, so it asks for a
991 cropping rectangle of 608&nbsp;&times;&nbsp;456 pixels. The present
992 scaling factors limit cropping to 640&nbsp;&times;&nbsp;384, so the
993 driver returns the cropping size 608&nbsp;&times;&nbsp;384 and adjusts
994 the image size to closest possible 304&nbsp;&times;&nbsp;192.</para>
995
996     </section>
997
998     <section>
999       <title>Examples</title>
1000
1001       <para>Source and target rectangles shall remain unchanged across
1002 closing and reopening a device, such that piping data into or out of a
1003 device will work without special preparations. More advanced
1004 applications should ensure the parameters are suitable before starting
1005 I/O.</para>
1006
1007       <example>
1008         <title>Resetting the cropping parameters</title>
1009
1010         <para>(A video capture device is assumed; change
1011 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other
1012 devices.)</para>
1013
1014         <programlisting>
1015 &v4l2-cropcap; cropcap;
1016 &v4l2-crop; crop;
1017
1018 memset (&amp;cropcap, 0, sizeof (cropcap));
1019 cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1020
1021 if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
1022         perror ("VIDIOC_CROPCAP");
1023         exit (EXIT_FAILURE);
1024 }
1025
1026 memset (&amp;crop, 0, sizeof (crop));
1027 crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1028 crop.c = cropcap.defrect;
1029
1030 /* Ignore if cropping is not supported (EINVAL). */
1031
1032 if (-1 == ioctl (fd, &VIDIOC-S-CROP;, &amp;crop)
1033     &amp;&amp; errno != EINVAL) {
1034         perror ("VIDIOC_S_CROP");
1035         exit (EXIT_FAILURE);
1036 }
1037       </programlisting>
1038       </example>
1039
1040       <example>
1041         <title>Simple downscaling</title>
1042
1043         <para>(A video capture device is assumed.)</para>
1044
1045         <programlisting>
1046 &v4l2-cropcap; cropcap;
1047 &v4l2-format; format;
1048
1049 reset_cropping_parameters ();
1050
1051 /* Scale down to 1/4 size of full picture. */
1052
1053 memset (&amp;format, 0, sizeof (format)); /* defaults */
1054
1055 format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1056
1057 format.fmt.pix.width = cropcap.defrect.width &gt;&gt; 1;
1058 format.fmt.pix.height = cropcap.defrect.height &gt;&gt; 1;
1059 format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
1060
1061 if (-1 == ioctl (fd, &VIDIOC-S-FMT;, &amp;format)) {
1062         perror ("VIDIOC_S_FORMAT");
1063         exit (EXIT_FAILURE);
1064 }
1065
1066 /* We could check the actual image size now, the actual scaling factor
1067    or if the driver can scale at all. */
1068         </programlisting>
1069       </example>
1070
1071       <example>
1072         <title>Selecting an output area</title>
1073
1074         <programlisting>
1075 &v4l2-cropcap; cropcap;
1076 &v4l2-crop; crop;
1077
1078 memset (&amp;cropcap, 0, sizeof (cropcap));
1079 cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
1080
1081 if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &amp;cropcap)) {
1082         perror ("VIDIOC_CROPCAP");
1083         exit (EXIT_FAILURE);
1084 }
1085
1086 memset (&amp;crop, 0, sizeof (crop));
1087
1088 crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
1089 crop.c = cropcap.defrect;
1090
1091 /* Scale the width and height to 50 % of their original size
1092    and center the output. */
1093
1094 crop.c.width /= 2;
1095 crop.c.height /= 2;
1096 crop.c.left += crop.c.width / 2;
1097 crop.c.top += crop.c.height / 2;
1098
1099 /* Ignore if cropping is not supported (EINVAL). */
1100
1101 if (-1 == ioctl (fd, VIDIOC_S_CROP, &amp;crop)
1102     &amp;&amp; errno != EINVAL) {
1103         perror ("VIDIOC_S_CROP");
1104         exit (EXIT_FAILURE);
1105 }
1106 </programlisting>
1107       </example>
1108
1109       <example>
1110         <title>Current scaling factor and pixel aspect</title>
1111
1112         <para>(A video capture device is assumed.)</para>
1113
1114         <programlisting>
1115 &v4l2-cropcap; cropcap;
1116 &v4l2-crop; crop;
1117 &v4l2-format; format;
1118 double hscale, vscale;
1119 double aspect;
1120 int dwidth, dheight;
1121
1122 memset (&amp;cropcap, 0, sizeof (cropcap));
1123 cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1124
1125 if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
1126         perror ("VIDIOC_CROPCAP");
1127         exit (EXIT_FAILURE);
1128 }
1129
1130 memset (&amp;crop, 0, sizeof (crop));
1131 crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1132
1133 if (-1 == ioctl (fd, &VIDIOC-G-CROP;, &amp;crop)) {
1134         if (errno != EINVAL) {
1135                 perror ("VIDIOC_G_CROP");
1136                 exit (EXIT_FAILURE);
1137         }
1138
1139         /* Cropping not supported. */
1140         crop.c = cropcap.defrect;
1141 }
1142
1143 memset (&amp;format, 0, sizeof (format));
1144 format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1145
1146 if (-1 == ioctl (fd, &VIDIOC-G-FMT;, &amp;format)) {
1147         perror ("VIDIOC_G_FMT");
1148         exit (EXIT_FAILURE);
1149 }
1150
1151 /* The scaling applied by the driver. */
1152
1153 hscale = format.fmt.pix.width / (double) crop.c.width;
1154 vscale = format.fmt.pix.height / (double) crop.c.height;
1155
1156 aspect = cropcap.pixelaspect.numerator /
1157          (double) cropcap.pixelaspect.denominator;
1158 aspect = aspect * hscale / vscale;
1159
1160 /* Devices following ITU-R BT.601 do not capture
1161    square pixels. For playback on a computer monitor
1162    we should scale the images to this size. */
1163
1164 dwidth = format.fmt.pix.width / aspect;
1165 dheight = format.fmt.pix.height;
1166         </programlisting>
1167       </example>
1168     </section>
1169   </section>
1170
1171   &sub-selection-api;
1172
1173   <section id="streaming-par">
1174     <title>Streaming Parameters</title>
1175
1176     <para>Streaming parameters are intended to optimize the video
1177 capture process as well as I/O. Presently applications can request a
1178 high quality capture mode with the &VIDIOC-S-PARM; ioctl.</para>
1179
1180     <para>The current video standard determines a nominal number of
1181 frames per second. If less than this number of frames is to be
1182 captured or output, applications can request frame skipping or
1183 duplicating on the driver side. This is especially useful when using
1184 the &func-read; or &func-write;, which are not augmented by timestamps
1185 or sequence counters, and to avoid unnecessary data copying.</para>
1186
1187     <para>Finally these ioctls can be used to determine the number of
1188 buffers used internally by a driver in read/write mode. For
1189 implications see the section discussing the &func-read;
1190 function.</para>
1191
1192     <para>To get and set the streaming parameters applications call
1193 the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; ioctl, respectively. They take
1194 a pointer to a &v4l2-streamparm;, which contains a union holding
1195 separate parameters for input and output devices.</para>
1196
1197     <para>These ioctls are optional, drivers need not implement
1198 them. If so, they return the &EINVAL;.</para>
1199   </section>