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>`.
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`.
97 .. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.7cm}|
101 .. cssclass:: longtable
103 .. flat-table:: struct v4l2_queryctrl
115 - Identifies the control, set by the application. See
116 :ref:`control-id` for predefined IDs. When the ID is ORed with
117 V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and
118 returns the first control with a higher ID. Drivers which do not
119 support this flag yet always return an ``EINVAL`` error code.
127 - Type of control, see :ref:`v4l2-ctrl-type`.
135 - Name of the control, a NUL-terminated ASCII string. This
136 information is intended for the user.
144 - Minimum value, inclusive. This field gives a lower bound for the
145 control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
146 the minimum value is to be used for each possible control type.
147 Note that this a signed 32-bit value.
155 - Maximum value, inclusive. This field gives an upper bound for the
156 control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
157 the maximum value is to be used for each possible control type.
158 Note that this a signed 32-bit value.
166 - This field gives a step size for the control. See enum
167 :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how the step value is
168 to be used for each possible control type. Note that this an
169 unsigned 32-bit value.
171 Generally drivers should not scale hardware control values. It may
172 be necessary for example when the ``name`` or ``id`` imply a
173 particular unit and the hardware actually accepts only multiples
174 of said unit. If so, drivers must take care values are properly
175 rounded when scaling, such that errors will not accumulate on
176 repeated read-write cycles.
178 This field gives the smallest change of an integer control
179 actually affecting hardware. Often the information is needed when
180 the user can change controls by keyboard or GUI buttons, rather
181 than a slider. When for example a hardware register accepts values
182 0-511 and the driver reports 0-65535, step should be 128.
184 Note that although signed, the step value is supposed to be always
193 - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_BOOLEAN``,
194 ``_BITMASK``, ``_MENU`` or ``_INTEGER_MENU`` control. Not valid
195 for other types of controls.
199 Drivers reset controls to their default value only when
200 the driver is first loaded, never afterwards.
208 - Control flags, see :ref:`control-flags`.
216 - Reserved for future extensions. Drivers must set the array to
221 .. tabularcolumns:: |p{1.2cm}|p{5.0cm}|p{11.3cm}|
223 .. _v4l2-query-ext-ctrl:
225 .. cssclass:: longtable
227 .. flat-table:: struct v4l2_query_ext_ctrl
239 - Identifies the control, set by the application. See
240 :ref:`control-id` for predefined IDs. When the ID is ORed with
241 ``V4L2_CTRL_FLAG_NEXT_CTRL`` the driver clears the flag and
242 returns the first non-compound control with a higher ID. When the
243 ID is ORed with ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` the driver clears
244 the flag and returns the first compound control with a higher ID.
245 Set both to get the first control (compound or not) with a higher
254 - Type of control, see :ref:`v4l2-ctrl-type`.
262 - Name of the control, a NUL-terminated ASCII string. This
263 information is intended for the user.
271 - Minimum value, inclusive. This field gives a lower bound for the
272 control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
273 the minimum value is to be used for each possible control type.
274 Note that this a signed 64-bit value.
282 - Maximum value, inclusive. This field gives an upper bound for the
283 control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
284 the maximum value is to be used for each possible control type.
285 Note that this a signed 64-bit value.
293 - This field gives a step size for the control. See enum
294 :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how the step value is
295 to be used for each possible control type. Note that this an
296 unsigned 64-bit value.
298 Generally drivers should not scale hardware control values. It may
299 be necessary for example when the ``name`` or ``id`` imply a
300 particular unit and the hardware actually accepts only multiples
301 of said unit. If so, drivers must take care values are properly
302 rounded when scaling, such that errors will not accumulate on
303 repeated read-write cycles.
305 This field gives the smallest change of an integer control
306 actually affecting hardware. Often the information is needed when
307 the user can change controls by keyboard or GUI buttons, rather
308 than a slider. When for example a hardware register accepts values
309 0-511 and the driver reports 0-65535, step should be 128.
317 - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_INTEGER64``,
318 ``_BOOLEAN``, ``_BITMASK``, ``_MENU``, ``_INTEGER_MENU``, ``_U8``
319 or ``_U16`` control. Not valid for other types of controls.
323 Drivers reset controls to their default value only when
324 the driver is first loaded, never afterwards.
332 - Control flags, see :ref:`control-flags`.
340 - The size in bytes of a single element of the array. Given a char
341 pointer ``p`` to a 3-dimensional array you can find the position
342 of cell ``(z, y, x)`` as follows:
343 ``p + ((z * dims[1] + y) * dims[0] + x) * elem_size``.
344 ``elem_size`` is always valid, also when the control isn't an
345 array. For string controls ``elem_size`` is equal to
354 - The number of elements in the N-dimensional array. If this control
355 is not an array, then ``elems`` is 1. The ``elems`` field can
364 - The number of dimension in the N-dimensional array. If this
365 control is not an array, then this field is 0.
371 - ``dims[V4L2_CTRL_MAX_DIMS]``
373 - The size of each dimension. The first ``nr_of_dims`` elements of
374 this array must be non-zero, all remaining elements must be zero.
382 - Reserved for future extensions. Applications and drivers must set
387 .. tabularcolumns:: |p{1.2cm}|p{0.6cm}|p{1.6cm}|p{13.5cm}|
391 .. flat-table:: struct v4l2_querymenu
404 - Identifies the control, set by the application from the respective
405 struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id``.
414 - Index of the menu item, starting at zero, set by the application.
431 - Name of the menu item, a NUL-terminated ASCII string. This
432 information is intended for the user. This field is valid for
433 ``V4L2_CTRL_FLAG_MENU`` type controls.
442 - Value of the integer menu item. This field is valid for
443 ``V4L2_CTRL_FLAG_INTEGER_MENU`` type controls.
452 - Reserved for future extensions. Drivers must set the array to
457 .. tabularcolumns:: |p{5.8cm}|p{1.4cm}|p{1.0cm}|p{1.4cm}|p{6.9cm}|
461 .. cssclass:: longtable
463 .. flat-table:: enum v4l2_ctrl_type
483 - ``V4L2_CTRL_TYPE_INTEGER``
491 - An integer-valued control ranging from minimum to maximum
492 inclusive. The step value indicates the increment between values.
496 - ``V4L2_CTRL_TYPE_BOOLEAN``
504 - A boolean-valued control. Zero corresponds to "disabled", and one
509 - ``V4L2_CTRL_TYPE_MENU``
517 - The control has a menu of N choices. The names of the menu items
518 can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl.
522 - ``V4L2_CTRL_TYPE_INTEGER_MENU``
530 - The control has a menu of N choices. The values of the menu items
531 can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. This is
532 similar to ``V4L2_CTRL_TYPE_MENU`` except that instead of strings,
533 the menu items are signed 64-bit integers.
537 - ``V4L2_CTRL_TYPE_BITMASK``
545 - A bitmask field. The maximum value is the set of bits that can be
546 used, all other bits are to be 0. The maximum value is interpreted
547 as a __u32, allowing the use of bit 31 in the bitmask.
551 - ``V4L2_CTRL_TYPE_BUTTON``
559 - A control which performs an action when set. Drivers must ignore
560 the value passed with ``VIDIOC_S_CTRL`` and return an ``EINVAL`` error
561 code on a ``VIDIOC_G_CTRL`` attempt.
565 - ``V4L2_CTRL_TYPE_INTEGER64``
573 - A 64-bit integer valued control. Minimum, maximum and step size
574 cannot be queried using ``VIDIOC_QUERYCTRL``. Only
575 ``VIDIOC_QUERY_EXT_CTRL`` can retrieve the 64-bit min/max/step
576 values, they should be interpreted as n/a when using
577 ``VIDIOC_QUERYCTRL``.
581 - ``V4L2_CTRL_TYPE_STRING``
589 - The minimum and maximum string lengths. The step size means that
590 the string must be (minimum + N * step) characters long for N ≥ 0.
591 These lengths do not include the terminating zero, so in order to
592 pass a string of length 8 to
593 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you need to
594 set the ``size`` field of struct
595 :ref:`v4l2_ext_control <v4l2-ext-control>` to 9. For
596 :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you can set
597 the ``size`` field to ``maximum`` + 1. Which character encoding is
598 used will depend on the string control itself and should be part
599 of the control documentation.
603 - ``V4L2_CTRL_TYPE_CTRL_CLASS``
611 - This is not a control. When ``VIDIOC_QUERYCTRL`` is called with a
612 control ID equal to a control class code (see :ref:`ctrl-class`)
613 + 1, the ioctl returns the name of the control class and this
614 control type. Older drivers which do not support this feature
615 return an ``EINVAL`` error code.
619 - ``V4L2_CTRL_TYPE_U8``
627 - An unsigned 8-bit valued control ranging from minimum to maximum
628 inclusive. The step value indicates the increment between values.
632 - ``V4L2_CTRL_TYPE_U16``
640 - An unsigned 16-bit valued control ranging from minimum to maximum
641 inclusive. The step value indicates the increment between values.
645 - ``V4L2_CTRL_TYPE_U32``
653 - An unsigned 32-bit valued control ranging from minimum to maximum
654 inclusive. The step value indicates the increment between values.
658 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
662 .. cssclass:: longtable
664 .. flat-table:: Control Flags
672 - ``V4L2_CTRL_FLAG_DISABLED``
676 - This control is permanently disabled and should be ignored by the
677 application. Any attempt to change the control will result in an
678 ``EINVAL`` error code.
682 - ``V4L2_CTRL_FLAG_GRABBED``
686 - This control is temporarily unchangeable, for example because
687 another application took over control of the respective resource.
688 Such controls may be displayed specially in a user interface.
689 Attempts to change the control may result in an ``EBUSY`` error code.
693 - ``V4L2_CTRL_FLAG_READ_ONLY``
697 - This control is permanently readable only. Any attempt to change
698 the control will result in an ``EINVAL`` error code.
702 - ``V4L2_CTRL_FLAG_UPDATE``
706 - A hint that changing this control may affect the value of other
707 controls within the same control class. Applications should update
708 their user interface accordingly.
712 - ``V4L2_CTRL_FLAG_INACTIVE``
716 - This control is not applicable to the current configuration and
717 should be displayed accordingly in a user interface. For example
718 the flag may be set on a MPEG audio level 2 bitrate control when
719 MPEG audio encoding level 1 was selected with another control.
723 - ``V4L2_CTRL_FLAG_SLIDER``
727 - A hint that this control is best represented as a slider-like
728 element in a user interface.
732 - ``V4L2_CTRL_FLAG_WRITE_ONLY``
736 - This control is permanently writable only. Any attempt to read the
737 control will result in an ``EACCES`` error code error code. This flag
738 is typically present for relative controls or action controls
739 where writing a value will cause the device to carry out a given
740 action (e. g. motor control) but no meaningful value can be
745 - ``V4L2_CTRL_FLAG_VOLATILE``
749 - This control is volatile, which means that the value of the
750 control changes continuously. A typical example would be the
751 current gain value if the device is in auto-gain mode. In such a
752 case the hardware calculates the gain value based on the lighting
753 conditions which can change over time.
757 Setting a new value for a volatile control will be ignored
759 :ref:`V4L2_CTRL_FLAG_EXECUTE_ON_WRITE <FLAG_EXECUTE_ON_WRITE>`
761 Setting a new value for a volatile control will *never* trigger a
762 :ref:`V4L2_EVENT_CTRL_CH_VALUE <ctrl-changes-flags>` event.
766 - ``V4L2_CTRL_FLAG_HAS_PAYLOAD``
770 - This control has a pointer type, so its value has to be accessed
771 using one of the pointer fields of struct
772 :ref:`v4l2_ext_control <v4l2-ext-control>`. This flag is set
773 for controls that are an array, string, or have a compound type.
774 In all cases you have to set a pointer to memory containing the
775 payload of the control.
778 .. _FLAG_EXECUTE_ON_WRITE:
780 - ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
784 - The value provided to the control will be propagated to the driver
785 even if it remains constant. This is required when the control
786 represents an action on the hardware. For example: clearing an
787 error flag or triggering the flash. All the controls of the type
788 ``V4L2_CTRL_TYPE_BUTTON`` have this flag set.
794 On success 0 is returned, on error -1 and the ``errno`` variable is set
795 appropriately. The generic error codes are described at the
796 :ref:`Generic Error Codes <gen-errors>` chapter.
799 The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id`` is
800 invalid. The struct :ref:`v4l2_querymenu <v4l2-querymenu>` ``id``
801 is invalid or ``index`` is out of range (less than ``minimum`` or
802 greater than ``maximum``) or this particular menu item is not
803 supported by the driver.
806 An attempt was made to read a write-only control.
809 ``V4L2_CTRL_FLAG_DISABLED`` was intended for two purposes: Drivers
810 can skip predefined controls not supported by the hardware (although
811 returning ``EINVAL`` would do as well), or disable predefined and private
812 controls after hardware detection without the trouble of reordering
813 control arrays and indices (``EINVAL`` cannot be used to skip private
814 controls because it would prematurely end the enumeration).
projects / cascardo / linux.git / blob