685 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _VIDIOC_QUERYCTRL:5 6*******************************************************************7ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU8*******************************************************************9 10Name11====12 13VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items14 15Synopsis16========17 18``int ioctl(int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp)``19 20.. c:macro:: VIDIOC_QUERY_EXT_CTRL21 22``int ioctl(int fd, VIDIOC_QUERY_EXT_CTRL, struct v4l2_query_ext_ctrl *argp)``23 24.. c:macro:: VIDIOC_QUERYMENU25 26``int ioctl(int fd, VIDIOC_QUERYMENU, struct v4l2_querymenu *argp)``27 28Arguments29=========30 31``fd``32 File descriptor returned by :c:func:`open()`.33 34``argp``35 Pointer to struct :c:type:`v4l2_queryctrl`, :c:type:`v4l2_query_ext_ctrl`36 or :c:type:`v4l2_querymenu` (depending on the ioctl).37 38Description39===========40 41To query the attributes of a control applications set the ``id`` field42of a struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` and call the43``VIDIOC_QUERYCTRL`` ioctl with a pointer to this structure. The driver44fills the rest of the structure or returns an ``EINVAL`` error code when the45``id`` is invalid.46 47It is possible to enumerate controls by calling ``VIDIOC_QUERYCTRL``48with successive ``id`` values starting from ``V4L2_CID_BASE`` up to and49exclusive ``V4L2_CID_LASTP1``. Drivers may return ``EINVAL`` if a control in50this range is not supported. Further applications can enumerate private51controls, which are not defined in this specification, by starting at52``V4L2_CID_PRIVATE_BASE`` and incrementing ``id`` until the driver53returns ``EINVAL``.54 55In both cases, when the driver sets the ``V4L2_CTRL_FLAG_DISABLED`` flag56in the ``flags`` field this control is permanently disabled and should57be ignored by the application. [#f1]_58 59When the application ORs ``id`` with ``V4L2_CTRL_FLAG_NEXT_CTRL`` the60driver returns the next supported non-compound control, or ``EINVAL`` if61there is none. In addition, the ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` flag62can be specified to enumerate all compound controls (i.e. controls with63type ≥ ``V4L2_CTRL_COMPOUND_TYPES`` and/or array control, in other words64controls that contain more than one value). Specify both65``V4L2_CTRL_FLAG_NEXT_CTRL`` and ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` in66order to enumerate all controls, compound or not. Drivers which do not67support these flags yet always return ``EINVAL``.68 69The ``VIDIOC_QUERY_EXT_CTRL`` ioctl was introduced in order to better70support controls that can use compound types, and to expose additional71control information that cannot be returned in struct72:ref:`v4l2_queryctrl <v4l2-queryctrl>` since that structure is full.73 74``VIDIOC_QUERY_EXT_CTRL`` is used in the same way as75``VIDIOC_QUERYCTRL``, except that the ``reserved`` array must be zeroed76as well.77 78Additional information is required for menu controls: the names of the79menu items. To query them applications set the ``id`` and ``index``80fields of struct :ref:`v4l2_querymenu <v4l2-querymenu>` and call the81``VIDIOC_QUERYMENU`` ioctl with a pointer to this structure. The driver82fills the rest of the structure or returns an ``EINVAL`` error code when the83``id`` or ``index`` is invalid. Menu items are enumerated by calling84``VIDIOC_QUERYMENU`` with successive ``index`` values from struct85:ref:`v4l2_queryctrl <v4l2-queryctrl>` ``minimum`` to ``maximum``,86inclusive.87 88.. note::89 90 It is possible for ``VIDIOC_QUERYMENU`` to return91 an ``EINVAL`` error code for some indices between ``minimum`` and92 ``maximum``. In that case that particular menu item is not supported by93 this driver. Also note that the ``minimum`` value is not necessarily 0.94 95See also the examples in :ref:`control`.96 97.. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.5cm}|98 99.. _v4l2-queryctrl:100 101.. cssclass:: longtable102 103.. flat-table:: struct v4l2_queryctrl104 :header-rows: 0105 :stub-columns: 0106 :widths: 1 1 2107 108 * - __u32109 - ``id``110 - Identifies the control, set by the application. See111 :ref:`control-id` for predefined IDs. When the ID is ORed with112 V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and113 returns the first control with a higher ID. Drivers which do not114 support this flag yet always return an ``EINVAL`` error code.115 * - __u32116 - ``type``117 - Type of control, see :c:type:`v4l2_ctrl_type`.118 * - __u8119 - ``name``\ [32]120 - Name of the control, a NUL-terminated ASCII string. This121 information is intended for the user.122 * - __s32123 - ``minimum``124 - Minimum value, inclusive. This field gives a lower bound for the125 control. See enum :c:type:`v4l2_ctrl_type` how126 the minimum value is to be used for each possible control type.127 Note that this a signed 32-bit value.128 * - __s32129 - ``maximum``130 - Maximum value, inclusive. This field gives an upper bound for the131 control. See enum :c:type:`v4l2_ctrl_type` how132 the maximum value is to be used for each possible control type.133 Note that this a signed 32-bit value.134 * - __s32135 - ``step``136 - This field gives a step size for the control. See enum137 :c:type:`v4l2_ctrl_type` how the step value is138 to be used for each possible control type. Note that this an139 unsigned 32-bit value.140 141 Generally drivers should not scale hardware control values. It may142 be necessary for example when the ``name`` or ``id`` imply a143 particular unit and the hardware actually accepts only multiples144 of said unit. If so, drivers must take care values are properly145 rounded when scaling, such that errors will not accumulate on146 repeated read-write cycles.147 148 This field gives the smallest change of an integer control149 actually affecting hardware. Often the information is needed when150 the user can change controls by keyboard or GUI buttons, rather151 than a slider. When for example a hardware register accepts values152 0-511 and the driver reports 0-65535, step should be 128.153 154 Note that although signed, the step value is supposed to be always155 positive.156 * - __s32157 - ``default_value``158 - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_BOOLEAN``,159 ``_BITMASK``, ``_MENU`` or ``_INTEGER_MENU`` control. Not valid160 for other types of controls.161 162 .. note::163 164 Drivers reset controls to their default value only when165 the driver is first loaded, never afterwards.166 * - __u32167 - ``flags``168 - Control flags, see :ref:`control-flags`.169 * - __u32170 - ``reserved``\ [2]171 - Reserved for future extensions. Drivers must set the array to172 zero.173 174 175.. tabularcolumns:: |p{1.2cm}|p{5.5cm}|p{10.6cm}|176 177.. _v4l2-query-ext-ctrl:178 179.. cssclass:: longtable180 181.. flat-table:: struct v4l2_query_ext_ctrl182 :header-rows: 0183 :stub-columns: 0184 :widths: 1 1 2185 186 * - __u32187 - ``id``188 - Identifies the control, set by the application. See189 :ref:`control-id` for predefined IDs. When the ID is ORed with190 ``V4L2_CTRL_FLAG_NEXT_CTRL`` the driver clears the flag and191 returns the first non-compound control with a higher ID. When the192 ID is ORed with ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` the driver clears193 the flag and returns the first compound control with a higher ID.194 Set both to get the first control (compound or not) with a higher195 ID.196 * - __u32197 - ``type``198 - Type of control, see :c:type:`v4l2_ctrl_type`.199 * - char200 - ``name``\ [32]201 - Name of the control, a NUL-terminated ASCII string. This202 information is intended for the user.203 * - __s64204 - ``minimum``205 - Minimum value, inclusive. This field gives a lower bound for the206 control. See enum :c:type:`v4l2_ctrl_type` how207 the minimum value is to be used for each possible control type.208 Note that this a signed 64-bit value.209 * - __s64210 - ``maximum``211 - Maximum value, inclusive. This field gives an upper bound for the212 control. See enum :c:type:`v4l2_ctrl_type` how213 the maximum value is to be used for each possible control type.214 Note that this a signed 64-bit value.215 * - __u64216 - ``step``217 - This field gives a step size for the control. See enum218 :c:type:`v4l2_ctrl_type` how the step value is219 to be used for each possible control type. Note that this an220 unsigned 64-bit value.221 222 Generally drivers should not scale hardware control values. It may223 be necessary for example when the ``name`` or ``id`` imply a224 particular unit and the hardware actually accepts only multiples225 of said unit. If so, drivers must take care values are properly226 rounded when scaling, such that errors will not accumulate on227 repeated read-write cycles.228 229 This field gives the smallest change of an integer control230 actually affecting hardware. Often the information is needed when231 the user can change controls by keyboard or GUI buttons, rather232 than a slider. When for example a hardware register accepts values233 0-511 and the driver reports 0-65535, step should be 128.234 * - __s64235 - ``default_value``236 - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_INTEGER64``,237 ``_BOOLEAN``, ``_BITMASK``, ``_MENU``, ``_INTEGER_MENU``, ``_U8``238 or ``_U16`` control. Not valid for other types of controls.239 240 .. note::241 242 Drivers reset controls to their default value only when243 the driver is first loaded, never afterwards.244 * - __u32245 - ``flags``246 - Control flags, see :ref:`control-flags`.247 * - __u32248 - ``elem_size``249 - The size in bytes of a single element of the array. Given a char250 pointer ``p`` to a 3-dimensional array you can find the position251 of cell ``(z, y, x)`` as follows:252 ``p + ((z * dims[1] + y) * dims[0] + x) * elem_size``.253 ``elem_size`` is always valid, also when the control isn't an254 array. For string controls ``elem_size`` is equal to255 ``maximum + 1``.256 * - __u32257 - ``elems``258 - The number of elements in the N-dimensional array. If this control259 is not an array, then ``elems`` is 1. The ``elems`` field can260 never be 0.261 * - __u32262 - ``nr_of_dims``263 - The number of dimension in the N-dimensional array. If this264 control is not an array, then this field is 0.265 * - __u32266 - ``dims[V4L2_CTRL_MAX_DIMS]``267 - The size of each dimension. The first ``nr_of_dims`` elements of268 this array must be non-zero, all remaining elements must be zero.269 * - __u32270 - ``reserved``\ [32]271 - Reserved for future extensions. Applications and drivers must set272 the array to zero.273 274 275.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.1cm}|276 277.. _v4l2-querymenu:278 279.. flat-table:: struct v4l2_querymenu280 :header-rows: 0281 :stub-columns: 0282 :widths: 1 1 2283 284 * - __u32285 - ``id``286 - Identifies the control, set by the application from the respective287 struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id``.288 * - __u32289 - ``index``290 - Index of the menu item, starting at zero, set by the application.291 * - union {292 - (anonymous)293 * - __u8294 - ``name``\ [32]295 - Name of the menu item, a NUL-terminated ASCII string. This296 information is intended for the user. This field is valid for297 ``V4L2_CTRL_TYPE_MENU`` type controls.298 * - __s64299 - ``value``300 - Value of the integer menu item. This field is valid for301 ``V4L2_CTRL_TYPE_INTEGER_MENU`` type controls.302 * - }303 -304 * - __u32305 - ``reserved``306 - Reserved for future extensions. Drivers must set the array to307 zero.308 309.. c:type:: v4l2_ctrl_type310 311.. raw:: latex312 313 \footnotesize314 315.. tabularcolumns:: |p{6.5cm}|p{1.5cm}|p{1.1cm}|p{1.5cm}|p{6.8cm}|316 317.. cssclass:: longtable318 319.. flat-table:: enum v4l2_ctrl_type320 :header-rows: 1321 :stub-columns: 0322 :widths: 30 5 5 5 55323 324 * - Type325 - ``minimum``326 - ``step``327 - ``maximum``328 - Description329 * - ``V4L2_CTRL_TYPE_INTEGER``330 - any331 - any332 - any333 - An integer-valued control ranging from minimum to maximum334 inclusive. The step value indicates the increment between values.335 * - ``V4L2_CTRL_TYPE_BOOLEAN``336 - 0337 - 1338 - 1339 - A boolean-valued control. Zero corresponds to "disabled", and one340 means "enabled".341 * - ``V4L2_CTRL_TYPE_MENU``342 - ≥ 0343 - 1344 - N-1345 - The control has a menu of N choices. The names of the menu items346 can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl.347 * - ``V4L2_CTRL_TYPE_INTEGER_MENU``348 - ≥ 0349 - 1350 - N-1351 - The control has a menu of N choices. The values of the menu items352 can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. This is353 similar to ``V4L2_CTRL_TYPE_MENU`` except that instead of strings,354 the menu items are signed 64-bit integers.355 * - ``V4L2_CTRL_TYPE_BITMASK``356 - 0357 - n/a358 - any359 - A bitmask field. The maximum value is the set of bits that can be360 used, all other bits are to be 0. The maximum value is interpreted361 as a __u32, allowing the use of bit 31 in the bitmask.362 * - ``V4L2_CTRL_TYPE_BUTTON``363 - 0364 - 0365 - 0366 - A control which performs an action when set. Drivers must ignore367 the value passed with ``VIDIOC_S_CTRL`` and return an ``EACCES`` error368 code on a ``VIDIOC_G_CTRL`` attempt.369 * - ``V4L2_CTRL_TYPE_INTEGER64``370 - any371 - any372 - any373 - A 64-bit integer valued control. Minimum, maximum and step size374 cannot be queried using ``VIDIOC_QUERYCTRL``. Only375 ``VIDIOC_QUERY_EXT_CTRL`` can retrieve the 64-bit min/max/step376 values, they should be interpreted as n/a when using377 ``VIDIOC_QUERYCTRL``.378 * - ``V4L2_CTRL_TYPE_STRING``379 - ≥ 0380 - ≥ 1381 - ≥ 0382 - The minimum and maximum string lengths. The step size means that383 the string must be (minimum + N * step) characters long for N ≥ 0.384 These lengths do not include the terminating zero, so in order to385 pass a string of length 8 to386 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you need to387 set the ``size`` field of struct388 :c:type:`v4l2_ext_control` to 9. For389 :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you can set390 the ``size`` field to ``maximum`` + 1. Which character encoding is391 used will depend on the string control itself and should be part392 of the control documentation.393 * - ``V4L2_CTRL_TYPE_CTRL_CLASS``394 - n/a395 - n/a396 - n/a397 - This is not a control. When ``VIDIOC_QUERYCTRL`` is called with a398 control ID equal to a control class code (see :ref:`ctrl-class`)399 + 1, the ioctl returns the name of the control class and this400 control type. Older drivers which do not support this feature401 return an ``EINVAL`` error code.402 * - ``V4L2_CTRL_TYPE_U8``403 - any404 - any405 - any406 - An unsigned 8-bit valued control ranging from minimum to maximum407 inclusive. The step value indicates the increment between values.408 * - ``V4L2_CTRL_TYPE_U16``409 - any410 - any411 - any412 - An unsigned 16-bit valued control ranging from minimum to maximum413 inclusive. The step value indicates the increment between values.414 * - ``V4L2_CTRL_TYPE_U32``415 - any416 - any417 - any418 - An unsigned 32-bit valued control ranging from minimum to maximum419 inclusive. The step value indicates the increment between values.420 * - ``V4L2_CTRL_TYPE_MPEG2_QUANTISATION``421 - n/a422 - n/a423 - n/a424 - A struct :c:type:`v4l2_ctrl_mpeg2_quantisation`, containing MPEG-2425 quantisation matrices for stateless video decoders.426 * - ``V4L2_CTRL_TYPE_MPEG2_SEQUENCE``427 - n/a428 - n/a429 - n/a430 - A struct :c:type:`v4l2_ctrl_mpeg2_sequence`, containing MPEG-2431 sequence parameters for stateless video decoders.432 * - ``V4L2_CTRL_TYPE_MPEG2_PICTURE``433 - n/a434 - n/a435 - n/a436 - A struct :c:type:`v4l2_ctrl_mpeg2_picture`, containing MPEG-2437 picture parameters for stateless video decoders.438 * - ``V4L2_CTRL_TYPE_AREA``439 - n/a440 - n/a441 - n/a442 - A struct :c:type:`v4l2_area`, containing the width and the height443 of a rectangular area. Units depend on the use case.444 * - ``V4L2_CTRL_TYPE_H264_SPS``445 - n/a446 - n/a447 - n/a448 - A struct :c:type:`v4l2_ctrl_h264_sps`, containing H264449 sequence parameters for stateless video decoders.450 * - ``V4L2_CTRL_TYPE_H264_PPS``451 - n/a452 - n/a453 - n/a454 - A struct :c:type:`v4l2_ctrl_h264_pps`, containing H264455 picture parameters for stateless video decoders.456 * - ``V4L2_CTRL_TYPE_H264_SCALING_MATRIX``457 - n/a458 - n/a459 - n/a460 - A struct :c:type:`v4l2_ctrl_h264_scaling_matrix`, containing H264461 scaling matrices for stateless video decoders.462 * - ``V4L2_CTRL_TYPE_H264_SLICE_PARAMS``463 - n/a464 - n/a465 - n/a466 - A struct :c:type:`v4l2_ctrl_h264_slice_params`, containing H264467 slice parameters for stateless video decoders.468 * - ``V4L2_CTRL_TYPE_H264_DECODE_PARAMS``469 - n/a470 - n/a471 - n/a472 - A struct :c:type:`v4l2_ctrl_h264_decode_params`, containing H264473 decode parameters for stateless video decoders.474 * - ``V4L2_CTRL_TYPE_FWHT_PARAMS``475 - n/a476 - n/a477 - n/a478 - A struct :c:type:`v4l2_ctrl_fwht_params`, containing FWHT479 parameters for stateless video decoders.480 * - ``V4L2_CTRL_TYPE_HEVC_SPS``481 - n/a482 - n/a483 - n/a484 - A struct :c:type:`v4l2_ctrl_hevc_sps`, containing HEVC Sequence485 Parameter Set for stateless video decoders.486 * - ``V4L2_CTRL_TYPE_HEVC_PPS``487 - n/a488 - n/a489 - n/a490 - A struct :c:type:`v4l2_ctrl_hevc_pps`, containing HEVC Picture491 Parameter Set for stateless video decoders.492 * - ``V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS``493 - n/a494 - n/a495 - n/a496 - A struct :c:type:`v4l2_ctrl_hevc_slice_params`, containing HEVC497 slice parameters for stateless video decoders.498 * - ``V4L2_CTRL_TYPE_HEVC_SCALING_MATRIX``499 - n/a500 - n/a501 - n/a502 - A struct :c:type:`v4l2_ctrl_hevc_scaling_matrix`, containing HEVC503 scaling matrix for stateless video decoders.504 * - ``V4L2_CTRL_TYPE_VP8_FRAME``505 - n/a506 - n/a507 - n/a508 - A struct :c:type:`v4l2_ctrl_vp8_frame`, containing VP8509 frame parameters for stateless video decoders.510 * - ``V4L2_CTRL_TYPE_HEVC_DECODE_PARAMS``511 - n/a512 - n/a513 - n/a514 - A struct :c:type:`v4l2_ctrl_hevc_decode_params`, containing HEVC515 decoding parameters for stateless video decoders.516 * - ``V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR``517 - n/a518 - n/a519 - n/a520 - A struct :c:type:`v4l2_ctrl_vp9_compressed_hdr`, containing VP9521 probabilities updates for stateless video decoders.522 * - ``V4L2_CTRL_TYPE_VP9_FRAME``523 - n/a524 - n/a525 - n/a526 - A struct :c:type:`v4l2_ctrl_vp9_frame`, containing VP9527 frame decode parameters for stateless video decoders.528 * - ``V4L2_CTRL_TYPE_AV1_SEQUENCE``529 - n/a530 - n/a531 - n/a532 - A struct :c:type:`v4l2_ctrl_av1_sequence`, containing AV1 Sequence OBU533 decoding parameters for stateless video decoders.534 * - ``V4L2_CTRL_TYPE_AV1_TILE_GROUP_ENTRY``535 - n/a536 - n/a537 - n/a538 - A struct :c:type:`v4l2_ctrl_av1_tile_group_entry`, containing AV1 Tile Group539 OBU decoding parameters for stateless video decoders.540 * - ``V4L2_CTRL_TYPE_AV1_FRAME``541 - n/a542 - n/a543 - n/a544 - A struct :c:type:`v4l2_ctrl_av1_frame`, containing AV1 Frame/Frame545 Header OBU decoding parameters for stateless video decoders.546 * - ``V4L2_CTRL_TYPE_AV1_FILM_GRAIN``547 - n/a548 - n/a549 - n/a550 - A struct :c:type:`v4l2_ctrl_av1_film_grain`, containing AV1 Film Grain551 parameters for stateless video decoders.552 553.. raw:: latex554 555 \normalsize556 557.. tabularcolumns:: |p{7.3cm}|p{1.8cm}|p{8.2cm}|558 559.. cssclass:: longtable560 561.. _control-flags:562 563.. flat-table:: Control Flags564 :header-rows: 0565 :stub-columns: 0566 :widths: 3 1 4567 568 * - ``V4L2_CTRL_FLAG_DISABLED``569 - 0x0001570 - This control is permanently disabled and should be ignored by the571 application. Any attempt to change the control will result in an572 ``EINVAL`` error code.573 * - ``V4L2_CTRL_FLAG_GRABBED``574 - 0x0002575 - This control is temporarily unchangeable, for example because576 another application took over control of the respective resource.577 Such controls may be displayed specially in a user interface.578 Attempts to change the control may result in an ``EBUSY`` error code.579 * - ``V4L2_CTRL_FLAG_READ_ONLY``580 - 0x0004581 - This control is permanently readable only. Any attempt to change582 the control will result in an ``EINVAL`` error code.583 * - ``V4L2_CTRL_FLAG_UPDATE``584 - 0x0008585 - A hint that changing this control may affect the value of other586 controls within the same control class. Applications should update587 their user interface accordingly.588 * - ``V4L2_CTRL_FLAG_INACTIVE``589 - 0x0010590 - This control is not applicable to the current configuration and591 should be displayed accordingly in a user interface. For example592 the flag may be set on a MPEG audio level 2 bitrate control when593 MPEG audio encoding level 1 was selected with another control.594 * - ``V4L2_CTRL_FLAG_SLIDER``595 - 0x0020596 - A hint that this control is best represented as a slider-like597 element in a user interface.598 * - ``V4L2_CTRL_FLAG_WRITE_ONLY``599 - 0x0040600 - This control is permanently writable only. Any attempt to read the601 control will result in an ``EACCES`` error code error code. This flag602 is typically present for relative controls or action controls603 where writing a value will cause the device to carry out a given604 action (e. g. motor control) but no meaningful value can be605 returned.606 * - ``V4L2_CTRL_FLAG_VOLATILE``607 - 0x0080608 - This control is volatile, which means that the value of the609 control changes continuously. A typical example would be the610 current gain value if the device is in auto-gain mode. In such a611 case the hardware calculates the gain value based on the lighting612 conditions which can change over time.613 614 .. note::615 616 Setting a new value for a volatile control will be ignored617 unless618 :ref:`V4L2_CTRL_FLAG_EXECUTE_ON_WRITE <FLAG_EXECUTE_ON_WRITE>`619 is also set.620 Setting a new value for a volatile control will *never* trigger a621 :ref:`V4L2_EVENT_CTRL_CH_VALUE <ctrl-changes-flags>` event.622 * - ``V4L2_CTRL_FLAG_HAS_PAYLOAD``623 - 0x0100624 - This control has a pointer type, so its value has to be accessed625 using one of the pointer fields of struct626 :c:type:`v4l2_ext_control`. This flag is set627 for controls that are an array, string, or have a compound type.628 In all cases you have to set a pointer to memory containing the629 payload of the control.630 * .. _FLAG_EXECUTE_ON_WRITE:631 632 - ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``633 - 0x0200634 - The value provided to the control will be propagated to the driver635 even if it remains constant. This is required when the control636 represents an action on the hardware. For example: clearing an637 error flag or triggering the flash. All the controls of the type638 ``V4L2_CTRL_TYPE_BUTTON`` have this flag set.639 * .. _FLAG_MODIFY_LAYOUT:640 641 - ``V4L2_CTRL_FLAG_MODIFY_LAYOUT``642 - 0x0400643 - Changing this control value may modify the layout of the644 buffer (for video devices) or the media bus format (for sub-devices).645 646 A typical example would be the ``V4L2_CID_ROTATE`` control.647 648 Note that typically controls with this flag will also set the649 ``V4L2_CTRL_FLAG_GRABBED`` flag when buffers are allocated or650 streaming is in progress since most drivers do not support changing651 the format in that case.652 * - ``V4L2_CTRL_FLAG_DYNAMIC_ARRAY``653 - 0x0800654 - This control is a dynamically sized 1-dimensional array. It655 behaves the same as a regular array, except that the number656 of elements as reported by the ``elems`` field is between 1 and657 ``dims[0]``. So setting the control with a differently sized658 array will change the ``elems`` field when the control is659 queried afterwards.660 661Return Value662============663 664On success 0 is returned, on error -1 and the ``errno`` variable is set665appropriately. The generic error codes are described at the666:ref:`Generic Error Codes <gen-errors>` chapter.667 668EINVAL669 The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id`` is670 invalid. The struct :ref:`v4l2_querymenu <v4l2-querymenu>` ``id``671 is invalid or ``index`` is out of range (less than ``minimum`` or672 greater than ``maximum``) or this particular menu item is not673 supported by the driver.674 675EACCES676 An attempt was made to read a write-only control.677 678.. [#f1]679 ``V4L2_CTRL_FLAG_DISABLED`` was intended for two purposes: Drivers680 can skip predefined controls not supported by the hardware (although681 returning ``EINVAL`` would do as well), or disable predefined and private682 controls after hardware detection without the trouble of reordering683 control arrays and indices (``EINVAL`` cannot be used to skip private684 controls because it would prematurely end the enumeration).685