[libcamera-devel] [PATCH v2 1/2] libcamera: controls: Add controls for AEC/AGC flicker avoidance

[David Plowman]

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 two controls intended to be used by AEC/AGC
algorithms:

AeFlickerMode to determine whether flicker avoidance is active or not.

AeFlickerPeriod to specify a custom flicker period when the period is
other than 50 or 60Hz.

Signed-off-by: David Plowman <david.plowman at raspberrypi.com>
---
 src/libcamera/control_ids.yaml | 69 +++++++++++++++++++++++++---------
 1 file changed, 52 insertions(+), 17 deletions(-)

diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml
index adea5f90..8093ab75 100644
--- a/src/libcamera/control_ids.yaml
+++ b/src/libcamera/control_ids.yaml
@@ -14,6 +14,58 @@ controls:
 
         \sa ExposureTime AnalogueGain
 
+  - 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 the exposure time to integer multiples
+        of this cycle period, wherever possible.
+
+        Implementations may not support all of the flicker modes listed below.
+
+      enum:
+        - name: FlickerOff
+          value: 0
+          description: No flicker avoidance is performed.
+        - name: FlickerFreq50Hz
+          value: 1
+          description: 50Hz flicker avoidance.
+            Suppress flicker effects caused by lighting runing with a
+            100Hz period (such as produced by 50Hz mains electricity).
+        - name: FlickerFreq60Hz
+          value: 2
+          description: 60Hz flicker avoidance.
+            Suppress flicker effects caused by lighting running with a
+            120Hz period (such as produced by 60Hz mains electricity).
+        - name: FlickerCustom
+          value: 3
+          description: Custom flicker avoidance.
+            Suppress flicker effects caused by lighting running with a
+            period specified by AeFlickerPeriod.
+
+            \sa AeFlickerPeriod
+        - name: FlickerAuto
+          value: 4
+          description: Automatic flicker period detection and avoidance.
+            The system will automatically determine the most likely value
+            of the flicker period, and avoid flicker of this frequency.
+        
+  - AeFlickerPeriod:
+      type: int32_t
+      description: Custom flicker period in microseconds.
+        This value is taken as the current flicker period to avoid. It
+        is used when the AeFlickerMode is set to FlickerCustom.
+
+        For example, to avoid 50Hz mains flicker, you could set the period
+        to 10000, corresponding to 10ms (twice the mains frequency), and
+        AeFlickerMode to FlickerCustom.
+
+        \sa AeFlickerMode
+
   - AeLocked:
       type: bool
       description: |
@@ -843,23 +895,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
-- 
2.30.2