Merge branch 'x86-cpu-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git...
[linux-2.6.git] / Documentation / DocBook / 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 recomended 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. Other features can be queried
240 by calling the respective ioctl, for example &VIDIOC-ENUMINPUT;
241 to learn about the number, types and names of video connectors on the
242 device. Although abstraction is a major objective of this API, the
243 ioctl also allows driver specific applications to reliable identify
244 the driver.</para>
245
246     <para>All V4L2 drivers must support
247 <constant>VIDIOC_QUERYCAP</constant>. Applications should always call
248 this ioctl after opening the device.</para>
249   </section>
250
251   <section id="app-pri">
252     <title>Application Priority</title>
253
254     <para>When multiple applications share a device it may be
255 desirable to assign them different priorities. Contrary to the
256 traditional "rm -rf /" school of thought a video recording application
257 could for example block other applications from changing video
258 controls or switching the current TV channel. Another objective is to
259 permit low priority applications working in background, which can be
260 preempted by user controlled applications and automatically regain
261 control of the device at a later time.</para>
262
263     <para>Since these features cannot be implemented entirely in user
264 space V4L2 defines the &VIDIOC-G-PRIORITY; and &VIDIOC-S-PRIORITY;
265 ioctls to request and query the access priority associate with a file
266 descriptor. Opening a device assigns a medium priority, compatible
267 with earlier versions of V4L2 and drivers not supporting these ioctls.
268 Applications requiring a different priority will usually call
269 <constant>VIDIOC_S_PRIORITY</constant> after verifying the device with
270 the &VIDIOC-QUERYCAP; ioctl.</para>
271
272     <para>Ioctls changing driver properties, such as &VIDIOC-S-INPUT;,
273 return an &EBUSY; after another application obtained higher priority.
274 An event mechanism to notify applications about asynchronous property
275 changes has been proposed but not added yet.</para>
276   </section>
277
278   <section id="video">
279     <title>Video Inputs and Outputs</title>
280
281     <para>Video inputs and outputs are physical connectors of a
282 device. These can be for example RF connectors (antenna/cable), CVBS
283 a.k.a. Composite Video, S-Video or RGB connectors. Only video and VBI
284 capture devices have inputs, output devices have outputs, at least one
285 each. Radio devices have no video inputs or outputs.</para>
286
287     <para>To learn about the number and attributes of the
288 available inputs and outputs applications can enumerate them with the
289 &VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; ioctl, respectively. The
290 &v4l2-input; returned by the <constant>VIDIOC_ENUMINPUT</constant>
291 ioctl also contains signal status information applicable when the
292 current video input is queried.</para>
293
294     <para>The &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; ioctl return the
295 index of the current video input or output. To select a different
296 input or output applications call the &VIDIOC-S-INPUT; and
297 &VIDIOC-S-OUTPUT; ioctl. Drivers must implement all the input ioctls
298 when the device has one or more inputs, all the output ioctls when the
299 device has one or more outputs.</para>
300
301     <!--
302     <figure id=io-tree>
303       <title>Input and output enumeration is the root of most device properties.</title>
304       <mediaobject>
305         <imageobject>
306           <imagedata fileref="links.pdf" format="ps" />
307         </imageobject>
308         <imageobject>
309           <imagedata fileref="links.gif" format="gif" />
310         </imageobject>
311         <textobject>
312           <phrase>Links between various device property structures.</phrase>
313         </textobject>
314       </mediaobject>
315     </figure>
316     -->
317
318     <example>
319       <title>Information about the current video input</title>
320
321       <programlisting>
322 &v4l2-input; input;
323 int index;
324
325 if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;index)) {
326         perror ("VIDIOC_G_INPUT");
327         exit (EXIT_FAILURE);
328 }
329
330 memset (&amp;input, 0, sizeof (input));
331 input.index = index;
332
333 if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
334         perror ("VIDIOC_ENUMINPUT");
335         exit (EXIT_FAILURE);
336 }
337
338 printf ("Current input: %s\n", input.name);
339       </programlisting>
340     </example>
341
342     <example>
343       <title>Switching to the first video input</title>
344
345       <programlisting>
346 int index;
347
348 index = 0;
349
350 if (-1 == ioctl (fd, &VIDIOC-S-INPUT;, &amp;index)) {
351         perror ("VIDIOC_S_INPUT");
352         exit (EXIT_FAILURE);
353 }
354       </programlisting>
355     </example>
356   </section>
357
358   <section id="audio">
359     <title>Audio Inputs and Outputs</title>
360
361     <para>Audio inputs and outputs are physical connectors of a
362 device. Video capture devices have inputs, output devices have
363 outputs, zero or more each. Radio devices have no audio inputs or
364 outputs. They have exactly one tuner which in fact
365 <emphasis>is</emphasis> an audio source, but this API associates
366 tuners with video inputs or outputs only, and radio devices have
367 none of these.<footnote>
368         <para>Actually &v4l2-audio; ought to have a
369 <structfield>tuner</structfield> field like &v4l2-input;, not only
370 making the API more consistent but also permitting radio devices with
371 multiple tuners.</para>
372       </footnote> A connector on a TV card to loop back the received
373 audio signal to a sound card is not considered an audio output.</para>
374
375     <para>Audio and video inputs and outputs are associated. Selecting
376 a video source also selects an audio source. This is most evident when
377 the video and audio source is a tuner. Further audio connectors can
378 combine with more than one video input or output. Assumed two
379 composite video inputs and two audio inputs exist, there may be up to
380 four valid combinations. The relation of video and audio connectors
381 is defined in the <structfield>audioset</structfield> field of the
382 respective &v4l2-input; or &v4l2-output;, where each bit represents
383 the index number, starting at zero, of one audio input or output.</para>
384
385     <para>To learn about the number and attributes of the
386 available inputs and outputs applications can enumerate them with the
387 &VIDIOC-ENUMAUDIO; and &VIDIOC-ENUMAUDOUT; ioctl, respectively. The
388 &v4l2-audio; returned by the <constant>VIDIOC_ENUMAUDIO</constant> ioctl
389 also contains signal status information applicable when the current
390 audio input is queried.</para>
391
392     <para>The &VIDIOC-G-AUDIO; and &VIDIOC-G-AUDOUT; ioctl report
393 the current audio input and output, respectively. Note that, unlike
394 &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; these ioctls return a structure
395 as <constant>VIDIOC_ENUMAUDIO</constant> and
396 <constant>VIDIOC_ENUMAUDOUT</constant> do, not just an index.</para>
397
398     <para>To select an audio input and change its properties
399 applications call the &VIDIOC-S-AUDIO; ioctl. To select an audio
400 output (which presently has no changeable properties) applications
401 call the &VIDIOC-S-AUDOUT; ioctl.</para>
402
403     <para>Drivers must implement all input ioctls when the device
404 has one or more inputs, all output ioctls when the device has one
405 or more outputs. When the device has any audio inputs or outputs the
406 driver must set the <constant>V4L2_CAP_AUDIO</constant> flag in the
407 &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl.</para>
408
409     <example>
410       <title>Information about the current audio input</title>
411
412       <programlisting>
413 &v4l2-audio; audio;
414
415 memset (&amp;audio, 0, sizeof (audio));
416
417 if (-1 == ioctl (fd, &VIDIOC-G-AUDIO;, &amp;audio)) {
418         perror ("VIDIOC_G_AUDIO");
419         exit (EXIT_FAILURE);
420 }
421
422 printf ("Current input: %s\n", audio.name);
423       </programlisting>
424     </example>
425
426     <example>
427       <title>Switching to the first audio input</title>
428
429       <programlisting>
430 &v4l2-audio; audio;
431
432 memset (&amp;audio, 0, sizeof (audio)); /* clear audio.mode, audio.reserved */
433
434 audio.index = 0;
435
436 if (-1 == ioctl (fd, &VIDIOC-S-AUDIO;, &amp;audio)) {
437         perror ("VIDIOC_S_AUDIO");
438         exit (EXIT_FAILURE);
439 }
440       </programlisting>
441     </example>
442   </section>
443
444   <section id="tuner">
445     <title>Tuners and Modulators</title>
446
447     <section>
448       <title>Tuners</title>
449
450       <para>Video input devices can have one or more tuners
451 demodulating a RF signal. Each tuner is associated with one or more
452 video inputs, depending on the number of RF connectors on the tuner.
453 The <structfield>type</structfield> field of the respective
454 &v4l2-input; returned by the &VIDIOC-ENUMINPUT; ioctl is set to
455 <constant>V4L2_INPUT_TYPE_TUNER</constant> and its
456 <structfield>tuner</structfield> field contains the index number of
457 the tuner.</para>
458
459       <para>Radio devices have exactly one tuner with index zero, no
460 video inputs.</para>
461
462       <para>To query and change tuner properties applications use the
463 &VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctl, respectively. The
464 &v4l2-tuner; returned by <constant>VIDIOC_G_TUNER</constant> also
465 contains signal status information applicable when the tuner of the
466 current video input, or a radio tuner is queried. Note that
467 <constant>VIDIOC_S_TUNER</constant> does not switch the current tuner,
468 when there is more than one at all. The tuner is solely determined by
469 the current video input. Drivers must support both ioctls and set the
470 <constant>V4L2_CAP_TUNER</constant> flag in the &v4l2-capability;
471 returned by the &VIDIOC-QUERYCAP; ioctl when the device has one or
472 more tuners.</para>
473     </section>
474
475     <section>
476       <title>Modulators</title>
477
478       <para>Video output devices can have one or more modulators, uh,
479 modulating a video signal for radiation or connection to the antenna
480 input of a TV set or video recorder. Each modulator is associated with
481 one or more video outputs, depending on the number of RF connectors on
482 the modulator. The <structfield>type</structfield> field of the
483 respective &v4l2-output; returned by the &VIDIOC-ENUMOUTPUT; ioctl is
484 set to <constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> and its
485 <structfield>modulator</structfield> field contains the index number
486 of the modulator. This specification does not define radio output
487 devices.</para>
488
489       <para>To query and change modulator properties applications use
490 the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that
491 <constant>VIDIOC_S_MODULATOR</constant> does not switch the current
492 modulator, when there is more than one at all. The modulator is solely
493 determined by the current video output. Drivers must support both
494 ioctls and set the <constant>V4L2_CAP_MODULATOR</constant> flag in
495 the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl when the
496 device has one or more modulators.</para>
497     </section>
498
499     <section>
500       <title>Radio Frequency</title>
501
502       <para>To get and set the tuner or modulator radio frequency
503 applications use the &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY;
504 ioctl which both take a pointer to a &v4l2-frequency;. These ioctls
505 are used for TV and radio devices alike. Drivers must support both
506 ioctls when the tuner or modulator ioctls are supported, or
507 when the device is a radio device.</para>
508     </section>
509   </section>
510
511   <section id="standard">
512     <title>Video Standards</title>
513
514     <para>Video devices typically support one or more different video
515 standards or variations of standards. Each video input and output may
516 support another set of standards. This set is reported by the
517 <structfield>std</structfield> field of &v4l2-input; and
518 &v4l2-output; returned by the &VIDIOC-ENUMINPUT; and
519 &VIDIOC-ENUMOUTPUT; ioctl, respectively.</para>
520
521     <para>V4L2 defines one bit for each analog video standard
522 currently in use worldwide, and sets aside bits for driver defined
523 standards, &eg; hybrid standards to watch NTSC video tapes on PAL TVs
524 and vice versa. Applications can use the predefined bits to select a
525 particular standard, although presenting the user a menu of supported
526 standards is preferred. To enumerate and query the attributes of the
527 supported standards applications use the &VIDIOC-ENUMSTD; ioctl.</para>
528
529     <para>Many of the defined standards are actually just variations
530 of a few major standards. The hardware may in fact not distinguish
531 between them, or do so internal and switch automatically. Therefore
532 enumerated standards also contain sets of one or more standard
533 bits.</para>
534
535     <para>Assume a hypothetic tuner capable of demodulating B/PAL,
536 G/PAL and I/PAL signals. The first enumerated standard is a set of B
537 and G/PAL, switched automatically depending on the selected radio
538 frequency in UHF or VHF band. Enumeration gives a "PAL-B/G" or "PAL-I"
539 choice. Similar a Composite input may collapse standards, enumerating
540 "PAL-B/G/H/I", "NTSC-M" and "SECAM-D/K".<footnote>
541         <para>Some users are already confused by technical terms PAL,
542 NTSC and SECAM. There is no point asking them to distinguish between
543 B, G, D, or K when the software or hardware can do that
544 automatically.</para>
545     </footnote></para>
546
547     <para>To query and select the standard used by the current video
548 input or output applications call the &VIDIOC-G-STD; and
549 &VIDIOC-S-STD; ioctl, respectively. The <emphasis>received</emphasis>
550 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>
551         <para>An alternative to the current scheme is to use pointers
552 to indices as arguments of <constant>VIDIOC_G_STD</constant> and
553 <constant>VIDIOC_S_STD</constant>, the &v4l2-input; and
554 &v4l2-output; <structfield>std</structfield> field would be a set of
555 indices like <structfield>audioset</structfield>.</para>
556         <para>Indices are consistent with the rest of the API
557 and identify the standard unambiguously. In the present scheme of
558 things an enumerated standard is looked up by &v4l2-std-id;. Now the
559 standards supported by the inputs of a device can overlap. Just
560 assume the tuner and composite input in the example above both
561 exist on a device. An enumeration of "PAL-B/G", "PAL-H/I" suggests
562 a choice which does not exist. We cannot merge or omit sets, because
563 applications would be unable to find the standards reported by
564 <constant>VIDIOC_G_STD</constant>. That leaves separate enumerations
565 for each input. Also selecting a standard by &v4l2-std-id; can be
566 ambiguous. Advantage of this method is that applications need not
567 identify the standard indirectly, after enumerating.</para><para>So in
568 summary, the lookup itself is unavoidable. The difference is only
569 whether the lookup is necessary to find an enumerated standard or to
570 switch to a standard by &v4l2-std-id;.</para>
571       </footnote> Drivers must implement all video standard ioctls
572 when the device has one or more video inputs or outputs.</para>
573
574     <para>Special rules apply to USB cameras where the notion of video
575 standards makes little sense. More generally any capture device,
576 output devices accordingly, which is <itemizedlist>
577         <listitem>
578           <para>incapable of capturing fields or frames at the nominal
579 rate of the video standard, or</para>
580         </listitem>
581         <listitem>
582           <para>where <link linkend="buffer">timestamps</link> refer
583 to the instant the field or frame was received by the driver, not the
584 capture time, or</para>
585         </listitem>
586         <listitem>
587           <para>where <link linkend="buffer">sequence numbers</link>
588 refer to the frames received by the driver, not the captured
589 frames.</para>
590         </listitem>
591       </itemizedlist> Here the driver shall set the
592 <structfield>std</structfield> field of &v4l2-input; and &v4l2-output;
593 to zero, the <constant>VIDIOC_G_STD</constant>,
594 <constant>VIDIOC_S_STD</constant>,
595 <constant>VIDIOC_QUERYSTD</constant> and
596 <constant>VIDIOC_ENUMSTD</constant> ioctls shall return the
597 &EINVAL;.<footnote>
598         <para>See <xref linkend="buffer" /> for a rationale. Probably
599 even USB cameras follow some well known video standard. It might have
600 been better to explicitly indicate elsewhere if a device cannot live
601 up to normal expectations, instead of this exception.</para>
602             </footnote></para>
603
604     <example>
605       <title>Information about the current video standard</title>
606
607       <programlisting>
608 &v4l2-std-id; std_id;
609 &v4l2-standard; standard;
610
611 if (-1 == ioctl (fd, &VIDIOC-G-STD;, &amp;std_id)) {
612         /* Note when VIDIOC_ENUMSTD always returns EINVAL this
613            is no video device or it falls under the USB exception,
614            and VIDIOC_G_STD returning EINVAL is no error. */
615
616         perror ("VIDIOC_G_STD");
617         exit (EXIT_FAILURE);
618 }
619
620 memset (&amp;standard, 0, sizeof (standard));
621 standard.index = 0;
622
623 while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
624         if (standard.id &amp; std_id) {
625                printf ("Current video standard: %s\n", standard.name);
626                exit (EXIT_SUCCESS);
627         }
628
629         standard.index++;
630 }
631
632 /* EINVAL indicates the end of the enumeration, which cannot be
633    empty unless this device falls under the USB exception. */
634
635 if (errno == EINVAL || standard.index == 0) {
636         perror ("VIDIOC_ENUMSTD");
637         exit (EXIT_FAILURE);
638 }
639       </programlisting>
640     </example>
641
642     <example>
643       <title>Listing the video standards supported by the current
644 input</title>
645
646       <programlisting>
647 &v4l2-input; input;
648 &v4l2-standard; standard;
649
650 memset (&amp;input, 0, sizeof (input));
651
652 if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
653         perror ("VIDIOC_G_INPUT");
654         exit (EXIT_FAILURE);
655 }
656
657 if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
658         perror ("VIDIOC_ENUM_INPUT");
659         exit (EXIT_FAILURE);
660 }
661
662 printf ("Current input %s supports:\n", input.name);
663
664 memset (&amp;standard, 0, sizeof (standard));
665 standard.index = 0;
666
667 while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
668         if (standard.id &amp; input.std)
669                 printf ("%s\n", standard.name);
670
671         standard.index++;
672 }
673
674 /* EINVAL indicates the end of the enumeration, which cannot be
675    empty unless this device falls under the USB exception. */
676
677 if (errno != EINVAL || standard.index == 0) {
678         perror ("VIDIOC_ENUMSTD");
679         exit (EXIT_FAILURE);
680 }
681       </programlisting>
682     </example>
683
684     <example>
685       <title>Selecting a new video standard</title>
686
687       <programlisting>
688 &v4l2-input; input;
689 &v4l2-std-id; std_id;
690
691 memset (&amp;input, 0, sizeof (input));
692
693 if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
694         perror ("VIDIOC_G_INPUT");
695         exit (EXIT_FAILURE);
696 }
697
698 if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
699         perror ("VIDIOC_ENUM_INPUT");
700         exit (EXIT_FAILURE);
701 }
702
703 if (0 == (input.std &amp; V4L2_STD_PAL_BG)) {
704         fprintf (stderr, "Oops. B/G PAL is not supported.\n");
705         exit (EXIT_FAILURE);
706 }
707
708 /* Note this is also supposed to work when only B
709    <emphasis>or</emphasis> G/PAL is supported. */
710
711 std_id = V4L2_STD_PAL_BG;
712
713 if (-1 == ioctl (fd, &VIDIOC-S-STD;, &amp;std_id)) {
714         perror ("VIDIOC_S_STD");
715         exit (EXIT_FAILURE);
716 }
717       </programlisting>
718     </example>
719   </section>
720
721   &sub-controls;
722
723   <section id="format">
724     <title>Data Formats</title>
725
726     <section>
727       <title>Data Format Negotiation</title>
728
729       <para>Different devices exchange different kinds of data with
730 applications, for example video images, raw or sliced VBI data, RDS
731 datagrams. Even within one kind many different formats are possible,
732 in particular an abundance of image formats. Although drivers must
733 provide a default and the selection persists across closing and
734 reopening a device, applications should always negotiate a data format
735 before engaging in data exchange. Negotiation means the application
736 asks for a particular format and the driver selects and reports the
737 best the hardware can do to satisfy the request. Of course
738 applications can also just query the current selection.</para>
739
740       <para>A single mechanism exists to negotiate all data formats
741 using the aggregate &v4l2-format; and the &VIDIOC-G-FMT; and
742 &VIDIOC-S-FMT; ioctls. Additionally the &VIDIOC-TRY-FMT; ioctl can be
743 used to examine what the hardware <emphasis>could</emphasis> do,
744 without actually selecting a new data format. The data formats
745 supported by the V4L2 API are covered in the respective device section
746 in <xref linkend="devices" />. For a closer look at image formats see
747 <xref linkend="pixfmt" />.</para>
748
749       <para>The <constant>VIDIOC_S_FMT</constant> ioctl is a major
750 turning-point in the initialization sequence. Prior to this point
751 multiple panel applications can access the same device concurrently to
752 select the current input, change controls or modify other properties.
753 The first <constant>VIDIOC_S_FMT</constant> assigns a logical stream
754 (video data, VBI data etc.) exclusively to one file descriptor.</para>
755
756       <para>Exclusive means no other application, more precisely no
757 other file descriptor, can grab this stream or change device
758 properties inconsistent with the negotiated parameters. A video
759 standard change for example, when the new standard uses a different
760 number of scan lines, can invalidate the selected image format.
761 Therefore only the file descriptor owning the stream can make
762 invalidating changes. Accordingly multiple file descriptors which
763 grabbed different logical streams prevent each other from interfering
764 with their settings. When for example video overlay is about to start
765 or already in progress, simultaneous video capturing may be restricted
766 to the same cropping and image size.</para>
767
768       <para>When applications omit the
769 <constant>VIDIOC_S_FMT</constant> ioctl its locking side effects are
770 implied by the next step, the selection of an I/O method with the
771 &VIDIOC-REQBUFS; ioctl or implicit with the first &func-read; or
772 &func-write; call.</para>
773
774       <para>Generally only one logical stream can be assigned to a
775 file descriptor, the exception being drivers permitting simultaneous
776 video capturing and overlay using the same file descriptor for
777 compatibility with V4L and earlier versions of V4L2. Switching the
778 logical stream or returning into "panel mode" is possible by closing
779 and reopening the device. Drivers <emphasis>may</emphasis> support a
780 switch using <constant>VIDIOC_S_FMT</constant>.</para>
781
782       <para>All drivers exchanging data with
783 applications must support the <constant>VIDIOC_G_FMT</constant> and
784 <constant>VIDIOC_S_FMT</constant> ioctl. Implementation of the
785 <constant>VIDIOC_TRY_FMT</constant> is highly recommended but
786 optional.</para>
787     </section>
788
789     <section>
790       <title>Image Format Enumeration</title>
791
792       <para>Apart of the generic format negotiation functions
793 a special ioctl to enumerate all image formats supported by video
794 capture, overlay or output devices is available.<footnote>
795           <para>Enumerating formats an application has no a-priori
796 knowledge of (otherwise it could explicitly ask for them and need not
797 enumerate) seems useless, but there are applications serving as proxy
798 between drivers and the actual video applications for which this is
799 useful.</para>
800         </footnote></para>
801
802       <para>The &VIDIOC-ENUM-FMT; ioctl must be supported
803 by all drivers exchanging image data with applications.</para>
804
805       <important>
806         <para>Drivers are not supposed to convert image formats in
807 kernel space. They must enumerate only formats directly supported by
808 the hardware. If necessary driver writers should publish an example
809 conversion routine or library for integration into applications.</para>
810       </important>
811     </section>
812   </section>
813
814   <section id="crop">
815     <title>Image Cropping, Insertion and Scaling</title>
816
817     <para>Some video capture devices can sample a subsection of the
818 picture and shrink or enlarge it to an image of arbitrary size. We
819 call these abilities cropping and scaling. Some video output devices
820 can scale an image up or down and insert it at an arbitrary scan line
821 and horizontal offset into a video signal.</para>
822
823     <para>Applications can use the following API to select an area in
824 the video signal, query the default area and the hardware limits.
825 <emphasis>Despite their name, the &VIDIOC-CROPCAP;, &VIDIOC-G-CROP;
826 and &VIDIOC-S-CROP; ioctls apply to input as well as output
827 devices.</emphasis></para>
828
829     <para>Scaling requires a source and a target. On a video capture
830 or overlay device the source is the video signal, and the cropping
831 ioctls determine the area actually sampled. The target are images
832 read by the application or overlaid onto the graphics screen. Their
833 size (and position for an overlay) is negotiated with the
834 &VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls.</para>
835
836     <para>On a video output device the source are the images passed in
837 by the application, and their size is again negotiated with the
838 <constant>VIDIOC_G/S_FMT</constant> ioctls, or may be encoded in a
839 compressed video stream. The target is the video signal, and the
840 cropping ioctls determine the area where the images are
841 inserted.</para>
842
843     <para>Source and target rectangles are defined even if the device
844 does not support scaling or the <constant>VIDIOC_G/S_CROP</constant>
845 ioctls. Their size (and position where applicable) will be fixed in
846 this case. <emphasis>All capture and output device must support the
847 <constant>VIDIOC_CROPCAP</constant> ioctl such that applications can
848 determine if scaling takes place.</emphasis></para>
849
850     <section>
851       <title>Cropping Structures</title>
852
853       <figure id="crop-scale">
854         <title>Image Cropping, Insertion and Scaling</title>
855         <mediaobject>
856           <imageobject>
857             <imagedata fileref="crop.pdf" format="PS" />
858           </imageobject>
859           <imageobject>
860             <imagedata fileref="crop.gif" format="GIF" />
861           </imageobject>
862           <textobject>
863             <phrase>The cropping, insertion and scaling process</phrase>
864           </textobject>
865         </mediaobject>
866       </figure>
867
868       <para>For capture devices the coordinates of the top left
869 corner, width and height of the area which can be sampled is given by
870 the <structfield>bounds</structfield> substructure of the
871 &v4l2-cropcap; returned by the <constant>VIDIOC_CROPCAP</constant>
872 ioctl. To support a wide range of hardware this specification does not
873 define an origin or units. However by convention drivers should
874 horizontally count unscaled samples relative to 0H (the leading edge
875 of the horizontal sync pulse, see <xref linkend="vbi-hsync" />).
876 Vertically ITU-R line
877 numbers of the first field (<xref linkend="vbi-525" />, <xref
878 linkend="vbi-625" />), multiplied by two if the driver can capture both
879 fields.</para>
880
881       <para>The top left corner, width and height of the source
882 rectangle, that is the area actually sampled, is given by &v4l2-crop;
883 using the same coordinate system as &v4l2-cropcap;. Applications can
884 use the <constant>VIDIOC_G_CROP</constant> and
885 <constant>VIDIOC_S_CROP</constant> ioctls to get and set this
886 rectangle. It must lie completely within the capture boundaries and
887 the driver may further adjust the requested size and/or position
888 according to hardware limitations.</para>
889
890       <para>Each capture device has a default source rectangle, given
891 by the <structfield>defrect</structfield> substructure of
892 &v4l2-cropcap;. The center of this rectangle shall align with the
893 center of the active picture area of the video signal, and cover what
894 the driver writer considers the complete picture. Drivers shall reset
895 the source rectangle to the default when the driver is first loaded,
896 but not later.</para>
897
898       <para>For output devices these structures and ioctls are used
899 accordingly, defining the <emphasis>target</emphasis> rectangle where
900 the images will be inserted into the video signal.</para>
901
902     </section>
903
904     <section>
905       <title>Scaling Adjustments</title>
906
907       <para>Video hardware can have various cropping, insertion and
908 scaling limitations. It may only scale up or down, support only
909 discrete scaling factors, or have different scaling abilities in
910 horizontal and vertical direction. Also it may not support scaling at
911 all. At the same time the &v4l2-crop; rectangle may have to be
912 aligned, and both the source and target rectangles may have arbitrary
913 upper and lower size limits. In particular the maximum
914 <structfield>width</structfield> and <structfield>height</structfield>
915 in &v4l2-crop; may be smaller than the
916 &v4l2-cropcap;.<structfield>bounds</structfield> area. Therefore, as
917 usual, drivers are expected to adjust the requested parameters and
918 return the actual values selected.</para>
919
920       <para>Applications can change the source or the target rectangle
921 first, as they may prefer a particular image size or a certain area in
922 the video signal. If the driver has to adjust both to satisfy hardware
923 limitations, the last requested rectangle shall take priority, and the
924 driver should preferably adjust the opposite one. The &VIDIOC-TRY-FMT;
925 ioctl however shall not change the driver state and therefore only
926 adjust the requested rectangle.</para>
927
928       <para>Suppose scaling on a video capture device is restricted to
929 a factor 1:1 or 2:1 in either direction and the target image size must
930 be a multiple of 16&nbsp;&times;&nbsp;16 pixels. The source cropping
931 rectangle is set to defaults, which are also the upper limit in this
932 example, of 640&nbsp;&times;&nbsp;400 pixels at offset 0,&nbsp;0. An
933 application requests an image size of 300&nbsp;&times;&nbsp;225
934 pixels, assuming video will be scaled down from the "full picture"
935 accordingly. The driver sets the image size to the closest possible
936 values 304&nbsp;&times;&nbsp;224, then chooses the cropping rectangle
937 closest to the requested size, that is 608&nbsp;&times;&nbsp;224
938 (224&nbsp;&times;&nbsp;2:1 would exceed the limit 400). The offset
939 0,&nbsp;0 is still valid, thus unmodified. Given the default cropping
940 rectangle reported by <constant>VIDIOC_CROPCAP</constant> the
941 application can easily propose another offset to center the cropping
942 rectangle.</para>
943
944       <para>Now the application may insist on covering an area using a
945 picture aspect ratio closer to the original request, so it asks for a
946 cropping rectangle of 608&nbsp;&times;&nbsp;456 pixels. The present
947 scaling factors limit cropping to 640&nbsp;&times;&nbsp;384, so the
948 driver returns the cropping size 608&nbsp;&times;&nbsp;384 and adjusts
949 the image size to closest possible 304&nbsp;&times;&nbsp;192.</para>
950
951     </section>
952
953     <section>
954       <title>Examples</title>
955
956       <para>Source and target rectangles shall remain unchanged across
957 closing and reopening a device, such that piping data into or out of a
958 device will work without special preparations. More advanced
959 applications should ensure the parameters are suitable before starting
960 I/O.</para>
961
962       <example>
963         <title>Resetting the cropping parameters</title>
964
965         <para>(A video capture device is assumed; change
966 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other
967 devices.)</para>
968
969         <programlisting>
970 &v4l2-cropcap; cropcap;
971 &v4l2-crop; crop;
972
973 memset (&amp;cropcap, 0, sizeof (cropcap));
974 cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
975
976 if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
977         perror ("VIDIOC_CROPCAP");
978         exit (EXIT_FAILURE);
979 }
980
981 memset (&amp;crop, 0, sizeof (crop));
982 crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
983 crop.c = cropcap.defrect;
984
985 /* Ignore if cropping is not supported (EINVAL). */
986
987 if (-1 == ioctl (fd, &VIDIOC-S-CROP;, &amp;crop)
988     &amp;&amp; errno != EINVAL) {
989         perror ("VIDIOC_S_CROP");
990         exit (EXIT_FAILURE);
991 }
992       </programlisting>
993       </example>
994
995       <example>
996         <title>Simple downscaling</title>
997
998         <para>(A video capture device is assumed.)</para>
999
1000         <programlisting>
1001 &v4l2-cropcap; cropcap;
1002 &v4l2-format; format;
1003
1004 reset_cropping_parameters ();
1005
1006 /* Scale down to 1/4 size of full picture. */
1007
1008 memset (&amp;format, 0, sizeof (format)); /* defaults */
1009
1010 format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1011
1012 format.fmt.pix.width = cropcap.defrect.width &gt;&gt; 1;
1013 format.fmt.pix.height = cropcap.defrect.height &gt;&gt; 1;
1014 format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
1015
1016 if (-1 == ioctl (fd, &VIDIOC-S-FMT;, &amp;format)) {
1017         perror ("VIDIOC_S_FORMAT");
1018         exit (EXIT_FAILURE);
1019 }
1020
1021 /* We could check the actual image size now, the actual scaling factor
1022    or if the driver can scale at all. */
1023         </programlisting>
1024       </example>
1025
1026       <example>
1027         <title>Selecting an output area</title>
1028
1029         <programlisting>
1030 &v4l2-cropcap; cropcap;
1031 &v4l2-crop; crop;
1032
1033 memset (&amp;cropcap, 0, sizeof (cropcap));
1034 cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
1035
1036 if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &amp;cropcap)) {
1037         perror ("VIDIOC_CROPCAP");
1038         exit (EXIT_FAILURE);
1039 }
1040
1041 memset (&amp;crop, 0, sizeof (crop));
1042
1043 crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
1044 crop.c = cropcap.defrect;
1045
1046 /* Scale the width and height to 50 % of their original size
1047    and center the output. */
1048
1049 crop.c.width /= 2;
1050 crop.c.height /= 2;
1051 crop.c.left += crop.c.width / 2;
1052 crop.c.top += crop.c.height / 2;
1053
1054 /* Ignore if cropping is not supported (EINVAL). */
1055
1056 if (-1 == ioctl (fd, VIDIOC_S_CROP, &amp;crop)
1057     &amp;&amp; errno != EINVAL) {
1058         perror ("VIDIOC_S_CROP");
1059         exit (EXIT_FAILURE);
1060 }
1061 </programlisting>
1062       </example>
1063
1064       <example>
1065         <title>Current scaling factor and pixel aspect</title>
1066
1067         <para>(A video capture device is assumed.)</para>
1068
1069         <programlisting>
1070 &v4l2-cropcap; cropcap;
1071 &v4l2-crop; crop;
1072 &v4l2-format; format;
1073 double hscale, vscale;
1074 double aspect;
1075 int dwidth, dheight;
1076
1077 memset (&amp;cropcap, 0, sizeof (cropcap));
1078 cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1079
1080 if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
1081         perror ("VIDIOC_CROPCAP");
1082         exit (EXIT_FAILURE);
1083 }
1084
1085 memset (&amp;crop, 0, sizeof (crop));
1086 crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1087
1088 if (-1 == ioctl (fd, &VIDIOC-G-CROP;, &amp;crop)) {
1089         if (errno != EINVAL) {
1090                 perror ("VIDIOC_G_CROP");
1091                 exit (EXIT_FAILURE);
1092         }
1093
1094         /* Cropping not supported. */
1095         crop.c = cropcap.defrect;
1096 }
1097
1098 memset (&amp;format, 0, sizeof (format));
1099 format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1100
1101 if (-1 == ioctl (fd, &VIDIOC-G-FMT;, &amp;format)) {
1102         perror ("VIDIOC_G_FMT");
1103         exit (EXIT_FAILURE);
1104 }
1105
1106 /* The scaling applied by the driver. */
1107
1108 hscale = format.fmt.pix.width / (double) crop.c.width;
1109 vscale = format.fmt.pix.height / (double) crop.c.height;
1110
1111 aspect = cropcap.pixelaspect.numerator /
1112          (double) cropcap.pixelaspect.denominator;
1113 aspect = aspect * hscale / vscale;
1114
1115 /* Devices following ITU-R BT.601 do not capture
1116    square pixels. For playback on a computer monitor
1117    we should scale the images to this size. */
1118
1119 dwidth = format.fmt.pix.width / aspect;
1120 dheight = format.fmt.pix.height;
1121         </programlisting>
1122       </example>
1123     </section>
1124   </section>
1125
1126   <section id="streaming-par">
1127     <title>Streaming Parameters</title>
1128
1129     <para>Streaming parameters are intended to optimize the video
1130 capture process as well as I/O. Presently applications can request a
1131 high quality capture mode with the &VIDIOC-S-PARM; ioctl.</para>
1132
1133     <para>The current video standard determines a nominal number of
1134 frames per second. If less than this number of frames is to be
1135 captured or output, applications can request frame skipping or
1136 duplicating on the driver side. This is especially useful when using
1137 the &func-read; or &func-write;, which are not augmented by timestamps
1138 or sequence counters, and to avoid unneccessary data copying.</para>
1139
1140     <para>Finally these ioctls can be used to determine the number of
1141 buffers used internally by a driver in read/write mode. For
1142 implications see the section discussing the &func-read;
1143 function.</para>
1144
1145     <para>To get and set the streaming parameters applications call
1146 the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; ioctl, respectively. They take
1147 a pointer to a &v4l2-streamparm;, which contains a union holding
1148 separate parameters for input and output devices.</para>
1149
1150     <para>These ioctls are optional, drivers need not implement
1151 them. If so, they return the &EINVAL;.</para>
1152   </section>
1153
1154   <!--
1155 Local Variables:
1156 mode: sgml
1157 sgml-parent-document: "v4l2.sgml"
1158 indent-tabs-mode: nil
1159 End:
1160   -->