libcamera: controls: Add controls for AEC/AGC flicker avoidance

Flicker is the term used to describe brightness banding or oscillation
of images caused typically by artificial lighting driven by a 50 or
60Hz mains supply. We add three controls intended to be used by
AEC/AGC algorithms:

AeFlickerMode to enable flicker avoidance.

AeFlickerPeriod to set the flicker period "manually".

AeFlickerDetected to report any flicker that is currently detected.

Signed-off-by: David Plowman <david.plowman@raspberrypi.com>
Reviewed-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
Reviewed-by: Umang Jain <umang.jain@ideasonboard.com>
Signed-off-by: Naushir Patuck <naush@raspberrypi.com>

src/libcamera/control_ids.yaml

@@ -156,6 +156,79 @@ controls:
         control of which features should be automatically adjusted shouldn't
         better be handled through a separate AE mode control.
 
+  - AeFlickerMode:
+      type: int32_t
+      description: |
+        Set the flicker mode, which determines whether, and how, the AGC/AEC
+        algorithm attempts to hide flicker effects caused by the duty cycle of
+        artificial lighting.
+
+        Although implementation dependent, many algorithms for "flicker
+        avoidance" work by restricting this exposure time to integer multiples
+        of the cycle period, wherever possible.
+
+        Implementations may not support all of the flicker modes listed below.
+
+        By default the system will start in FlickerAuto mode if this is
+        supported, otherwise the flicker mode will be set to FlickerOff.
+
+      enum:
+        - name: FlickerOff
+          value: 0
+          description: No flicker avoidance is performed.
+        - name: FlickerManual
+          value: 1
+          description: Manual flicker avoidance.
+            Suppress flicker effects caused by lighting running with a period
+            specified by the AeFlickerPeriod control.
+            \sa AeFlickerPeriod
+        - name: FlickerAuto
+          value: 2
+          description: Automatic flicker period detection and avoidance.
+            The system will automatically determine the most likely value of
+            flicker period, and avoid flicker of this frequency. Once flicker
+            is being corrected, it is implementation dependent whether the
+            system is still able to detect a change in the flicker period.
+            \sa AeFlickerDetected
+
+  - AeFlickerPeriod:
+      type: int32_t
+      description: Manual flicker period in microseconds.
+        This value sets the current flicker period to avoid. It is used when
+        AeFlickerMode is set to FlickerManual.
+
+        To cancel 50Hz mains flicker, this should be set to 10000 (corresponding
+        to 100Hz), or 8333 (120Hz) for 60Hz mains.
+
+        Setting the mode to FlickerManual when no AeFlickerPeriod has ever been
+        set means that no flicker cancellation occurs (until the value of this
+        control is updated).
+
+        Switching to modes other than FlickerManual has no effect on the
+        value of the AeFlickerPeriod control.
+
+        \sa AeFlickerMode
+
+  - AeFlickerDetected:
+      type: int32_t
+      description: Flicker period detected in microseconds.
+        The value reported here indicates the currently detected flicker
+        period, or zero if no flicker at all is detected.
+
+        When AeFlickerMode is set to FlickerAuto, there may be a period during
+        which the value reported here remains zero. Once a non-zero value is
+        reported, then this is the flicker period that has been detected and is
+        now being cancelled.
+
+        In the case of 50Hz mains flicker, the value would be 10000
+        (corresponding to 100Hz), or 8333 (120Hz) for 60Hz mains flicker.
+
+        It is implementation dependent whether the system can continue to detect
+        flicker of different periods when another frequency is already being
+        cancelled.
+
+        \sa AeFlickerMode
+
   - Brightness:
       type: float
       description: |
@@ -850,23 +923,6 @@ controls:
           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