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

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/userspace-api/media/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _control:
  11
  12 *************
  13 User Controls
  14 *************
  15
  16 Devices typically have a number of user-settable controls such as
  17 brightness, saturation and so on, which would be presented to the user
  18 on a graphical user interface. But, different devices will have
  19 different controls available, and furthermore, the range of possible
  20 values, and the default value will vary from device to device. The
  21 control ioctls provide the information and a mechanism to create a nice
  22 user interface for these controls that will work correctly with any
  23 device.
  24
  25 All controls are accessed using an ID value. V4L2 defines several IDs
  26 for specific purposes. Drivers can also implement their own custom
  27 controls using ``V4L2_CID_PRIVATE_BASE``  [#f1]_ and higher values. The
  28 pre-defined control IDs have the prefix ``V4L2_CID_``, and are listed in
  29 :ref:`control-id`. The ID is used when querying the attributes of a
  30 control, and when getting or setting the current value.
  31
  32 Generally applications should present controls to the user without
  33 assumptions about their purpose. Each control comes with a name string
  34 the user is supposed to understand. When the purpose is non-intuitive
  35 the driver writer should provide a user manual, a user interface plug-in
  36 or a driver specific panel application. Predefined IDs were introduced
  37 to change a few controls programmatically, for example to mute a device
  38 during a channel switch.
  39
  40 Drivers may enumerate different controls after switching the current
  41 video input or output, tuner or modulator, or audio input or output.
  42 Different in the sense of other bounds, another default and current
  43 value, step size or other menu items. A control with a certain *custom*
  44 ID can also change name and type.
  45
  46 If a control is not applicable to the current configuration of the
  47 device (for example, it doesn't apply to the current video input)
  48 drivers set the ``V4L2_CTRL_FLAG_INACTIVE`` flag.
  49
  50 Control values are stored globally, they do not change when switching
  51 except to stay within the reported bounds. They also do not change e. g.
  52 when the device is opened or closed, when the tuner radio frequency is
  53 changed or generally never without application request.
  54
  55 V4L2 specifies an event mechanism to notify applications when controls
  56 change value (see
  57 :ref:`VIDIOC_SUBSCRIBE_EVENT`, event
  58 ``V4L2_EVENT_CTRL``), panel applications might want to make use of that
  59 in order to always reflect the correct control value.
  60
  61 All controls use machine endianness.
  62
  63
  64 .. _control-id:
  65
  66 Control IDs
  67 ===========
  68
  69 ``V4L2_CID_BASE``
  70     First predefined ID, equal to ``V4L2_CID_BRIGHTNESS``.
  71
  72 ``V4L2_CID_USER_BASE``
  73     Synonym of ``V4L2_CID_BASE``.
  74
  75 ``V4L2_CID_BRIGHTNESS`` ``(integer)``
  76     Picture brightness, or more precisely, the black level.
  77
  78 ``V4L2_CID_CONTRAST`` ``(integer)``
  79     Picture contrast or luma gain.
  80
  81 ``V4L2_CID_SATURATION`` ``(integer)``
  82     Picture color saturation or chroma gain.
  83
  84 ``V4L2_CID_HUE`` ``(integer)``
  85     Hue or color balance.
  86
  87 ``V4L2_CID_AUDIO_VOLUME`` ``(integer)``
  88     Overall audio volume. Note some drivers also provide an OSS or ALSA
  89     mixer interface.
  90
  91 ``V4L2_CID_AUDIO_BALANCE`` ``(integer)``
  92     Audio stereo balance. Minimum corresponds to all the way left,
  93     maximum to right.
  94
  95 ``V4L2_CID_AUDIO_BASS`` ``(integer)``
  96     Audio bass adjustment.
  97
  98 ``V4L2_CID_AUDIO_TREBLE`` ``(integer)``
  99     Audio treble adjustment.
 100
 101 ``V4L2_CID_AUDIO_MUTE`` ``(boolean)``
 102     Mute audio, i. e. set the volume to zero, however without affecting
 103     ``V4L2_CID_AUDIO_VOLUME``. Like ALSA drivers, V4L2 drivers must mute
 104     at load time to avoid excessive noise. Actually the entire device
 105     should be reset to a low power consumption state.
 106
 107 ``V4L2_CID_AUDIO_LOUDNESS`` ``(boolean)``
 108     Loudness mode (bass boost).
 109
 110 ``V4L2_CID_BLACK_LEVEL`` ``(integer)``
 111     Another name for brightness (not a synonym of
 112     ``V4L2_CID_BRIGHTNESS``). This control is deprecated and should not
 113     be used in new drivers and applications.
 114
 115 ``V4L2_CID_AUTO_WHITE_BALANCE`` ``(boolean)``
 116     Automatic white balance (cameras).
 117
 118 ``V4L2_CID_DO_WHITE_BALANCE`` ``(button)``
 119     This is an action control. When set (the value is ignored), the
 120     device will do a white balance and then hold the current setting.
 121     Contrast this with the boolean ``V4L2_CID_AUTO_WHITE_BALANCE``,
 122     which, when activated, keeps adjusting the white balance.
 123
 124 ``V4L2_CID_RED_BALANCE`` ``(integer)``
 125     Red chroma balance.
 126
 127 ``V4L2_CID_BLUE_BALANCE`` ``(integer)``
 128     Blue chroma balance.
 129
 130 ``V4L2_CID_GAMMA`` ``(integer)``
 131     Gamma adjust.
 132
 133 ``V4L2_CID_WHITENESS`` ``(integer)``
 134     Whiteness for grey-scale devices. This is a synonym for
 135     ``V4L2_CID_GAMMA``. This control is deprecated and should not be
 136     used in new drivers and applications.
 137
 138 ``V4L2_CID_EXPOSURE`` ``(integer)``
 139     Exposure (cameras). [Unit?]
 140
 141 ``V4L2_CID_AUTOGAIN`` ``(boolean)``
 142     Automatic gain/exposure control.
 143
 144 ``V4L2_CID_GAIN`` ``(integer)``
 145     Gain control.
 146
 147     Primarily used to control gain on e.g. TV tuners but also on
 148     webcams. Most devices control only digital gain with this control
 149     but on some this could include analogue gain as well. Devices that
 150     recognise the difference between digital and analogue gain use
 151     controls ``V4L2_CID_DIGITAL_GAIN`` and ``V4L2_CID_ANALOGUE_GAIN``.
 152
 153 ``V4L2_CID_HFLIP`` ``(boolean)``
 154     Mirror the picture horizontally.
 155
 156 ``V4L2_CID_VFLIP`` ``(boolean)``
 157     Mirror the picture vertically.
 158
 159 .. _v4l2-power-line-frequency:
 160
 161 ``V4L2_CID_POWER_LINE_FREQUENCY`` ``(enum)``
 162     Enables a power line frequency filter to avoid flicker. Possible
 163     values for ``enum v4l2_power_line_frequency`` are:
 164     ``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` (0),
 165     ``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` (1),
 166     ``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` (2) and
 167     ``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` (3).
 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.5cm}|p{12cm}|
 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
 250
 251
 252 ``V4L2_CID_COLORFX_CBCR`` ``(integer)``
 253     Determines the Cb and Cr coefficients for ``V4L2_COLORFX_SET_CBCR``
 254     color effect. Bits [7:0] of the supplied 32 bit value are
 255     interpreted as Cr component, bits [15:8] as Cb component and bits
 256     [31:16] must be zero.
 257
 258 ``V4L2_CID_AUTOBRIGHTNESS`` ``(boolean)``
 259     Enable Automatic Brightness.
 260
 261 ``V4L2_CID_ROTATE`` ``(integer)``
 262     Rotates the image by specified angle. Common angles are 90, 270 and
 263     180. Rotating the image to 90 and 270 will reverse the height and
 264     width of the display window. It is necessary to set the new height
 265     and width of the picture using the
 266     :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl according to the
 267     rotation angle selected.
 268
 269 ``V4L2_CID_BG_COLOR`` ``(integer)``
 270     Sets the background color on the current output device. Background
 271     color needs to be specified in the RGB24 format. The supplied 32 bit
 272     value is interpreted as bits 0-7 Red color information, bits 8-15
 273     Green color information, bits 16-23 Blue color information and bits
 274     24-31 must be zero.
 275
 276 ``V4L2_CID_ILLUMINATORS_1 V4L2_CID_ILLUMINATORS_2`` ``(boolean)``
 277     Switch on or off the illuminator 1 or 2 of the device (usually a
 278     microscope).
 279
 280 ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE`` ``(integer)``
 281     This is a read-only control that can be read by the application and
 282     used as a hint to determine the number of CAPTURE buffers to pass to
 283     REQBUFS. The value is the minimum number of CAPTURE buffers that is
 284     necessary for hardware to work.
 285
 286 ``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT`` ``(integer)``
 287     This is a read-only control that can be read by the application and
 288     used as a hint to determine the number of OUTPUT buffers to pass to
 289     REQBUFS. The value is the minimum number of OUTPUT buffers that is
 290     necessary for hardware to work.
 291
 292 .. _v4l2-alpha-component:
 293
 294 ``V4L2_CID_ALPHA_COMPONENT`` ``(integer)``
 295     Sets the alpha color component. When a capture device (or capture
 296     queue of a mem-to-mem device) produces a frame format that includes
 297     an alpha component (e.g.
 298     :ref:`packed RGB image formats <pixfmt-rgb>`) and the alpha value
 299     is not defined by the device or the mem-to-mem input data this
 300     control lets you select the alpha component value of all pixels.
 301     When an output device (or output queue of a mem-to-mem device)
 302     consumes a frame format that doesn't include an alpha component and
 303     the device supports alpha channel processing this control lets you
 304     set the alpha component value of all pixels for further processing
 305     in the device.
 306
 307 ``V4L2_CID_LASTP1``
 308     End of the predefined control IDs (currently
 309     ``V4L2_CID_ALPHA_COMPONENT`` + 1).
 310
 311 ``V4L2_CID_PRIVATE_BASE``
 312     ID of the first custom (driver specific) control. Applications
 313     depending on particular custom controls should check the driver name
 314     and version, see :ref:`querycap`.
 315
 316 Applications can enumerate the available controls with the
 317 :ref:`VIDIOC_QUERYCTRL` and
 318 :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>` ioctls, get and set a
 319 control value with the :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
 320 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls. Drivers must implement
 321 ``VIDIOC_QUERYCTRL``, ``VIDIOC_G_CTRL`` and ``VIDIOC_S_CTRL`` when the
 322 device has one or more controls, ``VIDIOC_QUERYMENU`` when it has one or
 323 more menu type controls.
 324
 325
 326 .. _enum_all_controls:
 327
 328 Example: Enumerating all controls
 329 =================================
 330
 331 .. code-block:: c
 332
 333     struct v4l2_queryctrl queryctrl;
 334     struct v4l2_querymenu querymenu;
 335
 336     static void enumerate_menu(__u32 id)
 337     {
 338         printf("  Menu items:\\n");
 339
 340         memset(&querymenu, 0, sizeof(querymenu));
 341         querymenu.id = id;
 342
 343         for (querymenu.index = queryctrl.minimum;
 344              querymenu.index <= queryctrl.maximum;
 345              querymenu.index++) {
 346             if (0 == ioctl(fd, VIDIOC_QUERYMENU, &querymenu)) {
 347                 printf("  %s\\n", querymenu.name);
 348             }
 349         }
 350     }
 351
 352     memset(&queryctrl, 0, sizeof(queryctrl));
 353
 354     queryctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
 355     while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
 356         if (!(queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)) {
 357             printf("Control %s\\n", queryctrl.name);
 358
 359             if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
 360                 enumerate_menu(queryctrl.id);
 361         }
 362
 363         queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
 364     }
 365     if (errno != EINVAL) {
 366         perror("VIDIOC_QUERYCTRL");
 367         exit(EXIT_FAILURE);
 368     }
 369
 370 Example: Enumerating all controls including compound controls
 371 =============================================================
 372
 373 .. code-block:: c
 374
 375     struct v4l2_query_ext_ctrl query_ext_ctrl;
 376
 377     memset(&query_ext_ctrl, 0, sizeof(query_ext_ctrl));
 378
 379     query_ext_ctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL | V4L2_CTRL_FLAG_NEXT_COMPOUND;
 380     while (0 == ioctl(fd, VIDIOC_QUERY_EXT_CTRL, &query_ext_ctrl)) {
 381         if (!(query_ext_ctrl.flags & V4L2_CTRL_FLAG_DISABLED)) {
 382             printf("Control %s\\n", query_ext_ctrl.name);
 383
 384             if (query_ext_ctrl.type == V4L2_CTRL_TYPE_MENU)
 385                 enumerate_menu(query_ext_ctrl.id);
 386         }
 387
 388         query_ext_ctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL | V4L2_CTRL_FLAG_NEXT_COMPOUND;
 389     }
 390     if (errno != EINVAL) {
 391         perror("VIDIOC_QUERY_EXT_CTRL");
 392         exit(EXIT_FAILURE);
 393     }
 394
 395 Example: Enumerating all user controls (old style)
 396 ==================================================
 397
 398 .. code-block:: c
 399
 400
 401     memset(&queryctrl, 0, sizeof(queryctrl));
 402
 403     for (queryctrl.id = V4L2_CID_BASE;
 404          queryctrl.id < V4L2_CID_LASTP1;
 405          queryctrl.id++) {
 406         if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
 407             if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
 408                 continue;
 409
 410             printf("Control %s\\n", queryctrl.name);
 411
 412             if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
 413                 enumerate_menu(queryctrl.id);
 414         } else {
 415             if (errno == EINVAL)
 416                 continue;
 417
 418             perror("VIDIOC_QUERYCTRL");
 419             exit(EXIT_FAILURE);
 420         }
 421     }
 422
 423     for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
 424          queryctrl.id++) {
 425         if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
 426             if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
 427                 continue;
 428
 429             printf("Control %s\\n", queryctrl.name);
 430
 431             if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
 432                 enumerate_menu(queryctrl.id);
 433         } else {
 434             if (errno == EINVAL)
 435                 break;
 436
 437             perror("VIDIOC_QUERYCTRL");
 438             exit(EXIT_FAILURE);
 439         }
 440     }
 441
 442
 443 Example: Changing controls
 444 ==========================
 445
 446 .. code-block:: c
 447
 448     struct v4l2_queryctrl queryctrl;
 449     struct v4l2_control control;
 450
 451     memset(&queryctrl, 0, sizeof(queryctrl));
 452     queryctrl.id = V4L2_CID_BRIGHTNESS;
 453
 454     if (-1 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
 455         if (errno != EINVAL) {
 456             perror("VIDIOC_QUERYCTRL");
 457             exit(EXIT_FAILURE);
 458         } else {
 459             printf("V4L2_CID_BRIGHTNESS is not supportedn");
 460         }
 461     } else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) {
 462         printf("V4L2_CID_BRIGHTNESS is not supportedn");
 463     } else {
 464         memset(&control, 0, sizeof (control));
 465         control.id = V4L2_CID_BRIGHTNESS;
 466         control.value = queryctrl.default_value;
 467
 468         if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)) {
 469             perror("VIDIOC_S_CTRL");
 470             exit(EXIT_FAILURE);
 471         }
 472     }
 473
 474     memset(&control, 0, sizeof(control));
 475     control.id = V4L2_CID_CONTRAST;
 476
 477     if (0 == ioctl(fd, VIDIOC_G_CTRL, &control)) {
 478         control.value += 1;
 479
 480         /* The driver may clamp the value or return ERANGE, ignored here */
 481
 482         if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)
 483             && errno != ERANGE) {
 484             perror("VIDIOC_S_CTRL");
 485             exit(EXIT_FAILURE);
 486         }
 487     /* Ignore if V4L2_CID_CONTRAST is unsupported */
 488     } else if (errno != EINVAL) {
 489         perror("VIDIOC_G_CTRL");
 490         exit(EXIT_FAILURE);
 491     }
 492
 493     control.id = V4L2_CID_AUDIO_MUTE;
 494     control.value = 1; /* silence */
 495
 496     /* Errors ignored */
 497     ioctl(fd, VIDIOC_S_CTRL, &control);
 498
 499 .. [#f1]
 500    The use of ``V4L2_CID_PRIVATE_BASE`` is problematic because different
 501    drivers may use the same ``V4L2_CID_PRIVATE_BASE`` ID for different
 502    controls. This makes it hard to programmatically set such controls
 503    since the meaning of the control with that ID is driver dependent. In
 504    order to resolve this drivers use unique IDs and the
 505    ``V4L2_CID_PRIVATE_BASE`` IDs are mapped to those unique IDs by the
 506    kernel. Consider these ``V4L2_CID_PRIVATE_BASE`` IDs as aliases to
 507    the real IDs.
 508
 509    Many applications today still use the ``V4L2_CID_PRIVATE_BASE`` IDs
 510    instead of using :ref:`VIDIOC_QUERYCTRL` with
 511    the ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag to enumerate all IDs, so
 512    support for ``V4L2_CID_PRIVATE_BASE`` is still around.