{"id":15972,"url":"https://patchwork.libcamera.org/api/patches/15972/?format=json","web_url":"https://patchwork.libcamera.org/patch/15972/","project":{"id":1,"url":"https://patchwork.libcamera.org/api/projects/1/?format=json","name":"libcamera","link_name":"libcamera","list_id":"libcamera_core","list_email":"libcamera-devel@lists.libcamera.org","web_url":"","scm_url":"","webscm_url":""},"msgid":"<20220518134728.777709-4-paul.elder@ideasonboard.com>","date":"2022-05-18T13:47:28","name":"[libcamera-devel,3/3] libcamera: control_ids: Add high-level documentation for AE","commit_ref":null,"pull_url":null,"state":"new","archived":false,"hash":"9cfbcff0688baef2ef5834e0d75483d0069a9bd1","submitter":{"id":17,"url":"https://patchwork.libcamera.org/api/people/17/?format=json","name":"Paul Elder","email":"paul.elder@ideasonboard.com"},"delegate":null,"mbox":"https://patchwork.libcamera.org/patch/15972/mbox/","series":[{"id":3123,"url":"https://patchwork.libcamera.org/api/series/3123/?format=json","web_url":"https://patchwork.libcamera.org/project/libcamera/list/?series=3123","date":"2022-05-18T13:47:25","name":"AE controls","version":1,"mbox":"https://patchwork.libcamera.org/series/3123/mbox/"}],"comments":"https://patchwork.libcamera.org/api/patches/15972/comments/","check":"pending","checks":"https://patchwork.libcamera.org/api/patches/15972/checks/","tags":{},"headers":{"Return-Path":"","X-Original-To":"parsemail@patchwork.libcamera.org","Delivered-To":"parsemail@patchwork.libcamera.org","Received":["from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id D70CBC3256\n\tfor ;\n\tWed, 18 May 2022 13:47:50 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id CB2046565E;\n\tWed, 18 May 2022 15:47:49 +0200 (CEST)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 4358865658\n\tfor ;\n\tWed, 18 May 2022 15:47:45 +0200 (CEST)","from localhost.localdomain (unknown [45.131.31.124])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id CCB5B1027;\n\tWed, 18 May 2022 15:47:44 +0200 (CEST)"],"DKIM-Signature":["v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org;\n\ts=mail; t=1652881669;\n\tbh=qstfj7d2bg2uIa4x6d1yL9Wn39GJh6nHjxaqXi69Oo4=;\n\th=To:Date:In-Reply-To:References:Subject:List-Id:List-Unsubscribe:\n\tList-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:\n\tFrom;\n\tb=a5JgNyn0G/qLPxfpTpU8qxRIMJtNnkVceD8rhz4/CfvNQATA0ZB0eqdQZkr7DZRPK\n\tjRhbaVHQmdpNzK/x1tpgWIdmCvYDThHWBoNdyr/I0PMFd5zfz3/5rBRBDmoeucDYyP\n\t7dmahzWoJ55Q3zERYuARin7ABi7EEHy7Qv+u0ibYmdd7/r2+ZkwrRkY2DncauNR356\n\tKZ4qwrOwjKwVrJP0fxD5p7pA2vNzgPV2kRq4fsq+T8+YjDGuW/ahh1TIbBW70MQwqX\n\tw7O3K9/hoZqpTxo1NI6Bs+VqS8aR3MMbbGZSISVK7qH41AxceD6NDGtDNngdxIKlfe\n\tEn7G2e3LSuMaQ==","v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1652881665;\n\tbh=qstfj7d2bg2uIa4x6d1yL9Wn39GJh6nHjxaqXi69Oo4=;\n\th=From:To:Cc:Subject:Date:In-Reply-To:References:From;\n\tb=EutlDkleSPGlwUSlnVqUd/Rpku+rnooWyyiED0GNDDhBWypQfRs48gsXi0r6MAi52\n\tA8Fbk6/PHy6DDHD5pLahOeuKvhDistUoB06lnd7e+ygwtz/KkZ/xl9qHknLi8cTaC1\n\tGRX4r51MxpmzGymbF1z8J6aEuRyNHst36t/gGJdI="],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key; \n\tunprotected) header.d=ideasonboard.com\n\theader.i=@ideasonboard.com\n\theader.b=\"EutlDkle\"; dkim-atps=neutral","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","Content-Transfer-Encoding":"8bit","Subject":"[libcamera-devel] [PATCH 3/3] libcamera: control_ids: Add\n\thigh-level documentation for AE","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","From":"Paul Elder via libcamera-devel ","Reply-To":"Paul Elder ","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "},"content":"Add high-level documentation for AE, describing the states and the\ntransitions and how one would use the AE controls.\n\nSigned-off-by: Paul Elder \n---\n src/libcamera/control_ids.cpp.in | 82 ++++++++++++++++++++++++++++++++\n 1 file changed, 82 insertions(+)","diff":"diff --git a/src/libcamera/control_ids.cpp.in b/src/libcamera/control_ids.cpp.in\nindex 5fb1c2c3..62451d7f 100644\n--- a/src/libcamera/control_ids.cpp.in\n+++ b/src/libcamera/control_ids.cpp.in\n@@ -10,6 +10,88 @@\n #include \n #include \n \n+/**\n+ * \\page AE Auto-exposure Support\n+ *\n+ * libcamera offers the following controls related to exposure and gain:\n+ * - AnalogueGain\n+ * - AnalogueGainMode\n+ * - ExposureTime\n+ * - ExposureTimeMode\n+ * - AeState\n+ *\n+ * Auto-exposure and auto-gain can be enabled and disabled separately using the\n+ * ExposureTimeMode and AnalogueGainMode controls respectively. There is no\n+ * overarching AeEnable control.\n+ *\n+ * For each of exposure and gain, we can model it with three states: auto,\n+ * locked, and manual. Note that AnalogueGainMode and ExposureTimeMode only\n+ * have two values, as the locked state is simulated.\n+ *\n+ * /---------------------------------\\\n+ * | |\n+ * V |\n+ * +--------+ +--------+\n+ * | | ---------------------> | |\n+ * | Auto | +--------+ | Manual |\n+ * | | ----> | Locked | ----> | |\n+ * +--------+ +--------+ +--------+\n+ * ^ |\n+ * | |\n+ * \\----------------/\n+ *\n+ * Notice from the state diagram that locked to manual is a one-way state\n+ * change, as the reverse direction is nonsensical (see the design document for\n+ * more details on this topic).\n+ *\n+ * The exposure/gain is in the Auto state when\n+ * ExposureTimeMode/AnalogueGainMode is set to Auto. In this state, the value\n+ * that is computed by the AE algorithm is applied to the image sensor. Any\n+ * value that is supplied in the ExposureTime/AnalogueGain control is ignored\n+ * and is not retained.\n+ *\n+ * If ExposureTimeMode/AnalogueGainMode is set to Disabled, it can put us in\n+ * either the Locked or Manual state. The difference is in if\n+ * ExposureTime/AnalogueGain has been supplied. If it has not yet been\n+ * supplied, then we are in the Locked state. If it has been supplied, then we\n+ * are in the Manual state.\n+ *\n+ * In both the Locked state and the Manual state the exposure/gain value does\n+ * not come from the AE algorithm. In the Locked state the value comes from the\n+ * last value computed by the AE algorithm while the state was Auto, or if the\n+ * state was never Auto (e.g. we started in Locked, or the camera doesn't\n+ * support Auto), then the value should be a best-effort default value. In the\n+ * Manual state the value comes from the value supplied in the\n+ * ExposureTime/AnalogueGain control.\n+ *\n+ * To transition from the Locked state to the Manual state, a value needs to be\n+ * submitted in ExposureTime/AnalogueGain. Once the state has transitioned to\n+ * Manual, then this value will be retained, and doesn't need to be resubmitted\n+ * if it doesn't change.\n+ *\n+ * To transition to the Auto state, simply set\n+ * ExposureTimeMode/AnalogueGainMode to Auto.\n+ *\n+ *\n+ * The AeState metadata reports the state of the AE algorithm. As AE cannot\n+ * compute exposure and gain separately, the state of the AE component is\n+ * unified. There are three states: Inactive, Searching, and Converged.\n+ *\n+ * The state shall be Inactive if both ExposureTimeMode and AnalogueGainMode\n+ * are set to Disabled. If the camera only supports one of the two controls,\n+ * then the state shall be Inactive if that one control is set to Disabled. If\n+ * the camera does not support Disabled for at least one of the two controls,\n+ * then the state will never be Inactive, as AE will always be running.\n+ *\n+ * The state shall be Searching if at least one of exposure or gain calculated\n+ * by the AE algorithm is used (that is, at least one of the two modes is Auto),\n+ * *and* the value(s) have not converged yet.\n+ *\n+ * The state shall be Converged if at least one of exposure or gain calculated\n+ * by the AE algorithm is used (that is, at least one of the two modes is Auto),\n+ * *and* the value(s) have converged.\n+ */\n+\n /**\n * \\file control_ids.h\n * \\brief Camera control identifiers\n","prefixes":["libcamera-devel","3/3"]}