From patchwork Fri Jul 1 15:46:53 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jacopo Mondi X-Patchwork-Id: 16511 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 CD13CBD808 for ; Fri, 1 Jul 2022 15:47:09 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 1EDCA6564B; Fri, 1 Jul 2022 17:47:09 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1656690429; bh=OsqbNL+ygZCUWbd+OUr+JnjJsV2yynWegpQps1cBmDI=; h=To:Date:In-Reply-To:References:Subject:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=gTNj4JIUGiywRutm6QmzBKxsE8Ubd/NUqhAP3rbKDhhWEYeaDjmKnC0iU6pPLNyl3 YxYB6jWgDHCoyKvasizDzM4xX2j/M+QXbFFfvOSbC5XinpIp/5XOT6Ri7wa5a+LFAA gw6x6rusOGYZUlRZD2d9ZQ1uvKepKSkcYYcIH9QD6jHr54m+DlenF9grrBe6YCGJeN 91zX3Ho1drL52DpAQkCup/6VD6HgF2oc9zGGn/ew5x4JY4Kd29ot+4CZgmJZ6DoBEc Sf0Y7AV90ygsVxHfFr5qG0dwARsmXehDCZ5w80ocf5yn7iGyA3IU7jC8c5FZ+BT2p/ yqvhRC9MBwkHA== Received: from relay4-d.mail.gandi.net (relay4-d.mail.gandi.net [IPv6:2001:4b98:dc4:8::224]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 7CAB560552 for ; Fri, 1 Jul 2022 17:47:07 +0200 (CEST) Received: (Authenticated sender: jacopo@jmondi.org) by mail.gandi.net (Postfix) with ESMTPSA id 012DAE0004; Fri, 1 Jul 2022 15:47:06 +0000 (UTC) To: libcamera-devel@lists.libcamera.org Date: Fri, 1 Jul 2022 17:46:53 +0200 Message-Id: <20220701154701.354052-1-jacopo@jmondi.org> X-Mailer: git-send-email 2.36.1 In-Reply-To: <20220518134728.777709-2-paul.elder@ideasonboard.com> References: <20220518134728.777709-2-paul.elder@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH 1/9] controls: Reorganize the AE-related controls 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: , X-Patchwork-Original-From: Jacopo Mondi via libcamera-devel From: Jacopo Mondi Reply-To: Jacopo Mondi Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" From: Paul Elder via libcamera-devel We have multiple goals: - we need a lock of some sort, to instruct the AEGC to not update output results - we need manual modes, to override the values computed by the AEGC - we need to support seamless transitions from auto -> manual, and do so without flickering - we need custom minimum values for the manual controls, that is no magic values for enabling/disabling auto - all of these need to be done with AE sub-controls (exposure time, analogue gain) To achieve these goals, we introduce mode controls for the AE sub-controls: ExposureTimeMode and AnalogueGainMode. These have an auto state, and a disabled state. The disabled state has an internal one-way state change from locked to manual, triggered by the presence of the value-controls (ExposureTime and AnalogueGain). We then remove the AeEnable control, as it is a redundant control in the face of these two mode controls. We also remove AeLocked, as it is insufficient for reporting the AE state, and we promote AeState to non-draft to fill its role. Notably, the locked state is removed, since this information can be obtained from the aforementioned mode controls. Bug: https://bugs.libcamera.org/show_bug.cgi?id=42 Bug: https://bugs.libcamera.org/show_bug.cgi?id=43 Bug: https://bugs.libcamera.org/show_bug.cgi?id=47 Signed-off-by: Paul Elder --- src/libcamera/control_ids.yaml | 262 +++++++++++++++++++++++++-------- 1 file changed, 200 insertions(+), 62 deletions(-) diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml index ecab3ae97260..21275fcb9a83 100644 --- a/src/libcamera/control_ids.yaml +++ b/src/libcamera/control_ids.yaml @@ -7,23 +7,46 @@ # Unless otherwise stated, all controls are bi-directional, i.e. they can be # set through Request::controls() and returned out through Request::metadata(). controls: - - AeEnable: - type: bool + - AeState: + type: int32_t description: | - Enable or disable the AE. + Control to report the AE algorithm state associated with the capture + result. - \sa ExposureTime AnalogueGain + The state is still reported even if ExposureTimeMode or + AnalogueGainMode is set to Disabled. - - AeLocked: - type: bool - description: | - Report the lock status of a running AE algorithm. + \sa AnalogueGain + \sa AnalogueGainMode + \sa ExposureTime + \sa ExposureTimeMode - If the AE algorithm is locked the value shall be set to true, if it's - converging it shall be set to false. If the AE algorithm is not - running the control shall not be present in the metadata control list. + enum: + - name: AeStateInactive + value: 0 + description: | + The AE algorithm is inactive. - \sa AeEnable + This state should be returned if both AnalogueGainMode and + ExposureTimeMode are set to disabled (or one, if the camera only + supports one of the two controls). + - name: AeStateSearching + value: 1 + description: | + The AE algorithm has not converged yet. + + This state should be returned if at least one of AnalogueGainMode + or ExposureTimeMode is set to auto, and the AE algorithm hasn't + converged yet. If the AE algorithm converges, the state shall go to + AeStateConverged. + - name: AeStateConverged + value: 2 + description: | + The AE algorithm has converged. + + This state should be returned if at least one of AnalogueGainMode + or ExposureTimeMode is set to auto, and the AE algorithm has + converged. # AeMeteringMode needs further attention: # - Auto-generate max enum value. @@ -93,6 +116,13 @@ controls: how the desired total exposure is divided between the shutter time and the sensor's analogue gain. The exposure modes are platform specific, and not all exposure modes may be supported. + + When one of AnalogueGainMode or ExposureTimeMode is set to Disabled, + the fixed values will override any choices made by AeExposureMode. + + \sa AnalogueGainMode + \sa ExposureTimeMode + enum: - name: ExposureNormal value: 0 @@ -111,13 +141,15 @@ controls: type: float description: | Specify an Exposure Value (EV) parameter. The EV parameter will only be - applied if the AE algorithm is currently enabled. + applied if the AE algorithm is currently enabled, that is, at least one + of AnalogueGainMode and ExposureTimeMode are auto. By convention EV adjusts the exposure as log2. For example EV = [-2, -1, 0.5, 0, 0.5, 1, 2] results in an exposure adjustment of [1/4x, 1/2x, 1/sqrt(2)x, 1x, sqrt(2)x, 2x, 4x]. - \sa AeEnable + \sa AnalogueGainMode + \sa ExposureTimeMode - ExposureTime: type: int32_t @@ -125,17 +157,85 @@ controls: Exposure time (shutter speed) for the frame applied in the sensor device. This value is specified in micro-seconds. - Setting this value means that it is now fixed and the AE algorithm may - not change it. Setting it back to zero returns it to the control of the - AE algorithm. + This control will only take effect if ExposureTimeMode is Disabled. If + this control is set when ExposureTimeMode is Auto, the value will be + ignored and will not be retained. + + When reported in metadata, this control indicates what exposure time + was used for the current request, regardless of ExposureTimeMode. + ExposureTimeMode will indicate the source of the exposure time value, + whether it came from the AE algorithm or not. + + \sa AnalogueGain + \sa ExposureTimeMode + + - ExposureTimeMode: + type: int32_t + description: | + Controls the source of the exposure time that is applied to the image + sensor. When set to Auto, the AE algorithm computes the exposure time + and configures the image sensor accordingly. When set to Disabled, + exposure time specified in ExposureTime is applied to the image sensor. + If ExposureTime is not set, then the value last computed by the AE + algorithm when the mode was Auto will be used. + + If ExposureTime is not set and the mode is ExposureTimeModeDisabled and + AE was never Auto (either because the camera started in Disabled mode, + or Auto is not supported by the camera), the camera should use a + best-effort default value. + + When ExposureTimeMode is set Auto, the value set in ExposureTime is + ignored and is not retained. This means that if ExposureTimeMode is set + to Disabled and ExposureTime is not also set, the exposure time that + was last computed by the AE algorithm while the mode was Auto will be + applied to the sensor. + + If ExposureTimeModeDisabled is supported, the ExposureTime control must + also be supported. + + The set of ExposureTimeMode modes that are supported by the camera must + have an intersection with the supported set of AnalogueGainMode modes. - \sa AnalogueGain AeEnable + As it takes a few frames to apply the exposure time, there is a period of + time between submitting a request with ExposureTimeMode set to Disabled + and the exposure time component of the AE actually being disabled, + during which the AE algorithm can still update the exposure time. If an + application is switching from automatic and manual control and wishes + to eliminate any flicker during the switch, the following procedure is + recommended. - \todo Document the interactions between AeEnable and setting a fixed - value for this control. Consider interactions with other AE features, - such as aperture and aperture/shutter priority mode, and decide if - control of which features should be automatically adjusted shouldn't - better be handled through a separate AE mode control. + 1. Start with ExposureTimeMode set to Auto + + 2. Set ExposureTimeMode to Disabled + + 3. Wait for the first request to be output that has ExposureTimeMode + set to Disabled + + 4. Copy the value reported in ExposureTime into a new request, and + submit it + + 5. Proceed to run manual exposure time + + \sa ExposureTime + enum: + - name: ExposureTimeModeAuto + value: 0 + description: | + The exposure time will be calculated automatically and set by the + AE algorithm. If ExposureTime is set while this mode is active, it + will be ignored, and it will also not be retained. + - name: ExposureTimeModeDisabled + value: 1 + description: | + The exposure time will not be updated by the AE algorithm. It will + come from the last calculated value when the mode was Auto, or from + the value specified in ExposureTime. + + When transitioning from Auto to Disabled mode, the last computed + exposure value is used until a new value is specified through the + ExposureTime control. If an ExposureTime value is specified in the + same request where the ExposureTimeMode is changed from Auto to + Disabled, the provided ExposureTime is applied. - AnalogueGain: type: float @@ -144,17 +244,85 @@ controls: The value of the control specifies the gain multiplier applied to all colour channels. This value cannot be lower than 1.0. - Setting this value means that it is now fixed and the AE algorithm may - not change it. Setting it back to zero returns it to the control of the - AE algorithm. + This control will only take effect if AnalogueGainMode is Disabled. If + this control is set when AnalogueGainMode is Auto, the value will be + ignored and will not be retained. + + When reported in metadata, this control indicates what analogue gain + was used for the current request, regardless of AnalogueGainMode. + AnalogueGainMode will indicate the source of the analogue gain value, + whether it came from the AE algorithm or not. + + \sa ExposureTime + \sa AnalogueGainMode + + - AnalogueGainMode: + type: int32_t + description: | + Controls the source of the analogue gain that is applied to the image + sensor. When set to Auto, the AE algorithm computes the analogue gain + and configures the image sensor accordingly. When set to Disabled, + analogue gain specified in AnalogueGain is applied to the image sensor. + If AnalogueGain is not set, then the value last computed by the AE + algorithm when the mode was Auto will be used. + + If AnalogueGain is not set and the mode is AnalogueGainModeDisabled and + AE was never Auto (either because the camera started in Disabled mode, + or Auto is not supported by the camera), the camera should use a + best-effort default value. + + When AnalogueGainMode is set Auto, the value set in AnalogueGain is + ignored and is not retained. This means that if AnalogueGainMode is set + to Disabled and AnalogueGain is not also set, the analogue gain that + was last computed by the AE algorithm while the mode was Auto will be + applied to the sensor. - \sa ExposureTime AeEnable + If AnalogueGainModeDisabled is supported, the AnalogueGain control must + also be supported. + + The set of AnalogueGainMode modes that are supported by the camera must + have an intersection with the supported set of ExposureTimeMode modes. + + As it takes a few frames to apply the analogue gain, there is a period of + time between submitting a request with AnalogueGainMode set to Disabled + and the analogue gain component of the AE actually being disabled, + during which the AE algorithm can still update the analogue gain. If an + application is switching from automatic and manual control and wishes + to eliminate any flicker during the switch, the following procedure is + recommended. + + 1. Start with AnalogueGainMode set to Auto + + 2. Set AnalogueGainMode to Disabled + + 3. Wait for the first request to be output that has AnalogueGainMode + set to Disabled + + 4. Copy the value reported in AnalogueGain into a new request, and + submit it + + 5. Proceed to run manual analogue gain + + \sa AnalogueGain + enum: + - name: AnalogueGainModeAuto + value: 0 + description: | + The analogue gain will be calculated automatically and set by the + AE algorithm. If AnalogueGain is set while this mode is active, it + will be ignored, and it will also not be retained. + - name: AnalogueGainModeDisabled + value: 1 + description: | + The analogue gain will not be updated by the AE algorithm. It will + come from the last calculated value when the mode was Auto, or from + the value specified in AnalogueGain. - \todo Document the interactions between AeEnable and setting a fixed - value for this control. Consider interactions with other AE features, - such as aperture and aperture/shutter priority mode, and decide if - control of which features should be automatically adjusted shouldn't - better be handled through a separate AE mode control. + When transitioning from Auto to Disabled mode the last computed + gain value is used until a new value is specified through the + AnalogueGain control. If an AnalogueGain value is specified in the + same request where the AnalogueGainMode is set to Disabled, the + provided AnalogueGain is applied. - Brightness: type: float @@ -767,36 +935,6 @@ controls: High quality aberration correction which might reduce the frame rate. - - AeState: - type: int32_t - draft: true - description: | - Control to report the current AE algorithm state. Currently identical to - ANDROID_CONTROL_AE_STATE. - - Current state of the AE algorithm. - enum: - - name: AeStateInactive - value: 0 - description: The AE algorithm is inactive. - - name: AeStateSearching - value: 1 - description: The AE algorithm has not converged yet. - - name: AeStateConverged - value: 2 - description: The AE algorithm has converged. - - name: AeStateLocked - value: 3 - description: The AE algorithm is locked. - - name: AeStateFlashRequired - value: 4 - description: The AE algorithm would need a flash for good results - - name: AeStatePrecapture - value: 5 - description: | - The AE algorithm has started a pre-capture metering session. - \sa AePrecaptureTrigger - - AwbState: type: int32_t draft: true From patchwork Fri Jul 1 15:46:54 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jacopo Mondi X-Patchwork-Id: 16512 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 6F081BD808 for ; Fri, 1 Jul 2022 15:47:11 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id C031F6564E; Fri, 1 Jul 2022 17:47:09 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1656690429; bh=DsHQMiNjgW39Oo3k6j7HjI6IFzjD3edus4E8Vgi7zqA=; h=To:Date:In-Reply-To:References:Subject:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=UzZJa0Wm459ybpX/XxgxCfhi05YSTzoj5eamjoRYhDVI5rJCIy9pYgsxVuhaDE2hL oxBMSHVSogbUwp/7kXkFX4UduQHrEXxCVolRIUT/z/jHqAzMJwtWwQJrxpvNw7OtpO TEwEbQ3Gb5Ufwb50EmEmTP4EDjhrJdWezDMPYcKu1pbre5KS9rRegAzM0WgEZ6Kgqf NkqpnTTJZtJJ2J+X58eLrGFRzQUz/HkJhlvA8VytNZROLLHQUmNBuWxsW7B1mNw/Vs Dz8vZC7upg/oNmH2kADYO/XN8KOMtUnBVPs+IiY2q6kGbw8pMsnNgc9xH05HgIZxaD 7/PUfJZ+pDgNw== Received: from relay4-d.mail.gandi.net (relay4-d.mail.gandi.net [217.70.183.196]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 313B060552 for ; Fri, 1 Jul 2022 17:47:08 +0200 (CEST) Received: (Authenticated sender: jacopo@jmondi.org) by mail.gandi.net (Postfix) with ESMTPSA id 988F7E0005; Fri, 1 Jul 2022 15:47:07 +0000 (UTC) To: libcamera-devel@lists.libcamera.org Date: Fri, 1 Jul 2022 17:46:54 +0200 Message-Id: <20220701154701.354052-2-jacopo@jmondi.org> X-Mailer: git-send-email 2.36.1 In-Reply-To: <20220701154701.354052-1-jacopo@jmondi.org> References: <20220518134728.777709-2-paul.elder@ideasonboard.com> <20220701154701.354052-1-jacopo@jmondi.org> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH 2/9] fixup: Use the term 'Idle' for Ae/AnalogueGain state 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: , X-Patchwork-Original-From: Jacopo Mondi via libcamera-devel From: Jacopo Mondi Reply-To: Jacopo Mondi Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" The Auto-Focus controls use the word "Idle" in place of "Inactive". Use the same term for consistency. Signed-off-by: Jacopo Mondi Acked-by: Paul Elder --- src/libcamera/control_ids.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml index 21275fcb9a83..59770e63aead 100644 --- a/src/libcamera/control_ids.yaml +++ b/src/libcamera/control_ids.yaml @@ -22,7 +22,7 @@ controls: \sa ExposureTimeMode enum: - - name: AeStateInactive + - name: AeStateIdle value: 0 description: | The AE algorithm is inactive. @@ -944,7 +944,7 @@ controls: Current state of the AWB algorithm. enum: - - name: AwbStateInactive + - name: AwbStateIdle value: 0 description: The AWB algorithm is inactive. - name: AwbStateSearching From patchwork Fri Jul 1 15:46:55 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jacopo Mondi X-Patchwork-Id: 16513 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 A3CB2BD808 for ; Fri, 1 Jul 2022 15:47:12 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 5AE7065651; Fri, 1 Jul 2022 17:47:12 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1656690432; bh=1km8t/BvfrUvLPYwM9v37rUBS6Bl2/foVV9lOWkPbic=; h=To:Date:In-Reply-To:References:Subject:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=rkFkZKrt9dmg6o30g3L1BdKfmsZc5g7FZt5YqjyadF+JfL4NlQAqzeK8Cp5jYDrGR bCvEi3sZE7f7MEkICnvTKj2+4NQJVvDw6Y45H2ye+doYFjNsGDCz/zeb+aed841Wgu iMTcjNxylqKn4CA7XWG/eN5aOymQWeoX0FtvceJZzsQ1BRc18KsYHmPW0jdkpjfNGT 9DpaV4qdFcipLMJkYKItJDzhy8vePj3LM27RWcomlTKJ9lBkBq0xCP6Jo6Q534zclE dZRyDYVXqiUpjhePoLrADBVdeGfJNFixVDFPjMcfAC2/Erb42+jcHbF1xn+RB5JEYH M2ozlGn7HZ9UQ== Received: from relay4-d.mail.gandi.net (relay4-d.mail.gandi.net [217.70.183.196]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 2D2396564F for ; Fri, 1 Jul 2022 17:47:09 +0200 (CEST) Received: (Authenticated sender: jacopo@jmondi.org) by mail.gandi.net (Postfix) with ESMTPSA id 6A055E0005; Fri, 1 Jul 2022 15:47:08 +0000 (UTC) To: libcamera-devel@lists.libcamera.org Date: Fri, 1 Jul 2022 17:46:55 +0200 Message-Id: <20220701154701.354052-3-jacopo@jmondi.org> X-Mailer: git-send-email 2.36.1 In-Reply-To: <20220701154701.354052-1-jacopo@jmondi.org> References: <20220518134728.777709-2-paul.elder@ideasonboard.com> <20220701154701.354052-1-jacopo@jmondi.org> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH 3/9] fixup: s/Disabled/Manual for Exposure and Gain modes 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: , X-Patchwork-Original-From: Jacopo Mondi via libcamera-devel From: Jacopo Mondi Reply-To: Jacopo Mondi Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" The ExposureTimeMode and AnalogueGainMode controls define the following statues: - Auto - Disabled The AE algorithm modes should either be - Active vs Disabled: to highlight that the algorithm is active or not - Auto vs Manual: to highlight where the exposure time and analogue gain values are computed from Use the latter form and change AnalogueGainModeDisabled and ExposureTimeModeDisabled in AnalogueGainModeManual and ExposureTimeModeManual respectively. Signed-off-by: Jacopo Mondi Acked-by: Paul Elder --- src/libcamera/control_ids.yaml | 54 +++++++++++++++++----------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml index 59770e63aead..bb5eeb1507a9 100644 --- a/src/libcamera/control_ids.yaml +++ b/src/libcamera/control_ids.yaml @@ -14,7 +14,7 @@ controls: result. The state is still reported even if ExposureTimeMode or - AnalogueGainMode is set to Disabled. + AnalogueGainMode is set to Manual. \sa AnalogueGain \sa AnalogueGainMode @@ -28,7 +28,7 @@ controls: The AE algorithm is inactive. This state should be returned if both AnalogueGainMode and - ExposureTimeMode are set to disabled (or one, if the camera only + ExposureTimeMode are set to manual (or one, if the camera only supports one of the two controls). - name: AeStateSearching value: 1 @@ -117,7 +117,7 @@ controls: and the sensor's analogue gain. The exposure modes are platform specific, and not all exposure modes may be supported. - When one of AnalogueGainMode or ExposureTimeMode is set to Disabled, + When one of AnalogueGainMode or ExposureTimeMode is set to Manual, the fixed values will override any choices made by AeExposureMode. \sa AnalogueGainMode @@ -157,7 +157,7 @@ controls: Exposure time (shutter speed) for the frame applied in the sensor device. This value is specified in micro-seconds. - This control will only take effect if ExposureTimeMode is Disabled. If + This control will only take effect if ExposureTimeMode is Manual. If this control is set when ExposureTimeMode is Auto, the value will be ignored and will not be retained. @@ -174,30 +174,30 @@ controls: description: | Controls the source of the exposure time that is applied to the image sensor. When set to Auto, the AE algorithm computes the exposure time - and configures the image sensor accordingly. When set to Disabled, + and configures the image sensor accordingly. When set to Manual, exposure time specified in ExposureTime is applied to the image sensor. If ExposureTime is not set, then the value last computed by the AE algorithm when the mode was Auto will be used. - If ExposureTime is not set and the mode is ExposureTimeModeDisabled and - AE was never Auto (either because the camera started in Disabled mode, + If ExposureTime is not set and the mode is ExposureTimeModeManual and + AE was never Auto (either because the camera started in Manual mode, or Auto is not supported by the camera), the camera should use a best-effort default value. When ExposureTimeMode is set Auto, the value set in ExposureTime is ignored and is not retained. This means that if ExposureTimeMode is set - to Disabled and ExposureTime is not also set, the exposure time that + to Manual and ExposureTime is not also set, the exposure time that was last computed by the AE algorithm while the mode was Auto will be applied to the sensor. - If ExposureTimeModeDisabled is supported, the ExposureTime control must + If ExposureTimeModeManual is supported, the ExposureTime control must also be supported. The set of ExposureTimeMode modes that are supported by the camera must have an intersection with the supported set of AnalogueGainMode modes. As it takes a few frames to apply the exposure time, there is a period of - time between submitting a request with ExposureTimeMode set to Disabled + time between submitting a request with ExposureTimeMode set to Manual and the exposure time component of the AE actually being disabled, during which the AE algorithm can still update the exposure time. If an application is switching from automatic and manual control and wishes @@ -206,10 +206,10 @@ controls: 1. Start with ExposureTimeMode set to Auto - 2. Set ExposureTimeMode to Disabled + 2. Set ExposureTimeMode to Manual 3. Wait for the first request to be output that has ExposureTimeMode - set to Disabled + set to Manual 4. Copy the value reported in ExposureTime into a new request, and submit it @@ -224,18 +224,18 @@ controls: The exposure time will be calculated automatically and set by the AE algorithm. If ExposureTime is set while this mode is active, it will be ignored, and it will also not be retained. - - name: ExposureTimeModeDisabled + - name: ExposureTimeModeManual value: 1 description: | The exposure time will not be updated by the AE algorithm. It will come from the last calculated value when the mode was Auto, or from the value specified in ExposureTime. - When transitioning from Auto to Disabled mode, the last computed + When transitioning from Auto to Manual mode, the last computed exposure value is used until a new value is specified through the ExposureTime control. If an ExposureTime value is specified in the same request where the ExposureTimeMode is changed from Auto to - Disabled, the provided ExposureTime is applied. + Manual, the provided ExposureTime is applied. - AnalogueGain: type: float @@ -244,7 +244,7 @@ controls: The value of the control specifies the gain multiplier applied to all colour channels. This value cannot be lower than 1.0. - This control will only take effect if AnalogueGainMode is Disabled. If + This control will only take effect if AnalogueGainMode is Manual. If this control is set when AnalogueGainMode is Auto, the value will be ignored and will not be retained. @@ -261,30 +261,30 @@ controls: description: | Controls the source of the analogue gain that is applied to the image sensor. When set to Auto, the AE algorithm computes the analogue gain - and configures the image sensor accordingly. When set to Disabled, + and configures the image sensor accordingly. When set to Manual, analogue gain specified in AnalogueGain is applied to the image sensor. If AnalogueGain is not set, then the value last computed by the AE algorithm when the mode was Auto will be used. - If AnalogueGain is not set and the mode is AnalogueGainModeDisabled and - AE was never Auto (either because the camera started in Disabled mode, + If AnalogueGain is not set and the mode is AnalogueGainModeManual and + AE was never Auto (either because the camera started in Manual mode, or Auto is not supported by the camera), the camera should use a best-effort default value. When AnalogueGainMode is set Auto, the value set in AnalogueGain is ignored and is not retained. This means that if AnalogueGainMode is set - to Disabled and AnalogueGain is not also set, the analogue gain that + to Manual and AnalogueGain is not also set, the analogue gain that was last computed by the AE algorithm while the mode was Auto will be applied to the sensor. - If AnalogueGainModeDisabled is supported, the AnalogueGain control must + If AnalogueGainModeManual is supported, the AnalogueGain control must also be supported. The set of AnalogueGainMode modes that are supported by the camera must have an intersection with the supported set of ExposureTimeMode modes. As it takes a few frames to apply the analogue gain, there is a period of - time between submitting a request with AnalogueGainMode set to Disabled + time between submitting a request with AnalogueGainMode set to Manual and the analogue gain component of the AE actually being disabled, during which the AE algorithm can still update the analogue gain. If an application is switching from automatic and manual control and wishes @@ -293,10 +293,10 @@ controls: 1. Start with AnalogueGainMode set to Auto - 2. Set AnalogueGainMode to Disabled + 2. Set AnalogueGainMode to Manual 3. Wait for the first request to be output that has AnalogueGainMode - set to Disabled + set to Manual 4. Copy the value reported in AnalogueGain into a new request, and submit it @@ -311,17 +311,17 @@ controls: The analogue gain will be calculated automatically and set by the AE algorithm. If AnalogueGain is set while this mode is active, it will be ignored, and it will also not be retained. - - name: AnalogueGainModeDisabled + - name: AnalogueGainModeManual value: 1 description: | The analogue gain will not be updated by the AE algorithm. It will come from the last calculated value when the mode was Auto, or from the value specified in AnalogueGain. - When transitioning from Auto to Disabled mode the last computed + When transitioning from Auto to Manual mode the last computed gain value is used until a new value is specified through the AnalogueGain control. If an AnalogueGain value is specified in the - same request where the AnalogueGainMode is set to Disabled, the + same request where the AnalogueGainMode is set to Manual, the provided AnalogueGain is applied. - Brightness: From patchwork Fri Jul 1 15:46:56 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jacopo Mondi X-Patchwork-Id: 16514 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 64C90BD808 for ; Fri, 1 Jul 2022 15:47:13 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id F272060552; Fri, 1 Jul 2022 17:47:12 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1656690433; bh=8+mjGh/cZe4Q9GRaFWOee11yeJjmwD+zRJWhHyGBLSQ=; h=To:Date:In-Reply-To:References:Subject:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=rHn4ZPwpQj4mNt1Fq7eMh1KsZmC+j7PIpVWTxbwXGe80er0TOuwGETPNNa3iKGEmF 87J2d5jAfDG8CHmrgqAfymfpOh95LDs5SSMNnrfvqUdkW5E6GeACZLQGTLEBrqpxPb 56CCNjBcTbDpXA1NNbPTNJLFOze0jhutMTaZTfGnhdroO1oBAMbxH7I5SIzophdoYd acTxMZVjNU+uDtMQlgFcMyJ45nzwqWszw0qkLgZy8AfTGMWkTAs/VNNlL4r/J639in UXfljACaKGfxPXSM54aEl06nceMsUTgdUfA6kEhE7kJ1voxRW9tczFmvvHXC4ru1pi KQ3xEfPAtSMAg== Received: from relay4-d.mail.gandi.net (relay4-d.mail.gandi.net [217.70.183.196]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id D544B65651 for ; Fri, 1 Jul 2022 17:47:09 +0200 (CEST) Received: (Authenticated sender: jacopo@jmondi.org) by mail.gandi.net (Postfix) with ESMTPSA id 3D3B6E000E; Fri, 1 Jul 2022 15:47:09 +0000 (UTC) To: libcamera-devel@lists.libcamera.org Date: Fri, 1 Jul 2022 17:46:56 +0200 Message-Id: <20220701154701.354052-4-jacopo@jmondi.org> X-Mailer: git-send-email 2.36.1 In-Reply-To: <20220701154701.354052-1-jacopo@jmondi.org> References: <20220518134728.777709-2-paul.elder@ideasonboard.com> <20220701154701.354052-1-jacopo@jmondi.org> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH 4/9] fixup: Expand AeState documentation 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: , X-Patchwork-Original-From: Jacopo Mondi via libcamera-devel From: Jacopo Mondi Reply-To: Jacopo Mondi Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" The AeState control is tricky, it describes the state of the whole AEGC block which is independently controlled by ExposureTimeMode and AnalogueGainMode. Try to expand the documentation. Use "AEGC" when referring to the algorithm. Maybe the control should be named AEGCState ? Signed-off-by: Jacopo Mondi --- src/libcamera/control_ids.yaml | 64 ++++++++++++++++++++++++---------- 1 file changed, 46 insertions(+), 18 deletions(-) diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml index bb5eeb1507a9..d50df8bcad28 100644 --- a/src/libcamera/control_ids.yaml +++ b/src/libcamera/control_ids.yaml @@ -10,43 +10,71 @@ controls: - AeState: type: int32_t description: | - Control to report the AE algorithm state associated with the capture - result. + Control to report the AEGC algorithm state. - The state is still reported even if ExposureTimeMode or - AnalogueGainMode is set to Manual. + The AEGC algorithm computes the exposure time and the analogue gain + values to be applied to the image sensor. + + The AEGC algorithm behaviour is controlled by the ExposureTimeMode and + AnalogueGainMode controls, which allow applications to decide how + the exposure time and gain are computed, in Auto or Manual mode, + independently one from the other. + + The AeState control reports the AEGC algorithm state through a single + value and describes it a single computation block which computes + both the exposure time and the analogue gain values. + + When both the exposure time and analogue gain values are configured to + be in Manual mode, the AEGC algorithm is quiescent and does not actively + compute any value and the AeState control will report AeStateIdle. + + When at least the exposure time or analogue gain are configured to be + computed by the AEGC algorithm, the AeState control will report if the + algorithm has converged to stable values for any of the controls set + to be computed in Auto mode. - \sa AnalogueGain \sa AnalogueGainMode - \sa ExposureTime \sa ExposureTimeMode enum: - name: AeStateIdle value: 0 description: | - The AE algorithm is inactive. + The AEGC algorithm is inactive. + + This state is returned when both AnalogueGainMode and + ExposureTimeMode are set to Manual and the algorithm is not + actively computing any value. - This state should be returned if both AnalogueGainMode and - ExposureTimeMode are set to manual (or one, if the camera only - supports one of the two controls). + When ExposureTimeMode or AnalogueGainMode are set to Auto mode, the + AEGC algorithm might spontaneously initiate a new scan, in which + case the AeState control is moved to AeStateSearching. - name: AeStateSearching value: 1 description: | - The AE algorithm has not converged yet. + The AEGC algorithm is actively computing new values, for either the + exposure time or the analogue gain, but has not converged to a + stable result yet. + + This state is returned if at least one of AnalogueGainMode + or ExposureTimeMode is set to auto and the algorithm hasn't + converged yet. - This state should be returned if at least one of AnalogueGainMode - or ExposureTimeMode is set to auto, and the AE algorithm hasn't - converged yet. If the AE algorithm converges, the state shall go to - AeStateConverged. + The AEGC algorithm converges once stable values are computed for + any of the controls set to be computed in Auto mode. + + Once the algorithm converges the state is moved to AeStateConverged. - name: AeStateConverged value: 2 description: | The AE algorithm has converged. - This state should be returned if at least one of AnalogueGainMode - or ExposureTimeMode is set to auto, and the AE algorithm has - converged. + This state is returned if at least one of AnalogueGainMode + or ExposureTimeMode is set to Auto, and the AEGC algorithm has + converged to stable value. + + The AEGC algorithm might spontaneously re-initiate an AE scan, in + which case the state is moved to AeStateSearching. # AeMeteringMode needs further attention: # - Auto-generate max enum value. From patchwork Fri Jul 1 15:46:57 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jacopo Mondi X-Patchwork-Id: 16515 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 63EE3BD808 for ; Fri, 1 Jul 2022 15:47:14 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id E4C4D6565E; Fri, 1 Jul 2022 17:47:13 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1656690434; bh=IdHLsxMWsl/TjEJQaN15z6pLvOL7sLCkmUKZg9a+Pw4=; h=To:Date:In-Reply-To:References:Subject:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=c/gH5OXjcVal8yb+uZlxlWNdPbtHYEUgw3U8SjUZ81fE5tuJLQ+XWtPQYkaLq2xCO Ddf2uv1kNhLlqgARn9iKodFRt0pLaeclKwXn2p4AQj6bM2nouPe9L3/T7BmqirY02i gs58f/cYit7VxhVymrSEzaulDzDJAoRTiGh1UNCxArbRoR2T8bWLV/eG63nc4g3ZcP EJQJgqbKEeFdv57uug/SvGXjtQqSFOOJJMfx4VuMv9Md5gOHXQKVa8O0Ny0M/svus5 xuLLyURrjLqMh5XFxLEN7cvDk0m+Hne1ba4YdJ7GVSrJXVM9+28OcllcqpnRPvF1BZ mFSJAKvDMLtqQ== Received: from relay4-d.mail.gandi.net (relay4-d.mail.gandi.net [IPv6:2001:4b98:dc4:8::224]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id B5CEF60552 for ; Fri, 1 Jul 2022 17:47:10 +0200 (CEST) Received: (Authenticated sender: jacopo@jmondi.org) by mail.gandi.net (Postfix) with ESMTPSA id 0F6DBE000A; Fri, 1 Jul 2022 15:47:09 +0000 (UTC) To: libcamera-devel@lists.libcamera.org Date: Fri, 1 Jul 2022 17:46:57 +0200 Message-Id: <20220701154701.354052-5-jacopo@jmondi.org> X-Mailer: git-send-email 2.36.1 In-Reply-To: <20220701154701.354052-1-jacopo@jmondi.org> References: <20220518134728.777709-2-paul.elder@ideasonboard.com> <20220701154701.354052-1-jacopo@jmondi.org> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH 5/9] fixup: Capitalize "Auto" 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: , X-Patchwork-Original-From: Jacopo Mondi via libcamera-devel From: Jacopo Mondi Reply-To: Jacopo Mondi Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" The "Auto" and "Manual" terms when used to refer to control modes are keywords and should be captitalized. Signed-off-by: Jacopo Mondi Acked-by: Paul Elder --- src/libcamera/control_ids.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml index d50df8bcad28..b062b7e234a6 100644 --- a/src/libcamera/control_ids.yaml +++ b/src/libcamera/control_ids.yaml @@ -170,7 +170,7 @@ controls: description: | Specify an Exposure Value (EV) parameter. The EV parameter will only be applied if the AE algorithm is currently enabled, that is, at least one - of AnalogueGainMode and ExposureTimeMode are auto. + of AnalogueGainMode and ExposureTimeMode are in Auto mode. By convention EV adjusts the exposure as log2. For example EV = [-2, -1, 0.5, 0, 0.5, 1, 2] results in an exposure adjustment From patchwork Fri Jul 1 15:46:58 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jacopo Mondi X-Patchwork-Id: 16516 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 00141BD808 for ; Fri, 1 Jul 2022 15:47:15 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id BB8DE6565C; Fri, 1 Jul 2022 17:47:15 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1656690435; bh=cOryWfdVASI7VdmRVSGK8PW3OalV4m+56k8h8v5fo2g=; h=To:Date:In-Reply-To:References:Subject:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=TyVlD3c4JAWLO56DH+PGYd6AQIfGMv3GezZnabemys9kcgI7s9akTp9HxijOqRSAG V06bPoKV83fPT5qtvJ4N8Enmeg7w5U6EAkd12m8UeHdElBCW7LOpEbvSRL8HYYaksg IXFlvImBjJ264PfSgHExh4XX3W7+OoUHgoEqGaykHn9Ju2YT29Fwbe5qzSDbYJxj6w cT5UG7IrYQVi5b61BQOd1KUq6qFQIn1sjjy9Hce2hCx0LaQzk/Vl74FqDPLmmwh4kB dEeAfkrdJFsjHVyTUyXK/M8DLfFH1fu2l3ZJHHtyTwiu9JbkeK0RoU3JhBfl+bN//h 7lOFFbKZQdsyw== Received: from relay4-d.mail.gandi.net (relay4-d.mail.gandi.net [217.70.183.196]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 85F0065655 for ; Fri, 1 Jul 2022 17:47:11 +0200 (CEST) Received: (Authenticated sender: jacopo@jmondi.org) by mail.gandi.net (Postfix) with ESMTPSA id E59C0E0006; Fri, 1 Jul 2022 15:47:10 +0000 (UTC) To: libcamera-devel@lists.libcamera.org Date: Fri, 1 Jul 2022 17:46:58 +0200 Message-Id: <20220701154701.354052-6-jacopo@jmondi.org> X-Mailer: git-send-email 2.36.1 In-Reply-To: <20220701154701.354052-1-jacopo@jmondi.org> References: <20220518134728.777709-2-paul.elder@ideasonboard.com> <20220701154701.354052-1-jacopo@jmondi.org> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH 6/9] fixup: Reword ExposureTimeMode 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: , X-Patchwork-Original-From: Jacopo Mondi via libcamera-devel From: Jacopo Mondi Reply-To: Jacopo Mondi Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" Slightly reword the first part of the control definition. Signed-off-by: Jacopo Mondi Acked-by: Paul Elder --- src/libcamera/control_ids.yaml | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml index b062b7e234a6..e6676a149795 100644 --- a/src/libcamera/control_ids.yaml +++ b/src/libcamera/control_ids.yaml @@ -203,21 +203,15 @@ controls: Controls the source of the exposure time that is applied to the image sensor. When set to Auto, the AE algorithm computes the exposure time and configures the image sensor accordingly. When set to Manual, - exposure time specified in ExposureTime is applied to the image sensor. - If ExposureTime is not set, then the value last computed by the AE - algorithm when the mode was Auto will be used. + the value of the ExposureTime control is used. - If ExposureTime is not set and the mode is ExposureTimeModeManual and - AE was never Auto (either because the camera started in Manual mode, + When transitioning from Auto to Manual mode and no ExposureTime control + is provided by the application, the last value computed by the AE + algorithm when the mode was Auto will be used. If the ExposureTimeMode + was never set to Auto (either because the camera started in Manual mode, or Auto is not supported by the camera), the camera should use a best-effort default value. - When ExposureTimeMode is set Auto, the value set in ExposureTime is - ignored and is not retained. This means that if ExposureTimeMode is set - to Manual and ExposureTime is not also set, the exposure time that - was last computed by the AE algorithm while the mode was Auto will be - applied to the sensor. - If ExposureTimeModeManual is supported, the ExposureTime control must also be supported. From patchwork Fri Jul 1 15:46:59 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jacopo Mondi X-Patchwork-Id: 16517 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 D8550BD808 for ; Fri, 1 Jul 2022 15:47:16 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 5EA7F6565A; Fri, 1 Jul 2022 17:47:16 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1656690436; bh=An79EAGbcDFs93+ldfHlsveAiD+Llm2IFFTPo8gfAh8=; h=To:Date:In-Reply-To:References:Subject:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=sRL9Z6nCK3KTK/ElKqBm6bu+/S9NBJ99Gkc+RjpWbp9kLt1AlkVmQx3lukDa9GSvI vvKhgDlHK8HU+qxEUoxHxnX97Yf5Mfs+XbQTMKs2dPk40BfUhPlKYmgRcJICNF4Ib/ c7U1GaudBxYqeuQDFIIHff0Osx1DxO+JnJXe8GSUxzciehL6lQQZ552nsRhXerhj2W 0g9UBhfkle+Ly5NdphiCMqO9lYtawssgSHBmkly1p+o3KNbOGgp4sX08s4C97/T3Pb VVTfuyS1cCmVdEzlBTy6OV3gFHhnvXe9vwru2ipzVJVjbuDC7fMB4KLI3dwplpKgo+ da7+OlyeEU7ng== Received: from relay4-d.mail.gandi.net (relay4-d.mail.gandi.net [IPv6:2001:4b98:dc4:8::224]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 5DDFD65657 for ; Fri, 1 Jul 2022 17:47:12 +0200 (CEST) Received: (Authenticated sender: jacopo@jmondi.org) by mail.gandi.net (Postfix) with ESMTPSA id B88DCE0004; Fri, 1 Jul 2022 15:47:11 +0000 (UTC) To: libcamera-devel@lists.libcamera.org Date: Fri, 1 Jul 2022 17:46:59 +0200 Message-Id: <20220701154701.354052-7-jacopo@jmondi.org> X-Mailer: git-send-email 2.36.1 In-Reply-To: <20220701154701.354052-1-jacopo@jmondi.org> References: <20220518134728.777709-2-paul.elder@ideasonboard.com> <20220701154701.354052-1-jacopo@jmondi.org> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH 7/9] fixup: Rework flickerless transition mode 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: , X-Patchwork-Original-From: Jacopo Mondi via libcamera-devel From: Jacopo Mondi Reply-To: Jacopo Mondi Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" Re-work the introduction text. This might seems arbitrary but the new text provides a bit more context. Signed-off-by: Jacopo Mondi Acked-by: Paul Elder --- src/libcamera/control_ids.yaml | 32 ++++++++++++++++++++++++-------- 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml index e6676a149795..225377cf9e76 100644 --- a/src/libcamera/control_ids.yaml +++ b/src/libcamera/control_ids.yaml @@ -218,19 +218,35 @@ controls: The set of ExposureTimeMode modes that are supported by the camera must have an intersection with the supported set of AnalogueGainMode modes. - As it takes a few frames to apply the exposure time, there is a period of - time between submitting a request with ExposureTimeMode set to Manual - and the exposure time component of the AE actually being disabled, - during which the AE algorithm can still update the exposure time. If an - application is switching from automatic and manual control and wishes - to eliminate any flicker during the switch, the following procedure is - recommended. + Flickerless exposure mode transitions + + Applications that transition from ExposureTimeModeAuto to the direct + control of the exposure time should aim to do so by selecting an + ExposureTime value as close as possible to the last value computed by + the auto exposure algorithm in order to avoid any visible flickering. + + To select the correct value to use as ExposureTime value, applications + should accommodate the natural delay in applying controls caused by the + capture pipeline frame depth. + + When switching to manual exposure mode, applications should not + immediately specify an ExposureTime value in the same request where + ExposureTimeMode is set to Manual. They should instead wait for the + first Request where ExposureTimeMode is reported as + ExposureTimeModeManual in the Request metadata, and use the reported + ExposureTime to populate the control value in the next Request to be + queued to the Camera. + + The implementation of the auto-exposure algorithm should equally try to + minimize flickering and when transitioning from manual exposure mode to + auto exposure use the last value provided by the application as starting + point. 1. Start with ExposureTimeMode set to Auto 2. Set ExposureTimeMode to Manual - 3. Wait for the first request to be output that has ExposureTimeMode + 3. Wait for the first completed request that has ExposureTimeMode set to Manual 4. Copy the value reported in ExposureTime into a new request, and From patchwork Fri Jul 1 15:47:00 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jacopo Mondi X-Patchwork-Id: 16518 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 0140DBD808 for ; Fri, 1 Jul 2022 15:47:18 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 9E3D565657; Fri, 1 Jul 2022 17:47:17 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1656690437; bh=UGJ+gdTck/v0stuoI6Gwao0fARqas09Qcb74vekgk2c=; h=To:Date:In-Reply-To:References:Subject:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=rzr0CVv+4ql0Vzm553KqwfHEK/gjbDsET+ZBHXbyoixSt0UY3y2rriZOdaXXSrUg3 ZLwMtcqcWhhyzSwY5WIImxy5oxzTXC0eXg9o/HmWkpjtQyuO5vKy58r3EsZ3kdqF8o PJyyAlLGb5eJ1ZGt1PPv8xrofzHUKE2tUwu2o4n5fYsurCvNTBh+xCF4CSUCWOI73x sfvdKvnCJrFqUmEWzl5o9pLdhaKRa1vCA9JU//O3WUtQl9UlVuXuM3zCGoIWINw1X0 9bMiuAQ4/COvBuS+FJntapNvjEH7wpr6za5AVU6y+lqdM57Gm4Crgn0mrcs+YlVOCy YMvQiwFGd/25g== Received: from relay4-d.mail.gandi.net (relay4-d.mail.gandi.net [IPv6:2001:4b98:dc4:8::224]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 4E7CD65659 for ; Fri, 1 Jul 2022 17:47:13 +0200 (CEST) Received: (Authenticated sender: jacopo@jmondi.org) by mail.gandi.net (Postfix) with ESMTPSA id A304DE0004; Fri, 1 Jul 2022 15:47:12 +0000 (UTC) To: libcamera-devel@lists.libcamera.org Date: Fri, 1 Jul 2022 17:47:00 +0200 Message-Id: <20220701154701.354052-8-jacopo@jmondi.org> X-Mailer: git-send-email 2.36.1 In-Reply-To: <20220701154701.354052-1-jacopo@jmondi.org> References: <20220518134728.777709-2-paul.elder@ideasonboard.com> <20220701154701.354052-1-jacopo@jmondi.org> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH 8/9] fixup: Minor changes in ExposureTimeMode 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: , X-Patchwork-Original-From: Jacopo Mondi via libcamera-devel From: Jacopo Mondi Reply-To: Jacopo Mondi Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" slightly modify the ExposureTime modes description. Signed-off-by: Jacopo Mondi Acked-by: Paul Elder --- src/libcamera/control_ids.yaml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml index 225377cf9e76..1f22b9b35036 100644 --- a/src/libcamera/control_ids.yaml +++ b/src/libcamera/control_ids.yaml @@ -260,20 +260,20 @@ controls: value: 0 description: | The exposure time will be calculated automatically and set by the - AE algorithm. If ExposureTime is set while this mode is active, it - will be ignored, and it will also not be retained. + AE algorithm. + + If ExposureTime is set while this mode is active, it will be + ignored, and it will also not be retained. - name: ExposureTimeModeManual value: 1 description: | - The exposure time will not be updated by the AE algorithm. It will - come from the last calculated value when the mode was Auto, or from - the value specified in ExposureTime. + The exposure time will not be updated by the AE algorithm. When transitioning from Auto to Manual mode, the last computed exposure value is used until a new value is specified through the ExposureTime control. If an ExposureTime value is specified in the same request where the ExposureTimeMode is changed from Auto to - Manual, the provided ExposureTime is applied. + Manual, the provided ExposureTime is applied immediately. - AnalogueGain: type: float From patchwork Fri Jul 1 15:47:01 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jacopo Mondi X-Patchwork-Id: 16519 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 E39EBBD808 for ; Fri, 1 Jul 2022 15:47:18 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 8F1F465696; Fri, 1 Jul 2022 17:47:18 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1656690438; bh=0CBEY8whH6YeZjrrFCX58RzUaPf10Z11dV3Ed8/ItpE=; h=To:Date:In-Reply-To:References:Subject:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=B7Z35hA7ggV4SzakvgiYRpeQboh+dY5nNdAVA/k0wsJ3XCpZ8i1+6qujXzG9NPXvy BdujiQ5tEl0TLZME1opL/A+fOolOtt1AZTjSzTQJVYYfDvsvdoV1yM642mEQg28F1Q OGrx67KaOSeVoAmMPzudajWJESJA9+jgUympP6+SBt9unr6fjYw085KO5LaAzlTWio 6MniAQp3C/ts7o1xZcLB7F5seA5TMO29vAjpmiSOYvztijpfMl5NnX8lPOpJKGVCAw Ux9NR/ylyjVz2w9buuAM9ZnzAtqAbR+XZ6+sF5TYK0BH2LiCg5PmhwoK8AYvUWYuEm n8jLhka4M6D5Q== Received: from relay4-d.mail.gandi.net (relay4-d.mail.gandi.net [IPv6:2001:4b98:dc4:8::224]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 1220C6565F for ; Fri, 1 Jul 2022 17:47:14 +0200 (CEST) Received: (Authenticated sender: jacopo@jmondi.org) by mail.gandi.net (Postfix) with ESMTPSA id 7000BE0004; Fri, 1 Jul 2022 15:47:13 +0000 (UTC) To: libcamera-devel@lists.libcamera.org Date: Fri, 1 Jul 2022 17:47:01 +0200 Message-Id: <20220701154701.354052-9-jacopo@jmondi.org> X-Mailer: git-send-email 2.36.1 In-Reply-To: <20220701154701.354052-1-jacopo@jmondi.org> References: <20220518134728.777709-2-paul.elder@ideasonboard.com> <20220701154701.354052-1-jacopo@jmondi.org> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH 9/9] fixup: Align AnalogueGainMode to ExposureTimeMode 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: , X-Patchwork-Original-From: Jacopo Mondi via libcamera-devel From: Jacopo Mondi Reply-To: Jacopo Mondi Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" Align the description of the two controls. Signed-off-by: Jacopo Mondi Acked-by: Paul Elder --- src/libcamera/control_ids.yaml | 59 +++++++++++----------------------- 1 file changed, 19 insertions(+), 40 deletions(-) diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml index 1f22b9b35036..51713a5d148d 100644 --- a/src/libcamera/control_ids.yaml +++ b/src/libcamera/control_ids.yaml @@ -289,7 +289,7 @@ controls: When reported in metadata, this control indicates what analogue gain was used for the current request, regardless of AnalogueGainMode. AnalogueGainMode will indicate the source of the analogue gain value, - whether it came from the AE algorithm or not. + whether it came from the AEGC algorithm or not. \sa ExposureTime \sa AnalogueGainMode @@ -298,69 +298,48 @@ controls: type: int32_t description: | Controls the source of the analogue gain that is applied to the image - sensor. When set to Auto, the AE algorithm computes the analogue gain + sensor. When set to Auto, the AEGC algorithm computes the analogue gain and configures the image sensor accordingly. When set to Manual, - analogue gain specified in AnalogueGain is applied to the image sensor. - If AnalogueGain is not set, then the value last computed by the AE - algorithm when the mode was Auto will be used. + the value of the AnalogueGain control is used. - If AnalogueGain is not set and the mode is AnalogueGainModeManual and - AE was never Auto (either because the camera started in Manual mode, + When transitioning from Auto to Manual mode and no AnalogueGain control + is provided by the application, the last value computed by the AEGC + algorithm when the mode was Auto will be used. If the AnalogueGainMode + was never set to Auto (either because the camera started in Manual mode, or Auto is not supported by the camera), the camera should use a best-effort default value. - When AnalogueGainMode is set Auto, the value set in AnalogueGain is - ignored and is not retained. This means that if AnalogueGainMode is set - to Manual and AnalogueGain is not also set, the analogue gain that - was last computed by the AE algorithm while the mode was Auto will be - applied to the sensor. - If AnalogueGainModeManual is supported, the AnalogueGain control must also be supported. The set of AnalogueGainMode modes that are supported by the camera must have an intersection with the supported set of ExposureTimeMode modes. - As it takes a few frames to apply the analogue gain, there is a period of - time between submitting a request with AnalogueGainMode set to Manual - and the analogue gain component of the AE actually being disabled, - during which the AE algorithm can still update the analogue gain. If an - application is switching from automatic and manual control and wishes - to eliminate any flicker during the switch, the following procedure is - recommended. - - 1. Start with AnalogueGainMode set to Auto - - 2. Set AnalogueGainMode to Manual - - 3. Wait for the first request to be output that has AnalogueGainMode - set to Manual - - 4. Copy the value reported in AnalogueGain into a new request, and - submit it - - 5. Proceed to run manual analogue gain + The same procedure described for performing flickerless transitions in + the ExposureTimeMode control documentation should be applied to + analogue gain. + \sa ExposureTimeMode \sa AnalogueGain enum: - name: AnalogueGainModeAuto value: 0 description: | The analogue gain will be calculated automatically and set by the - AE algorithm. If AnalogueGain is set while this mode is active, it - will be ignored, and it will also not be retained. + AEGC algorithm. + + If AnalogueGain is set while this mode is active, it will be + ignored, and it will also not be retained. - name: AnalogueGainModeManual value: 1 description: | - The analogue gain will not be updated by the AE algorithm. It will - come from the last calculated value when the mode was Auto, or from - the value specified in AnalogueGain. + The analogue gain will not be updated by the AEGC algorithm. - When transitioning from Auto to Manual mode the last computed + When transitioning from Auto to Manual mode, the last computed gain value is used until a new value is specified through the AnalogueGain control. If an AnalogueGain value is specified in the - same request where the AnalogueGainMode is set to Manual, the - provided AnalogueGain is applied. + same request where the AnalogueGainMode is changed from Auto to + Manual, the provided AnalogueGain is applied immediately. - Brightness: type: float