Debian Codegraph @

Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst

raw
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).