diff options
Diffstat (limited to 'Documentation/media/uapi/v4l/ext-ctrls-camera.rst')
-rw-r--r-- | Documentation/media/uapi/v4l/ext-ctrls-camera.rst | 515 |
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. |