[libcamera-devel] [PATCH 7/9] fixup: Rework flickerless transition mode

[Jacopo Mondi]

Re-work the introduction text.

This might seems arbitrary but the new text provides a bit more context.

Signed-off-by: Jacopo Mondi <jacopo at jmondi.org>
---
 src/libcamera/control_ids.yaml | 32 ++++++++++++++++++++++++--------
 1 file changed, 24 insertions(+), 8 deletions(-)

diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml
index e6676a149795..225377cf9e76 100644
--- a/src/libcamera/control_ids.yaml
+++ b/src/libcamera/control_ids.yaml
@@ -218,19 +218,35 @@ controls:
         The set of ExposureTimeMode modes that are supported by the camera must
         have an intersection with the supported set of AnalogueGainMode modes.
 
-        As it takes a few frames to apply the exposure time, there is a period of
-        time between submitting a request with ExposureTimeMode set to Manual
-        and the exposure time component of the AE actually being disabled,
-        during which the AE algorithm can still update the exposure time. If an
-        application is switching from automatic and manual control and wishes
-        to eliminate any flicker during the switch, the following procedure is
-        recommended.
+        Flickerless exposure mode transitions
+
+        Applications that transition from ExposureTimeModeAuto to the direct
+        control of the exposure time should aim to do so by selecting an
+        ExposureTime value as close as possible to the last value computed by
+        the auto exposure algorithm in order to avoid any visible flickering.
+
+        To select the correct value to use as ExposureTime value, applications
+        should accommodate the natural delay in applying controls caused by the
+        capture pipeline frame depth.
+
+        When switching to manual exposure mode, applications should not
+        immediately specify an ExposureTime value in the same request where
+        ExposureTimeMode is set to Manual. They should instead wait for the
+        first Request where ExposureTimeMode is reported as
+        ExposureTimeModeManual in the Request metadata, and use the reported
+        ExposureTime to populate the control value in the next Request to be
+        queued to the Camera.
+
+        The implementation of the auto-exposure algorithm should equally try to
+        minimize flickering and when transitioning from manual exposure mode to
+        auto exposure use the last value provided by the application as starting
+        point.
 
         1. Start with ExposureTimeMode set to Auto
 
         2. Set ExposureTimeMode to Manual
 
-        3. Wait for the first request to be output that has ExposureTimeMode
+        3. Wait for the first completed request that has ExposureTimeMode
         set to Manual
 
         4. Copy the value reported in ExposureTime into a new request, and
-- 
2.36.1