From patchwork Mon Dec 13 15:22:15 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: David Plowman X-Patchwork-Id: 15153 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id B90E9C324B for ; Mon, 13 Dec 2021 15:22:26 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id DD1A26088B; Mon, 13 Dec 2021 16:22:25 +0100 (CET) Authentication-Results: lancelot.ideasonboard.com; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=raspberrypi.com header.i=@raspberrypi.com header.b="nzpet0Ls"; dkim-atps=neutral Received: from mail-wm1-x333.google.com (mail-wm1-x333.google.com [IPv6:2a00:1450:4864:20::333]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 9A32260868 for ; Mon, 13 Dec 2021 16:22:23 +0100 (CET) Received: by mail-wm1-x333.google.com with SMTP id g191-20020a1c9dc8000000b0032fbf912885so11812269wme.4 for ; Mon, 13 Dec 2021 07:22:23 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=raspberrypi.com; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=fkhg6BHriXrb+JRmK2yyd/0fIdV9HDaP/XBoe6qVfJk=; b=nzpet0LsJQX2D49PWrdgEfGJDq7h9McpXSEPeMuSS5/61jGbpTYYermLfE+Mxrvn4G XR3kAnK3jcyYNDG0ImT8OHE5AFZP1K8WVbjTYwPBR521gO5HAvO3oSEKq/1Fuhfep/zF nbLUyHR8fOISy1HO91/CIasBD4a/H0LmMHo06bDutJOD7QQ1P5N+8jMi7dr2wdL0Wl2V aqmfAmLpCQjWfuC6w7NpuLiJFJAzM8y4qNV1o+K9vgPQ6YKtzO319HGGMeUCL9s42NlT Gf6tDCq+Q2Ipc+v3A96GyGyEz/VsL/lIBu7JPIBW1nnoaCssrp+SK8sfsDHxjst7eqog RQTg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=fkhg6BHriXrb+JRmK2yyd/0fIdV9HDaP/XBoe6qVfJk=; b=0EMPLemOrKPh/UG2kOG7twWw77eWQB5qt9+n7DVLwvxagOYFdMTQ7fHIyjBrtIh/A2 4CkNqrxb7hRVcQQwd7a0peVpp3f2iKRkPWAn5vWu/WgXZ05hfVqwLJf5CDJYXXYvXdxT NqBhrR9l/pKDo9W36mCUUp5v+fIRCEzm7Ra2WX0/4sq1pStF90fCuAqwxWb8RFGO59M5 JP639k5H6ylTCVKA5wekfI/HJHdI156zmrVQHt3QjX4V5Q2rh8Ri8EJgVYiBoLxxnEIQ 0g66BsaeqiC7ZIkBgD6PNa/OZUoIyOj2jU7G5XKAXISxMwNE7Yjn4yXfFHayYVZN/KEW JTEg== X-Gm-Message-State: AOAM530AaMdd86hmgCV73KX2kXCS0EJBBpKlTVIY5zdHrMtVZhxWxT7O 2+qXopw4ULzGAWr7qIHaemlI5JbQT2PJuw== X-Google-Smtp-Source: ABdhPJwOWQG/nmSQF6nyUQSDSEL/16eEyfi1TahvnbhnuY+NSH4bZUNnZIW7M2yX9x9Vt6E8O/YmyQ== X-Received: by 2002:a1c:2685:: with SMTP id m127mr38655438wmm.42.1639408942846; Mon, 13 Dec 2021 07:22:22 -0800 (PST) Received: from pi4-davidp.pitowers.org ([2a00:1098:3142:14:e4a2:3070:eea4:e434]) by smtp.gmail.com with ESMTPSA id u2sm13001060wrs.17.2021.12.13.07.22.22 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 13 Dec 2021 07:22:22 -0800 (PST) From: David Plowman To: libcamera-devel@lists.libcamera.org Date: Mon, 13 Dec 2021 15:22:15 +0000 Message-Id: <20211213152215.17584-2-david.plowman@raspberrypi.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20211213152215.17584-1-david.plowman@raspberrypi.com> References: <20211213152215.17584-1-david.plowman@raspberrypi.com> MIME-Version: 1.0 Subject: [libcamera-devel] [RFC PATCH 1/1] libcamera: controls: Controls for driving AF (autofocus) algorithms X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" This patch describes a series of controls that allow applications to drive AF algorithms: AfMode - auto or continuous AfRange - full, macro or normal AfSpeed - fast or slow AfMethod - single or multi-spot AfWindow - AF window locations AfTrigger - start (trigger an AF scan) or cancel LensPosition - position of lens from lens driver AfState - reset, scanning, focused or failed --- src/libcamera/control_ids.yaml | 227 ++++++++++++++++++++++++--------- 1 file changed, 167 insertions(+), 60 deletions(-) diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml index 9d4638ae..e579f7b7 100644 --- a/src/libcamera/control_ids.yaml +++ b/src/libcamera/control_ids.yaml @@ -406,27 +406,6 @@ controls: The camera will cancel any active or completed metering sequence. The AE algorithm is reset to its initial state. - - AfTrigger: - type: int32_t - draft: true - description: | - Control for AF trigger. Currently identical to - ANDROID_CONTROL_AF_TRIGGER. - - Whether the camera device will trigger autofocus for this request. - enum: - - name: AfTriggerIdle - value: 0 - description: The trigger is idle. - - name: AfTriggerStart - value: 1 - description: The AF routine is started by the camera. - - name: AfTriggerCancel - value: 2 - description: | - The camera will cancel any active trigger and the AF routine is - reset to its initial state. - - NoiseReductionMode: type: int32_t draft: true @@ -507,45 +486,6 @@ controls: The AE algorithm has started a pre-capture metering session. \sa AePrecaptureTrigger - - AfState: - type: int32_t - draft: true - description: | - Control to report the current AF algorithm state. Currently identical to - ANDROID_CONTROL_AF_STATE. - - Current state of the AF algorithm. - enum: - - name: AfStateInactive - value: 0 - description: The AF algorithm is inactive. - - name: AfStatePassiveScan - value: 1 - description: | - AF is performing a passive scan of the scene in continuous - auto-focus mode. - - name: AfStatePassiveFocused - value: 2 - description: | - AF believes the scene is in focus, but might restart scanning. - - name: AfStateActiveScan - value: 3 - description: | - AF is performing a scan triggered by an AF trigger request. - \sa AfTrigger - - name: AfStateFocusedLock - value: 4 - description: | - AF believes has focused correctly and has locked focus. - - name: AfStateNotFocusedLock - value: 5 - description: | - AF has not been able to focus and has locked. - - name: AfStatePassiveUnfocused - value: 6 - description: | - AF has completed a passive scan without finding focus. - - AwbState: type: int32_t draft: true @@ -690,4 +630,171 @@ controls: value. All of the custom test patterns will be static (that is the raw image must not vary from frame to frame). + - AfMode: + type: int32_t + draft: true + description: | + Control to set the mode of the AF (autofocus) algorithm. + enum: + - name: AfModeAuto + value: 0 + description: | + The AF algorithm is in auto mode. This means that the algorithm + will never move the lens or change state unless the AfTrigger + control is used. The AfTrigger control can be used to initiate a + focus scan, the results of which will be reported by the AfState. + + In this mode, an application can move the lens for itself using + the LensPosition control. If the algorithm was scanning when the + lens is moved in this way, then the scan is implicitly cancelled. + - name: AfModeContinuous + value: 1 + description: | + The AF algorithm is in continuous mode. This means that the lens + can re-start a scan spontaneously at any moment, without any user + intervention. The AfState still reports whether the algorithm is + currently scanning or not, though the application has no ability + to initiate or cancel scans, nor move the lens for itself. + + The mode can be set to AfModeAuto which has the effect of + "pausing" any continuous AF activity, after which it could then + be moved back to AfModeContinuous to resume operation. + + - AfRange: + type: int32_t + draft: true + description: | + Control to set the range of focus distances that is scanned. + enum: + - name: AfRangeFull + value: 0 + description: The full range of focus distances is scanned. + - name: AfRangeMacro + value: 1 + description: Only close distances are scanned. + - name: AfRangeNormal + value: 2 + description: | + The full range of focus distances is scanned except for some of + the closest macro positions. + + - AfSpeed: + type: int32_t + draft: true + description: | + Control that determines whether the AF algorithm is to move the lens + as quickly as possible or more steadily. For example, during video + recording it may be desirable not to move the lens too abruptly, but + when in a preview mode (waiting for a still capture) it may be + helpful to move the lens as quickly as is reasonably possible. + enum: + - name: AfSpeedFast + value: 0 + description: Move the lens quickly. + - name: AfSpeedSlow + value: 0 + description: Move the lens more steadily. + + - AfMethod: + type: int32_t + draft: true + description: | + Control whether the AF algorithm uses a single window in the image to + determine the best focus position, or multiple windows simultaneously. + enum: + - name: AfMethodSingle + value: 0 + description: | + A single window within the image, defaulting to the centre, is used + to select the best focus distance. + - name: AfMethodMultiSpot + value: 0 + description: | + Multiple windows within the image are used to select the best focus + distance. The best focus distance is found for each one of the + windows, and then the distance that is closest to the camera is + selected. + + - AfWindow: + type: Rectangle + draft: true + description: | + Sets the focus windows used by the AF algorithm. The units used express + a proportion of the ScalerCrop control (or if unavailable, of the entire + image), as u0.16 format numbers. + + In order to be activated, a rectangle must be programmed with non-zero + width and height. If no rectangles are programmed in this way, then the + system will choose its own single default window in the centre of the + image. + + If AfMethod is set to AfMethodSingle, then only the first Rectangle in + this list is used (or the system default one if it is unprogrammed). + + If AfMethod is set to AfMethodMultiSpot then all the valid Rectangles in + this list are used. The size of the control indicates how many such + windows can be programmed and will vary between different platforms. + + size: [platform dependent] + + - AfTrigger: + type: int32_t + draft: true + description: | + This control starts an autofocus scan when AfMode is set to AfModeAuto, + and can also be used to terminate a scan early. + + It is ignored if AfMode is set to AfModeContinuous. + + enum: + - name: AfTriggerStart + value: 0 + description: Start an AF scan. Ignored if a scan is in progress. + - name: AfTriggerCancel + value: 1 + description: Cancel an AF scan. Ingored if no scan is in progress. + + - LensPosition: + type: int32_t + draft: true + description: | + Acts as a control to instruct the lens to move to a particular position + and also reports back the position of the lens for each frame. + + The units are determined by the lens driver. + + If the LensPosition control is used while an AF scan is in progress, + the scan is implicitly cancelled and the lens is then moved to the + desired location. It is ignored if AfMode is set to AfModeContinuous. + + - AfState: + type: int32_t + draft: true + description: | + Reports the current state of the AF algorithm. + enum: + - name: AfStateReset + value: 0 + description: | + The AF algorithm reports this state when: + * The camera system has just been started. + * A scan has been cancelled. + * The lens has been moved by the LensPosition control. + - name: AfStateScanning + value: 1 + description: | + AF is performing a scan. This state can be entered spontaneously + if AfMode is set to AfModeContinuous, otherwise it requires the + application to use the AfTrigger control to start the scan. + - name: AfStateFocused + value: 2 + description: | + An AF scan has been performed and the algorithm believes the + scene is in focus. + - name: AfStateFailed + value: 3 + description: | + An AF scan has been performed but the algorithm has not been able + to find the best focus position. + ...