{"id":17390,"url":"https://patchwork.libcamera.org/api/1.1/patches/17390/?format=json","web_url":"https://patchwork.libcamera.org/patch/17390/","project":{"id":1,"url":"https://patchwork.libcamera.org/api/1.1/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":"<20220923085222.7759-2-jacopo@jmondi.org>","date":"2022-09-23T08:52:22","name":"[libcamera-devel,8/6] libcamera: control_ids: Add high-level documentation for AE","commit_ref":null,"pull_url":null,"state":"superseded","archived":false,"hash":"170ac4b257ef3a3b3c6234154937c7b30c83e495","submitter":{"id":3,"url":"https://patchwork.libcamera.org/api/1.1/people/3/?format=json","name":"Jacopo Mondi","email":"jacopo@jmondi.org"},"delegate":{"id":15,"url":"https://patchwork.libcamera.org/api/1.1/users/15/?format=json","username":"jmondi","first_name":"Jacopo","last_name":"Mondi","email":"jacopo@jmondi.org"},"mbox":"https://patchwork.libcamera.org/patch/17390/mbox/","series":[{"id":3404,"url":"https://patchwork.libcamera.org/api/1.1/series/3404/?format=json","web_url":"https://patchwork.libcamera.org/project/libcamera/list/?series=3404","date":"2022-08-11T15:02:13","name":"AEGC controls","version":2,"mbox":"https://patchwork.libcamera.org/series/3404/mbox/"}],"comments":"https://patchwork.libcamera.org/api/patches/17390/comments/","check":"pending","checks":"https://patchwork.libcamera.org/api/patches/17390/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 EC41CC327E\n\tfor ;\n\tFri, 23 Sep 2022 08:52:41 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id BB512621BC;\n\tFri, 23 Sep 2022 10:52:40 +0200 (CEST)","from relay12.mail.gandi.net (relay12.mail.gandi.net\n\t[IPv6:2001:4b98:dc4:8::232])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id ABC0662229\n\tfor ;\n\tFri, 23 Sep 2022 10:52:39 +0200 (CEST)","(Authenticated sender: jacopo@jmondi.org)\n\tby mail.gandi.net (Postfix) with ESMTPSA id E509E200003;\n\tFri, 23 Sep 2022 08:52:38 +0000 (UTC)"],"DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org;\n\ts=mail; t=1663923160;\n\tbh=wWKBEGgh/ilXdEvxaLJPHBUL0oV5TdmHRJ3CCSuJzKQ=;\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=VofWZZsy8UsBjzm6d6kkQT1Nc6dyd4Kn+xdKlurrxLL5NtUarkKTs8Z87Huj89GZx\n\tL2SKVoNg56SFecLKhjJ47L919bDgoMXsxlydtqLnXh9Pu8jgO6/PdPZL+seF+GgdjK\n\tzwhQVCCj3wmtVkXTKa4ZGWemV6ABaJuUBUqryopDoJ8zfjBnXhaI5cmcssdLCydYog\n\tr3xsAfy0wxhNCkFW9ZWzsv5EqET0IG74sU53Ry7xuHx5TYWqAgccDD48OwMjNmkd5T\n\tL4t+4s+/zcYDEO88nXjHMTf+PSfjGRclPntricUpyrmO3y7PFWzbqI7dccsTPe2fpF\n\tnoNdZBgt2hblw==","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>\n\t<20220923085222.7759-1-jacopo@jmondi.org>","MIME-Version":"1.0","Content-Transfer-Encoding":"8bit","Subject":"[libcamera-devel] [PATCH 8/6] 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":"Jacopo Mondi via libcamera-devel ","Reply-To":"Jacopo Mondi ","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "},"content":"From: Paul Elder \n\nAdd 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 \nSigned-off-by: Jacopo Mondi \n---\nv1->v2:\n- s/Inactive/Idle\n- s/Disabled/Manual\n--\n src/libcamera/control_ids.cpp.in | 82 ++++++++++++++++++++++++++++++++\n 1 file changed, 82 insertions(+)\n\n--\n2.37.3","diff":"diff --git a/src/libcamera/control_ids.cpp.in b/src/libcamera/control_ids.cpp.in\nindex 5fb1c2c30558..4b3504f2c62c 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 Manual, 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: Idle, Searching, and Converged.\n+ *\n+ * The state shall be Idle if both ExposureTimeMode and AnalogueGainMode\n+ * are set to Manual. If the camera only supports one of the two controls,\n+ * then the state shall be Idle if that one control is set to Manual. If\n+ * the camera does not support Manual for at least one of the two controls,\n+ * then the state will never be Idle, 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","8/6"]}