| 1 |
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later |
| 2 |
.. c:namespace:: V4L |
| 3 |
|
| 4 |
.. _VIDIOC_QUERYCTRL: |
| 5 |
|
| 6 |
******************************************************************* |
| 7 |
ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU |
| 8 |
******************************************************************* |
| 9 |
|
| 10 |
Name |
| 11 |
==== |
| 12 |
|
| 13 |
VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items |
| 14 |
|
| 15 |
Synopsis |
| 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 |
|
| 30 |
Arguments |
| 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 |
|
| 40 |
Description |
| 41 |
=========== |
| 42 |
|
| 43 |
To query the attributes of a control applications set the ``id`` field |
| 44 |
of a struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` and call the |
| 45 |
``VIDIOC_QUERYCTRL`` ioctl with a pointer to this structure. The driver |
| 46 |
fills the rest of the structure or returns an ``EINVAL`` error code when the |
| 47 |
``id`` is invalid. |
| 48 |
|
| 49 |
It is possible to enumerate controls by calling ``VIDIOC_QUERYCTRL`` |
| 50 |
with successive ``id`` values starting from ``V4L2_CID_BASE`` up to and |
| 51 |
exclusive ``V4L2_CID_LASTP1``. Drivers may return ``EINVAL`` if a control in |
| 52 |
this range is not supported. Further applications can enumerate private |
| 53 |
controls, which are not defined in this specification, by starting at |
| 54 |
``V4L2_CID_PRIVATE_BASE`` and incrementing ``id`` until the driver |
| 55 |
returns ``EINVAL``. |
| 56 |
|
| 57 |
In both cases, when the driver sets the ``V4L2_CTRL_FLAG_DISABLED`` flag |
| 58 |
in the ``flags`` field this control is permanently disabled and should |
| 59 |
be ignored by the application. [#f1]_ |
| 60 |
|
| 61 |
When the application ORs ``id`` with ``V4L2_CTRL_FLAG_NEXT_CTRL`` the |
| 62 |
driver returns the next supported non-compound control, or ``EINVAL`` if |
| 63 |
there is none. In addition, the ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` flag |
| 64 |
can be specified to enumerate all compound controls (i.e. controls with |
| 65 |
type ≥ ``V4L2_CTRL_COMPOUND_TYPES`` and/or array control, in other words |
| 66 |
controls that contain more than one value). Specify both |
| 67 |
``V4L2_CTRL_FLAG_NEXT_CTRL`` and ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` in |
| 68 |
order to enumerate all controls, compound or not. Drivers which do not |
| 69 |
support these flags yet always return ``EINVAL``. |
| 70 |
|
| 71 |
The ``VIDIOC_QUERY_EXT_CTRL`` ioctl was introduced in order to better |
| 72 |
support controls that can use compound types, and to expose additional |
| 73 |
control 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 |
| 78 |
as well. |
| 79 |
|
| 80 |
Additional information is required for menu controls: the names of the |
| 81 |
menu items. To query them applications set the ``id`` and ``index`` |
| 82 |
fields of struct :ref:`v4l2_querymenu <v4l2-querymenu>` and call the |
| 83 |
``VIDIOC_QUERYMENU`` ioctl with a pointer to this structure. The driver |
| 84 |
fills 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``, |
| 88 |
inclusive. |
| 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 |
|
| 97 |
See 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 |
|
| 695 |
Return Value |
| 696 |
============ |
| 697 |
|
| 698 |
On success 0 is returned, on error -1 and the ``errno`` variable is set |
| 699 |
appropriately. The generic error codes are described at the |
| 700 |
:ref:`Generic Error Codes <gen-errors>` chapter. |
| 701 |
|
| 702 |
EINVAL |
| 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 |
|
| 709 |
EACCES |
| 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). |