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