Documentation/media/uapi/v4l/ext-ctrls-camera.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/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _camera-controls:
  11
  12 ************************
  13 Camera Control Reference
  14 ************************
  15
  16 The Camera class includes controls for mechanical (or equivalent
  17 digital) features of a device such as controllable lenses or sensors.
  18
  19
  20 .. _camera-control-id:
  21
  22 Camera Control IDs
  23 ==================
  24
  25 ``V4L2_CID_CAMERA_CLASS (class)``
  26     The Camera class descriptor. Calling
  27     :ref:`VIDIOC_QUERYCTRL` for this control will
  28     return a description of this control class.
  29
  30 .. _v4l2-exposure-auto-type:
  31
  32 ``V4L2_CID_EXPOSURE_AUTO``
  33     (enum)
  34
  35 enum v4l2_exposure_auto_type -
  36     Enables automatic adjustments of the exposure time and/or iris
  37     aperture. The effect of manual changes of the exposure time or iris
  38     aperture while these features are enabled is undefined, drivers
  39     should ignore such requests. Possible values are:
  40
  41
  42
  43 .. flat-table::
  44     :header-rows:  0
  45     :stub-columns: 0
  46
  47     * - ``V4L2_EXPOSURE_AUTO``
  48       - Automatic exposure time, automatic iris aperture.
  49     * - ``V4L2_EXPOSURE_MANUAL``
  50       - Manual exposure time, manual iris.
  51     * - ``V4L2_EXPOSURE_SHUTTER_PRIORITY``
  52       - Manual exposure time, auto iris.
  53     * - ``V4L2_EXPOSURE_APERTURE_PRIORITY``
  54       - Auto exposure time, manual iris.
  55
  56
  57
  58 ``V4L2_CID_EXPOSURE_ABSOLUTE (integer)``
  59     Determines the exposure time of the camera sensor. The exposure time
  60     is limited by the frame interval. Drivers should interpret the
  61     values as 100 µs units, where the value 1 stands for 1/10000th of a
  62     second, 10000 for 1 second and 100000 for 10 seconds.
  63
  64 ``V4L2_CID_EXPOSURE_AUTO_PRIORITY (boolean)``
  65     When ``V4L2_CID_EXPOSURE_AUTO`` is set to ``AUTO`` or
  66     ``APERTURE_PRIORITY``, this control determines if the device may
  67     dynamically vary the frame rate. By default this feature is disabled
  68     (0) and the frame rate must remain constant.
  69
  70 ``V4L2_CID_AUTO_EXPOSURE_BIAS (integer menu)``
  71     Determines the automatic exposure compensation, it is effective only
  72     when ``V4L2_CID_EXPOSURE_AUTO`` control is set to ``AUTO``,
  73     ``SHUTTER_PRIORITY`` or ``APERTURE_PRIORITY``. It is expressed in
  74     terms of EV, drivers should interpret the values as 0.001 EV units,
  75     where the value 1000 stands for +1 EV.
  76
  77     Increasing the exposure compensation value is equivalent to
  78     decreasing the exposure value (EV) and will increase the amount of
  79     light at the image sensor. The camera performs the exposure
  80     compensation by adjusting absolute exposure time and/or aperture.
  81
  82 .. _v4l2-exposure-metering:
  83
  84 ``V4L2_CID_EXPOSURE_METERING``
  85     (enum)
  86
  87 enum v4l2_exposure_metering -
  88     Determines how the camera measures the amount of light available for
  89     the frame exposure. Possible values are:
  90
  91 .. tabularcolumns:: |p{8.5cm}|p{9.0cm}|
  92
  93 .. flat-table::
  94     :header-rows:  0
  95     :stub-columns: 0
  96
  97     * - ``V4L2_EXPOSURE_METERING_AVERAGE``
  98       - Use the light information coming from the entire frame and average
  99         giving no weighting to any particular portion of the metered area.
 100     * - ``V4L2_EXPOSURE_METERING_CENTER_WEIGHTED``
 101       - Average the light information coming from the entire frame giving
 102         priority to the center of the metered area.
 103     * - ``V4L2_EXPOSURE_METERING_SPOT``
 104       - Measure only very small area at the center of the frame.
 105     * - ``V4L2_EXPOSURE_METERING_MATRIX``
 106       - A multi-zone metering. The light intensity is measured in several
 107         points of the frame and the results are combined. The algorithm of
 108         the zones selection and their significance in calculating the
 109         final value is device dependent.
 110
 111
 112
 113 ``V4L2_CID_PAN_RELATIVE (integer)``
 114     This control turns the camera horizontally by the specified amount.
 115     The unit is undefined. A positive value moves the camera to the
 116     right (clockwise when viewed from above), a negative value to the
 117     left. A value of zero does not cause motion. This is a write-only
 118     control.
 119
 120 ``V4L2_CID_TILT_RELATIVE (integer)``
 121     This control turns the camera vertically by the specified amount.
 122     The unit is undefined. A positive value moves the camera up, a
 123     negative value down. A value of zero does not cause motion. This is
 124     a write-only control.
 125
 126 ``V4L2_CID_PAN_RESET (button)``
 127     When this control is set, the camera moves horizontally to the
 128     default position.
 129
 130 ``V4L2_CID_TILT_RESET (button)``
 131     When this control is set, the camera moves vertically to the default
 132     position.
 133
 134 ``V4L2_CID_PAN_ABSOLUTE (integer)``
 135     This control turns the camera horizontally to the specified
 136     position. Positive values move the camera to the right (clockwise
 137     when viewed from above), negative values to the left. Drivers should
 138     interpret the values as arc seconds, with valid values between -180
 139     * 3600 and +180 * 3600 inclusive.
 140
 141 ``V4L2_CID_TILT_ABSOLUTE (integer)``
 142     This control turns the camera vertically to the specified position.
 143     Positive values move the camera up, negative values down. Drivers
 144     should interpret the values as arc seconds, with valid values
 145     between -180 * 3600 and +180 * 3600 inclusive.
 146
 147 ``V4L2_CID_FOCUS_ABSOLUTE (integer)``
 148     This control sets the focal point of the camera to the specified
 149     position. The unit is undefined. Positive values set the focus
 150     closer to the camera, negative values towards infinity.
 151
 152 ``V4L2_CID_FOCUS_RELATIVE (integer)``
 153     This control moves the focal point of the camera by the specified
 154     amount. The unit is undefined. Positive values move the focus closer
 155     to the camera, negative values towards infinity. This is a
 156     write-only control.
 157
 158 ``V4L2_CID_FOCUS_AUTO (boolean)``
 159     Enables continuous automatic focus adjustments. The effect of manual
 160     focus adjustments while this feature is enabled is undefined,
 161     drivers should ignore such requests.
 162
 163 ``V4L2_CID_AUTO_FOCUS_START (button)``
 164     Starts single auto focus process. The effect of setting this control
 165     when ``V4L2_CID_FOCUS_AUTO`` is set to ``TRUE`` (1) is undefined,
 166     drivers should ignore such requests.
 167
 168 ``V4L2_CID_AUTO_FOCUS_STOP (button)``
 169     Aborts automatic focusing started with ``V4L2_CID_AUTO_FOCUS_START``
 170     control. It is effective only when the continuous autofocus is
 171     disabled, that is when ``V4L2_CID_FOCUS_AUTO`` control is set to
 172     ``FALSE`` (0).
 173
 174 .. _v4l2-auto-focus-status:
 175
 176 ``V4L2_CID_AUTO_FOCUS_STATUS (bitmask)``
 177     The automatic focus status. This is a read-only control.
 178
 179     Setting ``V4L2_LOCK_FOCUS`` lock bit of the ``V4L2_CID_3A_LOCK``
 180     control may stop updates of the ``V4L2_CID_AUTO_FOCUS_STATUS``
 181     control value.
 182
 183 .. tabularcolumns:: |p{6.5cm}|p{11.0cm}|
 184
 185 .. flat-table::
 186     :header-rows:  0
 187     :stub-columns: 0
 188
 189     * - ``V4L2_AUTO_FOCUS_STATUS_IDLE``
 190       - Automatic focus is not active.
 191     * - ``V4L2_AUTO_FOCUS_STATUS_BUSY``
 192       - Automatic focusing is in progress.
 193     * - ``V4L2_AUTO_FOCUS_STATUS_REACHED``
 194       - Focus has been reached.
 195     * - ``V4L2_AUTO_FOCUS_STATUS_FAILED``
 196       - Automatic focus has failed, the driver will not transition from
 197         this state until another action is performed by an application.
 198
 199
 200
 201 .. _v4l2-auto-focus-range:
 202
 203 ``V4L2_CID_AUTO_FOCUS_RANGE``
 204     (enum)
 205
 206 enum v4l2_auto_focus_range -
 207     Determines auto focus distance range for which lens may be adjusted.
 208
 209 .. tabularcolumns:: |p{6.5cm}|p{11.0cm}|
 210
 211 .. flat-table::
 212     :header-rows:  0
 213     :stub-columns: 0
 214
 215     * - ``V4L2_AUTO_FOCUS_RANGE_AUTO``
 216       - The camera automatically selects the focus range.
 217     * - ``V4L2_AUTO_FOCUS_RANGE_NORMAL``
 218       - Normal distance range, limited for best automatic focus
 219         performance.
 220     * - ``V4L2_AUTO_FOCUS_RANGE_MACRO``
 221       - Macro (close-up) auto focus. The camera will use its minimum
 222         possible distance for auto focus.
 223     * - ``V4L2_AUTO_FOCUS_RANGE_INFINITY``
 224       - The lens is set to focus on an object at infinite distance.
 225
 226
 227
 228 ``V4L2_CID_ZOOM_ABSOLUTE (integer)``
 229     Specify the objective lens focal length as an absolute value. The
 230     zoom unit is driver-specific and its value should be a positive
 231     integer.
 232
 233 ``V4L2_CID_ZOOM_RELATIVE (integer)``
 234     Specify the objective lens focal length relatively to the current
 235     value. Positive values move the zoom lens group towards the
 236     telephoto direction, negative values towards the wide-angle
 237     direction. The zoom unit is driver-specific. This is a write-only
 238     control.
 239
 240 ``V4L2_CID_ZOOM_CONTINUOUS (integer)``
 241     Move the objective lens group at the specified speed until it
 242     reaches physical device limits or until an explicit request to stop
 243     the movement. A positive value moves the zoom lens group towards the
 244     telephoto direction. A value of zero stops the zoom lens group
 245     movement. A negative value moves the zoom lens group towards the
 246     wide-angle direction. The zoom speed unit is driver-specific.
 247
 248 ``V4L2_CID_IRIS_ABSOLUTE (integer)``
 249     This control sets the camera's aperture to the specified value. The
 250     unit is undefined. Larger values open the iris wider, smaller values
 251     close it.
 252
 253 ``V4L2_CID_IRIS_RELATIVE (integer)``
 254     This control modifies the camera's aperture by the specified amount.
 255     The unit is undefined. Positive values open the iris one step
 256     further, negative values close it one step further. This is a
 257     write-only control.
 258
 259 ``V4L2_CID_PRIVACY (boolean)``
 260     Prevent video from being acquired by the camera. When this control
 261     is set to ``TRUE`` (1), no image can be captured by the camera.
 262     Common means to enforce privacy are mechanical obturation of the
 263     sensor and firmware image processing, but the device is not
 264     restricted to these methods. Devices that implement the privacy
 265     control must support read access and may support write access.
 266
 267 ``V4L2_CID_BAND_STOP_FILTER (integer)``
 268     Switch the band-stop filter of a camera sensor on or off, or specify
 269     its strength. Such band-stop filters can be used, for example, to
 270     filter out the fluorescent light component.
 271
 272 .. _v4l2-auto-n-preset-white-balance:
 273
 274 ``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE``
 275     (enum)
 276
 277 enum v4l2_auto_n_preset_white_balance -
 278     Sets white balance to automatic, manual or a preset. The presets
 279     determine color temperature of the light as a hint to the camera for
 280     white balance adjustments resulting in most accurate color
 281     representation. The following white balance presets are listed in
 282     order of increasing color temperature.
 283
 284 .. tabularcolumns:: |p{7.0 cm}|p{10.5cm}|
 285
 286 .. flat-table::
 287     :header-rows:  0
 288     :stub-columns: 0
 289
 290     * - ``V4L2_WHITE_BALANCE_MANUAL``
 291       - Manual white balance.
 292     * - ``V4L2_WHITE_BALANCE_AUTO``
 293       - Automatic white balance adjustments.
 294     * - ``V4L2_WHITE_BALANCE_INCANDESCENT``
 295       - White balance setting for incandescent (tungsten) lighting. It
 296         generally cools down the colors and corresponds approximately to
 297         2500...3500 K color temperature range.
 298     * - ``V4L2_WHITE_BALANCE_FLUORESCENT``
 299       - White balance preset for fluorescent lighting. It corresponds
 300         approximately to 4000...5000 K color temperature.
 301     * - ``V4L2_WHITE_BALANCE_FLUORESCENT_H``
 302       - With this setting the camera will compensate for fluorescent H
 303         lighting.
 304     * - ``V4L2_WHITE_BALANCE_HORIZON``
 305       - White balance setting for horizon daylight. It corresponds
 306         approximately to 5000 K color temperature.
 307     * - ``V4L2_WHITE_BALANCE_DAYLIGHT``
 308       - White balance preset for daylight (with clear sky). It corresponds
 309         approximately to 5000...6500 K color temperature.
 310     * - ``V4L2_WHITE_BALANCE_FLASH``
 311       - With this setting the camera will compensate for the flash light.
 312         It slightly warms up the colors and corresponds roughly to
 313         5000...5500 K color temperature.
 314     * - ``V4L2_WHITE_BALANCE_CLOUDY``
 315       - White balance preset for moderately overcast sky. This option
 316         corresponds approximately to 6500...8000 K color temperature
 317         range.
 318     * - ``V4L2_WHITE_BALANCE_SHADE``
 319       - White balance preset for shade or heavily overcast sky. It
 320         corresponds approximately to 9000...10000 K color temperature.
 321
 322
 323
 324 .. _v4l2-wide-dynamic-range:
 325
 326 ``V4L2_CID_WIDE_DYNAMIC_RANGE (boolean)``
 327     Enables or disables the camera's wide dynamic range feature. This
 328     feature allows to obtain clear images in situations where intensity
 329     of the illumination varies significantly throughout the scene, i.e.
 330     there are simultaneously very dark and very bright areas. It is most
 331     commonly realized in cameras by combining two subsequent frames with
 332     different exposure times.  [#f1]_
 333
 334 .. _v4l2-image-stabilization:
 335
 336 ``V4L2_CID_IMAGE_STABILIZATION (boolean)``
 337     Enables or disables image stabilization.
 338
 339 ``V4L2_CID_ISO_SENSITIVITY (integer menu)``
 340     Determines ISO equivalent of an image sensor indicating the sensor's
 341     sensitivity to light. The numbers are expressed in arithmetic scale,
 342     as per :ref:`iso12232` standard, where doubling the sensor
 343     sensitivity is represented by doubling the numerical ISO value.
 344     Applications should interpret the values as standard ISO values
 345     multiplied by 1000, e.g. control value 800 stands for ISO 0.8.
 346     Drivers will usually support only a subset of standard ISO values.
 347     The effect of setting this control while the
 348     ``V4L2_CID_ISO_SENSITIVITY_AUTO`` control is set to a value other
 349     than ``V4L2_CID_ISO_SENSITIVITY_MANUAL`` is undefined, drivers
 350     should ignore such requests.
 351
 352 .. _v4l2-iso-sensitivity-auto-type:
 353
 354 ``V4L2_CID_ISO_SENSITIVITY_AUTO``
 355     (enum)
 356
 357 enum v4l2_iso_sensitivity_type -
 358     Enables or disables automatic ISO sensitivity adjustments.
 359
 360
 361
 362 .. flat-table::
 363     :header-rows:  0
 364     :stub-columns: 0
 365
 366     * - ``V4L2_CID_ISO_SENSITIVITY_MANUAL``
 367       - Manual ISO sensitivity.
 368     * - ``V4L2_CID_ISO_SENSITIVITY_AUTO``
 369       - Automatic ISO sensitivity adjustments.
 370
 371
 372
 373 .. _v4l2-scene-mode:
 374
 375 ``V4L2_CID_SCENE_MODE``
 376     (enum)
 377
 378 enum v4l2_scene_mode -
 379     This control allows to select scene programs as the camera automatic
 380     modes optimized for common shooting scenes. Within these modes the
 381     camera determines best exposure, aperture, focusing, light metering,
 382     white balance and equivalent sensitivity. The controls of those
 383     parameters are influenced by the scene mode control. An exact
 384     behavior in each mode is subject to the camera specification.
 385
 386     When the scene mode feature is not used, this control should be set
 387     to ``V4L2_SCENE_MODE_NONE`` to make sure the other possibly related
 388     controls are accessible. The following scene programs are defined:
 389
 390 .. tabularcolumns:: |p{6.0cm}|p{11.5cm}|
 391
 392 .. flat-table::
 393     :header-rows:  0
 394     :stub-columns: 0
 395
 396     * - ``V4L2_SCENE_MODE_NONE``
 397       - The scene mode feature is disabled.
 398     * - ``V4L2_SCENE_MODE_BACKLIGHT``
 399       - Backlight. Compensates for dark shadows when light is coming from
 400         behind a subject, also by automatically turning on the flash.
 401     * - ``V4L2_SCENE_MODE_BEACH_SNOW``
 402       - Beach and snow. This mode compensates for all-white or bright
 403         scenes, which tend to look gray and low contrast, when camera's
 404         automatic exposure is based on an average scene brightness. To
 405         compensate, this mode automatically slightly overexposes the
 406         frames. The white balance may also be adjusted to compensate for
 407         the fact that reflected snow looks bluish rather than white.
 408     * - ``V4L2_SCENE_MODE_CANDLELIGHT``
 409       - Candle light. The camera generally raises the ISO sensitivity and
 410         lowers the shutter speed. This mode compensates for relatively
 411         close subject in the scene. The flash is disabled in order to
 412         preserve the ambiance of the light.
 413     * - ``V4L2_SCENE_MODE_DAWN_DUSK``
 414       - Dawn and dusk. Preserves the colors seen in low natural light
 415         before dusk and after down. The camera may turn off the flash, and
 416         automatically focus at infinity. It will usually boost saturation
 417         and lower the shutter speed.
 418     * - ``V4L2_SCENE_MODE_FALL_COLORS``
 419       - Fall colors. Increases saturation and adjusts white balance for
 420         color enhancement. Pictures of autumn leaves get saturated reds
 421         and yellows.
 422     * - ``V4L2_SCENE_MODE_FIREWORKS``
 423       - Fireworks. Long exposure times are used to capture the expanding
 424         burst of light from a firework. The camera may invoke image
 425         stabilization.
 426     * - ``V4L2_SCENE_MODE_LANDSCAPE``
 427       - Landscape. The camera may choose a small aperture to provide deep
 428         depth of field and long exposure duration to help capture detail
 429         in dim light conditions. The focus is fixed at infinity. Suitable
 430         for distant and wide scenery.
 431     * - ``V4L2_SCENE_MODE_NIGHT``
 432       - Night, also known as Night Landscape. Designed for low light
 433         conditions, it preserves detail in the dark areas without blowing
 434         out bright objects. The camera generally sets itself to a
 435         medium-to-high ISO sensitivity, with a relatively long exposure
 436         time, and turns flash off. As such, there will be increased image
 437         noise and the possibility of blurred image.
 438     * - ``V4L2_SCENE_MODE_PARTY_INDOOR``
 439       - Party and indoor. Designed to capture indoor scenes that are lit
 440         by indoor background lighting as well as the flash. The camera
 441         usually increases ISO sensitivity, and adjusts exposure for the
 442         low light conditions.
 443     * - ``V4L2_SCENE_MODE_PORTRAIT``
 444       - Portrait. The camera adjusts the aperture so that the depth of
 445         field is reduced, which helps to isolate the subject against a
 446         smooth background. Most cameras recognize the presence of faces in
 447         the scene and focus on them. The color hue is adjusted to enhance
 448         skin tones. The intensity of the flash is often reduced.
 449     * - ``V4L2_SCENE_MODE_SPORTS``
 450       - Sports. Significantly increases ISO and uses a fast shutter speed
 451         to freeze motion of rapidly-moving subjects. Increased image noise
 452         may be seen in this mode.
 453     * - ``V4L2_SCENE_MODE_SUNSET``
 454       - Sunset. Preserves deep hues seen in sunsets and sunrises. It bumps
 455         up the saturation.
 456     * - ``V4L2_SCENE_MODE_TEXT``
 457       - Text. It applies extra contrast and sharpness, it is typically a
 458         black-and-white mode optimized for readability. Automatic focus
 459         may be switched to close-up mode and this setting may also involve
 460         some lens-distortion correction.
 461
 462
 463
 464 ``V4L2_CID_3A_LOCK (bitmask)``
 465     This control locks or unlocks the automatic focus, exposure and
 466     white balance. The automatic adjustments can be paused independently
 467     by setting the corresponding lock bit to 1. The camera then retains
 468     the settings until the lock bit is cleared. The following lock bits
 469     are defined:
 470
 471     When a given algorithm is not enabled, drivers should ignore
 472     requests to lock it and should return no error. An example might be
 473     an application setting bit ``V4L2_LOCK_WHITE_BALANCE`` when the
 474     ``V4L2_CID_AUTO_WHITE_BALANCE`` control is set to ``FALSE``. The
 475     value of this control may be changed by exposure, white balance or
 476     focus controls.
 477
 478
 479
 480 .. flat-table::
 481     :header-rows:  0
 482     :stub-columns: 0
 483
 484     * - ``V4L2_LOCK_EXPOSURE``
 485       - Automatic exposure adjustments lock.
 486     * - ``V4L2_LOCK_WHITE_BALANCE``
 487       - Automatic white balance adjustments lock.
 488     * - ``V4L2_LOCK_FOCUS``
 489       - Automatic focus lock.
 490
 491
 492
 493 ``V4L2_CID_PAN_SPEED (integer)``
 494     This control turns the camera horizontally at the specific speed.
 495     The unit is undefined. A positive value moves the camera to the
 496     right (clockwise when viewed from above), a negative value to the
 497     left. A value of zero stops the motion if one is in progress and has
 498     no effect otherwise.
 499
 500 ``V4L2_CID_TILT_SPEED (integer)``
 501     This control turns the camera vertically at the specified speed. The
 502     unit is undefined. A positive value moves the camera up, a negative
 503     value down. A value of zero stops the motion if one is in progress
 504     and has no effect otherwise.
 505
 506 .. [#f1]
 507    This control may be changed to a menu control in the future, if more
 508    options are required.