]>
Commit | Line | Data |
---|---|---|
8e080c2e MCC |
1 | <refentry id="vidioc-queryctrl"> |
2 | <refmeta> | |
715bfb3e | 3 | <refentrytitle>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU</refentrytitle> |
8e080c2e MCC |
4 | &manvol; |
5 | </refmeta> | |
6 | ||
7 | <refnamediv> | |
8 | <refname>VIDIOC_QUERYCTRL</refname> | |
715bfb3e | 9 | <refname>VIDIOC_QUERY_EXT_CTRL</refname> |
8e080c2e MCC |
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> | |
715bfb3e HV |
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> | |
8e080c2e MCC |
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> | |
715bfb3e | 54 | <para>VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU</para> |
8e080c2e MCC |
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 | |
10f8dfdc | 79 | <constant>V4L2_CID_LASTP1</constant>. Drivers may return |
8e080c2e MCC |
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 | |
715bfb3e HV |
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 | |
60f4570d HV |
104 | with type ≥ <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 | |
715bfb3e HV |
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> | |
8e080c2e MCC |
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; | |
6756207a HV |
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> | |
8e080c2e MCC |
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> | |
6016af82 | 154 | <entry>__u32</entry> |
8e080c2e MCC |
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 | |
715bfb3e HV |
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> | |
8e080c2e MCC |
171 | </row> |
172 | <row> | |
173 | <entry>__s32</entry> | |
174 | <entry><structfield>maximum</structfield></entry> | |
175 | <entry>Maximum value, inclusive. This field gives an upper | |
715bfb3e HV |
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> | |
8e080c2e MCC |
178 | </row> |
179 | <row> | |
180 | <entry>__s32</entry> | |
181 | <entry><structfield>step</structfield></entry> | |
715bfb3e HV |
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 | |
8e080c2e MCC |
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>, | |
715bfb3e HV |
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> | |
8e080c2e MCC |
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 | ||
715bfb3e HV |
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>, | |
5e6ec6b0 HV |
293 | <constant>_MENU</constant>, <constant>_INTEGER_MENU</constant>, |
294 | <constant>_U8</constant> or <constant>_U16</constant> control. | |
715bfb3e HV |
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 | ||
8e080c2e MCC |
346 | <table pgwide="1" frame="none" id="v4l2-querymenu"> |
347 | <title>struct <structname>v4l2_querymenu</structname></title> | |
6ec299f3 | 348 | <tgroup cols="4"> |
8e080c2e MCC |
349 | &cs-str; |
350 | <tbody valign="top"> | |
351 | <row> | |
352 | <entry>__u32</entry> | |
6ec299f3 | 353 | <entry></entry> |
8e080c2e MCC |
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> | |
6ec299f3 | 361 | <entry></entry> |
8e080c2e MCC |
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> | |
6ec299f3 SA |
367 | <entry>union</entry> |
368 | <entry></entry> | |
369 | <entry></entry> | |
370 | <entry></entry> | |
371 | </row> | |
372 | <row> | |
373 | <entry></entry> | |
8e080c2e MCC |
374 | <entry>__u8</entry> |
375 | <entry><structfield>name</structfield>[32]</entry> | |
376 | <entry>Name of the menu item, a NUL-terminated ASCII | |
6ec299f3 SA |
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> | |
8e080c2e MCC |
389 | </row> |
390 | <row> | |
391 | <entry>__u32</entry> | |
6ec299f3 | 392 | <entry></entry> |
8e080c2e MCC |
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 | |
60f4570d | 426 | values.</entry> |
8e080c2e MCC |
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> | |
6756207a | 438 | <entry>≥ 0</entry> |
8e080c2e MCC |
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> | |
aec67f05 | 444 | </row> |
6ec299f3 SA |
445 | <row> |
446 | <entry><constant>V4L2_CTRL_TYPE_INTEGER_MENU</constant></entry> | |
447 | <entry>≥ 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> | |
aec67f05 HV |
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> | |
8e080c2e MCC |
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> | |
715bfb3e HV |
480 | <entry>any</entry> |
481 | <entry>any</entry> | |
482 | <entry>any</entry> | |
8e080c2e | 483 | <entry>A 64-bit integer valued control. Minimum, maximum |
715bfb3e HV |
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> | |
8e080c2e MCC |
488 | </row> |
489 | <row> | |
490 | <entry><constant>V4L2_CTRL_TYPE_STRING</constant></entry> | |
491 | <entry>≥ 0</entry> | |
492 | <entry>≥ 1</entry> | |
493 | <entry>≥ 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 ≥ 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 | |
86055302 | 510 | equal to a control class code (see <xref linkend="ctrl-class" />) + 1, the |
8e080c2e MCC |
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> | |
5e6ec6b0 HV |
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 | |
60f4570d | 522 | values. |
028e2b4f | 523 | </entry> |
5e6ec6b0 HV |
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 | |
60f4570d HV |
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. | |
028e2b4f | 543 | </entry> |
5e6ec6b0 | 544 | </row> |
8e080c2e MCC |
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 | (⪚ motor control) but no meaningful value can be returned.</entry> | |
606 | </row> | |
74a45790 HV |
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 | |
acd2b672 RRD |
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> | |
74a45790 | 617 | </row> |
715bfb3e HV |
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> | |
acd2b672 RRD |
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 | |
ee5da769 | 630 | even if it remains constant. This is required when the control represents an action |
acd2b672 RRD |
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> | |
8e080c2e MCC |
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> | |
6756207a HV |
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> | |
8e080c2e MCC |
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> |