[libcamera-devel] [PATCH 9/9] fixup: Align AnalogueGainMode to ExposureTimeMode

[paul.elder at ideasonboard.com]

On Fri, Jul 01, 2022 at 05:47:01PM +0200, Jacopo Mondi wrote:
> Align the description of the two controls.
> 
> Signed-off-by: Jacopo Mondi <jacopo at jmondi.org>

Acked-by: Paul Elder <paul.elder at ideasonboard.com>

> ---
>  src/libcamera/control_ids.yaml | 59 +++++++++++-----------------------
>  1 file changed, 19 insertions(+), 40 deletions(-)
> 
> diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml
> index 1f22b9b35036..51713a5d148d 100644
> --- a/src/libcamera/control_ids.yaml
> +++ b/src/libcamera/control_ids.yaml
> @@ -289,7 +289,7 @@ controls:
>          When reported in metadata, this control indicates what analogue gain
>          was used for the current request, regardless of AnalogueGainMode.
>          AnalogueGainMode will indicate the source of the analogue gain value,
> -        whether it came from the AE algorithm or not.
> +        whether it came from the AEGC algorithm or not.
>  
>          \sa ExposureTime
>          \sa AnalogueGainMode
> @@ -298,69 +298,48 @@ controls:
>        type: int32_t
>        description: |
>          Controls the source of the analogue gain that is applied to the image
> -        sensor. When set to Auto, the AE algorithm computes the analogue gain
> +        sensor. When set to Auto, the AEGC algorithm computes the analogue gain
>          and configures the image sensor accordingly. When set to Manual,
> -        analogue gain specified in AnalogueGain is applied to the image sensor.
> -        If AnalogueGain is not set, then the value last computed by the AE
> -        algorithm when the mode was Auto will be used.
> +        the value of the AnalogueGain control is used.
>  
> -        If AnalogueGain is not set and the mode is AnalogueGainModeManual and
> -        AE was never Auto (either because the camera started in Manual mode,
> +        When transitioning from Auto to Manual mode and no AnalogueGain control
> +        is provided by the application, the last value computed by the AEGC
> +        algorithm when the mode was Auto will be used. If the AnalogueGainMode
> +        was never set to Auto (either because the camera started in Manual mode,
>          or Auto is not supported by the camera), the camera should use a
>          best-effort default value.
>  
> -        When AnalogueGainMode is set Auto, the value set in AnalogueGain is
> -        ignored and is not retained. This means that if AnalogueGainMode is set
> -        to Manual and AnalogueGain is not also set, the analogue gain that
> -        was last computed by the AE algorithm while the mode was Auto will be
> -        applied to the sensor.
> -
>          If AnalogueGainModeManual is supported, the AnalogueGain control must
>          also be supported.
>  
>          The set of AnalogueGainMode modes that are supported by the camera must
>          have an intersection with the supported set of ExposureTimeMode modes.
>  
> -        As it takes a few frames to apply the analogue gain, there is a period of
> -        time between submitting a request with AnalogueGainMode set to Manual
> -        and the analogue gain component of the AE actually being disabled,
> -        during which the AE algorithm can still update the analogue gain. If an
> -        application is switching from automatic and manual control and wishes
> -        to eliminate any flicker during the switch, the following procedure is
> -        recommended.
> -
> -        1. Start with AnalogueGainMode set to Auto
> -
> -        2. Set AnalogueGainMode to Manual
> -
> -        3. Wait for the first request to be output that has AnalogueGainMode
> -        set to Manual
> -
> -        4. Copy the value reported in AnalogueGain into a new request, and
> -        submit it
> -
> -        5. Proceed to run manual analogue gain
> +        The same procedure described for performing flickerless transitions in
> +        the ExposureTimeMode control documentation should be applied to
> +        analogue gain.
>  
> +        \sa ExposureTimeMode
>          \sa AnalogueGain
>        enum:
>          - name: AnalogueGainModeAuto
>            value: 0
>            description: |
>              The analogue gain will be calculated automatically and set by the
> -            AE algorithm. If AnalogueGain is set while this mode is active, it
> -            will be ignored, and it will also not be retained.
> +            AEGC algorithm.
> +
> +            If AnalogueGain is set while this mode is active, it will be
> +            ignored, and it will also not be retained.
>          - name: AnalogueGainModeManual
>            value: 1
>            description: |
> -            The analogue gain will not be updated by the AE algorithm. It will
> -            come from the last calculated value when the mode was Auto, or from
> -            the value specified in AnalogueGain.
> +            The analogue gain will not be updated by the AEGC algorithm.
>  
> -            When transitioning from Auto to Manual mode the last computed
> +            When transitioning from Auto to Manual mode, the last computed
>              gain value is used until a new value is specified through the
>              AnalogueGain control. If an AnalogueGain value is specified in the
> -            same request where the AnalogueGainMode is set to Manual, the
> -            provided AnalogueGain is applied.
> +            same request where the AnalogueGainMode is changed from Auto to
> +            Manual, the provided AnalogueGain is applied immediately.
>  
>    - Brightness:
>        type: float
> -- 
> 2.36.1
>