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