About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / media / v4l / vidioc-queryctrl.xml




Custom Search

Based on kernel version 4.7.2. Page generated on 2016-08-22 22:45 EST.

1	<refentry id="vidioc-queryctrl">
2	  <refmeta>
3	    <refentrytitle>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU</refentrytitle>
4	    &manvol;
5	  </refmeta>
6	
7	  <refnamediv>
8	    <refname>VIDIOC_QUERYCTRL</refname>
9	    <refname>VIDIOC_QUERY_EXT_CTRL</refname>
10	    <refname>VIDIOC_QUERYMENU</refname>
11	    <refpurpose>Enumerate controls and menu control items</refpurpose>
12	  </refnamediv>
13	
14	  <refsynopsisdiv>
15	    <funcsynopsis>
16	      <funcprototype>
17		<funcdef>int <function>ioctl</function></funcdef>
18		<paramdef>int <parameter>fd</parameter></paramdef>
19		<paramdef>int <parameter>request</parameter></paramdef>
20		<paramdef>struct v4l2_queryctrl *<parameter>argp</parameter></paramdef>
21	      </funcprototype>
22	    </funcsynopsis>
23	    <funcsynopsis>
24	      <funcprototype>
25		<funcdef>int <function>ioctl</function></funcdef>
26		<paramdef>int <parameter>fd</parameter></paramdef>
27		<paramdef>int <parameter>request</parameter></paramdef>
28		<paramdef>struct v4l2_query_ext_ctrl *<parameter>argp</parameter></paramdef>
29	      </funcprototype>
30	    </funcsynopsis>
31	    <funcsynopsis>
32	      <funcprototype>
33		<funcdef>int <function>ioctl</function></funcdef>
34		<paramdef>int <parameter>fd</parameter></paramdef>
35		<paramdef>int <parameter>request</parameter></paramdef>
36		<paramdef>struct v4l2_querymenu *<parameter>argp</parameter></paramdef>
37	      </funcprototype>
38	    </funcsynopsis>
39	  </refsynopsisdiv>
40	
41	  <refsect1>
42	    <title>Arguments</title>
43	
44	    <variablelist>
45	      <varlistentry>
46		<term><parameter>fd</parameter></term>
47		<listitem>
48		  <para>&fd;</para>
49		</listitem>
50	      </varlistentry>
51	      <varlistentry>
52		<term><parameter>request</parameter></term>
53		<listitem>
54		  <para>VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU</para>
55		</listitem>
56	      </varlistentry>
57	      <varlistentry>
58		<term><parameter>argp</parameter></term>
59		<listitem>
60		  <para></para>
61		</listitem>
62	      </varlistentry>
63	    </variablelist>
64	  </refsect1>
65	
66	  <refsect1>
67	    <title>Description</title>
68	
69	    <para>To query the attributes of a control applications set the
70	<structfield>id</structfield> field of a &v4l2-queryctrl; and call the
71	<constant>VIDIOC_QUERYCTRL</constant> ioctl with a pointer to this
72	structure. The driver fills the rest of the structure or returns an
73	&EINVAL; when the <structfield>id</structfield> is invalid.</para>
74	
75	    <para>It is possible to enumerate controls by calling
76	<constant>VIDIOC_QUERYCTRL</constant> with successive
77	<structfield>id</structfield> values starting from
78	<constant>V4L2_CID_BASE</constant> up to and exclusive
79	<constant>V4L2_CID_LASTP1</constant>. Drivers may return
80	<errorcode>EINVAL</errorcode> if a control in this range is not
81	supported. Further applications can enumerate private controls, which
82	are not defined in this specification, by starting at
83	<constant>V4L2_CID_PRIVATE_BASE</constant> and incrementing
84	<structfield>id</structfield> until the driver returns
85	<errorcode>EINVAL</errorcode>.</para>
86	
87	    <para>In both cases, when the driver sets the
88	<constant>V4L2_CTRL_FLAG_DISABLED</constant> flag in the
89	<structfield>flags</structfield> field this control is permanently
90	disabled and should be ignored by the application.<footnote>
91		<para><constant>V4L2_CTRL_FLAG_DISABLED</constant> was
92	intended for two purposes: Drivers can skip predefined controls not
93	supported by the hardware (although returning EINVAL would do as
94	well), or disable predefined and private controls after hardware
95	detection without the trouble of reordering control arrays and indices
96	(EINVAL cannot be used to skip private controls because it would
97	prematurely end the enumeration).</para></footnote></para>
98	
99	    <para>When the application ORs <structfield>id</structfield> with
100	<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> the driver returns the
101	next supported non-compound control, or <errorcode>EINVAL</errorcode>
102	if there is none. In addition, the <constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant>
103	flag can be specified to enumerate all compound controls (i.e. controls
104	with type &ge; <constant>V4L2_CTRL_COMPOUND_TYPES</constant> and/or array
105	control, in other words controls that contain more than one value).
106	Specify both <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> and
107	<constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant> in order to enumerate
108	all controls, compound or not. Drivers which do not support these flags yet
109	always return <errorcode>EINVAL</errorcode>.</para>
110	
111	    <para>The <constant>VIDIOC_QUERY_EXT_CTRL</constant> ioctl was
112	introduced in order to better support controls that can use compound
113	types, and to expose additional control information that cannot be
114	returned in &v4l2-queryctrl; since that structure is full.</para>
115	
116	    <para><constant>VIDIOC_QUERY_EXT_CTRL</constant> is used in the
117	same way as <constant>VIDIOC_QUERYCTRL</constant>, except that the
118	<structfield>reserved</structfield> array must be zeroed as well.</para>
119	
120	    <para>Additional information is required for menu controls: the
121	names of the menu items. To query them applications set the
122	<structfield>id</structfield> and <structfield>index</structfield>
123	fields of &v4l2-querymenu; and call the
124	<constant>VIDIOC_QUERYMENU</constant> ioctl with a pointer to this
125	structure. The driver fills the rest of the structure or returns an
126	&EINVAL; when the <structfield>id</structfield> or
127	<structfield>index</structfield> is invalid. Menu items are enumerated
128	by calling <constant>VIDIOC_QUERYMENU</constant> with successive
129	<structfield>index</structfield> values from &v4l2-queryctrl;
130	<structfield>minimum</structfield> to
131	<structfield>maximum</structfield>, inclusive. Note that it is possible
132	for <constant>VIDIOC_QUERYMENU</constant> to return an &EINVAL; for some
133	indices between <structfield>minimum</structfield> and <structfield>maximum</structfield>.
134	In that case that particular menu item is not supported by this driver. Also note that
135	the <structfield>minimum</structfield> value is not necessarily 0.</para>
136	
137	    <para>See also the examples in <xref linkend="control" />.</para>
138	
139	    <table pgwide="1" frame="none" id="v4l2-queryctrl">
140	      <title>struct <structname>v4l2_queryctrl</structname></title>
141	      <tgroup cols="3">
142		&cs-str;
143		<tbody valign="top">
144		  <row>
145		    <entry>__u32</entry>
146		    <entry><structfield>id</structfield></entry>
147		    <entry>Identifies the control, set by the application. See
148	<xref linkend="control-id" /> for predefined IDs. When the ID is ORed
149	with V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and returns
150	the first control with a higher ID. Drivers which do not support this
151	flag yet always return an &EINVAL;.</entry>
152		  </row>
153		  <row>
154		    <entry>__u32</entry>
155		    <entry><structfield>type</structfield></entry>
156		    <entry>Type of control, see <xref
157			linkend="v4l2-ctrl-type" />.</entry>
158		  </row>
159		  <row>
160		    <entry>__u8</entry>
161		    <entry><structfield>name</structfield>[32]</entry>
162		    <entry>Name of the control, a NUL-terminated ASCII
163	string. This information is intended for the user.</entry>
164		  </row>
165		  <row>
166		    <entry>__s32</entry>
167		    <entry><structfield>minimum</structfield></entry>
168		    <entry>Minimum value, inclusive. This field gives a lower
169	bound for the control. See &v4l2-ctrl-type; how the minimum value is to
170	be used for each possible control type. Note that this a signed 32-bit value.</entry>
171		  </row>
172		  <row>
173		    <entry>__s32</entry>
174		    <entry><structfield>maximum</structfield></entry>
175		    <entry>Maximum value, inclusive. This field gives an upper
176	bound for the control. See &v4l2-ctrl-type; how the maximum value is to
177	be used for each possible control type. Note that this a signed 32-bit value.</entry>
178		  </row>
179		  <row>
180		    <entry>__s32</entry>
181		    <entry><structfield>step</structfield></entry>
182		    <entry><para>This field gives a step size for the control.
183	See &v4l2-ctrl-type; how the step value is to be used for each possible
184	control type. Note that this an unsigned 32-bit value.
185	</para><para>Generally drivers should not scale hardware
186	control values. It may be necessary for example when the
187	<structfield>name</structfield> or <structfield>id</structfield> imply
188	a particular unit and the hardware actually accepts only multiples of
189	said unit. If so, drivers must take care values are properly rounded
190	when scaling, such that errors will not accumulate on repeated
191	read-write cycles.</para><para>This field gives the smallest change of
192	an integer control actually affecting hardware. Often the information
193	is needed when the user can change controls by keyboard or GUI
194	buttons, rather than a slider. When for example a hardware register
195	accepts values 0-511 and the driver reports 0-65535, step should be
196	128.</para><para>Note that although signed, the step value is supposed to
197	be always positive.</para></entry>
198		  </row>
199		  <row>
200		    <entry>__s32</entry>
201		    <entry><structfield>default_value</structfield></entry>
202		    <entry>The default value of a
203	<constant>V4L2_CTRL_TYPE_INTEGER</constant>,
204	<constant>_BOOLEAN</constant>, <constant>_BITMASK</constant>,
205	<constant>_MENU</constant> or <constant>_INTEGER_MENU</constant> control.
206	Not valid for other types of controls.
207	Note that drivers reset controls to their default value only when the
208	driver is first loaded, never afterwards.</entry>
209		  </row>
210		  <row>
211		    <entry>__u32</entry>
212		    <entry><structfield>flags</structfield></entry>
213		    <entry>Control flags, see <xref
214			linkend="control-flags" />.</entry>
215		  </row>
216		  <row>
217		    <entry>__u32</entry>
218		    <entry><structfield>reserved</structfield>[2]</entry>
219		    <entry>Reserved for future extensions. Drivers must set
220	the array to zero.</entry>
221		  </row>
222		</tbody>
223	      </tgroup>
224	    </table>
225	
226	    <table pgwide="1" frame="none" id="v4l2-query-ext-ctrl">
227	      <title>struct <structname>v4l2_query_ext_ctrl</structname></title>
228	      <tgroup cols="3">
229		&cs-str;
230		<tbody valign="top">
231		  <row>
232		    <entry>__u32</entry>
233		    <entry><structfield>id</structfield></entry>
234		    <entry>Identifies the control, set by the application. See
235	<xref linkend="control-id" /> for predefined IDs. When the ID is ORed
236	with <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> the driver clears the
237	flag and returns the first non-compound control with a higher ID. When the
238	ID is ORed with <constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant> the driver
239	clears the flag and returns the first compound control with a higher ID.
240	Set both to get the first control (compound or not) with a higher ID.</entry>
241		  </row>
242		  <row>
243		    <entry>__u32</entry>
244		    <entry><structfield>type</structfield></entry>
245		    <entry>Type of control, see <xref
246			linkend="v4l2-ctrl-type" />.</entry>
247		  </row>
248		  <row>
249		    <entry>char</entry>
250		    <entry><structfield>name</structfield>[32]</entry>
251		    <entry>Name of the control, a NUL-terminated ASCII
252	string. This information is intended for the user.</entry>
253		  </row>
254		  <row>
255		    <entry>__s64</entry>
256		    <entry><structfield>minimum</structfield></entry>
257		    <entry>Minimum value, inclusive. This field gives a lower
258	bound for the control. See &v4l2-ctrl-type; how the minimum value is to
259	be used for each possible control type. Note that this a signed 64-bit value.</entry>
260		  </row>
261		  <row>
262		    <entry>__s64</entry>
263		    <entry><structfield>maximum</structfield></entry>
264		    <entry>Maximum value, inclusive. This field gives an upper
265	bound for the control. See &v4l2-ctrl-type; how the maximum value is to
266	be used for each possible control type. Note that this a signed 64-bit value.</entry>
267		  </row>
268		  <row>
269		    <entry>__u64</entry>
270		    <entry><structfield>step</structfield></entry>
271		    <entry><para>This field gives a step size for the control.
272	See &v4l2-ctrl-type; how the step value is to be used for each possible
273	control type. Note that this an unsigned 64-bit value.
274	</para><para>Generally drivers should not scale hardware
275	control values. It may be necessary for example when the
276	<structfield>name</structfield> or <structfield>id</structfield> imply
277	a particular unit and the hardware actually accepts only multiples of
278	said unit. If so, drivers must take care values are properly rounded
279	when scaling, such that errors will not accumulate on repeated
280	read-write cycles.</para><para>This field gives the smallest change of
281	an integer control actually affecting hardware. Often the information
282	is needed when the user can change controls by keyboard or GUI
283	buttons, rather than a slider. When for example a hardware register
284	accepts values 0-511 and the driver reports 0-65535, step should be
285	128.</para></entry>
286		  </row>
287		  <row>
288		    <entry>__s64</entry>
289		    <entry><structfield>default_value</structfield></entry>
290		    <entry>The default value of a
291	<constant>V4L2_CTRL_TYPE_INTEGER</constant>, <constant>_INTEGER64</constant>,
292	<constant>_BOOLEAN</constant>, <constant>_BITMASK</constant>,
293	<constant>_MENU</constant>, <constant>_INTEGER_MENU</constant>,
294	<constant>_U8</constant> or <constant>_U16</constant> control.
295	Not valid for other types of controls.
296	Note that drivers reset controls to their default value only when the
297	driver is first loaded, never afterwards.
298	</entry>
299		  </row>
300		  <row>
301		    <entry>__u32</entry>
302		    <entry><structfield>flags</structfield></entry>
303		    <entry>Control flags, see <xref
304			linkend="control-flags" />.</entry>
305		  </row>
306		  <row>
307		    <entry>__u32</entry>
308		    <entry><structfield>elem_size</structfield></entry>
309		    <entry>The size in bytes of a single element of the array.
310	Given a char pointer <constant>p</constant> to a 3-dimensional array you can find the
311	position of cell <constant>(z, y, x)</constant> as follows:
312	<constant>p + ((z * dims[1] + y) * dims[0] + x) * elem_size</constant>. <structfield>elem_size</structfield>
313	is always valid, also when the control isn't an array. For string controls
314	<structfield>elem_size</structfield> is equal to <structfield>maximum + 1</structfield>.
315	</entry>
316		  </row>
317		  <row>
318		    <entry>__u32</entry>
319		    <entry><structfield>elems</structfield></entry>
320		    <entry>The number of elements in the N-dimensional array. If this control
321	is not an array, then <structfield>elems</structfield> is 1. The <structfield>elems</structfield>
322	field can never be 0.</entry>
323		  </row>
324		  <row>
325		    <entry>__u32</entry>
326		    <entry><structfield>nr_of_dims</structfield></entry>
327		    <entry>The number of dimension in the N-dimensional array. If this control
328	is not an array, then this field is 0.</entry>
329		  </row>
330		  <row>
331		    <entry>__u32</entry>
332		    <entry><structfield>dims[V4L2_CTRL_MAX_DIMS]</structfield></entry>
333		    <entry>The size of each dimension. The first <structfield>nr_of_dims</structfield>
334	elements of this array must be non-zero, all remaining elements must be zero.</entry>
335		  </row>
336		  <row>
337		    <entry>__u32</entry>
338		    <entry><structfield>reserved</structfield>[32]</entry>
339		    <entry>Reserved for future extensions. Applications and drivers
340	must set the array to zero.</entry>
341		  </row>
342		</tbody>
343	      </tgroup>
344	    </table>
345	
346	    <table pgwide="1" frame="none" id="v4l2-querymenu">
347	      <title>struct <structname>v4l2_querymenu</structname></title>
348	      <tgroup cols="4">
349		&cs-str;
350		<tbody valign="top">
351		  <row>
352		    <entry>__u32</entry>
353		    <entry></entry>
354		    <entry><structfield>id</structfield></entry>
355		    <entry>Identifies the control, set by the application
356	from the respective &v4l2-queryctrl;
357	<structfield>id</structfield>.</entry>
358		  </row>
359		  <row>
360		    <entry>__u32</entry>
361		    <entry></entry>
362		    <entry><structfield>index</structfield></entry>
363		    <entry>Index of the menu item, starting at zero, set by
364		    the application.</entry>
365		  </row>
366		  <row>
367		    <entry>union</entry>
368		    <entry></entry>
369		    <entry></entry>
370		    <entry></entry>
371		  </row>
372		  <row>
373		    <entry></entry>
374		    <entry>__u8</entry>
375		    <entry><structfield>name</structfield>[32]</entry>
376		    <entry>Name of the menu item, a NUL-terminated ASCII
377	string. This information is intended for the user. This field is valid
378	for <constant>V4L2_CTRL_FLAG_MENU</constant> type controls.</entry>
379		  </row>
380		  <row>
381		    <entry></entry>
382		    <entry>__s64</entry>
383		    <entry><structfield>value</structfield></entry>
384		    <entry>
385	              Value of the integer menu item. This field is valid for
386	              <constant>V4L2_CTRL_FLAG_INTEGER_MENU</constant> type
387	              controls.
388	            </entry>
389		  </row>
390		  <row>
391		    <entry>__u32</entry>
392		    <entry></entry>
393		    <entry><structfield>reserved</structfield></entry>
394		    <entry>Reserved for future extensions. Drivers must set
395	the array to zero.</entry>
396		  </row>
397		</tbody>
398	      </tgroup>
399	    </table>
400	
401	    <table pgwide="1" frame="none" id="v4l2-ctrl-type">
402	      <title>enum v4l2_ctrl_type</title>
403	      <tgroup cols="5" align="left">
404		<colspec colwidth="30*" />
405		<colspec colwidth="5*" align="center" />
406		<colspec colwidth="5*" align="center" />
407		<colspec colwidth="5*" align="center" />
408		<colspec colwidth="55*" />
409		<thead>
410		  <row>
411		    <entry>Type</entry>
412		    <entry><structfield>minimum</structfield></entry>
413		    <entry><structfield>step</structfield></entry>
414		    <entry><structfield>maximum</structfield></entry>
415		    <entry>Description</entry>
416		  </row>
417		</thead>
418		<tbody valign="top">
419		  <row>
420		    <entry><constant>V4L2_CTRL_TYPE_INTEGER</constant></entry>
421		    <entry>any</entry>
422		    <entry>any</entry>
423		    <entry>any</entry>
424		    <entry>An integer-valued control ranging from minimum to
425	maximum inclusive. The step value indicates the increment between
426	values.</entry>
427		  </row>
428		  <row>
429		    <entry><constant>V4L2_CTRL_TYPE_BOOLEAN</constant></entry>
430		    <entry>0</entry>
431		    <entry>1</entry>
432		    <entry>1</entry>
433		    <entry>A boolean-valued control. Zero corresponds to
434	"disabled", and one means "enabled".</entry>
435		  </row>
436		  <row>
437		    <entry><constant>V4L2_CTRL_TYPE_MENU</constant></entry>
438		    <entry>&ge; 0</entry>
439		    <entry>1</entry>
440		    <entry>N-1</entry>
441		    <entry>The control has a menu of N choices. The names of
442	the menu items can be enumerated with the
443	<constant>VIDIOC_QUERYMENU</constant> ioctl.</entry>
444		  </row>
445		  <row>
446		    <entry><constant>V4L2_CTRL_TYPE_INTEGER_MENU</constant></entry>
447		    <entry>&ge; 0</entry>
448		    <entry>1</entry>
449		    <entry>N-1</entry>
450		    <entry>
451	              The control has a menu of N choices. The values of the
452	              menu items can be enumerated with the
453	              <constant>VIDIOC_QUERYMENU</constant> ioctl. This is
454	              similar to <constant>V4L2_CTRL_TYPE_MENU</constant>
455	              except that instead of strings, the menu items are
456	              signed 64-bit integers.
457	            </entry>
458		  </row>
459		  <row>
460		    <entry><constant>V4L2_CTRL_TYPE_BITMASK</constant></entry>
461		    <entry>0</entry>
462		    <entry>n/a</entry>
463		    <entry>any</entry>
464		    <entry>A bitmask field. The maximum value is the set of bits that can
465	be used, all other bits are to be 0. The maximum value is interpreted as a __u32,
466	allowing the use of bit 31 in the bitmask.</entry>
467		  </row>
468		  <row>
469		    <entry><constant>V4L2_CTRL_TYPE_BUTTON</constant></entry>
470		    <entry>0</entry>
471		    <entry>0</entry>
472		    <entry>0</entry>
473		    <entry>A control which performs an action when set.
474	Drivers must ignore the value passed with
475	<constant>VIDIOC_S_CTRL</constant> and return an &EINVAL; on a
476	<constant>VIDIOC_G_CTRL</constant> attempt.</entry>
477		  </row>
478		  <row>
479		    <entry><constant>V4L2_CTRL_TYPE_INTEGER64</constant></entry>
480		    <entry>any</entry>
481		    <entry>any</entry>
482		    <entry>any</entry>
483		    <entry>A 64-bit integer valued control. Minimum, maximum
484	and step size cannot be queried using <constant>VIDIOC_QUERYCTRL</constant>.
485	Only <constant>VIDIOC_QUERY_EXT_CTRL</constant> can retrieve the 64-bit
486	min/max/step values, they should be interpreted as n/a when using
487	<constant>VIDIOC_QUERYCTRL</constant>.</entry>
488		  </row>
489		  <row>
490		    <entry><constant>V4L2_CTRL_TYPE_STRING</constant></entry>
491		    <entry>&ge; 0</entry>
492		    <entry>&ge; 1</entry>
493		    <entry>&ge; 0</entry>
494		    <entry>The minimum and maximum string lengths. The step size
495	means that the string must be (minimum + N * step) characters long for
496	N &ge; 0. These lengths do not include the terminating zero, so in order to
497	pass a string of length 8 to &VIDIOC-S-EXT-CTRLS; you need to set the
498	<structfield>size</structfield> field of &v4l2-ext-control; to 9. For &VIDIOC-G-EXT-CTRLS; you can
499	set the <structfield>size</structfield> field to <structfield>maximum</structfield> + 1.
500	Which character encoding is used will depend on the string control itself and
501	should be part of the control documentation.</entry>
502		  </row>
503		  <row>
504		    <entry><constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant></entry>
505		    <entry>n/a</entry>
506		    <entry>n/a</entry>
507		    <entry>n/a</entry>
508		    <entry>This is not a control. When
509	<constant>VIDIOC_QUERYCTRL</constant> is called with a control ID
510	equal to a control class code (see <xref linkend="ctrl-class" />) + 1, the
511	ioctl returns the name of the control class and this control type.
512	Older drivers which do not support this feature return an
513	&EINVAL;.</entry>
514		  </row>
515		  <row>
516		    <entry><constant>V4L2_CTRL_TYPE_U8</constant></entry>
517		    <entry>any</entry>
518		    <entry>any</entry>
519		    <entry>any</entry>
520		    <entry>An unsigned 8-bit valued control ranging from minimum to
521	maximum inclusive. The step value indicates the increment between
522	values.
523	</entry>
524		  </row>
525		  <row>
526		    <entry><constant>V4L2_CTRL_TYPE_U16</constant></entry>
527		    <entry>any</entry>
528		    <entry>any</entry>
529		    <entry>any</entry>
530		    <entry>An unsigned 16-bit valued control ranging from minimum to
531	maximum inclusive. The step value indicates the increment between
532	values.
533	</entry>
534		  </row>
535		  <row>
536		    <entry><constant>V4L2_CTRL_TYPE_U32</constant></entry>
537		    <entry>any</entry>
538		    <entry>any</entry>
539		    <entry>any</entry>
540		    <entry>An unsigned 32-bit valued control ranging from minimum to
541	maximum inclusive. The step value indicates the increment between
542	values.
543	</entry>
544		  </row>
545		</tbody>
546	      </tgroup>
547	    </table>
548	
549	    <table pgwide="1" frame="none" id="control-flags">
550	      <title>Control Flags</title>
551	      <tgroup cols="3">
552		&cs-def;
553		<tbody valign="top">
554		  <row>
555		    <entry><constant>V4L2_CTRL_FLAG_DISABLED</constant></entry>
556		    <entry>0x0001</entry>
557		    <entry>This control is permanently disabled and should be
558	ignored by the application. Any attempt to change the control will
559	result in an &EINVAL;.</entry>
560		  </row>
561		  <row>
562		    <entry><constant>V4L2_CTRL_FLAG_GRABBED</constant></entry>
563		    <entry>0x0002</entry>
564		    <entry>This control is temporarily unchangeable, for
565	example because another application took over control of the
566	respective resource. Such controls may be displayed specially in a
567	user interface. Attempts to change the control may result in an
568	&EBUSY;.</entry>
569		  </row>
570		  <row>
571		    <entry><constant>V4L2_CTRL_FLAG_READ_ONLY</constant></entry>
572		    <entry>0x0004</entry>
573		    <entry>This control is permanently readable only. Any
574	attempt to change the control will result in an &EINVAL;.</entry>
575		  </row>
576		  <row>
577		    <entry><constant>V4L2_CTRL_FLAG_UPDATE</constant></entry>
578		    <entry>0x0008</entry>
579		    <entry>A hint that changing this control may affect the
580	value of other controls within the same control class. Applications
581	should update their user interface accordingly.</entry>
582		  </row>
583		  <row>
584		    <entry><constant>V4L2_CTRL_FLAG_INACTIVE</constant></entry>
585		    <entry>0x0010</entry>
586		    <entry>This control is not applicable to the current
587	configuration and should be displayed accordingly in a user interface.
588	For example the flag may be set on a MPEG audio level 2 bitrate
589	control when MPEG audio encoding level 1 was selected with another
590	control.</entry>
591		  </row>
592		  <row>
593		    <entry><constant>V4L2_CTRL_FLAG_SLIDER</constant></entry>
594		    <entry>0x0020</entry>
595		    <entry>A hint that this control is best represented as a
596	slider-like element in a user interface.</entry>
597		  </row>
598		  <row>
599		    <entry><constant>V4L2_CTRL_FLAG_WRITE_ONLY</constant></entry>
600		    <entry>0x0040</entry>
601		    <entry>This control is permanently writable only. Any
602	attempt to read the control will result in an &EACCES; error code. This
603	flag is typically present for relative controls or action controls where
604	writing a value will cause the device to carry out a given action
605	(&eg; motor control) but no meaningful value can be returned.</entry>
606		  </row>
607		  <row>
608		    <entry><constant>V4L2_CTRL_FLAG_VOLATILE</constant></entry>
609		    <entry>0x0080</entry>
610		    <entry>This control is volatile, which means that the value of the control
611	changes continuously. A typical example would be the current gain value if the device
612	is in auto-gain mode. In such a case the hardware calculates the gain value based on
613	the lighting conditions which can change over time. Note that setting a new value for
614	a volatile control will have no effect and no <constant>V4L2_EVENT_CTRL_CH_VALUE</constant>
615	will be sent, unless the <constant>V4L2_CTRL_FLAG_EXECUTE_ON_WRITE</constant> flag
616	(see below) is also set. Otherwise the new value will just be ignored.</entry>
617		  </row>
618		  <row>
619		    <entry><constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant></entry>
620		    <entry>0x0100</entry>
621		    <entry>This control has a pointer type, so its value has to be accessed
622	using one of the pointer fields of &v4l2-ext-control;. This flag is set for controls
623	that are an array, string, or have a compound type. In all cases you have to set a
624	pointer to memory containing the payload of the control.</entry>
625		  </row>
626		  <row>
627		    <entry><constant>V4L2_CTRL_FLAG_EXECUTE_ON_WRITE</constant></entry>
628		    <entry>0x0200</entry>
629		    <entry>The value provided to the control will be propagated to the driver
630	even if it remains constant. This is required when the control represents an action
631	on the hardware. For example: clearing an error flag or triggering the flash. All the
632	controls of the type <constant>V4L2_CTRL_TYPE_BUTTON</constant> have this flag set.</entry>
633		  </row>
634		</tbody>
635	      </tgroup>
636	    </table>
637	  </refsect1>
638	
639	  <refsect1>
640	    &return-value;
641	
642	    <variablelist>
643	      <varlistentry>
644		<term><errorcode>EINVAL</errorcode></term>
645		<listitem>
646		  <para>The &v4l2-queryctrl; <structfield>id</structfield>
647	is invalid. The &v4l2-querymenu; <structfield>id</structfield> is
648	invalid or <structfield>index</structfield> is out of range (less than
649	<structfield>minimum</structfield> or greater than <structfield>maximum</structfield>)
650	or this particular menu item is not supported by the driver.</para>
651		</listitem>
652	      </varlistentry>
653	      <varlistentry>
654		<term><errorcode>EACCES</errorcode></term>
655		<listitem>
656		  <para>An attempt was made to read a write-only control.</para>
657		</listitem>
658	      </varlistentry>
659	    </variablelist>
660	  </refsect1>
661	</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.