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