{"id":15591,"url":"https://patchwork.libcamera.org/api/patches/15591/?format=json","web_url":"https://patchwork.libcamera.org/patch/15591/","project":{"id":1,"url":"https://patchwork.libcamera.org/api/projects/1/?format=json","name":"libcamera","link_name":"libcamera","list_id":"libcamera_core","list_email":"libcamera-devel@lists.libcamera.org","web_url":"","scm_url":"","webscm_url":""},"msgid":"<20220331151747.19458-2-david.plowman@raspberrypi.com>","date":"2022-03-31T15:17:47","name":"[libcamera-devel,v2,1/1] libcamera: controls: Controls for driving AF (autofocus) algorithms","commit_ref":null,"pull_url":null,"state":"superseded","archived":false,"hash":"d0408bf33ca60b07dde237b50b9394e498f8f7eb","submitter":{"id":42,"url":"https://patchwork.libcamera.org/api/people/42/?format=json","name":"David Plowman","email":"david.plowman@raspberrypi.com"},"delegate":null,"mbox":"https://patchwork.libcamera.org/patch/15591/mbox/","series":[{"id":3018,"url":"https://patchwork.libcamera.org/api/series/3018/?format=json","web_url":"https://patchwork.libcamera.org/project/libcamera/list/?series=3018","date":"2022-03-31T15:17:46","name":"AF controls","version":2,"mbox":"https://patchwork.libcamera.org/series/3018/mbox/"}],"comments":"https://patchwork.libcamera.org/api/patches/15591/comments/","check":"pending","checks":"https://patchwork.libcamera.org/api/patches/15591/checks/","tags":{},"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 5CDDAC0F1B\n\tfor ;\n\tThu, 31 Mar 2022 15:17:58 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id EBC7965638;\n\tThu, 31 Mar 2022 17:17:57 +0200 (CEST)","from mail-wr1-x430.google.com (mail-wr1-x430.google.com\n\t[IPv6:2a00:1450:4864:20::430])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 3323E65631\n\tfor ;\n\tThu, 31 Mar 2022 17:17:56 +0200 (CEST)","by mail-wr1-x430.google.com with SMTP id m30so280683wrb.1\n\tfor ;\n\tThu, 31 Mar 2022 08:17:56 -0700 (PDT)","from pi4-davidp.pitowers.org\n\t([2a00:1098:3142:14:e4a2:3070:eea4:e434])\n\tby smtp.gmail.com with ESMTPSA id\n\ti1-20020a05600c400100b0038cf3371208sm7537267wmm.22.2022.03.31.08.17.54\n\t(version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n\tThu, 31 Mar 2022 08:17:54 -0700 (PDT)"],"DKIM-Signature":["v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org;\n\ts=mail; t=1648739877;\n\tbh=gKuUraS7q2Z1HYBm/qs00gqmVvPOyPJcPRPdXmqZ7Dc=;\n\th=To:Date:In-Reply-To:References:Subject:List-Id:List-Unsubscribe:\n\tList-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:\n\tFrom;\n\tb=30wp+ynSoxCQXaPzPSiiOiSJ+Kk5kDBRbBtUk4KyQcrEu3eZ3oeFDyaRLdlnHQOPw\n\tPZnqPFYvIR7z+XKP7VpAgcQBuuseX0Cvv/oCn7fSkMdSWFjSLDSLzK3bvjQvljoK8R\n\tJSQxgUiP85a4V78JwEDHXuw1/CuMjzPf7Ls106ZQA93tvGsOmLauIoFmRyMNp841vh\n\tS+0iz0Y7rqo33j1pwekZ6CyZrZAy2tR3taS+vyDKwYugGnGbfuYBHC62xpAVIJ9fwL\n\tW8xxIcop8/8m8l42CXBDaK+X46zPvp8T3aaWnryDH8gITdJPvEJeHoYMIw1iyRdmOp\n\teJuvgPxYNQNDQ==","v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=raspberrypi.com; s=google;\n\th=from:to:cc:subject:date:message-id:in-reply-to:references\n\t:mime-version:content-transfer-encoding;\n\tbh=FdWTaurTn9W7KgwZjC/8SQezC9mg7uuZh1hQmu7HWEw=;\n\tb=pI187i6qCwGXwz/rfP80LZocUHOsd7GMlOKGolVm87qIPszhhs2I87jaz4ZVOnJqMD\n\ti4gCtWRyErm42ZwXBsjcNQ8z4hsp2l1vapgQIQmsXSKJLC+tc5g1GOEL1zvMQflBBuWg\n\tKzzCEw/2aE8P8d7p2pkPNtbOim93YTVvx5FZqI/GYvD/Cpm//xQg8cl4PQRSa6Rbn0Ok\n\tMeK2rTg6bIxAM6IzAgy1DKcPqxddOnlFMPdUEcyyxr0QEwFPgtQxb6TG139QXLJuqxrD\n\t0BR7IWZ4rTjR71NEjZYCfTuyrT4UMZWe3qeC+b4AC5n6i5jBzIdNiJvfIwRXfuTdH0ud\n\tNIIg=="],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (2048-bit key; \n\tunprotected) header.d=raspberrypi.com\n\theader.i=@raspberrypi.com\n\theader.b=\"pI187i6q\"; 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:from:to:cc:subject:date:message-id:in-reply-to\n\t:references:mime-version:content-transfer-encoding;\n\tbh=FdWTaurTn9W7KgwZjC/8SQezC9mg7uuZh1hQmu7HWEw=;\n\tb=2KSq0cjmCGkkccoBUeFz5hZk1axg3R+h6WzOGIsmKiNDfgYKUJIEh8YoPwIHJXLe64\n\ty8T9uI7Hufkdf7JLQEyjK1IeRw01KqEdEw5l5aymBheUpfsfDWKPsmZkI/KlFn1T9znN\n\tZ9cSLhgmYFyeicdqzh79SDpGqBC6npqBKniEFz/DJ1gxFhJ+85CTUiW54rtSzUqKB+pv\n\tPbXkiO5FlA5BRBksDrX/pFUBugqYGkGVirn1249j7JOhHKVQx1L4WfETLKzgXVuCugoe\n\tpEMruzJryyp9CLddQwEqLR0r4x48e44S96aFZI8NgpoBuPOL4/Mp/pHFAMYB26p45aR1\n\tY7Nw==","X-Gm-Message-State":"AOAM53042ebSxXKTzGaxVDXuFgcV8sKUAIhMcCgmbolrHcDLrhzpZZ1l\n\t/A6SAKLfZYGjR1/ruq5GKzYMAzkAlYkHqIqd","X-Google-Smtp-Source":"ABdhPJy5feHGVPh/uBXUkKjN86NhhFAJTSMn83ougsGIJJpvQVGPAYJ+I94nGg+8VKUfNqcPNMnScQ==","X-Received":"by 2002:a05:6000:2ab:b0:204:f77:c1a with SMTP id\n\tl11-20020a05600002ab00b002040f770c1amr4571132wry.173.1648739875475; \n\tThu, 31 Mar 2022 08:17:55 -0700 (PDT)","To":"libcamera-devel@lists.libcamera.org, hanlinchen@chromium.org,\n\thpa@redhat.com, jeanmichel.hautbois@ideasonboard.com","Date":"Thu, 31 Mar 2022 16:17:47 +0100","Message-Id":"<20220331151747.19458-2-david.plowman@raspberrypi.com>","X-Mailer":"git-send-email 2.30.2","In-Reply-To":"<20220331151747.19458-1-david.plowman@raspberrypi.com>","References":"<20220331151747.19458-1-david.plowman@raspberrypi.com>","MIME-Version":"1.0","Content-Transfer-Encoding":"8bit","Subject":"[libcamera-devel] [PATCH v2 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 ","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "},"content":"This patch describes a series of controls that allow applications to\ndrive AF algorithms:\n\nAfMode - manual, auto or continuous\nAfLensPosition - set lens position to macro/hyperfocal/infinity\nAfRange - full, macro or normal\nAfSpeed - fast or slow\nAfWindows - AF window locations\nAfTrigger - start (trigger an AF scan) or cancel\nAfPause - pause continuous AF\nLensPosition - position of lens from lens driver\nAfState - reports the mode, whether scanning/success/failure\n---\n src/libcamera/control_ids.yaml | 373 +++++++++++++++++++++++++++------\n 1 file changed, 313 insertions(+), 60 deletions(-)","diff":"diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml\nindex 9d4638ae..23607368 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,317 @@ 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+ 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+\n+ An implementation may choose not to implement all the modes.\n+\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, but an\n+ application can set controls to move the lens.\n+\n+ In this mode the AfState will always report AfStateManual.\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+ AfStateAuto. When a trigger control is sent, AfState will\n+ report AfStateAutoScanning for a period before spontaneously\n+ changing to AfStateAutoFocused or AfStateAutoFailed, depending on\n+ the outcome of the scan. It will remain in this state until\n+ another scan is initiated by the AfTrigger control. If a scan is\n+ cancelled (without changing to another mode), AfState will return\n+ to AfStateAuto.\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 (though it can \"pause\" them), nor to\n+ move the lens for itself.\n+\n+ When set to AfModeContinuous, the system will immediately initiate\n+ a scan so AfState will report AfStateContinuousScanning, and will\n+ settle on one of AfStateContinuousFocused or AfStateContinuousFailed,\n+ depending on the scan result.\n+\n+ - AfLensPosition:\n+ type: int32_t\n+ draft: true\n+ description: |\n+ Control to set the position of the lens to one of the following\n+ predefined locations. This control only has any effect when the AfMode\n+ is set to AfModeManual.\n+\n+ This control is distinct from the LensPosition control, which sets the\n+ lens position using the lens driver's units.\n+ enum:\n+ - name: AfLensPositionMacro\n+ value: 0\n+ description: The closest focal position of the lens.\n+ - name: AfLensPositionHyperfocal\n+ value: 1\n+ description: Hyperfocal position.\n+ - name: AfLensPositionInfinity\n+ value: 2\n+ description: The furthest focal position (usually infinity).\n+\n+ - AfRange:\n+ type: int32_t\n+ draft: true\n+ description: |\n+ Control to set the range of focus distances that is scanned. An\n+ implementation may choose not to implement all the options here.\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+ - 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+ - AfWindows:\n+ type: Rectangle\n+ draft: true\n+ description: |\n+ Sets the focus windows used by the AF algorithm. The units used express\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+ 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 AfModeManual or 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. This does not cause the lens to move\n+ anywhere else. Ignored if no scan is in progress.\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. If the AfState was previously\n+ reporting AfStateContinuousScanning it will now change to\n+ AfStateContinuousScanningPaused, and similarly for\n+ AfStateContinuousFocused and AfStateContinuousFailed.\n+ - name AfPauseDeferred\n+ value: 1\n+ description: |\n+ Pause the continuous autofocus algorithm as soon as it is no longer\n+ scanning. If the AfState is currently reporting\n+ AfStateContinuousFocused is will change to\n+ AfStateContinuousFocusedPaused, and similarly in the case of\n+ AfStateContinuousFailed.\n+\n+ If AfState reports AfStateContinuousScanning it will change to\n+ AfStateContinuousScanningPausing, and then move to one of\n+ AfStateContinuousFocusedPaused or AfStateContinuousFailedPaused\n+ when the scan completes.\n+ - name: AfPauseResume\n+ value: 2\n+ description: |\n+ Resume continous autofocus operation. The algorithm starts again\n+ from exactly where it left off, and the AfState will drop the\n+ 'Paused' or 'Pausing' part of the 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+ Note that this control is distinct from AfLensPosition, which allows\n+ the lens to be moved to its macro/hyperfocal/infinity position, rather\n+ than using lens driver units.\n+\n+ - AfState:\n+ type: int32_t\n+ draft: true\n+ description: |\n+ Reports the current state of the AF algorithm. The possible state changes\n+ are described below, although we add that the following general state\n+ changes are also allowed.\n+\n+ In any of the AfStateManual or AfStateContinuous states, the AfMode\n+ may be set to AfModeAuto and the algorithm will move to the\n+ AfStateAuto state. If AfTriggerStart is sent at the same time\n+ then the algorithm will move to AfStateAutoScanning state.\n+\n+ In any of the AfStateAuto or AfStateManual states, the AfMode may\n+ be set to AfModeContinuous and the algorithm will move to\n+ AfStateContinuousScanning.\n+\n+ In any of the AfStateAuto or AfStateContinuous states, the AfMode may\n+ be set to AfModeManual and the algorithm will move to\n+ AfStateManual. The lens will not be moved and will be left where\n+ it was at that moment.\n+\n+ enum:\n+ - name: AfStateManual\n+ value: 0\n+ description: |\n+ The AF algorithm is in manual mode (AfModeManual). The LensPosition\n+ and AfLensPosition controls can be used directly to move the lens. \n+ - name: AfStateAuto\n+ value: 1\n+ description: |\n+ The AF algorithm is in auto mode (AfModeAuto), and has either just\n+ been moved into that state, or a scan that was in progress has been\n+ cancelled.\n+ - name: AfStateAutoScanning\n+ value: 2\n+ description: |\n+ The AF algorithm is in auto mode (AfModeAuto), and a scan has been\n+ started using the AfTrigger control. The scan can be cancelled by\n+ sending AfTriggerCancel at which point the algorithm will either\n+ move back to AfStateAuto or, if the scan actually completes\n+ before the cancel request is processed, to one of\n+ AfStateAutoFocused or AfStateAutoFailed.\n+ - name: AfStateAutoFocused\n+ value: 3\n+ description: |\n+ The AF algorithm is in auto mode (AfModeAuto), and a scan has\n+ completed with the result that the algorithm believes the image is\n+ now in focus.\n+ - name: AfStateAutoFailed\n+ value: 4\n+ description: |\n+ The AF algorithm is in auto mode (AfModeAuto), and a scan has\n+ completed with the result that the algorithm did not find a good\n+ focus position.\n+ - name: AfStateContinuousScanning\n+ value: 5\n+ description: |\n+ The AF algorithm is in continuous mode (AfModeContinuous) and\n+ is currently scanning for a good focus position. This occurs when\n+ the mode is first set to AfModeContinuous, or may happen\n+ spontaneously when the algorithm believes a re-scan is needed.\n+ - name: AfStateContinuousScanningPausing\n+ value: 6\n+ description: |\n+ The AF algorithm is in continuous mode (AfModeContinuous) and\n+ was scanning when AfPauseDeferred was sent. The scan will complete\n+ at which point the algorithm moves to the\n+ AfStateContinuousFocusedPaused or AfStateContinuousFailedPaused\n+ state.\n+ - name: AfStateContinuousScanningPaused\n+ value: 7\n+ description: |\n+ The AF algorithm is in continuous mode (AfModeContinuous) and\n+ was scanning when AfPauseImmediate was sent. The scan will not\n+ complete and the algorithm will remain in this state. The scan\n+ may be resumed by sending AfPauseResume.\n+ - name: AfStateContinuousFocused\n+ value: 8\n+ description: |\n+ The AF algorithm is in continuous mode (AfModeContinuous) and\n+ a scan has completed with the algorithm believing it has found a\n+ good focus position.\n+ - name: AfStateContinuousFocusedPaused\n+ value: 9\n+ description: |\n+ The AF algorithm was in the AfStateContinuousFocused state and\n+ has been paused (by either AfPauseImmediate or AfPauseDeferred),\n+ or it was in the AfStateContinuousScanningPausing state and the\n+ scan has completed successfully. The algorithm will now remain\n+ in this state, and may be resumed by sending AfPauseResume.\n+ - name: AfStateContinuousFailed\n+ value: 10\n+ description: |\n+ The AF algorithm is in continuous mode (AfModeContinuous) and\n+ a scan has completed without finding a good focus position.\n+ - name: AfStateContinuousFailedPaused\n+ value: 11\n+ description: |\n+ The AF algorithm was in the AfStateContinuousFailed state and\n+ has been paused (by either AfPauseImmediate or AfPauseDeferred),\n+ or it was in the AfStateContinuousScanningPausing state and the\n+ scan has completed unsuccessfully. The algorithm will now remain\n+ in this state, and may be resumed by sending AfPauseResume.\n+\n ...\n","prefixes":["libcamera-devel","v2","1/1"]}