Camera control reference

Camera class와 control descriptor

Camera class는 제어 가능한 lens나 sensor처럼 장치의 mechanical feature 또는 그에 해당하는 digital feature를 위한 control을 포함합니다.

`V4L2_CID_CAMERA_CLASS`는 Camera class descriptor입니다. 이 control에 `VIDIOC_QUERYCTRL`을 호출하면 camera control class 설명을 반환합니다.

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _camera-controls:

************************
Camera Control Reference
************************

The Camera class includes controls for mechanical (or equivalent
digital) features of a device such as controllable lenses or sensors.


.. _camera-control-id:

Camera Control IDs
==================

``V4L2_CID_CAMERA_CLASS (class)``
    The Camera class descriptor. Calling
    :ref:`VIDIOC_QUERYCTRL` for this control will
    return a description of this control class.

.. _v4l2-exposure-auto-type:

Exposure mode, time, bias와 metering

`V4L2_CID_EXPOSURE_AUTO`는 exposure time과 iris aperture의 자동 조정을 켭니다. 자동 기능이 활성화된 동안 수동 exposure 또는 iris 변경의 효과는 정의되지 않으며 driver는 그런 요청을 무시해야 합니다.

`V4L2_CID_EXPOSURE_ABSOLUTE`는 camera sensor exposure time을 정하며 frame interval의 제한을 받습니다. 단위는 100 µs로, 값 1은 1/10000초, 10000은 1초, 100000은 10초입니다.

Exposure mode가 AUTO 또는 APERTURE_PRIORITY일 때 `V4L2_CID_EXPOSURE_AUTO_PRIORITY`는 장치가 frame rate를 동적으로 바꿀 수 있는지 정합니다. Default 0에서는 이 기능이 꺼져 frame rate를 일정하게 유지해야 합니다.

`V4L2_CID_AUTO_EXPOSURE_BIAS`는 AUTO, SHUTTER_PRIORITY, APERTURE_PRIORITY mode에서만 유효한 exposure compensation입니다. 0.001 EV 단위이며 값 1000은 +1 EV입니다.

Exposure compensation 값을 높이면 exposure value(EV)를 낮추는 것과 같아 sensor에 도달하는 빛이 늘어납니다. Camera는 absolute exposure time과 aperture 중 하나 또는 둘을 조정해 보상합니다.

`V4L2_CID_EXPOSURE_METERING`은 frame exposure에 사용할 available light 측정 방식을 선택합니다.

``V4L2_CID_EXPOSURE_AUTO``
    (enum)

enum v4l2_exposure_auto_type -
    Enables automatic adjustments of the exposure time and/or iris
    aperture. The effect of manual changes of the exposure time or iris
    aperture while these features are enabled is undefined, drivers
    should ignore such requests. Possible values are:


.. tabularcolumns:: |p{7.1cm}|p{10.4cm}|

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    * - ``V4L2_EXPOSURE_AUTO``
      - Automatic exposure time, automatic iris aperture.
    * - ``V4L2_EXPOSURE_MANUAL``
      - Manual exposure time, manual iris.
    * - ``V4L2_EXPOSURE_SHUTTER_PRIORITY``
      - Manual exposure time, auto iris.
    * - ``V4L2_EXPOSURE_APERTURE_PRIORITY``
      - Auto exposure time, manual iris.



``V4L2_CID_EXPOSURE_ABSOLUTE (integer)``
    Determines the exposure time of the camera sensor. The exposure time
    is limited by the frame interval. Drivers should interpret the
    values as 100 µs units, where the value 1 stands for 1/10000th of a
    second, 10000 for 1 second and 100000 for 10 seconds.

``V4L2_CID_EXPOSURE_AUTO_PRIORITY (boolean)``
    When ``V4L2_CID_EXPOSURE_AUTO`` is set to ``AUTO`` or
    ``APERTURE_PRIORITY``, this control determines if the device may
    dynamically vary the frame rate. By default this feature is disabled
    (0) and the frame rate must remain constant.

``V4L2_CID_AUTO_EXPOSURE_BIAS (integer menu)``
    Determines the automatic exposure compensation, it is effective only
    when ``V4L2_CID_EXPOSURE_AUTO`` control is set to ``AUTO``,
    ``SHUTTER_PRIORITY`` or ``APERTURE_PRIORITY``. It is expressed in
    terms of EV, drivers should interpret the values as 0.001 EV units,
    where the value 1000 stands for +1 EV.

    Increasing the exposure compensation value is equivalent to
    decreasing the exposure value (EV) and will increase the amount of
    light at the image sensor. The camera performs the exposure
    compensation by adjusting absolute exposure time and/or aperture.

