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 .. cpp:function:: int ioctl( int fd, int request, struct v4l2_queryctrl *argp )
20 .. cpp:function:: int ioctl( int fd, int request, struct v4l2_query_ext_ctrl *argp )
22 .. cpp:function:: int ioctl( int fd, int request, struct v4l2_querymenu *argp )
29 File descriptor returned by :ref:`open() <func-open>`.
32 VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU
40 To query the attributes of a control applications set the ``id`` field
41 of a struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` and call the
42 ``VIDIOC_QUERYCTRL`` ioctl with a pointer to this structure. The driver
43 fills the rest of the structure or returns an ``EINVAL`` error code when the
46 It is possible to enumerate controls by calling ``VIDIOC_QUERYCTRL``
47 with successive ``id`` values starting from ``V4L2_CID_BASE`` up to and
48 exclusive ``V4L2_CID_LASTP1``. Drivers may return ``EINVAL`` if a control in
49 this range is not supported. Further applications can enumerate private
50 controls, which are not defined in this specification, by starting at
51 ``V4L2_CID_PRIVATE_BASE`` and incrementing ``id`` until the driver
54 In both cases, when the driver sets the ``V4L2_CTRL_FLAG_DISABLED`` flag
55 in the ``flags`` field this control is permanently disabled and should
56 be ignored by the application. [#f1]_
58 When the application ORs ``id`` with ``V4L2_CTRL_FLAG_NEXT_CTRL`` the
59 driver returns the next supported non-compound control, or ``EINVAL`` if
60 there is none. In addition, the ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` flag
61 can be specified to enumerate all compound controls (i.e. controls with
62 type ≥ ``V4L2_CTRL_COMPOUND_TYPES`` and/or array control, in other words
63 controls that contain more than one value). Specify both
64 ``V4L2_CTRL_FLAG_NEXT_CTRL`` and ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` in
65 order to enumerate all controls, compound or not. Drivers which do not
66 support these flags yet always return ``EINVAL``.
68 The ``VIDIOC_QUERY_EXT_CTRL`` ioctl was introduced in order to better
69 support controls that can use compound types, and to expose additional
70 control information that cannot be returned in struct
71 :ref:`v4l2_queryctrl <v4l2-queryctrl>` since that structure is full.
73 ``VIDIOC_QUERY_EXT_CTRL`` is used in the same way as
74 ``VIDIOC_QUERYCTRL``, except that the ``reserved`` array must be zeroed
77 Additional information is required for menu controls: the names of the
78 menu items. To query them applications set the ``id`` and ``index``
79 fields of struct :ref:`v4l2_querymenu <v4l2-querymenu>` and call the
80 ``VIDIOC_QUERYMENU`` ioctl with a pointer to this structure. The driver
81 fills the rest of the structure or returns an ``EINVAL`` error code when the
82 ``id`` or ``index`` is invalid. Menu items are enumerated by calling
83 ``VIDIOC_QUERYMENU`` with successive ``index`` values from struct
84 :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``minimum`` to ``maximum``,
89 It is possible for ``VIDIOC_QUERYMENU`` to return
90 an ``EINVAL`` error code for some indices between ``minimum`` and
91 ``maximum``. In that case that particular menu item is not supported by
92 this driver. Also note that the ``minimum`` value is not necessarily 0.
94 See also the examples in :ref:`control`.
99 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
101 .. flat-table:: struct v4l2_queryctrl
113 - Identifies the control, set by the application. See
114 :ref:`control-id` for predefined IDs. When the ID is ORed with
115 V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and
116 returns the first control with a higher ID. Drivers which do not
117 support this flag yet always return an ``EINVAL`` error code.
125 - Type of control, see :ref:`v4l2-ctrl-type`.
133 - Name of the control, a NUL-terminated ASCII string. This
134 information is intended for the user.
142 - Minimum value, inclusive. This field gives a lower bound for the
143 control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
144 the minimum value is to be used for each possible control type.
145 Note that this a signed 32-bit value.
153 - Maximum value, inclusive. This field gives an upper bound for the
154 control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
155 the maximum value is to be used for each possible control type.
156 Note that this a signed 32-bit value.
164 - This field gives a step size for the control. See enum
165 :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how the step value is
166 to be used for each possible control type. Note that this an
167 unsigned 32-bit value.
169 Generally drivers should not scale hardware control values. It may
170 be necessary for example when the ``name`` or ``id`` imply a
171 particular unit and the hardware actually accepts only multiples
172 of said unit. If so, drivers must take care values are properly
173 rounded when scaling, such that errors will not accumulate on
174 repeated read-write cycles.
176 This field gives the smallest change of an integer control
177 actually affecting hardware. Often the information is needed when
178 the user can change controls by keyboard or GUI buttons, rather
179 than a slider. When for example a hardware register accepts values
180 0-511 and the driver reports 0-65535, step should be 128.
182 Note that although signed, the step value is supposed to be always
191 - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_BOOLEAN``,
192 ``_BITMASK``, ``_MENU`` or ``_INTEGER_MENU`` control. Not valid
193 for other types of controls.
197 Drivers reset controls to their default value only when
198 the driver is first loaded, never afterwards.
206 - Control flags, see :ref:`control-flags`.
214 - Reserved for future extensions. Drivers must set the array to
219 .. _v4l2-query-ext-ctrl:
221 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
223 .. flat-table:: struct v4l2_query_ext_ctrl
235 - Identifies the control, set by the application. See
236 :ref:`control-id` for predefined IDs. When the ID is ORed with
237 ``V4L2_CTRL_FLAG_NEXT_CTRL`` the driver clears the flag and
238 returns the first non-compound control with a higher ID. When the
239 ID is ORed with ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` the driver clears
240 the flag and returns the first compound control with a higher ID.
241 Set both to get the first control (compound or not) with a higher
250 - Type of control, see :ref:`v4l2-ctrl-type`.
258 - Name of the control, a NUL-terminated ASCII string. This
259 information is intended for the user.
267 - Minimum value, inclusive. This field gives a lower bound for the
268 control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
269 the minimum value is to be used for each possible control type.
270 Note that this a signed 64-bit value.
278 - Maximum value, inclusive. This field gives an upper bound for the
279 control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
280 the maximum value is to be used for each possible control type.
281 Note that this a signed 64-bit value.
289 - This field gives a step size for the control. See enum
290 :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how the step value is
291 to be used for each possible control type. Note that this an
292 unsigned 64-bit value.
294 Generally drivers should not scale hardware control values. It may
295 be necessary for example when the ``name`` or ``id`` imply a
296 particular unit and the hardware actually accepts only multiples
297 of said unit. If so, drivers must take care values are properly
298 rounded when scaling, such that errors will not accumulate on
299 repeated read-write cycles.
301 This field gives the smallest change of an integer control
302 actually affecting hardware. Often the information is needed when
303 the user can change controls by keyboard or GUI buttons, rather
304 than a slider. When for example a hardware register accepts values
305 0-511 and the driver reports 0-65535, step should be 128.
313 - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_INTEGER64``,
314 ``_BOOLEAN``, ``_BITMASK``, ``_MENU``, ``_INTEGER_MENU``, ``_U8``
315 or ``_U16`` control. Not valid for other types of controls.
319 Drivers reset controls to their default value only when
320 the driver is first loaded, never afterwards.
328 - Control flags, see :ref:`control-flags`.
336 - The size in bytes of a single element of the array. Given a char
337 pointer ``p`` to a 3-dimensional array you can find the position
338 of cell ``(z, y, x)`` as follows:
339 ``p + ((z * dims[1] + y) * dims[0] + x) * elem_size``.
340 ``elem_size`` is always valid, also when the control isn't an
341 array. For string controls ``elem_size`` is equal to
350 - The number of elements in the N-dimensional array. If this control
351 is not an array, then ``elems`` is 1. The ``elems`` field can
360 - The number of dimension in the N-dimensional array. If this
361 control is not an array, then this field is 0.
367 - ``dims[V4L2_CTRL_MAX_DIMS]``
369 - The size of each dimension. The first ``nr_of_dims`` elements of
370 this array must be non-zero, all remaining elements must be zero.
378 - Reserved for future extensions. Applications and drivers must set
385 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{7.0cm}|p{3.5cm}|
387 .. flat-table:: struct v4l2_querymenu
400 - Identifies the control, set by the application from the respective
401 struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id``.
410 - Index of the menu item, starting at zero, set by the application.
427 - Name of the menu item, a NUL-terminated ASCII string. This
428 information is intended for the user. This field is valid for
429 ``V4L2_CTRL_FLAG_MENU`` type controls.
438 - Value of the integer menu item. This field is valid for
439 ``V4L2_CTRL_FLAG_INTEGER_MENU`` type controls.
448 - Reserved for future extensions. Drivers must set the array to
455 .. tabularcolumns:: |p{5.3cm}|p{0.9cm}|p{0.9cm}|p{0.9cm}|p{9.5cm}|
457 .. flat-table:: enum v4l2_ctrl_type
477 - ``V4L2_CTRL_TYPE_INTEGER``
485 - An integer-valued control ranging from minimum to maximum
486 inclusive. The step value indicates the increment between values.
490 - ``V4L2_CTRL_TYPE_BOOLEAN``
498 - A boolean-valued control. Zero corresponds to "disabled", and one
503 - ``V4L2_CTRL_TYPE_MENU``
511 - The control has a menu of N choices. The names of the menu items
512 can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl.
516 - ``V4L2_CTRL_TYPE_INTEGER_MENU``
524 - The control has a menu of N choices. The values of the menu items
525 can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. This is
526 similar to ``V4L2_CTRL_TYPE_MENU`` except that instead of strings,
527 the menu items are signed 64-bit integers.
531 - ``V4L2_CTRL_TYPE_BITMASK``
539 - A bitmask field. The maximum value is the set of bits that can be
540 used, all other bits are to be 0. The maximum value is interpreted
541 as a __u32, allowing the use of bit 31 in the bitmask.
545 - ``V4L2_CTRL_TYPE_BUTTON``
553 - A control which performs an action when set. Drivers must ignore
554 the value passed with ``VIDIOC_S_CTRL`` and return an ``EINVAL`` error
555 code on a ``VIDIOC_G_CTRL`` attempt.
559 - ``V4L2_CTRL_TYPE_INTEGER64``
567 - A 64-bit integer valued control. Minimum, maximum and step size
568 cannot be queried using ``VIDIOC_QUERYCTRL``. Only
569 ``VIDIOC_QUERY_EXT_CTRL`` can retrieve the 64-bit min/max/step
570 values, they should be interpreted as n/a when using
571 ``VIDIOC_QUERYCTRL``.
575 - ``V4L2_CTRL_TYPE_STRING``
583 - The minimum and maximum string lengths. The step size means that
584 the string must be (minimum + N * step) characters long for N ≥ 0.
585 These lengths do not include the terminating zero, so in order to
586 pass a string of length 8 to
587 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you need to
588 set the ``size`` field of struct
589 :ref:`v4l2_ext_control <v4l2-ext-control>` to 9. For
590 :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you can set
591 the ``size`` field to ``maximum`` + 1. Which character encoding is
592 used will depend on the string control itself and should be part
593 of the control documentation.
597 - ``V4L2_CTRL_TYPE_CTRL_CLASS``
605 - This is not a control. When ``VIDIOC_QUERYCTRL`` is called with a
606 control ID equal to a control class code (see :ref:`ctrl-class`)
607 + 1, the ioctl returns the name of the control class and this
608 control type. Older drivers which do not support this feature
609 return an ``EINVAL`` error code.
613 - ``V4L2_CTRL_TYPE_U8``
621 - An unsigned 8-bit valued control ranging from minimum to maximum
622 inclusive. The step value indicates the increment between values.
626 - ``V4L2_CTRL_TYPE_U16``
634 - An unsigned 16-bit valued control ranging from minimum to maximum
635 inclusive. The step value indicates the increment between values.
639 - ``V4L2_CTRL_TYPE_U32``
647 - An unsigned 32-bit valued control ranging from minimum to maximum
648 inclusive. The step value indicates the increment between values.
654 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
656 .. flat-table:: Control Flags
664 - ``V4L2_CTRL_FLAG_DISABLED``
668 - This control is permanently disabled and should be ignored by the
669 application. Any attempt to change the control will result in an
670 ``EINVAL`` error code.
674 - ``V4L2_CTRL_FLAG_GRABBED``
678 - This control is temporarily unchangeable, for example because
679 another application took over control of the respective resource.
680 Such controls may be displayed specially in a user interface.
681 Attempts to change the control may result in an ``EBUSY`` error code.
685 - ``V4L2_CTRL_FLAG_READ_ONLY``
689 - This control is permanently readable only. Any attempt to change
690 the control will result in an ``EINVAL`` error code.
694 - ``V4L2_CTRL_FLAG_UPDATE``
698 - A hint that changing this control may affect the value of other
699 controls within the same control class. Applications should update
700 their user interface accordingly.
704 - ``V4L2_CTRL_FLAG_INACTIVE``
708 - This control is not applicable to the current configuration and
709 should be displayed accordingly in a user interface. For example
710 the flag may be set on a MPEG audio level 2 bitrate control when
711 MPEG audio encoding level 1 was selected with another control.
715 - ``V4L2_CTRL_FLAG_SLIDER``
719 - A hint that this control is best represented as a slider-like
720 element in a user interface.
724 - ``V4L2_CTRL_FLAG_WRITE_ONLY``
728 - This control is permanently writable only. Any attempt to read the
729 control will result in an ``EACCES`` error code error code. This flag
730 is typically present for relative controls or action controls
731 where writing a value will cause the device to carry out a given
732 action (e. g. motor control) but no meaningful value can be
737 - ``V4L2_CTRL_FLAG_VOLATILE``
741 - This control is volatile, which means that the value of the
742 control changes continuously. A typical example would be the
743 current gain value if the device is in auto-gain mode. In such a
744 case the hardware calculates the gain value based on the lighting
745 conditions which can change over time.
749 Setting a new value for a volatile control will have no
750 effect and no ``V4L2_EVENT_CTRL_CH_VALUE`` will be sent, unless
751 the ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE`` flag (see below) is
752 also set. Otherwise the new value will just be ignored.
756 - ``V4L2_CTRL_FLAG_HAS_PAYLOAD``
760 - This control has a pointer type, so its value has to be accessed
761 using one of the pointer fields of struct
762 :ref:`v4l2_ext_control <v4l2-ext-control>`. This flag is set
763 for controls that are an array, string, or have a compound type.
764 In all cases you have to set a pointer to memory containing the
765 payload of the control.
769 - ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
773 - The value provided to the control will be propagated to the driver
774 even if it remains constant. This is required when the control
775 represents an action on the hardware. For example: clearing an
776 error flag or triggering the flash. All the controls of the type
777 ``V4L2_CTRL_TYPE_BUTTON`` have this flag set.
783 On success 0 is returned, on error -1 and the ``errno`` variable is set
784 appropriately. The generic error codes are described at the
785 :ref:`Generic Error Codes <gen-errors>` chapter.
788 The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id`` is
789 invalid. The struct :ref:`v4l2_querymenu <v4l2-querymenu>` ``id``
790 is invalid or ``index`` is out of range (less than ``minimum`` or
791 greater than ``maximum``) or this particular menu item is not
792 supported by the driver.
795 An attempt was made to read a write-only control.
798 ``V4L2_CTRL_FLAG_DISABLED`` was intended for two purposes: Drivers
799 can skip predefined controls not supported by the hardware (although
800 returning ``EINVAL`` would do as well), or disable predefined and private
801 controls after hardware detection without the trouble of reordering
802 control arrays and indices (``EINVAL`` cannot be used to skip private
803 controls because it would prematurely end the enumeration).
projects / cascardo / linux.git / blob