From patchwork Fri Sep 23 08:52:22 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jacopo Mondi X-Patchwork-Id: 17390 X-Patchwork-Delegate: jacopo@jmondi.org 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 EC41CC327E for ; Fri, 23 Sep 2022 08:52:41 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id BB512621BC; Fri, 23 Sep 2022 10:52:40 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1663923160; bh=wWKBEGgh/ilXdEvxaLJPHBUL0oV5TdmHRJ3CCSuJzKQ=; 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=VofWZZsy8UsBjzm6d6kkQT1Nc6dyd4Kn+xdKlurrxLL5NtUarkKTs8Z87Huj89GZx L2SKVoNg56SFecLKhjJ47L919bDgoMXsxlydtqLnXh9Pu8jgO6/PdPZL+seF+GgdjK zwhQVCCj3wmtVkXTKa4ZGWemV6ABaJuUBUqryopDoJ8zfjBnXhaI5cmcssdLCydYog r3xsAfy0wxhNCkFW9ZWzsv5EqET0IG74sU53Ry7xuHx5TYWqAgccDD48OwMjNmkd5T L4t+4s+/zcYDEO88nXjHMTf+PSfjGRclPntricUpyrmO3y7PFWzbqI7dccsTPe2fpF noNdZBgt2hblw== Received: from relay12.mail.gandi.net (relay12.mail.gandi.net [IPv6:2001:4b98:dc4:8::232]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id ABC0662229 for ; Fri, 23 Sep 2022 10:52:39 +0200 (CEST) Received: (Authenticated sender: jacopo@jmondi.org) by mail.gandi.net (Postfix) with ESMTPSA id E509E200003; Fri, 23 Sep 2022 08:52:38 +0000 (UTC) To: libcamera-devel@lists.libcamera.org Date: Fri, 23 Sep 2022 10:52:22 +0200 Message-Id: <20220923085222.7759-2-jacopo@jmondi.org> X-Mailer: git-send-email 2.37.3 In-Reply-To: <20220923085222.7759-1-jacopo@jmondi.org> References: <20220811150219.62066-1-jacopo@jmondi.org> <20220923085222.7759-1-jacopo@jmondi.org> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH 8/6] libcamera: control_ids: Add high-level documentation for AE 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 Add high-level documentation for AE, describing the states and the transitions and how one would use the AE controls. Signed-off-by: Paul Elder Signed-off-by: Jacopo Mondi --- v1->v2: - s/Inactive/Idle - s/Disabled/Manual -- src/libcamera/control_ids.cpp.in | 82 ++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) -- 2.37.3 diff --git a/src/libcamera/control_ids.cpp.in b/src/libcamera/control_ids.cpp.in index 5fb1c2c30558..4b3504f2c62c 100644 --- a/src/libcamera/control_ids.cpp.in +++ b/src/libcamera/control_ids.cpp.in @@ -10,6 +10,88 @@ #include #include +/** + * \page AE Auto-exposure Support + * + * libcamera offers the following controls related to exposure and gain: + * - AnalogueGain + * - AnalogueGainMode + * - ExposureTime + * - ExposureTimeMode + * - AeState + * + * Auto-exposure and auto-gain can be enabled and disabled separately using the + * ExposureTimeMode and AnalogueGainMode controls respectively. There is no + * overarching AeEnable control. + * + * For each of exposure and gain, we can model it with three states: auto, + * locked, and manual. Note that AnalogueGainMode and ExposureTimeMode only + * have two values, as the locked state is simulated. + * + * /---------------------------------\ + * | | + * V | + * +--------+ +--------+ + * | | ---------------------> | | + * | Auto | +--------+ | Manual | + * | | ----> | Locked | ----> | | + * +--------+ +--------+ +--------+ + * ^ | + * | | + * \----------------/ + * + * Notice from the state diagram that locked to manual is a one-way state + * change, as the reverse direction is nonsensical (see the design document for + * more details on this topic). + * + * The exposure/gain is in the Auto state when + * ExposureTimeMode/AnalogueGainMode is set to Auto. In this state, the value + * that is computed by the AE algorithm is applied to the image sensor. Any + * value that is supplied in the ExposureTime/AnalogueGain control is ignored + * and is not retained. + * + * If ExposureTimeMode/AnalogueGainMode is set to Manual, it can put us in + * either the Locked or Manual state. The difference is in if + * ExposureTime/AnalogueGain has been supplied. If it has not yet been + * supplied, then we are in the Locked state. If it has been supplied, then we + * are in the Manual state. + * + * In both the Locked state and the Manual state the exposure/gain value does + * not come from the AE algorithm. In the Locked state the value comes from the + * last value computed by the AE algorithm while the state was Auto, or if the + * state was never Auto (e.g. we started in Locked, or the camera doesn't + * support Auto), then the value should be a best-effort default value. In the + * Manual state the value comes from the value supplied in the + * ExposureTime/AnalogueGain control. + * + * To transition from the Locked state to the Manual state, a value needs to be + * submitted in ExposureTime/AnalogueGain. Once the state has transitioned to + * Manual, then this value will be retained, and doesn't need to be resubmitted + * if it doesn't change. + * + * To transition to the Auto state, simply set + * ExposureTimeMode/AnalogueGainMode to Auto. + * + * + * The AeState metadata reports the state of the AE algorithm. As AE cannot + * compute exposure and gain separately, the state of the AE component is + * unified. There are three states: Idle, Searching, and Converged. + * + * The state shall be Idle if both ExposureTimeMode and AnalogueGainMode + * are set to Manual. If the camera only supports one of the two controls, + * then the state shall be Idle if that one control is set to Manual. If + * the camera does not support Manual for at least one of the two controls, + * then the state will never be Idle, as AE will always be running. + * + * The state shall be Searching if at least one of exposure or gain calculated + * by the AE algorithm is used (that is, at least one of the two modes is Auto), + * *and* the value(s) have not converged yet. + * + * The state shall be Converged if at least one of exposure or gain calculated + * by the AE algorithm is used (that is, at least one of the two modes is Auto), + * *and* the value(s) have converged. + */ + /** * \file control_ids.h * \brief Camera control identifiers