.. _v4l2-exposure-metering:

``V4L2_CID_EXPOSURE_METERING``
    (enum)

enum v4l2_exposure_metering -
    Determines how the camera measures the amount of light available for
    the frame exposure. Possible values are:

.. tabularcolumns:: |p{8.7cm}|p{8.7cm}|

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    * - ``V4L2_EXPOSURE_METERING_AVERAGE``
      - Use the light information coming from the entire frame and average
	giving no weighting to any particular portion of the metered area.
    * - ``V4L2_EXPOSURE_METERING_CENTER_WEIGHTED``
      - Average the light information coming from the entire frame giving
	priority to the center of the metered area.
    * - ``V4L2_EXPOSURE_METERING_SPOT``
      - Measure only very small area at the center of the frame.
    * - ``V4L2_EXPOSURE_METERING_MATRIX``
      - A multi-zone metering. The light intensity is measured in several
	points of the frame and the results are combined. The algorithm of
	the zones selection and their significance in calculating the
	final value is device dependent.

Pan, tilt와 focus command

`V4L2_CID_PAN_RELATIVE`는 camera를 지정량만큼 수평 회전합니다. 양수는 위에서 볼 때 시계방향인 오른쪽, 음수는 왼쪽이며 0은 움직이지 않습니다. 단위는 정의되지 않은 write-only control입니다.

`V4L2_CID_TILT_RELATIVE`는 수직 회전량을 지정합니다. 양수는 위, 음수는 아래, 0은 정지이며 단위가 정의되지 않은 write-only control입니다.

`V4L2_CID_PAN_RESET`과 `V4L2_CID_TILT_RESET` button은 각각 수평·수직 위치를 default로 되돌립니다.

`V4L2_CID_PAN_ABSOLUTE`와 `V4L2_CID_TILT_ABSOLUTE`는 absolute 위치를 arc-second 단위로 지정합니다. Pan 양수는 오른쪽, tilt 양수는 위쪽이며 유효 범위는 -180×3600부터 +180×3600까지입니다.

`V4L2_CID_FOCUS_ABSOLUTE`는 focal point 위치를 지정합니다. 양수는 camera에 더 가깝게, 음수는 infinity 방향으로 이동하며 단위는 정의되지 않습니다. `V4L2_CID_FOCUS_RELATIVE`는 현재 위치에서 지정량만큼 같은 방향 규칙으로 움직이는 write-only control입니다.

`V4L2_CID_FOCUS_AUTO`는 continuous autofocus를 켭니다. 활성화 중 수동 focus 조정의 효과는 정의되지 않으며 driver는 무시해야 합니다.

`V4L2_CID_AUTO_FOCUS_START`는 single autofocus를 시작합니다. Continuous autofocus가 TRUE일 때의 효과는 정의되지 않아 driver가 무시해야 합니다. `V4L2_CID_AUTO_FOCUS_STOP`은 START로 시작한 autofocus를 중단하며 continuous autofocus가 FALSE일 때만 유효합니다.

``V4L2_CID_PAN_RELATIVE (integer)``
    This control turns the camera horizontally by the specified amount.
    The unit is undefined. A positive value moves the camera to the
    right (clockwise when viewed from above), a negative value to the
    left. A value of zero does not cause motion. This is a write-only
    control.

``V4L2_CID_TILT_RELATIVE (integer)``
    This control turns the camera vertically by the specified amount.
    The unit is undefined. A positive value moves the camera up, a
    negative value down. A value of zero does not cause motion. This is
    a write-only control.

``V4L2_CID_PAN_RESET (button)``
    When this control is set, the camera moves horizontally to the
    default position.

``V4L2_CID_TILT_RESET (button)``
    When this control is set, the camera moves vertically to the default
    position.

``V4L2_CID_PAN_ABSOLUTE (integer)``
    This control turns the camera horizontally to the specified
    position. Positive values move the camera to the right (clockwise
    when viewed from above), negative values to the left. Drivers should
    interpret the values as arc seconds, with valid values between -180
    * 3600 and +180 * 3600 inclusive.

``V4L2_CID_TILT_ABSOLUTE (integer)``
    This control turns the camera vertically to the specified position.
    Positive values move the camera up, negative values down. Drivers
    should interpret the values as arc seconds, with valid values
    between -180 * 3600 and +180 * 3600 inclusive.

``V4L2_CID_FOCUS_ABSOLUTE (integer)``
    This control sets the focal point of the camera to the specified
    position. The unit is undefined. Positive values set the focus
    closer to the camera, negative values towards infinity.

