1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
6 *******************************************************************
7 ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU
8 *******************************************************************
13 VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items
18 ``int ioctl(int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp)``
20 .. c:macro:: VIDIOC_QUERY_EXT_CTRL
22 ``int ioctl(int fd, VIDIOC_QUERY_EXT_CTRL, struct v4l2_query_ext_ctrl *argp)``
24 .. c:macro:: VIDIOC_QUERYMENU
26 ``int ioctl(int fd, VIDIOC_QUERYMENU, struct v4l2_querymenu *argp)``
32 File descriptor returned by :c:func:`open()`.
35 Pointer to struct :c:type:`v4l2_queryctrl`, :c:type:`v4l2_query_ext_ctrl`
36 or :c:type:`v4l2_querymenu` (depending on the ioctl).
41 To query the attributes of a control applications set the ``id`` field
42 of a struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` and call the
43 ``VIDIOC_QUERYCTRL`` ioctl with a pointer to this structure. The driver
44 fills the rest of the structure or returns an ``EINVAL`` error code when the
47 It is possible to enumerate controls by calling ``VIDIOC_QUERYCTRL``
48 with successive ``id`` values starting from ``V4L2_CID_BASE`` up to and
49 exclusive ``V4L2_CID_LASTP1``. Drivers may return ``EINVAL`` if a control in
50 this range is not supported. Further applications can enumerate private
51 controls, which are not defined in this specification, by starting at
52 ``V4L2_CID_PRIVATE_BASE`` and incrementing ``id`` until the driver
55 In both cases, when the driver sets the ``V4L2_CTRL_FLAG_DISABLED`` flag
56 in the ``flags`` field this control is permanently disabled and should
57 be ignored by the application. [#f1]_
59 When the application ORs ``id`` with ``V4L2_CTRL_FLAG_NEXT_CTRL`` the
60 driver returns the next supported non-compound control, or ``EINVAL`` if
61 there is none. In addition, the ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` flag
62 can be specified to enumerate all compound controls (i.e. controls with
63 type ≥ ``V4L2_CTRL_COMPOUND_TYPES`` and/or array control, in other words
64 controls that contain more than one value). Specify both
65 ``V4L2_CTRL_FLAG_NEXT_CTRL`` and ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` in
66 order to enumerate all controls, compound or not. Drivers which do not
67 support these flags yet always return ``EINVAL``.
69 The ``VIDIOC_QUERY_EXT_CTRL`` ioctl was introduced in order to better
70 support controls that can use compound types, and to expose additional
71 control information that cannot be returned in struct
72 :ref:`v4l2_queryctrl <v4l2-queryctrl>` since that structure is full.
74 ``VIDIOC_QUERY_EXT_CTRL`` is used in the same way as
75 ``VIDIOC_QUERYCTRL``, except that the ``reserved`` array must be zeroed
78 Additional information is required for menu controls: the names of the
79 menu items. To query them applications set the ``id`` and ``index``
80 fields of struct :ref:`v4l2_querymenu <v4l2-querymenu>` and call the
81 ``VIDIOC_QUERYMENU`` ioctl with a pointer to this structure. The driver
82 fills the rest of the structure or returns an ``EINVAL`` error code when the
83 ``id`` or ``index`` is invalid. Menu items are enumerated by calling
84 ``VIDIOC_QUERYMENU`` with successive ``index`` values from struct
85 :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``minimum`` to ``maximum``,
90 It is possible for ``VIDIOC_QUERYMENU`` to return
91 an ``EINVAL`` error code for some indices between ``minimum`` and
92 ``maximum``. In that case that particular menu item is not supported by
93 this driver. Also note that the ``minimum`` value is not necessarily 0.
95 See also the examples in :ref:`control`.
97 .. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.7cm}|
101 .. cssclass:: longtable
103 .. flat-table:: struct v4l2_queryctrl
110 - Identifies the control, set by the application. See
111 :ref:`control-id` for predefined IDs. When the ID is ORed with
112 V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and
113 returns the first control with a higher ID. Drivers which do not
114 support this flag yet always return an ``EINVAL`` error code.
117 - Type of control, see :c:type:`v4l2_ctrl_type`.
120 - Name of the control, a NUL-terminated ASCII string. This
121 information is intended for the user.
124 - Minimum value, inclusive. This field gives a lower bound for the
125 control. See enum :c:type:`v4l2_ctrl_type` how
126 the minimum value is to be used for each possible control type.
127 Note that this a signed 32-bit value.
130 - Maximum value, inclusive. This field gives an upper bound for the
131 control. See enum :c:type:`v4l2_ctrl_type` how
132 the maximum value is to be used for each possible control type.
133 Note that this a signed 32-bit value.
136 - This field gives a step size for the control. See enum
137 :c:type:`v4l2_ctrl_type` how the step value is
138 to be used for each possible control type. Note that this an
139 unsigned 32-bit value.
141 Generally drivers should not scale hardware control values. It may
142 be necessary for example when the ``name`` or ``id`` imply a
143 particular unit and the hardware actually accepts only multiples
144 of said unit. If so, drivers must take care values are properly
145 rounded when scaling, such that errors will not accumulate on
146 repeated read-write cycles.
148 This field gives the smallest change of an integer control
149 actually affecting hardware. Often the information is needed when
150 the user can change controls by keyboard or GUI buttons, rather
151 than a slider. When for example a hardware register accepts values
152 0-511 and the driver reports 0-65535, step should be 128.
154 Note that although signed, the step value is supposed to be always
158 - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_BOOLEAN``,
159 ``_BITMASK``, ``_MENU`` or ``_INTEGER_MENU`` control. Not valid
160 for other types of controls.
164 Drivers reset controls to their default value only when
165 the driver is first loaded, never afterwards.
168 - Control flags, see :ref:`control-flags`.
171 - Reserved for future extensions. Drivers must set the array to
175 .. tabularcolumns:: |p{1.2cm}|p{5.0cm}|p{11.3cm}|
177 .. _v4l2-query-ext-ctrl:
179 .. cssclass:: longtable
181 .. flat-table:: struct v4l2_query_ext_ctrl
188 - Identifies the control, set by the application. See
189 :ref:`control-id` for predefined IDs. When the ID is ORed with
190 ``V4L2_CTRL_FLAG_NEXT_CTRL`` the driver clears the flag and
191 returns the first non-compound control with a higher ID. When the
192 ID is ORed with ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` the driver clears
193 the flag and returns the first compound control with a higher ID.
194 Set both to get the first control (compound or not) with a higher
198 - Type of control, see :c:type:`v4l2_ctrl_type`.
201 - Name of the control, a NUL-terminated ASCII string. This
202 information is intended for the user.
205 - Minimum value, inclusive. This field gives a lower bound for the
206 control. See enum :c:type:`v4l2_ctrl_type` how
207 the minimum value is to be used for each possible control type.
208 Note that this a signed 64-bit value.
211 - Maximum value, inclusive. This field gives an upper bound for the
212 control. See enum :c:type:`v4l2_ctrl_type` how
213 the maximum value is to be used for each possible control type.
214 Note that this a signed 64-bit value.
217 - This field gives a step size for the control. See enum
218 :c:type:`v4l2_ctrl_type` how the step value is
219 to be used for each possible control type. Note that this an
220 unsigned 64-bit value.
222 Generally drivers should not scale hardware control values. It may
223 be necessary for example when the ``name`` or ``id`` imply a
224 particular unit and the hardware actually accepts only multiples
225 of said unit. If so, drivers must take care values are properly
226 rounded when scaling, such that errors will not accumulate on
227 repeated read-write cycles.
229 This field gives the smallest change of an integer control
230 actually affecting hardware. Often the information is needed when
231 the user can change controls by keyboard or GUI buttons, rather
232 than a slider. When for example a hardware register accepts values
233 0-511 and the driver reports 0-65535, step should be 128.
236 - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_INTEGER64``,
237 ``_BOOLEAN``, ``_BITMASK``, ``_MENU``, ``_INTEGER_MENU``, ``_U8``
238 or ``_U16`` control. Not valid for other types of controls.
242 Drivers reset controls to their default value only when
243 the driver is first loaded, never afterwards.
246 - Control flags, see :ref:`control-flags`.
249 - The size in bytes of a single element of the array. Given a char
250 pointer ``p`` to a 3-dimensional array you can find the position
251 of cell ``(z, y, x)`` as follows:
252 ``p + ((z * dims[1] + y) * dims[0] + x) * elem_size``.
253 ``elem_size`` is always valid, also when the control isn't an
254 array. For string controls ``elem_size`` is equal to
258 - The number of elements in the N-dimensional array. If this control
259 is not an array, then ``elems`` is 1. The ``elems`` field can
263 - The number of dimension in the N-dimensional array. If this
264 control is not an array, then this field is 0.
266 - ``dims[V4L2_CTRL_MAX_DIMS]``
267 - The size of each dimension. The first ``nr_of_dims`` elements of
268 this array must be non-zero, all remaining elements must be zero.
271 - Reserved for future extensions. Applications and drivers must set
275 .. tabularcolumns:: |p{1.2cm}|p{1.0cm}|p{1.7cm}|p{13.0cm}|
279 .. flat-table:: struct v4l2_querymenu
286 - Identifies the control, set by the application from the respective
287 struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id``.
290 - Index of the menu item, starting at zero, set by the application.
295 - Name of the menu item, a NUL-terminated ASCII string. This
296 information is intended for the user. This field is valid for
297 ``V4L2_CTRL_TYPE_MENU`` type controls.
300 - Value of the integer menu item. This field is valid for
301 ``V4L2_CTRL_TYPE_INTEGER_MENU`` type controls.
306 - Reserved for future extensions. Drivers must set the array to
310 .. tabularcolumns:: |p{5.8cm}|p{1.4cm}|p{1.0cm}|p{1.4cm}|p{6.9cm}|
312 .. c:type:: v4l2_ctrl_type
314 .. cssclass:: longtable
316 .. flat-table:: enum v4l2_ctrl_type
326 * - ``V4L2_CTRL_TYPE_INTEGER``
330 - An integer-valued control ranging from minimum to maximum
331 inclusive. The step value indicates the increment between values.
332 * - ``V4L2_CTRL_TYPE_BOOLEAN``
336 - A boolean-valued control. Zero corresponds to "disabled", and one
338 * - ``V4L2_CTRL_TYPE_MENU``
342 - The control has a menu of N choices. The names of the menu items
343 can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl.
344 * - ``V4L2_CTRL_TYPE_INTEGER_MENU``
348 - The control has a menu of N choices. The values of the menu items
349 can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. This is
350 similar to ``V4L2_CTRL_TYPE_MENU`` except that instead of strings,
351 the menu items are signed 64-bit integers.
352 * - ``V4L2_CTRL_TYPE_BITMASK``
356 - A bitmask field. The maximum value is the set of bits that can be
357 used, all other bits are to be 0. The maximum value is interpreted
358 as a __u32, allowing the use of bit 31 in the bitmask.
359 * - ``V4L2_CTRL_TYPE_BUTTON``
363 - A control which performs an action when set. Drivers must ignore
364 the value passed with ``VIDIOC_S_CTRL`` and return an ``EACCES`` error
365 code on a ``VIDIOC_G_CTRL`` attempt.
366 * - ``V4L2_CTRL_TYPE_INTEGER64``
370 - A 64-bit integer valued control. Minimum, maximum and step size
371 cannot be queried using ``VIDIOC_QUERYCTRL``. Only
372 ``VIDIOC_QUERY_EXT_CTRL`` can retrieve the 64-bit min/max/step
373 values, they should be interpreted as n/a when using
374 ``VIDIOC_QUERYCTRL``.
375 * - ``V4L2_CTRL_TYPE_STRING``
379 - The minimum and maximum string lengths. The step size means that
380 the string must be (minimum + N * step) characters long for N ≥ 0.
381 These lengths do not include the terminating zero, so in order to
382 pass a string of length 8 to
383 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you need to
384 set the ``size`` field of struct
385 :c:type:`v4l2_ext_control` to 9. For
386 :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you can set
387 the ``size`` field to ``maximum`` + 1. Which character encoding is
388 used will depend on the string control itself and should be part
389 of the control documentation.
390 * - ``V4L2_CTRL_TYPE_CTRL_CLASS``
394 - This is not a control. When ``VIDIOC_QUERYCTRL`` is called with a
395 control ID equal to a control class code (see :ref:`ctrl-class`)
396 + 1, the ioctl returns the name of the control class and this
397 control type. Older drivers which do not support this feature
398 return an ``EINVAL`` error code.
399 * - ``V4L2_CTRL_TYPE_U8``
403 - An unsigned 8-bit valued control ranging from minimum to maximum
404 inclusive. The step value indicates the increment between values.
405 * - ``V4L2_CTRL_TYPE_U16``
409 - An unsigned 16-bit valued control ranging from minimum to maximum
410 inclusive. The step value indicates the increment between values.
411 * - ``V4L2_CTRL_TYPE_U32``
415 - An unsigned 32-bit valued control ranging from minimum to maximum
416 inclusive. The step value indicates the increment between values.
417 * - ``V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS``
421 - A struct :c:type:`v4l2_ctrl_mpeg2_slice_params`, containing MPEG-2
422 slice parameters for stateless video decoders.
423 * - ``V4L2_CTRL_TYPE_MPEG2_QUANTIZATION``
427 - A struct :c:type:`v4l2_ctrl_mpeg2_quantization`, containing MPEG-2
428 quantization matrices for stateless video decoders.
429 * - ``V4L2_CTRL_TYPE_AREA``
433 - A struct :c:type:`v4l2_area`, containing the width and the height
434 of a rectangular area. Units depend on the use case.
435 * - ``V4L2_CTRL_TYPE_H264_SPS``
439 - A struct :c:type:`v4l2_ctrl_h264_sps`, containing H264
440 sequence parameters for stateless video decoders.
441 * - ``V4L2_CTRL_TYPE_H264_PPS``
445 - A struct :c:type:`v4l2_ctrl_h264_pps`, containing H264
446 picture parameters for stateless video decoders.
447 * - ``V4L2_CTRL_TYPE_H264_SCALING_MATRIX``
451 - A struct :c:type:`v4l2_ctrl_h264_scaling_matrix`, containing H264
452 scaling matrices for stateless video decoders.
453 * - ``V4L2_CTRL_TYPE_H264_SLICE_PARAMS``
457 - A struct :c:type:`v4l2_ctrl_h264_slice_params`, containing H264
458 slice parameters for stateless video decoders.
459 * - ``V4L2_CTRL_TYPE_H264_DECODE_PARAMS``
463 - A struct :c:type:`v4l2_ctrl_h264_decode_params`, containing H264
464 decode parameters for stateless video decoders.
465 * - ``V4L2_CTRL_TYPE_HEVC_SPS``
469 - A struct :c:type:`v4l2_ctrl_hevc_sps`, containing HEVC Sequence
470 Parameter Set for stateless video decoders.
471 * - ``V4L2_CTRL_TYPE_HEVC_PPS``
475 - A struct :c:type:`v4l2_ctrl_hevc_pps`, containing HEVC Picture
476 Parameter Set for stateless video decoders.
477 * - ``V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS``
481 - A struct :c:type:`v4l2_ctrl_hevc_slice_params`, containing HEVC
482 slice parameters for stateless video decoders.
484 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
488 .. cssclass:: longtable
490 .. flat-table:: Control Flags
495 * - ``V4L2_CTRL_FLAG_DISABLED``
497 - This control is permanently disabled and should be ignored by the
498 application. Any attempt to change the control will result in an
499 ``EINVAL`` error code.
500 * - ``V4L2_CTRL_FLAG_GRABBED``
502 - This control is temporarily unchangeable, for example because
503 another application took over control of the respective resource.
504 Such controls may be displayed specially in a user interface.
505 Attempts to change the control may result in an ``EBUSY`` error code.
506 * - ``V4L2_CTRL_FLAG_READ_ONLY``
508 - This control is permanently readable only. Any attempt to change
509 the control will result in an ``EINVAL`` error code.
510 * - ``V4L2_CTRL_FLAG_UPDATE``
512 - A hint that changing this control may affect the value of other
513 controls within the same control class. Applications should update
514 their user interface accordingly.
515 * - ``V4L2_CTRL_FLAG_INACTIVE``
517 - This control is not applicable to the current configuration and
518 should be displayed accordingly in a user interface. For example
519 the flag may be set on a MPEG audio level 2 bitrate control when
520 MPEG audio encoding level 1 was selected with another control.
521 * - ``V4L2_CTRL_FLAG_SLIDER``
523 - A hint that this control is best represented as a slider-like
524 element in a user interface.
525 * - ``V4L2_CTRL_FLAG_WRITE_ONLY``
527 - This control is permanently writable only. Any attempt to read the
528 control will result in an ``EACCES`` error code error code. This flag
529 is typically present for relative controls or action controls
530 where writing a value will cause the device to carry out a given
531 action (e. g. motor control) but no meaningful value can be
533 * - ``V4L2_CTRL_FLAG_VOLATILE``
535 - This control is volatile, which means that the value of the
536 control changes continuously. A typical example would be the
537 current gain value if the device is in auto-gain mode. In such a
538 case the hardware calculates the gain value based on the lighting
539 conditions which can change over time.
543 Setting a new value for a volatile control will be ignored
545 :ref:`V4L2_CTRL_FLAG_EXECUTE_ON_WRITE <FLAG_EXECUTE_ON_WRITE>`
547 Setting a new value for a volatile control will *never* trigger a
548 :ref:`V4L2_EVENT_CTRL_CH_VALUE <ctrl-changes-flags>` event.
549 * - ``V4L2_CTRL_FLAG_HAS_PAYLOAD``
551 - This control has a pointer type, so its value has to be accessed
552 using one of the pointer fields of struct
553 :c:type:`v4l2_ext_control`. This flag is set
554 for controls that are an array, string, or have a compound type.
555 In all cases you have to set a pointer to memory containing the
556 payload of the control.
557 * .. _FLAG_EXECUTE_ON_WRITE:
559 - ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
561 - The value provided to the control will be propagated to the driver
562 even if it remains constant. This is required when the control
563 represents an action on the hardware. For example: clearing an
564 error flag or triggering the flash. All the controls of the type
565 ``V4L2_CTRL_TYPE_BUTTON`` have this flag set.
566 * .. _FLAG_MODIFY_LAYOUT:
568 - ``V4L2_CTRL_FLAG_MODIFY_LAYOUT``
570 - Changing this control value may modify the layout of the
571 buffer (for video devices) or the media bus format (for sub-devices).
573 A typical example would be the ``V4L2_CID_ROTATE`` control.
575 Note that typically controls with this flag will also set the
576 ``V4L2_CTRL_FLAG_GRABBED`` flag when buffers are allocated or
577 streaming is in progress since most drivers do not support changing
578 the format in that case.
583 On success 0 is returned, on error -1 and the ``errno`` variable is set
584 appropriately. The generic error codes are described at the
585 :ref:`Generic Error Codes <gen-errors>` chapter.
588 The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id`` is
589 invalid. The struct :ref:`v4l2_querymenu <v4l2-querymenu>` ``id``
590 is invalid or ``index`` is out of range (less than ``minimum`` or
591 greater than ``maximum``) or this particular menu item is not
592 supported by the driver.
595 An attempt was made to read a write-only control.
598 ``V4L2_CTRL_FLAG_DISABLED`` was intended for two purposes: Drivers
599 can skip predefined controls not supported by the hardware (although
600 returning ``EINVAL`` would do as well), or disable predefined and private
601 controls after hardware detection without the trouble of reordering
602 control arrays and indices (``EINVAL`` cannot be used to skip private
603 controls because it would prematurely end the enumeration).