1 .. -*- coding: utf-8; mode: rst -*-
5 *******************************************************************
6 ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU
7 *******************************************************************
12 VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items
18 .. c:function:: int ioctl( int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp )
19 :name: VIDIOC_QUERYCTRL
21 .. c:function:: int ioctl( int fd, VIDIOC_QUERY_EXT_CTRL, struct v4l2_query_ext_ctrl *argp )
22 :name: VIDIOC_QUERY_EXT_CTRL
24 .. c:function:: int ioctl( int fd, VIDIOC_QUERYMENU, struct v4l2_querymenu *argp )
25 :name: VIDIOC_QUERYMENU
32 File descriptor returned by :ref:`open() <func-open>`.
35 Pointer to struct :c:type:`v4l2_queryctl`, :c:type:`v4l2_query_ext_ctrl`
36 or :c:type`v4l2_querymenu` (depending on the ioctl).
42 To query the attributes of a control applications set the ``id`` field
43 of a struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` and call the
44 ``VIDIOC_QUERYCTRL`` ioctl with a pointer to this structure. The driver
45 fills the rest of the structure or returns an ``EINVAL`` error code when the
48 It is possible to enumerate controls by calling ``VIDIOC_QUERYCTRL``
49 with successive ``id`` values starting from ``V4L2_CID_BASE`` up to and
50 exclusive ``V4L2_CID_LASTP1``. Drivers may return ``EINVAL`` if a control in
51 this range is not supported. Further applications can enumerate private
52 controls, which are not defined in this specification, by starting at
53 ``V4L2_CID_PRIVATE_BASE`` and incrementing ``id`` until the driver
56 In both cases, when the driver sets the ``V4L2_CTRL_FLAG_DISABLED`` flag
57 in the ``flags`` field this control is permanently disabled and should
58 be ignored by the application. [#f1]_
60 When the application ORs ``id`` with ``V4L2_CTRL_FLAG_NEXT_CTRL`` the
61 driver returns the next supported non-compound control, or ``EINVAL`` if
62 there is none. In addition, the ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` flag
63 can be specified to enumerate all compound controls (i.e. controls with
64 type ≥ ``V4L2_CTRL_COMPOUND_TYPES`` and/or array control, in other words
65 controls that contain more than one value). Specify both
66 ``V4L2_CTRL_FLAG_NEXT_CTRL`` and ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` in
67 order to enumerate all controls, compound or not. Drivers which do not
68 support these flags yet always return ``EINVAL``.
70 The ``VIDIOC_QUERY_EXT_CTRL`` ioctl was introduced in order to better
71 support controls that can use compound types, and to expose additional
72 control information that cannot be returned in struct
73 :ref:`v4l2_queryctrl <v4l2-queryctrl>` since that structure is full.
75 ``VIDIOC_QUERY_EXT_CTRL`` is used in the same way as
76 ``VIDIOC_QUERYCTRL``, except that the ``reserved`` array must be zeroed
79 Additional information is required for menu controls: the names of the
80 menu items. To query them applications set the ``id`` and ``index``
81 fields of struct :ref:`v4l2_querymenu <v4l2-querymenu>` and call the
82 ``VIDIOC_QUERYMENU`` ioctl with a pointer to this structure. The driver
83 fills the rest of the structure or returns an ``EINVAL`` error code when the
84 ``id`` or ``index`` is invalid. Menu items are enumerated by calling
85 ``VIDIOC_QUERYMENU`` with successive ``index`` values from struct
86 :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``minimum`` to ``maximum``,
91 It is possible for ``VIDIOC_QUERYMENU`` to return
92 an ``EINVAL`` error code for some indices between ``minimum`` and
93 ``maximum``. In that case that particular menu item is not supported by
94 this driver. Also note that the ``minimum`` value is not necessarily 0.
96 See also the examples in :ref:`control`.
99 .. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.7cm}|
103 .. cssclass:: longtable
105 .. flat-table:: struct v4l2_queryctrl
112 - Identifies the control, set by the application. See
113 :ref:`control-id` for predefined IDs. When the ID is ORed with
114 V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and
115 returns the first control with a higher ID. Drivers which do not
116 support this flag yet always return an ``EINVAL`` error code.
119 - Type of control, see :c:type:`v4l2_ctrl_type`.
122 - Name of the control, a NUL-terminated ASCII string. This
123 information is intended for the user.
126 - Minimum value, inclusive. This field gives a lower bound for the
127 control. See enum :c:type:`v4l2_ctrl_type` how
128 the minimum value is to be used for each possible control type.
129 Note that this a signed 32-bit value.
132 - Maximum value, inclusive. This field gives an upper bound for the
133 control. See enum :c:type:`v4l2_ctrl_type` how
134 the maximum value is to be used for each possible control type.
135 Note that this a signed 32-bit value.
138 - This field gives a step size for the control. See enum
139 :c:type:`v4l2_ctrl_type` how the step value is
140 to be used for each possible control type. Note that this an
141 unsigned 32-bit value.
143 Generally drivers should not scale hardware control values. It may
144 be necessary for example when the ``name`` or ``id`` imply a
145 particular unit and the hardware actually accepts only multiples
146 of said unit. If so, drivers must take care values are properly
147 rounded when scaling, such that errors will not accumulate on
148 repeated read-write cycles.
150 This field gives the smallest change of an integer control
151 actually affecting hardware. Often the information is needed when
152 the user can change controls by keyboard or GUI buttons, rather
153 than a slider. When for example a hardware register accepts values
154 0-511 and the driver reports 0-65535, step should be 128.
156 Note that although signed, the step value is supposed to be always
160 - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_BOOLEAN``,
161 ``_BITMASK``, ``_MENU`` or ``_INTEGER_MENU`` control. Not valid
162 for other types of controls.
166 Drivers reset controls to their default value only when
167 the driver is first loaded, never afterwards.
170 - Control flags, see :ref:`control-flags`.
173 - Reserved for future extensions. Drivers must set the array to
178 .. tabularcolumns:: |p{1.2cm}|p{5.0cm}|p{11.3cm}|
180 .. _v4l2-query-ext-ctrl:
182 .. cssclass:: longtable
184 .. flat-table:: struct v4l2_query_ext_ctrl
191 - Identifies the control, set by the application. See
192 :ref:`control-id` for predefined IDs. When the ID is ORed with
193 ``V4L2_CTRL_FLAG_NEXT_CTRL`` the driver clears the flag and
194 returns the first non-compound control with a higher ID. When the
195 ID is ORed with ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` the driver clears
196 the flag and returns the first compound control with a higher ID.
197 Set both to get the first control (compound or not) with a higher
201 - Type of control, see :c:type:`v4l2_ctrl_type`.
204 - Name of the control, a NUL-terminated ASCII string. This
205 information is intended for the user.
208 - Minimum value, inclusive. This field gives a lower bound for the
209 control. See enum :c:type:`v4l2_ctrl_type` how
210 the minimum value is to be used for each possible control type.
211 Note that this a signed 64-bit value.
214 - Maximum value, inclusive. This field gives an upper bound for the
215 control. See enum :c:type:`v4l2_ctrl_type` how
216 the maximum value is to be used for each possible control type.
217 Note that this a signed 64-bit value.
220 - This field gives a step size for the control. See enum
221 :c:type:`v4l2_ctrl_type` how the step value is
222 to be used for each possible control type. Note that this an
223 unsigned 64-bit value.
225 Generally drivers should not scale hardware control values. It may
226 be necessary for example when the ``name`` or ``id`` imply a
227 particular unit and the hardware actually accepts only multiples
228 of said unit. If so, drivers must take care values are properly
229 rounded when scaling, such that errors will not accumulate on
230 repeated read-write cycles.
232 This field gives the smallest change of an integer control
233 actually affecting hardware. Often the information is needed when
234 the user can change controls by keyboard or GUI buttons, rather
235 than a slider. When for example a hardware register accepts values
236 0-511 and the driver reports 0-65535, step should be 128.
239 - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_INTEGER64``,
240 ``_BOOLEAN``, ``_BITMASK``, ``_MENU``, ``_INTEGER_MENU``, ``_U8``
241 or ``_U16`` control. Not valid for other types of controls.
245 Drivers reset controls to their default value only when
246 the driver is first loaded, never afterwards.
249 - Control flags, see :ref:`control-flags`.
252 - The size in bytes of a single element of the array. Given a char
253 pointer ``p`` to a 3-dimensional array you can find the position
254 of cell ``(z, y, x)`` as follows:
255 ``p + ((z * dims[1] + y) * dims[0] + x) * elem_size``.
256 ``elem_size`` is always valid, also when the control isn't an
257 array. For string controls ``elem_size`` is equal to
261 - The number of elements in the N-dimensional array. If this control
262 is not an array, then ``elems`` is 1. The ``elems`` field can
266 - The number of dimension in the N-dimensional array. If this
267 control is not an array, then this field is 0.
269 - ``dims[V4L2_CTRL_MAX_DIMS]``
270 - The size of each dimension. The first ``nr_of_dims`` elements of
271 this array must be non-zero, all remaining elements must be zero.
274 - Reserved for future extensions. Applications and drivers must set
279 .. tabularcolumns:: |p{1.2cm}|p{1.0cm}|p{1.7cm}|p{13.0cm}|
283 .. flat-table:: struct v4l2_querymenu
291 - Identifies the control, set by the application from the respective
292 struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id``.
296 - Index of the menu item, starting at zero, set by the application.
304 - Name of the menu item, a NUL-terminated ASCII string. This
305 information is intended for the user. This field is valid for
306 ``V4L2_CTRL_TYPE_MENU`` type controls.
310 - Value of the integer menu item. This field is valid for
311 ``V4L2_CTRL_TYPE_INTEGER_MENU`` type controls.
315 - Reserved for future extensions. Drivers must set the array to
320 .. tabularcolumns:: |p{5.8cm}|p{1.4cm}|p{1.0cm}|p{1.4cm}|p{6.9cm}|
322 .. c:type:: v4l2_ctrl_type
324 .. cssclass:: longtable
326 .. flat-table:: enum v4l2_ctrl_type
336 * - ``V4L2_CTRL_TYPE_INTEGER``
340 - An integer-valued control ranging from minimum to maximum
341 inclusive. The step value indicates the increment between values.
342 * - ``V4L2_CTRL_TYPE_BOOLEAN``
346 - A boolean-valued control. Zero corresponds to "disabled", and one
348 * - ``V4L2_CTRL_TYPE_MENU``
352 - The control has a menu of N choices. The names of the menu items
353 can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl.
354 * - ``V4L2_CTRL_TYPE_INTEGER_MENU``
358 - The control has a menu of N choices. The values of the menu items
359 can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. This is
360 similar to ``V4L2_CTRL_TYPE_MENU`` except that instead of strings,
361 the menu items are signed 64-bit integers.
362 * - ``V4L2_CTRL_TYPE_BITMASK``
366 - A bitmask field. The maximum value is the set of bits that can be
367 used, all other bits are to be 0. The maximum value is interpreted
368 as a __u32, allowing the use of bit 31 in the bitmask.
369 * - ``V4L2_CTRL_TYPE_BUTTON``
373 - A control which performs an action when set. Drivers must ignore
374 the value passed with ``VIDIOC_S_CTRL`` and return an ``EINVAL`` error
375 code on a ``VIDIOC_G_CTRL`` attempt.
376 * - ``V4L2_CTRL_TYPE_INTEGER64``
380 - A 64-bit integer valued control. Minimum, maximum and step size
381 cannot be queried using ``VIDIOC_QUERYCTRL``. Only
382 ``VIDIOC_QUERY_EXT_CTRL`` can retrieve the 64-bit min/max/step
383 values, they should be interpreted as n/a when using
384 ``VIDIOC_QUERYCTRL``.
385 * - ``V4L2_CTRL_TYPE_STRING``
389 - The minimum and maximum string lengths. The step size means that
390 the string must be (minimum + N * step) characters long for N ≥ 0.
391 These lengths do not include the terminating zero, so in order to
392 pass a string of length 8 to
393 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you need to
394 set the ``size`` field of struct
395 :c:type:`v4l2_ext_control` to 9. For
396 :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you can set
397 the ``size`` field to ``maximum`` + 1. Which character encoding is
398 used will depend on the string control itself and should be part
399 of the control documentation.
400 * - ``V4L2_CTRL_TYPE_CTRL_CLASS``
404 - This is not a control. When ``VIDIOC_QUERYCTRL`` is called with a
405 control ID equal to a control class code (see :ref:`ctrl-class`)
406 + 1, the ioctl returns the name of the control class and this
407 control type. Older drivers which do not support this feature
408 return an ``EINVAL`` error code.
409 * - ``V4L2_CTRL_TYPE_U8``
413 - An unsigned 8-bit valued control ranging from minimum to maximum
414 inclusive. The step value indicates the increment between values.
415 * - ``V4L2_CTRL_TYPE_U16``
419 - An unsigned 16-bit valued control ranging from minimum to maximum
420 inclusive. The step value indicates the increment between values.
421 * - ``V4L2_CTRL_TYPE_U32``
425 - An unsigned 32-bit valued control ranging from minimum to maximum
426 inclusive. The step value indicates the increment between values.
427 * - ``V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS``
431 - A struct :c:type:`v4l2_ctrl_mpeg2_slice_params`, containing MPEG-2
432 slice parameters for stateless video decoders.
433 * - ``V4L2_CTRL_TYPE_MPEG2_QUANTIZATION``
437 - A struct :c:type:`v4l2_ctrl_mpeg2_quantization`, containing MPEG-2
438 quantization matrices for stateless video decoders.
440 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
444 .. cssclass:: longtable
446 .. flat-table:: Control Flags
451 * - ``V4L2_CTRL_FLAG_DISABLED``
453 - This control is permanently disabled and should be ignored by the
454 application. Any attempt to change the control will result in an
455 ``EINVAL`` error code.
456 * - ``V4L2_CTRL_FLAG_GRABBED``
458 - This control is temporarily unchangeable, for example because
459 another application took over control of the respective resource.
460 Such controls may be displayed specially in a user interface.
461 Attempts to change the control may result in an ``EBUSY`` error code.
462 * - ``V4L2_CTRL_FLAG_READ_ONLY``
464 - This control is permanently readable only. Any attempt to change
465 the control will result in an ``EINVAL`` error code.
466 * - ``V4L2_CTRL_FLAG_UPDATE``
468 - A hint that changing this control may affect the value of other
469 controls within the same control class. Applications should update
470 their user interface accordingly.
471 * - ``V4L2_CTRL_FLAG_INACTIVE``
473 - This control is not applicable to the current configuration and
474 should be displayed accordingly in a user interface. For example
475 the flag may be set on a MPEG audio level 2 bitrate control when
476 MPEG audio encoding level 1 was selected with another control.
477 * - ``V4L2_CTRL_FLAG_SLIDER``
479 - A hint that this control is best represented as a slider-like
480 element in a user interface.
481 * - ``V4L2_CTRL_FLAG_WRITE_ONLY``
483 - This control is permanently writable only. Any attempt to read the
484 control will result in an ``EACCES`` error code error code. This flag
485 is typically present for relative controls or action controls
486 where writing a value will cause the device to carry out a given
487 action (e. g. motor control) but no meaningful value can be
489 * - ``V4L2_CTRL_FLAG_VOLATILE``
491 - This control is volatile, which means that the value of the
492 control changes continuously. A typical example would be the
493 current gain value if the device is in auto-gain mode. In such a
494 case the hardware calculates the gain value based on the lighting
495 conditions which can change over time.
499 Setting a new value for a volatile control will be ignored
501 :ref:`V4L2_CTRL_FLAG_EXECUTE_ON_WRITE <FLAG_EXECUTE_ON_WRITE>`
503 Setting a new value for a volatile control will *never* trigger a
504 :ref:`V4L2_EVENT_CTRL_CH_VALUE <ctrl-changes-flags>` event.
505 * - ``V4L2_CTRL_FLAG_HAS_PAYLOAD``
507 - This control has a pointer type, so its value has to be accessed
508 using one of the pointer fields of struct
509 :c:type:`v4l2_ext_control`. This flag is set
510 for controls that are an array, string, or have a compound type.
511 In all cases you have to set a pointer to memory containing the
512 payload of the control.
513 * .. _FLAG_EXECUTE_ON_WRITE:
515 - ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
517 - The value provided to the control will be propagated to the driver
518 even if it remains constant. This is required when the control
519 represents an action on the hardware. For example: clearing an
520 error flag or triggering the flash. All the controls of the type
521 ``V4L2_CTRL_TYPE_BUTTON`` have this flag set.
522 * .. _FLAG_MODIFY_LAYOUT:
524 - ``V4L2_CTRL_FLAG_MODIFY_LAYOUT``
526 - Changing this control value may modify the layout of the
527 buffer (for video devices) or the media bus format (for sub-devices).
529 A typical example would be the ``V4L2_CID_ROTATE`` control.
531 Note that typically controls with this flag will also set the
532 ``V4L2_CTRL_FLAG_GRABBED`` flag when buffers are allocated or
533 streaming is in progress since most drivers do not support changing
534 the format in that case.
540 On success 0 is returned, on error -1 and the ``errno`` variable is set
541 appropriately. The generic error codes are described at the
542 :ref:`Generic Error Codes <gen-errors>` chapter.
545 The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id`` is
546 invalid. The struct :ref:`v4l2_querymenu <v4l2-querymenu>` ``id``
547 is invalid or ``index`` is out of range (less than ``minimum`` or
548 greater than ``maximum``) or this particular menu item is not
549 supported by the driver.
552 An attempt was made to read a write-only control.
555 ``V4L2_CTRL_FLAG_DISABLED`` was intended for two purposes: Drivers
556 can skip predefined controls not supported by the hardware (although
557 returning ``EINVAL`` would do as well), or disable predefined and private
558 controls after hardware detection without the trouble of reordering
559 control arrays and indices (``EINVAL`` cannot be used to skip private
560 controls because it would prematurely end the enumeration).