``V4L2_CID_FOCUS_RELATIVE (integer)``
    This control moves the focal point of the camera by the specified
    amount. The unit is undefined. Positive values move the focus closer
    to the camera, negative values towards infinity. This is a
    write-only control.

``V4L2_CID_FOCUS_AUTO (boolean)``
    Enables continuous automatic focus adjustments. The effect of manual
    focus adjustments while this feature is enabled is undefined,
    drivers should ignore such requests.

``V4L2_CID_AUTO_FOCUS_START (button)``
    Starts single auto focus process. The effect of setting this control
    when ``V4L2_CID_FOCUS_AUTO`` is set to ``TRUE`` (1) is undefined,
    drivers should ignore such requests.

``V4L2_CID_AUTO_FOCUS_STOP (button)``
    Aborts automatic focusing started with ``V4L2_CID_AUTO_FOCUS_START``
    control. It is effective only when the continuous autofocus is
    disabled, that is when ``V4L2_CID_FOCUS_AUTO`` control is set to
    ``FALSE`` (0).

Autofocus status와 거리 범위

`V4L2_CID_AUTO_FOCUS_STATUS`는 read-only autofocus 상태 bitmask입니다. `V4L2_CID_3A_LOCK`의 `V4L2_LOCK_FOCUS` bit를 설정하면 status 값 갱신이 멈출 수 있습니다.

`V4L2_CID_AUTO_FOCUS_RANGE`는 lens가 autofocus에 사용할 거리 범위를 정합니다.

.. _v4l2-auto-focus-status:

``V4L2_CID_AUTO_FOCUS_STATUS (bitmask)``
    The automatic focus status. This is a read-only control.

    Setting ``V4L2_LOCK_FOCUS`` lock bit of the ``V4L2_CID_3A_LOCK``
    control may stop updates of the ``V4L2_CID_AUTO_FOCUS_STATUS``
    control value.

.. tabularcolumns:: |p{6.8cm}|p{10.7cm}|

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    * - ``V4L2_AUTO_FOCUS_STATUS_IDLE``
      - Automatic focus is not active.
    * - ``V4L2_AUTO_FOCUS_STATUS_BUSY``
      - Automatic focusing is in progress.
    * - ``V4L2_AUTO_FOCUS_STATUS_REACHED``
      - Focus has been reached.
    * - ``V4L2_AUTO_FOCUS_STATUS_FAILED``
      - Automatic focus has failed, the driver will not transition from
	this state until another action is performed by an application.



.. _v4l2-auto-focus-range:

``V4L2_CID_AUTO_FOCUS_RANGE``
    (enum)

enum v4l2_auto_focus_range -
    Determines auto focus distance range for which lens may be adjusted.

.. tabularcolumns:: |p{6.9cm}|p{10.6cm}|

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    * - ``V4L2_AUTO_FOCUS_RANGE_AUTO``
      - The camera automatically selects the focus range.
    * - ``V4L2_AUTO_FOCUS_RANGE_NORMAL``
      - Normal distance range, limited for best automatic focus
	performance.
    * - ``V4L2_AUTO_FOCUS_RANGE_MACRO``
      - Macro (close-up) auto focus. The camera will use its minimum
	possible distance for auto focus.
    * - ``V4L2_AUTO_FOCUS_RANGE_INFINITY``
      - The lens is set to focus on an object at infinite distance.

Zoom, iris, privacy와 band-stop filter

`V4L2_CID_ZOOM_ABSOLUTE`는 objective lens focal length를 양의 integer absolute 값으로 지정하며 단위는 driver-specific입니다. `V4L2_CID_ZOOM_RELATIVE`는 현재 값에 상대적인 write-only control로, 양수는 telephoto, 음수는 wide-angle 방향입니다.

`V4L2_CID_ZOOM_CONTINUOUS`는 physical limit에 도달하거나 명시적인 stop 요청이 올 때까지 지정 속도로 lens group을 움직입니다. 양수는 telephoto, 0은 정지, 음수는 wide-angle이며 속도 단위는 driver-specific입니다.

`V4L2_CID_IRIS_ABSOLUTE`는 aperture를 지정 값으로 설정합니다. 큰 값은 iris를 더 열고 작은 값은 닫습니다. `V4L2_CID_IRIS_RELATIVE`는 양수면 한 단계 열고 음수면 한 단계 닫는 write-only control입니다.

`V4L2_CID_PRIVACY`가 TRUE이면 camera가 image를 capture할 수 없게 합니다. Sensor mechanical obturation이나 firmware image processing이 일반적인 구현이지만 방법은 제한되지 않습니다. Privacy control 장치는 read access를 반드시 지원하고 write access는 선택적으로 지원할 수 있습니다.

