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
53frames per second. If less than this number of frames is to be
54captured or output, applications can request frame skipping or
55duplicating on the driver side. This is especially useful when using
56the <function>read()</function> or <function>write()</function>, which
57are not augmented by timestamps or sequence counters, and to avoid
58unnecessary data copying.</para>
59
60    <para>Further these ioctls can be used to determine the number of
61buffers used internally by a driver in read/write mode. For
62implications see the section discussing the &func-read;
63function.</para>
64
65    <para>To get and set the streaming parameters applications call
66the <constant>VIDIOC_G_PARM</constant> and
67<constant>VIDIOC_S_PARM</constant> ioctl, respectively. They take a
68pointer to a struct <structname>v4l2_streamparm</structname> which
69contains a union holding separate parameters for input and output
70devices.</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
136successive frames captured by the driver, in seconds. The
137field is intended to skip frames on the driver side, saving I/O
138bandwidth.</para><para>Applications store here the desired frame
139period, drivers return the actual frame period, which must be greater
140or equal to the nominal frame period determined by the current video
141standard (&v4l2-standard; <structfield>frameperiod</structfield>
142field). Changing the video standard (also implicitly by switching the
143video input) may reset this parameter to the nominal frame period. To
144reset manually applications can just set this field to
145zero.</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
153unused, applications and drivers must set this field to zero.
154Applications using this field should check the driver name and
155version, 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
161of buffers used internally by the driver in &func-read; mode. Drivers
162return the actual number of buffers. When an application requests zero
163buffers, drivers should just return the current setting rather than
164the 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
171applications 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
197successive frames output by the driver, in seconds.</entry>
198	  </row>
199	  <row>
200	    <entry spanname="hspan"><para>The field is intended to
201repeat frames on the driver side in &func-write; mode (in streaming
202mode timestamps can be used to throttle the output), saving I/O
203bandwidth.</para><para>Applications store here the desired frame
204period, drivers return the actual frame period, which must be greater
205or equal to the nominal frame period determined by the current video
206standard (&v4l2-standard; <structfield>frameperiod</structfield>
207field). Changing the video standard (also implicitly by switching the
208video output) may reset this parameter to the nominal frame period. To
209reset manually applications can just set this field to
210zero.</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
218unused, applications and drivers must set this field to zero.
219Applications using this field should check the driver name and
220version, 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
226of buffers used internally by the driver in
227<function>write()</function> mode. Drivers return the actual number of
228buffers. When an application requests zero buffers, drivers should
229just return the current setting rather than the minimum or an error
230code. 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
236applications 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
266is intended for still imaging applications. The idea is to get the
267best possible image quality that the hardware can deliver. It is not
268defined how the driver writer may achieve that; it will depend on the
269hardware and the ingenuity of the driver writer. High quality mode is
270a different mode from the the regular motion video capture modes. In
271high quality mode:<itemizedlist>
272		  <listitem>
273		    <para>The driver may be able to capture higher
274resolutions than for motion capture.</para>
275		  </listitem>
276		  <listitem>
277		    <para>The driver may support fewer pixel formats
278than motion capture (eg; true color).</para>
279		  </listitem>
280		  <listitem>
281		    <para>The driver may capture and arithmetically
282combine multiple successive fields or frames to remove color edge
283artifacts and reduce the noise in the video data.
284</para>
285		  </listitem>
286		  <listitem>
287		    <para>The driver may capture images in slices like
288a scanner in order to handle larger format images than would otherwise
289be possible. </para>
290		  </listitem>
291		  <listitem>
292		    <para>An image capture operation may be
293significantly slower than motion capture. </para>
294		  </listitem>
295		  <listitem>
296		    <para>Moving objects in the image might have
297excessive 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>
315