<div dir="ltr">Hi David, thanks for the patch!<div>Reviewed-by: Han-Lin Chen <<a href="mailto:hanlinchen@chromium.org">hanlinchen@chromium.org</a>><br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Mar 31, 2022 at 11:17 PM David Plowman <<a href="mailto:david.plowman@raspberrypi.com">david.plowman@raspberrypi.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">This patch describes a series of controls that allow applications to<br>
drive AF algorithms:<br>
<br>
AfMode - manual, auto or continuous<br>
AfLensPosition - set lens position to macro/hyperfocal/infinity<br>
AfRange - full, macro or normal<br>
AfSpeed - fast or slow<br>
AfWindows - AF window locations<br>
AfTrigger - start (trigger an AF scan) or cancel<br>
AfPause - pause continuous AF<br>
LensPosition - position of lens from lens driver<br>
AfState - reports the mode, whether scanning/success/failure<br>
---<br>
src/libcamera/control_ids.yaml | 373 +++++++++++++++++++++++++++------<br>
1 file changed, 313 insertions(+), 60 deletions(-)<br>
<br>
diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml<br>
index 9d4638ae..23607368 100644<br>
--- a/src/libcamera/control_ids.yaml<br>
+++ b/src/libcamera/control_ids.yaml<br>
@@ -406,27 +406,6 @@ controls:<br>
The camera will cancel any active or completed metering sequence.<br>
The AE algorithm is reset to its initial state.<br>
<br>
- - AfTrigger:<br>
- type: int32_t<br>
- draft: true<br>
- description: |<br>
- Control for AF trigger. Currently identical to<br>
- ANDROID_CONTROL_AF_TRIGGER.<br>
-<br>
- Whether the camera device will trigger autofocus for this request.<br>
- enum:<br>
- - name: AfTriggerIdle<br>
- value: 0<br>
- description: The trigger is idle.<br>
- - name: AfTriggerStart<br>
- value: 1<br>
- description: The AF routine is started by the camera.<br>
- - name: AfTriggerCancel<br>
- value: 2<br>
- description: |<br>
- The camera will cancel any active trigger and the AF routine is<br>
- reset to its initial state.<br>
-<br>
- NoiseReductionMode:<br>
type: int32_t<br>
draft: true<br>
@@ -507,45 +486,6 @@ controls:<br>
The AE algorithm has started a pre-capture metering session.<br>
\sa AePrecaptureTrigger<br>
<br>
- - AfState:<br>
- type: int32_t<br>
- draft: true<br>
- description: |<br>
- Control to report the current AF algorithm state. Currently identical to<br>
- ANDROID_CONTROL_AF_STATE.<br>
-<br>
- Current state of the AF algorithm.<br>
- enum:<br>
- - name: AfStateInactive<br>
- value: 0<br>
- description: The AF algorithm is inactive.<br>
- - name: AfStatePassiveScan<br>
- value: 1<br>
- description: |<br>
- AF is performing a passive scan of the scene in continuous<br>
- auto-focus mode.<br>
- - name: AfStatePassiveFocused<br>
- value: 2<br>
- description: |<br>
- AF believes the scene is in focus, but might restart scanning.<br>
- - name: AfStateActiveScan<br>
- value: 3<br>
- description: |<br>
- AF is performing a scan triggered by an AF trigger request.<br>
- \sa AfTrigger<br>
- - name: AfStateFocusedLock<br>
- value: 4<br>
- description: |<br>
- AF believes has focused correctly and has locked focus.<br>
- - name: AfStateNotFocusedLock<br>
- value: 5<br>
- description: |<br>
- AF has not been able to focus and has locked.<br>
- - name: AfStatePassiveUnfocused<br>
- value: 6<br>
- description: |<br>
- AF has completed a passive scan without finding focus.<br>
-<br>
- AwbState:<br>
type: int32_t<br>
draft: true<br>
@@ -690,4 +630,317 @@ controls:<br>
value. All of the custom test patterns will be static (that is the<br>
raw image must not vary from frame to frame).<br>
<br>
+ - AfMode:<br>
+ type: int32_t<br>
+ draft: true<br>
+ description: |<br>
+ Control to set the mode of the AF (autofocus) algorithm. Applications<br>
+ are allowed to set a new mode, and to send additional controls for<br>
+ that new mode, in the same request.<br>
+<br>
+ An implementation may choose not to implement all the modes.<br>
+<br>
+ enum:<br>
+ - name: AfModeManual<br>
+ value: 0<br>
+ description: |<br>
+ The AF algorithm is in manual mode. In this mode it will never<br>
+ perform any action nor move the lens of its own accord, but an<br>
+ application can set controls to move the lens.<br>
+<br>
+ In this mode the AfState will always report AfStateManual.<br>
+ - name: AfModeAuto<br>
+ value: 1<br>
+ description: |<br>
+ The AF algorithm is in auto mode. This means that the algorithm<br>
+ will never move the lens or change state unless the AfTrigger<br>
+ control is used. The AfTrigger control can be used to initiate a<br>
+ focus scan, the results of which will also be reported by AfState.<br>
+<br>
+ If the autofocus algorithm is moved from AfModeAuto to another<br>
+ mode while a scan is in progress, the scan is cancelled<br>
+ immediately, without waiting for the scan to finish.<br>
+<br>
+ When first entering this mode the AfState will report<br>
+ AfStateAuto. When a trigger control is sent, AfState will<br>
+ report AfStateAutoScanning for a period before spontaneously<br>
+ changing to AfStateAutoFocused or AfStateAutoFailed, depending on<br>
+ the outcome of the scan. It will remain in this state until<br>
+ another scan is initiated by the AfTrigger control. If a scan is<br>
+ cancelled (without changing to another mode), AfState will return<br>
+ to AfStateAuto.<br>
+ - name: AfModeContinuous<br>
+ value: 2<br>
+ description: |<br>
+ The AF algorithm is in continuous mode. This means that the lens<br>
+ can re-start a scan spontaneously at any moment, without any user<br>
+ intervention. The AfState still reports whether the algorithm is<br>
+ currently scanning or not, though the application has no ability<br>
+ to initiate or cancel scans (though it can "pause" them), nor to<br>
+ move the lens for itself.<br>
+<br>
+ When set to AfModeContinuous, the system will immediately initiate<br>
+ a scan so AfState will report AfStateContinuousScanning, and will<br>
+ settle on one of AfStateContinuousFocused or AfStateContinuousFailed,<br>
+ depending on the scan result.<br>
+<br>
+ - AfLensPosition:<br>
+ type: int32_t<br>
+ draft: true<br>
+ description: |<br>
+ Control to set the position of the lens to one of the following<br>
+ predefined locations. This control only has any effect when the AfMode<br>
+ is set to AfModeManual.<br>
+<br>
+ This control is distinct from the LensPosition control, which sets the<br>
+ lens position using the lens driver's units.<br>
+ enum:<br>
+ - name: AfLensPositionMacro<br>
+ value: 0<br>
+ description: The closest focal position of the lens.<br>
+ - name: AfLensPositionHyperfocal<br>
+ value: 1<br>
+ description: Hyperfocal position.<br>
+ - name: AfLensPositionInfinity<br>
+ value: 2<br>
+ description: The furthest focal position (usually infinity).<br>
+<br>
+ - AfRange:<br>
+ type: int32_t<br>
+ draft: true<br>
+ description: |<br>
+ Control to set the range of focus distances that is scanned. An<br>
+ implementation may choose not to implement all the options here.<br>
+ enum:<br>
+ - name: AfRangeNormal<br>
+ value: 0<br>
+ description: |<br>
+ A wide range of focus distances is scanned, all the way from<br>
+ infinity down to close distances, though depending on the<br>
+ implementation, possibly not including the very closest macro<br>
+ positions.<br>
+ - name: AfRangeMacro<br>
+ value: 1<br>
+ description: Only close distances are scanned.<br>
+ - name: AfRangeFull<br>
+ value: 2<br>
+ description: |<br>
+ The full range of focus distances is scanned just as with<br>
+ AfRangeNormal but this time including the very closest macro<br>
+ positions.<br>
+<br>
+ - AfSpeed:<br>
+ type: int32_t<br>
+ draft: true<br>
+ description: |<br>
+ Control that determines whether the AF algorithm is to move the lens<br>
+ as quickly as possible or more steadily. For example, during video<br>
+ recording it may be desirable not to move the lens too abruptly, but<br>
+ when in a preview mode (waiting for a still capture) it may be<br>
+ helpful to move the lens as quickly as is reasonably possible.<br>
+ enum:<br>
+ - name: AfSpeedNormal<br>
+ value: 0<br>
+ description: Move the lens at its usual speed.<br>
+ - name: AfSpeedFast<br>
+ value: 1<br>
+ description: Move the lens more quickly.<br>
+<br>
+ - AfWindows:<br>
+ type: Rectangle<br>
+ draft: true<br>
+ description: |<br>
+ Sets the focus windows used by the AF algorithm. The units used express<br>
+ a proportion of the ScalerCrop control (or if unavailable, of the entire<br>
+ image), as u0.16 format numbers.<br>
+<br>
+ In order to be activated, a rectangle must be programmed with non-zero<br>
+ width and height. If no rectangles are programmed in this way, then the<br>
+ system will choose its own single default window in the centre of the<br>
+ image.<br>
+<br>
+ The details of how the windows are used are platform dependent. We note<br>
+ that when there is more than one AF window, a typical implementation<br>
+ might find the optimal focus position for each one and finally select<br>
+ the window closest to the camera.<br>
+<br>
+ size: [platform dependent]<br>
+<br>
+ - AfTrigger:<br>
+ type: int32_t<br>
+ draft: true<br>
+ description: |<br>
+ This control starts an autofocus scan when AfMode is set to AfModeAuto,<br>
+ and can also be used to terminate a scan early.<br>
+<br>
+ It is ignored if AfMode is set to AfModeManual or AfModeContinuous.<br>
+<br>
+ enum:<br>
+ - name: AfTriggerStart<br>
+ value: 0<br>
+ description: Start an AF scan. Ignored if a scan is in progress.<br>
+ - name: AfTriggerCancel<br>
+ value: 1<br>
+ description: Cancel an AF scan. This does not cause the lens to move<br>
+ anywhere else. Ignored if no scan is in progress.<br>
+<br>
+ - AfPause:<br>
+ type: int32_t<br>
+ draft: true<br>
+ description: |<br>
+ This control has no effect except when in continuous autofocus mode<br>
+ (AfModeContinuous). It can be used to pause any lens movements while<br>
+ (for example) images are captured. The algorithm remains inactive<br>
+ until it is instructed to resume.<br>
+<br>
+ enum:<br>
+ - name: AfPauseImmediate<br>
+ value: 0<br>
+ description: |<br>
+ Pause the continuous autofocus algorithm immediately, whether or<br>
+ not any kind of scan is underway. If the AfState was previously<br>
+ reporting AfStateContinuousScanning it will now change to<br>
+ AfStateContinuousScanningPaused, and similarly for<br>
+ AfStateContinuousFocused and AfStateContinuousFailed.<br>
+ - name AfPauseDeferred<br>
+ value: 1<br>
+ description: |<br>
+ Pause the continuous autofocus algorithm as soon as it is no longer<br>
+ scanning. If the AfState is currently reporting<br>
+ AfStateContinuousFocused is will change to<br>
+ AfStateContinuousFocusedPaused, and similarly in the case of<br>
+ AfStateContinuousFailed.<br>
+<br>
+ If AfState reports AfStateContinuousScanning it will change to<br>
+ AfStateContinuousScanningPausing, and then move to one of<br>
+ AfStateContinuousFocusedPaused or AfStateContinuousFailedPaused<br>
+ when the scan completes.<br>
+ - name: AfPauseResume<br>
+ value: 2<br>
+ description: |<br>
+ Resume continous autofocus operation. The algorithm starts again<br>
+ from exactly where it left off, and the AfState will drop the<br>
+ 'Paused' or 'Pausing' part of the state.<br>
+<br>
+ - LensPosition:<br>
+ type: int32_t<br>
+ draft: true<br>
+ description: |<br>
+ Acts as a control to instruct the lens to move to a particular position<br>
+ and also reports back the position of the lens for each frame.<br>
+<br>
+ The units are determined by the lens driver.<br>
+<br>
+ The LensPosition control is ignored unless the AfMode is set to<br>
+ AfModeManual.<br>
+<br>
+ Note that this control is distinct from AfLensPosition, which allows<br>
+ the lens to be moved to its macro/hyperfocal/infinity position, rather<br>
+ than using lens driver units.<br>
+<br>
+ - AfState:<br>
+ type: int32_t<br>
+ draft: true<br>
+ description: |<br>
+ Reports the current state of the AF algorithm. The possible state changes<br>
+ are described below, although we add that the following general state<br>
+ changes are also allowed.<br>
+<br>
+ In any of the AfStateManual or AfStateContinuous states, the AfMode<br>
+ may be set to AfModeAuto and the algorithm will move to the<br>
+ AfStateAuto state. If AfTriggerStart is sent at the same time<br>
+ then the algorithm will move to AfStateAutoScanning state.<br>
+<br>
+ In any of the AfStateAuto or AfStateManual states, the AfMode may<br>
+ be set to AfModeContinuous and the algorithm will move to<br>
+ AfStateContinuousScanning.<br>
+<br>
+ In any of the AfStateAuto or AfStateContinuous states, the AfMode may<br>
+ be set to AfModeManual and the algorithm will move to<br>
+ AfStateManual. The lens will not be moved and will be left where<br>
+ it was at that moment.<br>
+<br>
+ enum:<br>
+ - name: AfStateManual<br>
+ value: 0<br>
+ description: |<br>
+ The AF algorithm is in manual mode (AfModeManual). The LensPosition<br>
+ and AfLensPosition controls can be used directly to move the lens. <br>
+ - name: AfStateAuto<br>
+ value: 1<br>
+ description: |<br>
+ The AF algorithm is in auto mode (AfModeAuto), and has either just<br>
+ been moved into that state, or a scan that was in progress has been<br>
+ cancelled.<br>
+ - name: AfStateAutoScanning<br>
+ value: 2<br>
+ description: |<br>
+ The AF algorithm is in auto mode (AfModeAuto), and a scan has been<br>
+ started using the AfTrigger control. The scan can be cancelled by<br>
+ sending AfTriggerCancel at which point the algorithm will either<br>
+ move back to AfStateAuto or, if the scan actually completes<br>
+ before the cancel request is processed, to one of<br>
+ AfStateAutoFocused or AfStateAutoFailed.<br>
+ - name: AfStateAutoFocused<br>
+ value: 3<br>
+ description: |<br>
+ The AF algorithm is in auto mode (AfModeAuto), and a scan has<br>
+ completed with the result that the algorithm believes the image is<br>
+ now in focus.<br>
+ - name: AfStateAutoFailed<br>
+ value: 4<br>
+ description: |<br>
+ The AF algorithm is in auto mode (AfModeAuto), and a scan has<br>
+ completed with the result that the algorithm did not find a good<br>
+ focus position.<br>
+ - name: AfStateContinuousScanning<br>
+ value: 5<br>
+ description: |<br>
+ The AF algorithm is in continuous mode (AfModeContinuous) and<br>
+ is currently scanning for a good focus position. This occurs when<br>
+ the mode is first set to AfModeContinuous, or may happen<br>
+ spontaneously when the algorithm believes a re-scan is needed.<br>
+ - name: AfStateContinuousScanningPausing<br>
+ value: 6<br>
+ description: |<br>
+ The AF algorithm is in continuous mode (AfModeContinuous) and<br>
+ was scanning when AfPauseDeferred was sent. The scan will complete<br>
+ at which point the algorithm moves to the<br>
+ AfStateContinuousFocusedPaused or AfStateContinuousFailedPaused<br>
+ state.<br>
+ - name: AfStateContinuousScanningPaused<br>
+ value: 7<br>
+ description: |<br>
+ The AF algorithm is in continuous mode (AfModeContinuous) and<br>
+ was scanning when AfPauseImmediate was sent. The scan will not<br>
+ complete and the algorithm will remain in this state. The scan<br>
+ may be resumed by sending AfPauseResume.<br>
+ - name: AfStateContinuousFocused<br>
+ value: 8<br>
+ description: |<br>
+ The AF algorithm is in continuous mode (AfModeContinuous) and<br>
+ a scan has completed with the algorithm believing it has found a<br>
+ good focus position.<br>
+ - name: AfStateContinuousFocusedPaused<br>
+ value: 9<br>
+ description: |<br>
+ The AF algorithm was in the AfStateContinuousFocused state and<br>
+ has been paused (by either AfPauseImmediate or AfPauseDeferred),<br>
+ or it was in the AfStateContinuousScanningPausing state and the<br>
+ scan has completed successfully. The algorithm will now remain<br>
+ in this state, and may be resumed by sending AfPauseResume.<br>
+ - name: AfStateContinuousFailed<br>
+ value: 10<br>
+ description: |<br>
+ The AF algorithm is in continuous mode (AfModeContinuous) and<br>
+ a scan has completed without finding a good focus position.<br>
+ - name: AfStateContinuousFailedPaused<br>
+ value: 11<br>
+ description: |<br>
+ The AF algorithm was in the AfStateContinuousFailed state and<br>
+ has been paused (by either AfPauseImmediate or AfPauseDeferred),<br>
+ or it was in the AfStateContinuousScanningPausing state and the<br>
+ scan has completed unsuccessfully. The algorithm will now remain<br>
+ in this state, and may be resumed by sending AfPauseResume.<br>
+<br>
...<br>
-- <br>
2.30.2<br>
<br>
</blockquote></div>