About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / media / v4l / vidioc-g-parm.xml




Custom Search

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

1	<refentry id="vidioc-g-parm">
2	  <refmeta>
3	    <refentrytitle>ioctl VIDIOC_G_PARM, VIDIOC_S_PARM</refentrytitle>
4	    &manvol;
5	  </refmeta>
6	
7	  <refnamediv>
8	    <refname>VIDIOC_G_PARM</refname>
9	    <refname>VIDIOC_S_PARM</refname>
10	    <refpurpose>Get or set streaming parameters</refpurpose>
11	  </refnamediv>
12	
13	  <refsynopsisdiv>
14	    <funcsynopsis>
15	      <funcprototype>
16		<funcdef>int <function>ioctl</function></funcdef>
17		<paramdef>int <parameter>fd</parameter></paramdef>
18		<paramdef>int <parameter>request</parameter></paramdef>
19		<paramdef>v4l2_streamparm *<parameter>argp</parameter></paramdef>
20	      </funcprototype>
21	    </funcsynopsis>
22	  </refsynopsisdiv>
23	
24	  <refsect1>
25	    <title>Arguments</title>
26	
27	    <variablelist>
28	      <varlistentry>
29		<term><parameter>fd</parameter></term>
30		<listitem>
31		  <para>&fd;</para>
32		</listitem>
33	      </varlistentry>
34	      <varlistentry>
35		<term><parameter>request</parameter></term>
36		<listitem>
37		  <para>VIDIOC_G_PARM, VIDIOC_S_PARM</para>
38		</listitem>
39	      </varlistentry>
40	      <varlistentry>
41		<term><parameter>argp</parameter></term>
42		<listitem>
43		  <para></para>
44		</listitem>
45	      </varlistentry>
46	    </variablelist>
47	  </refsect1>
48	
49	  <refsect1>
50	    <title>Description</title>
51	
52	    <para>The current video standard determines a nominal number of
53	frames per second. If less than this number of frames is to be
54	captured or output, applications can request frame skipping or
55	duplicating on the driver side. This is especially useful when using
56	the <function>read()</function> or <function>write()</function>, which
57	are not augmented by timestamps or sequence counters, and to avoid
58	unnecessary data copying.</para>
59	
60	    <para>Further these ioctls can be used to determine the number of
61	buffers used internally by a driver in read/write mode. For
62	implications see the section discussing the &func-read;
63	function.</para>
64	
65	    <para>To get and set the streaming parameters applications call
66	the <constant>VIDIOC_G_PARM</constant> and
67	<constant>VIDIOC_S_PARM</constant> ioctl, respectively. They take a
68	pointer to a struct <structname>v4l2_streamparm</structname> which
69	contains a union holding separate parameters for input and output
70	devices.</para>
71	
72	    <table pgwide="1" frame="none" id="v4l2-streamparm">
73	      <title>struct <structname>v4l2_streamparm</structname></title>
74	      <tgroup cols="4">
75		&cs-ustr;
76		<tbody valign="top">
77		  <row>
78		    <entry>__u32</entry>
79		    <entry><structfield>type</structfield></entry>
80		    <entry></entry>
81		    <entry>The buffer (stream) type, same as &v4l2-format;
82	<structfield>type</structfield>, set by the application. See <xref
83		    linkend="v4l2-buf-type" /></entry>
84		  </row>
85		  <row>
86		    <entry>union</entry>
87		    <entry><structfield>parm</structfield></entry>
88		    <entry></entry>
89		    <entry></entry>
90		  </row>
91		  <row>
92		    <entry></entry>
93		    <entry>&v4l2-captureparm;</entry>
94		    <entry><structfield>capture</structfield></entry>
95		    <entry>Parameters for capture devices, used when
96	<structfield>type</structfield> is
97	<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>.</entry>
98		  </row>
99		  <row>
100		    <entry></entry>
101		    <entry>&v4l2-outputparm;</entry>
102		    <entry><structfield>output</structfield></entry>
103		    <entry>Parameters for output devices, used when
104	<structfield>type</structfield> is
105	<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>.</entry>
106		  </row>
107		  <row>
108		    <entry></entry>
109		    <entry>__u8</entry>
110		    <entry><structfield>raw_data</structfield>[200]</entry>
111		    <entry>A place holder for future extensions.</entry>
112		  </row>
113		</tbody>
114	      </tgroup>
115	    </table>
116	
117	    <table pgwide="1" frame="none" id="v4l2-captureparm">
118	      <title>struct <structname>v4l2_captureparm</structname></title>
119	      <tgroup cols="3">
120		&cs-str;
121		<tbody valign="top">
122		  <row>
123		    <entry>__u32</entry>
124		    <entry><structfield>capability</structfield></entry>
125		    <entry>See <xref linkend="parm-caps" />.</entry>
126		  </row>
127		  <row>
128		    <entry>__u32</entry>
129		    <entry><structfield>capturemode</structfield></entry>
130		    <entry>Set by drivers and applications, see <xref linkend="parm-flags" />.</entry>
131		  </row>
132		  <row>
133		    <entry>&v4l2-fract;</entry>
134		    <entry><structfield>timeperframe</structfield></entry>
135		    <entry><para>This is the desired period between
136	successive frames captured by the driver, in seconds. The
137	field is intended to skip frames on the driver side, saving I/O
138	bandwidth.</para><para>Applications store here the desired frame
139	period, drivers return the actual frame period, which must be greater
140	or equal to the nominal frame period determined by the current video
141	standard (&v4l2-standard; <structfield>frameperiod</structfield>
142	field). Changing the video standard (also implicitly by switching the
143	video input) may reset this parameter to the nominal frame period. To
144	reset manually applications can just set this field to
145	zero.</para><para>Drivers support this function only when they set the
146	<constant>V4L2_CAP_TIMEPERFRAME</constant> flag in the
147	<structfield>capability</structfield> field.</para></entry>
148		  </row>
149		  <row>
150		    <entry>__u32</entry>
151		    <entry><structfield>extendedmode</structfield></entry>
152		    <entry>Custom (driver specific) streaming parameters. When
153	unused, applications and drivers must set this field to zero.
154	Applications using this field should check the driver name and
155	version, see <xref linkend="querycap" />.</entry>
156		  </row>
157		  <row>
158		    <entry>__u32</entry>
159		    <entry><structfield>readbuffers</structfield></entry>
160		    <entry>Applications set this field to the desired number
161	of buffers used internally by the driver in &func-read; mode. Drivers
162	return the actual number of buffers. When an application requests zero
163	buffers, drivers should just return the current setting rather than
164	the minimum or an error code. For details see <xref
165			linkend="rw" />.</entry>
166		  </row>
167		  <row>
168		    <entry>__u32</entry>
169		    <entry><structfield>reserved</structfield>[4]</entry>
170		    <entry>Reserved for future extensions. Drivers and
171	applications must set the array to zero.</entry>
172		  </row>
173		</tbody>
174	      </tgroup>
175	    </table>
176	
177	    <table pgwide="1" frame="none" id="v4l2-outputparm">
178	      <title>struct <structname>v4l2_outputparm</structname></title>
179	      <tgroup cols="3">
180		&cs-str;
181		<tbody valign="top">
182		  <row>
183		    <entry>__u32</entry>
184		    <entry><structfield>capability</structfield></entry>
185		    <entry>See <xref linkend="parm-caps" />.</entry>
186		  </row>
187		  <row>
188		    <entry>__u32</entry>
189		    <entry><structfield>outputmode</structfield></entry>
190		    <entry>Set by drivers and applications, see <xref
191		    linkend="parm-flags" />.</entry>
192		  </row>
193		  <row>
194		    <entry>&v4l2-fract;</entry>
195		    <entry><structfield>timeperframe</structfield></entry>
196		    <entry>This is the desired period between
197	successive frames output by the driver, in seconds.</entry>
198		  </row>
199		  <row>
200		    <entry spanname="hspan"><para>The field is intended to
201	repeat frames on the driver side in &func-write; mode (in streaming
202	mode timestamps can be used to throttle the output), saving I/O
203	bandwidth.</para><para>Applications store here the desired frame
204	period, drivers return the actual frame period, which must be greater
205	or equal to the nominal frame period determined by the current video
206	standard (&v4l2-standard; <structfield>frameperiod</structfield>
207	field). Changing the video standard (also implicitly by switching the
208	video output) may reset this parameter to the nominal frame period. To
209	reset manually applications can just set this field to
210	zero.</para><para>Drivers support this function only when they set the
211	<constant>V4L2_CAP_TIMEPERFRAME</constant> flag in the
212	<structfield>capability</structfield> field.</para></entry>
213		  </row>
214		  <row>
215		    <entry>__u32</entry>
216		    <entry><structfield>extendedmode</structfield></entry>
217		    <entry>Custom (driver specific) streaming parameters. When
218	unused, applications and drivers must set this field to zero.
219	Applications using this field should check the driver name and
220	version, see <xref linkend="querycap" />.</entry>
221		  </row>
222		  <row>
223		    <entry>__u32</entry>
224		    <entry><structfield>writebuffers</structfield></entry>
225		    <entry>Applications set this field to the desired number
226	of buffers used internally by the driver in
227	<function>write()</function> mode. Drivers return the actual number of
228	buffers. When an application requests zero buffers, drivers should
229	just return the current setting rather than the minimum or an error
230	code. For details see <xref linkend="rw" />.</entry>
231		  </row>
232		  <row>
233		    <entry>__u32</entry>
234		    <entry><structfield>reserved</structfield>[4]</entry>
235		    <entry>Reserved for future extensions. Drivers and
236	applications must set the array to zero.</entry>
237		  </row>
238		</tbody>
239	      </tgroup>
240	    </table>
241	
242	    <table pgwide="1" frame="none" id="parm-caps">
243	      <title>Streaming Parameters Capabilites</title>
244	      <tgroup cols="3">
245		&cs-def;
246		<tbody valign="top">
247		  <row>
248		    <entry><constant>V4L2_CAP_TIMEPERFRAME</constant></entry>
249		    <entry>0x1000</entry>
250		    <entry>The frame skipping/repeating controlled by the
251	<structfield>timeperframe</structfield> field is supported.</entry>
252		  </row>
253		</tbody>
254	      </tgroup>
255	    </table>
256	
257	    <table pgwide="1" frame="none" id="parm-flags">
258	      <title>Capture Parameters Flags</title>
259	      <tgroup cols="3">
260		&cs-def;
261		<tbody valign="top">
262		  <row>
263		    <entry><constant>V4L2_MODE_HIGHQUALITY</constant></entry>
264		    <entry>0x0001</entry>
265		    <entry><para>High quality imaging mode. High quality mode
266	is intended for still imaging applications. The idea is to get the
267	best possible image quality that the hardware can deliver. It is not
268	defined how the driver writer may achieve that; it will depend on the
269	hardware and the ingenuity of the driver writer. High quality mode is
270	a different mode from the the regular motion video capture modes. In
271	high quality mode:<itemizedlist>
272			  <listitem>
273			    <para>The driver may be able to capture higher
274	resolutions than for motion capture.</para>
275			  </listitem>
276			  <listitem>
277			    <para>The driver may support fewer pixel formats
278	than motion capture (eg; true color).</para>
279			  </listitem>
280			  <listitem>
281			    <para>The driver may capture and arithmetically
282	combine multiple successive fields or frames to remove color edge
283	artifacts and reduce the noise in the video data.
284	</para>
285			  </listitem>
286			  <listitem>
287			    <para>The driver may capture images in slices like
288	a scanner in order to handle larger format images than would otherwise
289	be possible. </para>
290			  </listitem>
291			  <listitem>
292			    <para>An image capture operation may be
293	significantly slower than motion capture. </para>
294			  </listitem>
295			  <listitem>
296			    <para>Moving objects in the image might have
297	excessive motion blur. </para>
298			  </listitem>
299			  <listitem>
300			    <para>Capture might only work through the
301	<function>read()</function> call.</para>
302			  </listitem>
303			</itemizedlist></para></entry>
304		  </row>
305		</tbody>
306	      </tgroup>
307	    </table>
308	
309	  </refsect1>
310	
311	  <refsect1>
312	    &return-value;
313	  </refsect1>
314	</refentry>
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.