0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002
0003 .. _camera-controls:
0004
0005 ************************
0006 Camera Control Reference
0007 ************************
0008
0009 The Camera class includes controls for mechanical (or equivalent
0010 digital) features of a device such as controllable lenses or sensors.
0011
0012
0013 .. _camera-control-id:
0014
0015 Camera Control IDs
0016 ==================
0017
0018 ``V4L2_CID_CAMERA_CLASS (class)``
0019 The Camera class descriptor. Calling
0020 :ref:`VIDIOC_QUERYCTRL` for this control will
0021 return a description of this control class.
0022
0023 .. _v4l2-exposure-auto-type:
0024
0025 ``V4L2_CID_EXPOSURE_AUTO``
0026 (enum)
0027
0028 enum v4l2_exposure_auto_type -
0029 Enables automatic adjustments of the exposure time and/or iris
0030 aperture. The effect of manual changes of the exposure time or iris
0031 aperture while these features are enabled is undefined, drivers
0032 should ignore such requests. Possible values are:
0033
0034
0035 .. tabularcolumns:: |p{7.1cm}|p{10.4cm}|
0036
0037 .. flat-table::
0038 :header-rows: 0
0039 :stub-columns: 0
0040
0041 * - ``V4L2_EXPOSURE_AUTO``
0042 - Automatic exposure time, automatic iris aperture.
0043 * - ``V4L2_EXPOSURE_MANUAL``
0044 - Manual exposure time, manual iris.
0045 * - ``V4L2_EXPOSURE_SHUTTER_PRIORITY``
0046 - Manual exposure time, auto iris.
0047 * - ``V4L2_EXPOSURE_APERTURE_PRIORITY``
0048 - Auto exposure time, manual iris.
0049
0050
0051
0052 ``V4L2_CID_EXPOSURE_ABSOLUTE (integer)``
0053 Determines the exposure time of the camera sensor. The exposure time
0054 is limited by the frame interval. Drivers should interpret the
0055 values as 100 µs units, where the value 1 stands for 1/10000th of a
0056 second, 10000 for 1 second and 100000 for 10 seconds.
0057
0058 ``V4L2_CID_EXPOSURE_AUTO_PRIORITY (boolean)``
0059 When ``V4L2_CID_EXPOSURE_AUTO`` is set to ``AUTO`` or
0060 ``APERTURE_PRIORITY``, this control determines if the device may
0061 dynamically vary the frame rate. By default this feature is disabled
0062 (0) and the frame rate must remain constant.
0063
0064 ``V4L2_CID_AUTO_EXPOSURE_BIAS (integer menu)``
0065 Determines the automatic exposure compensation, it is effective only
0066 when ``V4L2_CID_EXPOSURE_AUTO`` control is set to ``AUTO``,
0067 ``SHUTTER_PRIORITY`` or ``APERTURE_PRIORITY``. It is expressed in
0068 terms of EV, drivers should interpret the values as 0.001 EV units,
0069 where the value 1000 stands for +1 EV.
0070
0071 Increasing the exposure compensation value is equivalent to
0072 decreasing the exposure value (EV) and will increase the amount of
0073 light at the image sensor. The camera performs the exposure
0074 compensation by adjusting absolute exposure time and/or aperture.
0075
0076 .. _v4l2-exposure-metering:
0077
0078 ``V4L2_CID_EXPOSURE_METERING``
0079 (enum)
0080
0081 enum v4l2_exposure_metering -
0082 Determines how the camera measures the amount of light available for
0083 the frame exposure. Possible values are:
0084
0085 .. tabularcolumns:: |p{8.7cm}|p{8.7cm}|
0086
0087 .. flat-table::
0088 :header-rows: 0
0089 :stub-columns: 0
0090
0091 * - ``V4L2_EXPOSURE_METERING_AVERAGE``
0092 - Use the light information coming from the entire frame and average
0093 giving no weighting to any particular portion of the metered area.
0094 * - ``V4L2_EXPOSURE_METERING_CENTER_WEIGHTED``
0095 - Average the light information coming from the entire frame giving
0096 priority to the center of the metered area.
0097 * - ``V4L2_EXPOSURE_METERING_SPOT``
0098 - Measure only very small area at the center of the frame.
0099 * - ``V4L2_EXPOSURE_METERING_MATRIX``
0100 - A multi-zone metering. The light intensity is measured in several
0101 points of the frame and the results are combined. The algorithm of
0102 the zones selection and their significance in calculating the
0103 final value is device dependent.
0104
0105
0106
0107 ``V4L2_CID_PAN_RELATIVE (integer)``
0108 This control turns the camera horizontally by the specified amount.
0109 The unit is undefined. A positive value moves the camera to the
0110 right (clockwise when viewed from above), a negative value to the
0111 left. A value of zero does not cause motion. This is a write-only
0112 control.
0113
0114 ``V4L2_CID_TILT_RELATIVE (integer)``
0115 This control turns the camera vertically by the specified amount.
0116 The unit is undefined. A positive value moves the camera up, a
0117 negative value down. A value of zero does not cause motion. This is
0118 a write-only control.
0119
0120 ``V4L2_CID_PAN_RESET (button)``
0121 When this control is set, the camera moves horizontally to the
0122 default position.
0123
0124 ``V4L2_CID_TILT_RESET (button)``
0125 When this control is set, the camera moves vertically to the default
0126 position.
0127
0128 ``V4L2_CID_PAN_ABSOLUTE (integer)``
0129 This control turns the camera horizontally to the specified
0130 position. Positive values move the camera to the right (clockwise
0131 when viewed from above), negative values to the left. Drivers should
0132 interpret the values as arc seconds, with valid values between -180
0133 * 3600 and +180 * 3600 inclusive.
0134
0135 ``V4L2_CID_TILT_ABSOLUTE (integer)``
0136 This control turns the camera vertically to the specified position.
0137 Positive values move the camera up, negative values down. Drivers
0138 should interpret the values as arc seconds, with valid values
0139 between -180 * 3600 and +180 * 3600 inclusive.
0140
0141 ``V4L2_CID_FOCUS_ABSOLUTE (integer)``
0142 This control sets the focal point of the camera to the specified
0143 position. The unit is undefined. Positive values set the focus
0144 closer to the camera, negative values towards infinity.
0145
0146 ``V4L2_CID_FOCUS_RELATIVE (integer)``
0147 This control moves the focal point of the camera by the specified
0148 amount. The unit is undefined. Positive values move the focus closer
0149 to the camera, negative values towards infinity. This is a
0150 write-only control.
0151
0152 ``V4L2_CID_FOCUS_AUTO (boolean)``
0153 Enables continuous automatic focus adjustments. The effect of manual
0154 focus adjustments while this feature is enabled is undefined,
0155 drivers should ignore such requests.
0156
0157 ``V4L2_CID_AUTO_FOCUS_START (button)``
0158 Starts single auto focus process. The effect of setting this control
0159 when ``V4L2_CID_FOCUS_AUTO`` is set to ``TRUE`` (1) is undefined,
0160 drivers should ignore such requests.
0161
0162 ``V4L2_CID_AUTO_FOCUS_STOP (button)``
0163 Aborts automatic focusing started with ``V4L2_CID_AUTO_FOCUS_START``
0164 control. It is effective only when the continuous autofocus is
0165 disabled, that is when ``V4L2_CID_FOCUS_AUTO`` control is set to
0166 ``FALSE`` (0).
0167
0168 .. _v4l2-auto-focus-status:
0169
0170 ``V4L2_CID_AUTO_FOCUS_STATUS (bitmask)``
0171 The automatic focus status. This is a read-only control.
0172
0173 Setting ``V4L2_LOCK_FOCUS`` lock bit of the ``V4L2_CID_3A_LOCK``
0174 control may stop updates of the ``V4L2_CID_AUTO_FOCUS_STATUS``
0175 control value.
0176
0177 .. tabularcolumns:: |p{6.8cm}|p{10.7cm}|
0178
0179 .. flat-table::
0180 :header-rows: 0
0181 :stub-columns: 0
0182
0183 * - ``V4L2_AUTO_FOCUS_STATUS_IDLE``
0184 - Automatic focus is not active.
0185 * - ``V4L2_AUTO_FOCUS_STATUS_BUSY``
0186 - Automatic focusing is in progress.
0187 * - ``V4L2_AUTO_FOCUS_STATUS_REACHED``
0188 - Focus has been reached.
0189 * - ``V4L2_AUTO_FOCUS_STATUS_FAILED``
0190 - Automatic focus has failed, the driver will not transition from
0191 this state until another action is performed by an application.
0192
0193
0194
0195 .. _v4l2-auto-focus-range:
0196
0197 ``V4L2_CID_AUTO_FOCUS_RANGE``
0198 (enum)
0199
0200 enum v4l2_auto_focus_range -
0201 Determines auto focus distance range for which lens may be adjusted.
0202
0203 .. tabularcolumns:: |p{6.9cm}|p{10.6cm}|
0204
0205 .. flat-table::
0206 :header-rows: 0
0207 :stub-columns: 0
0208
0209 * - ``V4L2_AUTO_FOCUS_RANGE_AUTO``
0210 - The camera automatically selects the focus range.
0211 * - ``V4L2_AUTO_FOCUS_RANGE_NORMAL``
0212 - Normal distance range, limited for best automatic focus
0213 performance.
0214 * - ``V4L2_AUTO_FOCUS_RANGE_MACRO``
0215 - Macro (close-up) auto focus. The camera will use its minimum
0216 possible distance for auto focus.
0217 * - ``V4L2_AUTO_FOCUS_RANGE_INFINITY``
0218 - The lens is set to focus on an object at infinite distance.
0219
0220
0221
0222 ``V4L2_CID_ZOOM_ABSOLUTE (integer)``
0223 Specify the objective lens focal length as an absolute value. The
0224 zoom unit is driver-specific and its value should be a positive
0225 integer.
0226
0227 ``V4L2_CID_ZOOM_RELATIVE (integer)``
0228 Specify the objective lens focal length relatively to the current
0229 value. Positive values move the zoom lens group towards the
0230 telephoto direction, negative values towards the wide-angle
0231 direction. The zoom unit is driver-specific. This is a write-only
0232 control.
0233
0234 ``V4L2_CID_ZOOM_CONTINUOUS (integer)``
0235 Move the objective lens group at the specified speed until it
0236 reaches physical device limits or until an explicit request to stop
0237 the movement. A positive value moves the zoom lens group towards the
0238 telephoto direction. A value of zero stops the zoom lens group
0239 movement. A negative value moves the zoom lens group towards the
0240 wide-angle direction. The zoom speed unit is driver-specific.
0241
0242 ``V4L2_CID_IRIS_ABSOLUTE (integer)``
0243 This control sets the camera's aperture to the specified value. The
0244 unit is undefined. Larger values open the iris wider, smaller values
0245 close it.
0246
0247 ``V4L2_CID_IRIS_RELATIVE (integer)``
0248 This control modifies the camera's aperture by the specified amount.
0249 The unit is undefined. Positive values open the iris one step
0250 further, negative values close it one step further. This is a
0251 write-only control.
0252
0253 ``V4L2_CID_PRIVACY (boolean)``
0254 Prevent video from being acquired by the camera. When this control
0255 is set to ``TRUE`` (1), no image can be captured by the camera.
0256 Common means to enforce privacy are mechanical obturation of the
0257 sensor and firmware image processing, but the device is not
0258 restricted to these methods. Devices that implement the privacy
0259 control must support read access and may support write access.
0260
0261 ``V4L2_CID_BAND_STOP_FILTER (integer)``
0262 Switch the band-stop filter of a camera sensor on or off, or specify
0263 its strength. Such band-stop filters can be used, for example, to
0264 filter out the fluorescent light component.
0265
0266 .. _v4l2-auto-n-preset-white-balance:
0267
0268 ``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE``
0269 (enum)
0270
0271 enum v4l2_auto_n_preset_white_balance -
0272 Sets white balance to automatic, manual or a preset. The presets
0273 determine color temperature of the light as a hint to the camera for
0274 white balance adjustments resulting in most accurate color
0275 representation. The following white balance presets are listed in
0276 order of increasing color temperature.
0277
0278 .. tabularcolumns:: |p{7.4cm}|p{10.1cm}|
0279
0280 .. flat-table::
0281 :header-rows: 0
0282 :stub-columns: 0
0283
0284 * - ``V4L2_WHITE_BALANCE_MANUAL``
0285 - Manual white balance.
0286 * - ``V4L2_WHITE_BALANCE_AUTO``
0287 - Automatic white balance adjustments.
0288 * - ``V4L2_WHITE_BALANCE_INCANDESCENT``
0289 - White balance setting for incandescent (tungsten) lighting. It
0290 generally cools down the colors and corresponds approximately to
0291 2500...3500 K color temperature range.
0292 * - ``V4L2_WHITE_BALANCE_FLUORESCENT``
0293 - White balance preset for fluorescent lighting. It corresponds
0294 approximately to 4000...5000 K color temperature.
0295 * - ``V4L2_WHITE_BALANCE_FLUORESCENT_H``
0296 - With this setting the camera will compensate for fluorescent H
0297 lighting.
0298 * - ``V4L2_WHITE_BALANCE_HORIZON``
0299 - White balance setting for horizon daylight. It corresponds
0300 approximately to 5000 K color temperature.
0301 * - ``V4L2_WHITE_BALANCE_DAYLIGHT``
0302 - White balance preset for daylight (with clear sky). It corresponds
0303 approximately to 5000...6500 K color temperature.
0304 * - ``V4L2_WHITE_BALANCE_FLASH``
0305 - With this setting the camera will compensate for the flash light.
0306 It slightly warms up the colors and corresponds roughly to
0307 5000...5500 K color temperature.
0308 * - ``V4L2_WHITE_BALANCE_CLOUDY``
0309 - White balance preset for moderately overcast sky. This option
0310 corresponds approximately to 6500...8000 K color temperature
0311 range.
0312 * - ``V4L2_WHITE_BALANCE_SHADE``
0313 - White balance preset for shade or heavily overcast sky. It
0314 corresponds approximately to 9000...10000 K color temperature.
0315
0316
0317
0318 .. _v4l2-wide-dynamic-range:
0319
0320 ``V4L2_CID_WIDE_DYNAMIC_RANGE (boolean)``
0321 Enables or disables the camera's wide dynamic range feature. This
0322 feature allows to obtain clear images in situations where intensity
0323 of the illumination varies significantly throughout the scene, i.e.
0324 there are simultaneously very dark and very bright areas. It is most
0325 commonly realized in cameras by combining two subsequent frames with
0326 different exposure times. [#f1]_
0327
0328 .. _v4l2-image-stabilization:
0329
0330 ``V4L2_CID_IMAGE_STABILIZATION (boolean)``
0331 Enables or disables image stabilization.
0332
0333 ``V4L2_CID_ISO_SENSITIVITY (integer menu)``
0334 Determines ISO equivalent of an image sensor indicating the sensor's
0335 sensitivity to light. The numbers are expressed in arithmetic scale,
0336 as per :ref:`iso12232` standard, where doubling the sensor
0337 sensitivity is represented by doubling the numerical ISO value.
0338 Applications should interpret the values as standard ISO values
0339 multiplied by 1000, e.g. control value 800 stands for ISO 0.8.
0340 Drivers will usually support only a subset of standard ISO values.
0341 The effect of setting this control while the
0342 ``V4L2_CID_ISO_SENSITIVITY_AUTO`` control is set to a value other
0343 than ``V4L2_CID_ISO_SENSITIVITY_MANUAL`` is undefined, drivers
0344 should ignore such requests.
0345
0346 .. _v4l2-iso-sensitivity-auto-type:
0347
0348 ``V4L2_CID_ISO_SENSITIVITY_AUTO``
0349 (enum)
0350
0351 enum v4l2_iso_sensitivity_type -
0352 Enables or disables automatic ISO sensitivity adjustments.
0353
0354
0355
0356 .. flat-table::
0357 :header-rows: 0
0358 :stub-columns: 0
0359
0360 * - ``V4L2_CID_ISO_SENSITIVITY_MANUAL``
0361 - Manual ISO sensitivity.
0362 * - ``V4L2_CID_ISO_SENSITIVITY_AUTO``
0363 - Automatic ISO sensitivity adjustments.
0364
0365
0366
0367 .. _v4l2-scene-mode:
0368
0369 ``V4L2_CID_SCENE_MODE``
0370 (enum)
0371
0372 enum v4l2_scene_mode -
0373 This control allows to select scene programs as the camera automatic
0374 modes optimized for common shooting scenes. Within these modes the
0375 camera determines best exposure, aperture, focusing, light metering,
0376 white balance and equivalent sensitivity. The controls of those
0377 parameters are influenced by the scene mode control. An exact
0378 behavior in each mode is subject to the camera specification.
0379
0380 When the scene mode feature is not used, this control should be set
0381 to ``V4L2_SCENE_MODE_NONE`` to make sure the other possibly related
0382 controls are accessible. The following scene programs are defined:
0383
0384 .. raw:: latex
0385
0386 \small
0387
0388 .. tabularcolumns:: |p{5.9cm}|p{11.6cm}|
0389
0390 .. cssclass:: longtable
0391
0392 .. flat-table::
0393 :header-rows: 0
0394 :stub-columns: 0
0395
0396 * - ``V4L2_SCENE_MODE_NONE``
0397 - The scene mode feature is disabled.
0398 * - ``V4L2_SCENE_MODE_BACKLIGHT``
0399 - Backlight. Compensates for dark shadows when light is coming from
0400 behind a subject, also by automatically turning on the flash.
0401 * - ``V4L2_SCENE_MODE_BEACH_SNOW``
0402 - Beach and snow. This mode compensates for all-white or bright
0403 scenes, which tend to look gray and low contrast, when camera's
0404 automatic exposure is based on an average scene brightness. To
0405 compensate, this mode automatically slightly overexposes the
0406 frames. The white balance may also be adjusted to compensate for
0407 the fact that reflected snow looks bluish rather than white.
0408 * - ``V4L2_SCENE_MODE_CANDLELIGHT``
0409 - Candle light. The camera generally raises the ISO sensitivity and
0410 lowers the shutter speed. This mode compensates for relatively
0411 close subject in the scene. The flash is disabled in order to
0412 preserve the ambiance of the light.
0413 * - ``V4L2_SCENE_MODE_DAWN_DUSK``
0414 - Dawn and dusk. Preserves the colors seen in low natural light
0415 before dusk and after down. The camera may turn off the flash, and
0416 automatically focus at infinity. It will usually boost saturation
0417 and lower the shutter speed.
0418 * - ``V4L2_SCENE_MODE_FALL_COLORS``
0419 - Fall colors. Increases saturation and adjusts white balance for
0420 color enhancement. Pictures of autumn leaves get saturated reds
0421 and yellows.
0422 * - ``V4L2_SCENE_MODE_FIREWORKS``
0423 - Fireworks. Long exposure times are used to capture the expanding
0424 burst of light from a firework. The camera may invoke image
0425 stabilization.
0426 * - ``V4L2_SCENE_MODE_LANDSCAPE``
0427 - Landscape. The camera may choose a small aperture to provide deep
0428 depth of field and long exposure duration to help capture detail
0429 in dim light conditions. The focus is fixed at infinity. Suitable
0430 for distant and wide scenery.
0431 * - ``V4L2_SCENE_MODE_NIGHT``
0432 - Night, also known as Night Landscape. Designed for low light
0433 conditions, it preserves detail in the dark areas without blowing
0434 out bright objects. The camera generally sets itself to a
0435 medium-to-high ISO sensitivity, with a relatively long exposure
0436 time, and turns flash off. As such, there will be increased image
0437 noise and the possibility of blurred image.
0438 * - ``V4L2_SCENE_MODE_PARTY_INDOOR``
0439 - Party and indoor. Designed to capture indoor scenes that are lit
0440 by indoor background lighting as well as the flash. The camera
0441 usually increases ISO sensitivity, and adjusts exposure for the
0442 low light conditions.
0443 * - ``V4L2_SCENE_MODE_PORTRAIT``
0444 - Portrait. The camera adjusts the aperture so that the depth of
0445 field is reduced, which helps to isolate the subject against a
0446 smooth background. Most cameras recognize the presence of faces in
0447 the scene and focus on them. The color hue is adjusted to enhance
0448 skin tones. The intensity of the flash is often reduced.
0449 * - ``V4L2_SCENE_MODE_SPORTS``
0450 - Sports. Significantly increases ISO and uses a fast shutter speed
0451 to freeze motion of rapidly-moving subjects. Increased image noise
0452 may be seen in this mode.
0453 * - ``V4L2_SCENE_MODE_SUNSET``
0454 - Sunset. Preserves deep hues seen in sunsets and sunrises. It bumps
0455 up the saturation.
0456 * - ``V4L2_SCENE_MODE_TEXT``
0457 - Text. It applies extra contrast and sharpness, it is typically a
0458 black-and-white mode optimized for readability. Automatic focus
0459 may be switched to close-up mode and this setting may also involve
0460 some lens-distortion correction.
0461
0462 .. raw:: latex
0463
0464 \normalsize
0465
0466
0467 ``V4L2_CID_3A_LOCK (bitmask)``
0468 This control locks or unlocks the automatic focus, exposure and
0469 white balance. The automatic adjustments can be paused independently
0470 by setting the corresponding lock bit to 1. The camera then retains
0471 the settings until the lock bit is cleared. The following lock bits
0472 are defined:
0473
0474 When a given algorithm is not enabled, drivers should ignore
0475 requests to lock it and should return no error. An example might be
0476 an application setting bit ``V4L2_LOCK_WHITE_BALANCE`` when the
0477 ``V4L2_CID_AUTO_WHITE_BALANCE`` control is set to ``FALSE``. The
0478 value of this control may be changed by exposure, white balance or
0479 focus controls.
0480
0481
0482
0483 .. flat-table::
0484 :header-rows: 0
0485 :stub-columns: 0
0486
0487 * - ``V4L2_LOCK_EXPOSURE``
0488 - Automatic exposure adjustments lock.
0489 * - ``V4L2_LOCK_WHITE_BALANCE``
0490 - Automatic white balance adjustments lock.
0491 * - ``V4L2_LOCK_FOCUS``
0492 - Automatic focus lock.
0493
0494
0495
0496 ``V4L2_CID_PAN_SPEED (integer)``
0497 This control turns the camera horizontally at the specific speed.
0498 The unit is undefined. A positive value moves the camera to the
0499 right (clockwise when viewed from above), a negative value to the
0500 left. A value of zero stops the motion if one is in progress and has
0501 no effect otherwise.
0502
0503 ``V4L2_CID_TILT_SPEED (integer)``
0504 This control turns the camera vertically at the specified speed. The
0505 unit is undefined. A positive value moves the camera up, a negative
0506 value down. A value of zero stops the motion if one is in progress
0507 and has no effect otherwise.
0508
0509 ``V4L2_CID_CAMERA_ORIENTATION (menu)``
0510 This read-only control describes the camera orientation by reporting its
0511 mounting position on the device where the camera is installed. The control
0512 value is constant and not modifiable by software. This control is
0513 particularly meaningful for devices which have a well defined orientation,
0514 such as phones, laptops and portable devices since the control is expressed
0515 as a position relative to the device's intended usage orientation. For
0516 example, a camera installed on the user-facing side of a phone, a tablet or
0517 a laptop device is said to be have ``V4L2_CAMERA_ORIENTATION_FRONT``
0518 orientation, while a camera installed on the opposite side of the front one
0519 is said to be have ``V4L2_CAMERA_ORIENTATION_BACK`` orientation. Camera
0520 sensors not directly attached to the device, or attached in a way that
0521 allows them to move freely, such as webcams and digital cameras, are said to
0522 have the ``V4L2_CAMERA_ORIENTATION_EXTERNAL`` orientation.
0523
0524
0525 .. tabularcolumns:: |p{7.7cm}|p{9.8cm}|
0526
0527 .. flat-table::
0528 :header-rows: 0
0529 :stub-columns: 0
0530
0531 * - ``V4L2_CAMERA_ORIENTATION_FRONT``
0532 - The camera is oriented towards the user facing side of the device.
0533 * - ``V4L2_CAMERA_ORIENTATION_BACK``
0534 - The camera is oriented towards the back facing side of the device.
0535 * - ``V4L2_CAMERA_ORIENTATION_EXTERNAL``
0536 - The camera is not directly attached to the device and is freely movable.
0537
0538
0539
0540 ``V4L2_CID_CAMERA_SENSOR_ROTATION (integer)``
0541 This read-only control describes the rotation correction in degrees in the
0542 counter-clockwise direction to be applied to the captured images once
0543 captured to memory to compensate for the camera sensor mounting rotation.
0544
0545 For a precise definition of the sensor mounting rotation refer to the
0546 extensive description of the 'rotation' properties in the device tree
0547 bindings file 'video-interfaces.txt'.
0548
0549 A few examples are below reported, using a shark swimming from left to
0550 right in front of the user as the example scene to capture. ::
0551
0552 0 X-axis
0553 0 +------------------------------------->
0554 !
0555 !
0556 !
0557 ! |\____)\___
0558 ! ) _____ __`<
0559 ! |/ )/
0560 !
0561 !
0562 !
0563 V
0564 Y-axis
0565
0566 Example one - Webcam
0567
0568 Assuming you can bring your laptop with you while swimming with sharks,
0569 the camera module of the laptop is installed on the user facing part of a
0570 laptop screen casing, and is typically used for video calls. The captured
0571 images are meant to be displayed in landscape mode (width > height) on the
0572 laptop screen.
0573
0574 The camera is typically mounted upside-down to compensate the lens optical
0575 inversion effect. In this case the value of the
0576 V4L2_CID_CAMERA_SENSOR_ROTATION control is 0, no rotation is required to
0577 display images correctly to the user.
0578
0579 If the camera sensor is not mounted upside-down it is required to compensate
0580 the lens optical inversion effect and the value of the
0581 V4L2_CID_CAMERA_SENSOR_ROTATION control is 180 degrees, as images will
0582 result rotated when captured to memory. ::
0583
0584 +--------------------------------------+
0585 ! !
0586 ! !
0587 ! !
0588 ! __/(_____/| !
0589 ! >.___ ____ ( !
0590 ! \( \| !
0591 ! !
0592 ! !
0593 ! !
0594 +--------------------------------------+
0595
0596 A software rotation correction of 180 degrees has to be applied to correctly
0597 display the image on the user screen. ::
0598
0599 +--------------------------------------+
0600 ! !
0601 ! !
0602 ! !
0603 ! |\____)\___ !
0604 ! ) _____ __`< !
0605 ! |/ )/ !
0606 ! !
0607 ! !
0608 ! !
0609 +--------------------------------------+
0610
0611 Example two - Phone camera
0612
0613 It is more handy to go and swim with sharks with only your mobile phone
0614 with you and take pictures with the camera that is installed on the back
0615 side of the device, facing away from the user. The captured images are meant
0616 to be displayed in portrait mode (height > width) to match the device screen
0617 orientation and the device usage orientation used when taking the picture.
0618
0619 The camera sensor is typically mounted with its pixel array longer side
0620 aligned to the device longer side, upside-down mounted to compensate for
0621 the lens optical inversion effect.
0622
0623 The images once captured to memory will be rotated and the value of the
0624 V4L2_CID_CAMERA_SENSOR_ROTATION will report a 90 degree rotation. ::
0625
0626
0627 +-------------------------------------+
0628 | _ _ |
0629 | \ / |
0630 | | | |
0631 | | | |
0632 | | > |
0633 | < | |
0634 | | | |
0635 | . |
0636 | V |
0637 +-------------------------------------+
0638
0639 A correction of 90 degrees in counter-clockwise direction has to be
0640 applied to correctly display the image in portrait mode on the device
0641 screen. ::
0642
0643 +--------------------+
0644 | |
0645 | |
0646 | |
0647 | |
0648 | |
0649 | |
0650 | |\____)\___ |
0651 | ) _____ __`< |
0652 | |/ )/ |
0653 | |
0654 | |
0655 | |
0656 | |
0657 | |
0658 +--------------------+
0659
0660
0661 .. [#f1]
0662 This control may be changed to a menu control in the future, if more
0663 options are required.
