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