From patchwork Wed May 18 13:47:28 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paul Elder X-Patchwork-Id: 15972 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 D70CBC3256 for ; Wed, 18 May 2022 13:47:50 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id CB2046565E; Wed, 18 May 2022 15:47:49 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1652881669; bh=qstfj7d2bg2uIa4x6d1yL9Wn39GJh6nHjxaqXi69Oo4=; 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=a5JgNyn0G/qLPxfpTpU8qxRIMJtNnkVceD8rhz4/CfvNQATA0ZB0eqdQZkr7DZRPK jRhbaVHQmdpNzK/x1tpgWIdmCvYDThHWBoNdyr/I0PMFd5zfz3/5rBRBDmoeucDYyP 7dmahzWoJ55Q3zERYuARin7ABi7EEHy7Qv+u0ibYmdd7/r2+ZkwrRkY2DncauNR356 KZ4qwrOwjKwVrJP0fxD5p7pA2vNzgPV2kRq4fsq+T8+YjDGuW/ahh1TIbBW70MQwqX w7O3K9/hoZqpTxo1NI6Bs+VqS8aR3MMbbGZSISVK7qH41AxceD6NDGtDNngdxIKlfe En7G2e3LSuMaQ== Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 4358865658 for ; Wed, 18 May 2022 15:47:45 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="EutlDkle"; dkim-atps=neutral Received: from localhost.localdomain (unknown [45.131.31.124]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id CCB5B1027; Wed, 18 May 2022 15:47:44 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1652881665; bh=qstfj7d2bg2uIa4x6d1yL9Wn39GJh6nHjxaqXi69Oo4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=EutlDkleSPGlwUSlnVqUd/Rpku+rnooWyyiED0GNDDhBWypQfRs48gsXi0r6MAi52 A8Fbk6/PHy6DDHD5pLahOeuKvhDistUoB06lnd7e+ygwtz/KkZ/xl9qHknLi8cTaC1 GRX4r51MxpmzGymbF1z8J6aEuRyNHst36t/gGJdI= To: libcamera-devel@lists.libcamera.org Date: Wed, 18 May 2022 15:47:28 +0200 Message-Id: <20220518134728.777709-4-paul.elder@ideasonboard.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20220518134728.777709-1-paul.elder@ideasonboard.com> References: <20220518134728.777709-1-paul.elder@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH 3/3] 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: Paul Elder via libcamera-devel From: Paul Elder Reply-To: Paul Elder Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" 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 --- src/libcamera/control_ids.cpp.in | 82 ++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) diff --git a/src/libcamera/control_ids.cpp.in b/src/libcamera/control_ids.cpp.in index 5fb1c2c3..62451d7f 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 Disabled, 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: Inactive, Searching, and Converged. + * + * The state shall be Inactive if both ExposureTimeMode and AnalogueGainMode + * are set to Disabled. If the camera only supports one of the two controls, + * then the state shall be Inactive if that one control is set to Disabled. If + * the camera does not support Disabled for at least one of the two controls, + * then the state will never be Inactive, 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