^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) .. c:namespace:: V4L
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) .. _VIDIOC_QUERYCTRL:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) *******************************************************************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) *******************************************************************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) Name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) ====
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) Synopsis
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) ``int ioctl(int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) .. c:macro:: VIDIOC_QUERY_EXT_CTRL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) ``int ioctl(int fd, VIDIOC_QUERY_EXT_CTRL, struct v4l2_query_ext_ctrl *argp)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) .. c:macro:: VIDIOC_QUERYMENU
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) ``int ioctl(int fd, VIDIOC_QUERYMENU, struct v4l2_querymenu *argp)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) Arguments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) =========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) ``fd``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) File descriptor returned by :c:func:`open()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) ``argp``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) Pointer to struct :c:type:`v4l2_queryctrl`, :c:type:`v4l2_query_ext_ctrl`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) or :c:type:`v4l2_querymenu` (depending on the ioctl).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) Description
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) To query the attributes of a control applications set the ``id`` field
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) of a struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` and call the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) ``VIDIOC_QUERYCTRL`` ioctl with a pointer to this structure. The driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) fills the rest of the structure or returns an ``EINVAL`` error code when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) ``id`` is invalid.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) It is possible to enumerate controls by calling ``VIDIOC_QUERYCTRL``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) with successive ``id`` values starting from ``V4L2_CID_BASE`` up to and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) exclusive ``V4L2_CID_LASTP1``. Drivers may return ``EINVAL`` if a control in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) this range is not supported. Further applications can enumerate private
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) controls, which are not defined in this specification, by starting at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) ``V4L2_CID_PRIVATE_BASE`` and incrementing ``id`` until the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) returns ``EINVAL``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) In both cases, when the driver sets the ``V4L2_CTRL_FLAG_DISABLED`` flag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) in the ``flags`` field this control is permanently disabled and should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) be ignored by the application. [#f1]_
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) When the application ORs ``id`` with ``V4L2_CTRL_FLAG_NEXT_CTRL`` the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) driver returns the next supported non-compound control, or ``EINVAL`` if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) there is none. In addition, the ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` flag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) can be specified to enumerate all compound controls (i.e. controls with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) type ≥ ``V4L2_CTRL_COMPOUND_TYPES`` and/or array control, in other words
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) controls that contain more than one value). Specify both
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) ``V4L2_CTRL_FLAG_NEXT_CTRL`` and ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) order to enumerate all controls, compound or not. Drivers which do not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) support these flags yet always return ``EINVAL``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) The ``VIDIOC_QUERY_EXT_CTRL`` ioctl was introduced in order to better
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) support controls that can use compound types, and to expose additional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) control information that cannot be returned in struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) :ref:`v4l2_queryctrl <v4l2-queryctrl>` since that structure is full.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) ``VIDIOC_QUERY_EXT_CTRL`` is used in the same way as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) ``VIDIOC_QUERYCTRL``, except that the ``reserved`` array must be zeroed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) as well.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) Additional information is required for menu controls: the names of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) menu items. To query them applications set the ``id`` and ``index``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) fields of struct :ref:`v4l2_querymenu <v4l2-querymenu>` and call the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) ``VIDIOC_QUERYMENU`` ioctl with a pointer to this structure. The driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) fills the rest of the structure or returns an ``EINVAL`` error code when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) ``id`` or ``index`` is invalid. Menu items are enumerated by calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) ``VIDIOC_QUERYMENU`` with successive ``index`` values from struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``minimum`` to ``maximum``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) inclusive.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) It is possible for ``VIDIOC_QUERYMENU`` to return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) an ``EINVAL`` error code for some indices between ``minimum`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) ``maximum``. In that case that particular menu item is not supported by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) this driver. Also note that the ``minimum`` value is not necessarily 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) See also the examples in :ref:`control`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) .. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.7cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) .. _v4l2-queryctrl:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) .. cssclass:: longtable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) .. flat-table:: struct v4l2_queryctrl
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) :header-rows: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) :widths: 1 1 2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) - ``id``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) - Identifies the control, set by the application. See
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) :ref:`control-id` for predefined IDs. When the ID is ORed with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) returns the first control with a higher ID. Drivers which do not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) support this flag yet always return an ``EINVAL`` error code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) - ``type``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) - Type of control, see :c:type:`v4l2_ctrl_type`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) * - __u8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) - ``name``\ [32]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) - Name of the control, a NUL-terminated ASCII string. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) information is intended for the user.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) * - __s32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) - ``minimum``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) - Minimum value, inclusive. This field gives a lower bound for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) control. See enum :c:type:`v4l2_ctrl_type` how
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) the minimum value is to be used for each possible control type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) Note that this a signed 32-bit value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) * - __s32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) - ``maximum``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) - Maximum value, inclusive. This field gives an upper bound for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) control. See enum :c:type:`v4l2_ctrl_type` how
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) the maximum value is to be used for each possible control type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) Note that this a signed 32-bit value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) * - __s32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) - ``step``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) - This field gives a step size for the control. See enum
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) :c:type:`v4l2_ctrl_type` how the step value is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) to be used for each possible control type. Note that this an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) unsigned 32-bit value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) Generally drivers should not scale hardware control values. It may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) be necessary for example when the ``name`` or ``id`` imply a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) particular unit and the hardware actually accepts only multiples
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) of said unit. If so, drivers must take care values are properly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) rounded when scaling, such that errors will not accumulate on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) repeated read-write cycles.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) This field gives the smallest change of an integer control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) actually affecting hardware. Often the information is needed when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) the user can change controls by keyboard or GUI buttons, rather
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) than a slider. When for example a hardware register accepts values
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) 0-511 and the driver reports 0-65535, step should be 128.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) Note that although signed, the step value is supposed to be always
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) positive.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) * - __s32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) - ``default_value``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_BOOLEAN``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) ``_BITMASK``, ``_MENU`` or ``_INTEGER_MENU`` control. Not valid
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) for other types of controls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) Drivers reset controls to their default value only when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) the driver is first loaded, never afterwards.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) - ``flags``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) - Control flags, see :ref:`control-flags`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) - ``reserved``\ [2]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) - Reserved for future extensions. Drivers must set the array to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) .. tabularcolumns:: |p{1.2cm}|p{5.0cm}|p{11.3cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) .. _v4l2-query-ext-ctrl:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) .. cssclass:: longtable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) .. flat-table:: struct v4l2_query_ext_ctrl
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) :header-rows: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) :widths: 1 1 2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) - ``id``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) - Identifies the control, set by the application. See
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) :ref:`control-id` for predefined IDs. When the ID is ORed with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) ``V4L2_CTRL_FLAG_NEXT_CTRL`` the driver clears the flag and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) returns the first non-compound control with a higher ID. When the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) ID is ORed with ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` the driver clears
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) the flag and returns the first compound control with a higher ID.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) Set both to get the first control (compound or not) with a higher
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) ID.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) - ``type``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) - Type of control, see :c:type:`v4l2_ctrl_type`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) * - char
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) - ``name``\ [32]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) - Name of the control, a NUL-terminated ASCII string. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) information is intended for the user.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) * - __s64
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) - ``minimum``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) - Minimum value, inclusive. This field gives a lower bound for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) control. See enum :c:type:`v4l2_ctrl_type` how
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) the minimum value is to be used for each possible control type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) Note that this a signed 64-bit value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) * - __s64
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) - ``maximum``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) - Maximum value, inclusive. This field gives an upper bound for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) control. See enum :c:type:`v4l2_ctrl_type` how
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) the maximum value is to be used for each possible control type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) Note that this a signed 64-bit value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) * - __u64
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) - ``step``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) - This field gives a step size for the control. See enum
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) :c:type:`v4l2_ctrl_type` how the step value is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) to be used for each possible control type. Note that this an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) unsigned 64-bit value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) Generally drivers should not scale hardware control values. It may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) be necessary for example when the ``name`` or ``id`` imply a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) particular unit and the hardware actually accepts only multiples
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) of said unit. If so, drivers must take care values are properly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) rounded when scaling, such that errors will not accumulate on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) repeated read-write cycles.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) This field gives the smallest change of an integer control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) actually affecting hardware. Often the information is needed when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) the user can change controls by keyboard or GUI buttons, rather
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) than a slider. When for example a hardware register accepts values
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) 0-511 and the driver reports 0-65535, step should be 128.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) * - __s64
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) - ``default_value``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_INTEGER64``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) ``_BOOLEAN``, ``_BITMASK``, ``_MENU``, ``_INTEGER_MENU``, ``_U8``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) or ``_U16`` control. Not valid for other types of controls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) Drivers reset controls to their default value only when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) the driver is first loaded, never afterwards.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) - ``flags``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) - Control flags, see :ref:`control-flags`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) - ``elem_size``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) - The size in bytes of a single element of the array. Given a char
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) pointer ``p`` to a 3-dimensional array you can find the position
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) of cell ``(z, y, x)`` as follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) ``p + ((z * dims[1] + y) * dims[0] + x) * elem_size``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) ``elem_size`` is always valid, also when the control isn't an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) array. For string controls ``elem_size`` is equal to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) ``maximum + 1``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) - ``elems``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) - The number of elements in the N-dimensional array. If this control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) is not an array, then ``elems`` is 1. The ``elems`` field can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) never be 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) - ``nr_of_dims``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) - The number of dimension in the N-dimensional array. If this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) control is not an array, then this field is 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) - ``dims[V4L2_CTRL_MAX_DIMS]``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) - The size of each dimension. The first ``nr_of_dims`` elements of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) this array must be non-zero, all remaining elements must be zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) - ``reserved``\ [32]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) - Reserved for future extensions. Applications and drivers must set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) the array to zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) .. tabularcolumns:: |p{1.2cm}|p{1.0cm}|p{1.7cm}|p{13.0cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) .. _v4l2-querymenu:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) .. flat-table:: struct v4l2_querymenu
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) :header-rows: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) :widths: 1 1 2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) - ``id``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) - Identifies the control, set by the application from the respective
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) - ``index``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) - Index of the menu item, starting at zero, set by the application.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) * - union {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) - (anonymous)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) * - __u8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) - ``name``\ [32]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) - Name of the menu item, a NUL-terminated ASCII string. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) information is intended for the user. This field is valid for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) ``V4L2_CTRL_TYPE_MENU`` type controls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) * - __s64
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) - ``value``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) - Value of the integer menu item. This field is valid for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) ``V4L2_CTRL_TYPE_INTEGER_MENU`` type controls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) * - }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) - ``reserved``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) - Reserved for future extensions. Drivers must set the array to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) .. tabularcolumns:: |p{5.8cm}|p{1.4cm}|p{1.0cm}|p{1.4cm}|p{6.9cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) .. c:type:: v4l2_ctrl_type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) .. cssclass:: longtable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) .. flat-table:: enum v4l2_ctrl_type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) :header-rows: 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) :widths: 30 5 5 5 55
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) * - Type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) - ``minimum``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) - ``step``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) - ``maximum``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) - Description
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) * - ``V4L2_CTRL_TYPE_INTEGER``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) - any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) - any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) - any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) - An integer-valued control ranging from minimum to maximum
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) inclusive. The step value indicates the increment between values.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) * - ``V4L2_CTRL_TYPE_BOOLEAN``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) - 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) - 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) - 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) - A boolean-valued control. Zero corresponds to "disabled", and one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) means "enabled".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) * - ``V4L2_CTRL_TYPE_MENU``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) - ≥ 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) - 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) - N-1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) - The control has a menu of N choices. The names of the menu items
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) * - ``V4L2_CTRL_TYPE_INTEGER_MENU``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) - ≥ 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) - 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) - N-1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) - The control has a menu of N choices. The values of the menu items
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. This is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) similar to ``V4L2_CTRL_TYPE_MENU`` except that instead of strings,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) the menu items are signed 64-bit integers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) * - ``V4L2_CTRL_TYPE_BITMASK``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) - 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) - any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) - A bitmask field. The maximum value is the set of bits that can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) used, all other bits are to be 0. The maximum value is interpreted
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) as a __u32, allowing the use of bit 31 in the bitmask.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) * - ``V4L2_CTRL_TYPE_BUTTON``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) - 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) - 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) - 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) - A control which performs an action when set. Drivers must ignore
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) the value passed with ``VIDIOC_S_CTRL`` and return an ``EACCES`` error
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) code on a ``VIDIOC_G_CTRL`` attempt.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) * - ``V4L2_CTRL_TYPE_INTEGER64``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) - any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) - any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) - any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) - A 64-bit integer valued control. Minimum, maximum and step size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) cannot be queried using ``VIDIOC_QUERYCTRL``. Only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) ``VIDIOC_QUERY_EXT_CTRL`` can retrieve the 64-bit min/max/step
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) values, they should be interpreted as n/a when using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) ``VIDIOC_QUERYCTRL``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) * - ``V4L2_CTRL_TYPE_STRING``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) - ≥ 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) - ≥ 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) - ≥ 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) - The minimum and maximum string lengths. The step size means that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) the string must be (minimum + N * step) characters long for N ≥ 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) These lengths do not include the terminating zero, so in order to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) pass a string of length 8 to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you need to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) set the ``size`` field of struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) :c:type:`v4l2_ext_control` to 9. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you can set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) the ``size`` field to ``maximum`` + 1. Which character encoding is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) used will depend on the string control itself and should be part
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) of the control documentation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) * - ``V4L2_CTRL_TYPE_CTRL_CLASS``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) - This is not a control. When ``VIDIOC_QUERYCTRL`` is called with a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) control ID equal to a control class code (see :ref:`ctrl-class`)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) + 1, the ioctl returns the name of the control class and this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) control type. Older drivers which do not support this feature
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) return an ``EINVAL`` error code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) * - ``V4L2_CTRL_TYPE_U8``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) - any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) - any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) - any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) - An unsigned 8-bit valued control ranging from minimum to maximum
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) inclusive. The step value indicates the increment between values.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) * - ``V4L2_CTRL_TYPE_U16``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) - any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) - any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) - any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) - An unsigned 16-bit valued control ranging from minimum to maximum
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) inclusive. The step value indicates the increment between values.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) * - ``V4L2_CTRL_TYPE_U32``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) - any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) - any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) - any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) - An unsigned 32-bit valued control ranging from minimum to maximum
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) inclusive. The step value indicates the increment between values.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) * - ``V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) - A struct :c:type:`v4l2_ctrl_mpeg2_slice_params`, containing MPEG-2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) slice parameters for stateless video decoders.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) * - ``V4L2_CTRL_TYPE_MPEG2_QUANTIZATION``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) - A struct :c:type:`v4l2_ctrl_mpeg2_quantization`, containing MPEG-2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) quantization matrices for stateless video decoders.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429) * - ``V4L2_CTRL_TYPE_AREA``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) - A struct :c:type:`v4l2_area`, containing the width and the height
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) of a rectangular area. Units depend on the use case.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) * - ``V4L2_CTRL_TYPE_H264_SPS``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) - A struct :c:type:`v4l2_ctrl_h264_sps`, containing H264
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) sequence parameters for stateless video decoders.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) * - ``V4L2_CTRL_TYPE_H264_PPS``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) - A struct :c:type:`v4l2_ctrl_h264_pps`, containing H264
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) picture parameters for stateless video decoders.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) * - ``V4L2_CTRL_TYPE_H264_SCALING_MATRIX``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) - A struct :c:type:`v4l2_ctrl_h264_scaling_matrix`, containing H264
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) scaling matrices for stateless video decoders.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) * - ``V4L2_CTRL_TYPE_H264_SLICE_PARAMS``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) - A struct :c:type:`v4l2_ctrl_h264_slice_params`, containing H264
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) slice parameters for stateless video decoders.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) * - ``V4L2_CTRL_TYPE_H264_DECODE_PARAMS``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) - A struct :c:type:`v4l2_ctrl_h264_decode_params`, containing H264
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) decode parameters for stateless video decoders.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) * - ``V4L2_CTRL_TYPE_HEVC_SPS``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) - A struct :c:type:`v4l2_ctrl_hevc_sps`, containing HEVC Sequence
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470) Parameter Set for stateless video decoders.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) * - ``V4L2_CTRL_TYPE_HEVC_PPS``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) - A struct :c:type:`v4l2_ctrl_hevc_pps`, containing HEVC Picture
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) Parameter Set for stateless video decoders.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) * - ``V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) - n/a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) - A struct :c:type:`v4l2_ctrl_hevc_slice_params`, containing HEVC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) slice parameters for stateless video decoders.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484) .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486) .. _control-flags:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) .. cssclass:: longtable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) .. flat-table:: Control Flags
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) :header-rows: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) :widths: 3 1 4
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) * - ``V4L2_CTRL_FLAG_DISABLED``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) - 0x0001
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) - This control is permanently disabled and should be ignored by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) application. Any attempt to change the control will result in an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) ``EINVAL`` error code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) * - ``V4L2_CTRL_FLAG_GRABBED``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) - 0x0002
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) - This control is temporarily unchangeable, for example because
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) another application took over control of the respective resource.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504) Such controls may be displayed specially in a user interface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505) Attempts to change the control may result in an ``EBUSY`` error code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) * - ``V4L2_CTRL_FLAG_READ_ONLY``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) - 0x0004
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508) - This control is permanently readable only. Any attempt to change
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) the control will result in an ``EINVAL`` error code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510) * - ``V4L2_CTRL_FLAG_UPDATE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) - 0x0008
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) - A hint that changing this control may affect the value of other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513) controls within the same control class. Applications should update
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514) their user interface accordingly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515) * - ``V4L2_CTRL_FLAG_INACTIVE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516) - 0x0010
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517) - This control is not applicable to the current configuration and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518) should be displayed accordingly in a user interface. For example
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) the flag may be set on a MPEG audio level 2 bitrate control when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520) MPEG audio encoding level 1 was selected with another control.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) * - ``V4L2_CTRL_FLAG_SLIDER``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522) - 0x0020
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523) - A hint that this control is best represented as a slider-like
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524) element in a user interface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525) * - ``V4L2_CTRL_FLAG_WRITE_ONLY``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526) - 0x0040
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527) - This control is permanently writable only. Any attempt to read the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528) control will result in an ``EACCES`` error code error code. This flag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529) is typically present for relative controls or action controls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530) where writing a value will cause the device to carry out a given
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531) action (e. g. motor control) but no meaningful value can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532) returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533) * - ``V4L2_CTRL_FLAG_VOLATILE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534) - 0x0080
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535) - This control is volatile, which means that the value of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536) control changes continuously. A typical example would be the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537) current gain value if the device is in auto-gain mode. In such a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538) case the hardware calculates the gain value based on the lighting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539) conditions which can change over time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543) Setting a new value for a volatile control will be ignored
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544) unless
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545) :ref:`V4L2_CTRL_FLAG_EXECUTE_ON_WRITE <FLAG_EXECUTE_ON_WRITE>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546) is also set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547) Setting a new value for a volatile control will *never* trigger a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548) :ref:`V4L2_EVENT_CTRL_CH_VALUE <ctrl-changes-flags>` event.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549) * - ``V4L2_CTRL_FLAG_HAS_PAYLOAD``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550) - 0x0100
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551) - This control has a pointer type, so its value has to be accessed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552) using one of the pointer fields of struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553) :c:type:`v4l2_ext_control`. This flag is set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554) for controls that are an array, string, or have a compound type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555) In all cases you have to set a pointer to memory containing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556) payload of the control.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557) * .. _FLAG_EXECUTE_ON_WRITE:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559) - ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560) - 0x0200
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561) - The value provided to the control will be propagated to the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562) even if it remains constant. This is required when the control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563) represents an action on the hardware. For example: clearing an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564) error flag or triggering the flash. All the controls of the type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565) ``V4L2_CTRL_TYPE_BUTTON`` have this flag set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566) * .. _FLAG_MODIFY_LAYOUT:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568) - ``V4L2_CTRL_FLAG_MODIFY_LAYOUT``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569) - 0x0400
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570) - Changing this control value may modify the layout of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571) buffer (for video devices) or the media bus format (for sub-devices).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573) A typical example would be the ``V4L2_CID_ROTATE`` control.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) Note that typically controls with this flag will also set the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576) ``V4L2_CTRL_FLAG_GRABBED`` flag when buffers are allocated or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577) streaming is in progress since most drivers do not support changing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578) the format in that case.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580) Return Value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583) On success 0 is returned, on error -1 and the ``errno`` variable is set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584) appropriately. The generic error codes are described at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585) :ref:`Generic Error Codes <gen-errors>` chapter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587) EINVAL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588) The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id`` is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589) invalid. The struct :ref:`v4l2_querymenu <v4l2-querymenu>` ``id``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590) is invalid or ``index`` is out of range (less than ``minimum`` or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591) greater than ``maximum``) or this particular menu item is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592) supported by the driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594) EACCES
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595) An attempt was made to read a write-only control.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597) .. [#f1]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598) ``V4L2_CTRL_FLAG_DISABLED`` was intended for two purposes: Drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599) can skip predefined controls not supported by the hardware (although
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600) returning ``EINVAL`` would do as well), or disable predefined and private
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601) controls after hardware detection without the trouble of reordering
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602) control arrays and indices (``EINVAL`` cannot be used to skip private
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603) controls because it would prematurely end the enumeration).
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags