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.