{"id":15689,"url":"https://patchwork.libcamera.org/api/patches/15689/?format=json","web_url":"https://patchwork.libcamera.org/patch/15689/","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":"<20220420162622.16521-2-david.plowman@raspberrypi.com>","date":"2022-04-20T16:26:22","name":"[libcamera-devel,v3,1/1] libcamera: controls: Controls for driving AF (autofocus) algorithms","commit_ref":null,"pull_url":null,"state":"superseded","archived":false,"hash":"651a410cad812b098ea083332a460d6a85f0301c","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/15689/mbox/","series":[{"id":3060,"url":"https://patchwork.libcamera.org/api/series/3060/?format=json","web_url":"https://patchwork.libcamera.org/project/libcamera/list/?series=3060","date":"2022-04-20T16:26:21","name":"AF controls","version":3,"mbox":"https://patchwork.libcamera.org/series/3060/mbox/"}],"comments":"https://patchwork.libcamera.org/api/patches/15689/comments/","check":"pending","checks":"https://patchwork.libcamera.org/api/patches/15689/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 859C3C3260\n\tfor ;\n\tWed, 20 Apr 2022 16:26:46 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 916DE65643;\n\tWed, 20 Apr 2022 18:26:45 +0200 (CEST)","from mail-wm1-x32a.google.com (mail-wm1-x32a.google.com\n\t[IPv6:2a00:1450:4864:20::32a])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 4123C604AB\n\tfor ;\n\tWed, 20 Apr 2022 18:26:44 +0200 (CEST)","by mail-wm1-x32a.google.com with SMTP id x3so1554644wmj.5\n\tfor ;\n\tWed, 20 Apr 2022 09:26:44 -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\tc12-20020a05600c0a4c00b00381141f4967sm298910wmq.35.2022.04.20.09.26.42\n\t(version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n\tWed, 20 Apr 2022 09:26:42 -0700 (PDT)"],"DKIM-Signature":["v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org;\n\ts=mail; t=1650472005;\n\tbh=s0rqCobI5fuuANV9e8BDSGlGZ/ubasg9SzCjexcHJpE=;\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=s+tVNmkpm+/WEs0asY532OYDaOa7+jIR32Fg7PSrJG2mnN+zIkI6ZRoRpSH569oXl\n\tYTUWBHQhDbvsiDZTwvaaPkAtLEnhChFazMjCC75nwBB77WR6I4mQbOyD89qef78gXN\n\tyLilI/npaQ2gBGgx5GgzlHHu0ESqAcjQ9UXLLxM6bXZWpiS4SmqIx9uG1GYFZYTg9H\n\try2gm4NIXyxVhxm8JIsWE+dczZO0SjI/HkmhxxTa+PnZdf4+yfinp5G0bLF9grmlUs\n\tiMNMCfdaZIHqZDMun8OQYuB4YcAd7oaCU7bl6Cq9H7mK64VaPQm2hV+4L6l/q4JyTQ\n\tRAZuSbc6GXJ1g==","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=08cD7WWptItAQfZaK52HN5b6DkJIT37ZqWRCOE7BqvA=;\n\tb=OzlkiK8k1461JvMDMiT/k+qXKGAk6IvgzMJXKkwVqoPAkxMbEHq+BaqxJyAQRKl9JA\n\tfXWmL6OZgXxezeQkMifxTV1X8DuypYjV6g1AVU5av9gGbgdL/OmSqEyTiimigig9RhTY\n\tSiYAwbETiPWAwygK2P1MCkhfNJKEq5IW+JFB+4gaPO2JqF7pesTpE/3lWvbnUDiwqH24\n\tA53YOMqH9ghiJjq/0kdi0uMm2WuWXqazzk95490UePnE8bjTkAhafp0THkVW8QjuVsr7\n\tzxhQaWvJ4mHjciWOoc/f6aSPQC12JyNfLOIlAG35goqfv2jeJeicRPIab+pJjPojOWwU\n\tJFYA=="],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (2048-bit key; \n\tunprotected) header.d=raspberrypi.com\n\theader.i=@raspberrypi.com\n\theader.b=\"OzlkiK8k\"; 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=08cD7WWptItAQfZaK52HN5b6DkJIT37ZqWRCOE7BqvA=;\n\tb=1V1Kh7yayQEJ4UvEsAccLF5fLJBukK16b7sPRkMhEy60zN/qdiIEG1OTJ2MXophM87\n\tp7ZdQ88QXw1IFQ56CTPZm15IpRYiT/BrOgNmPs4mukeii/Iqqp2vUQ3L5iHTWzGdc8j0\n\tLEQQbkittPY4WJZuSjFha3WjIbE0gv2MgzOTyCtQW9j7nguH4RlREP7MYJpeXgKCH7+8\n\tP3vte3N6HlXkhMrV8WPp8LyPfN1llpmSoa5OgZp40ojRo6XngyplB33S2fCWEV5QVzsq\n\tAGh/bmq7tupXNtJGPK5Hce3CL6fi/5EnUAk0GeMiBEUP5kKHRb3sgdMBcaXz90Gec6hg\n\t3brA==","X-Gm-Message-State":"AOAM531q8TwvdaqscuxADiJNHkAUhYO/DiA+rAXoY9iA9jDpoSdF7qen\n\tMJj5mZjUI0cmfVYBf8dNSOcJGVGIjhWp+Ys+","X-Google-Smtp-Source":"ABdhPJz8gCwX9/23yjGAqjlvw3t6cySwRPKGBhpCuPdid92mlIZBbrNIckX8s4zbBvSjWBjfY1K60w==","X-Received":"by 2002:a05:600c:a06:b0:392:a4f2:2097 with SMTP id\n\tz6-20020a05600c0a0600b00392a4f22097mr4504525wmp.97.1650472003508; \n\tWed, 20 Apr 2022 09:26:43 -0700 (PDT)","To":"libcamera-devel@lists.libcamera.org,\n\tJean-Michel Hautbois ,\n\tHan-Lin Chen , Kate Hsuan , \n\tJacopo Mondi ","Date":"Wed, 20 Apr 2022 17:26:22 +0100","Message-Id":"<20220420162622.16521-2-david.plowman@raspberrypi.com>","X-Mailer":"git-send-email 2.30.2","In-Reply-To":"<20220420162622.16521-1-david.plowman@raspberrypi.com>","References":"<20220420162622.16521-1-david.plowman@raspberrypi.com>","MIME-Version":"1.0","Content-Transfer-Encoding":"8bit","Subject":"[libcamera-devel] [PATCH v3 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\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 - set or retrieve position of lens\nAfState - reports whether scanning/success/failure\nAfPauseState - reports whether continuous AF paused or not\n\nSigned-off-by: David Plowman \n---\n src/libcamera/control_ids.yaml | 318 ++++++++++++++++++++++++++-------\n 1 file changed, 258 insertions(+), 60 deletions(-)","diff":"diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml\nindex 9d4638ae..eccf18bc 100644\n--- a/src/libcamera/control_ids.yaml\n+++ b/src/libcamera/control_ids.yaml\n@@ -381,6 +381,264 @@ controls:\n \\todo Define how the sensor timestamp has to be used in the reprocessing\n use case.\n \n+ - AfMode:\n+ type: int32_t\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 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 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+ 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 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 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 (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 AfStateScanning, and will settle on\n+ one of AfStateFocused or AfStateFailed, depending on the scan result.\n+\n+ - AfRange:\n+ type: int32_t\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+ 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+ 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: [n]\n+\n+ - AfTrigger:\n+ type: int32_t\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+ 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. AfPauseState will subsequently\n+ report AfPauseStatePaused. AfState may report any of AfStateScanning,\n+ AfStateFocused or AfStateFailed, depending on the algorithm's state\n+ when it received this control.\n+ - name: AfPauseDeferred\n+ value: 1\n+ description: |\n+ This is similar to AfPauseImmediate, and if the AfState is currently\n+ reporting AfStateFocused or AfStateFailed it will remain in that\n+ state and AfPauseState will report AfPauseStatePaused.\n+\n+ However, if the algorithm is scanning (AfStateScanning), AfPauseState\n+ will report AfPauseStatePausing until the scan is finished, at which\n+ point AfState will report one of AfStateFocused or AfStateFailed, and\n+ AfPauseState will change to AfPauseStatePaused.\n+ - name: AfPauseResume\n+ value: 2\n+ description: |\n+ Resume continuous autofocus operation. The algorithm starts again\n+ from exactly where it left off, and AfPauseState will report\n+ AfPauseStateRunning.\n+\n+ - LensPosition:\n+ type: float\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 LensPosition control is ignored unless the AfMode is set to\n+ AfModeManual.\n+\n+ The units are dioptres divided by the hyperfocal distance. Non-integer\n+ values are permitted. For example:\n+ 0 moves the lens to infinity.\n+ 0.5 moves the lens to twice the hyperfocal distance.\n+ 1 moves the lens to the hyperfocal position.\n+ And larger values will focus the lens ever closer.\n+\n+ - AfState:\n+ type: int32_t\n+ description: |\n+ Reports the current state of the AF algorithm in conjunction with the\n+ reported AfMode value and (in continuous AF mode) the AfPauseState value.\n+ The possible state changes are described below, though we note the following\n+ state transitions that occur when the AfMode is changed.\n+\n+ If the AfMode is set to AfModeManual then the AfState will report\n+ AfStateReset. This action on its own does not cause the lens to move; the\n+ LensPosition control must subsequently be used to achieve this.\n+\n+ If the AfMode is set to AfModeAuto then the AfState will report\n+ AfStateReset, unless AfTriggerStart is sent at the same time in which\n+ case it will (start a scan and) report AfStateScanning.\n+\n+ If the AfMode is set to AfModeContinuous then the AfState will initially\n+ report AfStateScanning.\n+\n+ enum:\n+ - name: AfStateReset\n+ value: 0\n+ description: |\n+ The AF algorithm is in manual mode (AfModeManual) or in auto mode\n+ (AfModeAuto) and a scan has not yet been triggered, or an in-progress\n+ scan was cancelled.\n+ - name: AfStateScanning\n+ value: 1\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 AfStateReset or, if the scan actually completes\n+ before the cancel request is processed, to one of\n+ AfStateFocused or AfStateFailed.\n+\n+ Alternatively the AF algorithm be be in continuous mode (AfModeContinuous)\n+ at which point it may enter this state spontaneously whenever it\n+ determines that a rescan is needed.\n+ - name: AfStateFocused\n+ value: 2\n+ description: |\n+ The AF algorithm is in auto (AfModeAuto) or continuous (AfModeContinuous)\n+ mode and a scan has completed with the result that the algorithm believes\n+ the image is now in focus.\n+ - name: AfStateFailed\n+ value: 3\n+ description: |\n+ The AF algorithm is in auto (AfModeAuto) or continuous (AfModeContinuous)\n+ mode and a scan has completed with the result that the algorithm did not\n+ find a good focus position.\n+\n+ - AfPauseState:\n+ type: int32_t\n+ description: |\n+ Only applicable in continuous (AfModeContinuous) mode, this reports whether\n+ the algorithm is currently running, paused or pausing (that is, will pause\n+ as soon as any in-progress scan completes).\n+\n+ Any change to AfMode will cause AfPauseStateRunning to be reported.\n+\n+ enum:\n+ - name: AfPauseStateRunning\n+ value: 0\n+ description: |\n+ Continuous AF is running and the algorithm may restart a scan\n+ spontaneously.\n+ - name: AfPauseStatePausing\n+ value: 1\n+ description: |\n+ Continuous AF has been sent an AfPauseDeferred control, and will pause\n+ as soon as any in-progress scan completes (and then report\n+ AfPauseStatePaused). No new scans will be start spontaneously until\n+ the AfPauseResume control is sent.\n+ - name: AfPauseStatePaused\n+ value: 2\n+ description: |\n+ Continuous AF is paused. No further state changes or lens movements\n+ will occur until the AfPauseResume control is sent.\n+\n # ----------------------------------------------------------------------------\n # Draft controls section\n \n@@ -406,27 +664,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 +744,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","prefixes":["libcamera-devel","v3","1/1"]}