Debian Codegraph @

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

raw
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.