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