Patch Detail
Show a patch.
GET /api/1.1/patches/17390/?format=api
{ "id": 17390, "url": "https://patchwork.libcamera.org/api/1.1/patches/17390/?format=api", "web_url": "https://patchwork.libcamera.org/patch/17390/", "project": { "id": 1, "url": "https://patchwork.libcamera.org/api/1.1/projects/1/?format=api", "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=api", "name": "Jacopo Mondi", "email": "jacopo@jmondi.org" }, "delegate": { "id": 15, "url": "https://patchwork.libcamera.org/api/1.1/users/15/?format=api", "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=api", "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": "<libcamera-devel-bounces@lists.libcamera.org>", "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 <parsemail@patchwork.libcamera.org>;\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 <libcamera-devel@lists.libcamera.org>;\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": "<libcamera-devel.lists.libcamera.org>", "List-Unsubscribe": "<https://lists.libcamera.org/options/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=unsubscribe>", "List-Archive": "<https://lists.libcamera.org/pipermail/libcamera-devel/>", "List-Post": "<mailto:libcamera-devel@lists.libcamera.org>", "List-Help": "<mailto:libcamera-devel-request@lists.libcamera.org?subject=help>", "List-Subscribe": "<https://lists.libcamera.org/listinfo/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=subscribe>", "From": "Jacopo Mondi via libcamera-devel <libcamera-devel@lists.libcamera.org>", "Reply-To": "Jacopo Mondi <jacopo@jmondi.org>", "Errors-To": "libcamera-devel-bounces@lists.libcamera.org", "Sender": "\"libcamera-devel\" <libcamera-devel-bounces@lists.libcamera.org>" }, "content": "From: Paul Elder <paul.elder@ideasonboard.com>\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 <paul.elder@ideasonboard.com>\nSigned-off-by: Jacopo Mondi <jacopo@jmondi.org>\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 <libcamera/control_ids.h>\n #include <libcamera/controls.h>\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" ] }