0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_QUERYCTRL:
0005
0006 *******************************************************************
0007 ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU
0008 *******************************************************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items
0014
0015 Synopsis
0016 ========
0017
0018 ``int ioctl(int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp)``
0019
0020 .. c:macro:: VIDIOC_QUERY_EXT_CTRL
0021
0022 ``int ioctl(int fd, VIDIOC_QUERY_EXT_CTRL, struct v4l2_query_ext_ctrl *argp)``
0023
0024 .. c:macro:: VIDIOC_QUERYMENU
0025
0026 ``int ioctl(int fd, VIDIOC_QUERYMENU, struct v4l2_querymenu *argp)``
0027
0028 Arguments
0029 =========
0030
0031 ``fd``
0032 File descriptor returned by :c:func:`open()`.
0033
0034 ``argp``
0035 Pointer to struct :c:type:`v4l2_queryctrl`, :c:type:`v4l2_query_ext_ctrl`
0036 or :c:type:`v4l2_querymenu` (depending on the ioctl).
0037
0038 Description
0039 ===========
0040
0041 To query the attributes of a control applications set the ``id`` field
0042 of a struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` and call the
0043 ``VIDIOC_QUERYCTRL`` ioctl with a pointer to this structure. The driver
0044 fills the rest of the structure or returns an ``EINVAL`` error code when the
0045 ``id`` is invalid.
0046
0047 It is possible to enumerate controls by calling ``VIDIOC_QUERYCTRL``
0048 with successive ``id`` values starting from ``V4L2_CID_BASE`` up to and
0049 exclusive ``V4L2_CID_LASTP1``. Drivers may return ``EINVAL`` if a control in
0050 this range is not supported. Further applications can enumerate private
0051 controls, which are not defined in this specification, by starting at
0052 ``V4L2_CID_PRIVATE_BASE`` and incrementing ``id`` until the driver
0053 returns ``EINVAL``.
0054
0055 In both cases, when the driver sets the ``V4L2_CTRL_FLAG_DISABLED`` flag
0056 in the ``flags`` field this control is permanently disabled and should
0057 be ignored by the application. [#f1]_
0058
0059 When the application ORs ``id`` with ``V4L2_CTRL_FLAG_NEXT_CTRL`` the
0060 driver returns the next supported non-compound control, or ``EINVAL`` if
0061 there is none. In addition, the ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` flag
0062 can be specified to enumerate all compound controls (i.e. controls with
0063 type ≥ ``V4L2_CTRL_COMPOUND_TYPES`` and/or array control, in other words
0064 controls that contain more than one value). Specify both
0065 ``V4L2_CTRL_FLAG_NEXT_CTRL`` and ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` in
0066 order to enumerate all controls, compound or not. Drivers which do not
0067 support these flags yet always return ``EINVAL``.
0068
0069 The ``VIDIOC_QUERY_EXT_CTRL`` ioctl was introduced in order to better
0070 support controls that can use compound types, and to expose additional
0071 control information that cannot be returned in struct
0072 :ref:`v4l2_queryctrl <v4l2-queryctrl>` since that structure is full.
0073
0074 ``VIDIOC_QUERY_EXT_CTRL`` is used in the same way as
0075 ``VIDIOC_QUERYCTRL``, except that the ``reserved`` array must be zeroed
0076 as well.
0077
0078 Additional information is required for menu controls: the names of the
0079 menu items. To query them applications set the ``id`` and ``index``
0080 fields of struct :ref:`v4l2_querymenu <v4l2-querymenu>` and call the
0081 ``VIDIOC_QUERYMENU`` ioctl with a pointer to this structure. The driver
0082 fills the rest of the structure or returns an ``EINVAL`` error code when the
0083 ``id`` or ``index`` is invalid. Menu items are enumerated by calling
0084 ``VIDIOC_QUERYMENU`` with successive ``index`` values from struct
0085 :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``minimum`` to ``maximum``,
0086 inclusive.
0087
0088 .. note::
0089
0090 It is possible for ``VIDIOC_QUERYMENU`` to return
0091 an ``EINVAL`` error code for some indices between ``minimum`` and
0092 ``maximum``. In that case that particular menu item is not supported by
0093 this driver. Also note that the ``minimum`` value is not necessarily 0.
0094
0095 See also the examples in :ref:`control`.
0096
0097 .. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.5cm}|
0098
0099 .. _v4l2-queryctrl:
0100
0101 .. cssclass:: longtable
0102
0103 .. flat-table:: struct v4l2_queryctrl
0104 :header-rows: 0
0105 :stub-columns: 0
0106 :widths: 1 1 2
0107
0108 * - __u32
0109 - ``id``
0110 - Identifies the control, set by the application. See
0111 :ref:`control-id` for predefined IDs. When the ID is ORed with
0112 V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and
0113 returns the first control with a higher ID. Drivers which do not
0114 support this flag yet always return an ``EINVAL`` error code.
0115 * - __u32
0116 - ``type``
0117 - Type of control, see :c:type:`v4l2_ctrl_type`.
0118 * - __u8
0119 - ``name``\ [32]
0120 - Name of the control, a NUL-terminated ASCII string. This
0121 information is intended for the user.
0122 * - __s32
0123 - ``minimum``
0124 - Minimum value, inclusive. This field gives a lower bound for the
0125 control. See enum :c:type:`v4l2_ctrl_type` how
0126 the minimum value is to be used for each possible control type.
0127 Note that this a signed 32-bit value.
0128 * - __s32
0129 - ``maximum``
0130 - Maximum value, inclusive. This field gives an upper bound for the
0131 control. See enum :c:type:`v4l2_ctrl_type` how
0132 the maximum value is to be used for each possible control type.
0133 Note that this a signed 32-bit value.
0134 * - __s32
0135 - ``step``
0136 - This field gives a step size for the control. See enum
0137 :c:type:`v4l2_ctrl_type` how the step value is
0138 to be used for each possible control type. Note that this an
0139 unsigned 32-bit value.
0140
0141 Generally drivers should not scale hardware control values. It may
0142 be necessary for example when the ``name`` or ``id`` imply a
0143 particular unit and the hardware actually accepts only multiples
0144 of said unit. If so, drivers must take care values are properly
0145 rounded when scaling, such that errors will not accumulate on
0146 repeated read-write cycles.
0147
0148 This field gives the smallest change of an integer control
0149 actually affecting hardware. Often the information is needed when
0150 the user can change controls by keyboard or GUI buttons, rather
0151 than a slider. When for example a hardware register accepts values
0152 0-511 and the driver reports 0-65535, step should be 128.
0153
0154 Note that although signed, the step value is supposed to be always
0155 positive.
0156 * - __s32
0157 - ``default_value``
0158 - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_BOOLEAN``,
0159 ``_BITMASK``, ``_MENU`` or ``_INTEGER_MENU`` control. Not valid
0160 for other types of controls.
0161
0162 .. note::
0163
0164 Drivers reset controls to their default value only when
0165 the driver is first loaded, never afterwards.
0166 * - __u32
0167 - ``flags``
0168 - Control flags, see :ref:`control-flags`.
0169 * - __u32
0170 - ``reserved``\ [2]
0171 - Reserved for future extensions. Drivers must set the array to
0172 zero.
0173
0174
0175 .. tabularcolumns:: |p{1.2cm}|p{5.5cm}|p{10.6cm}|
0176
0177 .. _v4l2-query-ext-ctrl:
0178
0179 .. cssclass:: longtable
0180
0181 .. flat-table:: struct v4l2_query_ext_ctrl
0182 :header-rows: 0
0183 :stub-columns: 0
0184 :widths: 1 1 2
0185
0186 * - __u32
0187 - ``id``
0188 - Identifies the control, set by the application. See
0189 :ref:`control-id` for predefined IDs. When the ID is ORed with
0190 ``V4L2_CTRL_FLAG_NEXT_CTRL`` the driver clears the flag and
0191 returns the first non-compound control with a higher ID. When the
0192 ID is ORed with ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` the driver clears
0193 the flag and returns the first compound control with a higher ID.
0194 Set both to get the first control (compound or not) with a higher
0195 ID.
0196 * - __u32
0197 - ``type``
0198 - Type of control, see :c:type:`v4l2_ctrl_type`.
0199 * - char
0200 - ``name``\ [32]
0201 - Name of the control, a NUL-terminated ASCII string. This
0202 information is intended for the user.
0203 * - __s64
0204 - ``minimum``
0205 - Minimum value, inclusive. This field gives a lower bound for the
0206 control. See enum :c:type:`v4l2_ctrl_type` how
0207 the minimum value is to be used for each possible control type.
0208 Note that this a signed 64-bit value.
0209 * - __s64
0210 - ``maximum``
0211 - Maximum value, inclusive. This field gives an upper bound for the
0212 control. See enum :c:type:`v4l2_ctrl_type` how
0213 the maximum value is to be used for each possible control type.
0214 Note that this a signed 64-bit value.
0215 * - __u64
0216 - ``step``
0217 - This field gives a step size for the control. See enum
0218 :c:type:`v4l2_ctrl_type` how the step value is
0219 to be used for each possible control type. Note that this an
0220 unsigned 64-bit value.
0221
0222 Generally drivers should not scale hardware control values. It may
0223 be necessary for example when the ``name`` or ``id`` imply a
0224 particular unit and the hardware actually accepts only multiples
0225 of said unit. If so, drivers must take care values are properly
0226 rounded when scaling, such that errors will not accumulate on
0227 repeated read-write cycles.
0228
0229 This field gives the smallest change of an integer control
0230 actually affecting hardware. Often the information is needed when
0231 the user can change controls by keyboard or GUI buttons, rather
0232 than a slider. When for example a hardware register accepts values
0233 0-511 and the driver reports 0-65535, step should be 128.
0234 * - __s64
0235 - ``default_value``
0236 - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_INTEGER64``,
0237 ``_BOOLEAN``, ``_BITMASK``, ``_MENU``, ``_INTEGER_MENU``, ``_U8``
0238 or ``_U16`` control. Not valid for other types of controls.
0239
0240 .. note::
0241
0242 Drivers reset controls to their default value only when
0243 the driver is first loaded, never afterwards.
0244 * - __u32
0245 - ``flags``
0246 - Control flags, see :ref:`control-flags`.
0247 * - __u32
0248 - ``elem_size``
0249 - The size in bytes of a single element of the array. Given a char
0250 pointer ``p`` to a 3-dimensional array you can find the position
0251 of cell ``(z, y, x)`` as follows:
0252 ``p + ((z * dims[1] + y) * dims[0] + x) * elem_size``.
0253 ``elem_size`` is always valid, also when the control isn't an
0254 array. For string controls ``elem_size`` is equal to
0255 ``maximum + 1``.
0256 * - __u32
0257 - ``elems``
0258 - The number of elements in the N-dimensional array. If this control
0259 is not an array, then ``elems`` is 1. The ``elems`` field can
0260 never be 0.
0261 * - __u32
0262 - ``nr_of_dims``
0263 - The number of dimension in the N-dimensional array. If this
0264 control is not an array, then this field is 0.
0265 * - __u32
0266 - ``dims[V4L2_CTRL_MAX_DIMS]``
0267 - The size of each dimension. The first ``nr_of_dims`` elements of
0268 this array must be non-zero, all remaining elements must be zero.
0269 * - __u32
0270 - ``reserved``\ [32]
0271 - Reserved for future extensions. Applications and drivers must set
0272 the array to zero.
0273
0274
0275 .. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.1cm}|
0276
0277 .. _v4l2-querymenu:
0278
0279 .. flat-table:: struct v4l2_querymenu
0280 :header-rows: 0
0281 :stub-columns: 0
0282 :widths: 1 1 2
0283
0284 * - __u32
0285 - ``id``
0286 - Identifies the control, set by the application from the respective
0287 struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id``.
0288 * - __u32
0289 - ``index``
0290 - Index of the menu item, starting at zero, set by the application.
0291 * - union {
0292 - (anonymous)
0293 * - __u8
0294 - ``name``\ [32]
0295 - Name of the menu item, a NUL-terminated ASCII string. This
0296 information is intended for the user. This field is valid for
0297 ``V4L2_CTRL_TYPE_MENU`` type controls.
0298 * - __s64
0299 - ``value``
0300 - Value of the integer menu item. This field is valid for
0301 ``V4L2_CTRL_TYPE_INTEGER_MENU`` type controls.
0302 * - }
0303 -
0304 * - __u32
0305 - ``reserved``
0306 - Reserved for future extensions. Drivers must set the array to
0307 zero.
0308
0309 .. c:type:: v4l2_ctrl_type
0310
0311 .. raw:: latex
0312
0313 \footnotesize
0314
0315 .. tabularcolumns:: |p{6.5cm}|p{1.5cm}|p{1.1cm}|p{1.5cm}|p{6.8cm}|
0316
0317 .. cssclass:: longtable
0318
0319 .. flat-table:: enum v4l2_ctrl_type
0320 :header-rows: 1
0321 :stub-columns: 0
0322 :widths: 30 5 5 5 55
0323
0324 * - Type
0325 - ``minimum``
0326 - ``step``
0327 - ``maximum``
0328 - Description
0329 * - ``V4L2_CTRL_TYPE_INTEGER``
0330 - any
0331 - any
0332 - any
0333 - An integer-valued control ranging from minimum to maximum
0334 inclusive. The step value indicates the increment between values.
0335 * - ``V4L2_CTRL_TYPE_BOOLEAN``
0336 - 0
0337 - 1
0338 - 1
0339 - A boolean-valued control. Zero corresponds to "disabled", and one
0340 means "enabled".
0341 * - ``V4L2_CTRL_TYPE_MENU``
0342 - ≥ 0
0343 - 1
0344 - N-1
0345 - The control has a menu of N choices. The names of the menu items
0346 can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl.
0347 * - ``V4L2_CTRL_TYPE_INTEGER_MENU``
0348 - ≥ 0
0349 - 1
0350 - N-1
0351 - The control has a menu of N choices. The values of the menu items
0352 can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. This is
0353 similar to ``V4L2_CTRL_TYPE_MENU`` except that instead of strings,
0354 the menu items are signed 64-bit integers.
0355 * - ``V4L2_CTRL_TYPE_BITMASK``
0356 - 0
0357 - n/a
0358 - any
0359 - A bitmask field. The maximum value is the set of bits that can be
0360 used, all other bits are to be 0. The maximum value is interpreted
0361 as a __u32, allowing the use of bit 31 in the bitmask.
0362 * - ``V4L2_CTRL_TYPE_BUTTON``
0363 - 0
0364 - 0
0365 - 0
0366 - A control which performs an action when set. Drivers must ignore
0367 the value passed with ``VIDIOC_S_CTRL`` and return an ``EACCES`` error
0368 code on a ``VIDIOC_G_CTRL`` attempt.
0369 * - ``V4L2_CTRL_TYPE_INTEGER64``
0370 - any
0371 - any
0372 - any
0373 - A 64-bit integer valued control. Minimum, maximum and step size
0374 cannot be queried using ``VIDIOC_QUERYCTRL``. Only
0375 ``VIDIOC_QUERY_EXT_CTRL`` can retrieve the 64-bit min/max/step
0376 values, they should be interpreted as n/a when using
0377 ``VIDIOC_QUERYCTRL``.
0378 * - ``V4L2_CTRL_TYPE_STRING``
0379 - ≥ 0
0380 - ≥ 1
0381 - ≥ 0
0382 - The minimum and maximum string lengths. The step size means that
0383 the string must be (minimum + N * step) characters long for N ≥ 0.
0384 These lengths do not include the terminating zero, so in order to
0385 pass a string of length 8 to
0386 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you need to
0387 set the ``size`` field of struct
0388 :c:type:`v4l2_ext_control` to 9. For
0389 :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you can set
0390 the ``size`` field to ``maximum`` + 1. Which character encoding is
0391 used will depend on the string control itself and should be part
0392 of the control documentation.
0393 * - ``V4L2_CTRL_TYPE_CTRL_CLASS``
0394 - n/a
0395 - n/a
0396 - n/a
0397 - This is not a control. When ``VIDIOC_QUERYCTRL`` is called with a
0398 control ID equal to a control class code (see :ref:`ctrl-class`)
0399 + 1, the ioctl returns the name of the control class and this
0400 control type. Older drivers which do not support this feature
0401 return an ``EINVAL`` error code.
0402 * - ``V4L2_CTRL_TYPE_U8``
0403 - any
0404 - any
0405 - any
0406 - An unsigned 8-bit valued control ranging from minimum to maximum
0407 inclusive. The step value indicates the increment between values.
0408 * - ``V4L2_CTRL_TYPE_U16``
0409 - any
0410 - any
0411 - any
0412 - An unsigned 16-bit valued control ranging from minimum to maximum
0413 inclusive. The step value indicates the increment between values.
0414 * - ``V4L2_CTRL_TYPE_U32``
0415 - any
0416 - any
0417 - any
0418 - An unsigned 32-bit valued control ranging from minimum to maximum
0419 inclusive. The step value indicates the increment between values.
0420 * - ``V4L2_CTRL_TYPE_MPEG2_QUANTISATION``
0421 - n/a
0422 - n/a
0423 - n/a
0424 - A struct :c:type:`v4l2_ctrl_mpeg2_quantisation`, containing MPEG-2
0425 quantisation matrices for stateless video decoders.
0426 * - ``V4L2_CTRL_TYPE_MPEG2_SEQUENCE``
0427 - n/a
0428 - n/a
0429 - n/a
0430 - A struct :c:type:`v4l2_ctrl_mpeg2_sequence`, containing MPEG-2
0431 sequence parameters for stateless video decoders.
0432 * - ``V4L2_CTRL_TYPE_MPEG2_PICTURE``
0433 - n/a
0434 - n/a
0435 - n/a
0436 - A struct :c:type:`v4l2_ctrl_mpeg2_picture`, containing MPEG-2
0437 picture parameters for stateless video decoders.
0438 * - ``V4L2_CTRL_TYPE_AREA``
0439 - n/a
0440 - n/a
0441 - n/a
0442 - A struct :c:type:`v4l2_area`, containing the width and the height
0443 of a rectangular area. Units depend on the use case.
0444 * - ``V4L2_CTRL_TYPE_H264_SPS``
0445 - n/a
0446 - n/a
0447 - n/a
0448 - A struct :c:type:`v4l2_ctrl_h264_sps`, containing H264
0449 sequence parameters for stateless video decoders.
0450 * - ``V4L2_CTRL_TYPE_H264_PPS``
0451 - n/a
0452 - n/a
0453 - n/a
0454 - A struct :c:type:`v4l2_ctrl_h264_pps`, containing H264
0455 picture parameters for stateless video decoders.
0456 * - ``V4L2_CTRL_TYPE_H264_SCALING_MATRIX``
0457 - n/a
0458 - n/a
0459 - n/a
0460 - A struct :c:type:`v4l2_ctrl_h264_scaling_matrix`, containing H264
0461 scaling matrices for stateless video decoders.
0462 * - ``V4L2_CTRL_TYPE_H264_SLICE_PARAMS``
0463 - n/a
0464 - n/a
0465 - n/a
0466 - A struct :c:type:`v4l2_ctrl_h264_slice_params`, containing H264
0467 slice parameters for stateless video decoders.
0468 * - ``V4L2_CTRL_TYPE_H264_DECODE_PARAMS``
0469 - n/a
0470 - n/a
0471 - n/a
0472 - A struct :c:type:`v4l2_ctrl_h264_decode_params`, containing H264
0473 decode parameters for stateless video decoders.
0474 * - ``V4L2_CTRL_TYPE_FWHT_PARAMS``
0475 - n/a
0476 - n/a
0477 - n/a
0478 - A struct :c:type:`v4l2_ctrl_fwht_params`, containing FWHT
0479 parameters for stateless video decoders.
0480 * - ``V4L2_CTRL_TYPE_HEVC_SPS``
0481 - n/a
0482 - n/a
0483 - n/a
0484 - A struct :c:type:`v4l2_ctrl_hevc_sps`, containing HEVC Sequence
0485 Parameter Set for stateless video decoders.
0486 * - ``V4L2_CTRL_TYPE_HEVC_PPS``
0487 - n/a
0488 - n/a
0489 - n/a
0490 - A struct :c:type:`v4l2_ctrl_hevc_pps`, containing HEVC Picture
0491 Parameter Set for stateless video decoders.
0492 * - ``V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS``
0493 - n/a
0494 - n/a
0495 - n/a
0496 - A struct :c:type:`v4l2_ctrl_hevc_slice_params`, containing HEVC
0497 slice parameters for stateless video decoders.
0498 * - ``V4L2_CTRL_TYPE_HEVC_SCALING_MATRIX``
0499 - n/a
0500 - n/a
0501 - n/a
0502 - A struct :c:type:`v4l2_ctrl_hevc_scaling_matrix`, containing HEVC
0503 scaling matrix for stateless video decoders.
0504 * - ``V4L2_CTRL_TYPE_VP8_FRAME``
0505 - n/a
0506 - n/a
0507 - n/a
0508 - A struct :c:type:`v4l2_ctrl_vp8_frame`, containing VP8
0509 frame parameters for stateless video decoders.
0510 * - ``V4L2_CTRL_TYPE_HEVC_DECODE_PARAMS``
0511 - n/a
0512 - n/a
0513 - n/a
0514 - A struct :c:type:`v4l2_ctrl_hevc_decode_params`, containing HEVC
0515 decoding parameters for stateless video decoders.
0516 * - ``V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR``
0517 - n/a
0518 - n/a
0519 - n/a
0520 - A struct :c:type:`v4l2_ctrl_vp9_compressed_hdr`, containing VP9
0521 probabilities updates for stateless video decoders.
0522 * - ``V4L2_CTRL_TYPE_VP9_FRAME``
0523 - n/a
0524 - n/a
0525 - n/a
0526 - A struct :c:type:`v4l2_ctrl_vp9_frame`, containing VP9
0527 frame decode parameters for stateless video decoders.
0528
0529 .. raw:: latex
0530
0531 \normalsize
0532
0533 .. tabularcolumns:: |p{7.3cm}|p{1.8cm}|p{8.2cm}|
0534
0535 .. cssclass:: longtable
0536
0537 .. _control-flags:
0538
0539 .. flat-table:: Control Flags
0540 :header-rows: 0
0541 :stub-columns: 0
0542 :widths: 3 1 4
0543
0544 * - ``V4L2_CTRL_FLAG_DISABLED``
0545 - 0x0001
0546 - This control is permanently disabled and should be ignored by the
0547 application. Any attempt to change the control will result in an
0548 ``EINVAL`` error code.
0549 * - ``V4L2_CTRL_FLAG_GRABBED``
0550 - 0x0002
0551 - This control is temporarily unchangeable, for example because
0552 another application took over control of the respective resource.
0553 Such controls may be displayed specially in a user interface.
0554 Attempts to change the control may result in an ``EBUSY`` error code.
0555 * - ``V4L2_CTRL_FLAG_READ_ONLY``
0556 - 0x0004
0557 - This control is permanently readable only. Any attempt to change
0558 the control will result in an ``EINVAL`` error code.
0559 * - ``V4L2_CTRL_FLAG_UPDATE``
0560 - 0x0008
0561 - A hint that changing this control may affect the value of other
0562 controls within the same control class. Applications should update
0563 their user interface accordingly.
0564 * - ``V4L2_CTRL_FLAG_INACTIVE``
0565 - 0x0010
0566 - This control is not applicable to the current configuration and
0567 should be displayed accordingly in a user interface. For example
0568 the flag may be set on a MPEG audio level 2 bitrate control when
0569 MPEG audio encoding level 1 was selected with another control.
0570 * - ``V4L2_CTRL_FLAG_SLIDER``
0571 - 0x0020
0572 - A hint that this control is best represented as a slider-like
0573 element in a user interface.
0574 * - ``V4L2_CTRL_FLAG_WRITE_ONLY``
0575 - 0x0040
0576 - This control is permanently writable only. Any attempt to read the
0577 control will result in an ``EACCES`` error code error code. This flag
0578 is typically present for relative controls or action controls
0579 where writing a value will cause the device to carry out a given
0580 action (e. g. motor control) but no meaningful value can be
0581 returned.
0582 * - ``V4L2_CTRL_FLAG_VOLATILE``
0583 - 0x0080
0584 - This control is volatile, which means that the value of the
0585 control changes continuously. A typical example would be the
0586 current gain value if the device is in auto-gain mode. In such a
0587 case the hardware calculates the gain value based on the lighting
0588 conditions which can change over time.
0589
0590 .. note::
0591
0592 Setting a new value for a volatile control will be ignored
0593 unless
0594 :ref:`V4L2_CTRL_FLAG_EXECUTE_ON_WRITE <FLAG_EXECUTE_ON_WRITE>`
0595 is also set.
0596 Setting a new value for a volatile control will *never* trigger a
0597 :ref:`V4L2_EVENT_CTRL_CH_VALUE <ctrl-changes-flags>` event.
0598 * - ``V4L2_CTRL_FLAG_HAS_PAYLOAD``
0599 - 0x0100
0600 - This control has a pointer type, so its value has to be accessed
0601 using one of the pointer fields of struct
0602 :c:type:`v4l2_ext_control`. This flag is set
0603 for controls that are an array, string, or have a compound type.
0604 In all cases you have to set a pointer to memory containing the
0605 payload of the control.
0606 * .. _FLAG_EXECUTE_ON_WRITE:
0607
0608 - ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
0609 - 0x0200
0610 - The value provided to the control will be propagated to the driver
0611 even if it remains constant. This is required when the control
0612 represents an action on the hardware. For example: clearing an
0613 error flag or triggering the flash. All the controls of the type
0614 ``V4L2_CTRL_TYPE_BUTTON`` have this flag set.
0615 * .. _FLAG_MODIFY_LAYOUT:
0616
0617 - ``V4L2_CTRL_FLAG_MODIFY_LAYOUT``
0618 - 0x0400
0619 - Changing this control value may modify the layout of the
0620 buffer (for video devices) or the media bus format (for sub-devices).
0621
0622 A typical example would be the ``V4L2_CID_ROTATE`` control.
0623
0624 Note that typically controls with this flag will also set the
0625 ``V4L2_CTRL_FLAG_GRABBED`` flag when buffers are allocated or
0626 streaming is in progress since most drivers do not support changing
0627 the format in that case.
0628 * - ``V4L2_CTRL_FLAG_DYNAMIC_ARRAY``
0629 - 0x0800
0630 - This control is a dynamically sized 1-dimensional array. It
0631 behaves the same as a regular array, except that the number
0632 of elements as reported by the ``elems`` field is between 1 and
0633 ``dims[0]``. So setting the control with a differently sized
0634 array will change the ``elems`` field when the control is
0635 queried afterwards.
0636
0637 Return Value
0638 ============
0639
0640 On success 0 is returned, on error -1 and the ``errno`` variable is set
0641 appropriately. The generic error codes are described at the
0642 :ref:`Generic Error Codes <gen-errors>` chapter.
0643
0644 EINVAL
0645 The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id`` is
0646 invalid. The struct :ref:`v4l2_querymenu <v4l2-querymenu>` ``id``
0647 is invalid or ``index`` is out of range (less than ``minimum`` or
0648 greater than ``maximum``) or this particular menu item is not
0649 supported by the driver.
0650
0651 EACCES
0652 An attempt was made to read a write-only control.
0653
0654 .. [#f1]
0655 ``V4L2_CTRL_FLAG_DISABLED`` was intended for two purposes: Drivers
0656 can skip predefined controls not supported by the hardware (although
0657 returning ``EINVAL`` would do as well), or disable predefined and private
0658 controls after hardware detection without the trouble of reordering
0659 control arrays and indices (``EINVAL`` cannot be used to skip private
0660 controls because it would prematurely end the enumeration).
