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

[Jacopo Mondi]

Align the description of the two controls.

Signed-off-by: Jacopo Mondi <jacopo at jmondi.org>
---
 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