Debian Codegraph @

Documentation/userspace-api/media/v4l/control.rst

raw
1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: V4L
3
4 .. _control:
5
6 *************
7 User Controls
8 *************
9
10 Devices typically have a number of user-settable controls such as
11 brightness, saturation and so on, which would be presented to the user
12 on a graphical user interface. But, different devices will have
13 different controls available, and furthermore, the range of possible
14 values, and the default value will vary from device to device. The
15 control ioctls provide the information and a mechanism to create a nice
16 user interface for these controls that will work correctly with any
17 device.
18
19 All controls are accessed using an ID value. V4L2 defines several IDs
20 for specific purposes. Drivers can also implement their own custom
21 controls using ``V4L2_CID_PRIVATE_BASE`` [#f1]_ and higher values. The
22 pre-defined control IDs have the prefix ``V4L2_CID_``, and are listed in
23 :ref:`control-id`. The ID is used when querying the attributes of a
24 control, and when getting or setting the current value.
25
26 Generally applications should present controls to the user without
27 assumptions about their purpose. Each control comes with a name string
28 the user is supposed to understand. When the purpose is non-intuitive
29 the driver writer should provide a user manual, a user interface plug-in
30 or a driver specific panel application. Predefined IDs were introduced
31 to change a few controls programmatically, for example to mute a device
32 during a channel switch.
33
34 Drivers may enumerate different controls after switching the current
35 video input or output, tuner or modulator, or audio input or output.
36 Different in the sense of other bounds, another default and current
37 value, step size or other menu items. A control with a certain *custom*
38 ID can also change name and type.
39
40 If a control is not applicable to the current configuration of the
41 device (for example, it doesn't apply to the current video input)
42 drivers set the ``V4L2_CTRL_FLAG_INACTIVE`` flag.
43
44 Control values are stored globally, they do not change when switching
45 except to stay within the reported bounds. They also do not change e. g.
46 when the device is opened or closed, when the tuner radio frequency is
47 changed or generally never without application request.
48
49 V4L2 specifies an event mechanism to notify applications when controls
50 change value (see
51 :ref:`VIDIOC_SUBSCRIBE_EVENT`, event
52 ``V4L2_EVENT_CTRL``), panel applications might want to make use of that
53 in order to always reflect the correct control value.
54
55 All controls use machine endianness.
56
57
58 .. _control-id:
59
60 Control IDs
61 ===========
62
63 ``V4L2_CID_BASE``
64 First predefined ID, equal to ``V4L2_CID_BRIGHTNESS``.
65
66 ``V4L2_CID_USER_BASE``
67 Synonym of ``V4L2_CID_BASE``.
68
69 ``V4L2_CID_BRIGHTNESS`` ``(integer)``
70 Picture brightness, or more precisely, the black level.
71
72 ``V4L2_CID_CONTRAST`` ``(integer)``
73 Picture contrast or luma gain.
74
75 ``V4L2_CID_SATURATION`` ``(integer)``
76 Picture color saturation or chroma gain.
77
78 ``V4L2_CID_HUE`` ``(integer)``
79 Hue or color balance.
80
81 ``V4L2_CID_AUDIO_VOLUME`` ``(integer)``
82 Overall audio volume. Note some drivers also provide an OSS or ALSA
83 mixer interface.
84
85 ``V4L2_CID_AUDIO_BALANCE`` ``(integer)``
86 Audio stereo balance. Minimum corresponds to all the way left,
87 maximum to right.
88
89 ``V4L2_CID_AUDIO_BASS`` ``(integer)``
90 Audio bass adjustment.
91
92 ``V4L2_CID_AUDIO_TREBLE`` ``(integer)``
93 Audio treble adjustment.
94
95 ``V4L2_CID_AUDIO_MUTE`` ``(boolean)``
96 Mute audio, i. e. set the volume to zero, however without affecting
97 ``V4L2_CID_AUDIO_VOLUME``. Like ALSA drivers, V4L2 drivers must mute
98 at load time to avoid excessive noise. Actually the entire device
99 should be reset to a low power consumption state.
100
101 ``V4L2_CID_AUDIO_LOUDNESS`` ``(boolean)``
102 Loudness mode (bass boost).
103
104 ``V4L2_CID_BLACK_LEVEL`` ``(integer)``
105 Another name for brightness (not a synonym of
106 ``V4L2_CID_BRIGHTNESS``). This control is deprecated and should not
107 be used in new drivers and applications.
108
109 ``V4L2_CID_AUTO_WHITE_BALANCE`` ``(boolean)``
110 Automatic white balance (cameras).
111
112 ``V4L2_CID_DO_WHITE_BALANCE`` ``(button)``
113 This is an action control. When set (the value is ignored), the
114 device will do a white balance and then hold the current setting.
115 Contrast this with the boolean ``V4L2_CID_AUTO_WHITE_BALANCE``,
116 which, when activated, keeps adjusting the white balance.
117
118 ``V4L2_CID_RED_BALANCE`` ``(integer)``
119 Red chroma balance.
120
121 ``V4L2_CID_BLUE_BALANCE`` ``(integer)``
122 Blue chroma balance.
123
124 ``V4L2_CID_GAMMA`` ``(integer)``
125 Gamma adjust.
126
127 ``V4L2_CID_WHITENESS`` ``(integer)``
128 Whiteness for grey-scale devices. This is a synonym for
129 ``V4L2_CID_GAMMA``. This control is deprecated and should not be
130 used in new drivers and applications.
131
132 ``V4L2_CID_EXPOSURE`` ``(integer)``
133 Exposure (cameras). [Unit?]
134
135 ``V4L2_CID_AUTOGAIN`` ``(boolean)``
136 Automatic gain/exposure control.
137
138 ``V4L2_CID_GAIN`` ``(integer)``
139 Gain control.
140
141 Primarily used to control gain on e.g. TV tuners but also on
142 webcams. Most devices control only digital gain with this control
143 but on some this could include analogue gain as well. Devices that
144 recognise the difference between digital and analogue gain use
145 controls ``V4L2_CID_DIGITAL_GAIN`` and ``V4L2_CID_ANALOGUE_GAIN``.
146
147 .. _v4l2-cid-hflip:
148
149 ``V4L2_CID_HFLIP`` ``(boolean)``
150 Mirror the picture horizontally.
151
152 .. _v4l2-cid-vflip:
153
154 ``V4L2_CID_VFLIP`` ``(boolean)``
155 Mirror the picture vertically.
156
157 .. _v4l2-power-line-frequency:
158
159 ``V4L2_CID_POWER_LINE_FREQUENCY`` ``(enum)``
160 Enables a power line frequency filter to avoid flicker. Possible
161 values for ``enum v4l2_power_line_frequency`` are:
162
163 ========================================== ==
164 ``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` 0
165 ``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` 1
166 ``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` 2
167 ``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` 3
168 ========================================== ==
169
170 ``V4L2_CID_HUE_AUTO`` ``(boolean)``
171 Enables automatic hue control by the device. The effect of setting
172 ``V4L2_CID_HUE`` while automatic hue control is enabled is
173 undefined, drivers should ignore such request.
174
175 ``V4L2_CID_WHITE_BALANCE_TEMPERATURE`` ``(integer)``
176 This control specifies the white balance settings as a color
177 temperature in Kelvin. A driver should have a minimum of 2800
178 (incandescent) to 6500 (daylight). For more information about color
179 temperature see
180 `Wikipedia <http://en.wikipedia.org/wiki/Color_temperature>`__.
181
182 ``V4L2_CID_SHARPNESS`` ``(integer)``
183 Adjusts the sharpness filters in a camera. The minimum value
184 disables the filters, higher values give a sharper picture.
185
186 ``V4L2_CID_BACKLIGHT_COMPENSATION`` ``(integer)``
187 Adjusts the backlight compensation in a camera. The minimum value
188 disables backlight compensation.
189
190 ``V4L2_CID_CHROMA_AGC`` ``(boolean)``
191 Chroma automatic gain control.
192
193 ``V4L2_CID_CHROMA_GAIN`` ``(integer)``
194 Adjusts the Chroma gain control (for use when chroma AGC is
195 disabled).
196
197 ``V4L2_CID_COLOR_KILLER`` ``(boolean)``
198 Enable the color killer (i. e. force a black & white image in case
199 of a weak video signal).
200
201 .. _v4l2-colorfx:
202
203 ``V4L2_CID_COLORFX`` ``(enum)``
204 Selects a color effect. The following values are defined:
205
206
207
208 .. tabularcolumns:: |p{5.7cm}|p{11.8cm}|
209
210 .. flat-table::
211 :header-rows: 0
212 :stub-columns: 0
213 :widths: 11 24
214
215 * - ``V4L2_COLORFX_NONE``
216 - Color effect is disabled.
217 * - ``V4L2_COLORFX_ANTIQUE``
218 - An aging (old photo) effect.
219 * - ``V4L2_COLORFX_ART_FREEZE``
220 - Frost color effect.
221 * - ``V4L2_COLORFX_AQUA``
222 - Water color, cool tone.
223 * - ``V4L2_COLORFX_BW``
224 - Black and white.
225 * - ``V4L2_COLORFX_EMBOSS``
226 - Emboss, the highlights and shadows replace light/dark boundaries
227 and low contrast areas are set to a gray background.
228 * - ``V4L2_COLORFX_GRASS_GREEN``
229 - Grass green.
230 * - ``V4L2_COLORFX_NEGATIVE``
231 - Negative.
232 * - ``V4L2_COLORFX_SEPIA``
233 - Sepia tone.
234 * - ``V4L2_COLORFX_SKETCH``
235 - Sketch.
236 * - ``V4L2_COLORFX_SKIN_WHITEN``
237 - Skin whiten.
238 * - ``V4L2_COLORFX_SKY_BLUE``
239 - Sky blue.
240 * - ``V4L2_COLORFX_SOLARIZATION``
241 - Solarization, the image is partially reversed in tone, only color
242 values above or below a certain threshold are inverted.
243 * - ``V4L2_COLORFX_SILHOUETTE``
244 - Silhouette (outline).
245 * - ``V4L2_COLORFX_VIVID``
246 - Vivid colors.
247 * - ``V4L2_COLORFX_SET_CBCR``
248 - The Cb and Cr chroma components are replaced by fixed coefficients
249 determined by ``V4L2_CID_COLORFX_CBCR`` control.
250 * - ``V4L2_COLORFX_SET_RGB``
251 - The RGB components are replaced by the fixed RGB components determined
252 by ``V4L2_CID_COLORFX_RGB`` control.
253
254
255 ``V4L2_CID_COLORFX_RGB`` ``(integer)``
256 Determines the Red, Green, and Blue coefficients for
257 ``V4L2_COLORFX_SET_RGB`` color effect.
258 Bits [7:0] of the supplied 32 bit value are interpreted as Blue component,
259 bits [15:8] as Green component, bits [23:16] as Red component, and
260 bits [31:24] must be zero.
261
262 ``V4L2_CID_COLORFX_CBCR`` ``(integer)``
263 Determines the Cb and Cr coefficients for ``V4L2_COLORFX_SET_CBCR``
264 color effect. Bits [7:0] of the supplied 32 bit value are
265 interpreted as Cr component, bits [15:8] as Cb component and bits
266 [31:16] must be zero.
267
268 ``V4L2_CID_AUTOBRIGHTNESS`` ``(boolean)``
269 Enable Automatic Brightness.
270
271 ``V4L2_CID_ROTATE`` ``(integer)``
272 Rotates the image by specified angle. Common angles are 90, 270 and
273 180. Rotating the image to 90 and 270 will reverse the height and
274 width of the display window. It is necessary to set the new height
275 and width of the picture using the
276 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl according to the
277 rotation angle selected.
278
279 ``V4L2_CID_BG_COLOR`` ``(integer)``
280 Sets the background color on the current output device. Background
281 color needs to be specified in the RGB24 format. The supplied 32 bit
282 value is interpreted as bits 0-7 Red color information, bits 8-15
283 Green color information, bits 16-23 Blue color information and bits
284 24-31 must be zero.
285
286 ``V4L2_CID_ILLUMINATORS_1 V4L2_CID_ILLUMINATORS_2`` ``(boolean)``
287 Switch on or off the illuminator 1 or 2 of the device (usually a
288 microscope).
289
290 ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE`` ``(integer)``
291 This is a read-only control that can be read by the application and
292 used as a hint to determine the number of CAPTURE buffers to pass to
293 REQBUFS. The value is the minimum number of CAPTURE buffers that is
294 necessary for hardware to work. This control is required for stateful
295 decoders.
296
297 ``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT`` ``(integer)``
298 This is a read-only control that can be read by the application and
299 used as a hint to determine the number of OUTPUT buffers to pass to
300 REQBUFS. The value is the minimum number of OUTPUT buffers that is
301 necessary for hardware to work. This control is required for stateful
302 encoders.
303
304 .. _v4l2-alpha-component:
305
306 ``V4L2_CID_ALPHA_COMPONENT`` ``(integer)``
307 Sets the alpha color component. When a capture device (or capture
308 queue of a mem-to-mem device) produces a frame format that includes
309 an alpha component (e.g.
310 :ref:`packed RGB image formats <pixfmt-rgb>`) and the alpha value
311 is not defined by the device or the mem-to-mem input data this
312 control lets you select the alpha component value of all pixels.
313 When an output device (or output queue of a mem-to-mem device)
314 consumes a frame format that doesn't include an alpha component and
315 the device supports alpha channel processing this control lets you
316 set the alpha component value of all pixels for further processing
317 in the device.
318
319 ``V4L2_CID_LASTP1``
320 End of the predefined control IDs (currently
321 ``V4L2_CID_ALPHA_COMPONENT`` + 1).
322
323 ``V4L2_CID_PRIVATE_BASE``
324 ID of the first custom (driver specific) control. Applications
325 depending on particular custom controls should check the driver name
326 and version, see :ref:`querycap`.
327
328 Applications can enumerate the available controls with the
329 :ref:`VIDIOC_QUERYCTRL` and
330 :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>` ioctls, get and set a
331 control value with the :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
332 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls. Drivers must implement
333 ``VIDIOC_QUERYCTRL``, ``VIDIOC_G_CTRL`` and ``VIDIOC_S_CTRL`` when the
334 device has one or more controls, ``VIDIOC_QUERYMENU`` when it has one or
335 more menu type controls.
336
337
338 .. _enum_all_controls:
339
340 Example: Enumerating all controls
341 =================================
342
343 .. code-block:: c
344
345 struct v4l2_queryctrl queryctrl;
346 struct v4l2_querymenu querymenu;
347
348 static void enumerate_menu(__u32 id)
349 {
350 printf(" Menu items:\\n");
351
352 memset(&querymenu, 0, sizeof(querymenu));
353 querymenu.id = id;
354
355 for (querymenu.index = queryctrl.minimum;
356 querymenu.index <= queryctrl.maximum;
357 querymenu.index++) {
358 if (0 == ioctl(fd, VIDIOC_QUERYMENU, &querymenu)) {
359 printf(" %s\\n", querymenu.name);
360 }
361 }
362 }
363
364 memset(&queryctrl, 0, sizeof(queryctrl));
365
366 queryctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
367 while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
368 if (!(queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)) {
369 printf("Control %s\\n", queryctrl.name);
370
371 if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
372 enumerate_menu(queryctrl.id);
373 }
374
375 queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
376 }
377 if (errno != EINVAL) {
378 perror("VIDIOC_QUERYCTRL");
379 exit(EXIT_FAILURE);
380 }
381
382 Example: Enumerating all controls including compound controls
383 =============================================================
384
385 .. code-block:: c
386
387 struct v4l2_query_ext_ctrl query_ext_ctrl;
388
389 memset(&query_ext_ctrl, 0, sizeof(query_ext_ctrl));
390
391 query_ext_ctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL | V4L2_CTRL_FLAG_NEXT_COMPOUND;
392 while (0 == ioctl(fd, VIDIOC_QUERY_EXT_CTRL, &query_ext_ctrl)) {
393 if (!(query_ext_ctrl.flags & V4L2_CTRL_FLAG_DISABLED)) {
394 printf("Control %s\\n", query_ext_ctrl.name);
395
396 if (query_ext_ctrl.type == V4L2_CTRL_TYPE_MENU)
397 enumerate_menu(query_ext_ctrl.id);
398 }
399
400 query_ext_ctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL | V4L2_CTRL_FLAG_NEXT_COMPOUND;
401 }
402 if (errno != EINVAL) {
403 perror("VIDIOC_QUERY_EXT_CTRL");
404 exit(EXIT_FAILURE);
405 }
406
407 Example: Enumerating all user controls (old style)
408 ==================================================
409
410 .. code-block:: c
411
412
413 memset(&queryctrl, 0, sizeof(queryctrl));
414
415 for (queryctrl.id = V4L2_CID_BASE;
416 queryctrl.id < V4L2_CID_LASTP1;
417 queryctrl.id++) {
418 if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
419 if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
420 continue;
421
422 printf("Control %s\\n", queryctrl.name);
423
424 if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
425 enumerate_menu(queryctrl.id);
426 } else {
427 if (errno == EINVAL)
428 continue;
429
430 perror("VIDIOC_QUERYCTRL");
431 exit(EXIT_FAILURE);
432 }
433 }
434
435 for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
436 queryctrl.id++) {
437 if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
438 if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
439 continue;
440
441 printf("Control %s\\n", queryctrl.name);
442
443 if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
444 enumerate_menu(queryctrl.id);
445 } else {
446 if (errno == EINVAL)
447 break;
448
449 perror("VIDIOC_QUERYCTRL");
450 exit(EXIT_FAILURE);
451 }
452 }
453
454
455 Example: Changing controls
456 ==========================
457
458 .. code-block:: c
459
460 struct v4l2_queryctrl queryctrl;
461 struct v4l2_control control;
462
463 memset(&queryctrl, 0, sizeof(queryctrl));
464 queryctrl.id = V4L2_CID_BRIGHTNESS;
465
466 if (-1 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
467 if (errno != EINVAL) {
468 perror("VIDIOC_QUERYCTRL");
469 exit(EXIT_FAILURE);
470 } else {
471 printf("V4L2_CID_BRIGHTNESS is not supported\n");
472 }
473 } else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) {
474 printf("V4L2_CID_BRIGHTNESS is not supported\n");
475 } else {
476 memset(&control, 0, sizeof (control));
477 control.id = V4L2_CID_BRIGHTNESS;
478 control.value = queryctrl.default_value;
479
480 if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)) {
481 perror("VIDIOC_S_CTRL");
482 exit(EXIT_FAILURE);
483 }
484 }
485
486 memset(&control, 0, sizeof(control));
487 control.id = V4L2_CID_CONTRAST;
488
489 if (0 == ioctl(fd, VIDIOC_G_CTRL, &control)) {
490 control.value += 1;
491
492 /* The driver may clamp the value or return ERANGE, ignored here */
493
494 if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)
495 && errno != ERANGE) {
496 perror("VIDIOC_S_CTRL");
497 exit(EXIT_FAILURE);
498 }
499 /* Ignore if V4L2_CID_CONTRAST is unsupported */
500 } else if (errno != EINVAL) {
501 perror("VIDIOC_G_CTRL");
502 exit(EXIT_FAILURE);
503 }
504
505 control.id = V4L2_CID_AUDIO_MUTE;
506 control.value = 1; /* silence */
507
508 /* Errors ignored */
509 ioctl(fd, VIDIOC_S_CTRL, &control);
510
511 .. [#f1]
512 The use of ``V4L2_CID_PRIVATE_BASE`` is problematic because different
513 drivers may use the same ``V4L2_CID_PRIVATE_BASE`` ID for different
514 controls. This makes it hard to programmatically set such controls
515 since the meaning of the control with that ID is driver dependent. In
516 order to resolve this drivers use unique IDs and the
517 ``V4L2_CID_PRIVATE_BASE`` IDs are mapped to those unique IDs by the
518 kernel. Consider these ``V4L2_CID_PRIVATE_BASE`` IDs as aliases to
519 the real IDs.
520
521 Many applications today still use the ``V4L2_CID_PRIVATE_BASE`` IDs
522 instead of using :ref:`VIDIOC_QUERYCTRL` with
523 the ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag to enumerate all IDs, so
524 support for ``V4L2_CID_PRIVATE_BASE`` is still around.