Patch Detail
Show a patch.
GET /api/patches/15972/?format=api
{ "id": 15972, "url": "https://patchwork.libcamera.org/api/patches/15972/?format=api", "web_url": "https://patchwork.libcamera.org/patch/15972/", "project": { "id": 1, "url": "https://patchwork.libcamera.org/api/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": "<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=api", "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=api", "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": "<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 D70CBC3256\n\tfor <parsemail@patchwork.libcamera.org>;\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 <libcamera-devel@lists.libcamera.org>;\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": "<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": "Paul Elder via libcamera-devel <libcamera-devel@lists.libcamera.org>", "Reply-To": "Paul Elder <paul.elder@ideasonboard.com>", "Errors-To": "libcamera-devel-bounces@lists.libcamera.org", "Sender": "\"libcamera-devel\" <libcamera-devel-bounces@lists.libcamera.org>" }, "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 <paul.elder@ideasonboard.com>\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 <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 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" ] }