Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2
   3 .. _camera-controls:
   4
   5 ************************
   6 Camera Control Reference
   7 ************************
   8
   9 The Camera class includes controls for mechanical (or equivalent
  10 digital) features of a device such as controllable lenses or sensors.
  11
  12
  13 .. _camera-control-id:
  14
  15 Camera Control IDs
  16 ==================
  17
  18 ``V4L2_CID_CAMERA_CLASS (class)``
  19     The Camera class descriptor. Calling
  20     :ref:`VIDIOC_QUERYCTRL` for this control will
  21     return a description of this control class.
  22
  23 .. _v4l2-exposure-auto-type:
  24
  25 ``V4L2_CID_EXPOSURE_AUTO``
  26     (enum)
  27
  28 enum v4l2_exposure_auto_type -
  29     Enables automatic adjustments of the exposure time and/or iris
  30     aperture. The effect of manual changes of the exposure time or iris
  31     aperture while these features are enabled is undefined, drivers
  32     should ignore such requests. Possible values are:
  33
  34
  35 .. tabularcolumns:: |p{7.1cm}|p{10.4cm}|
  36
  37 .. flat-table::
  38     :header-rows:  0
  39     :stub-columns: 0
  40
  41     * - ``V4L2_EXPOSURE_AUTO``
  42       - Automatic exposure time, automatic iris aperture.
  43     * - ``V4L2_EXPOSURE_MANUAL``
  44       - Manual exposure time, manual iris.
  45     * - ``V4L2_EXPOSURE_SHUTTER_PRIORITY``
  46       - Manual exposure time, auto iris.
  47     * - ``V4L2_EXPOSURE_APERTURE_PRIORITY``
  48       - Auto exposure time, manual iris.
  49
  50
  51
  52 ``V4L2_CID_EXPOSURE_ABSOLUTE (integer)``
  53     Determines the exposure time of the camera sensor. The exposure time
  54     is limited by the frame interval. Drivers should interpret the
  55     values as 100 µs units, where the value 1 stands for 1/10000th of a
  56     second, 10000 for 1 second and 100000 for 10 seconds.
  57
  58 ``V4L2_CID_EXPOSURE_AUTO_PRIORITY (boolean)``
  59     When ``V4L2_CID_EXPOSURE_AUTO`` is set to ``AUTO`` or
  60     ``APERTURE_PRIORITY``, this control determines if the device may
  61     dynamically vary the frame rate. By default this feature is disabled
  62     (0) and the frame rate must remain constant.
  63
  64 ``V4L2_CID_AUTO_EXPOSURE_BIAS (integer menu)``
  65     Determines the automatic exposure compensation, it is effective only
  66     when ``V4L2_CID_EXPOSURE_AUTO`` control is set to ``AUTO``,
  67     ``SHUTTER_PRIORITY`` or ``APERTURE_PRIORITY``. It is expressed in
  68     terms of EV, drivers should interpret the values as 0.001 EV units,
  69     where the value 1000 stands for +1 EV.
  70
  71     Increasing the exposure compensation value is equivalent to
  72     decreasing the exposure value (EV) and will increase the amount of
  73     light at the image sensor. The camera performs the exposure
  74     compensation by adjusting absolute exposure time and/or aperture.
  75
  76 .. _v4l2-exposure-metering:
  77
  78 ``V4L2_CID_EXPOSURE_METERING``
  79     (enum)
  80
  81 enum v4l2_exposure_metering -
  82     Determines how the camera measures the amount of light available for
  83     the frame exposure. Possible values are:
  84
  85 .. tabularcolumns:: |p{8.7cm}|p{8.7cm}|
  86
  87 .. flat-table::
  88     :header-rows:  0
  89     :stub-columns: 0
  90
  91     * - ``V4L2_EXPOSURE_METERING_AVERAGE``
  92       - Use the light information coming from the entire frame and average
  93         giving no weighting to any particular portion of the metered area.
  94     * - ``V4L2_EXPOSURE_METERING_CENTER_WEIGHTED``
  95       - Average the light information coming from the entire frame giving
  96         priority to the center of the metered area.
  97     * - ``V4L2_EXPOSURE_METERING_SPOT``
  98       - Measure only very small area at the center of the frame.
  99     * - ``V4L2_EXPOSURE_METERING_MATRIX``
 100       - A multi-zone metering. The light intensity is measured in several
 101         points of the frame and the results are combined. The algorithm of
 102         the zones selection and their significance in calculating the
 103         final value is device dependent.
 104
 105
 106
 107 ``V4L2_CID_PAN_RELATIVE (integer)``
 108     This control turns the camera horizontally by the specified amount.
 109     The unit is undefined. A positive value moves the camera to the
 110     right (clockwise when viewed from above), a negative value to the
 111     left. A value of zero does not cause motion. This is a write-only
 112     control.
 113
 114 ``V4L2_CID_TILT_RELATIVE (integer)``
 115     This control turns the camera vertically by the specified amount.
 116     The unit is undefined. A positive value moves the camera up, a
 117     negative value down. A value of zero does not cause motion. This is
 118     a write-only control.
 119
 120 ``V4L2_CID_PAN_RESET (button)``
 121     When this control is set, the camera moves horizontally to the
 122     default position.
 123
 124 ``V4L2_CID_TILT_RESET (button)``
 125     When this control is set, the camera moves vertically to the default
 126     position.
 127
 128 ``V4L2_CID_PAN_ABSOLUTE (integer)``
 129     This control turns the camera horizontally to the specified
 130     position. Positive values move the camera to the right (clockwise
 131     when viewed from above), negative values to the left. Drivers should
 132     interpret the values as arc seconds, with valid values between -180
 133     * 3600 and +180 * 3600 inclusive.
 134
 135 ``V4L2_CID_TILT_ABSOLUTE (integer)``
 136     This control turns the camera vertically to the specified position.
 137     Positive values move the camera up, negative values down. Drivers
 138     should interpret the values as arc seconds, with valid values
 139     between -180 * 3600 and +180 * 3600 inclusive.
 140
 141 ``V4L2_CID_FOCUS_ABSOLUTE (integer)``
 142     This control sets the focal point of the camera to the specified
 143     position. The unit is undefined. Positive values set the focus
 144     closer to the camera, negative values towards infinity.
 145
 146 ``V4L2_CID_FOCUS_RELATIVE (integer)``
 147     This control moves the focal point of the camera by the specified
 148     amount. The unit is undefined. Positive values move the focus closer
 149     to the camera, negative values towards infinity. This is a
 150     write-only control.
 151
 152 ``V4L2_CID_FOCUS_AUTO (boolean)``
 153     Enables continuous automatic focus adjustments. The effect of manual
 154     focus adjustments while this feature is enabled is undefined,
 155     drivers should ignore such requests.
 156
 157 ``V4L2_CID_AUTO_FOCUS_START (button)``
 158     Starts single auto focus process. The effect of setting this control
 159     when ``V4L2_CID_FOCUS_AUTO`` is set to ``TRUE`` (1) is undefined,
 160     drivers should ignore such requests.
 161
 162 ``V4L2_CID_AUTO_FOCUS_STOP (button)``
 163     Aborts automatic focusing started with ``V4L2_CID_AUTO_FOCUS_START``
 164     control. It is effective only when the continuous autofocus is
 165     disabled, that is when ``V4L2_CID_FOCUS_AUTO`` control is set to
 166     ``FALSE`` (0).
 167
 168 .. _v4l2-auto-focus-status:
 169
 170 ``V4L2_CID_AUTO_FOCUS_STATUS (bitmask)``
 171     The automatic focus status. This is a read-only control.
 172
 173     Setting ``V4L2_LOCK_FOCUS`` lock bit of the ``V4L2_CID_3A_LOCK``
 174     control may stop updates of the ``V4L2_CID_AUTO_FOCUS_STATUS``
 175     control value.
 176
 177 .. tabularcolumns:: |p{6.8cm}|p{10.7cm}|
 178
 179 .. flat-table::
 180     :header-rows:  0
 181     :stub-columns: 0
 182
 183     * - ``V4L2_AUTO_FOCUS_STATUS_IDLE``
 184       - Automatic focus is not active.
 185     * - ``V4L2_AUTO_FOCUS_STATUS_BUSY``
 186       - Automatic focusing is in progress.
 187     * - ``V4L2_AUTO_FOCUS_STATUS_REACHED``
 188       - Focus has been reached.
 189     * - ``V4L2_AUTO_FOCUS_STATUS_FAILED``
 190       - Automatic focus has failed, the driver will not transition from
 191         this state until another action is performed by an application.
 192
 193
 194
 195 .. _v4l2-auto-focus-range:
 196
 197 ``V4L2_CID_AUTO_FOCUS_RANGE``
 198     (enum)
 199
 200 enum v4l2_auto_focus_range -
 201     Determines auto focus distance range for which lens may be adjusted.
 202
 203 .. tabularcolumns:: |p{6.9cm}|p{10.6cm}|
 204
 205 .. flat-table::
 206     :header-rows:  0
 207     :stub-columns: 0
 208
 209     * - ``V4L2_AUTO_FOCUS_RANGE_AUTO``
 210       - The camera automatically selects the focus range.
 211     * - ``V4L2_AUTO_FOCUS_RANGE_NORMAL``
 212       - Normal distance range, limited for best automatic focus
 213         performance.
 214     * - ``V4L2_AUTO_FOCUS_RANGE_MACRO``
 215       - Macro (close-up) auto focus. The camera will use its minimum
 216         possible distance for auto focus.
 217     * - ``V4L2_AUTO_FOCUS_RANGE_INFINITY``
 218       - The lens is set to focus on an object at infinite distance.
 219
 220
 221
 222 ``V4L2_CID_ZOOM_ABSOLUTE (integer)``
 223     Specify the objective lens focal length as an absolute value. The
 224     zoom unit is driver-specific and its value should be a positive
 225     integer.
 226
 227 ``V4L2_CID_ZOOM_RELATIVE (integer)``
 228     Specify the objective lens focal length relatively to the current
 229     value. Positive values move the zoom lens group towards the
 230     telephoto direction, negative values towards the wide-angle
 231     direction. The zoom unit is driver-specific. This is a write-only
 232     control.
 233
 234 ``V4L2_CID_ZOOM_CONTINUOUS (integer)``
 235     Move the objective lens group at the specified speed until it
 236     reaches physical device limits or until an explicit request to stop
 237     the movement. A positive value moves the zoom lens group towards the
 238     telephoto direction. A value of zero stops the zoom lens group
 239     movement. A negative value moves the zoom lens group towards the
 240     wide-angle direction. The zoom speed unit is driver-specific.
 241
 242 ``V4L2_CID_IRIS_ABSOLUTE (integer)``
 243     This control sets the camera's aperture to the specified value. The
 244     unit is undefined. Larger values open the iris wider, smaller values
 245     close it.
 246
 247 ``V4L2_CID_IRIS_RELATIVE (integer)``
 248     This control modifies the camera's aperture by the specified amount.
 249     The unit is undefined. Positive values open the iris one step
 250     further, negative values close it one step further. This is a
 251     write-only control.
 252
 253 ``V4L2_CID_PRIVACY (boolean)``
 254     Prevent video from being acquired by the camera. When this control
 255     is set to ``TRUE`` (1), no image can be captured by the camera.
 256     Common means to enforce privacy are mechanical obturation of the
 257     sensor and firmware image processing, but the device is not
 258     restricted to these methods. Devices that implement the privacy
 259     control must support read access and may support write access.
 260
 261 ``V4L2_CID_BAND_STOP_FILTER (integer)``
 262     Switch the band-stop filter of a camera sensor on or off, or specify
 263     its strength. Such band-stop filters can be used, for example, to
 264     filter out the fluorescent light component.
 265
 266 .. _v4l2-auto-n-preset-white-balance:
 267
 268 ``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE``
 269     (enum)
 270
 271 enum v4l2_auto_n_preset_white_balance -
 272     Sets white balance to automatic, manual or a preset. The presets
 273     determine color temperature of the light as a hint to the camera for
 274     white balance adjustments resulting in most accurate color
 275     representation. The following white balance presets are listed in
 276     order of increasing color temperature.
 277
 278 .. tabularcolumns:: |p{7.4cm}|p{10.1cm}|
 279
 280 .. flat-table::
 281     :header-rows:  0
 282     :stub-columns: 0
 283
 284     * - ``V4L2_WHITE_BALANCE_MANUAL``
 285       - Manual white balance.
 286     * - ``V4L2_WHITE_BALANCE_AUTO``
 287       - Automatic white balance adjustments.
 288     * - ``V4L2_WHITE_BALANCE_INCANDESCENT``
 289       - White balance setting for incandescent (tungsten) lighting. It
 290         generally cools down the colors and corresponds approximately to
 291         2500...3500 K color temperature range.
 292     * - ``V4L2_WHITE_BALANCE_FLUORESCENT``
 293       - White balance preset for fluorescent lighting. It corresponds
 294         approximately to 4000...5000 K color temperature.
 295     * - ``V4L2_WHITE_BALANCE_FLUORESCENT_H``
 296       - With this setting the camera will compensate for fluorescent H
 297         lighting.
 298     * - ``V4L2_WHITE_BALANCE_HORIZON``
 299       - White balance setting for horizon daylight. It corresponds
 300         approximately to 5000 K color temperature.
 301     * - ``V4L2_WHITE_BALANCE_DAYLIGHT``
 302       - White balance preset for daylight (with clear sky). It corresponds
 303         approximately to 5000...6500 K color temperature.
 304     * - ``V4L2_WHITE_BALANCE_FLASH``
 305       - With this setting the camera will compensate for the flash light.
 306         It slightly warms up the colors and corresponds roughly to
 307         5000...5500 K color temperature.
 308     * - ``V4L2_WHITE_BALANCE_CLOUDY``
 309       - White balance preset for moderately overcast sky. This option
 310         corresponds approximately to 6500...8000 K color temperature
 311         range.
 312     * - ``V4L2_WHITE_BALANCE_SHADE``
 313       - White balance preset for shade or heavily overcast sky. It
 314         corresponds approximately to 9000...10000 K color temperature.
 315
 316
 317
 318 .. _v4l2-wide-dynamic-range:
 319
 320 ``V4L2_CID_WIDE_DYNAMIC_RANGE (boolean)``
 321     Enables or disables the camera's wide dynamic range feature. This
 322     feature allows to obtain clear images in situations where intensity
 323     of the illumination varies significantly throughout the scene, i.e.
 324     there are simultaneously very dark and very bright areas. It is most
 325     commonly realized in cameras by combining two subsequent frames with
 326     different exposure times.  [#f1]_
 327
 328 .. _v4l2-image-stabilization:
 329
 330 ``V4L2_CID_IMAGE_STABILIZATION (boolean)``
 331     Enables or disables image stabilization.
 332
 333 ``V4L2_CID_ISO_SENSITIVITY (integer menu)``
 334     Determines ISO equivalent of an image sensor indicating the sensor's
 335     sensitivity to light. The numbers are expressed in arithmetic scale,
 336     as per :ref:`iso12232` standard, where doubling the sensor
 337     sensitivity is represented by doubling the numerical ISO value.
 338     Applications should interpret the values as standard ISO values
 339     multiplied by 1000, e.g. control value 800 stands for ISO 0.8.
 340     Drivers will usually support only a subset of standard ISO values.
 341     The effect of setting this control while the
 342     ``V4L2_CID_ISO_SENSITIVITY_AUTO`` control is set to a value other
 343     than ``V4L2_CID_ISO_SENSITIVITY_MANUAL`` is undefined, drivers
 344     should ignore such requests.
 345
 346 .. _v4l2-iso-sensitivity-auto-type:
 347
 348 ``V4L2_CID_ISO_SENSITIVITY_AUTO``
 349     (enum)
 350
 351 enum v4l2_iso_sensitivity_type -
 352     Enables or disables automatic ISO sensitivity adjustments.
 353
 354
 355
 356 .. flat-table::
 357     :header-rows:  0
 358     :stub-columns: 0
 359
 360     * - ``V4L2_CID_ISO_SENSITIVITY_MANUAL``
 361       - Manual ISO sensitivity.
 362     * - ``V4L2_CID_ISO_SENSITIVITY_AUTO``
 363       - Automatic ISO sensitivity adjustments.
 364
 365
 366
 367 .. _v4l2-scene-mode:
 368
 369 ``V4L2_CID_SCENE_MODE``
 370     (enum)
 371
 372 enum v4l2_scene_mode -
 373     This control allows to select scene programs as the camera automatic
 374     modes optimized for common shooting scenes. Within these modes the
 375     camera determines best exposure, aperture, focusing, light metering,
 376     white balance and equivalent sensitivity. The controls of those
 377     parameters are influenced by the scene mode control. An exact
 378     behavior in each mode is subject to the camera specification.
 379
 380     When the scene mode feature is not used, this control should be set
 381     to ``V4L2_SCENE_MODE_NONE`` to make sure the other possibly related
 382     controls are accessible. The following scene programs are defined:
 383
 384 .. raw:: latex
 385
 386     \small
 387
 388 .. tabularcolumns:: |p{5.9cm}|p{11.6cm}|
 389
 390 .. cssclass:: longtable
 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 .. raw:: latex
 463
 464     \normalsize
 465
 466
 467 ``V4L2_CID_3A_LOCK (bitmask)``
 468     This control locks or unlocks the automatic focus, exposure and
 469     white balance. The automatic adjustments can be paused independently
 470     by setting the corresponding lock bit to 1. The camera then retains
 471     the settings until the lock bit is cleared. The following lock bits
 472     are defined:
 473
 474     When a given algorithm is not enabled, drivers should ignore
 475     requests to lock it and should return no error. An example might be
 476     an application setting bit ``V4L2_LOCK_WHITE_BALANCE`` when the
 477     ``V4L2_CID_AUTO_WHITE_BALANCE`` control is set to ``FALSE``. The
 478     value of this control may be changed by exposure, white balance or
 479     focus controls.
 480
 481
 482
 483 .. flat-table::
 484     :header-rows:  0
 485     :stub-columns: 0
 486
 487     * - ``V4L2_LOCK_EXPOSURE``
 488       - Automatic exposure adjustments lock.
 489     * - ``V4L2_LOCK_WHITE_BALANCE``
 490       - Automatic white balance adjustments lock.
 491     * - ``V4L2_LOCK_FOCUS``
 492       - Automatic focus lock.
 493
 494
 495
 496 ``V4L2_CID_PAN_SPEED (integer)``
 497     This control turns the camera horizontally at the specific speed.
 498     The unit is undefined. A positive value moves the camera to the
 499     right (clockwise when viewed from above), a negative value to the
 500     left. A value of zero stops the motion if one is in progress and has
 501     no effect otherwise.
 502
 503 ``V4L2_CID_TILT_SPEED (integer)``
 504     This control turns the camera vertically at the specified speed. The
 505     unit is undefined. A positive value moves the camera up, a negative
 506     value down. A value of zero stops the motion if one is in progress
 507     and has no effect otherwise.
 508
 509 ``V4L2_CID_CAMERA_ORIENTATION (menu)``
 510     This read-only control describes the camera orientation by reporting its
 511     mounting position on the device where the camera is installed. The control
 512     value is constant and not modifiable by software. This control is
 513     particularly meaningful for devices which have a well defined orientation,
 514     such as phones, laptops and portable devices since the control is expressed
 515     as a position relative to the device's intended usage orientation. For
 516     example, a camera installed on the user-facing side of a phone, a tablet or
 517     a laptop device is said to be have ``V4L2_CAMERA_ORIENTATION_FRONT``
 518     orientation, while a camera installed on the opposite side of the front one
 519     is said to be have ``V4L2_CAMERA_ORIENTATION_BACK`` orientation. Camera
 520     sensors not directly attached to the device, or attached in a way that
 521     allows them to move freely, such as webcams and digital cameras, are said to
 522     have the ``V4L2_CAMERA_ORIENTATION_EXTERNAL`` orientation.
 523
 524
 525 .. tabularcolumns:: |p{7.7cm}|p{9.8cm}|
 526
 527 .. flat-table::
 528     :header-rows:  0
 529     :stub-columns: 0
 530
 531     * - ``V4L2_CAMERA_ORIENTATION_FRONT``
 532       - The camera is oriented towards the user facing side of the device.
 533     * - ``V4L2_CAMERA_ORIENTATION_BACK``
 534       - The camera is oriented towards the back facing side of the device.
 535     * - ``V4L2_CAMERA_ORIENTATION_EXTERNAL``
 536       - The camera is not directly attached to the device and is freely movable.
 537
 538
 539
 540 ``V4L2_CID_CAMERA_SENSOR_ROTATION (integer)``
 541     This read-only control describes the rotation correction in degrees in the
 542     counter-clockwise direction to be applied to the captured images once
 543     captured to memory to compensate for the camera sensor mounting rotation.
 544
 545     For a precise definition of the sensor mounting rotation refer to the
 546     extensive description of the 'rotation' properties in the device tree
 547     bindings file 'video-interfaces.txt'.
 548
 549     A few examples are below reported, using a shark swimming from left to
 550     right in front of the user as the example scene to capture. ::
 551
 552                  0               X-axis
 553                0 +------------------------------------->
 554                  !
 555                  !
 556                  !
 557                  !           |\____)\___
 558                  !           ) _____  __`<
 559                  !           |/     )/
 560                  !
 561                  !
 562                  !
 563                  V
 564                Y-axis
 565
 566     Example one - Webcam
 567
 568     Assuming you can bring your laptop with you while swimming with sharks,
 569     the camera module of the laptop is installed on the user facing part of a
 570     laptop screen casing, and is typically used for video calls. The captured
 571     images are meant to be displayed in landscape mode (width > height) on the
 572     laptop screen.
 573
 574     The camera is typically mounted upside-down to compensate the lens optical
 575     inversion effect. In this case the value of the
 576     V4L2_CID_CAMERA_SENSOR_ROTATION control is 0, no rotation is required to
 577     display images correctly to the user.
 578
 579     If the camera sensor is not mounted upside-down it is required to compensate
 580     the lens optical inversion effect and the value of the
 581     V4L2_CID_CAMERA_SENSOR_ROTATION control is 180 degrees, as images will
 582     result rotated when captured to memory. ::
 583
 584                  +--------------------------------------+
 585                  !                                      !
 586                  !                                      !
 587                  !                                      !
 588                  !              __/(_____/|             !
 589                  !            >.___  ____ (             !
 590                  !                 \(    \|             !
 591                  !                                      !
 592                  !                                      !
 593                  !                                      !
 594                  +--------------------------------------+
 595
 596     A software rotation correction of 180 degrees has to be applied to correctly
 597     display the image on the user screen. ::
 598
 599                  +--------------------------------------+
 600                  !                                      !
 601                  !                                      !
 602                  !                                      !
 603                  !             |\____)\___              !
 604                  !             ) _____  __`<            !
 605                  !             |/     )/                !
 606                  !                                      !
 607                  !                                      !
 608                  !                                      !
 609                  +--------------------------------------+
 610
 611     Example two - Phone camera
 612
 613     It is more handy to go and swim with sharks with only your mobile phone
 614     with you and take pictures with the camera that is installed on the back
 615     side of the device, facing away from the user. The captured images are meant
 616     to be displayed in portrait mode (height > width) to match the device screen
 617     orientation and the device usage orientation used when taking the picture.
 618
 619     The camera sensor is typically mounted with its pixel array longer side
 620     aligned to the device longer side, upside-down mounted to compensate for
 621     the lens optical inversion effect.
 622
 623     The images once captured to memory will be rotated and the value of the
 624     V4L2_CID_CAMERA_SENSOR_ROTATION will report a 90 degree rotation. ::
 625
 626
 627                  +-------------------------------------+
 628                  |                 _ _                 |
 629                  |                \   /                |
 630                  |                 | |                 |
 631                  |                 | |                 |
 632                  |                 |  >                |
 633                  |                <  |                 |
 634                  |                 | |                 |
 635                  |                   .                 |
 636                  |                  V                  |
 637                  +-------------------------------------+
 638
 639     A correction of 90 degrees in counter-clockwise direction has to be
 640     applied to correctly display the image in portrait mode on the device
 641     screen. ::
 642
 643                           +--------------------+
 644                           |                    |
 645                           |                    |
 646                           |                    |
 647                           |                    |
 648                           |                    |
 649                           |                    |
 650                           |   |\____)\___      |
 651                           |   ) _____  __`<    |
 652                           |   |/     )/        |
 653                           |                    |
 654                           |                    |
 655                           |                    |
 656                           |                    |
 657                           |                    |
 658                           +--------------------+
 659
 660
 661 .. [#f1]
 662    This control may be changed to a menu control in the future, if more
 663    options are required.