]>
Commit | Line | Data |
---|---|---|
8e080c2e MCC |
1 | <refentry id="vidioc-queryctrl"> |
2 | <refmeta> | |
3 | <refentrytitle>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</refentrytitle> | |
4 | &manvol; | |
5 | </refmeta> | |
6 | ||
7 | <refnamediv> | |
8 | <refname>VIDIOC_QUERYCTRL</refname> | |
9 | <refname>VIDIOC_QUERYMENU</refname> | |
10 | <refpurpose>Enumerate controls and menu control items</refpurpose> | |
11 | </refnamediv> | |
12 | ||
13 | <refsynopsisdiv> | |
14 | <funcsynopsis> | |
15 | <funcprototype> | |
16 | <funcdef>int <function>ioctl</function></funcdef> | |
17 | <paramdef>int <parameter>fd</parameter></paramdef> | |
18 | <paramdef>int <parameter>request</parameter></paramdef> | |
19 | <paramdef>struct v4l2_queryctrl *<parameter>argp</parameter></paramdef> | |
20 | </funcprototype> | |
21 | </funcsynopsis> | |
22 | <funcsynopsis> | |
23 | <funcprototype> | |
24 | <funcdef>int <function>ioctl</function></funcdef> | |
25 | <paramdef>int <parameter>fd</parameter></paramdef> | |
26 | <paramdef>int <parameter>request</parameter></paramdef> | |
27 | <paramdef>struct v4l2_querymenu *<parameter>argp</parameter></paramdef> | |
28 | </funcprototype> | |
29 | </funcsynopsis> | |
30 | </refsynopsisdiv> | |
31 | ||
32 | <refsect1> | |
33 | <title>Arguments</title> | |
34 | ||
35 | <variablelist> | |
36 | <varlistentry> | |
37 | <term><parameter>fd</parameter></term> | |
38 | <listitem> | |
39 | <para>&fd;</para> | |
40 | </listitem> | |
41 | </varlistentry> | |
42 | <varlistentry> | |
43 | <term><parameter>request</parameter></term> | |
44 | <listitem> | |
45 | <para>VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</para> | |
46 | </listitem> | |
47 | </varlistentry> | |
48 | <varlistentry> | |
49 | <term><parameter>argp</parameter></term> | |
50 | <listitem> | |
51 | <para></para> | |
52 | </listitem> | |
53 | </varlistentry> | |
54 | </variablelist> | |
55 | </refsect1> | |
56 | ||
57 | <refsect1> | |
58 | <title>Description</title> | |
59 | ||
60 | <para>To query the attributes of a control applications set the | |
61 | <structfield>id</structfield> field of a &v4l2-queryctrl; and call the | |
62 | <constant>VIDIOC_QUERYCTRL</constant> ioctl with a pointer to this | |
63 | structure. The driver fills the rest of the structure or returns an | |
64 | &EINVAL; when the <structfield>id</structfield> is invalid.</para> | |
65 | ||
66 | <para>It is possible to enumerate controls by calling | |
67 | <constant>VIDIOC_QUERYCTRL</constant> with successive | |
68 | <structfield>id</structfield> values starting from | |
69 | <constant>V4L2_CID_BASE</constant> up to and exclusive | |
70 | <constant>V4L2_CID_BASE_LASTP1</constant>. Drivers may return | |
71 | <errorcode>EINVAL</errorcode> if a control in this range is not | |
72 | supported. Further applications can enumerate private controls, which | |
73 | are not defined in this specification, by starting at | |
74 | <constant>V4L2_CID_PRIVATE_BASE</constant> and incrementing | |
75 | <structfield>id</structfield> until the driver returns | |
76 | <errorcode>EINVAL</errorcode>.</para> | |
77 | ||
78 | <para>In both cases, when the driver sets the | |
79 | <constant>V4L2_CTRL_FLAG_DISABLED</constant> flag in the | |
80 | <structfield>flags</structfield> field this control is permanently | |
81 | disabled and should be ignored by the application.<footnote> | |
82 | <para><constant>V4L2_CTRL_FLAG_DISABLED</constant> was | |
83 | intended for two purposes: Drivers can skip predefined controls not | |
84 | supported by the hardware (although returning EINVAL would do as | |
85 | well), or disable predefined and private controls after hardware | |
86 | detection without the trouble of reordering control arrays and indices | |
87 | (EINVAL cannot be used to skip private controls because it would | |
88 | prematurely end the enumeration).</para></footnote></para> | |
89 | ||
90 | <para>When the application ORs <structfield>id</structfield> with | |
91 | <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> the driver returns the | |
92 | next supported control, or <errorcode>EINVAL</errorcode> if there is | |
93 | none. Drivers which do not support this flag yet always return | |
94 | <errorcode>EINVAL</errorcode>.</para> | |
95 | ||
96 | <para>Additional information is required for menu controls: the | |
97 | names of the menu items. To query them applications set the | |
98 | <structfield>id</structfield> and <structfield>index</structfield> | |
99 | fields of &v4l2-querymenu; and call the | |
100 | <constant>VIDIOC_QUERYMENU</constant> ioctl with a pointer to this | |
101 | structure. The driver fills the rest of the structure or returns an | |
102 | &EINVAL; when the <structfield>id</structfield> or | |
103 | <structfield>index</structfield> is invalid. Menu items are enumerated | |
104 | by calling <constant>VIDIOC_QUERYMENU</constant> with successive | |
105 | <structfield>index</structfield> values from &v4l2-queryctrl; | |
6756207a HV |
106 | <structfield>minimum</structfield> to |
107 | <structfield>maximum</structfield>, inclusive. Note that it is possible | |
108 | for <constant>VIDIOC_QUERYMENU</constant> to return an &EINVAL; for some | |
109 | indices between <structfield>minimum</structfield> and <structfield>maximum</structfield>. | |
110 | In that case that particular menu item is not supported by this driver. Also note that | |
111 | the <structfield>minimum</structfield> value is not necessarily 0.</para> | |
8e080c2e MCC |
112 | |
113 | <para>See also the examples in <xref linkend="control" />.</para> | |
114 | ||
115 | <table pgwide="1" frame="none" id="v4l2-queryctrl"> | |
116 | <title>struct <structname>v4l2_queryctrl</structname></title> | |
117 | <tgroup cols="3"> | |
118 | &cs-str; | |
119 | <tbody valign="top"> | |
120 | <row> | |
121 | <entry>__u32</entry> | |
122 | <entry><structfield>id</structfield></entry> | |
123 | <entry>Identifies the control, set by the application. See | |
124 | <xref linkend="control-id" /> for predefined IDs. When the ID is ORed | |
125 | with V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and returns | |
126 | the first control with a higher ID. Drivers which do not support this | |
127 | flag yet always return an &EINVAL;.</entry> | |
128 | </row> | |
129 | <row> | |
130 | <entry>&v4l2-ctrl-type;</entry> | |
131 | <entry><structfield>type</structfield></entry> | |
132 | <entry>Type of control, see <xref | |
133 | linkend="v4l2-ctrl-type" />.</entry> | |
134 | </row> | |
135 | <row> | |
136 | <entry>__u8</entry> | |
137 | <entry><structfield>name</structfield>[32]</entry> | |
138 | <entry>Name of the control, a NUL-terminated ASCII | |
139 | string. This information is intended for the user.</entry> | |
140 | </row> | |
141 | <row> | |
142 | <entry>__s32</entry> | |
143 | <entry><structfield>minimum</structfield></entry> | |
144 | <entry>Minimum value, inclusive. This field gives a lower | |
145 | bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the | |
6756207a | 146 | lowest valid index for <constant>V4L2_CTRL_TYPE_MENU</constant> controls. |
8e080c2e MCC |
147 | For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the minimum value |
148 | gives the minimum length of the string. This length <emphasis>does not include the terminating | |
149 | zero</emphasis>. It may not be valid for any other type of control, including | |
150 | <constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note that this is a | |
151 | signed value.</entry> | |
152 | </row> | |
153 | <row> | |
154 | <entry>__s32</entry> | |
155 | <entry><structfield>maximum</structfield></entry> | |
156 | <entry>Maximum value, inclusive. This field gives an upper | |
157 | bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the | |
158 | highest valid index for <constant>V4L2_CTRL_TYPE_MENU</constant> | |
159 | controls. | |
160 | For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the maximum value | |
161 | gives the maximum length of the string. This length <emphasis>does not include the terminating | |
162 | zero</emphasis>. It may not be valid for any other type of control, including | |
163 | <constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note that this is a | |
164 | signed value.</entry> | |
165 | </row> | |
166 | <row> | |
167 | <entry>__s32</entry> | |
168 | <entry><structfield>step</structfield></entry> | |
169 | <entry><para>This field gives a step size for | |
170 | <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls. For | |
171 | <constant>V4L2_CTRL_TYPE_STRING</constant> controls this field refers to | |
172 | the string length that has to be a multiple of this step size. | |
173 | It may not be valid for any other type of control, including | |
174 | <constant>V4L2_CTRL_TYPE_INTEGER64</constant> | |
175 | controls.</para><para>Generally drivers should not scale hardware | |
176 | control values. It may be necessary for example when the | |
177 | <structfield>name</structfield> or <structfield>id</structfield> imply | |
178 | a particular unit and the hardware actually accepts only multiples of | |
179 | said unit. If so, drivers must take care values are properly rounded | |
180 | when scaling, such that errors will not accumulate on repeated | |
181 | read-write cycles.</para><para>This field gives the smallest change of | |
182 | an integer control actually affecting hardware. Often the information | |
183 | is needed when the user can change controls by keyboard or GUI | |
184 | buttons, rather than a slider. When for example a hardware register | |
185 | accepts values 0-511 and the driver reports 0-65535, step should be | |
186 | 128.</para><para>Note that although signed, the step value is supposed to | |
187 | be always positive.</para></entry> | |
188 | </row> | |
189 | <row> | |
190 | <entry>__s32</entry> | |
191 | <entry><structfield>default_value</structfield></entry> | |
192 | <entry>The default value of a | |
193 | <constant>V4L2_CTRL_TYPE_INTEGER</constant>, | |
194 | <constant>_BOOLEAN</constant> or <constant>_MENU</constant> control. | |
195 | Not valid for other types of controls. Drivers reset controls only | |
196 | when the driver is loaded, not later, in particular not when the | |
197 | func-open; is called.</entry> | |
198 | </row> | |
199 | <row> | |
200 | <entry>__u32</entry> | |
201 | <entry><structfield>flags</structfield></entry> | |
202 | <entry>Control flags, see <xref | |
203 | linkend="control-flags" />.</entry> | |
204 | </row> | |
205 | <row> | |
206 | <entry>__u32</entry> | |
207 | <entry><structfield>reserved</structfield>[2]</entry> | |
208 | <entry>Reserved for future extensions. Drivers must set | |
209 | the array to zero.</entry> | |
210 | </row> | |
211 | </tbody> | |
212 | </tgroup> | |
213 | </table> | |
214 | ||
215 | <table pgwide="1" frame="none" id="v4l2-querymenu"> | |
216 | <title>struct <structname>v4l2_querymenu</structname></title> | |
217 | <tgroup cols="3"> | |
218 | &cs-str; | |
219 | <tbody valign="top"> | |
220 | <row> | |
221 | <entry>__u32</entry> | |
222 | <entry><structfield>id</structfield></entry> | |
223 | <entry>Identifies the control, set by the application | |
224 | from the respective &v4l2-queryctrl; | |
225 | <structfield>id</structfield>.</entry> | |
226 | </row> | |
227 | <row> | |
228 | <entry>__u32</entry> | |
229 | <entry><structfield>index</structfield></entry> | |
230 | <entry>Index of the menu item, starting at zero, set by | |
231 | the application.</entry> | |
232 | </row> | |
233 | <row> | |
234 | <entry>__u8</entry> | |
235 | <entry><structfield>name</structfield>[32]</entry> | |
236 | <entry>Name of the menu item, a NUL-terminated ASCII | |
237 | string. This information is intended for the user.</entry> | |
238 | </row> | |
239 | <row> | |
240 | <entry>__u32</entry> | |
241 | <entry><structfield>reserved</structfield></entry> | |
242 | <entry>Reserved for future extensions. Drivers must set | |
243 | the array to zero.</entry> | |
244 | </row> | |
245 | </tbody> | |
246 | </tgroup> | |
247 | </table> | |
248 | ||
249 | <table pgwide="1" frame="none" id="v4l2-ctrl-type"> | |
250 | <title>enum v4l2_ctrl_type</title> | |
251 | <tgroup cols="5" align="left"> | |
252 | <colspec colwidth="30*" /> | |
253 | <colspec colwidth="5*" align="center" /> | |
254 | <colspec colwidth="5*" align="center" /> | |
255 | <colspec colwidth="5*" align="center" /> | |
256 | <colspec colwidth="55*" /> | |
257 | <thead> | |
258 | <row> | |
259 | <entry>Type</entry> | |
260 | <entry><structfield>minimum</structfield></entry> | |
261 | <entry><structfield>step</structfield></entry> | |
262 | <entry><structfield>maximum</structfield></entry> | |
263 | <entry>Description</entry> | |
264 | </row> | |
265 | </thead> | |
266 | <tbody valign="top"> | |
267 | <row> | |
268 | <entry><constant>V4L2_CTRL_TYPE_INTEGER</constant></entry> | |
269 | <entry>any</entry> | |
270 | <entry>any</entry> | |
271 | <entry>any</entry> | |
272 | <entry>An integer-valued control ranging from minimum to | |
273 | maximum inclusive. The step value indicates the increment between | |
274 | values which are actually different on the hardware.</entry> | |
275 | </row> | |
276 | <row> | |
277 | <entry><constant>V4L2_CTRL_TYPE_BOOLEAN</constant></entry> | |
278 | <entry>0</entry> | |
279 | <entry>1</entry> | |
280 | <entry>1</entry> | |
281 | <entry>A boolean-valued control. Zero corresponds to | |
282 | "disabled", and one means "enabled".</entry> | |
283 | </row> | |
284 | <row> | |
285 | <entry><constant>V4L2_CTRL_TYPE_MENU</constant></entry> | |
6756207a | 286 | <entry>≥ 0</entry> |
8e080c2e MCC |
287 | <entry>1</entry> |
288 | <entry>N-1</entry> | |
289 | <entry>The control has a menu of N choices. The names of | |
290 | the menu items can be enumerated with the | |
291 | <constant>VIDIOC_QUERYMENU</constant> ioctl.</entry> | |
292 | </row> | |
293 | <row> | |
294 | <entry><constant>V4L2_CTRL_TYPE_BUTTON</constant></entry> | |
295 | <entry>0</entry> | |
296 | <entry>0</entry> | |
297 | <entry>0</entry> | |
298 | <entry>A control which performs an action when set. | |
299 | Drivers must ignore the value passed with | |
300 | <constant>VIDIOC_S_CTRL</constant> and return an &EINVAL; on a | |
301 | <constant>VIDIOC_G_CTRL</constant> attempt.</entry> | |
302 | </row> | |
303 | <row> | |
304 | <entry><constant>V4L2_CTRL_TYPE_INTEGER64</constant></entry> | |
305 | <entry>n/a</entry> | |
306 | <entry>n/a</entry> | |
307 | <entry>n/a</entry> | |
308 | <entry>A 64-bit integer valued control. Minimum, maximum | |
309 | and step size cannot be queried.</entry> | |
310 | </row> | |
311 | <row> | |
312 | <entry><constant>V4L2_CTRL_TYPE_STRING</constant></entry> | |
313 | <entry>≥ 0</entry> | |
314 | <entry>≥ 1</entry> | |
315 | <entry>≥ 0</entry> | |
316 | <entry>The minimum and maximum string lengths. The step size | |
317 | means that the string must be (minimum + N * step) characters long for | |
318 | N ≥ 0. These lengths do not include the terminating zero, so in order to | |
319 | pass a string of length 8 to &VIDIOC-S-EXT-CTRLS; you need to set the | |
320 | <structfield>size</structfield> field of &v4l2-ext-control; to 9. For &VIDIOC-G-EXT-CTRLS; you can | |
321 | set the <structfield>size</structfield> field to <structfield>maximum</structfield> + 1. | |
322 | Which character encoding is used will depend on the string control itself and | |
323 | should be part of the control documentation.</entry> | |
324 | </row> | |
325 | <row> | |
326 | <entry><constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant></entry> | |
327 | <entry>n/a</entry> | |
328 | <entry>n/a</entry> | |
329 | <entry>n/a</entry> | |
330 | <entry>This is not a control. When | |
331 | <constant>VIDIOC_QUERYCTRL</constant> is called with a control ID | |
86055302 | 332 | equal to a control class code (see <xref linkend="ctrl-class" />) + 1, the |
8e080c2e MCC |
333 | ioctl returns the name of the control class and this control type. |
334 | Older drivers which do not support this feature return an | |
335 | &EINVAL;.</entry> | |
336 | </row> | |
337 | </tbody> | |
338 | </tgroup> | |
339 | </table> | |
340 | ||
341 | <table pgwide="1" frame="none" id="control-flags"> | |
342 | <title>Control Flags</title> | |
343 | <tgroup cols="3"> | |
344 | &cs-def; | |
345 | <tbody valign="top"> | |
346 | <row> | |
347 | <entry><constant>V4L2_CTRL_FLAG_DISABLED</constant></entry> | |
348 | <entry>0x0001</entry> | |
349 | <entry>This control is permanently disabled and should be | |
350 | ignored by the application. Any attempt to change the control will | |
351 | result in an &EINVAL;.</entry> | |
352 | </row> | |
353 | <row> | |
354 | <entry><constant>V4L2_CTRL_FLAG_GRABBED</constant></entry> | |
355 | <entry>0x0002</entry> | |
356 | <entry>This control is temporarily unchangeable, for | |
357 | example because another application took over control of the | |
358 | respective resource. Such controls may be displayed specially in a | |
359 | user interface. Attempts to change the control may result in an | |
360 | &EBUSY;.</entry> | |
361 | </row> | |
362 | <row> | |
363 | <entry><constant>V4L2_CTRL_FLAG_READ_ONLY</constant></entry> | |
364 | <entry>0x0004</entry> | |
365 | <entry>This control is permanently readable only. Any | |
366 | attempt to change the control will result in an &EINVAL;.</entry> | |
367 | </row> | |
368 | <row> | |
369 | <entry><constant>V4L2_CTRL_FLAG_UPDATE</constant></entry> | |
370 | <entry>0x0008</entry> | |
371 | <entry>A hint that changing this control may affect the | |
372 | value of other controls within the same control class. Applications | |
373 | should update their user interface accordingly.</entry> | |
374 | </row> | |
375 | <row> | |
376 | <entry><constant>V4L2_CTRL_FLAG_INACTIVE</constant></entry> | |
377 | <entry>0x0010</entry> | |
378 | <entry>This control is not applicable to the current | |
379 | configuration and should be displayed accordingly in a user interface. | |
380 | For example the flag may be set on a MPEG audio level 2 bitrate | |
381 | control when MPEG audio encoding level 1 was selected with another | |
382 | control.</entry> | |
383 | </row> | |
384 | <row> | |
385 | <entry><constant>V4L2_CTRL_FLAG_SLIDER</constant></entry> | |
386 | <entry>0x0020</entry> | |
387 | <entry>A hint that this control is best represented as a | |
388 | slider-like element in a user interface.</entry> | |
389 | </row> | |
390 | <row> | |
391 | <entry><constant>V4L2_CTRL_FLAG_WRITE_ONLY</constant></entry> | |
392 | <entry>0x0040</entry> | |
393 | <entry>This control is permanently writable only. Any | |
394 | attempt to read the control will result in an &EACCES; error code. This | |
395 | flag is typically present for relative controls or action controls where | |
396 | writing a value will cause the device to carry out a given action | |
397 | (⪚ motor control) but no meaningful value can be returned.</entry> | |
398 | </row> | |
399 | </tbody> | |
400 | </tgroup> | |
401 | </table> | |
402 | </refsect1> | |
403 | ||
404 | <refsect1> | |
405 | &return-value; | |
406 | ||
407 | <variablelist> | |
408 | <varlistentry> | |
409 | <term><errorcode>EINVAL</errorcode></term> | |
410 | <listitem> | |
411 | <para>The &v4l2-queryctrl; <structfield>id</structfield> | |
6756207a HV |
412 | is invalid. The &v4l2-querymenu; <structfield>id</structfield> is |
413 | invalid or <structfield>index</structfield> is out of range (less than | |
414 | <structfield>minimum</structfield> or greater than <structfield>maximum</structfield>) | |
415 | or this particular menu item is not supported by the driver.</para> | |
8e080c2e MCC |
416 | </listitem> |
417 | </varlistentry> | |
418 | <varlistentry> | |
419 | <term><errorcode>EACCES</errorcode></term> | |
420 | <listitem> | |
421 | <para>An attempt was made to read a write-only control.</para> | |
422 | </listitem> | |
423 | </varlistentry> | |
424 | </variablelist> | |
425 | </refsect1> | |
426 | </refentry> | |
427 | ||
428 | <!-- | |
429 | Local Variables: | |
430 | mode: sgml | |
431 | sgml-parent-document: "v4l2.sgml" | |
432 | indent-tabs-mode: nil | |
433 | End: | |
434 | --> |