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