1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3.. _camera-controls:
4
5************************
6Camera Control Reference
7************************
8
9The Camera class includes controls for mechanical (or equivalent
10digital) features of a device such as controllable lenses or sensors.
11
12
13.. _camera-control-id:
14
15Camera 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
28enum 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
81enum 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
200enum 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
271enum 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
351enum 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
372enum 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-camera-sensor-orientation:
510
511``V4L2_CID_CAMERA_ORIENTATION (menu)``
512    This read-only control describes the camera orientation by reporting its
513    mounting position on the device where the camera is installed. The control
514    value is constant and not modifiable by software. This control is
515    particularly meaningful for devices which have a well defined orientation,
516    such as phones, laptops and portable devices since the control is expressed
517    as a position relative to the device's intended usage orientation. For
518    example, a camera installed on the user-facing side of a phone, a tablet or
519    a laptop device is said to be have ``V4L2_CAMERA_ORIENTATION_FRONT``
520    orientation, while a camera installed on the opposite side of the front one
521    is said to be have ``V4L2_CAMERA_ORIENTATION_BACK`` orientation. Camera
522    sensors not directly attached to the device, or attached in a way that
523    allows them to move freely, such as webcams and digital cameras, are said to
524    have the ``V4L2_CAMERA_ORIENTATION_EXTERNAL`` orientation.
525
526
527.. tabularcolumns:: |p{7.7cm}|p{9.8cm}|
528
529.. flat-table::
530    :header-rows:  0
531    :stub-columns: 0
532
533    * - ``V4L2_CAMERA_ORIENTATION_FRONT``
534      - The camera is oriented towards the user facing side of the device.
535    * - ``V4L2_CAMERA_ORIENTATION_BACK``
536      - The camera is oriented towards the back facing side of the device.
537    * - ``V4L2_CAMERA_ORIENTATION_EXTERNAL``
538      - The camera is not directly attached to the device and is freely movable.
539
540
541.. _v4l2-camera-sensor-rotation:
542
543``V4L2_CID_CAMERA_SENSOR_ROTATION (integer)``
544    This read-only control describes the rotation correction in degrees in the
545    counter-clockwise direction to be applied to the captured images once
546    captured to memory to compensate for the camera sensor mounting rotation.
547
548    For a precise definition of the sensor mounting rotation refer to the
549    extensive description of the 'rotation' properties in the device tree
550    bindings file 'video-interfaces.txt'.
551
552    A few examples are below reported, using a shark swimming from left to
553    right in front of the user as the example scene to capture. ::
554
555                 0               X-axis
556               0 +------------------------------------->
557                 !
558                 !
559                 !
560                 !           |\____)\___
561                 !           ) _____  __`<
562                 !           |/     )/
563                 !
564                 !
565                 !
566                 V
567               Y-axis
568
569    Example one - Webcam
570
571    Assuming you can bring your laptop with you while swimming with sharks,
572    the camera module of the laptop is installed on the user facing part of a
573    laptop screen casing, and is typically used for video calls. The captured
574    images are meant to be displayed in landscape mode (width > height) on the
575    laptop screen.
576
577    The camera is typically mounted upside-down to compensate the lens optical
578    inversion effect. In this case the value of the
579    V4L2_CID_CAMERA_SENSOR_ROTATION control is 0, no rotation is required to
580    display images correctly to the user.
581
582    If the camera sensor is not mounted upside-down it is required to compensate
583    the lens optical inversion effect and the value of the
584    V4L2_CID_CAMERA_SENSOR_ROTATION control is 180 degrees, as images will
585    result rotated when captured to memory. ::
586
587                 +--------------------------------------+
588                 !                                      !
589                 !                                      !
590                 !                                      !
591                 !              __/(_____/|             !
592                 !            >.___  ____ (             !
593                 !                 \(    \|             !
594                 !                                      !
595                 !                                      !
596                 !                                      !
597                 +--------------------------------------+
598
599    A software rotation correction of 180 degrees has to be applied to correctly
600    display the image on the user screen. ::
601
602                 +--------------------------------------+
603                 !                                      !
604                 !                                      !
605                 !                                      !
606                 !             |\____)\___              !
607                 !             ) _____  __`<            !
608                 !             |/     )/                !
609                 !                                      !
610                 !                                      !
611                 !                                      !
612                 +--------------------------------------+
613
614    Example two - Phone camera
615
616    It is more handy to go and swim with sharks with only your mobile phone
617    with you and take pictures with the camera that is installed on the back
618    side of the device, facing away from the user. The captured images are meant
619    to be displayed in portrait mode (height > width) to match the device screen
620    orientation and the device usage orientation used when taking the picture.
621
622    The camera sensor is typically mounted with its pixel array longer side
623    aligned to the device longer side, upside-down mounted to compensate for
624    the lens optical inversion effect.
625
626    The images once captured to memory will be rotated and the value of the
627    V4L2_CID_CAMERA_SENSOR_ROTATION will report a 90 degree rotation. ::
628
629
630                 +-------------------------------------+
631                 |                 _ _                 |
632                 |                \   /                |
633                 |                 | |                 |
634                 |                 | |                 |
635                 |                 |  >                |
636                 |                <  |                 |
637                 |                 | |                 |
638                 |                   .                 |
639                 |                  V                  |
640                 +-------------------------------------+
641
642    A correction of 90 degrees in counter-clockwise direction has to be
643    applied to correctly display the image in portrait mode on the device
644    screen. ::
645
646                          +--------------------+
647                          |                    |
648                          |                    |
649                          |                    |
650                          |                    |
651                          |                    |
652                          |                    |
653                          |   |\____)\___      |
654                          |   ) _____  __`<    |
655                          |   |/     )/        |
656                          |                    |
657                          |                    |
658                          |                    |
659                          |                    |
660                          |                    |
661                          +--------------------+
662
663
664.. [#f1]
665   This control may be changed to a menu control in the future, if more
666   options are required.
667
668``V4L2_CID_HDR_SENSOR_MODE (menu)``
669    Change the sensor HDR mode. A HDR picture is obtained by merging two
670    captures of the same scene using two different exposure periods. HDR mode
671    describes the way these two captures are merged in the sensor.
672
673    As modes differ for each sensor, menu items are not standardized by this
674    control and are left to the programmer.
675