`V4L2_CID_BAND_STOP_FILTER`는 camera sensor band-stop filter를 on/off하거나 강도를 지정합니다. 예를 들어 fluorescent light component를 제거하는 데 사용할 수 있습니다.

``V4L2_CID_ZOOM_ABSOLUTE (integer)``
    Specify the objective lens focal length as an absolute value. The
    zoom unit is driver-specific and its value should be a positive
    integer.

``V4L2_CID_ZOOM_RELATIVE (integer)``
    Specify the objective lens focal length relatively to the current
    value. Positive values move the zoom lens group towards the
    telephoto direction, negative values towards the wide-angle
    direction. The zoom unit is driver-specific. This is a write-only
    control.

``V4L2_CID_ZOOM_CONTINUOUS (integer)``
    Move the objective lens group at the specified speed until it
    reaches physical device limits or until an explicit request to stop
    the movement. A positive value moves the zoom lens group towards the
    telephoto direction. A value of zero stops the zoom lens group
    movement. A negative value moves the zoom lens group towards the
    wide-angle direction. The zoom speed unit is driver-specific.

``V4L2_CID_IRIS_ABSOLUTE (integer)``
    This control sets the camera's aperture to the specified value. The
    unit is undefined. Larger values open the iris wider, smaller values
    close it.

``V4L2_CID_IRIS_RELATIVE (integer)``
    This control modifies the camera's aperture by the specified amount.
    The unit is undefined. Positive values open the iris one step
    further, negative values close it one step further. This is a
    write-only control.

``V4L2_CID_PRIVACY (boolean)``
    Prevent video from being acquired by the camera. When this control
    is set to ``TRUE`` (1), no image can be captured by the camera.
    Common means to enforce privacy are mechanical obturation of the
    sensor and firmware image processing, but the device is not
    restricted to these methods. Devices that implement the privacy
    control must support read access and may support write access.

``V4L2_CID_BAND_STOP_FILTER (integer)``
    Switch the band-stop filter of a camera sensor on or off, or specify
    its strength. Such band-stop filters can be used, for example, to
    filter out the fluorescent light component.

Automatic·preset white balance

`V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE`는 white balance를 automatic, manual 또는 preset으로 설정합니다. Preset의 color temperature는 camera가 가장 정확한 color representation을 만들도록 주는 힌트이며 아래 값은 color temperature 증가 순서입니다.

.. _v4l2-auto-n-preset-white-balance:

``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE``
    (enum)

enum v4l2_auto_n_preset_white_balance -
    Sets white balance to automatic, manual or a preset. The presets
    determine color temperature of the light as a hint to the camera for
    white balance adjustments resulting in most accurate color
    representation. The following white balance presets are listed in
    order of increasing color temperature.

.. tabularcolumns:: |p{7.4cm}|p{10.1cm}|

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    * - ``V4L2_WHITE_BALANCE_MANUAL``
      - Manual white balance.
    * - ``V4L2_WHITE_BALANCE_AUTO``
      - Automatic white balance adjustments.
    * - ``V4L2_WHITE_BALANCE_INCANDESCENT``
      - White balance setting for incandescent (tungsten) lighting. It
	generally cools down the colors and corresponds approximately to
	2500...3500 K color temperature range.
    * - ``V4L2_WHITE_BALANCE_FLUORESCENT``
      - White balance preset for fluorescent lighting. It corresponds
	approximately to 4000...5000 K color temperature.
    * - ``V4L2_WHITE_BALANCE_FLUORESCENT_H``
      - With this setting the camera will compensate for fluorescent H
	lighting.
    * - ``V4L2_WHITE_BALANCE_HORIZON``
      - White balance setting for horizon daylight. It corresponds
	approximately to 5000 K color temperature.
    * - ``V4L2_WHITE_BALANCE_DAYLIGHT``
      - White balance preset for daylight (with clear sky). It corresponds
	approximately to 5000...6500 K color temperature.
    * - ``V4L2_WHITE_BALANCE_FLASH``
      - With this setting the camera will compensate for the flash light.
	It slightly warms up the colors and corresponds roughly to
	5000...5500 K color temperature.
    * - ``V4L2_WHITE_BALANCE_CLOUDY``
      - White balance preset for moderately overcast sky. This option
	corresponds approximately to 6500...8000 K color temperature
	range.
    * - ``V4L2_WHITE_BALANCE_SHADE``
      - White balance preset for shade or heavily overcast sky. It
	corresponds approximately to 9000...10000 K color temperature.

WDR, stabilization과 ISO sensitivity

