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