6232ec3c16
Add an int64_t array control (controls::FrameDurations) to specify the minimum and maximum (in that order) frame duration to be used by the camera sensor. Signed-off-by: Naushir Patuck <naush@raspberrypi.com> Reviewed-by: David Plowman <david.plowman@raspberrypi.com> Tested-by: David Plowman <david.plowman@raspberrypi.com> Reviewed-by: Jacopo Mondi <jacopo@jmondi.org> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
612 lines
22 KiB
YAML
612 lines
22 KiB
YAML
# SPDX-License-Identifier: LGPL-2.1-or-later
|
|
#
|
|
# Copyright (C) 2019, Google Inc.
|
|
#
|
|
%YAML 1.2
|
|
---
|
|
# Unless otherwise stated, all controls are bi-directional, i.e. they can be
|
|
# set through Request::controls() and returned out through Request::metadata().
|
|
controls:
|
|
- AeEnable:
|
|
type: bool
|
|
description: |
|
|
Enable or disable the AE.
|
|
|
|
\sa ExposureTime AnalogueGain
|
|
|
|
- AeLocked:
|
|
type: bool
|
|
description: |
|
|
Report the lock status of a running AE algorithm.
|
|
|
|
If the AE algorithm is locked the value shall be set to true, if it's
|
|
converging it shall be set to false. If the AE algorithm is not
|
|
running the control shall not be present in the metadata control list.
|
|
|
|
\sa AeEnable
|
|
|
|
# AeMeteringMode needs further attention:
|
|
# - Auto-generate max enum value.
|
|
# - Better handling of custom types.
|
|
- AeMeteringMode:
|
|
type: int32_t
|
|
description: |
|
|
Specify a metering mode for the AE algorithm to use. The metering
|
|
modes determine which parts of the image are used to determine the
|
|
scene brightness. Metering modes may be platform specific and not
|
|
all metering modes may be supported.
|
|
enum:
|
|
- name: MeteringCentreWeighted
|
|
value: 0
|
|
description: Centre-weighted metering mode.
|
|
- name: MeteringSpot
|
|
value: 1
|
|
description: Spot metering mode.
|
|
- name: MeteringMatrix
|
|
value: 2
|
|
description: Matrix metering mode.
|
|
- name: MeteringCustom
|
|
value: 3
|
|
description: Custom metering mode.
|
|
|
|
# AeConstraintMode needs further attention:
|
|
# - Auto-generate max enum value.
|
|
# - Better handling of custom types.
|
|
- AeConstraintMode:
|
|
type: int32_t
|
|
description: |
|
|
Specify a constraint mode for the AE algorithm to use. These determine
|
|
how the measured scene brightness is adjusted to reach the desired
|
|
target exposure. Constraint modes may be platform specific, and not
|
|
all constraint modes may be supported.
|
|
enum:
|
|
- name: ConstraintNormal
|
|
value: 0
|
|
description: Default constraint mode.
|
|
This mode aims to balance the exposure of different parts of the
|
|
image so as to reach a reasonable average level. However, highlights
|
|
in the image may appear over-exposed and lowlights may appear
|
|
under-exposed.
|
|
- name: ConstraintHighlight
|
|
value: 1
|
|
description: Highlight constraint mode.
|
|
This mode adjusts the exposure levels in order to try and avoid
|
|
over-exposing the brightest parts (highlights) of an image.
|
|
Other non-highlight parts of the image may appear under-exposed.
|
|
- name: ConstraintShadows
|
|
value: 2
|
|
description: Shadows constraint mode.
|
|
This mode adjusts the exposure levels in order to try and avoid
|
|
under-exposing the dark parts (shadows) of an image. Other normally
|
|
exposed parts of the image may appear over-exposed.
|
|
- name: ConstraintCustom
|
|
value: 3
|
|
description: Custom constraint mode.
|
|
|
|
# AeExposureMode needs further attention:
|
|
# - Auto-generate max enum value.
|
|
# - Better handling of custom types.
|
|
- AeExposureMode:
|
|
type: int32_t
|
|
description: |
|
|
Specify an exposure mode for the AE algorithm to use. These specify
|
|
how the desired total exposure is divided between the shutter time
|
|
and the sensor's analogue gain. The exposure modes are platform
|
|
specific, and not all exposure modes may be supported.
|
|
enum:
|
|
- name: ExposureNormal
|
|
value: 0
|
|
description: Default exposure mode.
|
|
- name: ExposureShort
|
|
value: 1
|
|
description: Exposure mode allowing only short exposure times.
|
|
- name: ExposureLong
|
|
value: 2
|
|
description: Exposure mode allowing long exposure times.
|
|
- name: ExposureCustom
|
|
value: 3
|
|
description: Custom exposure mode.
|
|
|
|
- ExposureValue:
|
|
type: float
|
|
description: |
|
|
Specify an Exposure Value (EV) parameter. The EV parameter will only be
|
|
applied if the AE algorithm is currently enabled.
|
|
|
|
By convention EV adjusts the exposure as log2. For example
|
|
EV = [-2, -1, 0.5, 0, 0.5, 1, 2] results in an exposure adjustment
|
|
of [1/4x, 1/2x, 1/sqrt(2)x, 1x, sqrt(2)x, 2x, 4x].
|
|
|
|
\sa AeEnable
|
|
|
|
- ExposureTime:
|
|
type: int32_t
|
|
description: |
|
|
Exposure time (shutter speed) for the frame applied in the sensor
|
|
device. This value is specified in micro-seconds.
|
|
|
|
Setting this value means that it is now fixed and the AE algorithm may
|
|
not change it. Setting it back to zero returns it to the control of the
|
|
AE algorithm.
|
|
|
|
\sa AnalogueGain AeEnable
|
|
|
|
\todo Document the interactions between AeEnable and setting a fixed
|
|
value for this control. Consider interactions with other AE features,
|
|
such as aperture and aperture/shutter priority mode, and decide if
|
|
control of which features should be automatically adjusted shouldn't
|
|
better be handled through a separate AE mode control.
|
|
|
|
- AnalogueGain:
|
|
type: float
|
|
description: |
|
|
Analogue gain value applied in the sensor device.
|
|
The value of the control specifies the gain multiplier applied to all
|
|
colour channels. This value cannot be lower than 1.0.
|
|
|
|
Setting this value means that it is now fixed and the AE algorithm may
|
|
not change it. Setting it back to zero returns it to the control of the
|
|
AE algorithm.
|
|
|
|
\sa ExposureTime AeEnable
|
|
|
|
\todo Document the interactions between AeEnable and setting a fixed
|
|
value for this control. Consider interactions with other AE features,
|
|
such as aperture and aperture/shutter priority mode, and decide if
|
|
control of which features should be automatically adjusted shouldn't
|
|
better be handled through a separate AE mode control.
|
|
|
|
- Brightness:
|
|
type: float
|
|
description: |
|
|
Specify a fixed brightness parameter. Positive values (up to 1.0)
|
|
produce brighter images; negative values (up to -1.0) produce darker
|
|
images and 0.0 leaves pixels unchanged.
|
|
|
|
- Contrast:
|
|
type: float
|
|
description: |
|
|
Specify a fixed contrast parameter. Normal contrast is given by the
|
|
value 1.0; larger values produce images with more contrast.
|
|
|
|
- Lux:
|
|
type: float
|
|
description: |
|
|
Report an estimate of the current illuminance level in lux. The Lux
|
|
control can only be returned in metadata.
|
|
|
|
- AwbEnable:
|
|
type: bool
|
|
description: |
|
|
Enable or disable the AWB.
|
|
|
|
\sa ColourGains
|
|
|
|
# AwbMode needs further attention:
|
|
# - Auto-generate max enum value.
|
|
# - Better handling of custom types.
|
|
- AwbMode:
|
|
type: int32_t
|
|
description: |
|
|
Specify the range of illuminants to use for the AWB algorithm. The modes
|
|
supported are platform specific, and not all modes may be supported.
|
|
enum:
|
|
- name: AwbAuto
|
|
value: 0
|
|
description: Search over the whole colour temperature range.
|
|
- name: AwbIncandescent
|
|
value: 1
|
|
description: Incandescent AWB lamp mode.
|
|
- name: AwbTungsten
|
|
value: 2
|
|
description: Tungsten AWB lamp mode.
|
|
- name: AwbFluorescent
|
|
value: 3
|
|
description: Fluorescent AWB lamp mode.
|
|
- name: AwbIndoor
|
|
value: 4
|
|
description: Indoor AWB lighting mode.
|
|
- name: AwbDaylight
|
|
value: 5
|
|
description: Daylight AWB lighting mode.
|
|
- name: AwbCloudy
|
|
value: 6
|
|
description: Cloudy AWB lighting mode.
|
|
- name: AwbCustom
|
|
value: 7
|
|
description: Custom AWB mode.
|
|
|
|
- AwbLocked:
|
|
type: bool
|
|
description: |
|
|
Report the lock status of a running AWB algorithm.
|
|
|
|
If the AWB algorithm is locked the value shall be set to true, if it's
|
|
converging it shall be set to false. If the AWB algorithm is not
|
|
running the control shall not be present in the metadata control list.
|
|
|
|
\sa AwbEnable
|
|
|
|
- ColourGains:
|
|
type: float
|
|
description: |
|
|
Pair of gain values for the Red and Blue colour channels, in that
|
|
order. ColourGains can only be applied in a Request when the AWB is
|
|
disabled.
|
|
|
|
\sa AwbEnable
|
|
size: [2]
|
|
|
|
- ColourTemperature:
|
|
type: int32_t
|
|
description: Report the current estimate of the colour temperature, in
|
|
kelvin, for this frame. The ColourTemperature control can only be
|
|
returned in metadata.
|
|
|
|
- Saturation:
|
|
type: float
|
|
description: |
|
|
Specify a fixed saturation parameter. Normal saturation is given by
|
|
the value 1.0; larger values produce more saturated colours; 0.0
|
|
produces a greyscale image.
|
|
|
|
- SensorBlackLevels:
|
|
type: int32_t
|
|
description: |
|
|
Reports the sensor black levels used for processing a frame, in the
|
|
order R, Gr, Gb, B. These values are returned as numbers out of a 16-bit
|
|
pixel range (as if pixels ranged from 0 to 65535). The SensorBlackLevels
|
|
control can only be returned in metadata.
|
|
size: [4]
|
|
|
|
- Sharpness:
|
|
type: float
|
|
description: |
|
|
A value of 0.0 means no sharpening. The minimum value means
|
|
minimal sharpening, and shall be 0.0 unless the camera can't
|
|
disable sharpening completely. The default value shall give a
|
|
"reasonable" level of sharpening, suitable for most use cases.
|
|
The maximum value may apply extremely high levels of sharpening,
|
|
higher than anyone could reasonably want. Negative values are
|
|
not allowed. Note also that sharpening is not applied to raw
|
|
streams.
|
|
|
|
- FocusFoM:
|
|
type: int32_t
|
|
description: |
|
|
Reports a Figure of Merit (FoM) to indicate how in-focus the frame is.
|
|
A larger FocusFoM value indicates a more in-focus frame. This control
|
|
depends on the IPA to gather ISP statistics from the defined focus
|
|
region, and combine them in a suitable way to generate a FocusFoM value.
|
|
In this respect, it is not necessarily aimed at providing a way to
|
|
implement a focus algorithm by the application, rather an indication of
|
|
how in-focus a frame is.
|
|
|
|
- ColourCorrectionMatrix:
|
|
type: float
|
|
description: |
|
|
The 3x3 matrix that converts camera RGB to sRGB within the
|
|
imaging pipeline. This should describe the matrix that is used
|
|
after pixels have been white-balanced, but before any gamma
|
|
transformation. The 3x3 matrix is stored in conventional reading
|
|
order in an array of 9 floating point values.
|
|
|
|
size: [3x3]
|
|
|
|
- ScalerCrop:
|
|
type: Rectangle
|
|
description: |
|
|
Sets the image portion that will be scaled to form the whole of
|
|
the final output image. The (x,y) location of this rectangle is
|
|
relative to the PixelArrayActiveAreas that is being used. The units
|
|
remain native sensor pixels, even if the sensor is being used in
|
|
a binning or skipping mode.
|
|
|
|
This control is only present when the pipeline supports scaling. Its
|
|
maximum valid value is given by the properties::ScalerCropMaximum
|
|
property, and the two can be used to implement digital zoom.
|
|
|
|
- DigitalGain:
|
|
type: float
|
|
description: |
|
|
Digital gain value applied during the processing steps applied
|
|
to the image as captured from the sensor.
|
|
|
|
The global digital gain factor is applied to all the colour channels
|
|
of the RAW image. Different pipeline models are free to
|
|
specify how the global gain factor applies to each separate
|
|
channel.
|
|
|
|
If an imaging pipeline applies digital gain in distinct
|
|
processing steps, this value indicates their total sum.
|
|
Pipelines are free to decide how to adjust each processing
|
|
step to respect the received gain factor and shall report
|
|
their total value in the request metadata.
|
|
|
|
- FrameDurations:
|
|
type: int64_t
|
|
description: |
|
|
The minimum and maximum (in that order) frame duration,
|
|
expressed in microseconds.
|
|
|
|
When provided by applications, the control specifies the sensor frame
|
|
duration interval the pipeline has to use. This limits the largest
|
|
exposure time the sensor can use. For example, if a maximum frame
|
|
duration of 33ms is requested (corresponding to 30 frames per second),
|
|
the sensor will not be able to raise the exposure time above 33ms.
|
|
A fixed frame duration is achieved by setting the minimum and maximum
|
|
values to be the same. Setting both values to 0 reverts to using the
|
|
IPA provided defaults.
|
|
|
|
The maximum frame duration provides the absolute limit to the shutter
|
|
speed computed by the AE algorithm and it overrides any exposure mode
|
|
setting specified with controls::AeExposureMode. Similarly, when a
|
|
manual exposure time is set through controls::ExposureTime, it also
|
|
gets clipped to the limits set by this control. When reported in
|
|
metadata, the control expresses the minimum and maximum frame
|
|
durations used after being clipped to the sensor provided frame
|
|
duration limits.
|
|
|
|
\sa AeExposureMode
|
|
\sa ExposureTime
|
|
|
|
\todo Define how to calculate the capture frame rate by
|
|
defining controls to report additional delays introduced by
|
|
the capture pipeline or post-processing stages (ie JPEG
|
|
conversion, frame scaling).
|
|
|
|
\todo Provide an explicit definition of default control values, for
|
|
this and all other controls.
|
|
|
|
size: [2]
|
|
|
|
# ----------------------------------------------------------------------------
|
|
# Draft controls section
|
|
|
|
- AePrecaptureTrigger:
|
|
type: int32_t
|
|
draft: true
|
|
description: |
|
|
Control for AE metering trigger. Currently identical to
|
|
ANDROID_CONTROL_AE_PRECAPTURE_TRIGGER.
|
|
|
|
Whether the camera device will trigger a precapture metering sequence
|
|
when it processes this request.
|
|
enum:
|
|
- name: AePrecaptureTriggerIdle
|
|
value: 0
|
|
description: The trigger is idle.
|
|
- name: AePrecaptureTriggerStart
|
|
value: 1
|
|
description: The pre-capture AE metering is started by the camera.
|
|
- name: AePrecaptureTriggerCancel
|
|
value: 2
|
|
description: |
|
|
The camera will cancel any active or completed metering sequence.
|
|
The AE algorithm is reset to its initial state.
|
|
|
|
- AfTrigger:
|
|
type: int32_t
|
|
draft: true
|
|
description: |
|
|
Control for AF trigger. Currently identical to
|
|
ANDROID_CONTROL_AF_TRIGGER.
|
|
|
|
Whether the camera device will trigger autofocus for this request.
|
|
enum:
|
|
- name: AfTriggerIdle
|
|
value: 0
|
|
description: The trigger is idle.
|
|
- name: AfTriggerStart
|
|
value: 1
|
|
description: The AF routine is started by the camera.
|
|
- name: AfTriggerCancel
|
|
value: 2
|
|
description: |
|
|
The camera will cancel any active trigger and the AF routine is
|
|
reset to its initial state.
|
|
|
|
- NoiseReductionMode:
|
|
type: int32_t
|
|
draft: true
|
|
description: |
|
|
Control to select the noise reduction algorithm mode. Currently
|
|
identical to ANDROID_NOISE_REDUCTION_MODE.
|
|
|
|
Mode of operation for the noise reduction algorithm.
|
|
enum:
|
|
- name: NoiseReductionModeOff
|
|
value: 0
|
|
description: No noise reduction is applied
|
|
- name: NoiseReductionModeFast
|
|
value: 1
|
|
description: |
|
|
Noise reduction is applied without reducing the frame rate.
|
|
- name: NoiseReductionModeHighQuality
|
|
value: 2
|
|
description: |
|
|
High quality noise reduction at the expense of frame rate.
|
|
- name: NoiseReductionModeMinimal
|
|
value: 3
|
|
description: |
|
|
Minimal noise reduction is applied without reducing the frame rate.
|
|
- name: NoiseReductionModeZSL
|
|
value: 4
|
|
description: |
|
|
Noise reduction is applied at different levels to different streams.
|
|
|
|
- ColorCorrectionAberrationMode:
|
|
type: int32_t
|
|
draft: true
|
|
description: |
|
|
Control to select the color correction aberration mode. Currently
|
|
identical to ANDROID_COLOR_CORRECTION_ABERRATION_MODE.
|
|
|
|
Mode of operation for the chromatic aberration correction algorithm.
|
|
enum:
|
|
- name: ColorCorrectionAberrationOff
|
|
value: 0
|
|
description: No aberration correction is applied.
|
|
- name: ColorCorrectionAberrationFast
|
|
value: 1
|
|
description: Aberration correction will not slow down the frame rate.
|
|
- name: ColorCorrectionAberrationHighQuality
|
|
value: 2
|
|
description: |
|
|
High quality aberration correction which might reduce the frame
|
|
rate.
|
|
|
|
- AeState:
|
|
type: int32_t
|
|
draft: true
|
|
description: |
|
|
Control to report the current AE algorithm state. Currently identical to
|
|
ANDROID_CONTROL_AE_STATE.
|
|
|
|
Current state of the AE algorithm.
|
|
enum:
|
|
- name: AeStateInactive
|
|
value: 0
|
|
description: The AE algorithm is inactive.
|
|
- name: AeStateSearching
|
|
value: 1
|
|
description: The AE algorithm has not converged yet.
|
|
- name: AeStateConverged
|
|
value: 2
|
|
description: The AE algorithm has converged.
|
|
- name: AeStateLocked
|
|
value: 3
|
|
description: The AE algorithm is locked.
|
|
- name: AeStateFlashRequired
|
|
value: 4
|
|
description: The AE algorithm would need a flash for good results
|
|
- name: AeStatePrecapture
|
|
value: 5
|
|
description: |
|
|
The AE algorithm has started a pre-capture metering session.
|
|
\sa AePrecaptureTrigger
|
|
|
|
- AfState:
|
|
type: int32_t
|
|
draft: true
|
|
description: |
|
|
Control to report the current AF algorithm state. Currently identical to
|
|
ANDROID_CONTROL_AF_STATE.
|
|
|
|
Current state of the AF algorithm.
|
|
enum:
|
|
- name: AfStateInactive
|
|
value: 0
|
|
description: The AF algorithm is inactive.
|
|
- name: AfStatePassiveScan
|
|
value: 1
|
|
description: |
|
|
AF is performing a passive scan of the scene in continuous
|
|
auto-focus mode.
|
|
- name: AfStatePassiveFocused
|
|
value: 2
|
|
description: |
|
|
AF believes the scene is in focus, but might restart scanning.
|
|
- name: AfStateActiveScan
|
|
value: 3
|
|
description: |
|
|
AF is performing a scan triggered by an AF trigger request.
|
|
\sa AfTrigger
|
|
- name: AfStateFocusedLock
|
|
value: 4
|
|
description: |
|
|
AF believes has focused correctly and has locked focus.
|
|
- name: AfStateNotFocusedLock
|
|
value: 5
|
|
description: |
|
|
AF has not been able to focus and has locked.
|
|
- name: AfStatePassiveUnfocused
|
|
value: 6
|
|
description: |
|
|
AF has completed a passive scan without finding focus.
|
|
|
|
- AwbState:
|
|
type: int32_t
|
|
draft: true
|
|
description: |
|
|
Control to report the current AWB algorithm state. Currently identical
|
|
to ANDROID_CONTROL_AWB_STATE.
|
|
|
|
Current state of the AWB algorithm.
|
|
enum:
|
|
- name: AwbStateInactive
|
|
value: 0
|
|
description: The AWB algorithm is inactive.
|
|
- name: AwbStateSearching
|
|
value: 1
|
|
description: The AWB algorithm has not converged yet.
|
|
- name: AwbConverged
|
|
value: 2
|
|
description: The AWB algorithm has converged.
|
|
- name: AwbLocked
|
|
value: 3
|
|
description: The AWB algorithm is locked.
|
|
|
|
- SensorTimestamp:
|
|
type: int64_t
|
|
draft: true
|
|
description: |
|
|
Control to report the start of exposure of the first row of the captured
|
|
image. Currently identical to ANDROID_SENSOR_TIMESTAMP.
|
|
|
|
- SensorRollingShutterSkew:
|
|
type: int64_t
|
|
draft: true
|
|
description: |
|
|
Control to report the time between the start of exposure of the first
|
|
row and the start of exposure of the last row. Currently identical to
|
|
ANDROID_SENSOR_ROLLING_SHUTTER_SKEW
|
|
|
|
- LensShadingMapMode:
|
|
type: int32_t
|
|
draft: true
|
|
description: |
|
|
Control to report if the lens shading map is available. Currently
|
|
identical to ANDROID_STATISTICS_LENS_SHADING_MAP_MODE.
|
|
enum:
|
|
- name: LensShadingMapModeOff
|
|
value: 0
|
|
description: No lens shading map mode is available.
|
|
- name: LensShadingMapModeOn
|
|
value: 1
|
|
description: The lens shading map mode is available.
|
|
|
|
- SceneFlicker:
|
|
type: int32_t
|
|
draft: true
|
|
description: |
|
|
Control to report the detected scene light frequency. Currently
|
|
identical to ANDROID_STATISTICS_SCENE_FLICKER.
|
|
enum:
|
|
- name: SceneFickerOff
|
|
value: 0
|
|
description: No flickering detected.
|
|
- name: SceneFicker50Hz
|
|
value: 1
|
|
description: 50Hz flickering detected.
|
|
- name: SceneFicker60Hz
|
|
value: 2
|
|
description: 60Hz flickering detected.
|
|
|
|
- PipelineDepth:
|
|
type: int32_t
|
|
draft: true
|
|
description: |
|
|
Specifies the number of pipeline stages the frame went through from when
|
|
it was exposed to when the final completed result was available to the
|
|
framework. Always less than or equal to PipelineMaxDepth. Currently
|
|
identical to ANDROID_REQUEST_PIPELINE_DEPTH.
|
|
|
|
The typical value for this control is 3 as a frame is first exposed,
|
|
captured and then processed in a single pass through the ISP. Any
|
|
additional processing step performed after the ISP pass (in example face
|
|
detection, additional format conversions etc) count as an additional
|
|
pipeline stage.
|
|
|
|
...
|