`V4L2_CID_WIDE_DYNAMIC_RANGE`는 scene에 매우 어두운 영역과 매우 밝은 영역이 함께 있을 때 clear image를 얻는 WDR 기능을 on/off합니다. Camera에서는 exposure time이 다른 연속 frame 두 개를 결합하는 방식이 흔합니다.

`V4L2_CID_IMAGE_STABILIZATION`은 image stabilization을 on/off합니다.

`V4L2_CID_ISO_SENSITIVITY`는 ISO 12232 arithmetic scale에 따른 sensor의 light sensitivity를 지정합니다. Sensitivity가 두 배면 ISO 숫자도 두 배입니다. Control 값은 표준 ISO 값에 1000을 곱한 scale로 해석하며, 원문 예제의 값 800은 ISO 0.8을 뜻합니다. Driver는 보통 표준 ISO 일부만 지원합니다.

`V4L2_CID_ISO_SENSITIVITY_AUTO`가 MANUAL이 아닌데 ISO_SENSITIVITY를 설정한 효과는 정의되지 않으며 driver가 무시해야 합니다.

.. _v4l2-wide-dynamic-range:

``V4L2_CID_WIDE_DYNAMIC_RANGE (boolean)``
    Enables or disables the camera's wide dynamic range feature. This
    feature allows to obtain clear images in situations where intensity
    of the illumination varies significantly throughout the scene, i.e.
    there are simultaneously very dark and very bright areas. It is most
    commonly realized in cameras by combining two subsequent frames with
    different exposure times.  [#f1]_

.. _v4l2-image-stabilization:

``V4L2_CID_IMAGE_STABILIZATION (boolean)``
    Enables or disables image stabilization.

``V4L2_CID_ISO_SENSITIVITY (integer menu)``
    Determines ISO equivalent of an image sensor indicating the sensor's
    sensitivity to light. The numbers are expressed in arithmetic scale,
    as per :ref:`iso12232` standard, where doubling the sensor
    sensitivity is represented by doubling the numerical ISO value.
    Applications should interpret the values as standard ISO values
    multiplied by 1000, e.g. control value 800 stands for ISO 0.8.
    Drivers will usually support only a subset of standard ISO values.
    The effect of setting this control while the
    ``V4L2_CID_ISO_SENSITIVITY_AUTO`` control is set to a value other
    than ``V4L2_CID_ISO_SENSITIVITY_MANUAL`` is undefined, drivers
    should ignore such requests.

.. _v4l2-iso-sensitivity-auto-type:

``V4L2_CID_ISO_SENSITIVITY_AUTO``
    (enum)

enum v4l2_iso_sensitivity_type -
    Enables or disables automatic ISO sensitivity adjustments.



.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    * - ``V4L2_CID_ISO_SENSITIVITY_MANUAL``
      - Manual ISO sensitivity.
    * - ``V4L2_CID_ISO_SENSITIVITY_AUTO``
      - Automatic ISO sensitivity adjustments.

Scene program

`V4L2_CID_SCENE_MODE`는 일반적인 촬영 scene에 최적화된 camera automatic program을 선택합니다. Camera는 exposure, aperture, focus, light metering, white balance, equivalent sensitivity를 결정하며 관련 control은 scene mode의 영향을 받습니다. 각 mode의 정확한 동작은 camera specification에 따릅니다.

Scene mode를 사용하지 않으면 `V4L2_SCENE_MODE_NONE`으로 설정해야 다른 관련 control에 접근할 수 있습니다.

.. _v4l2-scene-mode:

``V4L2_CID_SCENE_MODE``
    (enum)

enum v4l2_scene_mode -
    This control allows to select scene programs as the camera automatic
    modes optimized for common shooting scenes. Within these modes the
    camera determines best exposure, aperture, focusing, light metering,
    white balance and equivalent sensitivity. The controls of those
    parameters are influenced by the scene mode control. An exact
    behavior in each mode is subject to the camera specification.

    When the scene mode feature is not used, this control should be set
    to ``V4L2_SCENE_MODE_NONE`` to make sure the other possibly related
    controls are accessible. The following scene programs are defined:

.. raw:: latex

    \small

.. tabularcolumns:: |p{5.9cm}|p{11.6cm}|

.. cssclass:: longtable

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    * - ``V4L2_SCENE_MODE_NONE``
      - The scene mode feature is disabled.
    * - ``V4L2_SCENE_MODE_BACKLIGHT``
      - Backlight. Compensates for dark shadows when light is coming from
	behind a subject, also by automatically turning on the flash.
    * - ``V4L2_SCENE_MODE_BEACH_SNOW``
      - Beach and snow. This mode compensates for all-white or bright
	scenes, which tend to look gray and low contrast, when camera's
	automatic exposure is based on an average scene brightness. To
	compensate, this mode automatically slightly overexposes the
	frames. The white balance may also be adjusted to compensate for
	the fact that reflected snow looks bluish rather than white.
    * - ``V4L2_SCENE_MODE_CANDLELIGHT``
      - Candle light. The camera generally raises the ISO sensitivity and
	lowers the shutter speed. This mode compensates for relatively
	close subject in the scene. The flash is disabled in order to
	preserve the ambiance of the light.
    * - ``V4L2_SCENE_MODE_DAWN_DUSK``
      - Dawn and dusk. Preserves the colors seen in low natural light
	before dusk and after down. The camera may turn off the flash, and
	automatically focus at infinity. It will usually boost saturation
	and lower the shutter speed.
    * - ``V4L2_SCENE_MODE_FALL_COLORS``
      - Fall colors. Increases saturation and adjusts white balance for
	color enhancement. Pictures of autumn leaves get saturated reds
	and yellows.
    * - ``V4L2_SCENE_MODE_FIREWORKS``
      - Fireworks. Long exposure times are used to capture the expanding
	burst of light from a firework. The camera may invoke image
	stabilization.
    * - ``V4L2_SCENE_MODE_LANDSCAPE``
      - Landscape. The camera may choose a small aperture to provide deep
	depth of field and long exposure duration to help capture detail
	in dim light conditions. The focus is fixed at infinity. Suitable
	for distant and wide scenery.
    * - ``V4L2_SCENE_MODE_NIGHT``
      - Night, also known as Night Landscape. Designed for low light
	conditions, it preserves detail in the dark areas without blowing
	out bright objects. The camera generally sets itself to a
	medium-to-high ISO sensitivity, with a relatively long exposure
	time, and turns flash off. As such, there will be increased image
	noise and the possibility of blurred image.
    * - ``V4L2_SCENE_MODE_PARTY_INDOOR``
      - Party and indoor. Designed to capture indoor scenes that are lit
	by indoor background lighting as well as the flash. The camera
	usually increases ISO sensitivity, and adjusts exposure for the
	low light conditions.
    * - ``V4L2_SCENE_MODE_PORTRAIT``
      - Portrait. The camera adjusts the aperture so that the depth of
	field is reduced, which helps to isolate the subject against a
	smooth background. Most cameras recognize the presence of faces in
	the scene and focus on them. The color hue is adjusted to enhance
	skin tones. The intensity of the flash is often reduced.
    * - ``V4L2_SCENE_MODE_SPORTS``
      - Sports. Significantly increases ISO and uses a fast shutter speed
	to freeze motion of rapidly-moving subjects. Increased image noise
	may be seen in this mode.
    * - ``V4L2_SCENE_MODE_SUNSET``
      - Sunset. Preserves deep hues seen in sunsets and sunrises. It bumps
	up the saturation.
    * - ``V4L2_SCENE_MODE_TEXT``
      - Text. It applies extra contrast and sharpness, it is typically a
	black-and-white mode optimized for readability. Automatic focus
	may be switched to close-up mode and this setting may also involve
	some lens-distortion correction.

.. raw:: latex

    \normalsize

3A lock과 pan/tilt speed

`V4L2_CID_3A_LOCK`은 automatic focus, exposure, white balance를 lock/unlock하는 bitmask입니다. 각 lock bit를 1로 설정하면 해당 automatic adjustment만 독립적으로 pause되고 bit를 지울 때까지 현재 설정을 유지합니다.

해당 algorithm이 활성화되지 않았으면 driver는 lock 요청을 오류 없이 무시해야 합니다. 예를 들어 `V4L2_CID_AUTO_WHITE_BALANCE`가 FALSE일 때 `V4L2_LOCK_WHITE_BALANCE`를 설정하는 경우입니다. Exposure, white balance 또는 focus control이 3A_LOCK 값을 바꿀 수도 있습니다.

`V4L2_CID_PAN_SPEED`는 수평 회전 속도를 지정합니다. 양수는 오른쪽, 음수는 왼쪽, 0은 진행 중 motion을 멈추며 motion이 없으면 효과가 없습니다. 단위는 정의되지 않습니다.

`V4L2_CID_TILT_SPEED`는 수직 회전 속도를 지정합니다. 양수는 위, 음수는 아래, 0은 진행 중 motion을 멈추며 motion이 없으면 효과가 없습니다.

``V4L2_CID_3A_LOCK (bitmask)``
    This control locks or unlocks the automatic focus, exposure and
    white balance. The automatic adjustments can be paused independently
    by setting the corresponding lock bit to 1. The camera then retains
    the settings until the lock bit is cleared. The following lock bits
    are defined:

    When a given algorithm is not enabled, drivers should ignore
    requests to lock it and should return no error. An example might be
    an application setting bit ``V4L2_LOCK_WHITE_BALANCE`` when the
    ``V4L2_CID_AUTO_WHITE_BALANCE`` control is set to ``FALSE``. The
    value of this control may be changed by exposure, white balance or
    focus controls.



.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    * - ``V4L2_LOCK_EXPOSURE``
      - Automatic exposure adjustments lock.
    * - ``V4L2_LOCK_WHITE_BALANCE``
      - Automatic white balance adjustments lock.
    * - ``V4L2_LOCK_FOCUS``
      - Automatic focus lock.



``V4L2_CID_PAN_SPEED (integer)``
    This control turns the camera horizontally at the specific speed.
    The unit is undefined. A positive value moves the camera to the
    right (clockwise when viewed from above), a negative value to the
    left. A value of zero stops the motion if one is in progress and has
    no effect otherwise.

``V4L2_CID_TILT_SPEED (integer)``
    This control turns the camera vertically at the specified speed. The
    unit is undefined. A positive value moves the camera up, a negative
    value down. A value of zero stops the motion if one is in progress
    and has no effect otherwise.

Device 기준 camera orientation

`V4L2_CID_CAMERA_ORIENTATION`은 camera가 설치된 device에서의 mounting position을 보고하는 read-only menu control입니다. 값은 constant이며 software가 바꿀 수 없습니다.

이 control은 phone, laptop, portable device처럼 intended usage orientation이 명확한 장치에서 특히 의미가 있습니다. 위치는 해당 device의 사용 방향을 기준으로 표현합니다.

.. _v4l2-camera-sensor-orientation:

``V4L2_CID_CAMERA_ORIENTATION (menu)``
    This read-only control describes the camera orientation by reporting its
    mounting position on the device where the camera is installed. The control
    value is constant and not modifiable by software. This control is
    particularly meaningful for devices which have a well defined orientation,
    such as phones, laptops and portable devices since the control is expressed
    as a position relative to the device's intended usage orientation. For
    example, a camera installed on the user-facing side of a phone, a tablet or
    a laptop device is said to be have ``V4L2_CAMERA_ORIENTATION_FRONT``
    orientation, while a camera installed on the opposite side of the front one
    is said to be have ``V4L2_CAMERA_ORIENTATION_BACK`` orientation. Camera
    sensors not directly attached to the device, or attached in a way that
    allows them to move freely, such as webcams and digital cameras, are said to
    have the ``V4L2_CAMERA_ORIENTATION_EXTERNAL`` orientation.


.. tabularcolumns:: |p{7.7cm}|p{9.8cm}|

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    * - ``V4L2_CAMERA_ORIENTATION_FRONT``
      - The camera is oriented towards the user facing side of the device.
    * - ``V4L2_CAMERA_ORIENTATION_BACK``
      - The camera is oriented towards the back facing side of the device.
    * - ``V4L2_CAMERA_ORIENTATION_EXTERNAL``
      - The camera is not directly attached to the device and is freely movable.

Sensor mounting rotation과 image 보정

`V4L2_CID_CAMERA_SENSOR_ROTATION`은 sensor mounting rotation을 보상하기 위해 memory에 capture된 image에 적용해야 하는 counter-clockwise rotation correction을 degree로 보고하는 read-only control입니다.

정확한 sensor mounting rotation 정의는 device-tree binding `video-interfaces.txt`의 `rotation` property 설명을 참조합니다. 원문은 사용자의 앞에서 왼쪽에서 오른쪽으로 헤엄치는 상어 scene을 예로 듭니다.

Webcam 예에서 laptop camera module은 user-facing screen casing에 설치되고 landscape mode(width > height)로 표시합니다. Lens optical inversion을 보상하려 sensor를 upside-down으로 장착하는 일반적인 경우에는 rotation 값이 0이며 추가 보정이 필요 없습니다.

Webcam sensor가 upside-down으로 장착되지 않았다면 memory에 capture된 image가 180도 돌아가므로 `V4L2_CID_CAMERA_SENSOR_ROTATION`은 180을 보고합니다. User screen에 올바르게 표시하려 software가 180도 보정해야 합니다.

Phone 예에서는 user 반대쪽 back camera를 portrait mode(height > width)로 표시합니다. Sensor pixel array의 긴 변을 device 긴 변에 맞추고 lens optical inversion 보상을 위해 upside-down으로 장착하는 것이 일반적입니다.

이 구성에서 memory에 capture된 image는 회전되어 있고 rotation control은 90도를 보고합니다. Device screen의 portrait mode에 올바르게 표시하려 counter-clockwise 90도 correction을 적용해야 합니다.

WDR control은 미래에 더 많은 option이 필요하면 boolean에서 menu control로 바뀔 수 있습니다.

.. _v4l2-camera-sensor-rotation:

``V4L2_CID_CAMERA_SENSOR_ROTATION (integer)``
    This read-only control describes the rotation correction in degrees in the
    counter-clockwise direction to be applied to the captured images once
    captured to memory to compensate for the camera sensor mounting rotation.

    For a precise definition of the sensor mounting rotation refer to the
    extensive description of the 'rotation' properties in the device tree
    bindings file 'video-interfaces.txt'.

    A few examples are below reported, using a shark swimming from left to
    right in front of the user as the example scene to capture. ::

                 0               X-axis
               0 +------------------------------------->
                 !
                 !
                 !
                 !           |\____)\___
                 !           ) _____  __`<
                 !           |/     )/
                 !
                 !
                 !
                 V
               Y-axis

    Example one - Webcam

    Assuming you can bring your laptop with you while swimming with sharks,
    the camera module of the laptop is installed on the user facing part of a
    laptop screen casing, and is typically used for video calls. The captured
    images are meant to be displayed in landscape mode (width > height) on the
    laptop screen.

    The camera is typically mounted upside-down to compensate the lens optical
    inversion effect. In this case the value of the
    V4L2_CID_CAMERA_SENSOR_ROTATION control is 0, no rotation is required to
    display images correctly to the user.

    If the camera sensor is not mounted upside-down it is required to compensate
    the lens optical inversion effect and the value of the
    V4L2_CID_CAMERA_SENSOR_ROTATION control is 180 degrees, as images will
    result rotated when captured to memory. ::

                 +--------------------------------------+
                 !                                      !
                 !                                      !
                 !                                      !
                 !              __/(_____/|             !
                 !            >.___  ____ (             !
                 !                 \(    \|             !
                 !                                      !
                 !                                      !
                 !                                      !
                 +--------------------------------------+

    A software rotation correction of 180 degrees has to be applied to correctly
    display the image on the user screen. ::

                 +--------------------------------------+
                 !                                      !
                 !                                      !
                 !                                      !
                 !             |\____)\___              !
                 !             ) _____  __`<            !
                 !             |/     )/                !
                 !                                      !
                 !                                      !
                 !                                      !
                 +--------------------------------------+

    Example two - Phone camera

    It is more handy to go and swim with sharks with only your mobile phone
    with you and take pictures with the camera that is installed on the back
    side of the device, facing away from the user. The captured images are meant
    to be displayed in portrait mode (height > width) to match the device screen
    orientation and the device usage orientation used when taking the picture.

    The camera sensor is typically mounted with its pixel array longer side
    aligned to the device longer side, upside-down mounted to compensate for
    the lens optical inversion effect.

    The images once captured to memory will be rotated and the value of the
    V4L2_CID_CAMERA_SENSOR_ROTATION will report a 90 degree rotation. ::


                 +-------------------------------------+
                 |                 _ _                 |
                 |                \   /                |
                 |                 | |                 |
                 |                 | |                 |
                 |                 |  >                |
                 |                <  |                 |
                 |                 | |                 |
                 |                   .                 |
                 |                  V                  |
                 +-------------------------------------+

    A correction of 90 degrees in counter-clockwise direction has to be
    applied to correctly display the image in portrait mode on the device
    screen. ::

                          +--------------------+
                          |                    |
                          |                    |
                          |                    |
                          |                    |
                          |                    |
                          |                    |
                          |   |\____)\___      |
                          |   ) _____  __`<    |
                          |   |/     )/        |
                          |                    |
                          |                    |
                          |                    |
                          |                    |
                          |                    |
                          +--------------------+


.. [#f1]
   This control may be changed to a menu control in the future, if more
   options are required.

Sensor HDR mode

`V4L2_CID_HDR_SENSOR_MODE`는 sensor HDR mode를 변경하는 menu control입니다. HDR image는 같은 scene을 서로 다른 exposure period로 두 번 capture한 뒤 병합하여 만듭니다. HDR mode는 sensor 내부에서 두 capture를 병합하는 방식을 나타냅니다.

지원 mode가 sensor마다 다르므로 이 control의 menu item은 표준화되지 않으며 programmer가 정의합니다.

``V4L2_CID_HDR_SENSOR_MODE (menu)``
    Change the sensor HDR mode. A HDR picture is obtained by merging two
    captures of the same scene using two different exposure periods. HDR mode
    describes the way these two captures are merged in the sensor.

    As modes differ for each sensor, menu items are not standardized by this
    control and are left to the programmer.