[{"id":22258,"web_url":"https://patchwork.libcamera.org/comment/22258/","msgid":"<45e6a2c9-fb59-4877-a639-f9931091529f@ideasonboard.com>","date":"2022-03-10T14:53:48","subject":"Re: [libcamera-devel] [PATCH 1/1] libcamera: controls: Controls for\n\tdriving AF (autofocus) algorithms","submitter":{"id":97,"url":"https://patchwork.libcamera.org/api/people/97/","name":"Nicolas Dufresne via libcamera-devel","email":"libcamera-devel@lists.libcamera.org"},"content":"Hi David,\n\nThanks for the patch !\n\nOn 10/03/2022 13:05, David Plowman via libcamera-devel wrote:\n> This patch describes a series of controls that allow applications to\n> drive AF algorithms:\n> \n> AfMode - manual, auto or continuous\n> AfRange - full, macro or normal\n> AfSpeed - fast or slow\n> AfWindow - AF window locations\n> AfTrigger - start (trigger an AF scan) or cancel\n> AfPause - pause continuous AF\n> LensPosition - position of lens from lens driver\n> AfState - reset, scanning, focused or failed\n> ---\n> src/libcamera/control_ids.yaml | 271 +++++++++++++++++++++++++--------\n> 1 file changed, 211 insertions(+), 60 deletions(-)\n> \n> diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml\n> index 9d4638ae..89636d82 100644\n> --- a/src/libcamera/control_ids.yaml\n> +++ b/src/libcamera/control_ids.yaml\n> @@ -406,27 +406,6 @@ controls:\n> The camera will cancel any active or completed metering sequence.\n> The AE algorithm is reset to its initial state.\n> \n> - - AfTrigger:\n> - type: int32_t\n> - draft: true\n> - description: |\n> - Control for AF trigger. Currently identical to\n> - ANDROID_CONTROL_AF_TRIGGER.\n> -\n> - Whether the camera device will trigger autofocus for this request.\n> - enum:\n> - - name: AfTriggerIdle\n> - value: 0\n> - description: The trigger is idle.\n> - - name: AfTriggerStart\n> - value: 1\n> - description: The AF routine is started by the camera.\n> - - name: AfTriggerCancel\n> - value: 2\n> - description: |\n> - The camera will cancel any active trigger and the AF routine is\n> - reset to its initial state.\n> -\n> - NoiseReductionMode:\n> type: int32_t\n> draft: true\n> @@ -507,45 +486,6 @@ controls:\n> The AE algorithm has started a pre-capture metering session.\n> \\sa AePrecaptureTrigger\n> \n> - - AfState:\n> - type: int32_t\n> - draft: true\n> - description: |\n> - Control to report the current AF algorithm state. Currently identical to\n> - ANDROID_CONTROL_AF_STATE.\n> -\n> - Current state of the AF algorithm.\n> - enum:\n> - - name: AfStateInactive\n> - value: 0\n> - description: The AF algorithm is inactive.\n> - - name: AfStatePassiveScan\n> - value: 1\n> - description: |\n> - AF is performing a passive scan of the scene in continuous\n> - auto-focus mode.\n> - - name: AfStatePassiveFocused\n> - value: 2\n> - description: |\n> - AF believes the scene is in focus, but might restart scanning.\n> - - name: AfStateActiveScan\n> - value: 3\n> - description: |\n> - AF is performing a scan triggered by an AF trigger request.\n> - \\sa AfTrigger\n> - - name: AfStateFocusedLock\n> - value: 4\n> - description: |\n> - AF believes has focused correctly and has locked focus.\n> - - name: AfStateNotFocusedLock\n> - value: 5\n> - description: |\n> - AF has not been able to focus and has locked.\n> - - name: AfStatePassiveUnfocused\n> - value: 6\n> - description: |\n> - AF has completed a passive scan without finding focus.\n> -\n> - AwbState:\n> type: int32_t\n> draft: true\n> @@ -690,4 +630,215 @@ controls:\n> value. All of the custom test patterns will be static (that is the\n> raw image must not vary from frame to frame).\n> \n> + - AfMode:\n> + type: int32_t\n\nSame open question for almost all: why int32_t and not uint8_t ?\nWe won't have negative values ? Maybe is it yaml ?\n\n> + draft: true\n> + description: |\n> + Control to set the mode of the AF (autofocus) algorithm. Applications\n> + are allowed to set a new mode, and to send additional controls for\n> + that new mode, in the same request.\n> + enum:\n> + - name: AfModeManual\n> + value: 0\n> + description: |\n> + The AF algorithm is in manual mode. In this mode it will never\n> + perform any action nor move the lens of its own accord. The only\n> +\t autofocus controls that have an immediate effect are AfMode (to\n> +\t switch out of manual mode) and LensPosition (so that the lens can\n> +\t be moved \"manually\").\n\nAlignment changed in the paragraph. I wonder if the part \"The only \nautofocus [...] \"manually\").\" should be moved in the top description ?\n\n> +\n> +\t In this mode the AfState will always report AfStateReset.\n> + - name: AfModeAuto\n> + value: 1\n> + description: |\n> + The AF algorithm is in auto mode. This means that the algorithm\n> + will never move the lens or change state unless the AfTrigger\n> + control is used. The AfTrigger control can be used to initiate a\n> + focus scan, the results of which will also be reported by AfState.\n> +\n> + If the autofocus algorithm is moved from AfModeAuto to another\n> + mode while a scan is in progress, the scan is cancelled\n> + immediately, without waiting for the scan to finish.\n> +\n> +\t When first entering this mode the AfState will report\n\nAlignment broken ?\n\n> +\t AfStateReset. When a trigger control is sent, AfState will\n> +\t report AfStateScanning for a period before spontaneously\n> +\t changing to AfStateFocused or AfStateFailed, depending on the\n> +\t outcome of the scan. It will remain in this state until another\n> +\t scan is initiated by the AfTrigger control. If a scan is\n> +\t cancelled (without changing to another mode), AfState will return\n> +\t to AfStateReset.\n> + - name: AfModeContinuous\n> + value: 2\n> + description: |\n> + The AF algorithm is in continuous mode. This means that the lens\n> + can re-start a scan spontaneously at any moment, without any user\n> + intervention. The AfState still reports whether the algorithm is\n> + currently scanning or not, though the application has no ability\n> + to initiate or cancel scans, nor move the lens for itself.\n> +\n\nAlignement broken ?\n\n> +\t When set to AfModeContinuous, the system will immediately initiate\n> +\t a scan so AfState will report AfStateScanning, and will settle on\n> +\t one of AfStateFocused or AfStateFailed, depending on the scan\n> +\t result.\n> +\n> + The continuous autofocus behaviour can be paused with the\n> +\t AfPause control. Pausing the algorithm does not change the value\n> +\t reported by AfState, so that applications can determine the\n> +\t state of the algorithm when the pause control took effect. Once\n> +\t un-paused (\"resumed\"), the algorithm starts again from exactly\n> +\t where it left off when it paused.\n\nI find this difficult to follow without having a state machine in some \ndrawn way... Is it something we could include in the documentation ? \nSeeing which Control changes to which one, which states are then \ntriggered, etc. ?\n\n> +\n> + - AfRange:\n> + type: int32_t\n> + draft: true\n> + description: |\n> + Control to set the range of focus distances that is scanned.\n> + enum:\n> + - name: AfRangeNormal\n> + value: 0\n> + description: |\n> +\t A wide range of focus distances is scanned, all the way from\n> +\t infinity down to close distances, though depending on the\n> +\t implementation, possibly not including the very closest macro\n> +\t positions.\n\nAlignment broken ?\n\n> + - name: AfRangeMacro\n> + value: 1\n> + description: Only close distances are scanned.\n> + - name: AfRangeFull\n> + value: 2\n> + description: |\n> + The full range of focus distances is scanned just as with\n> +\t AfRangeNormal but this time including the very closest macro\n> +\t positions.\n> +\n> + - AfSpeed:\n> + type: int32_t\n> + draft: true\n> + description: |\n> + Control that determines whether the AF algorithm is to move the lens\n> + as quickly as possible or more steadily. For example, during video\n> + recording it may be desirable not to move the lens too abruptly, but\n> + when in a preview mode (waiting for a still capture) it may be\n> + helpful to move the lens as quickly as is reasonably possible.\n> + enum:\n> + - name: AfSpeedNormal\n> + value: 0\n> + description: Move the lens at its usual speed.\n> + - name: AfSpeedFast\n> + value: 1\n> + description: Move the lens more quickly.\n> +\n\nCan we somehow configure this speed ?\n\n> + - AfWindow:\n> + type: Rectangle\n> + draft: true\n> + description: |\n> + Sets the focus windows used by the AF algorithm. The units used express\ns/windows/window ?\n> + a proportion of the ScalerCrop control (or if unavailable, of the entire\n> + image), as u0.16 format numbers.\n> +\n> + In order to be activated, a rectangle must be programmed with non-zero\n> + width and height. If no rectangles are programmed in this way, then the\n> + system will choose its own single default window in the centre of the\n> + image.\n> +\n> + The details of how the windows are used are platform dependent. We note\n> + that when there is more than one AF window, a typical implementation\n> + might find the optimal focus position for each one and finally select\n> +\t the window closest to the camera.\n\nAlignment broken ?\n\n> +\n> + size: [platform dependent]\n> +\n> + - AfTrigger:\n> + type: int32_t\n> + draft: true\n> + description: |\n> + This control starts an autofocus scan when AfMode is set to AfModeAuto,\n> + and can also be used to terminate a scan early.\n> +\n> + It is ignored if AfMode is set to AfModeContinuous.\n> +\n> + enum:\n> + - name: AfTriggerStart\n> + value: 0\n> + description: Start an AF scan. Ignored if a scan is in progress.\n> + - name: AfTriggerCancel\n> + value: 1\n> + description: Cancel an AF scan. Ingored if no scan is in progress.\n\nDoes cancelling a scan make the lens stay at its current position ? Or \nshould it be reset ?\n\n> +\n> + - AfPause:\n> + type: int32_t\n> + draft: true\n> + description: |\n> + This control has no effect except when in continuous autofocus mode\n> + (AfModeContinuous). It can be used to pause any lens movements while\n> + (for example) images are captured. The algorithm remains inactive\n> + until it is instructed to resume.\n> +\n> + enum:\n> + - name: AfPauseImmediate\n> + value: 0\n> + description: |\n> + Pause the continuous autofocus algorithm immediately, whether or\n> + not any kind of scan is underway. The AfState will continue to\n> + report whatever value it had when the control was enacted.\n> + - name AfPauseDeferred\n> + value: 1\n> + description: |\n> + Pause the continuous autofocus algorithm as soon as it is no longer\n> + scanning. The AfState will report AfStateFocused or AfStateFailed,\n> + depending on whether the final scan succeeds or not. If no scan is\n> +\t in currently progress, the algorithm will pause immediately.\n\nAlignment broken ?\n\n> + - name: AfPauseResume\n> + value: 2\n> + description: |\n\nAlignment broken ?\n\n> +\t Resume continous autofocus operation. The algorithm starts again\n> +\t from exactly where it left off, with AfState unchanged (one of\n> +\t AfStateFocused, AfStateFailed or following AfPauseImmediate it\n> +\t might also have been in the AfStateScanning state).\n> +\n> + - LensPosition:\n> + type: int32_t\n> + draft: true\n> + description: |\n> + Acts as a control to instruct the lens to move to a particular position\n> + and also reports back the position of the lens for each frame.\n> +\n> + The units are determined by the lens driver.\n> +\n> + The LensPosition control is ignored unless the AfMode is set to\n> + AfModeManual.\n> +\n> + - AfState:\n> + type: int32_t\n> + draft: true\n> + description: |\n> + Reports the current state of the AF algorithm.\n> + enum:\n> + - name: AfStateReset\n> + value: 0\n> + description: |\n> + The AF algorithm reports this state when:\n> + * It is in manual mode (AfModeManual).\n> + * The system has entered auto mode (AfModeAuto) but no scan\n> +\t\t has yet been initiated.\n> + * The system is in auto mode (AfModeAuto) and a scan has been\n> +\t\t cancelled.\n> + - name: AfStateScanning\n> + value: 1\n> + description: |\n> + AF is performing a scan. This state can be entered spontaneously\n> + if AfMode is set to AfModeContinuous, otherwise it requires the\n> + application to use the AfTrigger control to start the scan.\n> + - name: AfStateFocused\n> + value: 2\n> + description: |\n> + An AF scan has been performed and the algorithm believes the\n> + scene is in focus.\n> + - name: AfStateFailed\n> + value: 3\n> + description: |\n> + An AF scan has been performed but the algorithm has not been able\n> + to find the best focus position.\n\nI confirm my wish of having a graphical state machine :-).\n\nGreat work, thanks for it !\nJM\n\n> +\n> ...","headers":{"Return-Path":"","X-Original-To":"parsemail@patchwork.libcamera.org","Delivered-To":"parsemail@patchwork.libcamera.org","Received":["from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id 1D226BE08A\n\tfor ;\n\tThu, 10 Mar 2022 14:53:55 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 767AC632E2;\n\tThu, 10 Mar 2022 15:53:54 +0100 (CET)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 488AC601F5\n\tfor ;\n\tThu, 10 Mar 2022 15:53:52 +0100 (CET)","from [IPV6:2a01:e0a:169:7140:1119:faf9:2d11:44bb] (unknown\n\t[IPv6:2a01:e0a:169:7140:1119:faf9:2d11:44bb])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 9661E8E6;\n\tThu, 10 Mar 2022 15:53:51 +0100 (CET)"],"DKIM-Signature":["v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org;\n\ts=mail; t=1646924034;\n\tbh=EuUZlwuNQ/bsjF5RJVMaujjlyxR89oc4fiLWFleXE6M=;\n\th=Date:To:References:In-Reply-To:Subject:List-Id:List-Unsubscribe:\n\tList-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:\n\tFrom;\n\tb=n/C55RyuKfNTy2cgOjXMxGCXaSDlKqFMXvYEEfOBDWGZbrMJuNdjdpVf3Gmg6klIf\n\tamHsPZovcrVR3zS0hNdMGYhGx7Yqk1nf+wD6uhh/m62vjTz68whWlDyc55MoBFsV8M\n\tmITpb28qF8GLw0OZ4kxGyre9pK7DJGWlA8eBrTZit1ZCiJzk6Nd9rYs85eTFEsx8x5\n\t0Y0chAcEfJh2RhOoOoDw2si1g7BeZcxWENb+cElEfPW+ybOzkshDzHguHQHTsNCs1z\n\tQQflQZfj8HtPhrwSctc5jGFjoIHcvEo724y/mXwniHM16u/MiSuWL5uUWe1D2gZN5j\n\tcQ354ywfRoCyA==","v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1646924031;\n\tbh=EuUZlwuNQ/bsjF5RJVMaujjlyxR89oc4fiLWFleXE6M=;\n\th=Date:Subject:To:References:From:In-Reply-To:From;\n\tb=HirTCPhEqiV5VljsdOT4+KybWnHO669av+x2nF1QyaIgG/vp88Vy6aEhHPGS4oeS8\n\tg1HH41vXK6TrmknQjiPL1rkTLmRiHT+pozu3hHl9x1kPWUZPaixMnp2C6nlmP4DkE7\n\tRgsVijpAav0VsT+myiUNwBHlRviQDNIu5jKX3nNM="],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key; \n\tunprotected) header.d=ideasonboard.com\n\theader.i=@ideasonboard.com\n\theader.b=\"HirTCPhE\"; dkim-atps=neutral","Message-ID":"<45e6a2c9-fb59-4877-a639-f9931091529f@ideasonboard.com>","Date":"Thu, 10 Mar 2022 15:53:48 +0100","MIME-Version":"1.0","User-Agent":"Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101\n\tThunderbird/91.5.0","Content-Language":"en-US","To":"David Plowman ,\n\tlibcamera-devel@lists.libcamera.org, hanlinchen@chromium.org,\n\thpa@redhat.com","References":"<20220310120540.15296-1-david.plowman@raspberrypi.com>\n\t<20220310120540.15296-2-david.plowman@raspberrypi.com>","In-Reply-To":"<20220310120540.15296-2-david.plowman@raspberrypi.com>","Content-Type":"text/plain; charset=UTF-8; format=flowed","Content-Transfer-Encoding":"7bit","Subject":"Re: [libcamera-devel] [PATCH 1/1] libcamera: controls: Controls for\n\tdriving AF (autofocus) algorithms","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","From":"Jean-Michel Hautbois via libcamera-devel\n\t","Reply-To":"Jean-Michel Hautbois ","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}},{"id":22268,"web_url":"https://patchwork.libcamera.org/comment/22268/","msgid":"","date":"2022-03-14T11:05:50","subject":"Re: [libcamera-devel] [PATCH 1/1] libcamera: controls: Controls for\n\tdriving AF (autofocus) algorithms","submitter":{"id":97,"url":"https://patchwork.libcamera.org/api/people/97/","name":"Nicolas Dufresne via libcamera-devel","email":"libcamera-devel@lists.libcamera.org"},"content":"Hi David, Thanks for the great patch!\n\nOn Thu, Mar 10, 2022 at 10:53 PM Jean-Michel Hautbois <\njeanmichel.hautbois@ideasonboard.com> wrote:\n\n> Hi David,\n>\n> Thanks for the patch !\n>\n> On 10/03/2022 13:05, David Plowman via libcamera-devel wrote:\n> > This patch describes a series of controls that allow applications to\n> > drive AF algorithms:\n> >\n> > AfMode - manual, auto or continuous\n> > AfRange - full, macro or normal\n> > AfSpeed - fast or slow\n> > AfWindow - AF window locations\n> > AfTrigger - start (trigger an AF scan) or cancel\n> > AfPause - pause continuous AF\n> > LensPosition - position of lens from lens driver\n> > AfState - reset, scanning, focused or failed\n> > ---\n> > src/libcamera/control_ids.yaml | 271 +++++++++++++++++++++++++--------\n> > 1 file changed, 211 insertions(+), 60 deletions(-)\n> >\n> > diff --git a/src/libcamera/control_ids.yaml\n> b/src/libcamera/control_ids.yaml\n> > index 9d4638ae..89636d82 100644\n> > --- a/src/libcamera/control_ids.yaml\n> > +++ b/src/libcamera/control_ids.yaml\n> > @@ -406,27 +406,6 @@ controls:\n> > The camera will cancel any active or completed metering\n> sequence.\n> > The AE algorithm is reset to its initial state.\n> >\n> > - - AfTrigger:\n> > - type: int32_t\n> > - draft: true\n> > - description: |\n> > - Control for AF trigger. Currently identical to\n> > - ANDROID_CONTROL_AF_TRIGGER.\n> > -\n> > - Whether the camera device will trigger autofocus for this\n> request.\n> > - enum:\n> > - - name: AfTriggerIdle\n> > - value: 0\n> > - description: The trigger is idle.\n> > - - name: AfTriggerStart\n> > - value: 1\n> > - description: The AF routine is started by the camera.\n> > - - name: AfTriggerCancel\n> > - value: 2\n> > - description: |\n> > - The camera will cancel any active trigger and the AF\n> routine is\n> > - reset to its initial state.\n> > -\n> > - NoiseReductionMode:\n> > type: int32_t\n> > draft: true\n> > @@ -507,45 +486,6 @@ controls:\n> > The AE algorithm has started a pre-capture metering\n> session.\n> > \\sa AePrecaptureTrigger\n> >\n> > - - AfState:\n> > - type: int32_t\n> > - draft: true\n> > - description: |\n> > - Control to report the current AF algorithm state. Currently\n> identical to\n> > - ANDROID_CONTROL_AF_STATE.\n> > -\n> > - Current state of the AF algorithm.\n> > - enum:\n> > - - name: AfStateInactive\n> > - value: 0\n> > - description: The AF algorithm is inactive.\n> > - - name: AfStatePassiveScan\n> > - value: 1\n> > - description: |\n> > - AF is performing a passive scan of the scene in continuous\n> > - auto-focus mode.\n> > - - name: AfStatePassiveFocused\n> > - value: 2\n> > - description: |\n> > - AF believes the scene is in focus, but might restart\n> scanning.\n> > - - name: AfStateActiveScan\n> > - value: 3\n> > - description: |\n> > - AF is performing a scan triggered by an AF trigger request.\n> > - \\sa AfTrigger\n> > - - name: AfStateFocusedLock\n> > - value: 4\n> > - description: |\n> > - AF believes has focused correctly and has locked focus.\n> > - - name: AfStateNotFocusedLock\n> > - value: 5\n> > - description: |\n> > - AF has not been able to focus and has locked.\n> > - - name: AfStatePassiveUnfocused\n> > - value: 6\n> > - description: |\n> > - AF has completed a passive scan without finding focus.\n> > -\n> > - AwbState:\n> > type: int32_t\n> > draft: true\n> > @@ -690,4 +630,215 @@ controls:\n> > value. All of the custom test patterns will be static\n> (that is the\n> > raw image must not vary from frame to frame).\n> >\n> > + - AfMode:\n> > + type: int32_t\n>\n> Same open question for almost all: why int32_t and not uint8_t ?\n> We won't have negative values ? Maybe is it yaml ?\n>\n> > + draft: true\n> > + description: |\n> > + Control to set the mode of the AF (autofocus) algorithm.\n> Applications\n> > + are allowed to set a new mode, and to send additional controls\n> for\n> > + that new mode, in the same request.\n> > + enum:\n> > + - name: AfModeManual\n> > + value: 0\n> > + description: |\n> > + The AF algorithm is in manual mode. In this mode it will\n> never\n> > + perform any action nor move the lens of its own accord. The\n> only\n> > + autofocus controls that have an immediate effect are AfMode (to\n> > + switch out of manual mode) and LensPosition (so that the lens\n> can\n> > + be moved \"manually\").\n>\n> Alignment changed in the paragraph. I wonder if the part \"The only\n> autofocus [...] \"manually\").\" should be moved in the top description ?\n>\n> > +\n> > + In this mode the AfState will always report AfStateReset.\n> > + - name: AfModeAuto\n> > + value: 1\n> > + description: |\n> > + The AF algorithm is in auto mode. This means that the\n> algorithm\n> > + will never move the lens or change state unless the\n> AfTrigger\n> > + control is used. The AfTrigger control can be used to\n> initiate a\n> > + focus scan, the results of which will also be reported by\n> AfState.\n> > +\n> > + If the autofocus algorithm is moved from AfModeAuto to\n> another\n> > + mode while a scan is in progress, the scan is cancelled\n> > + immediately, without waiting for the scan to finish.\n> > +\n> > + When first entering this mode the AfState will report\n>\n> Alignment broken ?\n>\n> > + AfStateReset. When a trigger control is sent, AfState will\n> > + report AfStateScanning for a period before spontaneously\n> > + changing to AfStateFocused or AfStateFailed, depending on the\n> > + outcome of the scan. It will remain in this state until another\n> > + scan is initiated by the AfTrigger control. If a scan is\n> > + cancelled (without changing to another mode), AfState will\n> return\n> > + to AfStateReset.\n> > + - name: AfModeContinuous\n> > + value: 2\n> > + description: |\n> > + The AF algorithm is in continuous mode. This means that the\n> lens\n> > + can re-start a scan spontaneously at any moment, without\n> any user\n> > + intervention. The AfState still reports whether the\n> algorithm is\n> > + currently scanning or not, though the application has no\n> ability\n> > + to initiate or cancel scans, nor move the lens for itself.\n> > +\n>\n> Alignement broken ?\n>\n> > + When set to AfModeContinuous, the system will immediately\n> initiate\n> > + a scan so AfState will report AfStateScanning, and will settle\n> on\n> > + one of AfStateFocused or AfStateFailed, depending on the scan\n> > + result.\n> > +\n> > + The continuous autofocus behaviour can be paused with the\n> > + AfPause control. Pausing the algorithm does not change the\n> value\n> > + reported by AfState, so that applications can determine the\n> > + state of the algorithm when the pause control took effect. Once\n> > + un-paused (\"resumed\"), the algorithm starts again from exactly\n> > + where it left off when it paused.\n>\nAn open question:\nShould we make Macro and Continuous mandatory? Or they can be optional\ndepending on the algorithm implementation?\n\n>\n> I find this difficult to follow without having a state machine in some\n> drawn way... Is it something we could include in the documentation ?\n> Seeing which Control changes to which one, which states are then\n> triggered, etc. ?\n>\n> > +\n> > + - AfRange:\n> > + type: int32_t\n> > + draft: true\n> > + description: |\n> > + Control to set the range of focus distances that is scanned.\n> > + enum:\n> > + - name: AfRangeNormal\n> > + value: 0\n> > + description: |\n> > + A wide range of focus distances is scanned, all the way from\n> > + infinity down to close distances, though depending on the\n> > + implementation, possibly not including the very closest macro\n> > + positions.\n>\n> Alignment broken ?\n>\n> > + - name: AfRangeMacro\n> > + value: 1\n> > + description: Only close distances are scanned.\n> > + - name: AfRangeFull\n> > + value: 2\n> > + description: |\n> > + The full range of focus distances is scanned just as with\n> > + AfRangeNormal but this time including the very closest macro\n> > + positions.\n> > +\n> > + - AfSpeed:\n> > + type: int32_t\n> > + draft: true\n> > + description: |\n> > + Control that determines whether the AF algorithm is to move the\n> lens\n> > + as quickly as possible or more steadily. For example, during\n> video\n> > + recording it may be desirable not to move the lens too\n> abruptly, but\n> > + when in a preview mode (waiting for a still capture) it may be\n> > + helpful to move the lens as quickly as is reasonably possible.\n> > + enum:\n> > + - name: AfSpeedNormal\n> > + value: 0\n> > + description: Move the lens at its usual speed.\n> > + - name: AfSpeedFast\n> > + value: 1\n> > + description: Move the lens more quickly.\n> > +\n>\n> Can we somehow configure this speed ?\n>\n> > + - AfWindow:\n> > + type: Rectangle\n> > + draft: true\n> > + description: |\n> > + Sets the focus windows used by the AF algorithm. The units\n> used express\n> s/windows/window ?\n> > + a proportion of the ScalerCrop control (or if unavailable, of\n> the entire\n> > + image), as u0.16 format numbers.\n> > +\n> > + In order to be activated, a rectangle must be programmed with\n> non-zero\n> > + width and height. If no rectangles are programmed in this way,\n> then the\n> > + system will choose its own single default window in the centre\n> of the\n> > + image.\n> > +\n> > + The details of how the windows are used are platform\n> dependent. We note\n> > + that when there is more than one AF window, a typical\n> implementation\n> > + might find the optimal focus position for each one and finally\n> select\n> > + the window closest to the camera.\n>\n> Alignment broken ?\n>\n> > +\n> > + size: [platform dependent]\n> > +\n> > + - AfTrigger:\n> > + type: int32_t\n> > + draft: true\n> > + description: |\n> > + This control starts an autofocus scan when AfMode is set to\n> AfModeAuto,\n> > + and can also be used to terminate a scan early.\n> > +\n> > + It is ignored if AfMode is set to AfModeContinuous.\n> > +\n> > + enum:\n> > + - name: AfTriggerStart\n> > + value: 0\n> > + description: Start an AF scan. Ignored if a scan is in\n> progress.\n> > + - name: AfTriggerCancel\n> > + value: 1\n> > + description: Cancel an AF scan. Ingored if no scan is in\n> progress.\n>\n> Does cancelling a scan make the lens stay at its current position ? Or\n> should it be reset ?\n>\n> > +\n> > + - AfPause:\n> > + type: int32_t\n> > + draft: true\n> > + description: |\n> > + This control has no effect except when in continuous autofocus\n> mode\n> > + (AfModeContinuous). It can be used to pause any lens movements\n> while\n> > + (for example) images are captured. The algorithm remains\n> inactive\n> > + until it is instructed to resume.\n> > +\n> > + enum:\n> > + - name: AfPauseImmediate\n> > + value: 0\n> > + description: |\n> > + Pause the continuous autofocus algorithm immediately,\n> whether or\n> > + not any kind of scan is underway. The AfState will continue\n> to\n> > + report whatever value it had when the control was enacted.\n> > + - name AfPauseDeferred\n> > + value: 1\n> > + description: |\n> > + Pause the continuous autofocus algorithm as soon as it is\n> no longer\n> > + scanning. The AfState will report AfStateFocused or\n> AfStateFailed,\n> > + depending on whether the final scan succeeds or not. If no\n> scan is\n> > + in currently progress, the algorithm will pause immediately.\n>\n> Just to confirm. Since we removed the AftriggerIdle, I guess the two\ncontrols AfTriggerStart and AfPauseDeferred should be continuously set\nuntil the state becomes focused or failed? If so, is it better to mention\nit in the description?\nFor AfPauseImmediate, should it only report the state as failed when it's\nscanning and reset?\n\n\n> Alignment broken ?\n>\n> > + - name: AfPauseResume\n> > + value: 2\n> > + description: |\n>\n> Alignment broken ?\n>\n> > + Resume continous autofocus operation. The algorithm starts\n> again\n> > + from exactly where it left off, with AfState unchanged (one of\n> > + AfStateFocused, AfStateFailed or following AfPauseImmediate it\n> > + might also have been in the AfStateScanning state).\n> > +\n> > + - LensPosition:\n> > + type: int32_t\n> > + draft: true\n> > + description: |\n> > + Acts as a control to instruct the lens to move to a particular\n> position\n> > + and also reports back the position of the lens for each frame.\n> > +\n> > + The units are determined by the lens driver.\n> > +\n> > + The LensPosition control is ignored unless the AfMode is set to\n> > + AfModeManual.\n> > +\n> > + - AfState:\n> > + type: int32_t\n> > + draft: true\n> > + description: |\n> > + Reports the current state of the AF algorithm.\n> > + enum:\n> > + - name: AfStateReset\n> > + value: 0\n> > + description: |\n> > + The AF algorithm reports this state when:\n> > + * It is in manual mode (AfModeManual).\n> > + * The system has entered auto mode (AfModeAuto) but\n> no scan\n> > + has yet been initiated.\n> > + * The system is in auto mode (AfModeAuto) and a scan\n> has been\n> > + cancelled.\n> > + - name: AfStateScanning\n> > + value: 1\n> > + description: |\n> > + AF is performing a scan. This state can be entered\n> spontaneously\n> > + if AfMode is set to AfModeContinuous, otherwise it\n> requires the\n> > + application to use the AfTrigger control to start the\n> scan.\n> > + - name: AfStateFocused\n> > + value: 2\n> > + description: |\n> > + An AF scan has been performed and the algorithm believes\n> the\n> > + scene is in focus.\n> > + - name: AfStateFailed\n> > + value: 3\n> > + description: |\n> > + An AF scan has been performed but the algorithm has not\n> been able\n> > + to find the best focus position.\n>\n> I confirm my wish of having a graphical state machine :-).\n>\nVote +1 :-).\n\n>\n> Great work, thanks for it !\n> JM\n>\n> > +\n> > ...\n>","headers":{"Return-Path":"","X-Original-To":"parsemail@patchwork.libcamera.org","Delivered-To":"parsemail@patchwork.libcamera.org","Received":["from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id 481AFBF415\n\tfor ;\n\tMon, 14 Mar 2022 11:06:05 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 93D316118A;\n\tMon, 14 Mar 2022 12:06:04 +0100 (CET)","from mail-oo1-xc2a.google.com (mail-oo1-xc2a.google.com\n\t[IPv6:2607:f8b0:4864:20::c2a])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id BA67C604E6\n\tfor ;\n\tMon, 14 Mar 2022 12:06:02 +0100 (CET)","by mail-oo1-xc2a.google.com with SMTP id\n\tj7-20020a4ad6c7000000b0031c690e4123so19720633oot.11\n\tfor ;\n\tMon, 14 Mar 2022 04:06:02 -0700 (PDT)"],"DKIM-Signature":["v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org;\n\ts=mail; t=1647255964;\n\tbh=9208vgTAVVvHgVFL2k9Bty0nAo48PHkuQgsZmpmm5j8=;\n\th=References:In-Reply-To:Date:To:Subject:List-Id:List-Unsubscribe:\n\tList-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc:\n\tFrom;\n\tb=20ygMUhmHMEBNMsnVBOOhBJ63j9ZdcPUXQo/YUD3wZYuSBppU7YdUm5necNahT/kA\n\tUj7TtBIP/sbboOdEGYuT5RZixrFab1bP9IOPu3uHgAsCushALn9hQ67LKBebIvx/7t\n\tOjn+trlUK31KYDhVP1e6cBtSFMpgQxAOri8Js29kOokqGfQLmIKb8SW6aftFSzwn+X\n\t+Z0t+LBbEgiUqIcXSR4kFdNOZLIFHL1sBUyuwZNyrlhiuLHL4+x32pFiKzaoDs1ejf\n\tlGqWyvXxuPGH4kUf3jMEWaEecudTCO086twl/MXTpC/cAxashZWCAnp7CCgZaDOOMj\n\tkD2j1tYmbIsBA==","v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org;\n\ts=google; \n\th=mime-version:references:in-reply-to:from:date:message-id:subject:to\n\t:cc; bh=qEvFCOp3S0WLkG7u6PfBg81F5wUOFCELPO7zrxCWkLg=;\n\tb=Mi4DdOQajp7BDuV56VgaaErRu/2wG5YUmo5zvwc7/EBzvcRfFawfx2FQQLjH0wjTUw\n\t7Mc3ze7/6jv1y0treMCF7ql7BYsB3ESb5XKzkPhiYE/fh/1NAszw1kd+4L1rqi5s7Uo9\n\tgF0Y10qinPAIOiIrG2p3RxfmlIPTeItzyBqxI="],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key; \n\tunprotected) header.d=chromium.org\n\theader.i=@chromium.org header.b=\"Mi4DdOQa\"; \n\tdkim-atps=neutral","X-Google-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=1e100.net; s=20210112;\n\th=x-gm-message-state:mime-version:references:in-reply-to:from:date\n\t:message-id:subject:to:cc;\n\tbh=qEvFCOp3S0WLkG7u6PfBg81F5wUOFCELPO7zrxCWkLg=;\n\tb=tR2hDw54jEyRbdAUgBV3g2NIFP48bqU+jG0gJRe9/E4W6Y3w9c7hKD/102xT3+RVKN\n\thx/kYAwIXhp9j/dUAYhwzkBjG9ICUJkTiVJfYtk2XvKR9NrjEeBMPjXF47nbZgDRPgXD\n\tO4jjwqBGnqq4V3v6czVdqI8vHNg4H3RxGRMLMydEY0ONc2rtu0cuNmlJfrJzpKY1AVFA\n\t6DA1wHcKAH4bPSRjvwZArk0bRaPGb/zRjx6sNCiZ8151VU3EPHxiMLlylRW52+mccK0o\n\t1BL1d7B4fxFFrPlm9oMCw4rwbAV0W3aldRU1gItCcGJeHqVhzLKkRdvA7OCbtAPzSDzm\n\t8xRw==","X-Gm-Message-State":"AOAM530vEnWdo1nl1ovGwlQpeiy/qh7N9BsR8tVzbHtBttj/BIbkjUK0\n\tCHFPBIwUutSFYacmXasiDfQfW0bmVZgjONm45DQ8DQ==","X-Google-Smtp-Source":"ABdhPJz8WioWsJuuAiHLzLX93u/mHtw62zqYVIV3p4aPpRske18ZW9cBegzXxLABDndXLXQeBzAENB7E4zx94Pl2PCk=","X-Received":"by 2002:a05:6870:b417:b0:d4:547c:7a76 with SMTP id\n\tx23-20020a056870b41700b000d4547c7a76mr16522390oap.65.1647255961390;\n\tMon, 14 Mar 2022 04:06:01 -0700 (PDT)","MIME-Version":"1.0","References":"<20220310120540.15296-1-david.plowman@raspberrypi.com>\n\t<20220310120540.15296-2-david.plowman@raspberrypi.com>\n\t<45e6a2c9-fb59-4877-a639-f9931091529f@ideasonboard.com>","In-Reply-To":"<45e6a2c9-fb59-4877-a639-f9931091529f@ideasonboard.com>","Date":"Mon, 14 Mar 2022 19:05:50 +0800","Message-ID":"","To":"Jean-Michel Hautbois ","Content-Type":"multipart/alternative; boundary=\"0000000000006ee68705da2baa05\"","Subject":"Re: [libcamera-devel] [PATCH 1/1] libcamera: controls: Controls for\n\tdriving AF (autofocus) algorithms","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","From":"Hanlin Chen via libcamera-devel ","Reply-To":"Hanlin Chen ","Cc":"libcamera-devel@lists.libcamera.org","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}},{"id":22283,"web_url":"https://patchwork.libcamera.org/comment/22283/","msgid":"","date":"2022-03-15T16:34:23","subject":"Re: [libcamera-devel] [PATCH 1/1] libcamera: controls: Controls for\n\tdriving AF (autofocus) algorithms","submitter":{"id":97,"url":"https://patchwork.libcamera.org/api/people/97/","name":"Nicolas Dufresne via libcamera-devel","email":"libcamera-devel@lists.libcamera.org"},"content":"Hi Hanlin, Jean-Michel, everyone\n\nOn Mon, 14 Mar 2022 at 11:06, Hanlin Chen wrote:\n>\n> Hi David, Thanks for the great patch!\n>\n> On Thu, Mar 10, 2022 at 10:53 PM Jean-Michel Hautbois wrote:\n>>\n>> Hi David,\n>>\n>> Thanks for the patch !\n>>\n>> On 10/03/2022 13:05, David Plowman via libcamera-devel wrote:\n>> > This patch describes a series of controls that allow applications to\n>> > drive AF algorithms:\n>> >\n>> > AfMode - manual, auto or continuous\n>> > AfRange - full, macro or normal\n>> > AfSpeed - fast or slow\n>> > AfWindow - AF window locations\n>> > AfTrigger - start (trigger an AF scan) or cancel\n>> > AfPause - pause continuous AF\n>> > LensPosition - position of lens from lens driver\n>> > AfState - reset, scanning, focused or failed\n>> > ---\n>> > src/libcamera/control_ids.yaml | 271 +++++++++++++++++++++++++--------\n>> > 1 file changed, 211 insertions(+), 60 deletions(-)\n>> >\n>> > diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml\n>> > index 9d4638ae..89636d82 100644\n>> > --- a/src/libcamera/control_ids.yaml\n>> > +++ b/src/libcamera/control_ids.yaml\n>> > @@ -406,27 +406,6 @@ controls:\n>> > The camera will cancel any active or completed metering sequence.\n>> > The AE algorithm is reset to its initial state.\n>> >\n>> > - - AfTrigger:\n>> > - type: int32_t\n>> > - draft: true\n>> > - description: |\n>> > - Control for AF trigger. Currently identical to\n>> > - ANDROID_CONTROL_AF_TRIGGER.\n>> > -\n>> > - Whether the camera device will trigger autofocus for this request.\n>> > - enum:\n>> > - - name: AfTriggerIdle\n>> > - value: 0\n>> > - description: The trigger is idle.\n>> > - - name: AfTriggerStart\n>> > - value: 1\n>> > - description: The AF routine is started by the camera.\n>> > - - name: AfTriggerCancel\n>> > - value: 2\n>> > - description: |\n>> > - The camera will cancel any active trigger and the AF routine is\n>> > - reset to its initial state.\n>> > -\n>> > - NoiseReductionMode:\n>> > type: int32_t\n>> > draft: true\n>> > @@ -507,45 +486,6 @@ controls:\n>> > The AE algorithm has started a pre-capture metering session.\n>> > \\sa AePrecaptureTrigger\n>> >\n>> > - - AfState:\n>> > - type: int32_t\n>> > - draft: true\n>> > - description: |\n>> > - Control to report the current AF algorithm state. Currently identical to\n>> > - ANDROID_CONTROL_AF_STATE.\n>> > -\n>> > - Current state of the AF algorithm.\n>> > - enum:\n>> > - - name: AfStateInactive\n>> > - value: 0\n>> > - description: The AF algorithm is inactive.\n>> > - - name: AfStatePassiveScan\n>> > - value: 1\n>> > - description: |\n>> > - AF is performing a passive scan of the scene in continuous\n>> > - auto-focus mode.\n>> > - - name: AfStatePassiveFocused\n>> > - value: 2\n>> > - description: |\n>> > - AF believes the scene is in focus, but might restart scanning.\n>> > - - name: AfStateActiveScan\n>> > - value: 3\n>> > - description: |\n>> > - AF is performing a scan triggered by an AF trigger request.\n>> > - \\sa AfTrigger\n>> > - - name: AfStateFocusedLock\n>> > - value: 4\n>> > - description: |\n>> > - AF believes has focused correctly and has locked focus.\n>> > - - name: AfStateNotFocusedLock\n>> > - value: 5\n>> > - description: |\n>> > - AF has not been able to focus and has locked.\n>> > - - name: AfStatePassiveUnfocused\n>> > - value: 6\n>> > - description: |\n>> > - AF has completed a passive scan without finding focus.\n>> > -\n>> > - AwbState:\n>> > type: int32_t\n>> > draft: true\n>> > @@ -690,4 +630,215 @@ controls:\n>> > value. All of the custom test patterns will be static (that is the\n>> > raw image must not vary from frame to frame).\n>> >\n>> > + - AfMode:\n>> > + type: int32_t\n>>\n>> Same open question for almost all: why int32_t and not uint8_t ?\n>> We won't have negative values ? Maybe is it yaml ?\n\nThe file only seems to contain int32_ts so that's what I copied. Am I\nallowed other things?\n\n>>\n>> > + draft: true\n>> > + description: |\n>> > + Control to set the mode of the AF (autofocus) algorithm. Applications\n>> > + are allowed to set a new mode, and to send additional controls for\n>> > + that new mode, in the same request.\n>> > + enum:\n>> > + - name: AfModeManual\n>> > + value: 0\n>> > + description: |\n>> > + The AF algorithm is in manual mode. In this mode it will never\n>> > + perform any action nor move the lens of its own accord. The only\n>> > + autofocus controls that have an immediate effect are AfMode (to\n>> > + switch out of manual mode) and LensPosition (so that the lens can\n>> > + be moved \"manually\").\n>>\n>> Alignment changed in the paragraph. I wonder if the part \"The only\n>> autofocus [...] \"manually\").\" should be moved in the top description ?\n\nThanks, I'll fix this up and all the ones below...\n\n>>\n>> > +\n>> > + In this mode the AfState will always report AfStateReset.\n>> > + - name: AfModeAuto\n>> > + value: 1\n>> > + description: |\n>> > + The AF algorithm is in auto mode. This means that the algorithm\n>> > + will never move the lens or change state unless the AfTrigger\n>> > + control is used. The AfTrigger control can be used to initiate a\n>> > + focus scan, the results of which will also be reported by AfState.\n>> > +\n>> > + If the autofocus algorithm is moved from AfModeAuto to another\n>> > + mode while a scan is in progress, the scan is cancelled\n>> > + immediately, without waiting for the scan to finish.\n>> > +\n>> > + When first entering this mode the AfState will report\n>>\n>> Alignment broken ?\n>>\n>> > + AfStateReset. When a trigger control is sent, AfState will\n>> > + report AfStateScanning for a period before spontaneously\n>> > + changing to AfStateFocused or AfStateFailed, depending on the\n>> > + outcome of the scan. It will remain in this state until another\n>> > + scan is initiated by the AfTrigger control. If a scan is\n>> > + cancelled (without changing to another mode), AfState will return\n>> > + to AfStateReset.\n>> > + - name: AfModeContinuous\n>> > + value: 2\n>> > + description: |\n>> > + The AF algorithm is in continuous mode. This means that the lens\n>> > + can re-start a scan spontaneously at any moment, without any user\n>> > + intervention. The AfState still reports whether the algorithm is\n>> > + currently scanning or not, though the application has no ability\n>> > + to initiate or cancel scans, nor move the lens for itself.\n>> > +\n>>\n>> Alignement broken ?\n>>\n>> > + When set to AfModeContinuous, the system will immediately initiate\n>> > + a scan so AfState will report AfStateScanning, and will settle on\n>> > + one of AfStateFocused or AfStateFailed, depending on the scan\n>> > + result.\n>> > +\n>> > + The continuous autofocus behaviour can be paused with the\n>> > + AfPause control. Pausing the algorithm does not change the value\n>> > + reported by AfState, so that applications can determine the\n>> > + state of the algorithm when the pause control took effect. Once\n>> > + un-paused (\"resumed\"), the algorithm starts again from exactly\n>> > + where it left off when it paused.\n>\n> An open question:\n> Should we make Macro and Continuous mandatory? Or they can be optional depending on the algorithm implementation?\n\nI'd certainly like CAF (Continuous AF) to be optional. It's a feature\nyou could choose not to implement as it's quite a lot of work, and\nhard to make work well (especially without PDAF).\n\nSomething like the \"Macro\" range... don't mind. We could make it\noptional, or define it to be the same as \"Normal\". What do people\nthink?\n\n>>\n>>\n>> I find this difficult to follow without having a state machine in some\n>> drawn way... Is it something we could include in the documentation ?\n>> Seeing which Control changes to which one, which states are then\n>> triggered, etc. ?\n>>\n>> > +\n>> > + - AfRange:\n>> > + type: int32_t\n>> > + draft: true\n>> > + description: |\n>> > + Control to set the range of focus distances that is scanned.\n>> > + enum:\n>> > + - name: AfRangeNormal\n>> > + value: 0\n>> > + description: |\n>> > + A wide range of focus distances is scanned, all the way from\n>> > + infinity down to close distances, though depending on the\n>> > + implementation, possibly not including the very closest macro\n>> > + positions.\n>>\n>> Alignment broken ?\n>>\n>> > + - name: AfRangeMacro\n>> > + value: 1\n>> > + description: Only close distances are scanned.\n>> > + - name: AfRangeFull\n>> > + value: 2\n>> > + description: |\n>> > + The full range of focus distances is scanned just as with\n>> > + AfRangeNormal but this time including the very closest macro\n>> > + positions.\n>> > +\n>> > + - AfSpeed:\n>> > + type: int32_t\n>> > + draft: true\n>> > + description: |\n>> > + Control that determines whether the AF algorithm is to move the lens\n>> > + as quickly as possible or more steadily. For example, during video\n>> > + recording it may be desirable not to move the lens too abruptly, but\n>> > + when in a preview mode (waiting for a still capture) it may be\n>> > + helpful to move the lens as quickly as is reasonably possible.\n>> > + enum:\n>> > + - name: AfSpeedNormal\n>> > + value: 0\n>> > + description: Move the lens at its usual speed.\n>> > + - name: AfSpeedFast\n>> > + value: 1\n>> > + description: Move the lens more quickly.\n>> > +\n>>\n>> Can we somehow configure this speed ?\n\nGood question. You could imagine a continuous value here, though that\ndoes start to force the developer to do more work, and testing gets\nharder. So I feel slightly inclined to leave this as a binary choice,\nbut am certainly open to persuasion.\n\n>>\n>> > + - AfWindow:\n>> > + type: Rectangle\n>> > + draft: true\n>> > + description: |\n>> > + Sets the focus windows used by the AF algorithm. The units used express\n>> s/windows/window ?\n>> > + a proportion of the ScalerCrop control (or if unavailable, of the entire\n>> > + image), as u0.16 format numbers.\n>> > +\n>> > + In order to be activated, a rectangle must be programmed with non-zero\n>> > + width and height. If no rectangles are programmed in this way, then the\n>> > + system will choose its own single default window in the centre of the\n>> > + image.\n>> > +\n>> > + The details of how the windows are used are platform dependent. We note\n>> > + that when there is more than one AF window, a typical implementation\n>> > + might find the optimal focus position for each one and finally select\n>> > + the window closest to the camera.\n>>\n>> Alignment broken ?\n>>\n>> > +\n>> > + size: [platform dependent]\n>> > +\n>> > + - AfTrigger:\n>> > + type: int32_t\n>> > + draft: true\n>> > + description: |\n>> > + This control starts an autofocus scan when AfMode is set to AfModeAuto,\n>> > + and can also be used to terminate a scan early.\n>> > +\n>> > + It is ignored if AfMode is set to AfModeContinuous.\n>> > +\n>> > + enum:\n>> > + - name: AfTriggerStart\n>> > + value: 0\n>> > + description: Start an AF scan. Ignored if a scan is in progress.\n>> > + - name: AfTriggerCancel\n>> > + value: 1\n>> > + description: Cancel an AF scan. Ingored if no scan is in progress.\n>>\n>> Does cancelling a scan make the lens stay at its current position ? Or\n>> should it be reset ?\n\nStay at the current position. It's your (or the application's) choice\nwhether to reset the lens. I'll make that clearer.\n\n>>\n>> > +\n>> > + - AfPause:\n>> > + type: int32_t\n>> > + draft: true\n>> > + description: |\n>> > + This control has no effect except when in continuous autofocus mode\n>> > + (AfModeContinuous). It can be used to pause any lens movements while\n>> > + (for example) images are captured. The algorithm remains inactive\n>> > + until it is instructed to resume.\n>> > +\n>> > + enum:\n>> > + - name: AfPauseImmediate\n>> > + value: 0\n>> > + description: |\n>> > + Pause the continuous autofocus algorithm immediately, whether or\n>> > + not any kind of scan is underway. The AfState will continue to\n>> > + report whatever value it had when the control was enacted.\n>> > + - name AfPauseDeferred\n>> > + value: 1\n>> > + description: |\n>> > + Pause the continuous autofocus algorithm as soon as it is no longer\n>> > + scanning. The AfState will report AfStateFocused or AfStateFailed,\n>> > + depending on whether the final scan succeeds or not. If no scan is\n>> > + in currently progress, the algorithm will pause immediately.\n>>\n> Just to confirm. Since we removed the AftriggerIdle, I guess the two controls AfTriggerStart and AfPauseDeferred should be continuously set until the state becomes focused or failed? If so, is it better to mention it in the description?\n\nI imagined that these would be \"one-shot\" things. So you only need to\nsend them once and they happen.\n\nI imagine there might also be a slight delay between something being\nin focus and that feeding back to the application, so you wouldn't\nwant the algorithm to think \"oh, I'm being told to scan again even\nthough I've only just finished!\"\n\n> For AfPauseImmediate, should it only report the state as failed when it's scanning and reset?\n\nSo I think if it was \"scanning\" and gets \"AfPauseImmediate\", the state\nremains \"scanning\". If it was \"focused\" when it gets\n\"AfPauseImmediate\", then it stays \"focused\", and so on. The idea is\nthat this means you can be sure what state it was in when you sent\n\"AfPauseImmediate\". If we were to change the state you couldn't be\nsure whether it was focused or not. This could give an application the\nchance to put up a \"picture might be blurry\" message, for example.\n\n>\n>>\n>> Alignment broken ?\n>>\n>> > + - name: AfPauseResume\n>> > + value: 2\n>> > + description: |\n>>\n>> Alignment broken ?\n>>\n>> > + Resume continous autofocus operation. The algorithm starts again\n>> > + from exactly where it left off, with AfState unchanged (one of\n>> > + AfStateFocused, AfStateFailed or following AfPauseImmediate it\n>> > + might also have been in the AfStateScanning state).\n>> > +\n>> > + - LensPosition:\n>> > + type: int32_t\n>> > + draft: true\n>> > + description: |\n>> > + Acts as a control to instruct the lens to move to a particular position\n>> > + and also reports back the position of the lens for each frame.\n>> > +\n>> > + The units are determined by the lens driver.\n>> > +\n>> > + The LensPosition control is ignored unless the AfMode is set to\n>> > + AfModeManual.\n>> > +\n>> > + - AfState:\n>> > + type: int32_t\n>> > + draft: true\n>> > + description: |\n>> > + Reports the current state of the AF algorithm.\n>> > + enum:\n>> > + - name: AfStateReset\n>> > + value: 0\n>> > + description: |\n>> > + The AF algorithm reports this state when:\n>> > + * It is in manual mode (AfModeManual).\n>> > + * The system has entered auto mode (AfModeAuto) but no scan\n>> > + has yet been initiated.\n>> > + * The system is in auto mode (AfModeAuto) and a scan has been\n>> > + cancelled.\n>> > + - name: AfStateScanning\n>> > + value: 1\n>> > + description: |\n>> > + AF is performing a scan. This state can be entered spontaneously\n>> > + if AfMode is set to AfModeContinuous, otherwise it requires the\n>> > + application to use the AfTrigger control to start the scan.\n>> > + - name: AfStateFocused\n>> > + value: 2\n>> > + description: |\n>> > + An AF scan has been performed and the algorithm believes the\n>> > + scene is in focus.\n>> > + - name: AfStateFailed\n>> > + value: 3\n>> > + description: |\n>> > + An AF scan has been performed but the algorithm has not been able\n>> > + to find the best focus position.\n>>\n>> I confirm my wish of having a graphical state machine :-).\n>\n> Vote +1 :-).\n\nI'll look into doing that. Do we have a preferred package? Do I have\nto turn it into Ascii Art? :)\n\nThanks for all the feedback!\n\nDavid\n\n>>\n>>\n>> Great work, thanks for it !\n>> JM\n>>\n>> > +\n>> > ...","headers":{"Return-Path":"","X-Original-To":"parsemail@patchwork.libcamera.org","Delivered-To":"parsemail@patchwork.libcamera.org","Received":["from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id 52DC4BF415\n\tfor ;\n\tTue, 15 Mar 2022 16:34:38 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id B9D8E610F8;\n\tTue, 15 Mar 2022 17:34:37 +0100 (CET)","from mail-wr1-x429.google.com (mail-wr1-x429.google.com\n\t[IPv6:2a00:1450:4864:20::429])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id C04B0604DA\n\tfor ;\n\tTue, 15 Mar 2022 17:34:35 +0100 (CET)","by mail-wr1-x429.google.com with SMTP id j17so29956888wrc.0\n\tfor ;\n\tTue, 15 Mar 2022 09:34:35 -0700 (PDT)"],"DKIM-Signature":["v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org;\n\ts=mail; t=1647362077;\n\tbh=7uS3ILDqUOD2u0XmsImBR59fi5PNP4zyOelxAvRdM/E=;\n\th=References:In-Reply-To:Date:To:Subject:List-Id:List-Unsubscribe:\n\tList-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc:\n\tFrom;\n\tb=temwElPdXE/nqJN13QJfIibaawcvlh05FWNn+SU/QSnnpD270JYwZj831lfvvZ4lS\n\ttBIdqt7LZRPbsl9FWqd+8KWY8lv+JvUNmpcKLuo10s648LOBeB1cO6hCuAglU6s1Ox\n\tmJRApEmxSjeUDqD2OJC/11HiXlUa2mhYBNel3iZVGR2UJatdX1TbZQS0zNa132Rja5\n\tSIODFWsZDkJgNhq52CYe7r6+4L0KNhoGkBrsAPHbTeWIR0bymhZZcHkqzR/myRclz5\n\tmeS5pm11c7zGJKu78/nM8hoFK52cWaV90TFP9O+sOdCuPa0dX+Rl6ymlkeIaEwcEyB\n\tqqCv8W6yUzbPQ==","v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=raspberrypi.com; s=google;\n\th=mime-version:references:in-reply-to:from:date:message-id:subject:to\n\t:cc; bh=nJVuyTj9M1Kj0SRklMb0tWsFp6wK7cQzDKSEWxCxLRA=;\n\tb=TNO9bkHGGXo9EPOE1EHYn7ByVnMKrmiHw0Si5ftR4tVWkwUZMdANSSKKp4imp8+mDG\n\tiMC47tmukbb8Q7CxUYqvHoa1cSZM5PjOxPW3vl1Nylr2WdilDlNFtQsElIYrUYWruRoX\n\tvwEaixDy1OU0MJH2QcgisqMSKroqjSS7E9qOMF3ZFywtprZiTB5asrLfwuOoavd6xSzS\n\tIV0K8a0NFVrrQeOtZsAWvWC9iTk2OTm6D/EJAaMp3tw5t+56HXwOyIKIJIHtwc2iHNsz\n\tnTb87PlLJQdl0E9abZ/M2AMmJhM9XF6BB0if8WmyIezq3U5/S9uc8fLeH87QKnCKW/Rx\n\tCo4w=="],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (2048-bit key; \n\tunprotected) header.d=raspberrypi.com\n\theader.i=@raspberrypi.com\n\theader.b=\"TNO9bkHG\"; dkim-atps=neutral","X-Google-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=1e100.net; s=20210112;\n\th=x-gm-message-state:mime-version:references:in-reply-to:from:date\n\t:message-id:subject:to:cc;\n\tbh=nJVuyTj9M1Kj0SRklMb0tWsFp6wK7cQzDKSEWxCxLRA=;\n\tb=to9+FRe1jU7TLKLQVT2MLDA0F0idhpRNGyuNHPa6Mrz8H3Ofi5SMDM91iFdr+CnTX5\n\tNs+/Z+E/EwrlZR/UJWF3qr6uSRGtiTsl494Lx8z135eOtt3Wye9YT7TzbyIfCA9KEhPg\n\toQcq0J8usDaWdmN7uuIdgYKE6a2MZFu528T9eEtb+iVIs3k7dFaUQYNmLzDmeBvmPgQX\n\tf67mybHOKwJAm6aiWUp+K50mt3RT8CjyZoeZfdPv+DlUxDq80U8/9fIP6XXaq2kiU9O6\n\tSCrYK0zKCeQLlbdZOq+yUuJic9RPZNVX7QHBwtklmyk+5tNEiJ1qskmjlusRzuek69f7\n\t1hUw==","X-Gm-Message-State":"AOAM531Uy0NoP95ACMCWjl/09k/fQzyiDO5zbpagWloC7IeBLJJEYWhH\n\t5tGb7EX1/QfvCqm3bNl7nx6dV+VrPDhq05OiXgvXaA==","X-Google-Smtp-Source":"ABdhPJygcoYlJs0GD1qsOFRNr71b95XNZqQwtflKSA5YDHk8cfO0uJErfuOaQji7BG7BWXsbcQuqO36MW1ulazmxgxk=","X-Received":"by 2002:adf:a198:0:b0:1f0:2477:3b79 with SMTP id\n\tu24-20020adfa198000000b001f024773b79mr20336299wru.24.1647362075211;\n\tTue, 15 Mar 2022 09:34:35 -0700 (PDT)","MIME-Version":"1.0","References":"<20220310120540.15296-1-david.plowman@raspberrypi.com>\n\t<20220310120540.15296-2-david.plowman@raspberrypi.com>\n\t<45e6a2c9-fb59-4877-a639-f9931091529f@ideasonboard.com>\n\t","In-Reply-To":"","Date":"Tue, 15 Mar 2022 16:34:23 +0000","Message-ID":"","To":"Hanlin Chen ","Content-Type":"text/plain; charset=\"UTF-8\"","Subject":"Re: [libcamera-devel] [PATCH 1/1] libcamera: controls: Controls for\n\tdriving AF (autofocus) algorithms","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","From":"David Plowman via libcamera-devel ","Reply-To":"David Plowman ","Cc":"libcamera devel ","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}},{"id":22289,"web_url":"https://patchwork.libcamera.org/comment/22289/","msgid":"","date":"2022-03-16T10:19:26","subject":"Re: [libcamera-devel] [PATCH 1/1] libcamera: controls: Controls for\n\tdriving AF (autofocus) algorithms","submitter":{"id":97,"url":"https://patchwork.libcamera.org/api/people/97/","name":"Nicolas Dufresne via libcamera-devel","email":"libcamera-devel@lists.libcamera.org"},"content":"On Wed, Mar 16, 2022 at 12:34 AM David Plowman <\ndavid.plowman@raspberrypi.com> wrote:\n\n> Hi Hanlin, Jean-Michel, everyone\n>\n> On Mon, 14 Mar 2022 at 11:06, Hanlin Chen wrote:\n> >\n> > Hi David, Thanks for the great patch!\n> >\n> > On Thu, Mar 10, 2022 at 10:53 PM Jean-Michel Hautbois <\n> jeanmichel.hautbois@ideasonboard.com> wrote:\n> >>\n> >> Hi David,\n> >>\n> >> Thanks for the patch !\n> >>\n> >> On 10/03/2022 13:05, David Plowman via libcamera-devel wrote:\n> >> > This patch describes a series of controls that allow applications to\n> >> > drive AF algorithms:\n> >> >\n> >> > AfMode - manual, auto or continuous\n> >> > AfRange - full, macro or normal\n> >> > AfSpeed - fast or slow\n> >> > AfWindow - AF window locations\n> >> > AfTrigger - start (trigger an AF scan) or cancel\n> >> > AfPause - pause continuous AF\n> >> > LensPosition - position of lens from lens driver\n> >> > AfState - reset, scanning, focused or failed\n> >> > ---\n> >> > src/libcamera/control_ids.yaml | 271\n> +++++++++++++++++++++++++--------\n> >> > 1 file changed, 211 insertions(+), 60 deletions(-)\n> >> >\n> >> > diff --git a/src/libcamera/control_ids.yaml\n> b/src/libcamera/control_ids.yaml\n> >> > index 9d4638ae..89636d82 100644\n> >> > --- a/src/libcamera/control_ids.yaml\n> >> > +++ b/src/libcamera/control_ids.yaml\n> >> > @@ -406,27 +406,6 @@ controls:\n> >> > The camera will cancel any active or completed metering\n> sequence.\n> >> > The AE algorithm is reset to its initial state.\n> >> >\n> >> > - - AfTrigger:\n> >> > - type: int32_t\n> >> > - draft: true\n> >> > - description: |\n> >> > - Control for AF trigger. Currently identical to\n> >> > - ANDROID_CONTROL_AF_TRIGGER.\n> >> > -\n> >> > - Whether the camera device will trigger autofocus for this\n> request.\n> >> > - enum:\n> >> > - - name: AfTriggerIdle\n> >> > - value: 0\n> >> > - description: The trigger is idle.\n> >> > - - name: AfTriggerStart\n> >> > - value: 1\n> >> > - description: The AF routine is started by the camera.\n> >> > - - name: AfTriggerCancel\n> >> > - value: 2\n> >> > - description: |\n> >> > - The camera will cancel any active trigger and the AF\n> routine is\n> >> > - reset to its initial state.\n> >> > -\n> >> > - NoiseReductionMode:\n> >> > type: int32_t\n> >> > draft: true\n> >> > @@ -507,45 +486,6 @@ controls:\n> >> > The AE algorithm has started a pre-capture metering\n> session.\n> >> > \\sa AePrecaptureTrigger\n> >> >\n> >> > - - AfState:\n> >> > - type: int32_t\n> >> > - draft: true\n> >> > - description: |\n> >> > - Control to report the current AF algorithm state. Currently\n> identical to\n> >> > - ANDROID_CONTROL_AF_STATE.\n> >> > -\n> >> > - Current state of the AF algorithm.\n> >> > - enum:\n> >> > - - name: AfStateInactive\n> >> > - value: 0\n> >> > - description: The AF algorithm is inactive.\n> >> > - - name: AfStatePassiveScan\n> >> > - value: 1\n> >> > - description: |\n> >> > - AF is performing a passive scan of the scene in\n> continuous\n> >> > - auto-focus mode.\n> >> > - - name: AfStatePassiveFocused\n> >> > - value: 2\n> >> > - description: |\n> >> > - AF believes the scene is in focus, but might restart\n> scanning.\n> >> > - - name: AfStateActiveScan\n> >> > - value: 3\n> >> > - description: |\n> >> > - AF is performing a scan triggered by an AF trigger\n> request.\n> >> > - \\sa AfTrigger\n> >> > - - name: AfStateFocusedLock\n> >> > - value: 4\n> >> > - description: |\n> >> > - AF believes has focused correctly and has locked focus.\n> >> > - - name: AfStateNotFocusedLock\n> >> > - value: 5\n> >> > - description: |\n> >> > - AF has not been able to focus and has locked.\n> >> > - - name: AfStatePassiveUnfocused\n> >> > - value: 6\n> >> > - description: |\n> >> > - AF has completed a passive scan without finding focus.\n> >> > -\n> >> > - AwbState:\n> >> > type: int32_t\n> >> > draft: true\n> >> > @@ -690,4 +630,215 @@ controls:\n> >> > value. All of the custom test patterns will be static\n> (that is the\n> >> > raw image must not vary from frame to frame).\n> >> >\n> >> > + - AfMode:\n> >> > + type: int32_t\n> >>\n> >> Same open question for almost all: why int32_t and not uint8_t ?\n> >> We won't have negative values ? Maybe is it yaml ?\n>\n> The file only seems to contain int32_ts so that's what I copied. Am I\n> allowed other things?\n>\n> >>\n> >> > + draft: true\n> >> > + description: |\n> >> > + Control to set the mode of the AF (autofocus) algorithm.\n> Applications\n> >> > + are allowed to set a new mode, and to send additional\n> controls for\n> >> > + that new mode, in the same request.\n> >> > + enum:\n> >> > + - name: AfModeManual\n> >> > + value: 0\n> >> > + description: |\n> >> > + The AF algorithm is in manual mode. In this mode it will\n> never\n> >> > + perform any action nor move the lens of its own accord.\n> The only\n> >> > + autofocus controls that have an immediate effect are AfMode\n> (to\n> >> > + switch out of manual mode) and LensPosition (so that the\n> lens can\n> >> > + be moved \"manually\").\n> >>\n> >> Alignment changed in the paragraph. I wonder if the part \"The only\n> >> autofocus [...] \"manually\").\" should be moved in the top description ?\n>\n> Thanks, I'll fix this up and all the ones below...\n>\n> >>\n> >> > +\n> >> > + In this mode the AfState will always report AfStateReset.\n> >> > + - name: AfModeAuto\n> >> > + value: 1\n> >> > + description: |\n> >> > + The AF algorithm is in auto mode. This means that the\n> algorithm\n> >> > + will never move the lens or change state unless the\n> AfTrigger\n> >> > + control is used. The AfTrigger control can be used to\n> initiate a\n> >> > + focus scan, the results of which will also be reported\n> by AfState.\n> >> > +\n> >> > + If the autofocus algorithm is moved from AfModeAuto to\n> another\n> >> > + mode while a scan is in progress, the scan is cancelled\n> >> > + immediately, without waiting for the scan to finish.\n> >> > +\n> >> > + When first entering this mode the AfState will report\n> >>\n> >> Alignment broken ?\n> >>\n> >> > + AfStateReset. When a trigger control is sent, AfState will\n> >> > + report AfStateScanning for a period before spontaneously\n> >> > + changing to AfStateFocused or AfStateFailed, depending on\n> the\n> >> > + outcome of the scan. It will remain in this state until\n> another\n> >> > + scan is initiated by the AfTrigger control. If a scan is\n> >> > + cancelled (without changing to another mode), AfState will\n> return\n> >> > + to AfStateReset.\n> >> > + - name: AfModeContinuous\n> >> > + value: 2\n> >> > + description: |\n> >> > + The AF algorithm is in continuous mode. This means that\n> the lens\n> >> > + can re-start a scan spontaneously at any moment, without\n> any user\n> >> > + intervention. The AfState still reports whether the\n> algorithm is\n> >> > + currently scanning or not, though the application has no\n> ability\n> >> > + to initiate or cancel scans, nor move the lens for\n> itself.\n> >> > +\n> >>\n> >> Alignement broken ?\n> >>\n> >> > + When set to AfModeContinuous, the system will immediately\n> initiate\n> >> > + a scan so AfState will report AfStateScanning, and will\n> settle on\n> >> > + one of AfStateFocused or AfStateFailed, depending on the\n> scan\n> >> > + result.\n> >> > +\n> >> > + The continuous autofocus behaviour can be paused with the\n> >> > + AfPause control. Pausing the algorithm does not change the\n> value\n> >> > + reported by AfState, so that applications can determine the\n> >> > + state of the algorithm when the pause control took effect.\n> Once\n> >> > + un-paused (\"resumed\"), the algorithm starts again from\n> exactly\n> >> > + where it left off when it paused.\n> >\n> > An open question:\n> > Should we make Macro and Continuous mandatory? Or they can be optional\n> depending on the algorithm implementation?\n>\n> I'd certainly like CAF (Continuous AF) to be optional. It's a feature\n> you could choose not to implement as it's quite a lot of work, and\n> hard to make work well (especially without PDAF).\n>\n> Something like the \"Macro\" range... don't mind. We could make it\n> optional, or define it to be the same as \"Normal\". What do people\n> think?\n>\n> >>\n> >>\n> >> I find this difficult to follow without having a state machine in some\n> >> drawn way... Is it something we could include in the documentation ?\n> >> Seeing which Control changes to which one, which states are then\n> >> triggered, etc. ?\n> >>\n> >> > +\n> >> > + - AfRange:\n> >> > + type: int32_t\n> >> > + draft: true\n> >> > + description: |\n> >> > + Control to set the range of focus distances that is scanned.\n> >> > + enum:\n> >> > + - name: AfRangeNormal\n> >> > + value: 0\n> >> > + description: |\n> >> > + A wide range of focus distances is scanned, all the way from\n> >> > + infinity down to close distances, though depending on the\n> >> > + implementation, possibly not including the very closest\n> macro\n> >> > + positions.\n> >>\n> >> Alignment broken ?\n> >>\n> >> > + - name: AfRangeMacro\n> >> > + value: 1\n> >> > + description: Only close distances are scanned.\n> >> > + - name: AfRangeFull\n> >> > + value: 2\n> >> > + description: |\n> >> > + The full range of focus distances is scanned just as with\n> >> > + AfRangeNormal but this time including the very closest macro\n> >> > + positions.\n> >> > +\n> >> > + - AfSpeed:\n> >> > + type: int32_t\n> >> > + draft: true\n> >> > + description: |\n> >> > + Control that determines whether the AF algorithm is to move\n> the lens\n> >> > + as quickly as possible or more steadily. For example, during\n> video\n> >> > + recording it may be desirable not to move the lens too\n> abruptly, but\n> >> > + when in a preview mode (waiting for a still capture) it may\n> be\n> >> > + helpful to move the lens as quickly as is reasonably\n> possible.\n> >> > + enum:\n> >> > + - name: AfSpeedNormal\n> >> > + value: 0\n> >> > + description: Move the lens at its usual speed.\n> >> > + - name: AfSpeedFast\n> >> > + value: 1\n> >> > + description: Move the lens more quickly.\n> >> > +\n> >>\n> >> Can we somehow configure this speed ?\n>\n> Good question. You could imagine a continuous value here, though that\n> does start to force the developer to do more work, and testing gets\n> harder. So I feel slightly inclined to leave this as a binary choice,\n> but am certainly open to persuasion.\n>\n> >>\n> >> > + - AfWindow:\n> >> > + type: Rectangle\n> >> > + draft: true\n> >> > + description: |\n> >> > + Sets the focus windows used by the AF algorithm. The units\n> used express\n> >> s/windows/window ?\n> >> > + a proportion of the ScalerCrop control (or if unavailable,\n> of the entire\n> >> > + image), as u0.16 format numbers.\n> >> > +\n> >> > + In order to be activated, a rectangle must be programmed\n> with non-zero\n> >> > + width and height. If no rectangles are programmed in this\n> way, then the\n> >> > + system will choose its own single default window in the\n> centre of the\n> >> > + image.\n> >> > +\n> >> > + The details of how the windows are used are platform\n> dependent. We note\n> >> > + that when there is more than one AF window, a typical\n> implementation\n> >> > + might find the optimal focus position for each one and\n> finally select\n> >> > + the window closest to the camera.\n> >>\n> >> Alignment broken ?\n> >>\n> >> > +\n> >> > + size: [platform dependent]\n> >> > +\n> >> > + - AfTrigger:\n> >> > + type: int32_t\n> >> > + draft: true\n> >> > + description: |\n> >> > + This control starts an autofocus scan when AfMode is set to\n> AfModeAuto,\n> >> > + and can also be used to terminate a scan early.\n> >> > +\n> >> > + It is ignored if AfMode is set to AfModeContinuous.\n> >> > +\n> >> > + enum:\n> >> > + - name: AfTriggerStart\n> >> > + value: 0\n> >> > + description: Start an AF scan. Ignored if a scan is in\n> progress.\n> >> > + - name: AfTriggerCancel\n> >> > + value: 1\n> >> > + description: Cancel an AF scan. Ingored if no scan is in\n> progress.\n> >>\n> >> Does cancelling a scan make the lens stay at its current position ? Or\n> >> should it be reset ?\n>\n> Stay at the current position. It's your (or the application's) choice\n> whether to reset the lens. I'll make that clearer.\n>\n> >>\n> >> > +\n> >> > + - AfPause:\n> >> > + type: int32_t\n> >> > + draft: true\n> >> > + description: |\n> >> > + This control has no effect except when in continuous\n> autofocus mode\n> >> > + (AfModeContinuous). It can be used to pause any lens\n> movements while\n> >> > + (for example) images are captured. The algorithm remains\n> inactive\n> >> > + until it is instructed to resume.\n> >> > +\n> >> > + enum:\n> >> > + - name: AfPauseImmediate\n> >> > + value: 0\n> >> > + description: |\n> >> > + Pause the continuous autofocus algorithm immediately,\n> whether or\n> >> > + not any kind of scan is underway. The AfState will\n> continue to\n> >> > + report whatever value it had when the control was\n> enacted.\n> >> > + - name AfPauseDeferred\n> >> > + value: 1\n> >> > + description: |\n> >> > + Pause the continuous autofocus algorithm as soon as it\n> is no longer\n> >> > + scanning. The AfState will report AfStateFocused or\n> AfStateFailed,\n> >> > + depending on whether the final scan succeeds or not. If\n> no scan is\n> >> > + in currently progress, the algorithm will pause immediately.\n> >>\n> > Just to confirm. Since we removed the AftriggerIdle, I guess the two\n> controls AfTriggerStart and AfPauseDeferred should be continuously set\n> until the state becomes focused or failed? If so, is it better to mention\n> it in the description?\n>\n> I imagined that these would be \"one-shot\" things. So you only need to\n> send them once and they happen.\n>\n> I imagine there might also be a slight delay between something being\n> in focus and that feeding back to the application, so you wouldn't\n> want the algorithm to think \"oh, I'm being told to scan again even\n> though I've only just finished!\"\n>\n> > For AfPauseImmediate, should it only report the state as failed when\n> it's scanning and reset?\n>\n> So I think if it was \"scanning\" and gets \"AfPauseImmediate\", the state\n> remains \"scanning\". If it was \"focused\" when it gets\n> \"AfPauseImmediate\", then it stays \"focused\", and so on. The idea is\n> that this means you can be sure what state it was in when you sent\n> \"AfPauseImmediate\". If we were to change the state you couldn't be\n> sure whether it was focused or not. This could give an application the\n> chance to put up a \"picture might be blurry\" message, for example.\n>\n> >\n> >>\n> >> Alignment broken ?\n> >>\n> >> > + - name: AfPauseResume\n> >> > + value: 2\n> >> > + description: |\n> >>\n> >> Alignment broken ?\n> >>\n> >> > + Resume continous autofocus operation. The algorithm starts\n> again\n> >> > + from exactly where it left off, with AfState unchanged (one\n> of\n> >> > + AfStateFocused, AfStateFailed or following AfPauseImmediate\n> it\n> >> > + might also have been in the AfStateScanning state).\n> >> > +\n> >> > + - LensPosition:\n> >> > + type: int32_t\n> >> > + draft: true\n> >> > + description: |\n> >> > + Acts as a control to instruct the lens to move to a\n> particular position\n> >> > + and also reports back the position of the lens for each\n> frame.\n> >> > +\n> >> > + The units are determined by the lens driver.\n> >> > +\n> >> > + The LensPosition control is ignored unless the AfMode is\n> set to\n> >> > + AfModeManual.\n> >> > +\n> >> > + - AfState:\n> >> > + type: int32_t\n> >> > + draft: true\n> >> > + description: |\n> >> > + Reports the current state of the AF algorithm.\n> >> > + enum:\n> >> > + - name: AfStateReset\n> >> > + value: 0\n> >> > + description: |\n> >> > + The AF algorithm reports this state when:\n> >> > + * It is in manual mode (AfModeManual).\n> >> > + * The system has entered auto mode (AfModeAuto)\n> but no scan\n> >> > + has yet been initiated.\n> >> > + * The system is in auto mode (AfModeAuto) and a\n> scan has been\n> >> > + cancelled.\n> >> > + - name: AfStateScanning\n> >> > + value: 1\n> >> > + description: |\n> >> > + AF is performing a scan. This state can be entered\n> spontaneously\n> >> > + if AfMode is set to AfModeContinuous, otherwise it\n> requires the\n> >> > + application to use the AfTrigger control to start the\n> scan.\n> >> > + - name: AfStateFocused\n> >> > + value: 2\n> >> > + description: |\n> >> > + An AF scan has been performed and the algorithm\n> believes the\n> >> > + scene is in focus.\n> >> > + - name: AfStateFailed\n> >> > + value: 3\n> >> > + description: |\n> >> > + An AF scan has been performed but the algorithm has\n> not been able\n> >> > + to find the best focus position.\n> >>\n> >> I confirm my wish of having a graphical state machine :-).\n> >\n> > Vote +1 :-).\n>\n> I'll look into doing that. Do we have a preferred package? Do I have\n> to turn it into Ascii Art? :)\n>\nHow about a state transition table? We could prove its completeness and it\nmay be easier for rst documentation.\n\n>\n> Thanks for all the feedback!\n>\n> David\n>\n> >>\n> >>\n> >> Great work, thanks for it !\n> >> JM\n> >>\n> >> > +\n> >> > ...\n>","headers":{"Return-Path":"","X-Original-To":"parsemail@patchwork.libcamera.org","Delivered-To":"parsemail@patchwork.libcamera.org","Received":["from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id 3C845BDE17\n\tfor ;\n\tWed, 16 Mar 2022 10:19:42 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 87E3E6118A;\n\tWed, 16 Mar 2022 11:19:41 +0100 (CET)","from mail-ot1-x32d.google.com (mail-ot1-x32d.google.com\n\t[IPv6:2607:f8b0:4864:20::32d])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 2C695601F5\n\tfor ;\n\tWed, 16 Mar 2022 11:19:40 +0100 (CET)","by mail-ot1-x32d.google.com with SMTP id\n\te25-20020a0568301e5900b005b236d5d74fso1144283otj.0\n\tfor ;\n\tWed, 16 Mar 2022 03:19:40 -0700 (PDT)"],"DKIM-Signature":["v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org;\n\ts=mail; t=1647425981;\n\tbh=WYsqV0VDLSbq/Z2zdpts9eM6Fk0QB0TZZasJdQTF9C8=;\n\th=References:In-Reply-To:Date:To:Subject:List-Id:List-Unsubscribe:\n\tList-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc:\n\tFrom;\n\tb=oQ+YI5WH/MwBCbuwsJt14U9VNUHsYSA3msxXzL8zo6zo6xaqX7mPvF5axnH6kNfsX\n\t8qur5sMkHGLnG2FwCx4VgMH/MK1zj2vyxO4PkBCJL8VsPOLqVrcHOdwYbgc/QHTqx7\n\t2CUt2VO+HrvU7D/9mRghBXaKOjH7U4s5f12Gv9/tCR5YNyRarNMpHAXIHRI8tRJpxL\n\tgTbJHZvf+REZ5CG8YZ3Mc0TDCsqeGmEJPssrQr14ndVaHiDXMHRxzSdMgKoaLT6hKG\n\tPlMlFZ6O4bCS3ee2buqRugCWQYqwXHmaj49CayFHzYZqtVvLfA45iTGNcpBRauc1yq\n\tHOubIeVKoOW4A==","v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org;\n\ts=google; \n\th=mime-version:references:in-reply-to:from:date:message-id:subject:to\n\t:cc; bh=6hpIrj6yv1S+G42eGgFToHMeP9S9scuz4DJeHbbxvug=;\n\tb=fix/21BX/MhJ+kGUQurMaApbSfWNQ7XvUIHzPON+IzywxIxPdxcX+VhbCFdZGZiHmg\n\teLyC8PS/Ms3JgpVadifI4uMTTC/ABZ6LLr5GQ+A71e2EmZNmjYDODoe7hkMdKGiyOiQb\n\tXtXsF31YRBNg/J1lxQqddFxoRNgKR57kF+InQ="],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key; \n\tunprotected) header.d=chromium.org\n\theader.i=@chromium.org header.b=\"fix/21BX\"; \n\tdkim-atps=neutral","X-Google-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=1e100.net; s=20210112;\n\th=x-gm-message-state:mime-version:references:in-reply-to:from:date\n\t:message-id:subject:to:cc;\n\tbh=6hpIrj6yv1S+G42eGgFToHMeP9S9scuz4DJeHbbxvug=;\n\tb=2+JQeGwVURdf35E2Ke3lCp8mlkQr+M4nJjuu2r+V6c4UCdGnfE/zNNX6M40j72C7HJ\n\ty/p9tnfYCwTTDpHvRyJ5cdmLbmv6paF9SCKeZq4EoQ4ortL+703Idtwg/dJvDHRVg0u1\n\tiynkShHAy2IIL3On51zh7sAGDvCFotfLpmsyYGeJtdUvsPs5TKhKl9ZqFFlVcBuFECNo\n\tL2Ly0bVKeJYbI8huJ0fNY92S2+KjFVk+NVjodQuEMcnu9NCWNahG/Ttb/3DJ9AqgFmaP\n\tPeYD5kTel4m4TeHADi24RwpxxW2HcJP1LX32EeetaLVuGnSBe989upKKgre+8FyLFpO3\n\tM4xg==","X-Gm-Message-State":"AOAM531CyvpSO80F7ROm2QE3A9qhRYh4L64suwzoZSuGwfQw9WFu5GJu\n\tOqbPfwNCCf4EOjqmnyeHKvTUURIHPMqy6LWadJUX+GxPJPlt4Q==","X-Google-Smtp-Source":"ABdhPJybiObIAGBUPHqGKfWs00N92EnTh0B5j41stYyXTzIhQqiv/A6fLvz7oVhUvBHcHG9Bw4UiBW/Fkt6gZShBNq4=","X-Received":"by 2002:a05:6830:c5:b0:5c9:7a04:b313 with SMTP id\n\tx5-20020a05683000c500b005c97a04b313mr1722088oto.176.1647425977522;\n\tWed, 16 Mar 2022 03:19:37 -0700 (PDT)","MIME-Version":"1.0","References":"<20220310120540.15296-1-david.plowman@raspberrypi.com>\n\t<20220310120540.15296-2-david.plowman@raspberrypi.com>\n\t<45e6a2c9-fb59-4877-a639-f9931091529f@ideasonboard.com>\n\t\n\t","In-Reply-To":"","Date":"Wed, 16 Mar 2022 18:19:26 +0800","Message-ID":"","To":"David Plowman ","Content-Type":"multipart/alternative; boundary=\"0000000000002f3d5005da53403b\"","Subject":"Re: [libcamera-devel] [PATCH 1/1] libcamera: controls: Controls for\n\tdriving AF (autofocus) algorithms","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","From":"Hanlin Chen via libcamera-devel ","Reply-To":"Hanlin Chen ","Cc":"libcamera devel ","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}},{"id":22290,"web_url":"https://patchwork.libcamera.org/comment/22290/","msgid":"<164742744881.11309.1637613189169577217@Monstersaurus>","date":"2022-03-16T10:44:08","subject":"Re: [libcamera-devel] [PATCH 1/1] libcamera: controls: Controls for\n\tdriving AF (autofocus) algorithms","submitter":{"id":97,"url":"https://patchwork.libcamera.org/api/people/97/","name":"Nicolas Dufresne via libcamera-devel","email":"libcamera-devel@lists.libcamera.org"},"content":"Quoting Hanlin Chen via libcamera-devel (2022-03-16 10:19:26)\n> On Wed, Mar 16, 2022 at 12:34 AM David Plowman <\n> david.plowman@raspberrypi.com> wrote:\n> \n> > Hi Hanlin, Jean-Michel, everyone\n> >\n> > On Mon, 14 Mar 2022 at 11:06, Hanlin Chen wrote:\n> > >\n> > > Hi David, Thanks for the great patch!\n> > >\n> > > On Thu, Mar 10, 2022 at 10:53 PM Jean-Michel Hautbois <\n> > jeanmichel.hautbois@ideasonboard.com> wrote:\n> > >>\n> > >> Hi David,\n> > >>\n> > >> Thanks for the patch !\n> > >>\n> > >> On 10/03/2022 13:05, David Plowman via libcamera-devel wrote:\n> > >> > This patch describes a series of controls that allow applications to\n> > >> > drive AF algorithms:\n> > >> >\n> > >> > AfMode - manual, auto or continuous\n> > >> > AfRange - full, macro or normal\n> > >> > AfSpeed - fast or slow\n> > >> > AfWindow - AF window locations\n> > >> > AfTrigger - start (trigger an AF scan) or cancel\n> > >> > AfPause - pause continuous AF\n> > >> > LensPosition - position of lens from lens driver\n> > >> > AfState - reset, scanning, focused or failed\n> > >> > ---\n> > >> > src/libcamera/control_ids.yaml | 271\n> > +++++++++++++++++++++++++--------\n> > >> > 1 file changed, 211 insertions(+), 60 deletions(-)\n> > >> >\n> > >> > diff --git a/src/libcamera/control_ids.yaml\n> > b/src/libcamera/control_ids.yaml\n> > >> > index 9d4638ae..89636d82 100644\n> > >> > --- a/src/libcamera/control_ids.yaml\n> > >> > +++ b/src/libcamera/control_ids.yaml\n> > >> > @@ -406,27 +406,6 @@ controls:\n> > >> > The camera will cancel any active or completed metering\n> > sequence.\n> > >> > The AE algorithm is reset to its initial state.\n> > >> >\n> > >> > - - AfTrigger:\n> > >> > - type: int32_t\n> > >> > - draft: true\n> > >> > - description: |\n> > >> > - Control for AF trigger. Currently identical to\n> > >> > - ANDROID_CONTROL_AF_TRIGGER.\n> > >> > -\n> > >> > - Whether the camera device will trigger autofocus for this\n> > request.\n> > >> > - enum:\n> > >> > - - name: AfTriggerIdle\n> > >> > - value: 0\n> > >> > - description: The trigger is idle.\n> > >> > - - name: AfTriggerStart\n> > >> > - value: 1\n> > >> > - description: The AF routine is started by the camera.\n> > >> > - - name: AfTriggerCancel\n> > >> > - value: 2\n> > >> > - description: |\n> > >> > - The camera will cancel any active trigger and the AF\n> > routine is\n> > >> > - reset to its initial state.\n> > >> > -\n> > >> > - NoiseReductionMode:\n> > >> > type: int32_t\n> > >> > draft: true\n> > >> > @@ -507,45 +486,6 @@ controls:\n> > >> > The AE algorithm has started a pre-capture metering\n> > session.\n> > >> > \\sa AePrecaptureTrigger\n> > >> >\n> > >> > - - AfState:\n> > >> > - type: int32_t\n> > >> > - draft: true\n> > >> > - description: |\n> > >> > - Control to report the current AF algorithm state. Currently\n> > identical to\n> > >> > - ANDROID_CONTROL_AF_STATE.\n> > >> > -\n> > >> > - Current state of the AF algorithm.\n> > >> > - enum:\n> > >> > - - name: AfStateInactive\n> > >> > - value: 0\n> > >> > - description: The AF algorithm is inactive.\n> > >> > - - name: AfStatePassiveScan\n> > >> > - value: 1\n> > >> > - description: |\n> > >> > - AF is performing a passive scan of the scene in\n> > continuous\n> > >> > - auto-focus mode.\n> > >> > - - name: AfStatePassiveFocused\n> > >> > - value: 2\n> > >> > - description: |\n> > >> > - AF believes the scene is in focus, but might restart\n> > scanning.\n> > >> > - - name: AfStateActiveScan\n> > >> > - value: 3\n> > >> > - description: |\n> > >> > - AF is performing a scan triggered by an AF trigger\n> > request.\n> > >> > - \\sa AfTrigger\n> > >> > - - name: AfStateFocusedLock\n> > >> > - value: 4\n> > >> > - description: |\n> > >> > - AF believes has focused correctly and has locked focus.\n> > >> > - - name: AfStateNotFocusedLock\n> > >> > - value: 5\n> > >> > - description: |\n> > >> > - AF has not been able to focus and has locked.\n> > >> > - - name: AfStatePassiveUnfocused\n> > >> > - value: 6\n> > >> > - description: |\n> > >> > - AF has completed a passive scan without finding focus.\n> > >> > -\n> > >> > - AwbState:\n> > >> > type: int32_t\n> > >> > draft: true\n> > >> > @@ -690,4 +630,215 @@ controls:\n> > >> > value. All of the custom test patterns will be static\n> > (that is the\n> > >> > raw image must not vary from frame to frame).\n> > >> >\n> > >> > + - AfMode:\n> > >> > + type: int32_t\n> > >>\n> > >> Same open question for almost all: why int32_t and not uint8_t ?\n> > >> We won't have negative values ? Maybe is it yaml ?\n> >\n> > The file only seems to contain int32_ts so that's what I copied. Am I\n> > allowed other things?\n> >\n> > >>\n> > >> > + draft: true\n> > >> > + description: |\n> > >> > + Control to set the mode of the AF (autofocus) algorithm.\n> > Applications\n> > >> > + are allowed to set a new mode, and to send additional\n> > controls for\n> > >> > + that new mode, in the same request.\n> > >> > + enum:\n> > >> > + - name: AfModeManual\n> > >> > + value: 0\n> > >> > + description: |\n> > >> > + The AF algorithm is in manual mode. In this mode it will\n> > never\n> > >> > + perform any action nor move the lens of its own accord.\n> > The only\n> > >> > + autofocus controls that have an immediate effect are AfMode\n> > (to\n> > >> > + switch out of manual mode) and LensPosition (so that the\n> > lens can\n> > >> > + be moved \"manually\").\n> > >>\n> > >> Alignment changed in the paragraph. I wonder if the part \"The only\n> > >> autofocus [...] \"manually\").\" should be moved in the top description ?\n> >\n> > Thanks, I'll fix this up and all the ones below...\n> >\n> > >>\n> > >> > +\n> > >> > + In this mode the AfState will always report AfStateReset.\n> > >> > + - name: AfModeAuto\n> > >> > + value: 1\n> > >> > + description: |\n> > >> > + The AF algorithm is in auto mode. This means that the\n> > algorithm\n> > >> > + will never move the lens or change state unless the\n> > AfTrigger\n> > >> > + control is used. The AfTrigger control can be used to\n> > initiate a\n> > >> > + focus scan, the results of which will also be reported\n> > by AfState.\n> > >> > +\n> > >> > + If the autofocus algorithm is moved from AfModeAuto to\n> > another\n> > >> > + mode while a scan is in progress, the scan is cancelled\n> > >> > + immediately, without waiting for the scan to finish.\n> > >> > +\n> > >> > + When first entering this mode the AfState will report\n> > >>\n> > >> Alignment broken ?\n> > >>\n> > >> > + AfStateReset. When a trigger control is sent, AfState will\n> > >> > + report AfStateScanning for a period before spontaneously\n> > >> > + changing to AfStateFocused or AfStateFailed, depending on\n> > the\n> > >> > + outcome of the scan. It will remain in this state until\n> > another\n> > >> > + scan is initiated by the AfTrigger control. If a scan is\n> > >> > + cancelled (without changing to another mode), AfState will\n> > return\n> > >> > + to AfStateReset.\n> > >> > + - name: AfModeContinuous\n> > >> > + value: 2\n> > >> > + description: |\n> > >> > + The AF algorithm is in continuous mode. This means that\n> > the lens\n> > >> > + can re-start a scan spontaneously at any moment, without\n> > any user\n> > >> > + intervention. The AfState still reports whether the\n> > algorithm is\n> > >> > + currently scanning or not, though the application has no\n> > ability\n> > >> > + to initiate or cancel scans, nor move the lens for\n> > itself.\n> > >> > +\n> > >>\n> > >> Alignement broken ?\n> > >>\n> > >> > + When set to AfModeContinuous, the system will immediately\n> > initiate\n> > >> > + a scan so AfState will report AfStateScanning, and will\n> > settle on\n> > >> > + one of AfStateFocused or AfStateFailed, depending on the\n> > scan\n> > >> > + result.\n> > >> > +\n> > >> > + The continuous autofocus behaviour can be paused with the\n> > >> > + AfPause control. Pausing the algorithm does not change the\n> > value\n> > >> > + reported by AfState, so that applications can determine the\n> > >> > + state of the algorithm when the pause control took effect.\n> > Once\n> > >> > + un-paused (\"resumed\"), the algorithm starts again from\n> > exactly\n> > >> > + where it left off when it paused.\n> > >\n> > > An open question:\n> > > Should we make Macro and Continuous mandatory? Or they can be optional\n> > depending on the algorithm implementation?\n> >\n> > I'd certainly like CAF (Continuous AF) to be optional. It's a feature\n> > you could choose not to implement as it's quite a lot of work, and\n> > hard to make work well (especially without PDAF).\n> >\n> > Something like the \"Macro\" range... don't mind. We could make it\n> > optional, or define it to be the same as \"Normal\". What do people\n> > think?\n> >\n> > >>\n> > >>\n> > >> I find this difficult to follow without having a state machine in some\n> > >> drawn way... Is it something we could include in the documentation ?\n> > >> Seeing which Control changes to which one, which states are then\n> > >> triggered, etc. ?\n> > >>\n> > >> > +\n> > >> > + - AfRange:\n> > >> > + type: int32_t\n> > >> > + draft: true\n> > >> > + description: |\n> > >> > + Control to set the range of focus distances that is scanned.\n> > >> > + enum:\n> > >> > + - name: AfRangeNormal\n> > >> > + value: 0\n> > >> > + description: |\n> > >> > + A wide range of focus distances is scanned, all the way from\n> > >> > + infinity down to close distances, though depending on the\n> > >> > + implementation, possibly not including the very closest\n> > macro\n> > >> > + positions.\n> > >>\n> > >> Alignment broken ?\n> > >>\n> > >> > + - name: AfRangeMacro\n> > >> > + value: 1\n> > >> > + description: Only close distances are scanned.\n> > >> > + - name: AfRangeFull\n> > >> > + value: 2\n> > >> > + description: |\n> > >> > + The full range of focus distances is scanned just as with\n> > >> > + AfRangeNormal but this time including the very closest macro\n> > >> > + positions.\n> > >> > +\n> > >> > + - AfSpeed:\n> > >> > + type: int32_t\n> > >> > + draft: true\n> > >> > + description: |\n> > >> > + Control that determines whether the AF algorithm is to move\n> > the lens\n> > >> > + as quickly as possible or more steadily. For example, during\n> > video\n> > >> > + recording it may be desirable not to move the lens too\n> > abruptly, but\n> > >> > + when in a preview mode (waiting for a still capture) it may\n> > be\n> > >> > + helpful to move the lens as quickly as is reasonably\n> > possible.\n> > >> > + enum:\n> > >> > + - name: AfSpeedNormal\n> > >> > + value: 0\n> > >> > + description: Move the lens at its usual speed.\n> > >> > + - name: AfSpeedFast\n> > >> > + value: 1\n> > >> > + description: Move the lens more quickly.\n> > >> > +\n> > >>\n> > >> Can we somehow configure this speed ?\n> >\n> > Good question. You could imagine a continuous value here, though that\n> > does start to force the developer to do more work, and testing gets\n> > harder. So I feel slightly inclined to leave this as a binary choice,\n> > but am certainly open to persuasion.\n> >\n> > >>\n> > >> > + - AfWindow:\n> > >> > + type: Rectangle\n> > >> > + draft: true\n> > >> > + description: |\n> > >> > + Sets the focus windows used by the AF algorithm. The units\n> > used express\n> > >> s/windows/window ?\n> > >> > + a proportion of the ScalerCrop control (or if unavailable,\n> > of the entire\n> > >> > + image), as u0.16 format numbers.\n> > >> > +\n> > >> > + In order to be activated, a rectangle must be programmed\n> > with non-zero\n> > >> > + width and height. If no rectangles are programmed in this\n> > way, then the\n> > >> > + system will choose its own single default window in the\n> > centre of the\n> > >> > + image.\n> > >> > +\n> > >> > + The details of how the windows are used are platform\n> > dependent. We note\n> > >> > + that when there is more than one AF window, a typical\n> > implementation\n> > >> > + might find the optimal focus position for each one and\n> > finally select\n> > >> > + the window closest to the camera.\n> > >>\n> > >> Alignment broken ?\n> > >>\n> > >> > +\n> > >> > + size: [platform dependent]\n> > >> > +\n> > >> > + - AfTrigger:\n> > >> > + type: int32_t\n> > >> > + draft: true\n> > >> > + description: |\n> > >> > + This control starts an autofocus scan when AfMode is set to\n> > AfModeAuto,\n> > >> > + and can also be used to terminate a scan early.\n> > >> > +\n> > >> > + It is ignored if AfMode is set to AfModeContinuous.\n> > >> > +\n> > >> > + enum:\n> > >> > + - name: AfTriggerStart\n> > >> > + value: 0\n> > >> > + description: Start an AF scan. Ignored if a scan is in\n> > progress.\n> > >> > + - name: AfTriggerCancel\n> > >> > + value: 1\n> > >> > + description: Cancel an AF scan. Ingored if no scan is in\n> > progress.\n> > >>\n> > >> Does cancelling a scan make the lens stay at its current position ? Or\n> > >> should it be reset ?\n> >\n> > Stay at the current position. It's your (or the application's) choice\n> > whether to reset the lens. I'll make that clearer.\n> >\n> > >>\n> > >> > +\n> > >> > + - AfPause:\n> > >> > + type: int32_t\n> > >> > + draft: true\n> > >> > + description: |\n> > >> > + This control has no effect except when in continuous\n> > autofocus mode\n> > >> > + (AfModeContinuous). It can be used to pause any lens\n> > movements while\n> > >> > + (for example) images are captured. The algorithm remains\n> > inactive\n> > >> > + until it is instructed to resume.\n> > >> > +\n> > >> > + enum:\n> > >> > + - name: AfPauseImmediate\n> > >> > + value: 0\n> > >> > + description: |\n> > >> > + Pause the continuous autofocus algorithm immediately,\n> > whether or\n> > >> > + not any kind of scan is underway. The AfState will\n> > continue to\n> > >> > + report whatever value it had when the control was\n> > enacted.\n> > >> > + - name AfPauseDeferred\n> > >> > + value: 1\n> > >> > + description: |\n> > >> > + Pause the continuous autofocus algorithm as soon as it\n> > is no longer\n> > >> > + scanning. The AfState will report AfStateFocused or\n> > AfStateFailed,\n> > >> > + depending on whether the final scan succeeds or not. If\n> > no scan is\n> > >> > + in currently progress, the algorithm will pause immediately.\n> > >>\n> > > Just to confirm. Since we removed the AftriggerIdle, I guess the two\n> > controls AfTriggerStart and AfPauseDeferred should be continuously set\n> > until the state becomes focused or failed? If so, is it better to mention\n> > it in the description?\n> >\n> > I imagined that these would be \"one-shot\" things. So you only need to\n> > send them once and they happen.\n> >\n> > I imagine there might also be a slight delay between something being\n> > in focus and that feeding back to the application, so you wouldn't\n> > want the algorithm to think \"oh, I'm being told to scan again even\n> > though I've only just finished!\"\n> >\n> > > For AfPauseImmediate, should it only report the state as failed when\n> > it's scanning and reset?\n> >\n> > So I think if it was \"scanning\" and gets \"AfPauseImmediate\", the state\n> > remains \"scanning\". If it was \"focused\" when it gets\n> > \"AfPauseImmediate\", then it stays \"focused\", and so on. The idea is\n> > that this means you can be sure what state it was in when you sent\n> > \"AfPauseImmediate\". If we were to change the state you couldn't be\n> > sure whether it was focused or not. This could give an application the\n> > chance to put up a \"picture might be blurry\" message, for example.\n> >\n> > >\n> > >>\n> > >> Alignment broken ?\n> > >>\n> > >> > + - name: AfPauseResume\n> > >> > + value: 2\n> > >> > + description: |\n> > >>\n> > >> Alignment broken ?\n> > >>\n> > >> > + Resume continous autofocus operation. The algorithm starts\n> > again\n> > >> > + from exactly where it left off, with AfState unchanged (one\n> > of\n> > >> > + AfStateFocused, AfStateFailed or following AfPauseImmediate\n> > it\n> > >> > + might also have been in the AfStateScanning state).\n> > >> > +\n> > >> > + - LensPosition:\n> > >> > + type: int32_t\n> > >> > + draft: true\n> > >> > + description: |\n> > >> > + Acts as a control to instruct the lens to move to a\n> > particular position\n> > >> > + and also reports back the position of the lens for each\n> > frame.\n> > >> > +\n> > >> > + The units are determined by the lens driver.\n> > >> > +\n> > >> > + The LensPosition control is ignored unless the AfMode is\n> > set to\n> > >> > + AfModeManual.\n> > >> > +\n> > >> > + - AfState:\n> > >> > + type: int32_t\n> > >> > + draft: true\n> > >> > + description: |\n> > >> > + Reports the current state of the AF algorithm.\n> > >> > + enum:\n> > >> > + - name: AfStateReset\n> > >> > + value: 0\n> > >> > + description: |\n> > >> > + The AF algorithm reports this state when:\n> > >> > + * It is in manual mode (AfModeManual).\n> > >> > + * The system has entered auto mode (AfModeAuto)\n> > but no scan\n> > >> > + has yet been initiated.\n> > >> > + * The system is in auto mode (AfModeAuto) and a\n> > scan has been\n> > >> > + cancelled.\n> > >> > + - name: AfStateScanning\n> > >> > + value: 1\n> > >> > + description: |\n> > >> > + AF is performing a scan. This state can be entered\n> > spontaneously\n> > >> > + if AfMode is set to AfModeContinuous, otherwise it\n> > requires the\n> > >> > + application to use the AfTrigger control to start the\n> > scan.\n> > >> > + - name: AfStateFocused\n> > >> > + value: 2\n> > >> > + description: |\n> > >> > + An AF scan has been performed and the algorithm\n> > believes the\n> > >> > + scene is in focus.\n> > >> > + - name: AfStateFailed\n> > >> > + value: 3\n> > >> > + description: |\n> > >> > + An AF scan has been performed but the algorithm has\n> > not been able\n> > >> > + to find the best focus position.\n> > >>\n> > >> I confirm my wish of having a graphical state machine :-).\n> > >\n> > > Vote +1 :-).\n> >\n> > I'll look into doing that. Do we have a preferred package? Do I have\n> > to turn it into Ascii Art? :)\n> >\n> How about a state transition table? We could prove its completeness and it\n> may be easier for rst documentation.\n\nAscii art means the image goes right in the source, but I know it's not\neasy. https://asciiflow.com/#/ does help quite a bit for me though.\n\nIf we can fit other types of images in and correctly get them into any\nproduced documentation, I think other formats like SVG could be\nacceptable (as then they could be updated) but any non-vector image\nwould get hard to maintain and update if there are changes.\n\nOf course we expect this to be cast in stone once it's correct so maybe\nthere shouldn't be any changes ...\n\n\n\n> \n> >\n> > Thanks for all the feedback!\n> >\n> > David\n> >\n> > >>\n> > >>\n> > >> Great work, thanks for it !\n> > >> JM\n> > >>\n> > >> > +\n> > >> > ...\n> >","headers":{"Return-Path":"","X-Original-To":"parsemail@patchwork.libcamera.org","Delivered-To":"parsemail@patchwork.libcamera.org","Received":["from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id ED974BF415\n\tfor ;\n\tWed, 16 Mar 2022 10:44:13 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 37B4F604E9;\n\tWed, 16 Mar 2022 11:44:13 +0100 (CET)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id A7251601F5\n\tfor ;\n\tWed, 16 Mar 2022 11:44:11 +0100 (CET)","from pendragon.ideasonboard.com\n\t(cpc89244-aztw30-2-0-cust3082.18-1.cable.virginm.net [86.31.172.11])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 41219A67;\n\tWed, 16 Mar 2022 11:44:11 +0100 (CET)"],"DKIM-Signature":["v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org;\n\ts=mail; t=1647427453;\n\tbh=zTl7nmL01LZsiE64OHkg6fw6ZIPH7qoCVZ2DtlyX4VE=;\n\th=In-Reply-To:References:To:Date:Subject:List-Id:List-Unsubscribe:\n\tList-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc:\n\tFrom;\n\tb=HvwoP7dxECOB0qUhjx9tCzFn/NCbUYv39HrNMrxdc+9AuVnaJKwlCVc8Xq5MDHzth\n\tM3yy4xUE0IUoBviadhaq4RiwTdXtRYGaPcnhc9Snj2uLYY8mlNKHv0N0Vso2FhkuYc\n\tl6oVF0UnFomKb2LC3/vBGuR1cTGHsNFR1hqJyWfIfYfgNcqFuhJUi9jUAafVPgoK8D\n\tdvqh4c0x/DGDKEcFICz+1yFbaKoBq2sfzvQV3u2gp3T5yWyt8DZXyqB2GvHjE/aewl\n\t485Sxgjc2WEZhVCSUZyN5sEllyxT0zMIvpmk+EBrG34D+LXNo6Q9bX4983DU+10l3J\n\t1mMe0GDCES8oA==","v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1647427451;\n\tbh=zTl7nmL01LZsiE64OHkg6fw6ZIPH7qoCVZ2DtlyX4VE=;\n\th=In-Reply-To:References:Subject:From:Cc:To:Date:From;\n\tb=GlcAXQtngNj/dSxPTTuFj4opNb+K3RXbAmBKM6PAoLiRhNdK3w7r8wr0V8MuXTESu\n\tgRost0lLCdICr45CSyGfFpR5RamIlBCXxSqKm3VqlDhHQatclUZjzJf2kgGyhlUZH2\n\tY2X6Eu7KCw36xrXkClc5aWMpnqviaFwCIErtxgUw="],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key; \n\tunprotected) header.d=ideasonboard.com\n\theader.i=@ideasonboard.com\n\theader.b=\"GlcAXQtn\"; dkim-atps=neutral","Content-Type":"text/plain; charset=\"utf-8\"","MIME-Version":"1.0","Content-Transfer-Encoding":"quoted-printable","In-Reply-To":"","References":"<20220310120540.15296-1-david.plowman@raspberrypi.com>\n\t<20220310120540.15296-2-david.plowman@raspberrypi.com>\n\t<45e6a2c9-fb59-4877-a639-f9931091529f@ideasonboard.com>\n\t\n\t\n\t","To":"David Plowman ,\n\tHanlin Chen ,\n\tHanlin Chen via libcamera-devel ","Date":"Wed, 16 Mar 2022 10:44:08 +0000","Message-ID":"<164742744881.11309.1637613189169577217@Monstersaurus>","User-Agent":"alot/0.10","Subject":"Re: [libcamera-devel] [PATCH 1/1] libcamera: controls: Controls for\n\tdriving AF (autofocus) algorithms","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","From":"Kieran Bingham via libcamera-devel\n\t","Reply-To":"Kieran Bingham ","Cc":"libcamera devel ","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}}]