{"id":15283,"url":"https://patchwork.libcamera.org/api/patches/15283/?format=json","web_url":"https://patchwork.libcamera.org/patch/15283/","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":"<20220118113750.19943-2-david.plowman@raspberrypi.com>","date":"2022-01-18T11:37:50","name":"[libcamera-devel,RFC,v2,1/1] libcamera: controls: Controls for driving AF (autofocus) algorithms","commit_ref":null,"pull_url":null,"state":"accepted","archived":false,"hash":"bd25ed0a3fa9d64b78985c69e5a4218b0c40ff65","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/15283/mbox/","series":[{"id":2895,"url":"https://patchwork.libcamera.org/api/series/2895/?format=json","web_url":"https://patchwork.libcamera.org/project/libcamera/list/?series=2895","date":"2022-01-18T11:37:49","name":"Autofocus controls","version":2,"mbox":"https://patchwork.libcamera.org/series/2895/mbox/"}],"comments":"https://patchwork.libcamera.org/api/patches/15283/comments/","check":"pending","checks":"https://patchwork.libcamera.org/api/patches/15283/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 9A6EAC325A\n\tfor ;\n\tTue, 18 Jan 2022 11:38:04 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 2FA9C60868;\n\tTue, 18 Jan 2022 12:38:04 +0100 (CET)","from mail-wm1-x32d.google.com (mail-wm1-x32d.google.com\n\t[IPv6:2a00:1450:4864:20::32d])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 7240E6017D\n\tfor ;\n\tTue, 18 Jan 2022 12:38:01 +0100 (CET)","by mail-wm1-x32d.google.com with SMTP id\n\ti187-20020a1c3bc4000000b0034d2ed1be2aso3589218wma.1\n\tfor ;\n\tTue, 18 Jan 2022 03:38:01 -0800 (PST)","from pi4-davidp.lan (plowpeople3.plus.com. [80.229.223.72])\n\tby smtp.gmail.com with ESMTPSA id\n\tr4sm2252169wmq.33.2022.01.18.03.38.00\n\t(version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n\tTue, 18 Jan 2022 03:38:00 -0800 (PST)"],"Authentication-Results":"lancelot.ideasonboard.com;\n\tdkim=fail reason=\"signature verification failed\" (2048-bit key;\n\tunprotected) header.d=raspberrypi.com header.i=@raspberrypi.com\n\theader.b=\"Czk3M5Vb\"; dkim-atps=neutral","DKIM-Signature":"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=mz/xadpgz4NW32YRr1tfkAjkvx/0BYaCIHR9BU/2Y0k=;\n\tb=Czk3M5VbfqeMp74Dz7wwxFdEJzMxPODYRl2ZvV08ZG//DEjSNc4NGSINIxfei4cirb\n\th0oCTQ0XqeC23V4I3roHzWn/GDH+0BgbC3tlcxWIp2Y0E6XXdfIJeZinCsjngdoULua0\n\txIbhxeFjzBjUhUXxjhSvK9QkUSQIRjHDZMRo0Cw+Vc94ycYAkyXsO2IdcpxulfS+Od9W\n\tr3lVUAebmBre9m9FwOhIPgiYhnMk3FwA/sP0ySJ8ECZi85CLJVaAcrMaKl74/oN+kLgz\n\t03txtWgeUHqLF0lckNp1lW4AAVK9OBPnd8M989bOcsVFvgADK8cvJy3OAXx+fA7FNhIq\n\tOltg==","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=mz/xadpgz4NW32YRr1tfkAjkvx/0BYaCIHR9BU/2Y0k=;\n\tb=gKlw1EBw5IIWMiTAHBckPCoCO7HGXPjxX8i3cAHmcLXlUlYXb/aM4OxABxZ46jXiP3\n\te9Rz6M+uHU9TxSCQeD6At+hIlwR9tRs9rfcoi81zsZt4kXmXl/NxNZOtInn5R54EgLRq\n\tnNXnA3eLDYRoa1OGKTcMRzoClg2On/gnawF0bjpvjk1VgzS64KUuG5hvR5Ke1YL/65Fc\n\t7B3034/WP3aMhaPZD7VBTtscQqhLvZXGghC54uqjxaKjyFZx6od7a0T532/5SoJF78BF\n\tgoJ+bQaqJznaUTiCzLmsz0uZCtmnUc/JggqqxDEAx+ovWoAmHuePFxN9dfB6Pw4CBYUe\n\tNmJw==","X-Gm-Message-State":"AOAM531uMEIy9C+6fKt4QFuLiSLqJg5jO1ZDJLFCgccDCIHtclzKy636\n\ti6cdf1Ab2+dja+JXKrKGXgEjTCStoQPv0KJr","X-Google-Smtp-Source":"ABdhPJx5piK8QjmTrteaVmTROkc8HkxZesGG6hW7M7vCjJeGwm7ILmnfTB0tXKDFbXD43WWm5ZZQfg==","X-Received":"by 2002:a5d:4f85:: with SMTP id d5mr23679473wru.51.1642505880879;\n\tTue, 18 Jan 2022 03:38:00 -0800 (PST)","From":"David Plowman ","To":"libcamera-devel@lists.libcamera.org","Date":"Tue, 18 Jan 2022 11:37:50 +0000","Message-Id":"<20220118113750.19943-2-david.plowman@raspberrypi.com>","X-Mailer":"git-send-email 2.30.2","In-Reply-To":"<20220118113750.19943-1-david.plowman@raspberrypi.com>","References":"<20220118113750.19943-1-david.plowman@raspberrypi.com>","MIME-Version":"1.0","Content-Transfer-Encoding":"8bit","Subject":"[libcamera-devel] [RFC PATCH v2 1/1] libcamera: controls: Controls\n\tfor driving 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","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\nAfMethod - single or multi-spot\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 | 295 ++++++++++++++++++++++++++-------\n 1 file changed, 235 insertions(+), 60 deletions(-)","diff":"diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml\nindex 9d4638ae..0b5ea9bd 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,239 @@ 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. Furthermore, setting the mode to\n+ the value it currently has is also permitted (with no effect).\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+\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+\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+\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+\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+ - 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+ - AfMethod:\n+ type: int32_t\n+ draft: true\n+ description: |\n+ Control whether the AF algorithm uses a single window in the image to\n+ determine the best focus position, or multiple windows simultaneously.\n+ enum:\n+ - name: AfMethodSingle\n+ value: 0\n+ description: |\n+ A single window within the image, defaulting to the centre, is used\n+ to select the best focus distance.\n+ - name: AfMethodMultiSpot\n+ value: 0\n+ description: |\n+ Multiple windows within the image are used to select the best focus\n+ distance. The best focus distance is found for each one of the\n+ windows, and then the distance that is closest to the camera is\n+ selected.\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+ 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+ If AfMethod is set to AfMethodSingle, then only the first Rectangle in\n+ this list is used (or the system default one if it is unprogrammed).\n+\n+ If AfMethod is set to AfMethodMultiSpot then all the valid Rectangles in\n+ this list are used. The size of the control indicates how many such\n+ windows can be programmed and will vary between different platforms.\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+ - 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+ - name: AfPauseResume\n+ value: 2\n+ description: |\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+\t \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+\n ...\n","prefixes":["libcamera-devel","RFC","v2","1/1"]}