About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / media / v4l / common.xml




Custom Search

Based on kernel version 3.13. Page generated on 2014-01-20 22:02 EST.

1	  <title>Common API Elements</title>
2	
3	  <para>Programming a V4L2 device consists of these
4	steps:</para>
5	
6	  <itemizedlist>
7	    <listitem>
8	      <para>Opening the device</para>
9	    </listitem>
10	    <listitem>
11	      <para>Changing device properties, selecting a video and audio
12	input, video standard, picture brightness a.&nbsp;o.</para>
13	    </listitem>
14	    <listitem>
15	      <para>Negotiating a data format</para>
16	    </listitem>
17	    <listitem>
18	      <para>Negotiating an input/output method</para>
19	    </listitem>
20	    <listitem>
21	      <para>The actual input/output loop</para>
22	    </listitem>
23	    <listitem>
24	      <para>Closing the device</para>
25	    </listitem>
26	  </itemizedlist>
27	
28	  <para>In practice most steps are optional and can be executed out of
29	order. It depends on the V4L2 device type, you can read about the
30	details in <xref linkend="devices" />. In this chapter we will discuss
31	the basic concepts applicable to all devices.</para>
32	
33	  <section id="open">
34	    <title>Opening and Closing Devices</title>
35	
36	    <section>
37	      <title>Device Naming</title>
38	
39	      <para>V4L2 drivers are implemented as kernel modules, loaded
40	manually by the system administrator or automatically when a device is
41	first opened. The driver modules plug into the "videodev" kernel
42	module. It provides helper functions and a common application
43	interface specified in this document.</para>
44	
45	      <para>Each driver thus loaded registers one or more device nodes
46	with major number 81 and a minor number between 0 and 255. Assigning
47	minor numbers to V4L2 devices is entirely up to the system administrator,
48	this is primarily intended to solve conflicts between devices.<footnote>
49		  <para>Access permissions are associated with character
50	device special files, hence we must ensure device numbers cannot
51	change with the module load order. To this end minor numbers are no
52	longer automatically assigned by the "videodev" module as in V4L but
53	requested by the driver. The defaults will suffice for most people
54	unless two drivers compete for the same minor numbers.</para>
55		</footnote> The module options to select minor numbers are named
56	after the device special file with a "_nr" suffix. For example "video_nr"
57	for <filename>/dev/video</filename> video capture devices. The number is
58	an offset to the base minor number associated with the device type.
59	<footnote>
60		  <para>In earlier versions of the V4L2 API the module options
61	where named after the device special file with a "unit_" prefix, expressing
62	the minor number itself, not an offset. Rationale for this change is unknown.
63	Lastly the naming and semantics are just a convention among driver writers,
64	the point to note is that minor numbers are not supposed to be hardcoded
65	into drivers.</para>
66		</footnote> When the driver supports multiple devices of the same
67	type more than one minor number can be assigned, separated by commas:
68	<informalexample>
69		  <screen>
70	&gt; insmod mydriver.o video_nr=0,1 radio_nr=0,1</screen>
71		</informalexample></para>
72	
73	      <para>In <filename>/etc/modules.conf</filename> this may be
74	written as: <informalexample>
75		  <screen>
76	alias char-major-81-0 mydriver
77	alias char-major-81-1 mydriver
78	alias char-major-81-64 mydriver              <co id="alias" />
79	options mydriver video_nr=0,1 radio_nr=0,1   <co id="options" />
80		  </screen>
81		  <calloutlist>
82		    <callout arearefs="alias">
83		      <para>When an application attempts to open a device
84	special file with major number 81 and minor number 0, 1, or 64, load
85	"mydriver" (and the "videodev" module it depends upon).</para>
86		    </callout>
87		    <callout arearefs="options">
88		      <para>Register the first two video capture devices with
89	minor number 0 and 1 (base number is 0), the first two radio device
90	with minor number 64 and 65 (base 64).</para>
91		    </callout>
92		  </calloutlist>
93		</informalexample> When no minor number is given as module
94	option the driver supplies a default. <xref linkend="devices" />
95	recommends the base minor numbers to be used for the various device
96	types. Obviously minor numbers must be unique. When the number is
97	already in use the <emphasis>offending device</emphasis> will not be
98	registered. <!-- Blessed by Linus Torvalds on
99	linux-kernel@vger.kernel.org, 2002-11-20. --></para>
100	
101	      <para>By convention system administrators create various
102	character device special files with these major and minor numbers in
103	the <filename>/dev</filename> directory. The names recommended for the
104	different V4L2 device types are listed in <xref linkend="devices" />.
105	</para>
106	
107	      <para>The creation of character special files (with
108	<application>mknod</application>) is a privileged operation and
109	devices cannot be opened by major and minor number. That means
110	applications cannot <emphasis>reliable</emphasis> scan for loaded or
111	installed drivers. The user must enter a device name, or the
112	application can try the conventional device names.</para>
113	
114	      <para>Under the device filesystem (devfs) the minor number
115	options are ignored. V4L2 drivers (or by proxy the "videodev" module)
116	automatically create the required device files in the
117	<filename>/dev/v4l</filename> directory using the conventional device
118	names above.</para>
119	    </section>
120	
121	    <section id="related">
122	      <title>Related Devices</title>
123	
124	      <para>Devices can support several related functions. For example
125	video capturing, video overlay and VBI capturing are related because
126	these functions share, amongst other, the same video input and tuner
127	frequency. V4L and earlier versions of V4L2 used the same device name
128	and minor number for video capturing and overlay, but different ones
129	for VBI. Experience showed this approach has several problems<footnote>
130		  <para>Given a device file name one cannot reliable find
131	related devices. For once names are arbitrary and in a system with
132	multiple devices, where only some support VBI capturing, a
133	<filename>/dev/video2</filename> is not necessarily related to
134	<filename>/dev/vbi2</filename>. The V4L
135	<constant>VIDIOCGUNIT</constant> ioctl would require a search for a
136	device file with a particular major and minor number.</para>
137		</footnote>, and to make things worse the V4L videodev module
138	used to prohibit multiple opens of a device.</para>
139	
140	      <para>As a remedy the present version of the V4L2 API relaxed the
141	concept of device types with specific names and minor numbers. For
142	compatibility with old applications drivers must still register different
143	minor numbers to assign a default function to the device. But if related
144	functions are supported by the driver they must be available under all
145	registered minor numbers. The desired function can be selected after
146	opening the device as described in <xref linkend="devices" />.</para>
147	
148	      <para>Imagine a driver supporting video capturing, video
149	overlay, raw VBI capturing, and FM radio reception. It registers three
150	devices with minor number 0, 64 and 224 (this numbering scheme is
151	inherited from the V4L API). Regardless if
152	<filename>/dev/video</filename> (81, 0) or
153	<filename>/dev/vbi</filename> (81, 224) is opened the application can
154	select any one of the video capturing, overlay or VBI capturing
155	functions. Without programming (e.&nbsp;g. reading from the device
156	with <application>dd</application> or <application>cat</application>)
157	<filename>/dev/video</filename> captures video images, while
158	<filename>/dev/vbi</filename> captures raw VBI data.
159	<filename>/dev/radio</filename> (81, 64) is invariable a radio device,
160	unrelated to the video functions. Being unrelated does not imply the
161	devices can be used at the same time, however. The &func-open;
162	function may very well return an &EBUSY;.</para>
163	
164	      <para>Besides video input or output the hardware may also
165	support audio sampling or playback. If so, these functions are
166	implemented as OSS or ALSA PCM devices and eventually OSS or ALSA
167	audio mixer. The V4L2 API makes no provisions yet to find these
168	related devices. If you have an idea please write to the linux-media
169	mailing list: &v4l-ml;.</para>
170	    </section>
171	
172	    <section>
173	      <title>Multiple Opens</title>
174	
175	      <para>In general, V4L2 devices can be opened more than once.
176	When this is supported by the driver, users can for example start a
177	"panel" application to change controls like brightness or audio
178	volume, while another application captures video and audio. In other words, panel
179	applications are comparable to an OSS or ALSA audio mixer application.
180	When a device supports multiple functions like capturing and overlay
181	<emphasis>simultaneously</emphasis>, multiple opens allow concurrent
182	use of the device by forked processes or specialized applications.</para>
183	
184	      <para>Multiple opens are optional, although drivers should
185	permit at least concurrent accesses without data exchange, &ie; panel
186	applications. This implies &func-open; can return an &EBUSY; when the
187	device is already in use, as well as &func-ioctl; functions initiating
188	data exchange (namely the &VIDIOC-S-FMT; ioctl), and the &func-read;
189	and &func-write; functions.</para>
190	
191	      <para>Mere opening a V4L2 device does not grant exclusive
192	access.<footnote>
193		  <para>Drivers could recognize the
194	<constant>O_EXCL</constant> open flag. Presently this is not required,
195	so applications cannot know if it really works.</para>
196		</footnote> Initiating data exchange however assigns the right
197	to read or write the requested type of data, and to change related
198	properties, to this file descriptor. Applications can request
199	additional access privileges using the priority mechanism described in
200	<xref linkend="app-pri" />.</para>
201	    </section>
202	
203	    <section>
204	      <title>Shared Data Streams</title>
205	
206	      <para>V4L2 drivers should not support multiple applications
207	reading or writing the same data stream on a device by copying
208	buffers, time multiplexing or similar means. This is better handled by
209	a proxy application in user space. When the driver supports stream
210	sharing anyway it must be implemented transparently. The V4L2 API does
211	not specify how conflicts are solved. <!-- For example O_EXCL when the
212	application does not want to be preempted, PROT_READ mmapped buffers
213	which can be mapped twice, what happens when image formats do not
214	match etc.--></para>
215	    </section>
216	
217	    <section>
218	      <title>Functions</title>
219	
220	    <para>To open and close V4L2 devices applications use the
221	&func-open; and &func-close; function, respectively. Devices are
222	programmed using the &func-ioctl; function as explained in the
223	following sections.</para>
224	    </section>
225	  </section>
226	
227	  <section id="querycap">
228	    <title>Querying Capabilities</title>
229	
230	    <para>Because V4L2 covers a wide variety of devices not all
231	aspects of the API are equally applicable to all types of devices.
232	Furthermore devices of the same type have different capabilities and
233	this specification permits the omission of a few complicated and less
234	important parts of the API.</para>
235	
236	    <para>The &VIDIOC-QUERYCAP; ioctl is available to check if the kernel
237	device is compatible with this specification, and to query the <link
238	linkend="devices">functions</link> and <link linkend="io">I/O
239	methods</link> supported by the device.</para>
240	
241	    <para>Starting with kernel version 3.1, VIDIOC-QUERYCAP will return the
242	V4L2 API version used by the driver, with generally matches the Kernel version.
243	There's no need of using &VIDIOC-QUERYCAP; to check if an specific ioctl is
244	supported, the V4L2 core now returns ENOIOCTLCMD if a driver doesn't provide
245	support for an ioctl.</para>
246	
247	    <para>Other features can be queried
248	by calling the respective ioctl, for example &VIDIOC-ENUMINPUT;
249	to learn about the number, types and names of video connectors on the
250	device. Although abstraction is a major objective of this API, the
251	ioctl also allows driver specific applications to reliable identify
252	the driver.</para>
253	
254	    <para>All V4L2 drivers must support
255	<constant>VIDIOC_QUERYCAP</constant>. Applications should always call
256	this ioctl after opening the device.</para>
257	  </section>
258	
259	  <section id="app-pri">
260	    <title>Application Priority</title>
261	
262	    <para>When multiple applications share a device it may be
263	desirable to assign them different priorities. Contrary to the
264	traditional "rm -rf /" school of thought a video recording application
265	could for example block other applications from changing video
266	controls or switching the current TV channel. Another objective is to
267	permit low priority applications working in background, which can be
268	preempted by user controlled applications and automatically regain
269	control of the device at a later time.</para>
270	
271	    <para>Since these features cannot be implemented entirely in user
272	space V4L2 defines the &VIDIOC-G-PRIORITY; and &VIDIOC-S-PRIORITY;
273	ioctls to request and query the access priority associate with a file
274	descriptor. Opening a device assigns a medium priority, compatible
275	with earlier versions of V4L2 and drivers not supporting these ioctls.
276	Applications requiring a different priority will usually call
277	<constant>VIDIOC_S_PRIORITY</constant> after verifying the device with
278	the &VIDIOC-QUERYCAP; ioctl.</para>
279	
280	    <para>Ioctls changing driver properties, such as &VIDIOC-S-INPUT;,
281	return an &EBUSY; after another application obtained higher priority.
282	An event mechanism to notify applications about asynchronous property
283	changes has been proposed but not added yet.</para>
284	  </section>
285	
286	  <section id="video">
287	    <title>Video Inputs and Outputs</title>
288	
289	    <para>Video inputs and outputs are physical connectors of a
290	device. These can be for example RF connectors (antenna/cable), CVBS
291	a.k.a. Composite Video, S-Video or RGB connectors. Only video and VBI
292	capture devices have inputs, output devices have outputs, at least one
293	each. Radio devices have no video inputs or outputs.</para>
294	
295	    <para>To learn about the number and attributes of the
296	available inputs and outputs applications can enumerate them with the
297	&VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; ioctl, respectively. The
298	&v4l2-input; returned by the <constant>VIDIOC_ENUMINPUT</constant>
299	ioctl also contains signal status information applicable when the
300	current video input is queried.</para>
301	
302	    <para>The &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; ioctl return the
303	index of the current video input or output. To select a different
304	input or output applications call the &VIDIOC-S-INPUT; and
305	&VIDIOC-S-OUTPUT; ioctl. Drivers must implement all the input ioctls
306	when the device has one or more inputs, all the output ioctls when the
307	device has one or more outputs.</para>
308	
309	    <!--
310	    <figure id=io-tree>
311	      <title>Input and output enumeration is the root of most device properties.</title>
312	      <mediaobject>
313		<imageobject>
314		  <imagedata fileref="links.pdf" format="ps" />
315		</imageobject>
316		<imageobject>
317		  <imagedata fileref="links.gif" format="gif" />
318		</imageobject>
319		<textobject>
320		  <phrase>Links between various device property structures.</phrase>
321		</textobject>
322	      </mediaobject>
323	    </figure>
324	    -->
325	
326	    <example>
327	      <title>Information about the current video input</title>
328	
329	      <programlisting>
330	&v4l2-input; input;
331	int index;
332	
333	if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;index)) {
334		perror ("VIDIOC_G_INPUT");
335		exit (EXIT_FAILURE);
336	}
337	
338	memset (&amp;input, 0, sizeof (input));
339	input.index = index;
340	
341	if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
342		perror ("VIDIOC_ENUMINPUT");
343		exit (EXIT_FAILURE);
344	}
345	
346	printf ("Current input: %s\n", input.name);
347	      </programlisting>
348	    </example>
349	
350	    <example>
351	      <title>Switching to the first video input</title>
352	
353	      <programlisting>
354	int index;
355	
356	index = 0;
357	
358	if (-1 == ioctl (fd, &VIDIOC-S-INPUT;, &amp;index)) {
359		perror ("VIDIOC_S_INPUT");
360		exit (EXIT_FAILURE);
361	}
362	      </programlisting>
363	    </example>
364	  </section>
365	
366	  <section id="audio">
367	    <title>Audio Inputs and Outputs</title>
368	
369	    <para>Audio inputs and outputs are physical connectors of a
370	device. Video capture devices have inputs, output devices have
371	outputs, zero or more each. Radio devices have no audio inputs or
372	outputs. They have exactly one tuner which in fact
373	<emphasis>is</emphasis> an audio source, but this API associates
374	tuners with video inputs or outputs only, and radio devices have
375	none of these.<footnote>
376		<para>Actually &v4l2-audio; ought to have a
377	<structfield>tuner</structfield> field like &v4l2-input;, not only
378	making the API more consistent but also permitting radio devices with
379	multiple tuners.</para>
380	      </footnote> A connector on a TV card to loop back the received
381	audio signal to a sound card is not considered an audio output.</para>
382	
383	    <para>Audio and video inputs and outputs are associated. Selecting
384	a video source also selects an audio source. This is most evident when
385	the video and audio source is a tuner. Further audio connectors can
386	combine with more than one video input or output. Assumed two
387	composite video inputs and two audio inputs exist, there may be up to
388	four valid combinations. The relation of video and audio connectors
389	is defined in the <structfield>audioset</structfield> field of the
390	respective &v4l2-input; or &v4l2-output;, where each bit represents
391	the index number, starting at zero, of one audio input or output.</para>
392	
393	    <para>To learn about the number and attributes of the
394	available inputs and outputs applications can enumerate them with the
395	&VIDIOC-ENUMAUDIO; and &VIDIOC-ENUMAUDOUT; ioctl, respectively. The
396	&v4l2-audio; returned by the <constant>VIDIOC_ENUMAUDIO</constant> ioctl
397	also contains signal status information applicable when the current
398	audio input is queried.</para>
399	
400	    <para>The &VIDIOC-G-AUDIO; and &VIDIOC-G-AUDOUT; ioctl report
401	the current audio input and output, respectively. Note that, unlike
402	&VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; these ioctls return a structure
403	as <constant>VIDIOC_ENUMAUDIO</constant> and
404	<constant>VIDIOC_ENUMAUDOUT</constant> do, not just an index.</para>
405	
406	    <para>To select an audio input and change its properties
407	applications call the &VIDIOC-S-AUDIO; ioctl. To select an audio
408	output (which presently has no changeable properties) applications
409	call the &VIDIOC-S-AUDOUT; ioctl.</para>
410	
411	    <para>Drivers must implement all input ioctls when the device
412	has one or more inputs, all output ioctls when the device has one
413	or more outputs. When the device has any audio inputs or outputs the
414	driver must set the <constant>V4L2_CAP_AUDIO</constant> flag in the
415	&v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl.</para>
416	
417	    <example>
418	      <title>Information about the current audio input</title>
419	
420	      <programlisting>
421	&v4l2-audio; audio;
422	
423	memset (&amp;audio, 0, sizeof (audio));
424	
425	if (-1 == ioctl (fd, &VIDIOC-G-AUDIO;, &amp;audio)) {
426		perror ("VIDIOC_G_AUDIO");
427		exit (EXIT_FAILURE);
428	}
429	
430	printf ("Current input: %s\n", audio.name);
431	      </programlisting>
432	    </example>
433	
434	    <example>
435	      <title>Switching to the first audio input</title>
436	
437	      <programlisting>
438	&v4l2-audio; audio;
439	
440	memset (&amp;audio, 0, sizeof (audio)); /* clear audio.mode, audio.reserved */
441	
442	audio.index = 0;
443	
444	if (-1 == ioctl (fd, &VIDIOC-S-AUDIO;, &amp;audio)) {
445		perror ("VIDIOC_S_AUDIO");
446		exit (EXIT_FAILURE);
447	}
448	      </programlisting>
449	    </example>
450	  </section>
451	
452	  <section id="tuner">
453	    <title>Tuners and Modulators</title>
454	
455	    <section>
456	      <title>Tuners</title>
457	
458	      <para>Video input devices can have one or more tuners
459	demodulating a RF signal. Each tuner is associated with one or more
460	video inputs, depending on the number of RF connectors on the tuner.
461	The <structfield>type</structfield> field of the respective
462	&v4l2-input; returned by the &VIDIOC-ENUMINPUT; ioctl is set to
463	<constant>V4L2_INPUT_TYPE_TUNER</constant> and its
464	<structfield>tuner</structfield> field contains the index number of
465	the tuner.</para>
466	
467	      <para>Radio input devices have exactly one tuner with index zero, no
468	video inputs.</para>
469	
470	      <para>To query and change tuner properties applications use the
471	&VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctl, respectively. The
472	&v4l2-tuner; returned by <constant>VIDIOC_G_TUNER</constant> also
473	contains signal status information applicable when the tuner of the
474	current video or radio input is queried. Note that
475	<constant>VIDIOC_S_TUNER</constant> does not switch the current tuner,
476	when there is more than one at all. The tuner is solely determined by
477	the current video input. Drivers must support both ioctls and set the
478	<constant>V4L2_CAP_TUNER</constant> flag in the &v4l2-capability;
479	returned by the &VIDIOC-QUERYCAP; ioctl when the device has one or
480	more tuners.</para>
481	    </section>
482	
483	    <section>
484	      <title>Modulators</title>
485	
486	      <para>Video output devices can have one or more modulators, uh,
487	modulating a video signal for radiation or connection to the antenna
488	input of a TV set or video recorder. Each modulator is associated with
489	one or more video outputs, depending on the number of RF connectors on
490	the modulator. The <structfield>type</structfield> field of the
491	respective &v4l2-output; returned by the &VIDIOC-ENUMOUTPUT; ioctl is
492	set to <constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> and its
493	<structfield>modulator</structfield> field contains the index number
494	of the modulator.</para>
495	
496	      <para>Radio output devices have exactly one modulator with index
497	zero, no video outputs.</para>
498	
499	      <para>A video or radio device cannot support both a tuner and a
500	modulator. Two separate device nodes will have to be used for such
501	hardware, one that supports the tuner functionality and one that supports
502	the modulator functionality. The reason is a limitation with the
503	&VIDIOC-S-FREQUENCY; ioctl where you cannot specify whether the frequency
504	is for a tuner or a modulator.</para>
505	
506	      <para>To query and change modulator properties applications use
507	the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that
508	<constant>VIDIOC_S_MODULATOR</constant> does not switch the current
509	modulator, when there is more than one at all. The modulator is solely
510	determined by the current video output. Drivers must support both
511	ioctls and set the <constant>V4L2_CAP_MODULATOR</constant> flag in
512	the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl when the
513	device has one or more modulators.</para>
514	    </section>
515	
516	    <section>
517	      <title>Radio Frequency</title>
518	
519	      <para>To get and set the tuner or modulator radio frequency
520	applications use the &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY;
521	ioctl which both take a pointer to a &v4l2-frequency;. These ioctls
522	are used for TV and radio devices alike. Drivers must support both
523	ioctls when the tuner or modulator ioctls are supported, or
524	when the device is a radio device.</para>
525	    </section>
526	  </section>
527	
528	  <section id="standard">
529	    <title>Video Standards</title>
530	
531	    <para>Video devices typically support one or more different video
532	standards or variations of standards. Each video input and output may
533	support another set of standards. This set is reported by the
534	<structfield>std</structfield> field of &v4l2-input; and
535	&v4l2-output; returned by the &VIDIOC-ENUMINPUT; and
536	&VIDIOC-ENUMOUTPUT; ioctl, respectively.</para>
537	
538	    <para>V4L2 defines one bit for each analog video standard
539	currently in use worldwide, and sets aside bits for driver defined
540	standards, &eg; hybrid standards to watch NTSC video tapes on PAL TVs
541	and vice versa. Applications can use the predefined bits to select a
542	particular standard, although presenting the user a menu of supported
543	standards is preferred. To enumerate and query the attributes of the
544	supported standards applications use the &VIDIOC-ENUMSTD; ioctl.</para>
545	
546	    <para>Many of the defined standards are actually just variations
547	of a few major standards. The hardware may in fact not distinguish
548	between them, or do so internal and switch automatically. Therefore
549	enumerated standards also contain sets of one or more standard
550	bits.</para>
551	
552	    <para>Assume a hypothetic tuner capable of demodulating B/PAL,
553	G/PAL and I/PAL signals. The first enumerated standard is a set of B
554	and G/PAL, switched automatically depending on the selected radio
555	frequency in UHF or VHF band. Enumeration gives a "PAL-B/G" or "PAL-I"
556	choice. Similar a Composite input may collapse standards, enumerating
557	"PAL-B/G/H/I", "NTSC-M" and "SECAM-D/K".<footnote>
558		<para>Some users are already confused by technical terms PAL,
559	NTSC and SECAM. There is no point asking them to distinguish between
560	B, G, D, or K when the software or hardware can do that
561	automatically.</para>
562	    </footnote></para>
563	
564	    <para>To query and select the standard used by the current video
565	input or output applications call the &VIDIOC-G-STD; and
566	&VIDIOC-S-STD; ioctl, respectively. The <emphasis>received</emphasis>
567	standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note that the parameter of all these ioctls is a pointer to a &v4l2-std-id; type (a standard set), <emphasis>not</emphasis> an index into the standard enumeration.<footnote>
568		<para>An alternative to the current scheme is to use pointers
569	to indices as arguments of <constant>VIDIOC_G_STD</constant> and
570	<constant>VIDIOC_S_STD</constant>, the &v4l2-input; and
571	&v4l2-output; <structfield>std</structfield> field would be a set of
572	indices like <structfield>audioset</structfield>.</para>
573		<para>Indices are consistent with the rest of the API
574	and identify the standard unambiguously. In the present scheme of
575	things an enumerated standard is looked up by &v4l2-std-id;. Now the
576	standards supported by the inputs of a device can overlap. Just
577	assume the tuner and composite input in the example above both
578	exist on a device. An enumeration of "PAL-B/G", "PAL-H/I" suggests
579	a choice which does not exist. We cannot merge or omit sets, because
580	applications would be unable to find the standards reported by
581	<constant>VIDIOC_G_STD</constant>. That leaves separate enumerations
582	for each input. Also selecting a standard by &v4l2-std-id; can be
583	ambiguous. Advantage of this method is that applications need not
584	identify the standard indirectly, after enumerating.</para><para>So in
585	summary, the lookup itself is unavoidable. The difference is only
586	whether the lookup is necessary to find an enumerated standard or to
587	switch to a standard by &v4l2-std-id;.</para>
588	      </footnote> Drivers must implement all video standard ioctls
589	when the device has one or more video inputs or outputs.</para>
590	
591	    <para>Special rules apply to devices such as USB cameras where the notion of video
592	standards makes little sense. More generally for any capture or output device
593	which is: <itemizedlist>
594		<listitem>
595		  <para>incapable of capturing fields or frames at the nominal
596	rate of the video standard, or</para>
597		</listitem>
598		<listitem>
599		  <para>that does not support the video standard formats at all.</para>
600		</listitem>
601	      </itemizedlist> Here the driver shall set the
602	<structfield>std</structfield> field of &v4l2-input; and &v4l2-output;
603	to zero and the <constant>VIDIOC_G_STD</constant>,
604	<constant>VIDIOC_S_STD</constant>,
605	<constant>VIDIOC_QUERYSTD</constant> and
606	<constant>VIDIOC_ENUMSTD</constant> ioctls shall return the
607	&ENOTTY;.<footnote>
608		<para>See <xref linkend="buffer" /> for a rationale.</para>
609		<para>Applications can make use of the <xref linkend="input-capabilities" /> and
610	<xref linkend="output-capabilities"/> flags to determine whether the video standard ioctls
611	are available for the device.</para>
612	
613		<para>See <xref linkend="buffer" /> for a rationale. Probably
614	even USB cameras follow some well known video standard. It might have
615	been better to explicitly indicate elsewhere if a device cannot live
616	up to normal expectations, instead of this exception.</para>
617		    </footnote></para>
618	
619	    <example>
620	      <title>Information about the current video standard</title>
621	
622	      <programlisting>
623	&v4l2-std-id; std_id;
624	&v4l2-standard; standard;
625	
626	if (-1 == ioctl (fd, &VIDIOC-G-STD;, &amp;std_id)) {
627		/* Note when VIDIOC_ENUMSTD always returns ENOTTY this
628		   is no video device or it falls under the USB exception,
629		   and VIDIOC_G_STD returning ENOTTY is no error. */
630	
631		perror ("VIDIOC_G_STD");
632		exit (EXIT_FAILURE);
633	}
634	
635	memset (&amp;standard, 0, sizeof (standard));
636	standard.index = 0;
637	
638	while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
639		if (standard.id &amp; std_id) {
640		       printf ("Current video standard: %s\n", standard.name);
641		       exit (EXIT_SUCCESS);
642		}
643	
644		standard.index++;
645	}
646	
647	/* EINVAL indicates the end of the enumeration, which cannot be
648	   empty unless this device falls under the USB exception. */
649	
650	if (errno == EINVAL || standard.index == 0) {
651		perror ("VIDIOC_ENUMSTD");
652		exit (EXIT_FAILURE);
653	}
654	      </programlisting>
655	    </example>
656	
657	    <example>
658	      <title>Listing the video standards supported by the current
659	input</title>
660	
661	      <programlisting>
662	&v4l2-input; input;
663	&v4l2-standard; standard;
664	
665	memset (&amp;input, 0, sizeof (input));
666	
667	if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
668		perror ("VIDIOC_G_INPUT");
669		exit (EXIT_FAILURE);
670	}
671	
672	if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
673		perror ("VIDIOC_ENUM_INPUT");
674		exit (EXIT_FAILURE);
675	}
676	
677	printf ("Current input %s supports:\n", input.name);
678	
679	memset (&amp;standard, 0, sizeof (standard));
680	standard.index = 0;
681	
682	while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
683		if (standard.id &amp; input.std)
684			printf ("%s\n", standard.name);
685	
686		standard.index++;
687	}
688	
689	/* EINVAL indicates the end of the enumeration, which cannot be
690	   empty unless this device falls under the USB exception. */
691	
692	if (errno != EINVAL || standard.index == 0) {
693		perror ("VIDIOC_ENUMSTD");
694		exit (EXIT_FAILURE);
695	}
696	      </programlisting>
697	    </example>
698	
699	    <example>
700	      <title>Selecting a new video standard</title>
701	
702	      <programlisting>
703	&v4l2-input; input;
704	&v4l2-std-id; std_id;
705	
706	memset (&amp;input, 0, sizeof (input));
707	
708	if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
709		perror ("VIDIOC_G_INPUT");
710		exit (EXIT_FAILURE);
711	}
712	
713	if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
714		perror ("VIDIOC_ENUM_INPUT");
715		exit (EXIT_FAILURE);
716	}
717	
718	if (0 == (input.std &amp; V4L2_STD_PAL_BG)) {
719		fprintf (stderr, "Oops. B/G PAL is not supported.\n");
720		exit (EXIT_FAILURE);
721	}
722	
723	/* Note this is also supposed to work when only B
724	   <emphasis>or</emphasis> G/PAL is supported. */
725	
726	std_id = V4L2_STD_PAL_BG;
727	
728	if (-1 == ioctl (fd, &VIDIOC-S-STD;, &amp;std_id)) {
729		perror ("VIDIOC_S_STD");
730		exit (EXIT_FAILURE);
731	}
732	      </programlisting>
733	    </example>
734	  </section>
735	  <section id="dv-timings">
736		<title>Digital Video (DV) Timings</title>
737		<para>
738		The video standards discussed so far have been dealing with Analog TV and the
739	corresponding video timings. Today there are many more different hardware interfaces
740	such as High Definition TV interfaces (HDMI), VGA, DVI connectors etc., that carry
741	video signals and there is a need to extend the API to select the video timings
742	for these interfaces. Since it is not possible to extend the &v4l2-std-id; due to
743	the limited bits available, a new set of IOCTLs was added to set/get video timings at
744	the input and output: </para><itemizedlist>
745		<listitem>
746		<para>DV Timings: This will allow applications to define detailed
747	video timings for the interface. This includes parameters such as width, height,
748	polarities, frontporch, backporch etc. The <filename>linux/v4l2-dv-timings.h</filename>
749	header can be used to get the timings of the formats in the <xref linkend="cea861" /> and
750	<xref linkend="vesadmt" /> standards.
751		</para>
752		</listitem>
753		</itemizedlist>
754		<para>To enumerate and query the attributes of the DV timings supported by a device,
755		applications use the &VIDIOC-ENUM-DV-TIMINGS; and &VIDIOC-DV-TIMINGS-CAP; ioctls.
756		To set DV timings for the device, applications use the
757	&VIDIOC-S-DV-TIMINGS; ioctl and to get current DV timings they use the
758	&VIDIOC-G-DV-TIMINGS; ioctl. To detect the DV timings as seen by the video receiver applications
759	use the &VIDIOC-QUERY-DV-TIMINGS; ioctl.</para>
760		<para>Applications can make use of the <xref linkend="input-capabilities" /> and
761	<xref linkend="output-capabilities"/> flags to decide what ioctls are available to set the
762	video timings for the device.</para>
763	  </section>
764	
765	  &sub-controls;
766	
767	  <section id="format">
768	    <title>Data Formats</title>
769	
770	    <section>
771	      <title>Data Format Negotiation</title>
772	
773	      <para>Different devices exchange different kinds of data with
774	applications, for example video images, raw or sliced VBI data, RDS
775	datagrams. Even within one kind many different formats are possible,
776	in particular an abundance of image formats. Although drivers must
777	provide a default and the selection persists across closing and
778	reopening a device, applications should always negotiate a data format
779	before engaging in data exchange. Negotiation means the application
780	asks for a particular format and the driver selects and reports the
781	best the hardware can do to satisfy the request. Of course
782	applications can also just query the current selection.</para>
783	
784	      <para>A single mechanism exists to negotiate all data formats
785	using the aggregate &v4l2-format; and the &VIDIOC-G-FMT; and
786	&VIDIOC-S-FMT; ioctls. Additionally the &VIDIOC-TRY-FMT; ioctl can be
787	used to examine what the hardware <emphasis>could</emphasis> do,
788	without actually selecting a new data format. The data formats
789	supported by the V4L2 API are covered in the respective device section
790	in <xref linkend="devices" />. For a closer look at image formats see
791	<xref linkend="pixfmt" />.</para>
792	
793	      <para>The <constant>VIDIOC_S_FMT</constant> ioctl is a major
794	turning-point in the initialization sequence. Prior to this point
795	multiple panel applications can access the same device concurrently to
796	select the current input, change controls or modify other properties.
797	The first <constant>VIDIOC_S_FMT</constant> assigns a logical stream
798	(video data, VBI data etc.) exclusively to one file descriptor.</para>
799	
800	      <para>Exclusive means no other application, more precisely no
801	other file descriptor, can grab this stream or change device
802	properties inconsistent with the negotiated parameters. A video
803	standard change for example, when the new standard uses a different
804	number of scan lines, can invalidate the selected image format.
805	Therefore only the file descriptor owning the stream can make
806	invalidating changes. Accordingly multiple file descriptors which
807	grabbed different logical streams prevent each other from interfering
808	with their settings. When for example video overlay is about to start
809	or already in progress, simultaneous video capturing may be restricted
810	to the same cropping and image size.</para>
811	
812	      <para>When applications omit the
813	<constant>VIDIOC_S_FMT</constant> ioctl its locking side effects are
814	implied by the next step, the selection of an I/O method with the
815	&VIDIOC-REQBUFS; ioctl or implicit with the first &func-read; or
816	&func-write; call.</para>
817	
818	      <para>Generally only one logical stream can be assigned to a
819	file descriptor, the exception being drivers permitting simultaneous
820	video capturing and overlay using the same file descriptor for
821	compatibility with V4L and earlier versions of V4L2. Switching the
822	logical stream or returning into "panel mode" is possible by closing
823	and reopening the device. Drivers <emphasis>may</emphasis> support a
824	switch using <constant>VIDIOC_S_FMT</constant>.</para>
825	
826	      <para>All drivers exchanging data with
827	applications must support the <constant>VIDIOC_G_FMT</constant> and
828	<constant>VIDIOC_S_FMT</constant> ioctl. Implementation of the
829	<constant>VIDIOC_TRY_FMT</constant> is highly recommended but
830	optional.</para>
831	    </section>
832	
833	    <section>
834	      <title>Image Format Enumeration</title>
835	
836	      <para>Apart of the generic format negotiation functions
837	a special ioctl to enumerate all image formats supported by video
838	capture, overlay or output devices is available.<footnote>
839		  <para>Enumerating formats an application has no a-priori
840	knowledge of (otherwise it could explicitly ask for them and need not
841	enumerate) seems useless, but there are applications serving as proxy
842	between drivers and the actual video applications for which this is
843	useful.</para>
844		</footnote></para>
845	
846	      <para>The &VIDIOC-ENUM-FMT; ioctl must be supported
847	by all drivers exchanging image data with applications.</para>
848	
849	      <important>
850		<para>Drivers are not supposed to convert image formats in
851	kernel space. They must enumerate only formats directly supported by
852	the hardware. If necessary driver writers should publish an example
853	conversion routine or library for integration into applications.</para>
854	      </important>
855	    </section>
856	  </section>
857	
858	  &sub-planar-apis;
859	
860	  <section id="crop">
861	    <title>Image Cropping, Insertion and Scaling</title>
862	
863	    <para>Some video capture devices can sample a subsection of the
864	picture and shrink or enlarge it to an image of arbitrary size. We
865	call these abilities cropping and scaling. Some video output devices
866	can scale an image up or down and insert it at an arbitrary scan line
867	and horizontal offset into a video signal.</para>
868	
869	    <para>Applications can use the following API to select an area in
870	the video signal, query the default area and the hardware limits.
871	<emphasis>Despite their name, the &VIDIOC-CROPCAP;, &VIDIOC-G-CROP;
872	and &VIDIOC-S-CROP; ioctls apply to input as well as output
873	devices.</emphasis></para>
874	
875	    <para>Scaling requires a source and a target. On a video capture
876	or overlay device the source is the video signal, and the cropping
877	ioctls determine the area actually sampled. The target are images
878	read by the application or overlaid onto the graphics screen. Their
879	size (and position for an overlay) is negotiated with the
880	&VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls.</para>
881	
882	    <para>On a video output device the source are the images passed in
883	by the application, and their size is again negotiated with the
884	<constant>VIDIOC_G/S_FMT</constant> ioctls, or may be encoded in a
885	compressed video stream. The target is the video signal, and the
886	cropping ioctls determine the area where the images are
887	inserted.</para>
888	
889	    <para>Source and target rectangles are defined even if the device
890	does not support scaling or the <constant>VIDIOC_G/S_CROP</constant>
891	ioctls. Their size (and position where applicable) will be fixed in
892	this case. <emphasis>All capture and output device must support the
893	<constant>VIDIOC_CROPCAP</constant> ioctl such that applications can
894	determine if scaling takes place.</emphasis></para>
895	
896	    <section>
897	      <title>Cropping Structures</title>
898	
899	      <figure id="crop-scale">
900		<title>Image Cropping, Insertion and Scaling</title>
901		<mediaobject>
902		  <imageobject>
903		    <imagedata fileref="crop.pdf" format="PS" />
904		  </imageobject>
905		  <imageobject>
906		    <imagedata fileref="crop.gif" format="GIF" />
907		  </imageobject>
908		  <textobject>
909		    <phrase>The cropping, insertion and scaling process</phrase>
910		  </textobject>
911		</mediaobject>
912	      </figure>
913	
914	      <para>For capture devices the coordinates of the top left
915	corner, width and height of the area which can be sampled is given by
916	the <structfield>bounds</structfield> substructure of the
917	&v4l2-cropcap; returned by the <constant>VIDIOC_CROPCAP</constant>
918	ioctl. To support a wide range of hardware this specification does not
919	define an origin or units. However by convention drivers should
920	horizontally count unscaled samples relative to 0H (the leading edge
921	of the horizontal sync pulse, see <xref linkend="vbi-hsync" />).
922	Vertically ITU-R line
923	numbers of the first field (<xref linkend="vbi-525" />, <xref
924	linkend="vbi-625" />), multiplied by two if the driver can capture both
925	fields.</para>
926	
927	      <para>The top left corner, width and height of the source
928	rectangle, that is the area actually sampled, is given by &v4l2-crop;
929	using the same coordinate system as &v4l2-cropcap;. Applications can
930	use the <constant>VIDIOC_G_CROP</constant> and
931	<constant>VIDIOC_S_CROP</constant> ioctls to get and set this
932	rectangle. It must lie completely within the capture boundaries and
933	the driver may further adjust the requested size and/or position
934	according to hardware limitations.</para>
935	
936	      <para>Each capture device has a default source rectangle, given
937	by the <structfield>defrect</structfield> substructure of
938	&v4l2-cropcap;. The center of this rectangle shall align with the
939	center of the active picture area of the video signal, and cover what
940	the driver writer considers the complete picture. Drivers shall reset
941	the source rectangle to the default when the driver is first loaded,
942	but not later.</para>
943	
944	      <para>For output devices these structures and ioctls are used
945	accordingly, defining the <emphasis>target</emphasis> rectangle where
946	the images will be inserted into the video signal.</para>
947	
948	    </section>
949	
950	    <section>
951	      <title>Scaling Adjustments</title>
952	
953	      <para>Video hardware can have various cropping, insertion and
954	scaling limitations. It may only scale up or down, support only
955	discrete scaling factors, or have different scaling abilities in
956	horizontal and vertical direction. Also it may not support scaling at
957	all. At the same time the &v4l2-crop; rectangle may have to be
958	aligned, and both the source and target rectangles may have arbitrary
959	upper and lower size limits. In particular the maximum
960	<structfield>width</structfield> and <structfield>height</structfield>
961	in &v4l2-crop; may be smaller than the
962	&v4l2-cropcap;.<structfield>bounds</structfield> area. Therefore, as
963	usual, drivers are expected to adjust the requested parameters and
964	return the actual values selected.</para>
965	
966	      <para>Applications can change the source or the target rectangle
967	first, as they may prefer a particular image size or a certain area in
968	the video signal. If the driver has to adjust both to satisfy hardware
969	limitations, the last requested rectangle shall take priority, and the
970	driver should preferably adjust the opposite one. The &VIDIOC-TRY-FMT;
971	ioctl however shall not change the driver state and therefore only
972	adjust the requested rectangle.</para>
973	
974	      <para>Suppose scaling on a video capture device is restricted to
975	a factor 1:1 or 2:1 in either direction and the target image size must
976	be a multiple of 16&nbsp;&times;&nbsp;16 pixels. The source cropping
977	rectangle is set to defaults, which are also the upper limit in this
978	example, of 640&nbsp;&times;&nbsp;400 pixels at offset 0,&nbsp;0. An
979	application requests an image size of 300&nbsp;&times;&nbsp;225
980	pixels, assuming video will be scaled down from the "full picture"
981	accordingly. The driver sets the image size to the closest possible
982	values 304&nbsp;&times;&nbsp;224, then chooses the cropping rectangle
983	closest to the requested size, that is 608&nbsp;&times;&nbsp;224
984	(224&nbsp;&times;&nbsp;2:1 would exceed the limit 400). The offset
985	0,&nbsp;0 is still valid, thus unmodified. Given the default cropping
986	rectangle reported by <constant>VIDIOC_CROPCAP</constant> the
987	application can easily propose another offset to center the cropping
988	rectangle.</para>
989	
990	      <para>Now the application may insist on covering an area using a
991	picture aspect ratio closer to the original request, so it asks for a
992	cropping rectangle of 608&nbsp;&times;&nbsp;456 pixels. The present
993	scaling factors limit cropping to 640&nbsp;&times;&nbsp;384, so the
994	driver returns the cropping size 608&nbsp;&times;&nbsp;384 and adjusts
995	the image size to closest possible 304&nbsp;&times;&nbsp;192.</para>
996	
997	    </section>
998	
999	    <section>
1000	      <title>Examples</title>
1001	
1002	      <para>Source and target rectangles shall remain unchanged across
1003	closing and reopening a device, such that piping data into or out of a
1004	device will work without special preparations. More advanced
1005	applications should ensure the parameters are suitable before starting
1006	I/O.</para>
1007	
1008	      <example>
1009		<title>Resetting the cropping parameters</title>
1010	
1011		<para>(A video capture device is assumed; change
1012	<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other
1013	devices.)</para>
1014	
1015		<programlisting>
1016	&v4l2-cropcap; cropcap;
1017	&v4l2-crop; crop;
1018	
1019	memset (&amp;cropcap, 0, sizeof (cropcap));
1020	cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1021	
1022	if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
1023		perror ("VIDIOC_CROPCAP");
1024		exit (EXIT_FAILURE);
1025	}
1026	
1027	memset (&amp;crop, 0, sizeof (crop));
1028	crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1029	crop.c = cropcap.defrect;
1030	
1031	/* Ignore if cropping is not supported (EINVAL). */
1032	
1033	if (-1 == ioctl (fd, &VIDIOC-S-CROP;, &amp;crop)
1034	    &amp;&amp; errno != EINVAL) {
1035		perror ("VIDIOC_S_CROP");
1036		exit (EXIT_FAILURE);
1037	}
1038	      </programlisting>
1039	      </example>
1040	
1041	      <example>
1042		<title>Simple downscaling</title>
1043	
1044		<para>(A video capture device is assumed.)</para>
1045	
1046		<programlisting>
1047	&v4l2-cropcap; cropcap;
1048	&v4l2-format; format;
1049	
1050	reset_cropping_parameters ();
1051	
1052	/* Scale down to 1/4 size of full picture. */
1053	
1054	memset (&amp;format, 0, sizeof (format)); /* defaults */
1055	
1056	format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1057	
1058	format.fmt.pix.width = cropcap.defrect.width &gt;&gt; 1;
1059	format.fmt.pix.height = cropcap.defrect.height &gt;&gt; 1;
1060	format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
1061	
1062	if (-1 == ioctl (fd, &VIDIOC-S-FMT;, &amp;format)) {
1063		perror ("VIDIOC_S_FORMAT");
1064		exit (EXIT_FAILURE);
1065	}
1066	
1067	/* We could check the actual image size now, the actual scaling factor
1068	   or if the driver can scale at all. */
1069		</programlisting>
1070	      </example>
1071	
1072	      <example>
1073		<title>Selecting an output area</title>
1074	
1075		<programlisting>
1076	&v4l2-cropcap; cropcap;
1077	&v4l2-crop; crop;
1078	
1079	memset (&amp;cropcap, 0, sizeof (cropcap));
1080	cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
1081	
1082	if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &amp;cropcap)) {
1083		perror ("VIDIOC_CROPCAP");
1084		exit (EXIT_FAILURE);
1085	}
1086	
1087	memset (&amp;crop, 0, sizeof (crop));
1088	
1089	crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
1090	crop.c = cropcap.defrect;
1091	
1092	/* Scale the width and height to 50 % of their original size
1093	   and center the output. */
1094	
1095	crop.c.width /= 2;
1096	crop.c.height /= 2;
1097	crop.c.left += crop.c.width / 2;
1098	crop.c.top += crop.c.height / 2;
1099	
1100	/* Ignore if cropping is not supported (EINVAL). */
1101	
1102	if (-1 == ioctl (fd, VIDIOC_S_CROP, &amp;crop)
1103	    &amp;&amp; errno != EINVAL) {
1104		perror ("VIDIOC_S_CROP");
1105		exit (EXIT_FAILURE);
1106	}
1107	</programlisting>
1108	      </example>
1109	
1110	      <example>
1111		<title>Current scaling factor and pixel aspect</title>
1112	
1113		<para>(A video capture device is assumed.)</para>
1114	
1115		<programlisting>
1116	&v4l2-cropcap; cropcap;
1117	&v4l2-crop; crop;
1118	&v4l2-format; format;
1119	double hscale, vscale;
1120	double aspect;
1121	int dwidth, dheight;
1122	
1123	memset (&amp;cropcap, 0, sizeof (cropcap));
1124	cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1125	
1126	if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
1127		perror ("VIDIOC_CROPCAP");
1128		exit (EXIT_FAILURE);
1129	}
1130	
1131	memset (&amp;crop, 0, sizeof (crop));
1132	crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1133	
1134	if (-1 == ioctl (fd, &VIDIOC-G-CROP;, &amp;crop)) {
1135		if (errno != EINVAL) {
1136			perror ("VIDIOC_G_CROP");
1137			exit (EXIT_FAILURE);
1138		}
1139	
1140		/* Cropping not supported. */
1141		crop.c = cropcap.defrect;
1142	}
1143	
1144	memset (&amp;format, 0, sizeof (format));
1145	format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1146	
1147	if (-1 == ioctl (fd, &VIDIOC-G-FMT;, &amp;format)) {
1148		perror ("VIDIOC_G_FMT");
1149		exit (EXIT_FAILURE);
1150	}
1151	
1152	/* The scaling applied by the driver. */
1153	
1154	hscale = format.fmt.pix.width / (double) crop.c.width;
1155	vscale = format.fmt.pix.height / (double) crop.c.height;
1156	
1157	aspect = cropcap.pixelaspect.numerator /
1158		 (double) cropcap.pixelaspect.denominator;
1159	aspect = aspect * hscale / vscale;
1160	
1161	/* Devices following ITU-R BT.601 do not capture
1162	   square pixels. For playback on a computer monitor
1163	   we should scale the images to this size. */
1164	
1165	dwidth = format.fmt.pix.width / aspect;
1166	dheight = format.fmt.pix.height;
1167		</programlisting>
1168	      </example>
1169	    </section>
1170	  </section>
1171	
1172	  &sub-selection-api;
1173	
1174	  <section id="streaming-par">
1175	    <title>Streaming Parameters</title>
1176	
1177	    <para>Streaming parameters are intended to optimize the video
1178	capture process as well as I/O. Presently applications can request a
1179	high quality capture mode with the &VIDIOC-S-PARM; ioctl.</para>
1180	
1181	    <para>The current video standard determines a nominal number of
1182	frames per second. If less than this number of frames is to be
1183	captured or output, applications can request frame skipping or
1184	duplicating on the driver side. This is especially useful when using
1185	the &func-read; or &func-write;, which are not augmented by timestamps
1186	or sequence counters, and to avoid unnecessary data copying.</para>
1187	
1188	    <para>Finally these ioctls can be used to determine the number of
1189	buffers used internally by a driver in read/write mode. For
1190	implications see the section discussing the &func-read;
1191	function.</para>
1192	
1193	    <para>To get and set the streaming parameters applications call
1194	the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; ioctl, respectively. They take
1195	a pointer to a &v4l2-streamparm;, which contains a union holding
1196	separate parameters for input and output devices.</para>
1197	
1198	    <para>These ioctls are optional, drivers need not implement
1199	them. If so, they return the &EINVAL;.</para>
1200	  </section>
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.