Documentation/media/uapi/v4l/vidioc-queryctrl.rst

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