0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002
0003 .. _control:
0004
0005 *************
0006 User Controls
0007 *************
0008
0009 Devices typically have a number of user-settable controls such as
0010 brightness, saturation and so on, which would be presented to the user
0011 on a graphical user interface. But, different devices will have
0012 different controls available, and furthermore, the range of possible
0013 values, and the default value will vary from device to device. The
0014 control ioctls provide the information and a mechanism to create a nice
0015 user interface for these controls that will work correctly with any
0016 device.
0017
0018 All controls are accessed using an ID value. V4L2 defines several IDs
0019 for specific purposes. Drivers can also implement their own custom
0020 controls using ``V4L2_CID_PRIVATE_BASE`` [#f1]_ and higher values. The
0021 pre-defined control IDs have the prefix ``V4L2_CID_``, and are listed in
0022 :ref:`control-id`. The ID is used when querying the attributes of a
0023 control, and when getting or setting the current value.
0024
0025 Generally applications should present controls to the user without
0026 assumptions about their purpose. Each control comes with a name string
0027 the user is supposed to understand. When the purpose is non-intuitive
0028 the driver writer should provide a user manual, a user interface plug-in
0029 or a driver specific panel application. Predefined IDs were introduced
0030 to change a few controls programmatically, for example to mute a device
0031 during a channel switch.
0032
0033 Drivers may enumerate different controls after switching the current
0034 video input or output, tuner or modulator, or audio input or output.
0035 Different in the sense of other bounds, another default and current
0036 value, step size or other menu items. A control with a certain *custom*
0037 ID can also change name and type.
0038
0039 If a control is not applicable to the current configuration of the
0040 device (for example, it doesn't apply to the current video input)
0041 drivers set the ``V4L2_CTRL_FLAG_INACTIVE`` flag.
0042
0043 Control values are stored globally, they do not change when switching
0044 except to stay within the reported bounds. They also do not change e. g.
0045 when the device is opened or closed, when the tuner radio frequency is
0046 changed or generally never without application request.
0047
0048 V4L2 specifies an event mechanism to notify applications when controls
0049 change value (see
0050 :ref:`VIDIOC_SUBSCRIBE_EVENT`, event
0051 ``V4L2_EVENT_CTRL``), panel applications might want to make use of that
0052 in order to always reflect the correct control value.
0053
0054 All controls use machine endianness.
0055
0056
0057 .. _control-id:
0058
0059 Control IDs
0060 ===========
0061
0062 ``V4L2_CID_BASE``
0063 First predefined ID, equal to ``V4L2_CID_BRIGHTNESS``.
0064
0065 ``V4L2_CID_USER_BASE``
0066 Synonym of ``V4L2_CID_BASE``.
0067
0068 ``V4L2_CID_BRIGHTNESS`` ``(integer)``
0069 Picture brightness, or more precisely, the black level.
0070
0071 ``V4L2_CID_CONTRAST`` ``(integer)``
0072 Picture contrast or luma gain.
0073
0074 ``V4L2_CID_SATURATION`` ``(integer)``
0075 Picture color saturation or chroma gain.
0076
0077 ``V4L2_CID_HUE`` ``(integer)``
0078 Hue or color balance.
0079
0080 ``V4L2_CID_AUDIO_VOLUME`` ``(integer)``
0081 Overall audio volume. Note some drivers also provide an OSS or ALSA
0082 mixer interface.
0083
0084 ``V4L2_CID_AUDIO_BALANCE`` ``(integer)``
0085 Audio stereo balance. Minimum corresponds to all the way left,
0086 maximum to right.
0087
0088 ``V4L2_CID_AUDIO_BASS`` ``(integer)``
0089 Audio bass adjustment.
0090
0091 ``V4L2_CID_AUDIO_TREBLE`` ``(integer)``
0092 Audio treble adjustment.
0093
0094 ``V4L2_CID_AUDIO_MUTE`` ``(boolean)``
0095 Mute audio, i. e. set the volume to zero, however without affecting
0096 ``V4L2_CID_AUDIO_VOLUME``. Like ALSA drivers, V4L2 drivers must mute
0097 at load time to avoid excessive noise. Actually the entire device
0098 should be reset to a low power consumption state.
0099
0100 ``V4L2_CID_AUDIO_LOUDNESS`` ``(boolean)``
0101 Loudness mode (bass boost).
0102
0103 ``V4L2_CID_BLACK_LEVEL`` ``(integer)``
0104 Another name for brightness (not a synonym of
0105 ``V4L2_CID_BRIGHTNESS``). This control is deprecated and should not
0106 be used in new drivers and applications.
0107
0108 ``V4L2_CID_AUTO_WHITE_BALANCE`` ``(boolean)``
0109 Automatic white balance (cameras).
0110
0111 ``V4L2_CID_DO_WHITE_BALANCE`` ``(button)``
0112 This is an action control. When set (the value is ignored), the
0113 device will do a white balance and then hold the current setting.
0114 Contrast this with the boolean ``V4L2_CID_AUTO_WHITE_BALANCE``,
0115 which, when activated, keeps adjusting the white balance.
0116
0117 ``V4L2_CID_RED_BALANCE`` ``(integer)``
0118 Red chroma balance.
0119
0120 ``V4L2_CID_BLUE_BALANCE`` ``(integer)``
0121 Blue chroma balance.
0122
0123 ``V4L2_CID_GAMMA`` ``(integer)``
0124 Gamma adjust.
0125
0126 ``V4L2_CID_WHITENESS`` ``(integer)``
0127 Whiteness for grey-scale devices. This is a synonym for
0128 ``V4L2_CID_GAMMA``. This control is deprecated and should not be
0129 used in new drivers and applications.
0130
0131 ``V4L2_CID_EXPOSURE`` ``(integer)``
0132 Exposure (cameras). [Unit?]
0133
0134 ``V4L2_CID_AUTOGAIN`` ``(boolean)``
0135 Automatic gain/exposure control.
0136
0137 ``V4L2_CID_GAIN`` ``(integer)``
0138 Gain control.
0139
0140 Primarily used to control gain on e.g. TV tuners but also on
0141 webcams. Most devices control only digital gain with this control
0142 but on some this could include analogue gain as well. Devices that
0143 recognise the difference between digital and analogue gain use
0144 controls ``V4L2_CID_DIGITAL_GAIN`` and ``V4L2_CID_ANALOGUE_GAIN``.
0145
0146 ``V4L2_CID_HFLIP`` ``(boolean)``
0147 Mirror the picture horizontally.
0148
0149 ``V4L2_CID_VFLIP`` ``(boolean)``
0150 Mirror the picture vertically.
0151
0152 .. _v4l2-power-line-frequency:
0153
0154 ``V4L2_CID_POWER_LINE_FREQUENCY`` ``(enum)``
0155 Enables a power line frequency filter to avoid flicker. Possible
0156 values for ``enum v4l2_power_line_frequency`` are:
0157
0158 ========================================== ==
0159 ``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` 0
0160 ``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` 1
0161 ``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` 2
0162 ``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` 3
0163 ========================================== ==
0164
0165 ``V4L2_CID_HUE_AUTO`` ``(boolean)``
0166 Enables automatic hue control by the device. The effect of setting
0167 ``V4L2_CID_HUE`` while automatic hue control is enabled is
0168 undefined, drivers should ignore such request.
0169
0170 ``V4L2_CID_WHITE_BALANCE_TEMPERATURE`` ``(integer)``
0171 This control specifies the white balance settings as a color
0172 temperature in Kelvin. A driver should have a minimum of 2800
0173 (incandescent) to 6500 (daylight). For more information about color
0174 temperature see
0175 `Wikipedia <http://en.wikipedia.org/wiki/Color_temperature>`__.
0176
0177 ``V4L2_CID_SHARPNESS`` ``(integer)``
0178 Adjusts the sharpness filters in a camera. The minimum value
0179 disables the filters, higher values give a sharper picture.
0180
0181 ``V4L2_CID_BACKLIGHT_COMPENSATION`` ``(integer)``
0182 Adjusts the backlight compensation in a camera. The minimum value
0183 disables backlight compensation.
0184
0185 ``V4L2_CID_CHROMA_AGC`` ``(boolean)``
0186 Chroma automatic gain control.
0187
0188 ``V4L2_CID_CHROMA_GAIN`` ``(integer)``
0189 Adjusts the Chroma gain control (for use when chroma AGC is
0190 disabled).
0191
0192 ``V4L2_CID_COLOR_KILLER`` ``(boolean)``
0193 Enable the color killer (i. e. force a black & white image in case
0194 of a weak video signal).
0195
0196 .. _v4l2-colorfx:
0197
0198 ``V4L2_CID_COLORFX`` ``(enum)``
0199 Selects a color effect. The following values are defined:
0200
0201
0202
0203 .. tabularcolumns:: |p{5.7cm}|p{11.8cm}|
0204
0205 .. flat-table::
0206 :header-rows: 0
0207 :stub-columns: 0
0208 :widths: 11 24
0209
0210 * - ``V4L2_COLORFX_NONE``
0211 - Color effect is disabled.
0212 * - ``V4L2_COLORFX_ANTIQUE``
0213 - An aging (old photo) effect.
0214 * - ``V4L2_COLORFX_ART_FREEZE``
0215 - Frost color effect.
0216 * - ``V4L2_COLORFX_AQUA``
0217 - Water color, cool tone.
0218 * - ``V4L2_COLORFX_BW``
0219 - Black and white.
0220 * - ``V4L2_COLORFX_EMBOSS``
0221 - Emboss, the highlights and shadows replace light/dark boundaries
0222 and low contrast areas are set to a gray background.
0223 * - ``V4L2_COLORFX_GRASS_GREEN``
0224 - Grass green.
0225 * - ``V4L2_COLORFX_NEGATIVE``
0226 - Negative.
0227 * - ``V4L2_COLORFX_SEPIA``
0228 - Sepia tone.
0229 * - ``V4L2_COLORFX_SKETCH``
0230 - Sketch.
0231 * - ``V4L2_COLORFX_SKIN_WHITEN``
0232 - Skin whiten.
0233 * - ``V4L2_COLORFX_SKY_BLUE``
0234 - Sky blue.
0235 * - ``V4L2_COLORFX_SOLARIZATION``
0236 - Solarization, the image is partially reversed in tone, only color
0237 values above or below a certain threshold are inverted.
0238 * - ``V4L2_COLORFX_SILHOUETTE``
0239 - Silhouette (outline).
0240 * - ``V4L2_COLORFX_VIVID``
0241 - Vivid colors.
0242 * - ``V4L2_COLORFX_SET_CBCR``
0243 - The Cb and Cr chroma components are replaced by fixed coefficients
0244 determined by ``V4L2_CID_COLORFX_CBCR`` control.
0245 * - ``V4L2_COLORFX_SET_RGB``
0246 - The RGB components are replaced by the fixed RGB components determined
0247 by ``V4L2_CID_COLORFX_RGB`` control.
0248
0249
0250 ``V4L2_CID_COLORFX_RGB`` ``(integer)``
0251 Determines the Red, Green, and Blue coefficients for
0252 ``V4L2_COLORFX_SET_RGB`` color effect.
0253 Bits [7:0] of the supplied 32 bit value are interpreted as Blue component,
0254 bits [15:8] as Green component, bits [23:16] as Red component, and
0255 bits [31:24] must be zero.
0256
0257 ``V4L2_CID_COLORFX_CBCR`` ``(integer)``
0258 Determines the Cb and Cr coefficients for ``V4L2_COLORFX_SET_CBCR``
0259 color effect. Bits [7:0] of the supplied 32 bit value are
0260 interpreted as Cr component, bits [15:8] as Cb component and bits
0261 [31:16] must be zero.
0262
0263 ``V4L2_CID_AUTOBRIGHTNESS`` ``(boolean)``
0264 Enable Automatic Brightness.
0265
0266 ``V4L2_CID_ROTATE`` ``(integer)``
0267 Rotates the image by specified angle. Common angles are 90, 270 and
0268 180. Rotating the image to 90 and 270 will reverse the height and
0269 width of the display window. It is necessary to set the new height
0270 and width of the picture using the
0271 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl according to the
0272 rotation angle selected.
0273
0274 ``V4L2_CID_BG_COLOR`` ``(integer)``
0275 Sets the background color on the current output device. Background
0276 color needs to be specified in the RGB24 format. The supplied 32 bit
0277 value is interpreted as bits 0-7 Red color information, bits 8-15
0278 Green color information, bits 16-23 Blue color information and bits
0279 24-31 must be zero.
0280
0281 ``V4L2_CID_ILLUMINATORS_1 V4L2_CID_ILLUMINATORS_2`` ``(boolean)``
0282 Switch on or off the illuminator 1 or 2 of the device (usually a
0283 microscope).
0284
0285 ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE`` ``(integer)``
0286 This is a read-only control that can be read by the application and
0287 used as a hint to determine the number of CAPTURE buffers to pass to
0288 REQBUFS. The value is the minimum number of CAPTURE buffers that is
0289 necessary for hardware to work.
0290
0291 ``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT`` ``(integer)``
0292 This is a read-only control that can be read by the application and
0293 used as a hint to determine the number of OUTPUT buffers to pass to
0294 REQBUFS. The value is the minimum number of OUTPUT buffers that is
0295 necessary for hardware to work.
0296
0297 .. _v4l2-alpha-component:
0298
0299 ``V4L2_CID_ALPHA_COMPONENT`` ``(integer)``
0300 Sets the alpha color component. When a capture device (or capture
0301 queue of a mem-to-mem device) produces a frame format that includes
0302 an alpha component (e.g.
0303 :ref:`packed RGB image formats <pixfmt-rgb>`) and the alpha value
0304 is not defined by the device or the mem-to-mem input data this
0305 control lets you select the alpha component value of all pixels.
0306 When an output device (or output queue of a mem-to-mem device)
0307 consumes a frame format that doesn't include an alpha component and
0308 the device supports alpha channel processing this control lets you
0309 set the alpha component value of all pixels for further processing
0310 in the device.
0311
0312 ``V4L2_CID_LASTP1``
0313 End of the predefined control IDs (currently
0314 ``V4L2_CID_ALPHA_COMPONENT`` + 1).
0315
0316 ``V4L2_CID_PRIVATE_BASE``
0317 ID of the first custom (driver specific) control. Applications
0318 depending on particular custom controls should check the driver name
0319 and version, see :ref:`querycap`.
0320
0321 Applications can enumerate the available controls with the
0322 :ref:`VIDIOC_QUERYCTRL` and
0323 :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>` ioctls, get and set a
0324 control value with the :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
0325 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls. Drivers must implement
0326 ``VIDIOC_QUERYCTRL``, ``VIDIOC_G_CTRL`` and ``VIDIOC_S_CTRL`` when the
0327 device has one or more controls, ``VIDIOC_QUERYMENU`` when it has one or
0328 more menu type controls.
0329
0330
0331 .. _enum_all_controls:
0332
0333 Example: Enumerating all controls
0334 =================================
0335
0336 .. code-block:: c
0337
0338 struct v4l2_queryctrl queryctrl;
0339 struct v4l2_querymenu querymenu;
0340
0341 static void enumerate_menu(__u32 id)
0342 {
0343 printf(" Menu items:\\n");
0344
0345 memset(&querymenu, 0, sizeof(querymenu));
0346 querymenu.id = id;
0347
0348 for (querymenu.index = queryctrl.minimum;
0349 querymenu.index <= queryctrl.maximum;
0350 querymenu.index++) {
0351 if (0 == ioctl(fd, VIDIOC_QUERYMENU, &querymenu)) {
0352 printf(" %s\\n", querymenu.name);
0353 }
0354 }
0355 }
0356
0357 memset(&queryctrl, 0, sizeof(queryctrl));
0358
0359 queryctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
0360 while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
0361 if (!(queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)) {
0362 printf("Control %s\\n", queryctrl.name);
0363
0364 if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
0365 enumerate_menu(queryctrl.id);
0366 }
0367
0368 queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
0369 }
0370 if (errno != EINVAL) {
0371 perror("VIDIOC_QUERYCTRL");
0372 exit(EXIT_FAILURE);
0373 }
0374
0375 Example: Enumerating all controls including compound controls
0376 =============================================================
0377
0378 .. code-block:: c
0379
0380 struct v4l2_query_ext_ctrl query_ext_ctrl;
0381
0382 memset(&query_ext_ctrl, 0, sizeof(query_ext_ctrl));
0383
0384 query_ext_ctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL | V4L2_CTRL_FLAG_NEXT_COMPOUND;
0385 while (0 == ioctl(fd, VIDIOC_QUERY_EXT_CTRL, &query_ext_ctrl)) {
0386 if (!(query_ext_ctrl.flags & V4L2_CTRL_FLAG_DISABLED)) {
0387 printf("Control %s\\n", query_ext_ctrl.name);
0388
0389 if (query_ext_ctrl.type == V4L2_CTRL_TYPE_MENU)
0390 enumerate_menu(query_ext_ctrl.id);
0391 }
0392
0393 query_ext_ctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL | V4L2_CTRL_FLAG_NEXT_COMPOUND;
0394 }
0395 if (errno != EINVAL) {
0396 perror("VIDIOC_QUERY_EXT_CTRL");
0397 exit(EXIT_FAILURE);
0398 }
0399
0400 Example: Enumerating all user controls (old style)
0401 ==================================================
0402
0403 .. code-block:: c
0404
0405
0406 memset(&queryctrl, 0, sizeof(queryctrl));
0407
0408 for (queryctrl.id = V4L2_CID_BASE;
0409 queryctrl.id < V4L2_CID_LASTP1;
0410 queryctrl.id++) {
0411 if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
0412 if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
0413 continue;
0414
0415 printf("Control %s\\n", queryctrl.name);
0416
0417 if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
0418 enumerate_menu(queryctrl.id);
0419 } else {
0420 if (errno == EINVAL)
0421 continue;
0422
0423 perror("VIDIOC_QUERYCTRL");
0424 exit(EXIT_FAILURE);
0425 }
0426 }
0427
0428 for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
0429 queryctrl.id++) {
0430 if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
0431 if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
0432 continue;
0433
0434 printf("Control %s\\n", queryctrl.name);
0435
0436 if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
0437 enumerate_menu(queryctrl.id);
0438 } else {
0439 if (errno == EINVAL)
0440 break;
0441
0442 perror("VIDIOC_QUERYCTRL");
0443 exit(EXIT_FAILURE);
0444 }
0445 }
0446
0447
0448 Example: Changing controls
0449 ==========================
0450
0451 .. code-block:: c
0452
0453 struct v4l2_queryctrl queryctrl;
0454 struct v4l2_control control;
0455
0456 memset(&queryctrl, 0, sizeof(queryctrl));
0457 queryctrl.id = V4L2_CID_BRIGHTNESS;
0458
0459 if (-1 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
0460 if (errno != EINVAL) {
0461 perror("VIDIOC_QUERYCTRL");
0462 exit(EXIT_FAILURE);
0463 } else {
0464 printf("V4L2_CID_BRIGHTNESS is not supported\n");
0465 }
0466 } else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) {
0467 printf("V4L2_CID_BRIGHTNESS is not supported\n");
0468 } else {
0469 memset(&control, 0, sizeof (control));
0470 control.id = V4L2_CID_BRIGHTNESS;
0471 control.value = queryctrl.default_value;
0472
0473 if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)) {
0474 perror("VIDIOC_S_CTRL");
0475 exit(EXIT_FAILURE);
0476 }
0477 }
0478
0479 memset(&control, 0, sizeof(control));
0480 control.id = V4L2_CID_CONTRAST;
0481
0482 if (0 == ioctl(fd, VIDIOC_G_CTRL, &control)) {
0483 control.value += 1;
0484
0485 /* The driver may clamp the value or return ERANGE, ignored here */
0486
0487 if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)
0488 && errno != ERANGE) {
0489 perror("VIDIOC_S_CTRL");
0490 exit(EXIT_FAILURE);
0491 }
0492 /* Ignore if V4L2_CID_CONTRAST is unsupported */
0493 } else if (errno != EINVAL) {
0494 perror("VIDIOC_G_CTRL");
0495 exit(EXIT_FAILURE);
0496 }
0497
0498 control.id = V4L2_CID_AUDIO_MUTE;
0499 control.value = 1; /* silence */
0500
0501 /* Errors ignored */
0502 ioctl(fd, VIDIOC_S_CTRL, &control);
0503
0504 .. [#f1]
0505 The use of ``V4L2_CID_PRIVATE_BASE`` is problematic because different
0506 drivers may use the same ``V4L2_CID_PRIVATE_BASE`` ID for different
0507 controls. This makes it hard to programmatically set such controls
0508 since the meaning of the control with that ID is driver dependent. In
0509 order to resolve this drivers use unique IDs and the
0510 ``V4L2_CID_PRIVATE_BASE`` IDs are mapped to those unique IDs by the
0511 kernel. Consider these ``V4L2_CID_PRIVATE_BASE`` IDs as aliases to
0512 the real IDs.
0513
0514 Many applications today still use the ``V4L2_CID_PRIVATE_BASE`` IDs
0515 instead of using :ref:`VIDIOC_QUERYCTRL` with
0516 the ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag to enumerate all IDs, so
0517 support for ``V4L2_CID_PRIVATE_BASE`` is still around.
