blob: 71f6bf9e735e89067902618ebea4b22035a892df [file] [log] [blame]
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -03001 <title>Common API Elements</title>
2
3 <para>Programming a V4L2 device consists of these
4steps:</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
12input, video standard, picture brightness a.&nbsp;o.</para>
13 </listitem>
14 <listitem>
15 <para>Negotiating a data format</para>
16 </listitem>
17 <listitem>
18 <para>Negotiating an input/output method</para>
19 </listitem>
20 <listitem>
21 <para>The actual input/output loop</para>
22 </listitem>
23 <listitem>
24 <para>Closing the device</para>
25 </listitem>
26 </itemizedlist>
27
28 <para>In practice most steps are optional and can be executed out of
29order. It depends on the V4L2 device type, you can read about the
30details in <xref linkend="devices" />. In this chapter we will discuss
31the 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
40manually by the system administrator or automatically when a device is
Hans Verkuil5d5f87b2014-02-04 09:55:19 -030041first discovered. The driver modules plug into the "videodev" kernel
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -030042module. It provides helper functions and a common application
43interface specified in this document.</para>
44
45 <para>Each driver thus loaded registers one or more device nodes
Hans Verkuil5d5f87b2014-02-04 09:55:19 -030046with major number 81 and a minor number between 0 and 255. Minor numbers
47are allocated dynamically unless the kernel is compiled with the kernel
48option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers are
49allocated in ranges depending on the device node type (video, radio, etc.).</para>
50
51 <para>Many drivers support "video_nr", "radio_nr" or "vbi_nr"
52module options to select specific video/radio/vbi node numbers. This allows
53the user to request that the device node is named e.g. /dev/video5 instead
54of leaving it to chance. When the driver supports multiple devices of the same
55type more than one device node number can be assigned, separated by commas:
56 <informalexample>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -030057 <screen>
Hans Verkuil5d5f87b2014-02-04 09:55:19 -030058&gt; modprobe mydriver video_nr=0,1 radio_nr=0,1</screen>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -030059 </informalexample></para>
60
61 <para>In <filename>/etc/modules.conf</filename> this may be
62written as: <informalexample>
63 <screen>
Hans Verkuil5d5f87b2014-02-04 09:55:19 -030064options mydriver video_nr=0,1 radio_nr=0,1
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -030065 </screen>
Hans Verkuil5d5f87b2014-02-04 09:55:19 -030066 </informalexample> When no device node number is given as module
67option the driver supplies a default.</para>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -030068
Hans Verkuil5d5f87b2014-02-04 09:55:19 -030069 <para>Normally udev will create the device nodes in /dev automatically
70for you. If udev is not installed, then you need to enable the
71CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to correctly
72relate a minor number to a device node number. I.e., you need to be certain
73that minor number 5 maps to device node name video5. With this kernel option
74different device types have different minor number ranges. These ranges are
75listed in <xref linkend="devices" />.
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -030076</para>
77
78 <para>The creation of character special files (with
79<application>mknod</application>) is a privileged operation and
80devices cannot be opened by major and minor number. That means
81applications cannot <emphasis>reliable</emphasis> scan for loaded or
82installed drivers. The user must enter a device name, or the
83application can try the conventional device names.</para>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -030084 </section>
85
86 <section id="related">
87 <title>Related Devices</title>
88
Hans Verkuil5d5f87b2014-02-04 09:55:19 -030089 <para>Devices can support several functions. For example
90video capturing, VBI capturing and radio support.</para>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -030091
Hans Verkuil5d5f87b2014-02-04 09:55:19 -030092 <para>The V4L2 API creates different nodes for each of these functions.</para>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -030093
Hans Verkuil5d5f87b2014-02-04 09:55:19 -030094 <para>The V4L2 API was designed with the idea that one device node could support
95all functions. However, in practice this never worked: this 'feature'
96was never used by applications and many drivers did not support it and if
97they did it was certainly never tested. In addition, switching a device
98node between different functions only works when using the streaming I/O
99API, not with the read()/write() API.</para>
100
101 <para>Today each device node supports just one function.</para>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300102
103 <para>Besides video input or output the hardware may also
104support audio sampling or playback. If so, these functions are
Hans Verkuil5d5f87b2014-02-04 09:55:19 -0300105implemented as ALSA PCM devices with optional ALSA audio mixer
106devices.</para>
107
108 <para>One problem with all these devices is that the V4L2 API
109makes no provisions to find these related devices. Some really
110complex devices use the Media Controller (see <xref linkend="media_controller" />)
111which can be used for this purpose. But most drivers do not use it,
112and while some code exists that uses sysfs to discover related devices
113(see libmedia_dev in the <ulink url="http://git.linuxtv.org/v4l-utils/">v4l-utils</ulink>
114git repository), there is no library yet that can provide a single API towards
115both Media Controller-based devices and devices that do not use the Media Controller.
116If you want to work on this please write to the linux-media mailing list: &v4l-ml;.</para>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300117 </section>
118
119 <section>
120 <title>Multiple Opens</title>
121
Hans Verkuil5d5f87b2014-02-04 09:55:19 -0300122 <para>V4L2 devices can be opened more than once.<footnote><para>
123There are still some old and obscure drivers that have not been updated to
124allow for multiple opens. This implies that for such drivers &func-open; can
125return an &EBUSY; when the device is already in use.</para></footnote>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300126When this is supported by the driver, users can for example start a
127"panel" application to change controls like brightness or audio
128volume, while another application captures video and audio. In other words, panel
Hans Verkuil5d5f87b2014-02-04 09:55:19 -0300129applications are comparable to an ALSA audio mixer application.
130Just opening a V4L2 device should not change the state of the device.<footnote>
131<para>Unfortunately, opening a radio device often switches the state of the
132device to radio mode in many drivers. This behavior should be fixed eventually
133as it violates the V4L2 specification.</para></footnote></para>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300134
Hans Verkuil5d5f87b2014-02-04 09:55:19 -0300135 <para>Once an application has allocated the memory buffers needed for
136streaming data (by calling the &VIDIOC-REQBUFS; or &VIDIOC-CREATE-BUFS; ioctls,
137or implicitly by calling the &func-read; or &func-write; functions) that
138application (filehandle) becomes the owner of the device. It is no longer
139allowed to make changes that would affect the buffer sizes (e.g. by calling
140the &VIDIOC-S-FMT; ioctl) and other applications are no longer allowed to allocate
141buffers or start or stop streaming. The &EBUSY; will be returned instead.</para>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300142
Hans Verkuil5d5f87b2014-02-04 09:55:19 -0300143 <para>Merely opening a V4L2 device does not grant exclusive
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300144access.<footnote>
145 <para>Drivers could recognize the
146<constant>O_EXCL</constant> open flag. Presently this is not required,
147so applications cannot know if it really works.</para>
148 </footnote> Initiating data exchange however assigns the right
149to read or write the requested type of data, and to change related
150properties, to this file descriptor. Applications can request
151additional access privileges using the priority mechanism described in
152<xref linkend="app-pri" />.</para>
153 </section>
154
155 <section>
156 <title>Shared Data Streams</title>
157
158 <para>V4L2 drivers should not support multiple applications
159reading or writing the same data stream on a device by copying
160buffers, time multiplexing or similar means. This is better handled by
Hans Verkuil5d5f87b2014-02-04 09:55:19 -0300161a proxy application in user space.</para>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300162 </section>
163
164 <section>
165 <title>Functions</title>
166
167 <para>To open and close V4L2 devices applications use the
168&func-open; and &func-close; function, respectively. Devices are
169programmed using the &func-ioctl; function as explained in the
170following sections.</para>
171 </section>
172 </section>
173
174 <section id="querycap">
175 <title>Querying Capabilities</title>
176
177 <para>Because V4L2 covers a wide variety of devices not all
178aspects of the API are equally applicable to all types of devices.
179Furthermore devices of the same type have different capabilities and
180this specification permits the omission of a few complicated and less
181important parts of the API.</para>
182
183 <para>The &VIDIOC-QUERYCAP; ioctl is available to check if the kernel
184device is compatible with this specification, and to query the <link
185linkend="devices">functions</link> and <link linkend="io">I/O
Mauro Carvalho Chehabc20eb182011-06-25 14:11:52 -0300186methods</link> supported by the device.</para>
187
188 <para>Starting with kernel version 3.1, VIDIOC-QUERYCAP will return the
189V4L2 API version used by the driver, with generally matches the Kernel version.
Hans Verkuil1c656c872014-01-07 08:17:35 -0300190There's no need of using &VIDIOC-QUERYCAP; to check if a specific ioctl is
191supported, the V4L2 core now returns ENOTTY if a driver doesn't provide
Mauro Carvalho Chehabc20eb182011-06-25 14:11:52 -0300192support for an ioctl.</para>
193
194 <para>Other features can be queried
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300195by calling the respective ioctl, for example &VIDIOC-ENUMINPUT;
196to learn about the number, types and names of video connectors on the
197device. Although abstraction is a major objective of this API, the
Hans Verkuil1c656c872014-01-07 08:17:35 -0300198&VIDIOC-QUERYCAP; ioctl also allows driver specific applications to reliably identify
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300199the driver.</para>
200
201 <para>All V4L2 drivers must support
202<constant>VIDIOC_QUERYCAP</constant>. Applications should always call
203this ioctl after opening the device.</para>
204 </section>
205
206 <section id="app-pri">
207 <title>Application Priority</title>
208
209 <para>When multiple applications share a device it may be
210desirable to assign them different priorities. Contrary to the
211traditional "rm -rf /" school of thought a video recording application
212could for example block other applications from changing video
213controls or switching the current TV channel. Another objective is to
214permit low priority applications working in background, which can be
215preempted by user controlled applications and automatically regain
216control of the device at a later time.</para>
217
218 <para>Since these features cannot be implemented entirely in user
219space V4L2 defines the &VIDIOC-G-PRIORITY; and &VIDIOC-S-PRIORITY;
220ioctls to request and query the access priority associate with a file
221descriptor. Opening a device assigns a medium priority, compatible
222with earlier versions of V4L2 and drivers not supporting these ioctls.
223Applications requiring a different priority will usually call
224<constant>VIDIOC_S_PRIORITY</constant> after verifying the device with
225the &VIDIOC-QUERYCAP; ioctl.</para>
226
227 <para>Ioctls changing driver properties, such as &VIDIOC-S-INPUT;,
Hans Verkuil1c656c872014-01-07 08:17:35 -0300228return an &EBUSY; after another application obtained higher priority.</para>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300229 </section>
230
231 <section id="video">
232 <title>Video Inputs and Outputs</title>
233
234 <para>Video inputs and outputs are physical connectors of a
235device. These can be for example RF connectors (antenna/cable), CVBS
Hans Verkuil1c656c872014-01-07 08:17:35 -0300236a.k.a. Composite Video, S-Video or RGB connectors. Video and VBI
237capture devices have inputs. Video and VBI output devices have outputs,
238at least one each. Radio devices have no video inputs or outputs.</para>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300239
240 <para>To learn about the number and attributes of the
241available inputs and outputs applications can enumerate them with the
242&VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; ioctl, respectively. The
243&v4l2-input; returned by the <constant>VIDIOC_ENUMINPUT</constant>
244ioctl also contains signal status information applicable when the
245current video input is queried.</para>
246
Hans Verkuil1c656c872014-01-07 08:17:35 -0300247 <para>The &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; ioctls return the
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300248index of the current video input or output. To select a different
249input or output applications call the &VIDIOC-S-INPUT; and
Hans Verkuil1c656c872014-01-07 08:17:35 -0300250&VIDIOC-S-OUTPUT; ioctls. Drivers must implement all the input ioctls
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300251when the device has one or more inputs, all the output ioctls when the
252device has one or more outputs.</para>
253
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300254 <example>
255 <title>Information about the current video input</title>
256
257 <programlisting>
258&v4l2-input; input;
259int index;
260
Hans Verkuil1c656c872014-01-07 08:17:35 -0300261if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &amp;index)) {
262 perror("VIDIOC_G_INPUT");
263 exit(EXIT_FAILURE);
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300264}
265
Hans Verkuil1c656c872014-01-07 08:17:35 -0300266memset(&amp;input, 0, sizeof(input));
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300267input.index = index;
268
Hans Verkuil1c656c872014-01-07 08:17:35 -0300269if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
270 perror("VIDIOC_ENUMINPUT");
271 exit(EXIT_FAILURE);
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300272}
273
Hans Verkuil1c656c872014-01-07 08:17:35 -0300274printf("Current input: %s\n", input.name);
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300275 </programlisting>
276 </example>
277
278 <example>
279 <title>Switching to the first video input</title>
280
281 <programlisting>
282int index;
283
284index = 0;
285
Hans Verkuil1c656c872014-01-07 08:17:35 -0300286if (-1 == ioctl(fd, &VIDIOC-S-INPUT;, &amp;index)) {
287 perror("VIDIOC_S_INPUT");
288 exit(EXIT_FAILURE);
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300289}
290 </programlisting>
291 </example>
292 </section>
293
294 <section id="audio">
295 <title>Audio Inputs and Outputs</title>
296
297 <para>Audio inputs and outputs are physical connectors of a
298device. Video capture devices have inputs, output devices have
299outputs, zero or more each. Radio devices have no audio inputs or
300outputs. They have exactly one tuner which in fact
301<emphasis>is</emphasis> an audio source, but this API associates
302tuners with video inputs or outputs only, and radio devices have
303none of these.<footnote>
304 <para>Actually &v4l2-audio; ought to have a
305<structfield>tuner</structfield> field like &v4l2-input;, not only
306making the API more consistent but also permitting radio devices with
307multiple tuners.</para>
308 </footnote> A connector on a TV card to loop back the received
309audio signal to a sound card is not considered an audio output.</para>
310
311 <para>Audio and video inputs and outputs are associated. Selecting
312a video source also selects an audio source. This is most evident when
313the video and audio source is a tuner. Further audio connectors can
314combine with more than one video input or output. Assumed two
315composite video inputs and two audio inputs exist, there may be up to
316four valid combinations. The relation of video and audio connectors
317is defined in the <structfield>audioset</structfield> field of the
318respective &v4l2-input; or &v4l2-output;, where each bit represents
319the index number, starting at zero, of one audio input or output.</para>
320
321 <para>To learn about the number and attributes of the
322available inputs and outputs applications can enumerate them with the
323&VIDIOC-ENUMAUDIO; and &VIDIOC-ENUMAUDOUT; ioctl, respectively. The
324&v4l2-audio; returned by the <constant>VIDIOC_ENUMAUDIO</constant> ioctl
325also contains signal status information applicable when the current
326audio input is queried.</para>
327
Hans Verkuil1c656c872014-01-07 08:17:35 -0300328 <para>The &VIDIOC-G-AUDIO; and &VIDIOC-G-AUDOUT; ioctls report
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300329the current audio input and output, respectively. Note that, unlike
330&VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; these ioctls return a structure
331as <constant>VIDIOC_ENUMAUDIO</constant> and
332<constant>VIDIOC_ENUMAUDOUT</constant> do, not just an index.</para>
333
334 <para>To select an audio input and change its properties
335applications call the &VIDIOC-S-AUDIO; ioctl. To select an audio
336output (which presently has no changeable properties) applications
337call the &VIDIOC-S-AUDOUT; ioctl.</para>
338
Hans Verkuil1c656c872014-01-07 08:17:35 -0300339 <para>Drivers must implement all audio input ioctls when the device
340has multiple selectable audio inputs, all audio output ioctls when the
341device has multiple selectable audio outputs. When the device has any
342audio inputs or outputs the driver must set the <constant>V4L2_CAP_AUDIO</constant>
343flag in the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl.</para>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300344
345 <example>
346 <title>Information about the current audio input</title>
347
348 <programlisting>
349&v4l2-audio; audio;
350
Hans Verkuil1c656c872014-01-07 08:17:35 -0300351memset(&amp;audio, 0, sizeof(audio));
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300352
Hans Verkuil1c656c872014-01-07 08:17:35 -0300353if (-1 == ioctl(fd, &VIDIOC-G-AUDIO;, &amp;audio)) {
354 perror("VIDIOC_G_AUDIO");
355 exit(EXIT_FAILURE);
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300356}
357
Hans Verkuil1c656c872014-01-07 08:17:35 -0300358printf("Current input: %s\n", audio.name);
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300359 </programlisting>
360 </example>
361
362 <example>
363 <title>Switching to the first audio input</title>
364
365 <programlisting>
366&v4l2-audio; audio;
367
Hans Verkuil1c656c872014-01-07 08:17:35 -0300368memset(&amp;audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300369
370audio.index = 0;
371
Hans Verkuil1c656c872014-01-07 08:17:35 -0300372if (-1 == ioctl(fd, &VIDIOC-S-AUDIO;, &amp;audio)) {
373 perror("VIDIOC_S_AUDIO");
374 exit(EXIT_FAILURE);
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300375}
376 </programlisting>
377 </example>
378 </section>
379
380 <section id="tuner">
381 <title>Tuners and Modulators</title>
382
383 <section>
384 <title>Tuners</title>
385
386 <para>Video input devices can have one or more tuners
387demodulating a RF signal. Each tuner is associated with one or more
388video inputs, depending on the number of RF connectors on the tuner.
389The <structfield>type</structfield> field of the respective
390&v4l2-input; returned by the &VIDIOC-ENUMINPUT; ioctl is set to
391<constant>V4L2_INPUT_TYPE_TUNER</constant> and its
392<structfield>tuner</structfield> field contains the index number of
393the tuner.</para>
394
Hans Verkuilefcf5bd2012-05-28 07:42:54 -0300395 <para>Radio input devices have exactly one tuner with index zero, no
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300396video inputs.</para>
397
398 <para>To query and change tuner properties applications use the
Hans Verkuild4d68192014-01-07 09:39:57 -0300399&VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctls, respectively. The
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300400&v4l2-tuner; returned by <constant>VIDIOC_G_TUNER</constant> also
401contains signal status information applicable when the tuner of the
Hans Verkuilefcf5bd2012-05-28 07:42:54 -0300402current video or radio input is queried. Note that
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300403<constant>VIDIOC_S_TUNER</constant> does not switch the current tuner,
404when there is more than one at all. The tuner is solely determined by
405the current video input. Drivers must support both ioctls and set the
406<constant>V4L2_CAP_TUNER</constant> flag in the &v4l2-capability;
407returned by the &VIDIOC-QUERYCAP; ioctl when the device has one or
408more tuners.</para>
409 </section>
410
411 <section>
412 <title>Modulators</title>
413
414 <para>Video output devices can have one or more modulators, uh,
415modulating a video signal for radiation or connection to the antenna
416input of a TV set or video recorder. Each modulator is associated with
417one or more video outputs, depending on the number of RF connectors on
418the modulator. The <structfield>type</structfield> field of the
419respective &v4l2-output; returned by the &VIDIOC-ENUMOUTPUT; ioctl is
420set to <constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> and its
421<structfield>modulator</structfield> field contains the index number
Hans Verkuilefcf5bd2012-05-28 07:42:54 -0300422of the modulator.</para>
423
424 <para>Radio output devices have exactly one modulator with index
425zero, no video outputs.</para>
426
427 <para>A video or radio device cannot support both a tuner and a
428modulator. Two separate device nodes will have to be used for such
429hardware, one that supports the tuner functionality and one that supports
430the modulator functionality. The reason is a limitation with the
431&VIDIOC-S-FREQUENCY; ioctl where you cannot specify whether the frequency
432is for a tuner or a modulator.</para>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300433
434 <para>To query and change modulator properties applications use
435the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that
436<constant>VIDIOC_S_MODULATOR</constant> does not switch the current
437modulator, when there is more than one at all. The modulator is solely
438determined by the current video output. Drivers must support both
439ioctls and set the <constant>V4L2_CAP_MODULATOR</constant> flag in
440the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl when the
441device has one or more modulators.</para>
442 </section>
443
444 <section>
445 <title>Radio Frequency</title>
446
447 <para>To get and set the tuner or modulator radio frequency
448applications use the &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY;
449ioctl which both take a pointer to a &v4l2-frequency;. These ioctls
450are used for TV and radio devices alike. Drivers must support both
451ioctls when the tuner or modulator ioctls are supported, or
452when the device is a radio device.</para>
453 </section>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300454 </section>
455
456 <section id="standard">
457 <title>Video Standards</title>
458
459 <para>Video devices typically support one or more different video
460standards or variations of standards. Each video input and output may
461support another set of standards. This set is reported by the
462<structfield>std</structfield> field of &v4l2-input; and
463&v4l2-output; returned by the &VIDIOC-ENUMINPUT; and
Hans Verkuild4d68192014-01-07 09:39:57 -0300464&VIDIOC-ENUMOUTPUT; ioctls, respectively.</para>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300465
466 <para>V4L2 defines one bit for each analog video standard
467currently in use worldwide, and sets aside bits for driver defined
468standards, &eg; hybrid standards to watch NTSC video tapes on PAL TVs
469and vice versa. Applications can use the predefined bits to select a
470particular standard, although presenting the user a menu of supported
471standards is preferred. To enumerate and query the attributes of the
472supported standards applications use the &VIDIOC-ENUMSTD; ioctl.</para>
473
474 <para>Many of the defined standards are actually just variations
475of a few major standards. The hardware may in fact not distinguish
476between them, or do so internal and switch automatically. Therefore
477enumerated standards also contain sets of one or more standard
478bits.</para>
479
480 <para>Assume a hypothetic tuner capable of demodulating B/PAL,
481G/PAL and I/PAL signals. The first enumerated standard is a set of B
482and G/PAL, switched automatically depending on the selected radio
483frequency in UHF or VHF band. Enumeration gives a "PAL-B/G" or "PAL-I"
484choice. Similar a Composite input may collapse standards, enumerating
485"PAL-B/G/H/I", "NTSC-M" and "SECAM-D/K".<footnote>
486 <para>Some users are already confused by technical terms PAL,
487NTSC and SECAM. There is no point asking them to distinguish between
488B, G, D, or K when the software or hardware can do that
489automatically.</para>
490 </footnote></para>
491
492 <para>To query and select the standard used by the current video
493input or output applications call the &VIDIOC-G-STD; and
494&VIDIOC-S-STD; ioctl, respectively. The <emphasis>received</emphasis>
Hans Verkuild4d68192014-01-07 09:39:57 -0300495standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note that the
496parameter of all these ioctls is a pointer to a &v4l2-std-id; type
497(a standard set), <emphasis>not</emphasis> an index into the standard
498enumeration. Drivers must implement all video standard ioctls
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300499when the device has one or more video inputs or outputs.</para>
500
Hans Verkuild7a11e12012-09-14 07:39:55 -0300501 <para>Special rules apply to devices such as USB cameras where the notion of video
502standards makes little sense. More generally for any capture or output device
503which is: <itemizedlist>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300504 <listitem>
505 <para>incapable of capturing fields or frames at the nominal
506rate of the video standard, or</para>
507 </listitem>
508 <listitem>
Hans Verkuild7a11e12012-09-14 07:39:55 -0300509 <para>that does not support the video standard formats at all.</para>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300510 </listitem>
511 </itemizedlist> Here the driver shall set the
512<structfield>std</structfield> field of &v4l2-input; and &v4l2-output;
Hans Verkuild7a11e12012-09-14 07:39:55 -0300513to zero and the <constant>VIDIOC_G_STD</constant>,
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300514<constant>VIDIOC_S_STD</constant>,
515<constant>VIDIOC_QUERYSTD</constant> and
516<constant>VIDIOC_ENUMSTD</constant> ioctls shall return the
Hans Verkuild4d68192014-01-07 09:39:57 -0300517&ENOTTY; or the &EINVAL;.</para>
Hans Verkuild7a11e12012-09-14 07:39:55 -0300518 <para>Applications can make use of the <xref linkend="input-capabilities" /> and
519<xref linkend="output-capabilities"/> flags to determine whether the video standard ioctls
Hans Verkuild4d68192014-01-07 09:39:57 -0300520can be used with the given input or output.</para>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300521
522 <example>
523 <title>Information about the current video standard</title>
524
525 <programlisting>
526&v4l2-std-id; std_id;
527&v4l2-standard; standard;
528
Hans Verkuild4d68192014-01-07 09:39:57 -0300529if (-1 == ioctl(fd, &VIDIOC-G-STD;, &amp;std_id)) {
Hans Verkuild7a11e12012-09-14 07:39:55 -0300530 /* Note when VIDIOC_ENUMSTD always returns ENOTTY this
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300531 is no video device or it falls under the USB exception,
Hans Verkuild7a11e12012-09-14 07:39:55 -0300532 and VIDIOC_G_STD returning ENOTTY is no error. */
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300533
Hans Verkuild4d68192014-01-07 09:39:57 -0300534 perror("VIDIOC_G_STD");
535 exit(EXIT_FAILURE);
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300536}
537
Hans Verkuild4d68192014-01-07 09:39:57 -0300538memset(&amp;standard, 0, sizeof(standard));
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300539standard.index = 0;
540
Hans Verkuild4d68192014-01-07 09:39:57 -0300541while (0 == ioctl(fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300542 if (standard.id &amp; std_id) {
Hans Verkuild4d68192014-01-07 09:39:57 -0300543 printf("Current video standard: %s\n", standard.name);
544 exit(EXIT_SUCCESS);
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300545 }
546
547 standard.index++;
548}
549
550/* EINVAL indicates the end of the enumeration, which cannot be
551 empty unless this device falls under the USB exception. */
552
553if (errno == EINVAL || standard.index == 0) {
Hans Verkuild4d68192014-01-07 09:39:57 -0300554 perror("VIDIOC_ENUMSTD");
555 exit(EXIT_FAILURE);
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300556}
557 </programlisting>
558 </example>
559
560 <example>
561 <title>Listing the video standards supported by the current
562input</title>
563
564 <programlisting>
565&v4l2-input; input;
566&v4l2-standard; standard;
567
Hans Verkuild4d68192014-01-07 09:39:57 -0300568memset(&amp;input, 0, sizeof(input));
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300569
Hans Verkuild4d68192014-01-07 09:39:57 -0300570if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
571 perror("VIDIOC_G_INPUT");
572 exit(EXIT_FAILURE);
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300573}
574
Hans Verkuild4d68192014-01-07 09:39:57 -0300575if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
576 perror("VIDIOC_ENUM_INPUT");
577 exit(EXIT_FAILURE);
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300578}
579
Hans Verkuild4d68192014-01-07 09:39:57 -0300580printf("Current input %s supports:\n", input.name);
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300581
Hans Verkuild4d68192014-01-07 09:39:57 -0300582memset(&amp;standard, 0, sizeof(standard));
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300583standard.index = 0;
584
Hans Verkuild4d68192014-01-07 09:39:57 -0300585while (0 == ioctl(fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300586 if (standard.id &amp; input.std)
Hans Verkuild4d68192014-01-07 09:39:57 -0300587 printf("%s\n", standard.name);
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300588
589 standard.index++;
590}
591
592/* EINVAL indicates the end of the enumeration, which cannot be
593 empty unless this device falls under the USB exception. */
594
595if (errno != EINVAL || standard.index == 0) {
Hans Verkuild4d68192014-01-07 09:39:57 -0300596 perror("VIDIOC_ENUMSTD");
597 exit(EXIT_FAILURE);
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300598}
599 </programlisting>
600 </example>
601
602 <example>
603 <title>Selecting a new video standard</title>
604
605 <programlisting>
606&v4l2-input; input;
607&v4l2-std-id; std_id;
608
Hans Verkuild4d68192014-01-07 09:39:57 -0300609memset(&amp;input, 0, sizeof(input));
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300610
Hans Verkuild4d68192014-01-07 09:39:57 -0300611if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
612 perror("VIDIOC_G_INPUT");
613 exit(EXIT_FAILURE);
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300614}
615
Hans Verkuild4d68192014-01-07 09:39:57 -0300616if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
617 perror("VIDIOC_ENUM_INPUT");
618 exit(EXIT_FAILURE);
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300619}
620
621if (0 == (input.std &amp; V4L2_STD_PAL_BG)) {
Hans Verkuild4d68192014-01-07 09:39:57 -0300622 fprintf(stderr, "Oops. B/G PAL is not supported.\n");
623 exit(EXIT_FAILURE);
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300624}
625
626/* Note this is also supposed to work when only B
627 <emphasis>or</emphasis> G/PAL is supported. */
628
629std_id = V4L2_STD_PAL_BG;
630
Hans Verkuild4d68192014-01-07 09:39:57 -0300631if (-1 == ioctl(fd, &VIDIOC-S-STD;, &amp;std_id)) {
632 perror("VIDIOC_S_STD");
633 exit(EXIT_FAILURE);
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300634}
635 </programlisting>
636 </example>
Hans Verkuil7dcc6062012-05-15 08:04:28 -0300637 </section>
Muralidharan Karicheri007701e2009-12-03 01:13:17 -0300638 <section id="dv-timings">
639 <title>Digital Video (DV) Timings</title>
640 <para>
Hans Verkuil7dcc6062012-05-15 08:04:28 -0300641 The video standards discussed so far have been dealing with Analog TV and the
Muralidharan Karicheri007701e2009-12-03 01:13:17 -0300642corresponding video timings. Today there are many more different hardware interfaces
643such as High Definition TV interfaces (HDMI), VGA, DVI connectors etc., that carry
644video signals and there is a need to extend the API to select the video timings
645for these interfaces. Since it is not possible to extend the &v4l2-std-id; due to
Hans Verkuild4d68192014-01-07 09:39:57 -0300646the limited bits available, a new set of ioctls was added to set/get video timings at
647the input and output.</para>
648
649 <para>These ioctls deal with the detailed digital video timings that define
650each video format. This includes parameters such as the active video width and height,
651signal polarities, frontporches, backporches, sync widths etc. The <filename>linux/v4l2-dv-timings.h</filename>
Hans Verkuil7dcc6062012-05-15 08:04:28 -0300652header can be used to get the timings of the formats in the <xref linkend="cea861" /> and
653<xref linkend="vesadmt" /> standards.
654 </para>
Hans Verkuild4d68192014-01-07 09:39:57 -0300655
656 <para>To enumerate and query the attributes of the DV timings supported by a device
Hans Verkuil7dcc6062012-05-15 08:04:28 -0300657 applications use the &VIDIOC-ENUM-DV-TIMINGS; and &VIDIOC-DV-TIMINGS-CAP; ioctls.
Hans Verkuild4d68192014-01-07 09:39:57 -0300658 To set DV timings for the device applications use the
Hans Verkuil7dcc6062012-05-15 08:04:28 -0300659&VIDIOC-S-DV-TIMINGS; ioctl and to get current DV timings they use the
660&VIDIOC-G-DV-TIMINGS; ioctl. To detect the DV timings as seen by the video receiver applications
661use the &VIDIOC-QUERY-DV-TIMINGS; ioctl.</para>
Muralidharan Karicheri007701e2009-12-03 01:13:17 -0300662 <para>Applications can make use of the <xref linkend="input-capabilities" /> and
Hans Verkuild4d68192014-01-07 09:39:57 -0300663<xref linkend="output-capabilities"/> flags to determine whether the digital video ioctls
664can be used with the given input or output.</para>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300665 </section>
666
667 &sub-controls;
668
669 <section id="format">
670 <title>Data Formats</title>
671
672 <section>
673 <title>Data Format Negotiation</title>
674
675 <para>Different devices exchange different kinds of data with
676applications, for example video images, raw or sliced VBI data, RDS
677datagrams. Even within one kind many different formats are possible,
678in particular an abundance of image formats. Although drivers must
679provide a default and the selection persists across closing and
680reopening a device, applications should always negotiate a data format
681before engaging in data exchange. Negotiation means the application
682asks for a particular format and the driver selects and reports the
683best the hardware can do to satisfy the request. Of course
684applications can also just query the current selection.</para>
685
686 <para>A single mechanism exists to negotiate all data formats
687using the aggregate &v4l2-format; and the &VIDIOC-G-FMT; and
688&VIDIOC-S-FMT; ioctls. Additionally the &VIDIOC-TRY-FMT; ioctl can be
689used to examine what the hardware <emphasis>could</emphasis> do,
690without actually selecting a new data format. The data formats
691supported by the V4L2 API are covered in the respective device section
692in <xref linkend="devices" />. For a closer look at image formats see
693<xref linkend="pixfmt" />.</para>
694
695 <para>The <constant>VIDIOC_S_FMT</constant> ioctl is a major
696turning-point in the initialization sequence. Prior to this point
697multiple panel applications can access the same device concurrently to
698select the current input, change controls or modify other properties.
699The first <constant>VIDIOC_S_FMT</constant> assigns a logical stream
700(video data, VBI data etc.) exclusively to one file descriptor.</para>
701
702 <para>Exclusive means no other application, more precisely no
703other file descriptor, can grab this stream or change device
704properties inconsistent with the negotiated parameters. A video
705standard change for example, when the new standard uses a different
706number of scan lines, can invalidate the selected image format.
707Therefore only the file descriptor owning the stream can make
708invalidating changes. Accordingly multiple file descriptors which
709grabbed different logical streams prevent each other from interfering
710with their settings. When for example video overlay is about to start
711or already in progress, simultaneous video capturing may be restricted
712to the same cropping and image size.</para>
713
714 <para>When applications omit the
715<constant>VIDIOC_S_FMT</constant> ioctl its locking side effects are
716implied by the next step, the selection of an I/O method with the
717&VIDIOC-REQBUFS; ioctl or implicit with the first &func-read; or
718&func-write; call.</para>
719
720 <para>Generally only one logical stream can be assigned to a
721file descriptor, the exception being drivers permitting simultaneous
722video capturing and overlay using the same file descriptor for
723compatibility with V4L and earlier versions of V4L2. Switching the
724logical stream or returning into "panel mode" is possible by closing
725and reopening the device. Drivers <emphasis>may</emphasis> support a
726switch using <constant>VIDIOC_S_FMT</constant>.</para>
727
728 <para>All drivers exchanging data with
729applications must support the <constant>VIDIOC_G_FMT</constant> and
730<constant>VIDIOC_S_FMT</constant> ioctl. Implementation of the
731<constant>VIDIOC_TRY_FMT</constant> is highly recommended but
732optional.</para>
733 </section>
734
735 <section>
736 <title>Image Format Enumeration</title>
737
738 <para>Apart of the generic format negotiation functions
739a special ioctl to enumerate all image formats supported by video
740capture, overlay or output devices is available.<footnote>
741 <para>Enumerating formats an application has no a-priori
Mauro Carvalho Chehab9aa08852009-09-15 20:27:18 -0300742knowledge of (otherwise it could explicitly ask for them and need not
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300743enumerate) seems useless, but there are applications serving as proxy
744between drivers and the actual video applications for which this is
745useful.</para>
746 </footnote></para>
747
748 <para>The &VIDIOC-ENUM-FMT; ioctl must be supported
749by all drivers exchanging image data with applications.</para>
750
751 <important>
752 <para>Drivers are not supposed to convert image formats in
753kernel space. They must enumerate only formats directly supported by
754the hardware. If necessary driver writers should publish an example
755conversion routine or library for integration into applications.</para>
756 </important>
757 </section>
758 </section>
759
Pawel Osciak53b5d572011-01-07 01:41:33 -0300760 &sub-planar-apis;
761
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -0300762 <section id="crop">
763 <title>Image Cropping, Insertion and Scaling</title>
764
765 <para>Some video capture devices can sample a subsection of the
766picture and shrink or enlarge it to an image of arbitrary size. We
767call these abilities cropping and scaling. Some video output devices
768can scale an image up or down and insert it at an arbitrary scan line
769and horizontal offset into a video signal.</para>
770
771 <para>Applications can use the following API to select an area in
772the video signal, query the default area and the hardware limits.
773<emphasis>Despite their name, the &VIDIOC-CROPCAP;, &VIDIOC-G-CROP;
774and &VIDIOC-S-CROP; ioctls apply to input as well as output
775devices.</emphasis></para>
776
777 <para>Scaling requires a source and a target. On a video capture
778or overlay device the source is the video signal, and the cropping
779ioctls determine the area actually sampled. The target are images
780read by the application or overlaid onto the graphics screen. Their
781size (and position for an overlay) is negotiated with the
782&VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls.</para>
783
784 <para>On a video output device the source are the images passed in
785by the application, and their size is again negotiated with the
786<constant>VIDIOC_G/S_FMT</constant> ioctls, or may be encoded in a
787compressed video stream. The target is the video signal, and the
788cropping ioctls determine the area where the images are
789inserted.</para>
790
791 <para>Source and target rectangles are defined even if the device
792does not support scaling or the <constant>VIDIOC_G/S_CROP</constant>
793ioctls. Their size (and position where applicable) will be fixed in
794this case. <emphasis>All capture and output device must support the
795<constant>VIDIOC_CROPCAP</constant> ioctl such that applications can
796determine if scaling takes place.</emphasis></para>
797
798 <section>
799 <title>Cropping Structures</title>
800
801 <figure id="crop-scale">
802 <title>Image Cropping, Insertion and Scaling</title>
803 <mediaobject>
804 <imageobject>
805 <imagedata fileref="crop.pdf" format="PS" />
806 </imageobject>
807 <imageobject>
808 <imagedata fileref="crop.gif" format="GIF" />
809 </imageobject>
810 <textobject>
811 <phrase>The cropping, insertion and scaling process</phrase>
812 </textobject>
813 </mediaobject>
814 </figure>
815
816 <para>For capture devices the coordinates of the top left
817corner, width and height of the area which can be sampled is given by
818the <structfield>bounds</structfield> substructure of the
819&v4l2-cropcap; returned by the <constant>VIDIOC_CROPCAP</constant>
820ioctl. To support a wide range of hardware this specification does not
821define an origin or units. However by convention drivers should
822horizontally count unscaled samples relative to 0H (the leading edge
823of the horizontal sync pulse, see <xref linkend="vbi-hsync" />).
824Vertically ITU-R line
825numbers of the first field (<xref linkend="vbi-525" />, <xref
826linkend="vbi-625" />), multiplied by two if the driver can capture both
827fields.</para>
828
829 <para>The top left corner, width and height of the source
830rectangle, that is the area actually sampled, is given by &v4l2-crop;
831using the same coordinate system as &v4l2-cropcap;. Applications can
832use the <constant>VIDIOC_G_CROP</constant> and
833<constant>VIDIOC_S_CROP</constant> ioctls to get and set this
834rectangle. It must lie completely within the capture boundaries and
835the driver may further adjust the requested size and/or position
836according to hardware limitations.</para>
837
838 <para>Each capture device has a default source rectangle, given
839by the <structfield>defrect</structfield> substructure of
840&v4l2-cropcap;. The center of this rectangle shall align with the
841center of the active picture area of the video signal, and cover what
842the driver writer considers the complete picture. Drivers shall reset
843the source rectangle to the default when the driver is first loaded,
844but not later.</para>
845
846 <para>For output devices these structures and ioctls are used
847accordingly, defining the <emphasis>target</emphasis> rectangle where
848the images will be inserted into the video signal.</para>
849
850 </section>
851
852 <section>
853 <title>Scaling Adjustments</title>
854
855 <para>Video hardware can have various cropping, insertion and
856scaling limitations. It may only scale up or down, support only
857discrete scaling factors, or have different scaling abilities in
858horizontal and vertical direction. Also it may not support scaling at
859all. At the same time the &v4l2-crop; rectangle may have to be
860aligned, and both the source and target rectangles may have arbitrary
861upper and lower size limits. In particular the maximum
862<structfield>width</structfield> and <structfield>height</structfield>
863in &v4l2-crop; may be smaller than the
864&v4l2-cropcap;.<structfield>bounds</structfield> area. Therefore, as
865usual, drivers are expected to adjust the requested parameters and
866return the actual values selected.</para>
867
868 <para>Applications can change the source or the target rectangle
869first, as they may prefer a particular image size or a certain area in
870the video signal. If the driver has to adjust both to satisfy hardware
871limitations, the last requested rectangle shall take priority, and the
872driver should preferably adjust the opposite one. The &VIDIOC-TRY-FMT;
873ioctl however shall not change the driver state and therefore only
874adjust the requested rectangle.</para>
875
876 <para>Suppose scaling on a video capture device is restricted to
877a factor 1:1 or 2:1 in either direction and the target image size must
878be a multiple of 16&nbsp;&times;&nbsp;16 pixels. The source cropping
879rectangle is set to defaults, which are also the upper limit in this
880example, of 640&nbsp;&times;&nbsp;400 pixels at offset 0,&nbsp;0. An
881application requests an image size of 300&nbsp;&times;&nbsp;225
882pixels, assuming video will be scaled down from the "full picture"
883accordingly. The driver sets the image size to the closest possible
884values 304&nbsp;&times;&nbsp;224, then chooses the cropping rectangle
885closest to the requested size, that is 608&nbsp;&times;&nbsp;224
886(224&nbsp;&times;&nbsp;2:1 would exceed the limit 400). The offset
8870,&nbsp;0 is still valid, thus unmodified. Given the default cropping
888rectangle reported by <constant>VIDIOC_CROPCAP</constant> the
889application can easily propose another offset to center the cropping
890rectangle.</para>
891
892 <para>Now the application may insist on covering an area using a
893picture aspect ratio closer to the original request, so it asks for a
894cropping rectangle of 608&nbsp;&times;&nbsp;456 pixels. The present
895scaling factors limit cropping to 640&nbsp;&times;&nbsp;384, so the
896driver returns the cropping size 608&nbsp;&times;&nbsp;384 and adjusts
897the image size to closest possible 304&nbsp;&times;&nbsp;192.</para>
898
899 </section>
900
901 <section>
902 <title>Examples</title>
903
904 <para>Source and target rectangles shall remain unchanged across
905closing and reopening a device, such that piping data into or out of a
906device will work without special preparations. More advanced
907applications should ensure the parameters are suitable before starting
908I/O.</para>
909
910 <example>
911 <title>Resetting the cropping parameters</title>
912
913 <para>(A video capture device is assumed; change
914<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other
915devices.)</para>
916
917 <programlisting>
918&v4l2-cropcap; cropcap;
919&v4l2-crop; crop;
920
921memset (&amp;cropcap, 0, sizeof (cropcap));
922cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
923
924if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
925 perror ("VIDIOC_CROPCAP");
926 exit (EXIT_FAILURE);
927}
928
929memset (&amp;crop, 0, sizeof (crop));
930crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
931crop.c = cropcap.defrect;
932
933/* Ignore if cropping is not supported (EINVAL). */
934
935if (-1 == ioctl (fd, &VIDIOC-S-CROP;, &amp;crop)
936 &amp;&amp; errno != EINVAL) {
937 perror ("VIDIOC_S_CROP");
938 exit (EXIT_FAILURE);
939}
940 </programlisting>
941 </example>
942
943 <example>
944 <title>Simple downscaling</title>
945
946 <para>(A video capture device is assumed.)</para>
947
948 <programlisting>
949&v4l2-cropcap; cropcap;
950&v4l2-format; format;
951
952reset_cropping_parameters ();
953
954/* Scale down to 1/4 size of full picture. */
955
956memset (&amp;format, 0, sizeof (format)); /* defaults */
957
958format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
959
960format.fmt.pix.width = cropcap.defrect.width &gt;&gt; 1;
961format.fmt.pix.height = cropcap.defrect.height &gt;&gt; 1;
962format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
963
964if (-1 == ioctl (fd, &VIDIOC-S-FMT;, &amp;format)) {
965 perror ("VIDIOC_S_FORMAT");
966 exit (EXIT_FAILURE);
967}
968
969/* We could check the actual image size now, the actual scaling factor
970 or if the driver can scale at all. */
971 </programlisting>
972 </example>
973
974 <example>
975 <title>Selecting an output area</title>
976
977 <programlisting>
978&v4l2-cropcap; cropcap;
979&v4l2-crop; crop;
980
981memset (&amp;cropcap, 0, sizeof (cropcap));
982cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
983
984if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &amp;cropcap)) {
985 perror ("VIDIOC_CROPCAP");
986 exit (EXIT_FAILURE);
987}
988
989memset (&amp;crop, 0, sizeof (crop));
990
991crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
992crop.c = cropcap.defrect;
993
994/* Scale the width and height to 50 % of their original size
995 and center the output. */
996
997crop.c.width /= 2;
998crop.c.height /= 2;
999crop.c.left += crop.c.width / 2;
1000crop.c.top += crop.c.height / 2;
1001
1002/* Ignore if cropping is not supported (EINVAL). */
1003
1004if (-1 == ioctl (fd, VIDIOC_S_CROP, &amp;crop)
1005 &amp;&amp; errno != EINVAL) {
1006 perror ("VIDIOC_S_CROP");
1007 exit (EXIT_FAILURE);
1008}
1009</programlisting>
1010 </example>
1011
1012 <example>
1013 <title>Current scaling factor and pixel aspect</title>
1014
1015 <para>(A video capture device is assumed.)</para>
1016
1017 <programlisting>
1018&v4l2-cropcap; cropcap;
1019&v4l2-crop; crop;
1020&v4l2-format; format;
1021double hscale, vscale;
1022double aspect;
1023int dwidth, dheight;
1024
1025memset (&amp;cropcap, 0, sizeof (cropcap));
1026cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1027
1028if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
1029 perror ("VIDIOC_CROPCAP");
1030 exit (EXIT_FAILURE);
1031}
1032
1033memset (&amp;crop, 0, sizeof (crop));
1034crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1035
1036if (-1 == ioctl (fd, &VIDIOC-G-CROP;, &amp;crop)) {
1037 if (errno != EINVAL) {
1038 perror ("VIDIOC_G_CROP");
1039 exit (EXIT_FAILURE);
1040 }
1041
1042 /* Cropping not supported. */
1043 crop.c = cropcap.defrect;
1044}
1045
1046memset (&amp;format, 0, sizeof (format));
1047format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1048
1049if (-1 == ioctl (fd, &VIDIOC-G-FMT;, &amp;format)) {
1050 perror ("VIDIOC_G_FMT");
1051 exit (EXIT_FAILURE);
1052}
1053
1054/* The scaling applied by the driver. */
1055
1056hscale = format.fmt.pix.width / (double) crop.c.width;
1057vscale = format.fmt.pix.height / (double) crop.c.height;
1058
1059aspect = cropcap.pixelaspect.numerator /
1060 (double) cropcap.pixelaspect.denominator;
1061aspect = aspect * hscale / vscale;
1062
1063/* Devices following ITU-R BT.601 do not capture
1064 square pixels. For playback on a computer monitor
1065 we should scale the images to this size. */
1066
1067dwidth = format.fmt.pix.width / aspect;
1068dheight = format.fmt.pix.height;
1069 </programlisting>
1070 </example>
1071 </section>
1072 </section>
1073
Tomasz Stanislawski8af49222011-08-19 07:00:04 -03001074 &sub-selection-api;
1075
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -03001076 <section id="streaming-par">
1077 <title>Streaming Parameters</title>
1078
1079 <para>Streaming parameters are intended to optimize the video
1080capture process as well as I/O. Presently applications can request a
1081high quality capture mode with the &VIDIOC-S-PARM; ioctl.</para>
1082
1083 <para>The current video standard determines a nominal number of
1084frames per second. If less than this number of frames is to be
1085captured or output, applications can request frame skipping or
1086duplicating on the driver side. This is especially useful when using
1087the &func-read; or &func-write;, which are not augmented by timestamps
Daniel Mack3ad2f3fb2010-02-03 08:01:28 +08001088or sequence counters, and to avoid unnecessary data copying.</para>
Mauro Carvalho Chehab8e080c2e2009-09-13 22:16:04 -03001089
1090 <para>Finally these ioctls can be used to determine the number of
1091buffers used internally by a driver in read/write mode. For
1092implications see the section discussing the &func-read;
1093function.</para>
1094
1095 <para>To get and set the streaming parameters applications call
1096the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; ioctl, respectively. They take
1097a pointer to a &v4l2-streamparm;, which contains a union holding
1098separate parameters for input and output devices.</para>
1099
1100 <para>These ioctls are optional, drivers need not implement
1101them. If so, they return the &EINVAL;.</para>
1102 </section>