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