{"id":15437,"url":"https://patchwork.libcamera.org/api/patches/15437/?format=json","web_url":"https://patchwork.libcamera.org/patch/15437/","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":"<20220310120540.15296-2-david.plowman@raspberrypi.com>","date":"2022-03-10T12:05:40","name":"[libcamera-devel,1/1] libcamera: controls: Controls for driving AF (autofocus) algorithms","commit_ref":null,"pull_url":null,"state":"superseded","archived":false,"hash":"1a2ff04310bc36ebc1b5a7d70cd7b02f95827b14","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/15437/mbox/","series":[{"id":2957,"url":"https://patchwork.libcamera.org/api/series/2957/?format=json","web_url":"https://patchwork.libcamera.org/project/libcamera/list/?series=2957","date":"2022-03-10T12:05:39","name":"AF controls","version":1,"mbox":"https://patchwork.libcamera.org/series/2957/mbox/"}],"comments":"https://patchwork.libcamera.org/api/patches/15437/comments/","check":"pending","checks":"https://patchwork.libcamera.org/api/patches/15437/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\r\n\t[92.243.16.209])\r\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id 212D4BE08A\r\n\tfor ;\r\n\tThu, 10 Mar 2022 12:06:06 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\r\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id C3B79632E9;\r\n\tThu, 10 Mar 2022 13:06:04 +0100 (CET)","from mail-wr1-x42f.google.com (mail-wr1-x42f.google.com\r\n\t[IPv6:2a00:1450:4864:20::42f])\r\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 3DE07601F5\r\n\tfor ;\r\n\tThu, 10 Mar 2022 13:06:03 +0100 (CET)","by mail-wr1-x42f.google.com with SMTP id k24so7597371wrd.7\r\n\tfor ;\r\n\tThu, 10 Mar 2022 04:06:03 -0800 (PST)","from pi4-davidp.pitowers.org\r\n\t([2a00:1098:3142:14:e4a2:3070:eea4:e434])\r\n\tby smtp.gmail.com with ESMTPSA id\r\n\tbg18-20020a05600c3c9200b0037c2ef07493sm5399161wmb.3.2022.03.10.04.06.01\r\n\t(version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\r\n\tThu, 10 Mar 2022 04:06:02 -0800 (PST)"],"DKIM-Signature":["v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org;\r\n\ts=mail; t=1646913964;\r\n\tbh=r4pKdbZdxlOXmqBXrtmYgA5IRmSMGgYBumBVVDlzeM8=;\r\n\th=To:Date:In-Reply-To:References:Subject:List-Id:List-Unsubscribe:\r\n\tList-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:\r\n\tFrom;\r\n\tb=oXbc0c1D0BzaFC8+ocqP5aI7hYW7CmWuK09kCM5k5g7EsyTbzwgyICcKt7oSxiZUj\r\n\tEQs9NYQTyoAzurE/RFaRUYvjESKocVBNMazM2dKZYL7Hq1+AjFZEaVC4DhnlxEZmew\r\n\tvh8XLb9WF8Q6ofO9EcZcYOvmdvnDGy2gJ2jxM6sVG5yW56zrUkq8UFhyZrTj4Pm4pz\r\n\t1XG31d+qkMIk+aBYLPBgbnj6e99Nfc+A21Z/jmhQYzqNlZHm2zFGDPjMIimZD4caEs\r\n\t/fNINR6Lqqmny4lpODad5cer8wIr7xdARmKxciV57eKzTfJ+fIApFJe15gf+7zunn+\r\n\tHFOe9lLS0Mekg==","v=1; a=rsa-sha256; c=relaxed/relaxed;\r\n\td=raspberrypi.com; s=google;\r\n\th=from:to:cc:subject:date:message-id:in-reply-to:references\r\n\t:mime-version:content-transfer-encoding;\r\n\tbh=WqFguFVXyRqDDS3EF9Z9Td+S1KFOVUih7mpL0tJjLuA=;\r\n\tb=ihpF2iQy4+inCoTvnIHQ/ILd6wBYAg8mzDLzt8rgFYtiuIOhmAU2h3/LcWV+ChwvQt\r\n\tQf8JHFFGlX0kFNLct6luXvEtrFtJh/4C7zLUfT0RnPP/OP4Vu3HN30ZPAIV/Ow01FO/5\r\n\t74qg7CgW8vafT55CmeMx65rWEx0dmRNiX9QsLVq+OsHf4JAPcdTThh776YFTOkZKintq\r\n\tOlIyiwdBvG3xY+uaPAJ/6/y45xcP0NMkiZOobFwLj0ORgdXKeqPEhNPVJr8BkwIwh9zH\r\n\t/Z/QvLVM/yw39UK+w36f5Q46r7v6ETrEbqreio/EfefM5gUK1jksV6TZv/kgEEpd3trQ\r\n\tvVEg=="],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (2048-bit key; \r\n\tunprotected) header.d=raspberrypi.com\r\n\theader.i=@raspberrypi.com\r\n\theader.b=\"ihpF2iQy\"; dkim-atps=neutral","X-Google-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\r\n\td=1e100.net; s=20210112;\r\n\th=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to\r\n\t:references:mime-version:content-transfer-encoding;\r\n\tbh=WqFguFVXyRqDDS3EF9Z9Td+S1KFOVUih7mpL0tJjLuA=;\r\n\tb=ptRTKGG14JBH7FJQT0zRzhjmcwFUoJJKTkqKo6ZSTAkWQ4jw9yMvo2m1DzPxwBOS6b\r\n\tYGJclEGknzV4XfY2My92oLGK77q1fEiAey5dphGZ44t7hkvPnmeKy26x5M0xgktPwkSi\r\n\tGS/gpXsw4Af/x3ymn7uFnCRr9gvkV57cIvJgSb5zpXm3OOZu1XcV1/EM7tsxCj+7NIqn\r\n\tzsUuiw42F3mYmGPzEP4punn6JrflBF9nKV1HFxsxo2xF7RQ6SlpBlIowV1gJrKvqvgVB\r\n\tmwTXBDkBDSHx/4ElpsHT5LGgrLZqFu0xDDm7GXWyVXhMahza3YtjMNSBOkQv2KKBZCSj\r\n\tCkxw==","X-Gm-Message-State":"AOAM531cIQxM/hGDKfzIzMtfa1uYJnlUyO2qIv4swy1PvHCPxGslFdAY\r\n\tAx4gvq2FBJ/pTm1bcen7wRgTxSr9t9FRqQ==","X-Google-Smtp-Source":"ABdhPJyJky0C6oEel1OGD1/e65lJPVpKTixjBc3hLfof8XbZqSZwQHz4QX5GtPo/AOB9dKnwW86JcA==","X-Received":"by 2002:a5d:538b:0:b0:1f1:e60b:20c2 with SMTP id\r\n\td11-20020a5d538b000000b001f1e60b20c2mr3230597wrv.294.1646913962540; \r\n\tThu, 10 Mar 2022 04:06:02 -0800 (PST)","To":"libcamera-devel@lists.libcamera.org, hanlinchen@chromium.org,\r\n\thpa@redhat.com","Date":"Thu, 10 Mar 2022 12:05:40 +0000","Message-Id":"<20220310120540.15296-2-david.plowman@raspberrypi.com>","X-Mailer":"git-send-email 2.30.2","In-Reply-To":"<20220310120540.15296-1-david.plowman@raspberrypi.com>","References":"<20220310120540.15296-1-david.plowman@raspberrypi.com>","MIME-Version":"1.0","Content-Transfer-Encoding":"8bit","Subject":"[libcamera-devel] [PATCH 1/1] libcamera: controls: Controls for\r\n\tdriving AF (autofocus) algorithms","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\r\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\r\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\nAfWindow - AF window locations\nAfTrigger - start (trigger an AF scan) or cancel\nAfPause - pause continuous AF\nLensPosition - position of lens from lens driver\nAfState - reset, scanning, focused or failed\n---\n src/libcamera/control_ids.yaml | 271 +++++++++++++++++++++++++--------\n 1 file changed, 211 insertions(+), 60 deletions(-)","diff":"diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml\r\nindex 9d4638ae..89636d82 100644\r\n--- a/src/libcamera/control_ids.yaml\r\n+++ b/src/libcamera/control_ids.yaml\r\n@@ -406,27 +406,6 @@ controls:\r\n The camera will cancel any active or completed metering sequence.\r\n The AE algorithm is reset to its initial state.\r\n \r\n- - AfTrigger:\r\n- type: int32_t\r\n- draft: true\r\n- description: |\r\n- Control for AF trigger. Currently identical to\r\n- ANDROID_CONTROL_AF_TRIGGER.\r\n-\r\n- Whether the camera device will trigger autofocus for this request.\r\n- enum:\r\n- - name: AfTriggerIdle\r\n- value: 0\r\n- description: The trigger is idle.\r\n- - name: AfTriggerStart\r\n- value: 1\r\n- description: The AF routine is started by the camera.\r\n- - name: AfTriggerCancel\r\n- value: 2\r\n- description: |\r\n- The camera will cancel any active trigger and the AF routine is\r\n- reset to its initial state.\r\n-\r\n - NoiseReductionMode:\r\n type: int32_t\r\n draft: true\r\n@@ -507,45 +486,6 @@ controls:\r\n The AE algorithm has started a pre-capture metering session.\r\n \\sa AePrecaptureTrigger\r\n \r\n- - AfState:\r\n- type: int32_t\r\n- draft: true\r\n- description: |\r\n- Control to report the current AF algorithm state. Currently identical to\r\n- ANDROID_CONTROL_AF_STATE.\r\n-\r\n- Current state of the AF algorithm.\r\n- enum:\r\n- - name: AfStateInactive\r\n- value: 0\r\n- description: The AF algorithm is inactive.\r\n- - name: AfStatePassiveScan\r\n- value: 1\r\n- description: |\r\n- AF is performing a passive scan of the scene in continuous\r\n- auto-focus mode.\r\n- - name: AfStatePassiveFocused\r\n- value: 2\r\n- description: |\r\n- AF believes the scene is in focus, but might restart scanning.\r\n- - name: AfStateActiveScan\r\n- value: 3\r\n- description: |\r\n- AF is performing a scan triggered by an AF trigger request.\r\n- \\sa AfTrigger\r\n- - name: AfStateFocusedLock\r\n- value: 4\r\n- description: |\r\n- AF believes has focused correctly and has locked focus.\r\n- - name: AfStateNotFocusedLock\r\n- value: 5\r\n- description: |\r\n- AF has not been able to focus and has locked.\r\n- - name: AfStatePassiveUnfocused\r\n- value: 6\r\n- description: |\r\n- AF has completed a passive scan without finding focus.\r\n-\r\n - AwbState:\r\n type: int32_t\r\n draft: true\r\n@@ -690,4 +630,215 @@ controls:\r\n value. All of the custom test patterns will be static (that is the\r\n raw image must not vary from frame to frame).\r\n \r\n+ - AfMode:\r\n+ type: int32_t\r\n+ draft: true\r\n+ description: |\r\n+ Control to set the mode of the AF (autofocus) algorithm. Applications\r\n+ are allowed to set a new mode, and to send additional controls for\r\n+ that new mode, in the same request.\r\n+ enum:\r\n+ - name: AfModeManual\r\n+ value: 0\r\n+ description: |\r\n+ The AF algorithm is in manual mode. In this mode it will never\r\n+ perform any action nor move the lens of its own accord. The only\r\n+\t autofocus controls that have an immediate effect are AfMode (to\r\n+\t switch out of manual mode) and LensPosition (so that the lens can\r\n+\t be moved \"manually\").\r\n+\r\n+\t In this mode the AfState will always report AfStateReset.\r\n+ - name: AfModeAuto\r\n+ value: 1\r\n+ description: |\r\n+ The AF algorithm is in auto mode. This means that the algorithm\r\n+ will never move the lens or change state unless the AfTrigger\r\n+ control is used. The AfTrigger control can be used to initiate a\r\n+ focus scan, the results of which will also be reported by AfState.\r\n+\r\n+ If the autofocus algorithm is moved from AfModeAuto to another\r\n+ mode while a scan is in progress, the scan is cancelled\r\n+ immediately, without waiting for the scan to finish.\r\n+\r\n+\t When first entering this mode the AfState will report\r\n+\t AfStateReset. When a trigger control is sent, AfState will\r\n+\t report AfStateScanning for a period before spontaneously\r\n+\t changing to AfStateFocused or AfStateFailed, depending on the\r\n+\t outcome of the scan. It will remain in this state until another\r\n+\t scan is initiated by the AfTrigger control. If a scan is\r\n+\t cancelled (without changing to another mode), AfState will return\r\n+\t to AfStateReset.\r\n+ - name: AfModeContinuous\r\n+ value: 2\r\n+ description: |\r\n+ The AF algorithm is in continuous mode. This means that the lens\r\n+ can re-start a scan spontaneously at any moment, without any user\r\n+ intervention. The AfState still reports whether the algorithm is\r\n+ currently scanning or not, though the application has no ability\r\n+ to initiate or cancel scans, nor move the lens for itself.\r\n+\r\n+\t When set to AfModeContinuous, the system will immediately initiate\r\n+\t a scan so AfState will report AfStateScanning, and will settle on\r\n+\t one of AfStateFocused or AfStateFailed, depending on the scan\r\n+\t result.\r\n+\r\n+ The continuous autofocus behaviour can be paused with the\r\n+\t AfPause control. Pausing the algorithm does not change the value\r\n+\t reported by AfState, so that applications can determine the\r\n+\t state of the algorithm when the pause control took effect. Once\r\n+\t un-paused (\"resumed\"), the algorithm starts again from exactly\r\n+\t where it left off when it paused.\r\n+\r\n+ - AfRange:\r\n+ type: int32_t\r\n+ draft: true\r\n+ description: |\r\n+ Control to set the range of focus distances that is scanned.\r\n+ enum:\r\n+ - name: AfRangeNormal\r\n+ value: 0\r\n+ description: |\r\n+\t A wide range of focus distances is scanned, all the way from\r\n+\t infinity down to close distances, though depending on the\r\n+\t implementation, possibly not including the very closest macro\r\n+\t positions.\r\n+ - name: AfRangeMacro\r\n+ value: 1\r\n+ description: Only close distances are scanned.\r\n+ - name: AfRangeFull\r\n+ value: 2\r\n+ description: |\r\n+ The full range of focus distances is scanned just as with\r\n+\t AfRangeNormal but this time including the very closest macro\r\n+\t positions.\r\n+\r\n+ - AfSpeed:\r\n+ type: int32_t\r\n+ draft: true\r\n+ description: |\r\n+ Control that determines whether the AF algorithm is to move the lens\r\n+ as quickly as possible or more steadily. For example, during video\r\n+ recording it may be desirable not to move the lens too abruptly, but\r\n+ when in a preview mode (waiting for a still capture) it may be\r\n+ helpful to move the lens as quickly as is reasonably possible.\r\n+ enum:\r\n+ - name: AfSpeedNormal\r\n+ value: 0\r\n+ description: Move the lens at its usual speed.\r\n+ - name: AfSpeedFast\r\n+ value: 1\r\n+ description: Move the lens more quickly.\r\n+\r\n+ - AfWindow:\r\n+ type: Rectangle\r\n+ draft: true\r\n+ description: |\r\n+ Sets the focus windows used by the AF algorithm. The units used express\r\n+ a proportion of the ScalerCrop control (or if unavailable, of the entire\r\n+ image), as u0.16 format numbers.\r\n+\r\n+ In order to be activated, a rectangle must be programmed with non-zero\r\n+ width and height. If no rectangles are programmed in this way, then the\r\n+ system will choose its own single default window in the centre of the\r\n+ image.\r\n+\r\n+ The details of how the windows are used are platform dependent. We note\r\n+ that when there is more than one AF window, a typical implementation\r\n+ might find the optimal focus position for each one and finally select\r\n+\t the window closest to the camera.\r\n+\r\n+ size: [platform dependent]\r\n+\r\n+ - AfTrigger:\r\n+ type: int32_t\r\n+ draft: true\r\n+ description: |\r\n+ This control starts an autofocus scan when AfMode is set to AfModeAuto,\r\n+ and can also be used to terminate a scan early.\r\n+\r\n+ It is ignored if AfMode is set to AfModeContinuous.\r\n+\r\n+ enum:\r\n+ - name: AfTriggerStart\r\n+ value: 0\r\n+ description: Start an AF scan. Ignored if a scan is in progress.\r\n+ - name: AfTriggerCancel\r\n+ value: 1\r\n+ description: Cancel an AF scan. Ingored if no scan is in progress.\r\n+\r\n+ - AfPause:\r\n+ type: int32_t\r\n+ draft: true\r\n+ description: |\r\n+ This control has no effect except when in continuous autofocus mode\r\n+ (AfModeContinuous). It can be used to pause any lens movements while\r\n+ (for example) images are captured. The algorithm remains inactive\r\n+ until it is instructed to resume.\r\n+\r\n+ enum:\r\n+ - name: AfPauseImmediate\r\n+ value: 0\r\n+ description: |\r\n+ Pause the continuous autofocus algorithm immediately, whether or\r\n+ not any kind of scan is underway. The AfState will continue to\r\n+ report whatever value it had when the control was enacted.\r\n+ - name AfPauseDeferred\r\n+ value: 1\r\n+ description: |\r\n+ Pause the continuous autofocus algorithm as soon as it is no longer\r\n+ scanning. The AfState will report AfStateFocused or AfStateFailed,\r\n+ depending on whether the final scan succeeds or not. If no scan is\r\n+\t in currently progress, the algorithm will pause immediately.\r\n+ - name: AfPauseResume\r\n+ value: 2\r\n+ description: |\r\n+\t Resume continous autofocus operation. The algorithm starts again\r\n+\t from exactly where it left off, with AfState unchanged (one of\r\n+\t AfStateFocused, AfStateFailed or following AfPauseImmediate it\r\n+\t might also have been in the AfStateScanning state).\r\n+\r\n+ - LensPosition:\r\n+ type: int32_t\r\n+ draft: true\r\n+ description: |\r\n+ Acts as a control to instruct the lens to move to a particular position\r\n+ and also reports back the position of the lens for each frame.\r\n+\r\n+ The units are determined by the lens driver.\r\n+\r\n+ The LensPosition control is ignored unless the AfMode is set to\r\n+ AfModeManual.\r\n+\r\n+ - AfState:\r\n+ type: int32_t\r\n+ draft: true\r\n+ description: |\r\n+ Reports the current state of the AF algorithm.\r\n+ enum:\r\n+ - name: AfStateReset\r\n+ value: 0\r\n+ description: |\r\n+ The AF algorithm reports this state when:\r\n+ * It is in manual mode (AfModeManual).\r\n+ * The system has entered auto mode (AfModeAuto) but no scan\r\n+\t\t has yet been initiated.\r\n+ * The system is in auto mode (AfModeAuto) and a scan has been\r\n+\t\t cancelled.\r\n+ - name: AfStateScanning\r\n+ value: 1\r\n+ description: |\r\n+ AF is performing a scan. This state can be entered spontaneously\r\n+ if AfMode is set to AfModeContinuous, otherwise it requires the\r\n+ application to use the AfTrigger control to start the scan.\r\n+ - name: AfStateFocused\r\n+ value: 2\r\n+ description: |\r\n+ An AF scan has been performed and the algorithm believes the\r\n+ scene is in focus.\r\n+ - name: AfStateFailed\r\n+ value: 3\r\n+ description: |\r\n+ An AF scan has been performed but the algorithm has not been able\r\n+ to find the best focus position.\r\n+\r\n ...","prefixes":["libcamera-devel","1/1"]}