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

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   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:
 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
 325 Applications can enumerate the available controls with the
 326 :ref:`VIDIOC_QUERYCTRL` and
 327 :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>` ioctls, get and set a
 328 control 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
 331 device has one or more controls, ``VIDIOC_QUERYMENU`` when it has one or
 332 more menu type controls.
 333
 334
 335 .. _enum_all_controls:
 336
 337 Example: 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
 379 Example: 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
 404 Example: 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
 452 Example: 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.