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 ``V4L2_CID_HFLIP`` ``(boolean)``
 141     Mirror the picture horizontally.
 142
 143 ``V4L2_CID_VFLIP`` ``(boolean)``
 144     Mirror the picture vertically.
 145
 146 .. _v4l2-power-line-frequency:
 147
 148 ``V4L2_CID_POWER_LINE_FREQUENCY`` ``(enum)``
 149     Enables a power line frequency filter to avoid flicker. Possible
 150     values for ``enum v4l2_power_line_frequency`` are:
 151     ``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` (0),
 152     ``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` (1),
 153     ``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` (2) and
 154     ``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` (3).
 155
 156 ``V4L2_CID_HUE_AUTO`` ``(boolean)``
 157     Enables automatic hue control by the device. The effect of setting
 158     ``V4L2_CID_HUE`` while automatic hue control is enabled is
 159     undefined, drivers should ignore such request.
 160
 161 ``V4L2_CID_WHITE_BALANCE_TEMPERATURE`` ``(integer)``
 162     This control specifies the white balance settings as a color
 163     temperature in Kelvin. A driver should have a minimum of 2800
 164     (incandescent) to 6500 (daylight). For more information about color
 165     temperature see
 166     `Wikipedia <http://en.wikipedia.org/wiki/Color_temperature>`__.
 167
 168 ``V4L2_CID_SHARPNESS`` ``(integer)``
 169     Adjusts the sharpness filters in a camera. The minimum value
 170     disables the filters, higher values give a sharper picture.
 171
 172 ``V4L2_CID_BACKLIGHT_COMPENSATION`` ``(integer)``
 173     Adjusts the backlight compensation in a camera. The minimum value
 174     disables backlight compensation.
 175
 176 ``V4L2_CID_CHROMA_AGC`` ``(boolean)``
 177     Chroma automatic gain control.
 178
 179 ``V4L2_CID_CHROMA_GAIN`` ``(integer)``
 180     Adjusts the Chroma gain control (for use when chroma AGC is
 181     disabled).
 182
 183 ``V4L2_CID_COLOR_KILLER`` ``(boolean)``
 184     Enable the color killer (i. e. force a black & white image in case
 185     of a weak video signal).
 186
 187 .. _v4l2-colorfx:
 188
 189 ``V4L2_CID_COLORFX`` ``(enum)``
 190     Selects a color effect. The following values are defined:
 191
 192
 193
 194 .. tabularcolumns:: |p{5.5cm}|p{12cm}|
 195
 196 .. flat-table::
 197     :header-rows:  0
 198     :stub-columns: 0
 199     :widths: 11 24
 200
 201     -  .. row 1
 202
 203        -  ``V4L2_COLORFX_NONE``
 204
 205        -  Color effect is disabled.
 206
 207     -  .. row 2
 208
 209        -  ``V4L2_COLORFX_ANTIQUE``
 210
 211        -  An aging (old photo) effect.
 212
 213     -  .. row 3
 214
 215        -  ``V4L2_COLORFX_ART_FREEZE``
 216
 217        -  Frost color effect.
 218
 219     -  .. row 4
 220
 221        -  ``V4L2_COLORFX_AQUA``
 222
 223        -  Water color, cool tone.
 224
 225     -  .. row 5
 226
 227        -  ``V4L2_COLORFX_BW``
 228
 229        -  Black and white.
 230
 231     -  .. row 6
 232
 233        -  ``V4L2_COLORFX_EMBOSS``
 234
 235        -  Emboss, the highlights and shadows replace light/dark boundaries
 236           and low contrast areas are set to a gray background.
 237
 238     -  .. row 7
 239
 240        -  ``V4L2_COLORFX_GRASS_GREEN``
 241
 242        -  Grass green.
 243
 244     -  .. row 8
 245
 246        -  ``V4L2_COLORFX_NEGATIVE``
 247
 248        -  Negative.
 249
 250     -  .. row 9
 251
 252        -  ``V4L2_COLORFX_SEPIA``
 253
 254        -  Sepia tone.
 255
 256     -  .. row 10
 257
 258        -  ``V4L2_COLORFX_SKETCH``
 259
 260        -  Sketch.
 261
 262     -  .. row 11
 263
 264        -  ``V4L2_COLORFX_SKIN_WHITEN``
 265
 266        -  Skin whiten.
 267
 268     -  .. row 12
 269
 270        -  ``V4L2_COLORFX_SKY_BLUE``
 271
 272        -  Sky blue.
 273
 274     -  .. row 13
 275
 276        -  ``V4L2_COLORFX_SOLARIZATION``
 277
 278        -  Solarization, the image is partially reversed in tone, only color
 279           values above or below a certain threshold are inverted.
 280
 281     -  .. row 14
 282
 283        -  ``V4L2_COLORFX_SILHOUETTE``
 284
 285        -  Silhouette (outline).
 286
 287     -  .. row 15
 288
 289        -  ``V4L2_COLORFX_VIVID``
 290
 291        -  Vivid colors.
 292
 293     -  .. row 16
 294
 295        -  ``V4L2_COLORFX_SET_CBCR``
 296
 297        -  The Cb and Cr chroma components are replaced by fixed coefficients
 298           determined by ``V4L2_CID_COLORFX_CBCR`` control.
 299
 300
 301
 302 ``V4L2_CID_COLORFX_CBCR`` ``(integer)``
 303     Determines the Cb and Cr coefficients for ``V4L2_COLORFX_SET_CBCR``
 304     color effect. Bits [7:0] of the supplied 32 bit value are
 305     interpreted as Cr component, bits [15:8] as Cb component and bits
 306     [31:16] must be zero.
 307
 308 ``V4L2_CID_AUTOBRIGHTNESS`` ``(boolean)``
 309     Enable Automatic Brightness.
 310
 311 ``V4L2_CID_ROTATE`` ``(integer)``
 312     Rotates the image by specified angle. Common angles are 90, 270 and
 313     180. Rotating the image to 90 and 270 will reverse the height and
 314     width of the display window. It is necessary to set the new height
 315     and width of the picture using the
 316     :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl according to the
 317     rotation angle selected.
 318
 319 ``V4L2_CID_BG_COLOR`` ``(integer)``
 320     Sets the background color on the current output device. Background
 321     color needs to be specified in the RGB24 format. The supplied 32 bit
 322     value is interpreted as bits 0-7 Red color information, bits 8-15
 323     Green color information, bits 16-23 Blue color information and bits
 324     24-31 must be zero.
 325
 326 ``V4L2_CID_ILLUMINATORS_1 V4L2_CID_ILLUMINATORS_2`` ``(boolean)``
 327     Switch on or off the illuminator 1 or 2 of the device (usually a
 328     microscope).
 329
 330 ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE`` ``(integer)``
 331     This is a read-only control that can be read by the application and
 332     used as a hint to determine the number of CAPTURE buffers to pass to
 333     REQBUFS. The value is the minimum number of CAPTURE buffers that is
 334     necessary for hardware to work.
 335
 336 ``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT`` ``(integer)``
 337     This is a read-only control that can be read by the application and
 338     used as a hint to determine the number of OUTPUT buffers to pass to
 339     REQBUFS. The value is the minimum number of OUTPUT buffers that is
 340     necessary for hardware to work.
 341
 342 .. _v4l2-alpha-component:
 343
 344 ``V4L2_CID_ALPHA_COMPONENT`` ``(integer)``
 345     Sets the alpha color component. When a capture device (or capture
 346     queue of a mem-to-mem device) produces a frame format that includes
 347     an alpha component (e.g.
 348     :ref:`packed RGB image formats <rgb-formats>`) and the alpha value
 349     is not defined by the device or the mem-to-mem input data this
 350     control lets you select the alpha component value of all pixels.
 351     When an output device (or output queue of a mem-to-mem device)
 352     consumes a frame format that doesn't include an alpha component and
 353     the device supports alpha channel processing this control lets you
 354     set the alpha component value of all pixels for further processing
 355     in the device.
 356
 357 ``V4L2_CID_LASTP1``
 358     End of the predefined control IDs (currently
 359     ``V4L2_CID_ALPHA_COMPONENT`` + 1).
 360
 361 ``V4L2_CID_PRIVATE_BASE``
 362     ID of the first custom (driver specific) control. Applications
 363     depending on particular custom controls should check the driver name
 364     and version, see :ref:`querycap`.
 365
 366 Applications can enumerate the available controls with the
 367 :ref:`VIDIOC_QUERYCTRL` and
 368 :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>` ioctls, get and set a
 369 control value with the :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
 370 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls. Drivers must implement
 371 ``VIDIOC_QUERYCTRL``, ``VIDIOC_G_CTRL`` and ``VIDIOC_S_CTRL`` when the
 372 device has one or more controls, ``VIDIOC_QUERYMENU`` when it has one or
 373 more menu type controls.
 374
 375
 376 .. _enum_all_controls:
 377
 378 Example: Enumerating all user controls
 379 ======================================
 380
 381 .. code-block:: c
 382
 383
 384     struct v4l2_queryctrl queryctrl;
 385     struct v4l2_querymenu querymenu;
 386
 387     static void enumerate_menu(void)
 388     {
 389         printf("  Menu items:\\n");
 390
 391         memset(&querymenu, 0, sizeof(querymenu));
 392         querymenu.id = queryctrl.id;
 393
 394         for (querymenu.index = queryctrl.minimum;
 395              querymenu.index <= queryctrl.maximum;
 396              querymenu.index++) {
 397             if (0 == ioctl(fd, VIDIOC_QUERYMENU, &querymenu)) {
 398                 printf("  %s\\n", querymenu.name);
 399             }
 400         }
 401     }
 402
 403     memset(&queryctrl, 0, sizeof(queryctrl));
 404
 405     for (queryctrl.id = V4L2_CID_BASE;
 406          queryctrl.id < V4L2_CID_LASTP1;
 407          queryctrl.id++) {
 408         if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
 409             if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
 410                 continue;
 411
 412             printf("Control %s\\n", queryctrl.name);
 413
 414             if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
 415                 enumerate_menu();
 416         } else {
 417             if (errno == EINVAL)
 418                 continue;
 419
 420             perror("VIDIOC_QUERYCTRL");
 421             exit(EXIT_FAILURE);
 422         }
 423     }
 424
 425     for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
 426          queryctrl.id++) {
 427         if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
 428             if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
 429                 continue;
 430
 431             printf("Control %s\\n", queryctrl.name);
 432
 433             if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
 434                 enumerate_menu();
 435         } else {
 436             if (errno == EINVAL)
 437                 break;
 438
 439             perror("VIDIOC_QUERYCTRL");
 440             exit(EXIT_FAILURE);
 441         }
 442     }
 443
 444
 445 Example: Enumerating all user controls (alternative)
 446 ====================================================
 447
 448 .. code-block:: c
 449
 450     memset(&queryctrl, 0, sizeof(queryctrl));
 451
 452     queryctrl.id = V4L2_CTRL_CLASS_USER | V4L2_CTRL_FLAG_NEXT_CTRL;
 453     while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
 454         if (V4L2_CTRL_ID2CLASS(queryctrl.id) != V4L2_CTRL_CLASS_USER)
 455             break;
 456         if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
 457             continue;
 458
 459         printf("Control %s\\n", queryctrl.name);
 460
 461         if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
 462             enumerate_menu();
 463
 464         queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
 465     }
 466     if (errno != EINVAL) {
 467         perror("VIDIOC_QUERYCTRL");
 468         exit(EXIT_FAILURE);
 469     }
 470
 471 Example: Changing controls
 472 ==========================
 473
 474 .. code-block:: c
 475
 476     struct v4l2_queryctrl queryctrl;
 477     struct v4l2_control control;
 478
 479     memset(&queryctrl, 0, sizeof(queryctrl));
 480     queryctrl.id = V4L2_CID_BRIGHTNESS;
 481
 482     if (-1 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
 483         if (errno != EINVAL) {
 484             perror("VIDIOC_QUERYCTRL");
 485             exit(EXIT_FAILURE);
 486         } else {
 487             printf("V4L2_CID_BRIGHTNESS is not supportedn");
 488         }
 489     } else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) {
 490         printf("V4L2_CID_BRIGHTNESS is not supportedn");
 491     } else {
 492         memset(&control, 0, sizeof (control));
 493         control.id = V4L2_CID_BRIGHTNESS;
 494         control.value = queryctrl.default_value;
 495
 496         if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)) {
 497             perror("VIDIOC_S_CTRL");
 498             exit(EXIT_FAILURE);
 499         }
 500     }
 501
 502     memset(&control, 0, sizeof(control));
 503     control.id = V4L2_CID_CONTRAST;
 504
 505     if (0 == ioctl(fd, VIDIOC_G_CTRL, &control)) {
 506         control.value += 1;
 507
 508         /* The driver may clamp the value or return ERANGE, ignored here */
 509
 510         if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)
 511             && errno != ERANGE) {
 512             perror("VIDIOC_S_CTRL");
 513             exit(EXIT_FAILURE);
 514         }
 515     /* Ignore if V4L2_CID_CONTRAST is unsupported */
 516     } else if (errno != EINVAL) {
 517         perror("VIDIOC_G_CTRL");
 518         exit(EXIT_FAILURE);
 519     }
 520
 521     control.id = V4L2_CID_AUDIO_MUTE;
 522     control.value = 1; /* silence */
 523
 524     /* Errors ignored */
 525     ioctl(fd, VIDIOC_S_CTRL, &control);
 526
 527 .. [#f1]
 528    The use of ``V4L2_CID_PRIVATE_BASE`` is problematic because different
 529    drivers may use the same ``V4L2_CID_PRIVATE_BASE`` ID for different
 530    controls. This makes it hard to programatically set such controls
 531    since the meaning of the control with that ID is driver dependent. In
 532    order to resolve this drivers use unique IDs and the
 533    ``V4L2_CID_PRIVATE_BASE`` IDs are mapped to those unique IDs by the
 534    kernel. Consider these ``V4L2_CID_PRIVATE_BASE`` IDs as aliases to
 535    the real IDs.
 536
 537    Many applications today still use the ``V4L2_CID_PRIVATE_BASE`` IDs
 538    instead of using :ref:`VIDIOC_QUERYCTRL` with
 539    the ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag to enumerate all IDs, so
 540    support for ``V4L2_CID_PRIVATE_BASE`` is still around.