aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/media/uapi/v4l/ext-ctrls-camera.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/media/uapi/v4l/ext-ctrls-camera.rst')
-rw-r--r--Documentation/media/uapi/v4l/ext-ctrls-camera.rst515
1 files changed, 0 insertions, 515 deletions
diff --git a/Documentation/media/uapi/v4l/ext-ctrls-camera.rst b/Documentation/media/uapi/v4l/ext-ctrls-camera.rst
deleted file mode 100644
index 51c1d5c9eb00..000000000000
--- a/Documentation/media/uapi/v4l/ext-ctrls-camera.rst
+++ /dev/null
@@ -1,515 +0,0 @@
-.. Permission is granted to copy, distribute and/or modify this
-.. document under the terms of the GNU Free Documentation License,
-.. Version 1.1 or any later version published by the Free Software
-.. Foundation, with no Invariant Sections, no Front-Cover Texts
-.. and no Back-Cover Texts. A copy of the license is included at
-.. Documentation/media/uapi/fdl-appendix.rst.
-..
-.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-
-.. _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:
-
-``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:
-
-
-
-.. 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.8cm}|
-
-.. 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.
-
-
-
-``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).
-
-.. _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.7cm}|p{10.8cm}|
-
-.. 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.8cm}|p{10.7cm}|
-
-.. 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.
-
-
-
-``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.
-
-.. _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.2 cm}|p{10.3cm}|
-
-.. 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.
-
-
-
-.. _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.
-
-
-
-.. _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.5cm}|
-
-.. 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
-
-
-``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.
-
-.. [#f1]
- This control may be changed to a menu control in the future, if more
- options are required.