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