About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / media / v4l / common.xml

Custom Search

Based on kernel version 3.15.4. Page generated on 2014-07-07 09:02 EST.

1	  <title>Common API Elements</title>
3	  <para>Programming a V4L2 device consists of these
4	steps:</para>
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>
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>
33	  <section id="open">
34	    <title>Opening and Closing Devices</title>
36	    <section>
37	      <title>Device Naming</title>
39	      <para>V4L2 drivers are implemented as kernel modules, loaded
40	manually by the system administrator or automatically when a device is
41	first discovered. 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>
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. Minor numbers
47	are allocated dynamically unless the kernel is compiled with the kernel
48	option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers are
49	allocated in ranges depending on the device node type (video, radio, etc.).</para>
51	      <para>Many drivers support "video_nr", "radio_nr" or "vbi_nr"
52	module options to select specific video/radio/vbi node numbers. This allows
53	the user to request that the device node is named e.g. /dev/video5 instead
54	of leaving it to chance. When the driver supports multiple devices of the same
55	type more than one device node number can be assigned, separated by commas:
56		<informalexample>
57		  <screen>
58	&gt; modprobe mydriver video_nr=0,1 radio_nr=0,1</screen>
59		</informalexample></para>
61	      <para>In <filename>/etc/modules.conf</filename> this may be
62	written as: <informalexample>
63		  <screen>
64	options mydriver video_nr=0,1 radio_nr=0,1
65		  </screen>
66		</informalexample> When no device node number is given as module
67	option the driver supplies a default.</para>
69	      <para>Normally udev will create the device nodes in /dev automatically
70	for you. If udev is not installed, then you need to enable the
71	CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to correctly
72	relate a minor number to a device node number. I.e., you need to be certain
73	that minor number 5 maps to device node name video5. With this kernel option
74	different device types have different minor number ranges. These ranges are
75	listed in <xref linkend="devices" />.
76	</para>
78	      <para>The creation of character special files (with
79	<application>mknod</application>) is a privileged operation and
80	devices cannot be opened by major and minor number. That means
81	applications cannot <emphasis>reliable</emphasis> scan for loaded or
82	installed drivers. The user must enter a device name, or the
83	application can try the conventional device names.</para>
84	    </section>
86	    <section id="related">
87	      <title>Related Devices</title>
89	      <para>Devices can support several functions. For example
90	video capturing, VBI capturing and radio support.</para>
92	      <para>The V4L2 API creates different nodes for each of these functions.</para>
94	      <para>The V4L2 API was designed with the idea that one device node could support
95	all functions. However, in practice this never worked: this 'feature'
96	was never used by applications and many drivers did not support it and if
97	they did it was certainly never tested. In addition, switching a device
98	node between different functions only works when using the streaming I/O
99	API, not with the read()/write() API.</para>
101	      <para>Today each device node supports just one function.</para>
103	      <para>Besides video input or output the hardware may also
104	support audio sampling or playback. If so, these functions are
105	implemented as ALSA PCM devices with optional ALSA audio mixer
106	devices.</para>
108	      <para>One problem with all these devices is that the V4L2 API
109	makes no provisions to find these related devices. Some really
110	complex devices use the Media Controller (see <xref linkend="media_controller" />)
111	which can be used for this purpose. But most drivers do not use it,
112	and 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>
114	git repository), there is no library yet that can provide a single API towards
115	both Media Controller-based devices and devices that do not use the Media Controller.
116	If you want to work on this please write to the linux-media mailing list: &v4l-ml;.</para>
117	    </section>
119	    <section>
120	      <title>Multiple Opens</title>
122	      <para>V4L2 devices can be opened more than once.<footnote><para>
123	There are still some old and obscure drivers that have not been updated to
124	allow for multiple opens. This implies that for such drivers &func-open; can
125	return an &EBUSY; when the device is already in use.</para></footnote>
126	When this is supported by the driver, users can for example start a
127	"panel" application to change controls like brightness or audio
128	volume, while another application captures video and audio. In other words, panel
129	applications are comparable to an ALSA audio mixer application.
130	Just 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
132	device to radio mode in many drivers. This behavior should be fixed eventually
133	as it violates the V4L2 specification.</para></footnote></para>
135	      <para>Once an application has allocated the memory buffers needed for
136	streaming data (by calling the &VIDIOC-REQBUFS; or &VIDIOC-CREATE-BUFS; ioctls,
137	or implicitly by calling the &func-read; or &func-write; functions) that
138	application (filehandle) becomes the owner of the device. It is no longer
139	allowed to make changes that would affect the buffer sizes (e.g. by calling
140	the &VIDIOC-S-FMT; ioctl) and other applications are no longer allowed to allocate
141	buffers or start or stop streaming. The &EBUSY; will be returned instead.</para>
143	      <para>Merely opening a V4L2 device does not grant exclusive
144	access.<footnote>
145		  <para>Drivers could recognize the
146	<constant>O_EXCL</constant> open flag. Presently this is not required,
147	so applications cannot know if it really works.</para>
148		</footnote> Initiating data exchange however assigns the right
149	to read or write the requested type of data, and to change related
150	properties, to this file descriptor. Applications can request
151	additional access privileges using the priority mechanism described in
152	<xref linkend="app-pri" />.</para>
153	    </section>
155	    <section>
156	      <title>Shared Data Streams</title>
158	      <para>V4L2 drivers should not support multiple applications
159	reading or writing the same data stream on a device by copying
160	buffers, time multiplexing or similar means. This is better handled by
161	a proxy application in user space.</para>
162	    </section>
164	    <section>
165	      <title>Functions</title>
167	    <para>To open and close V4L2 devices applications use the
168	&func-open; and &func-close; function, respectively. Devices are
169	programmed using the &func-ioctl; function as explained in the
170	following sections.</para>
171	    </section>
172	  </section>
174	  <section id="querycap">
175	    <title>Querying Capabilities</title>
177	    <para>Because V4L2 covers a wide variety of devices not all
178	aspects of the API are equally applicable to all types of devices.
179	Furthermore devices of the same type have different capabilities and
180	this specification permits the omission of a few complicated and less
181	important parts of the API.</para>
183	    <para>The &VIDIOC-QUERYCAP; ioctl is available to check if the kernel
184	device is compatible with this specification, and to query the <link
185	linkend="devices">functions</link> and <link linkend="io">I/O
186	methods</link> supported by the device.</para>
188	    <para>Starting with kernel version 3.1, VIDIOC-QUERYCAP will return the
189	V4L2 API version used by the driver, with generally matches the Kernel version.
190	There's no need of using &VIDIOC-QUERYCAP; to check if a specific ioctl is
191	supported, the V4L2 core now returns ENOTTY if a driver doesn't provide
192	support for an ioctl.</para>
194	    <para>Other features can be queried
195	by calling the respective ioctl, for example &VIDIOC-ENUMINPUT;
196	to learn about the number, types and names of video connectors on the
197	device. Although abstraction is a major objective of this API, the
198	&VIDIOC-QUERYCAP; ioctl also allows driver specific applications to reliably identify
199	the driver.</para>
201	    <para>All V4L2 drivers must support
202	<constant>VIDIOC_QUERYCAP</constant>. Applications should always call
203	this ioctl after opening the device.</para>
204	  </section>
206	  <section id="app-pri">
207	    <title>Application Priority</title>
209	    <para>When multiple applications share a device it may be
210	desirable to assign them different priorities. Contrary to the
211	traditional "rm -rf /" school of thought a video recording application
212	could for example block other applications from changing video
213	controls or switching the current TV channel. Another objective is to
214	permit low priority applications working in background, which can be
215	preempted by user controlled applications and automatically regain
216	control of the device at a later time.</para>
218	    <para>Since these features cannot be implemented entirely in user
219	space V4L2 defines the &VIDIOC-G-PRIORITY; and &VIDIOC-S-PRIORITY;
220	ioctls to request and query the access priority associate with a file
221	descriptor. Opening a device assigns a medium priority, compatible
222	with earlier versions of V4L2 and drivers not supporting these ioctls.
223	Applications requiring a different priority will usually call
224	<constant>VIDIOC_S_PRIORITY</constant> after verifying the device with
225	the &VIDIOC-QUERYCAP; ioctl.</para>
227	    <para>Ioctls changing driver properties, such as &VIDIOC-S-INPUT;,
228	return an &EBUSY; after another application obtained higher priority.</para>
229	  </section>
231	  <section id="video">
232	    <title>Video Inputs and Outputs</title>
234	    <para>Video inputs and outputs are physical connectors of a
235	device. These can be for example RF connectors (antenna/cable), CVBS
236	a.k.a. Composite Video, S-Video or RGB connectors. Video and VBI
237	capture devices have inputs. Video and VBI output devices have outputs,
238	at least one each. Radio devices have no video inputs or outputs.</para>
240	    <para>To learn about the number and attributes of the
241	available 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>
244	ioctl also contains signal status information applicable when the
245	current video input is queried.</para>
247	    <para>The &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; ioctls return the
248	index of the current video input or output. To select a different
249	input or output applications call the &VIDIOC-S-INPUT; and
250	&VIDIOC-S-OUTPUT; ioctls. Drivers must implement all the input ioctls
251	when the device has one or more inputs, all the output ioctls when the
252	device has one or more outputs.</para>
254	    <example>
255	      <title>Information about the current video input</title>
257	      <programlisting>
258	&v4l2-input; input;
259	int index;
261	if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &amp;index)) {
262		perror("VIDIOC_G_INPUT");
263		exit(EXIT_FAILURE);
264	}
266	memset(&amp;input, 0, sizeof(input));
267	input.index = index;
269	if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
270		perror("VIDIOC_ENUMINPUT");
271		exit(EXIT_FAILURE);
272	}
274	printf("Current input: %s\n", input.name);
275	      </programlisting>
276	    </example>
278	    <example>
279	      <title>Switching to the first video input</title>
281	      <programlisting>
282	int index;
284	index = 0;
286	if (-1 == ioctl(fd, &VIDIOC-S-INPUT;, &amp;index)) {
287		perror("VIDIOC_S_INPUT");
288		exit(EXIT_FAILURE);
289	}
290	      </programlisting>
291	    </example>
292	  </section>
294	  <section id="audio">
295	    <title>Audio Inputs and Outputs</title>
297	    <para>Audio inputs and outputs are physical connectors of a
298	device. Video capture devices have inputs, output devices have
299	outputs, zero or more each. Radio devices have no audio inputs or
300	outputs. They have exactly one tuner which in fact
301	<emphasis>is</emphasis> an audio source, but this API associates
302	tuners with video inputs or outputs only, and radio devices have
303	none of these.<footnote>
304		<para>Actually &v4l2-audio; ought to have a
305	<structfield>tuner</structfield> field like &v4l2-input;, not only
306	making the API more consistent but also permitting radio devices with
307	multiple tuners.</para>
308	      </footnote> A connector on a TV card to loop back the received
309	audio signal to a sound card is not considered an audio output.</para>
311	    <para>Audio and video inputs and outputs are associated. Selecting
312	a video source also selects an audio source. This is most evident when
313	the video and audio source is a tuner. Further audio connectors can
314	combine with more than one video input or output. Assumed two
315	composite video inputs and two audio inputs exist, there may be up to
316	four valid combinations. The relation of video and audio connectors
317	is defined in the <structfield>audioset</structfield> field of the
318	respective &v4l2-input; or &v4l2-output;, where each bit represents
319	the index number, starting at zero, of one audio input or output.</para>
321	    <para>To learn about the number and attributes of the
322	available 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
325	also contains signal status information applicable when the current
326	audio input is queried.</para>
328	    <para>The &VIDIOC-G-AUDIO; and &VIDIOC-G-AUDOUT; ioctls report
329	the current audio input and output, respectively. Note that, unlike
330	&VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; these ioctls return a structure
331	as <constant>VIDIOC_ENUMAUDIO</constant> and
332	<constant>VIDIOC_ENUMAUDOUT</constant> do, not just an index.</para>
334	    <para>To select an audio input and change its properties
335	applications call the &VIDIOC-S-AUDIO; ioctl. To select an audio
336	output (which presently has no changeable properties) applications
337	call the &VIDIOC-S-AUDOUT; ioctl.</para>
339	    <para>Drivers must implement all audio input ioctls when the device
340	has multiple selectable audio inputs, all audio output ioctls when the
341	device has multiple selectable audio outputs. When the device has any
342	audio inputs or outputs the driver must set the <constant>V4L2_CAP_AUDIO</constant>
343	flag in the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl.</para>
345	    <example>
346	      <title>Information about the current audio input</title>
348	      <programlisting>
349	&v4l2-audio; audio;
351	memset(&amp;audio, 0, sizeof(audio));
353	if (-1 == ioctl(fd, &VIDIOC-G-AUDIO;, &amp;audio)) {
354		perror("VIDIOC_G_AUDIO");
355		exit(EXIT_FAILURE);
356	}
358	printf("Current input: %s\n", audio.name);
359	      </programlisting>
360	    </example>
362	    <example>
363	      <title>Switching to the first audio input</title>
365	      <programlisting>
366	&v4l2-audio; audio;
368	memset(&amp;audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */
370	audio.index = 0;
372	if (-1 == ioctl(fd, &VIDIOC-S-AUDIO;, &amp;audio)) {
373		perror("VIDIOC_S_AUDIO");
374		exit(EXIT_FAILURE);
375	}
376	      </programlisting>
377	    </example>
378	  </section>
380	  <section id="tuner">
381	    <title>Tuners and Modulators</title>
383	    <section>
384	      <title>Tuners</title>
386	      <para>Video input devices can have one or more tuners
387	demodulating a RF signal. Each tuner is associated with one or more
388	video inputs, depending on the number of RF connectors on the tuner.
389	The <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
393	the tuner.</para>
395	      <para>Radio input devices have exactly one tuner with index zero, no
396	video inputs.</para>
398	      <para>To query and change tuner properties applications use the
399	&VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctls, respectively. The
400	&v4l2-tuner; returned by <constant>VIDIOC_G_TUNER</constant> also
401	contains signal status information applicable when the tuner of the
402	current video or radio input is queried. Note that
403	<constant>VIDIOC_S_TUNER</constant> does not switch the current tuner,
404	when there is more than one at all. The tuner is solely determined by
405	the current video input. Drivers must support both ioctls and set the
406	<constant>V4L2_CAP_TUNER</constant> flag in the &v4l2-capability;
407	returned by the &VIDIOC-QUERYCAP; ioctl when the device has one or
408	more tuners.</para>
409	    </section>
411	    <section>
412	      <title>Modulators</title>
414	      <para>Video output devices can have one or more modulators, uh,
415	modulating a video signal for radiation or connection to the antenna
416	input of a TV set or video recorder. Each modulator is associated with
417	one or more video outputs, depending on the number of RF connectors on
418	the modulator. The <structfield>type</structfield> field of the
419	respective &v4l2-output; returned by the &VIDIOC-ENUMOUTPUT; ioctl is
420	set to <constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> and its
421	<structfield>modulator</structfield> field contains the index number
422	of the modulator.</para>
424	      <para>Radio output devices have exactly one modulator with index
425	zero, no video outputs.</para>
427	      <para>A video or radio device cannot support both a tuner and a
428	modulator. Two separate device nodes will have to be used for such
429	hardware, one that supports the tuner functionality and one that supports
430	the modulator functionality. The reason is a limitation with the
431	&VIDIOC-S-FREQUENCY; ioctl where you cannot specify whether the frequency
432	is for a tuner or a modulator.</para>
434	      <para>To query and change modulator properties applications use
435	the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that
436	<constant>VIDIOC_S_MODULATOR</constant> does not switch the current
437	modulator, when there is more than one at all. The modulator is solely
438	determined by the current video output. Drivers must support both
439	ioctls and set the <constant>V4L2_CAP_MODULATOR</constant> flag in
440	the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl when the
441	device has one or more modulators.</para>
442	    </section>
444	    <section>
445	      <title>Radio Frequency</title>
447	      <para>To get and set the tuner or modulator radio frequency
448	applications use the &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY;
449	ioctl which both take a pointer to a &v4l2-frequency;. These ioctls
450	are used for TV and radio devices alike. Drivers must support both
451	ioctls when the tuner or modulator ioctls are supported, or
452	when the device is a radio device.</para>
453	    </section>
454	  </section>
456	  <section id="standard">
457	    <title>Video Standards</title>
459	    <para>Video devices typically support one or more different video
460	standards or variations of standards. Each video input and output may
461	support 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
464	&VIDIOC-ENUMOUTPUT; ioctls, respectively.</para>
466	    <para>V4L2 defines one bit for each analog video standard
467	currently in use worldwide, and sets aside bits for driver defined
468	standards, &eg; hybrid standards to watch NTSC video tapes on PAL TVs
469	and vice versa. Applications can use the predefined bits to select a
470	particular standard, although presenting the user a menu of supported
471	standards is preferred. To enumerate and query the attributes of the
472	supported standards applications use the &VIDIOC-ENUMSTD; ioctl.</para>
474	    <para>Many of the defined standards are actually just variations
475	of a few major standards. The hardware may in fact not distinguish
476	between them, or do so internal and switch automatically. Therefore
477	enumerated standards also contain sets of one or more standard
478	bits.</para>
480	    <para>Assume a hypothetic tuner capable of demodulating B/PAL,
481	G/PAL and I/PAL signals. The first enumerated standard is a set of B
482	and G/PAL, switched automatically depending on the selected radio
483	frequency in UHF or VHF band. Enumeration gives a "PAL-B/G" or "PAL-I"
484	choice. 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,
487	NTSC and SECAM. There is no point asking them to distinguish between
488	B, G, D, or K when the software or hardware can do that
489	automatically.</para>
490	    </footnote></para>
492	    <para>To query and select the standard used by the current video
493	input or output applications call the &VIDIOC-G-STD; and
494	&VIDIOC-S-STD; ioctl, respectively. The <emphasis>received</emphasis>
495	standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note that the
496	parameter 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
498	enumeration. Drivers must implement all video standard ioctls
499	when the device has one or more video inputs or outputs.</para>
501	    <para>Special rules apply to devices such as USB cameras where the notion of video
502	standards makes little sense. More generally for any capture or output device
503	which is: <itemizedlist>
504		<listitem>
505		  <para>incapable of capturing fields or frames at the nominal
506	rate of the video standard, or</para>
507		</listitem>
508		<listitem>
509		  <para>that does not support the video standard formats at all.</para>
510		</listitem>
511	      </itemizedlist> Here the driver shall set the
512	<structfield>std</structfield> field of &v4l2-input; and &v4l2-output;
513	to zero and the <constant>VIDIOC_G_STD</constant>,
514	<constant>VIDIOC_S_STD</constant>,
515	<constant>VIDIOC_QUERYSTD</constant> and
516	<constant>VIDIOC_ENUMSTD</constant> ioctls shall return the
517	&ENOTTY; or the &EINVAL;.</para>
518		<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
520	can be used with the given input or output.</para>
522	    <example>
523	      <title>Information about the current video standard</title>
525	      <programlisting>
526	&v4l2-std-id; std_id;
527	&v4l2-standard; standard;
529	if (-1 == ioctl(fd, &VIDIOC-G-STD;, &amp;std_id)) {
530		/* Note when VIDIOC_ENUMSTD always returns ENOTTY this
531		   is no video device or it falls under the USB exception,
532		   and VIDIOC_G_STD returning ENOTTY is no error. */
534		perror("VIDIOC_G_STD");
535		exit(EXIT_FAILURE);
536	}
538	memset(&amp;standard, 0, sizeof(standard));
539	standard.index = 0;
541	while (0 == ioctl(fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
542		if (standard.id &amp; std_id) {
543		       printf("Current video standard: %s\n", standard.name);
544		       exit(EXIT_SUCCESS);
545		}
547		standard.index++;
548	}
550	/* EINVAL indicates the end of the enumeration, which cannot be
551	   empty unless this device falls under the USB exception. */
553	if (errno == EINVAL || standard.index == 0) {
554		perror("VIDIOC_ENUMSTD");
555		exit(EXIT_FAILURE);
556	}
557	      </programlisting>
558	    </example>
560	    <example>
561	      <title>Listing the video standards supported by the current
562	input</title>
564	      <programlisting>
565	&v4l2-input; input;
566	&v4l2-standard; standard;
568	memset(&amp;input, 0, sizeof(input));
570	if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
571		perror("VIDIOC_G_INPUT");
572		exit(EXIT_FAILURE);
573	}
575	if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
576		perror("VIDIOC_ENUM_INPUT");
577		exit(EXIT_FAILURE);
578	}
580	printf("Current input %s supports:\n", input.name);
582	memset(&amp;standard, 0, sizeof(standard));
583	standard.index = 0;
585	while (0 == ioctl(fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
586		if (standard.id &amp; input.std)
587			printf("%s\n", standard.name);
589		standard.index++;
590	}
592	/* EINVAL indicates the end of the enumeration, which cannot be
593	   empty unless this device falls under the USB exception. */
595	if (errno != EINVAL || standard.index == 0) {
596		perror("VIDIOC_ENUMSTD");
597		exit(EXIT_FAILURE);
598	}
599	      </programlisting>
600	    </example>
602	    <example>
603	      <title>Selecting a new video standard</title>
605	      <programlisting>
606	&v4l2-input; input;
607	&v4l2-std-id; std_id;
609	memset(&amp;input, 0, sizeof(input));
611	if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
612		perror("VIDIOC_G_INPUT");
613		exit(EXIT_FAILURE);
614	}
616	if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
617		perror("VIDIOC_ENUM_INPUT");
618		exit(EXIT_FAILURE);
619	}
621	if (0 == (input.std &amp; V4L2_STD_PAL_BG)) {
622		fprintf(stderr, "Oops. B/G PAL is not supported.\n");
623		exit(EXIT_FAILURE);
624	}
626	/* Note this is also supposed to work when only B
627	   <emphasis>or</emphasis> G/PAL is supported. */
629	std_id = V4L2_STD_PAL_BG;
631	if (-1 == ioctl(fd, &VIDIOC-S-STD;, &amp;std_id)) {
632		perror("VIDIOC_S_STD");
633		exit(EXIT_FAILURE);
634	}
635	      </programlisting>
636	    </example>
637	  </section>
638	  <section id="dv-timings">
639		<title>Digital Video (DV) Timings</title>
640		<para>
641		The video standards discussed so far have been dealing with Analog TV and the
642	corresponding video timings. Today there are many more different hardware interfaces
643	such as High Definition TV interfaces (HDMI), VGA, DVI connectors etc., that carry
644	video signals and there is a need to extend the API to select the video timings
645	for these interfaces. Since it is not possible to extend the &v4l2-std-id; due to
646	the limited bits available, a new set of ioctls was added to set/get video timings at
647	the input and output.</para>
649		<para>These ioctls deal with the detailed digital video timings that define
650	each video format. This includes parameters such as the active video width and height,
651	signal polarities, frontporches, backporches, sync widths etc. The <filename>linux/v4l2-dv-timings.h</filename>
652	header can be used to get the timings of the formats in the <xref linkend="cea861" /> and
653	<xref linkend="vesadmt" /> standards.
654		</para>
656		<para>To enumerate and query the attributes of the DV timings supported by a device
657		applications use the &VIDIOC-ENUM-DV-TIMINGS; and &VIDIOC-DV-TIMINGS-CAP; ioctls.
658		To set DV timings for the device applications use the
659	&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
661	use the &VIDIOC-QUERY-DV-TIMINGS; ioctl.</para>
662		<para>Applications can make use of the <xref linkend="input-capabilities" /> and
663	<xref linkend="output-capabilities"/> flags to determine whether the digital video ioctls
664	can be used with the given input or output.</para>
665	  </section>
667	  &sub-controls;
669	  <section id="format">
670	    <title>Data Formats</title>
672	    <section>
673	      <title>Data Format Negotiation</title>
675	      <para>Different devices exchange different kinds of data with
676	applications, for example video images, raw or sliced VBI data, RDS
677	datagrams. Even within one kind many different formats are possible,
678	in particular an abundance of image formats. Although drivers must
679	provide a default and the selection persists across closing and
680	reopening a device, applications should always negotiate a data format
681	before engaging in data exchange. Negotiation means the application
682	asks for a particular format and the driver selects and reports the
683	best the hardware can do to satisfy the request. Of course
684	applications can also just query the current selection.</para>
686	      <para>A single mechanism exists to negotiate all data formats
687	using the aggregate &v4l2-format; and the &VIDIOC-G-FMT; and
688	&VIDIOC-S-FMT; ioctls. Additionally the &VIDIOC-TRY-FMT; ioctl can be
689	used to examine what the hardware <emphasis>could</emphasis> do,
690	without actually selecting a new data format. The data formats
691	supported by the V4L2 API are covered in the respective device section
692	in <xref linkend="devices" />. For a closer look at image formats see
693	<xref linkend="pixfmt" />.</para>
695	      <para>The <constant>VIDIOC_S_FMT</constant> ioctl is a major
696	turning-point in the initialization sequence. Prior to this point
697	multiple panel applications can access the same device concurrently to
698	select the current input, change controls or modify other properties.
699	The first <constant>VIDIOC_S_FMT</constant> assigns a logical stream
700	(video data, VBI data etc.) exclusively to one file descriptor.</para>
702	      <para>Exclusive means no other application, more precisely no
703	other file descriptor, can grab this stream or change device
704	properties inconsistent with the negotiated parameters. A video
705	standard change for example, when the new standard uses a different
706	number of scan lines, can invalidate the selected image format.
707	Therefore only the file descriptor owning the stream can make
708	invalidating changes. Accordingly multiple file descriptors which
709	grabbed different logical streams prevent each other from interfering
710	with their settings. When for example video overlay is about to start
711	or already in progress, simultaneous video capturing may be restricted
712	to the same cropping and image size.</para>
714	      <para>When applications omit the
715	<constant>VIDIOC_S_FMT</constant> ioctl its locking side effects are
716	implied 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>
720	      <para>Generally only one logical stream can be assigned to a
721	file descriptor, the exception being drivers permitting simultaneous
722	video capturing and overlay using the same file descriptor for
723	compatibility with V4L and earlier versions of V4L2. Switching the
724	logical stream or returning into "panel mode" is possible by closing
725	and reopening the device. Drivers <emphasis>may</emphasis> support a
726	switch using <constant>VIDIOC_S_FMT</constant>.</para>
728	      <para>All drivers exchanging data with
729	applications 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
732	optional.</para>
733	    </section>
735	    <section>
736	      <title>Image Format Enumeration</title>
738	      <para>Apart of the generic format negotiation functions
739	a special ioctl to enumerate all image formats supported by video
740	capture, overlay or output devices is available.<footnote>
741		  <para>Enumerating formats an application has no a-priori
742	knowledge of (otherwise it could explicitly ask for them and need not
743	enumerate) seems useless, but there are applications serving as proxy
744	between drivers and the actual video applications for which this is
745	useful.</para>
746		</footnote></para>
748	      <para>The &VIDIOC-ENUM-FMT; ioctl must be supported
749	by all drivers exchanging image data with applications.</para>
751	      <important>
752		<para>Drivers are not supposed to convert image formats in
753	kernel space. They must enumerate only formats directly supported by
754	the hardware. If necessary driver writers should publish an example
755	conversion routine or library for integration into applications.</para>
756	      </important>
757	    </section>
758	  </section>
760	  &sub-planar-apis;
762	  <section id="crop">
763	    <title>Image Cropping, Insertion and Scaling</title>
765	    <para>Some video capture devices can sample a subsection of the
766	picture and shrink or enlarge it to an image of arbitrary size. We
767	call these abilities cropping and scaling. Some video output devices
768	can scale an image up or down and insert it at an arbitrary scan line
769	and horizontal offset into a video signal.</para>
771	    <para>Applications can use the following API to select an area in
772	the video signal, query the default area and the hardware limits.
773	<emphasis>Despite their name, the &VIDIOC-CROPCAP;, &VIDIOC-G-CROP;
774	and &VIDIOC-S-CROP; ioctls apply to input as well as output
775	devices.</emphasis></para>
777	    <para>Scaling requires a source and a target. On a video capture
778	or overlay device the source is the video signal, and the cropping
779	ioctls determine the area actually sampled. The target are images
780	read by the application or overlaid onto the graphics screen. Their
781	size (and position for an overlay) is negotiated with the
782	&VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls.</para>
784	    <para>On a video output device the source are the images passed in
785	by the application, and their size is again negotiated with the
786	<constant>VIDIOC_G/S_FMT</constant> ioctls, or may be encoded in a
787	compressed video stream. The target is the video signal, and the
788	cropping ioctls determine the area where the images are
789	inserted.</para>
791	    <para>Source and target rectangles are defined even if the device
792	does not support scaling or the <constant>VIDIOC_G/S_CROP</constant>
793	ioctls. Their size (and position where applicable) will be fixed in
794	this case. <emphasis>All capture and output device must support the
795	<constant>VIDIOC_CROPCAP</constant> ioctl such that applications can
796	determine if scaling takes place.</emphasis></para>
798	    <section>
799	      <title>Cropping Structures</title>
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>
816	      <para>For capture devices the coordinates of the top left
817	corner, width and height of the area which can be sampled is given by
818	the <structfield>bounds</structfield> substructure of the
819	&v4l2-cropcap; returned by the <constant>VIDIOC_CROPCAP</constant>
820	ioctl. To support a wide range of hardware this specification does not
821	define an origin or units. However by convention drivers should
822	horizontally count unscaled samples relative to 0H (the leading edge
823	of the horizontal sync pulse, see <xref linkend="vbi-hsync" />).
824	Vertically ITU-R line
825	numbers of the first field (<xref linkend="vbi-525" />, <xref
826	linkend="vbi-625" />), multiplied by two if the driver can capture both
827	fields.</para>
829	      <para>The top left corner, width and height of the source
830	rectangle, that is the area actually sampled, is given by &v4l2-crop;
831	using the same coordinate system as &v4l2-cropcap;. Applications can
832	use the <constant>VIDIOC_G_CROP</constant> and
833	<constant>VIDIOC_S_CROP</constant> ioctls to get and set this
834	rectangle. It must lie completely within the capture boundaries and
835	the driver may further adjust the requested size and/or position
836	according to hardware limitations.</para>
838	      <para>Each capture device has a default source rectangle, given
839	by the <structfield>defrect</structfield> substructure of
840	&v4l2-cropcap;. The center of this rectangle shall align with the
841	center of the active picture area of the video signal, and cover what
842	the driver writer considers the complete picture. Drivers shall reset
843	the source rectangle to the default when the driver is first loaded,
844	but not later.</para>
846	      <para>For output devices these structures and ioctls are used
847	accordingly, defining the <emphasis>target</emphasis> rectangle where
848	the images will be inserted into the video signal.</para>
850	    </section>
852	    <section>
853	      <title>Scaling Adjustments</title>
855	      <para>Video hardware can have various cropping, insertion and
856	scaling limitations. It may only scale up or down, support only
857	discrete scaling factors, or have different scaling abilities in
858	horizontal and vertical direction. Also it may not support scaling at
859	all. At the same time the &v4l2-crop; rectangle may have to be
860	aligned, and both the source and target rectangles may have arbitrary
861	upper and lower size limits. In particular the maximum
862	<structfield>width</structfield> and <structfield>height</structfield>
863	in &v4l2-crop; may be smaller than the
864	&v4l2-cropcap;.<structfield>bounds</structfield> area. Therefore, as
865	usual, drivers are expected to adjust the requested parameters and
866	return the actual values selected.</para>
868	      <para>Applications can change the source or the target rectangle
869	first, as they may prefer a particular image size or a certain area in
870	the video signal. If the driver has to adjust both to satisfy hardware
871	limitations, the last requested rectangle shall take priority, and the
872	driver should preferably adjust the opposite one. The &VIDIOC-TRY-FMT;
873	ioctl however shall not change the driver state and therefore only
874	adjust the requested rectangle.</para>
876	      <para>Suppose scaling on a video capture device is restricted to
877	a factor 1:1 or 2:1 in either direction and the target image size must
878	be a multiple of 16&nbsp;&times;&nbsp;16 pixels. The source cropping
879	rectangle is set to defaults, which are also the upper limit in this
880	example, of 640&nbsp;&times;&nbsp;400 pixels at offset 0,&nbsp;0. An
881	application requests an image size of 300&nbsp;&times;&nbsp;225
882	pixels, assuming video will be scaled down from the "full picture"
883	accordingly. The driver sets the image size to the closest possible
884	values 304&nbsp;&times;&nbsp;224, then chooses the cropping rectangle
885	closest 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
887	0,&nbsp;0 is still valid, thus unmodified. Given the default cropping
888	rectangle reported by <constant>VIDIOC_CROPCAP</constant> the
889	application can easily propose another offset to center the cropping
890	rectangle.</para>
892	      <para>Now the application may insist on covering an area using a
893	picture aspect ratio closer to the original request, so it asks for a
894	cropping rectangle of 608&nbsp;&times;&nbsp;456 pixels. The present
895	scaling factors limit cropping to 640&nbsp;&times;&nbsp;384, so the
896	driver returns the cropping size 608&nbsp;&times;&nbsp;384 and adjusts
897	the image size to closest possible 304&nbsp;&times;&nbsp;192.</para>
899	    </section>
901	    <section>
902	      <title>Examples</title>
904	      <para>Source and target rectangles shall remain unchanged across
905	closing and reopening a device, such that piping data into or out of a
906	device will work without special preparations. More advanced
907	applications should ensure the parameters are suitable before starting
908	I/O.</para>
910	      <example>
911		<title>Resetting the cropping parameters</title>
913		<para>(A video capture device is assumed; change
914	<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other
915	devices.)</para>
917		<programlisting>
918	&v4l2-cropcap; cropcap;
919	&v4l2-crop; crop;
921	memset (&amp;cropcap, 0, sizeof (cropcap));
922	cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
924	if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
925		perror ("VIDIOC_CROPCAP");
926		exit (EXIT_FAILURE);
927	}
929	memset (&amp;crop, 0, sizeof (crop));
930	crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
931	crop.c = cropcap.defrect;
933	/* Ignore if cropping is not supported (EINVAL). */
935	if (-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>
943	      <example>
944		<title>Simple downscaling</title>
946		<para>(A video capture device is assumed.)</para>
948		<programlisting>
949	&v4l2-cropcap; cropcap;
950	&v4l2-format; format;
952	reset_cropping_parameters ();
954	/* Scale down to 1/4 size of full picture. */
956	memset (&amp;format, 0, sizeof (format)); /* defaults */
958	format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
960	format.fmt.pix.width = cropcap.defrect.width &gt;&gt; 1;
961	format.fmt.pix.height = cropcap.defrect.height &gt;&gt; 1;
962	format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
964	if (-1 == ioctl (fd, &VIDIOC-S-FMT;, &amp;format)) {
965		perror ("VIDIOC_S_FORMAT");
966		exit (EXIT_FAILURE);
967	}
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>
974	      <example>
975		<title>Selecting an output area</title>
977		<programlisting>
978	&v4l2-cropcap; cropcap;
979	&v4l2-crop; crop;
981	memset (&amp;cropcap, 0, sizeof (cropcap));
982	cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
984	if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &amp;cropcap)) {
985		perror ("VIDIOC_CROPCAP");
986		exit (EXIT_FAILURE);
987	}
989	memset (&amp;crop, 0, sizeof (crop));
991	crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
992	crop.c = cropcap.defrect;
994	/* Scale the width and height to 50 % of their original size
995	   and center the output. */
997	crop.c.width /= 2;
998	crop.c.height /= 2;
999	crop.c.left += crop.c.width / 2;
1000	crop.c.top += crop.c.height / 2;
1002	/* Ignore if cropping is not supported (EINVAL). */
1004	if (-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>
1012	      <example>
1013		<title>Current scaling factor and pixel aspect</title>
1015		<para>(A video capture device is assumed.)</para>
1017		<programlisting>
1018	&v4l2-cropcap; cropcap;
1019	&v4l2-crop; crop;
1020	&v4l2-format; format;
1021	double hscale, vscale;
1022	double aspect;
1023	int dwidth, dheight;
1025	memset (&amp;cropcap, 0, sizeof (cropcap));
1026	cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1028	if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
1029		perror ("VIDIOC_CROPCAP");
1030		exit (EXIT_FAILURE);
1031	}
1033	memset (&amp;crop, 0, sizeof (crop));
1034	crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1036	if (-1 == ioctl (fd, &VIDIOC-G-CROP;, &amp;crop)) {
1037		if (errno != EINVAL) {
1038			perror ("VIDIOC_G_CROP");
1039			exit (EXIT_FAILURE);
1040		}
1042		/* Cropping not supported. */
1043		crop.c = cropcap.defrect;
1044	}
1046	memset (&amp;format, 0, sizeof (format));
1047	format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1049	if (-1 == ioctl (fd, &VIDIOC-G-FMT;, &amp;format)) {
1050		perror ("VIDIOC_G_FMT");
1051		exit (EXIT_FAILURE);
1052	}
1054	/* The scaling applied by the driver. */
1056	hscale = format.fmt.pix.width / (double) crop.c.width;
1057	vscale = format.fmt.pix.height / (double) crop.c.height;
1059	aspect = cropcap.pixelaspect.numerator /
1060		 (double) cropcap.pixelaspect.denominator;
1061	aspect = aspect * hscale / vscale;
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. */
1067	dwidth = format.fmt.pix.width / aspect;
1068	dheight = format.fmt.pix.height;
1069		</programlisting>
1070	      </example>
1071	    </section>
1072	  </section>
1074	  &sub-selection-api;
1076	  <section id="streaming-par">
1077	    <title>Streaming Parameters</title>
1079	    <para>Streaming parameters are intended to optimize the video
1080	capture process as well as I/O. Presently applications can request a
1081	high quality capture mode with the &VIDIOC-S-PARM; ioctl.</para>
1083	    <para>The current video standard determines a nominal number of
1084	frames per second. If less than this number of frames is to be
1085	captured or output, applications can request frame skipping or
1086	duplicating on the driver side. This is especially useful when using
1087	the &func-read; or &func-write;, which are not augmented by timestamps
1088	or sequence counters, and to avoid unnecessary data copying.</para>
1090	    <para>Finally these ioctls can be used to determine the number of
1091	buffers used internally by a driver in read/write mode. For
1092	implications see the section discussing the &func-read;
1093	function.</para>
1095	    <para>To get and set the streaming parameters applications call
1096	the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; ioctl, respectively. They take
1097	a pointer to a &v4l2-streamparm;, which contains a union holding
1098	separate parameters for input and output devices.</para>
1100	    <para>These ioctls are optional, drivers need not implement
1101	them. If so, they return the &EINVAL;.</para>
1102	  </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.