GNU Linux-libre 4.14.295-gnu1
[releases.git] / Documentation / media / uapi / v4l / control.rst
1 .. -*- coding: utf-8; mode: rst -*-
2
3 .. _control:
4
5 *************
6 User Controls
7 *************
8
9 Devices typically have a number of user-settable controls such as
10 brightness, saturation and so on, which would be presented to the user
11 on a graphical user interface. But, different devices will have
12 different controls available, and furthermore, the range of possible
13 values, and the default value will vary from device to device. The
14 control ioctls provide the information and a mechanism to create a nice
15 user interface for these controls that will work correctly with any
16 device.
17
18 All controls are accessed using an ID value. V4L2 defines several IDs
19 for specific purposes. Drivers can also implement their own custom
20 controls using ``V4L2_CID_PRIVATE_BASE``  [#f1]_ and higher values. The
21 pre-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
23 control, and when getting or setting the current value.
24
25 Generally applications should present controls to the user without
26 assumptions about their purpose. Each control comes with a name string
27 the user is supposed to understand. When the purpose is non-intuitive
28 the driver writer should provide a user manual, a user interface plug-in
29 or a driver specific panel application. Predefined IDs were introduced
30 to change a few controls programmatically, for example to mute a device
31 during a channel switch.
32
33 Drivers may enumerate different controls after switching the current
34 video input or output, tuner or modulator, or audio input or output.
35 Different in the sense of other bounds, another default and current
36 value, step size or other menu items. A control with a certain *custom*
37 ID can also change name and type.
38
39 If a control is not applicable to the current configuration of the
40 device (for example, it doesn't apply to the current video input)
41 drivers set the ``V4L2_CTRL_FLAG_INACTIVE`` flag.
42
43 Control values are stored globally, they do not change when switching
44 except to stay within the reported bounds. They also do not change e. g.
45 when the device is opened or closed, when the tuner radio frequency is
46 changed or generally never without application request.
47
48 V4L2 specifies an event mechanism to notify applications when controls
49 change value (see
50 :ref:`VIDIOC_SUBSCRIBE_EVENT`, event
51 ``V4L2_EVENT_CTRL``), panel applications might want to make use of that
52 in order to always reflect the correct control value.
53
54 All controls use machine endianness.
55
56
57 .. _control-id:
58
59 Control 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`` ``(boolean)``
147     Mirror the picture horizontally.
148
149 ``V4L2_CID_VFLIP`` ``(boolean)``
150     Mirror the picture vertically.
151
152 .. _v4l2-power-line-frequency:
153
154 ``V4L2_CID_POWER_LINE_FREQUENCY`` ``(enum)``
155     Enables a power line frequency filter to avoid flicker. Possible
156     values for ``enum v4l2_power_line_frequency`` are:
157     ``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` (0),
158     ``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` (1),
159     ``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` (2) and
160     ``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` (3).
161
162 ``V4L2_CID_HUE_AUTO`` ``(boolean)``
163     Enables automatic hue control by the device. The effect of setting
164     ``V4L2_CID_HUE`` while automatic hue control is enabled is
165     undefined, drivers should ignore such request.
166
167 ``V4L2_CID_WHITE_BALANCE_TEMPERATURE`` ``(integer)``
168     This control specifies the white balance settings as a color
169     temperature in Kelvin. A driver should have a minimum of 2800
170     (incandescent) to 6500 (daylight). For more information about color
171     temperature see
172     `Wikipedia <http://en.wikipedia.org/wiki/Color_temperature>`__.
173
174 ``V4L2_CID_SHARPNESS`` ``(integer)``
175     Adjusts the sharpness filters in a camera. The minimum value
176     disables the filters, higher values give a sharper picture.
177
178 ``V4L2_CID_BACKLIGHT_COMPENSATION`` ``(integer)``
179     Adjusts the backlight compensation in a camera. The minimum value
180     disables backlight compensation.
181
182 ``V4L2_CID_CHROMA_AGC`` ``(boolean)``
183     Chroma automatic gain control.
184
185 ``V4L2_CID_CHROMA_GAIN`` ``(integer)``
186     Adjusts the Chroma gain control (for use when chroma AGC is
187     disabled).
188
189 ``V4L2_CID_COLOR_KILLER`` ``(boolean)``
190     Enable the color killer (i. e. force a black & white image in case
191     of a weak video signal).
192
193 .. _v4l2-colorfx:
194
195 ``V4L2_CID_COLORFX`` ``(enum)``
196     Selects a color effect. The following values are defined:
197
198
199
200 .. tabularcolumns:: |p{5.5cm}|p{12cm}|
201
202 .. flat-table::
203     :header-rows:  0
204     :stub-columns: 0
205     :widths: 11 24
206
207     * - ``V4L2_COLORFX_NONE``
208       - Color effect is disabled.
209     * - ``V4L2_COLORFX_ANTIQUE``
210       - An aging (old photo) effect.
211     * - ``V4L2_COLORFX_ART_FREEZE``
212       - Frost color effect.
213     * - ``V4L2_COLORFX_AQUA``
214       - Water color, cool tone.
215     * - ``V4L2_COLORFX_BW``
216       - Black and white.
217     * - ``V4L2_COLORFX_EMBOSS``
218       - Emboss, the highlights and shadows replace light/dark boundaries
219         and low contrast areas are set to a gray background.
220     * - ``V4L2_COLORFX_GRASS_GREEN``
221       - Grass green.
222     * - ``V4L2_COLORFX_NEGATIVE``
223       - Negative.
224     * - ``V4L2_COLORFX_SEPIA``
225       - Sepia tone.
226     * - ``V4L2_COLORFX_SKETCH``
227       - Sketch.
228     * - ``V4L2_COLORFX_SKIN_WHITEN``
229       - Skin whiten.
230     * - ``V4L2_COLORFX_SKY_BLUE``
231       - Sky blue.
232     * - ``V4L2_COLORFX_SOLARIZATION``
233       - Solarization, the image is partially reversed in tone, only color
234         values above or below a certain threshold are inverted.
235     * - ``V4L2_COLORFX_SILHOUETTE``
236       - Silhouette (outline).
237     * - ``V4L2_COLORFX_VIVID``
238       - Vivid colors.
239     * - ``V4L2_COLORFX_SET_CBCR``
240       - The Cb and Cr chroma components are replaced by fixed coefficients
241         determined by ``V4L2_CID_COLORFX_CBCR`` control.
242
243
244
245 ``V4L2_CID_COLORFX_CBCR`` ``(integer)``
246     Determines the Cb and Cr coefficients for ``V4L2_COLORFX_SET_CBCR``
247     color effect. Bits [7:0] of the supplied 32 bit value are
248     interpreted as Cr component, bits [15:8] as Cb component and bits
249     [31:16] must be zero.
250
251 ``V4L2_CID_AUTOBRIGHTNESS`` ``(boolean)``
252     Enable Automatic Brightness.
253
254 ``V4L2_CID_ROTATE`` ``(integer)``
255     Rotates the image by specified angle. Common angles are 90, 270 and
256     180. Rotating the image to 90 and 270 will reverse the height and
257     width of the display window. It is necessary to set the new height
258     and width of the picture using the
259     :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl according to the
260     rotation angle selected.
261
262 ``V4L2_CID_BG_COLOR`` ``(integer)``
263     Sets the background color on the current output device. Background
264     color needs to be specified in the RGB24 format. The supplied 32 bit
265     value is interpreted as bits 0-7 Red color information, bits 8-15
266     Green color information, bits 16-23 Blue color information and bits
267     24-31 must be zero.
268
269 ``V4L2_CID_ILLUMINATORS_1 V4L2_CID_ILLUMINATORS_2`` ``(boolean)``
270     Switch on or off the illuminator 1 or 2 of the device (usually a
271     microscope).
272
273 ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE`` ``(integer)``
274     This is a read-only control that can be read by the application and
275     used as a hint to determine the number of CAPTURE buffers to pass to
276     REQBUFS. The value is the minimum number of CAPTURE buffers that is
277     necessary for hardware to work.
278
279 ``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT`` ``(integer)``
280     This is a read-only control that can be read by the application and
281     used as a hint to determine the number of OUTPUT buffers to pass to
282     REQBUFS. The value is the minimum number of OUTPUT buffers that is
283     necessary for hardware to work.
284
285 .. _v4l2-alpha-component:
286
287 ``V4L2_CID_ALPHA_COMPONENT`` ``(integer)``
288     Sets the alpha color component. When a capture device (or capture
289     queue of a mem-to-mem device) produces a frame format that includes
290     an alpha component (e.g.
291     :ref:`packed RGB image formats <rgb-formats>`) and the alpha value
292     is not defined by the device or the mem-to-mem input data this
293     control lets you select the alpha component value of all pixels.
294     When an output device (or output queue of a mem-to-mem device)
295     consumes a frame format that doesn't include an alpha component and
296     the device supports alpha channel processing this control lets you
297     set the alpha component value of all pixels for further processing
298     in the device.
299
300 ``V4L2_CID_LASTP1``
301     End of the predefined control IDs (currently
302     ``V4L2_CID_ALPHA_COMPONENT`` + 1).
303
304 ``V4L2_CID_PRIVATE_BASE``
305     ID of the first custom (driver specific) control. Applications
306     depending on particular custom controls should check the driver name
307     and version, see :ref:`querycap`.
308
309 Applications can enumerate the available controls with the
310 :ref:`VIDIOC_QUERYCTRL` and
311 :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>` ioctls, get and set a
312 control value with the :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
313 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls. Drivers must implement
314 ``VIDIOC_QUERYCTRL``, ``VIDIOC_G_CTRL`` and ``VIDIOC_S_CTRL`` when the
315 device has one or more controls, ``VIDIOC_QUERYMENU`` when it has one or
316 more menu type controls.
317
318
319 .. _enum_all_controls:
320
321 Example: Enumerating all controls
322 =================================
323
324 .. code-block:: c
325
326     struct v4l2_queryctrl queryctrl;
327     struct v4l2_querymenu querymenu;
328
329     static void enumerate_menu(__u32 id)
330     {
331         printf("  Menu items:\\n");
332
333         memset(&querymenu, 0, sizeof(querymenu));
334         querymenu.id = id;
335
336         for (querymenu.index = queryctrl.minimum;
337              querymenu.index <= queryctrl.maximum;
338              querymenu.index++) {
339             if (0 == ioctl(fd, VIDIOC_QUERYMENU, &querymenu)) {
340                 printf("  %s\\n", querymenu.name);
341             }
342         }
343     }
344
345     memset(&queryctrl, 0, sizeof(queryctrl));
346
347     queryctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
348     while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
349         if (!(queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)) {
350             printf("Control %s\\n", queryctrl.name);
351
352             if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
353                 enumerate_menu(queryctrl.id);
354         }
355
356         queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
357     }
358     if (errno != EINVAL) {
359         perror("VIDIOC_QUERYCTRL");
360         exit(EXIT_FAILURE);
361     }
362
363 Example: Enumerating all controls including compound controls
364 =============================================================
365
366 .. code-block:: c
367
368     struct v4l2_query_ext_ctrl query_ext_ctrl;
369
370     memset(&query_ext_ctrl, 0, sizeof(query_ext_ctrl));
371
372     query_ext_ctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL | V4L2_CTRL_FLAG_NEXT_COMPOUND;
373     while (0 == ioctl(fd, VIDIOC_QUERY_EXT_CTRL, &query_ext_ctrl)) {
374         if (!(query_ext_ctrl.flags & V4L2_CTRL_FLAG_DISABLED)) {
375             printf("Control %s\\n", query_ext_ctrl.name);
376
377             if (query_ext_ctrl.type == V4L2_CTRL_TYPE_MENU)
378                 enumerate_menu(query_ext_ctrl.id);
379         }
380
381         query_ext_ctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL | V4L2_CTRL_FLAG_NEXT_COMPOUND;
382     }
383     if (errno != EINVAL) {
384         perror("VIDIOC_QUERY_EXT_CTRL");
385         exit(EXIT_FAILURE);
386     }
387
388 Example: Enumerating all user controls (old style)
389 ==================================================
390
391 .. code-block:: c
392
393
394     memset(&queryctrl, 0, sizeof(queryctrl));
395
396     for (queryctrl.id = V4L2_CID_BASE;
397          queryctrl.id < V4L2_CID_LASTP1;
398          queryctrl.id++) {
399         if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
400             if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
401                 continue;
402
403             printf("Control %s\\n", queryctrl.name);
404
405             if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
406                 enumerate_menu(queryctrl.id);
407         } else {
408             if (errno == EINVAL)
409                 continue;
410
411             perror("VIDIOC_QUERYCTRL");
412             exit(EXIT_FAILURE);
413         }
414     }
415
416     for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
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                 break;
429
430             perror("VIDIOC_QUERYCTRL");
431             exit(EXIT_FAILURE);
432         }
433     }
434
435
436 Example: Changing controls
437 ==========================
438
439 .. code-block:: c
440
441     struct v4l2_queryctrl queryctrl;
442     struct v4l2_control control;
443
444     memset(&queryctrl, 0, sizeof(queryctrl));
445     queryctrl.id = V4L2_CID_BRIGHTNESS;
446
447     if (-1 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
448         if (errno != EINVAL) {
449             perror("VIDIOC_QUERYCTRL");
450             exit(EXIT_FAILURE);
451         } else {
452             printf("V4L2_CID_BRIGHTNESS is not supportedn");
453         }
454     } else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) {
455         printf("V4L2_CID_BRIGHTNESS is not supportedn");
456     } else {
457         memset(&control, 0, sizeof (control));
458         control.id = V4L2_CID_BRIGHTNESS;
459         control.value = queryctrl.default_value;
460
461         if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)) {
462             perror("VIDIOC_S_CTRL");
463             exit(EXIT_FAILURE);
464         }
465     }
466
467     memset(&control, 0, sizeof(control));
468     control.id = V4L2_CID_CONTRAST;
469
470     if (0 == ioctl(fd, VIDIOC_G_CTRL, &control)) {
471         control.value += 1;
472
473         /* The driver may clamp the value or return ERANGE, ignored here */
474
475         if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)
476             && errno != ERANGE) {
477             perror("VIDIOC_S_CTRL");
478             exit(EXIT_FAILURE);
479         }
480     /* Ignore if V4L2_CID_CONTRAST is unsupported */
481     } else if (errno != EINVAL) {
482         perror("VIDIOC_G_CTRL");
483         exit(EXIT_FAILURE);
484     }
485
486     control.id = V4L2_CID_AUDIO_MUTE;
487     control.value = 1; /* silence */
488
489     /* Errors ignored */
490     ioctl(fd, VIDIOC_S_CTRL, &control);
491
492 .. [#f1]
493    The use of ``V4L2_CID_PRIVATE_BASE`` is problematic because different
494    drivers may use the same ``V4L2_CID_PRIVATE_BASE`` ID for different
495    controls. This makes it hard to programatically set such controls
496    since the meaning of the control with that ID is driver dependent. In
497    order to resolve this drivers use unique IDs and the
498    ``V4L2_CID_PRIVATE_BASE`` IDs are mapped to those unique IDs by the
499    kernel. Consider these ``V4L2_CID_PRIVATE_BASE`` IDs as aliases to
500    the real IDs.
501
502    Many applications today still use the ``V4L2_CID_PRIVATE_BASE`` IDs
503    instead of using :ref:`VIDIOC_QUERYCTRL` with
504    the ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag to enumerate all IDs, so
505    support for ``V4L2_CID_PRIVATE_BASE`` is still around.