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     * - ``V4L2_COLORFX_NONE``
 202       - Color effect is disabled.
 203     * - ``V4L2_COLORFX_ANTIQUE``
 204       - An aging (old photo) effect.
 205     * - ``V4L2_COLORFX_ART_FREEZE``
 206       - Frost color effect.
 207     * - ``V4L2_COLORFX_AQUA``
 208       - Water color, cool tone.
 209     * - ``V4L2_COLORFX_BW``
 210       - Black and white.
 211     * - ``V4L2_COLORFX_EMBOSS``
 212       - Emboss, the highlights and shadows replace light/dark boundaries
 213         and low contrast areas are set to a gray background.
 214     * - ``V4L2_COLORFX_GRASS_GREEN``
 215       - Grass green.
 216     * - ``V4L2_COLORFX_NEGATIVE``
 217       - Negative.
 218     * - ``V4L2_COLORFX_SEPIA``
 219       - Sepia tone.
 220     * - ``V4L2_COLORFX_SKETCH``
 221       - Sketch.
 222     * - ``V4L2_COLORFX_SKIN_WHITEN``
 223       - Skin whiten.
 224     * - ``V4L2_COLORFX_SKY_BLUE``
 225       - Sky blue.
 226     * - ``V4L2_COLORFX_SOLARIZATION``
 227       - Solarization, the image is partially reversed in tone, only color
 228         values above or below a certain threshold are inverted.
 229     * - ``V4L2_COLORFX_SILHOUETTE``
 230       - Silhouette (outline).
 231     * - ``V4L2_COLORFX_VIVID``
 232       - Vivid colors.
 233     * - ``V4L2_COLORFX_SET_CBCR``
 234       - The Cb and Cr chroma components are replaced by fixed coefficients
 235         determined by ``V4L2_CID_COLORFX_CBCR`` control.
 236
 237
 238
 239 ``V4L2_CID_COLORFX_CBCR`` ``(integer)``
 240     Determines the Cb and Cr coefficients for ``V4L2_COLORFX_SET_CBCR``
 241     color effect. Bits [7:0] of the supplied 32 bit value are
 242     interpreted as Cr component, bits [15:8] as Cb component and bits
 243     [31:16] must be zero.
 244
 245 ``V4L2_CID_AUTOBRIGHTNESS`` ``(boolean)``
 246     Enable Automatic Brightness.
 247
 248 ``V4L2_CID_ROTATE`` ``(integer)``
 249     Rotates the image by specified angle. Common angles are 90, 270 and
 250     180. Rotating the image to 90 and 270 will reverse the height and
 251     width of the display window. It is necessary to set the new height
 252     and width of the picture using the
 253     :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl according to the
 254     rotation angle selected.
 255
 256 ``V4L2_CID_BG_COLOR`` ``(integer)``
 257     Sets the background color on the current output device. Background
 258     color needs to be specified in the RGB24 format. The supplied 32 bit
 259     value is interpreted as bits 0-7 Red color information, bits 8-15
 260     Green color information, bits 16-23 Blue color information and bits
 261     24-31 must be zero.
 262
 263 ``V4L2_CID_ILLUMINATORS_1 V4L2_CID_ILLUMINATORS_2`` ``(boolean)``
 264     Switch on or off the illuminator 1 or 2 of the device (usually a
 265     microscope).
 266
 267 ``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE`` ``(integer)``
 268     This is a read-only control that can be read by the application and
 269     used as a hint to determine the number of CAPTURE buffers to pass to
 270     REQBUFS. The value is the minimum number of CAPTURE buffers that is
 271     necessary for hardware to work.
 272
 273 ``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT`` ``(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 OUTPUT buffers to pass to
 276     REQBUFS. The value is the minimum number of OUTPUT buffers that is
 277     necessary for hardware to work.
 278
 279 .. _v4l2-alpha-component:
 280
 281 ``V4L2_CID_ALPHA_COMPONENT`` ``(integer)``
 282     Sets the alpha color component. When a capture device (or capture
 283     queue of a mem-to-mem device) produces a frame format that includes
 284     an alpha component (e.g.
 285     :ref:`packed RGB image formats <rgb-formats>`) and the alpha value
 286     is not defined by the device or the mem-to-mem input data this
 287     control lets you select the alpha component value of all pixels.
 288     When an output device (or output queue of a mem-to-mem device)
 289     consumes a frame format that doesn't include an alpha component and
 290     the device supports alpha channel processing this control lets you
 291     set the alpha component value of all pixels for further processing
 292     in the device.
 293
 294 ``V4L2_CID_LASTP1``
 295     End of the predefined control IDs (currently
 296     ``V4L2_CID_ALPHA_COMPONENT`` + 1).
 297
 298 ``V4L2_CID_PRIVATE_BASE``
 299     ID of the first custom (driver specific) control. Applications
 300     depending on particular custom controls should check the driver name
 301     and version, see :ref:`querycap`.
 302
 303 Applications can enumerate the available controls with the
 304 :ref:`VIDIOC_QUERYCTRL` and
 305 :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>` ioctls, get and set a
 306 control value with the :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
 307 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls. Drivers must implement
 308 ``VIDIOC_QUERYCTRL``, ``VIDIOC_G_CTRL`` and ``VIDIOC_S_CTRL`` when the
 309 device has one or more controls, ``VIDIOC_QUERYMENU`` when it has one or
 310 more menu type controls.
 311
 312
 313 .. _enum_all_controls:
 314
 315 Example: Enumerating all controls
 316 =================================
 317
 318 .. code-block:: c
 319
 320     struct v4l2_queryctrl queryctrl;
 321     struct v4l2_querymenu querymenu;
 322
 323     static void enumerate_menu(__u32 id)
 324     {
 325         printf("  Menu items:\\n");
 326
 327         memset(&querymenu, 0, sizeof(querymenu));
 328         querymenu.id = id;
 329
 330         for (querymenu.index = queryctrl.minimum;
 331              querymenu.index <= queryctrl.maximum;
 332              querymenu.index++) {
 333             if (0 == ioctl(fd, VIDIOC_QUERYMENU, &querymenu)) {
 334                 printf("  %s\\n", querymenu.name);
 335             }
 336         }
 337     }
 338
 339     memset(&queryctrl, 0, sizeof(queryctrl));
 340
 341     queryctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
 342     while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
 343         if (!(queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)) {
 344             printf("Control %s\\n", queryctrl.name);
 345
 346             if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
 347                 enumerate_menu(queryctrl.id);
 348         }
 349
 350         queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
 351     }
 352     if (errno != EINVAL) {
 353         perror("VIDIOC_QUERYCTRL");
 354         exit(EXIT_FAILURE);
 355     }
 356
 357 Example: Enumerating all controls including compound controls
 358 =============================================================
 359
 360 .. code-block:: c
 361
 362     struct v4l2_query_ext_ctrl query_ext_ctrl;
 363
 364     memset(&query_ext_ctrl, 0, sizeof(query_ext_ctrl));
 365
 366     query_ext_ctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL | V4L2_CTRL_FLAG_NEXT_COMPOUND;
 367     while (0 == ioctl(fd, VIDIOC_QUERY_EXT_CTRL, &query_ext_ctrl)) {
 368         if (!(query_ext_ctrl.flags & V4L2_CTRL_FLAG_DISABLED)) {
 369             printf("Control %s\\n", query_ext_ctrl.name);
 370
 371             if (query_ext_ctrl.type == V4L2_CTRL_TYPE_MENU)
 372                 enumerate_menu(query_ext_ctrl.id);
 373         }
 374
 375         query_ext_ctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL | V4L2_CTRL_FLAG_NEXT_COMPOUND;
 376     }
 377     if (errno != EINVAL) {
 378         perror("VIDIOC_QUERY_EXT_CTRL");
 379         exit(EXIT_FAILURE);
 380     }
 381
 382 Example: Enumerating all user controls (old style)
 383 ==================================================
 384
 385 .. code-block:: c
 386
 387
 388     memset(&queryctrl, 0, sizeof(queryctrl));
 389
 390     for (queryctrl.id = V4L2_CID_BASE;
 391          queryctrl.id < V4L2_CID_LASTP1;
 392          queryctrl.id++) {
 393         if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
 394             if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
 395                 continue;
 396
 397             printf("Control %s\\n", queryctrl.name);
 398
 399             if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
 400                 enumerate_menu(queryctrl.id);
 401         } else {
 402             if (errno == EINVAL)
 403                 continue;
 404
 405             perror("VIDIOC_QUERYCTRL");
 406             exit(EXIT_FAILURE);
 407         }
 408     }
 409
 410     for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
 411          queryctrl.id++) {
 412         if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
 413             if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
 414                 continue;
 415
 416             printf("Control %s\\n", queryctrl.name);
 417
 418             if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
 419                 enumerate_menu(queryctrl.id);
 420         } else {
 421             if (errno == EINVAL)
 422                 break;
 423
 424             perror("VIDIOC_QUERYCTRL");
 425             exit(EXIT_FAILURE);
 426         }
 427     }
 428
 429
 430 Example: Changing controls
 431 ==========================
 432
 433 .. code-block:: c
 434
 435     struct v4l2_queryctrl queryctrl;
 436     struct v4l2_control control;
 437
 438     memset(&queryctrl, 0, sizeof(queryctrl));
 439     queryctrl.id = V4L2_CID_BRIGHTNESS;
 440
 441     if (-1 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
 442         if (errno != EINVAL) {
 443             perror("VIDIOC_QUERYCTRL");
 444             exit(EXIT_FAILURE);
 445         } else {
 446             printf("V4L2_CID_BRIGHTNESS is not supportedn");
 447         }
 448     } else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) {
 449         printf("V4L2_CID_BRIGHTNESS is not supportedn");
 450     } else {
 451         memset(&control, 0, sizeof (control));
 452         control.id = V4L2_CID_BRIGHTNESS;
 453         control.value = queryctrl.default_value;
 454
 455         if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)) {
 456             perror("VIDIOC_S_CTRL");
 457             exit(EXIT_FAILURE);
 458         }
 459     }
 460
 461     memset(&control, 0, sizeof(control));
 462     control.id = V4L2_CID_CONTRAST;
 463
 464     if (0 == ioctl(fd, VIDIOC_G_CTRL, &control)) {
 465         control.value += 1;
 466
 467         /* The driver may clamp the value or return ERANGE, ignored here */
 468
 469         if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)
 470             && errno != ERANGE) {
 471             perror("VIDIOC_S_CTRL");
 472             exit(EXIT_FAILURE);
 473         }
 474     /* Ignore if V4L2_CID_CONTRAST is unsupported */
 475     } else if (errno != EINVAL) {
 476         perror("VIDIOC_G_CTRL");
 477         exit(EXIT_FAILURE);
 478     }
 479
 480     control.id = V4L2_CID_AUDIO_MUTE;
 481     control.value = 1; /* silence */
 482
 483     /* Errors ignored */
 484     ioctl(fd, VIDIOC_S_CTRL, &control);
 485
 486 .. [#f1]
 487    The use of ``V4L2_CID_PRIVATE_BASE`` is problematic because different
 488    drivers may use the same ``V4L2_CID_PRIVATE_BASE`` ID for different
 489    controls. This makes it hard to programatically set such controls
 490    since the meaning of the control with that ID is driver dependent. In
 491    order to resolve this drivers use unique IDs and the
 492    ``V4L2_CID_PRIVATE_BASE`` IDs are mapped to those unique IDs by the
 493    kernel. Consider these ``V4L2_CID_PRIVATE_BASE`` IDs as aliases to
 494    the real IDs.
 495
 496    Many applications today still use the ``V4L2_CID_PRIVATE_BASE`` IDs
 497    instead of using :ref:`VIDIOC_QUERYCTRL` with
 498    the ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag to enumerate all IDs, so
 499    support for ``V4L2_CID_PRIVATE_BASE`` is still around.