{"id":24151,"url":"https://patchwork.libcamera.org/api/patches/24151/?format=json","web_url":"https://patchwork.libcamera.org/patch/24151/","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":"<20250818082909.2001635-2-stefan.klug@ideasonboard.com>","date":"2025-08-18T08:28:39","name":"[RFC,1/4] libipa: agc_mean_luminance: pass estimateLuminance() as parameter","commit_ref":null,"pull_url":null,"state":"new","archived":false,"hash":"7ab276ad2ccce19d6261f5b8df0883672bf27f45","submitter":{"id":184,"url":"https://patchwork.libcamera.org/api/people/184/?format=json","name":"Stefan Klug","email":"stefan.klug@ideasonboard.com"},"delegate":null,"mbox":"https://patchwork.libcamera.org/patch/24151/mbox/","series":[{"id":5390,"url":"https://patchwork.libcamera.org/api/series/5390/?format=json","web_url":"https://patchwork.libcamera.org/project/libcamera/list/?series=5390","date":"2025-08-18T08:28:38","name":"libipa: agc_mean_luminance: Use composition instead of","version":1,"mbox":"https://patchwork.libcamera.org/series/5390/mbox/"}],"comments":"https://patchwork.libcamera.org/api/patches/24151/comments/","check":"pending","checks":"https://patchwork.libcamera.org/api/patches/24151/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 F0C42BEFBE\n\tfor ;\n\tMon, 18 Aug 2025 08:29:59 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id AC0BC6925F;\n\tMon, 18 Aug 2025 10:29:59 +0200 (CEST)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 86FA76924E\n\tfor ;\n\tMon, 18 Aug 2025 10:29:57 +0200 (CEST)","from ideasonboard.com (unknown\n\t[IPv6:2a00:6020:448c:6c00:766d:a405:f64e:fe3a])\n\tby perceval.ideasonboard.com (Postfix) with UTF8SMTPSA id 901812416; \n\tMon, 18 Aug 2025 10:29:00 +0200 (CEST)"],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"EXOVCIfT\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1755505740;\n\tbh=s5Oen/RpoxgdECRxB6R8dYCZKQYyFROrCS3k7Wxu1os=;\n\th=From:To:Cc:Subject:Date:In-Reply-To:References:From;\n\tb=EXOVCIfTkRoHNEejE1V6SwLQXswKFBVcsadbdMeeDK5G4Gguwny/xZQQncAXUXE7S\n\tXVZ0usS9KUXVRcokzZT9lrIKxMjxICIWVjy/9GqK7oMgVvYZ9EVWflre0DapdcHHC7\n\tf04FeJCQLPnl4x87izEpCvHRuYm6XT1V5mjBhz5w=","From":"Stefan Klug ","To":"libcamera-devel@lists.libcamera.org","Cc":"Stefan Klug ","Subject":"[RFC PATCH 1/4] libipa: agc_mean_luminance: pass estimateLuminance()\n\tas parameter","Date":"Mon, 18 Aug 2025 10:28:39 +0200","Message-ID":"<20250818082909.2001635-2-stefan.klug@ideasonboard.com>","X-Mailer":"git-send-email 2.48.1","In-Reply-To":"<20250818082909.2001635-1-stefan.klug@ideasonboard.com>","References":"<20250818082909.2001635-1-stefan.klug@ideasonboard.com>","MIME-Version":"1.0","Content-Transfer-Encoding":"8bit","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","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "},"content":"To use AgcMeanLuminance an algorithm derives from it and overrides the\nestimateLuminance() function. This override is the only reason to\nderive from this class. It has however two downsides:\n- It is more difficult for the reader to know which functionality comes\n from where.\n- It is necessary to keep references to data needed in the\n estimateLuminance() function inside the class, even though that date\n is only accessed inside AgcMenaLuminance::calculateNewEv().\n\nRemove the need to derive from AgcMeanLuminance by passing\nestimateLuminance as function object into calculateNewEv().\n\nSigned-off-by: Stefan Klug \n---\n src/ipa/ipu3/algorithms/agc.cpp | 4 +-\n src/ipa/ipu3/algorithms/agc.h | 2 +-\n src/ipa/libipa/agc_mean_luminance.cpp | 57 ++++++++++++++-------------\n src/ipa/libipa/agc_mean_luminance.h | 9 +++--\n src/ipa/mali-c55/algorithms/agc.cpp | 5 ++-\n src/ipa/mali-c55/algorithms/agc.h | 2 +-\n src/ipa/rkisp1/algorithms/agc.cpp | 23 ++++++-----\n src/ipa/rkisp1/algorithms/agc.h | 5 +--\n 8 files changed, 60 insertions(+), 47 deletions(-)","diff":"diff --git a/src/ipa/ipu3/algorithms/agc.cpp b/src/ipa/ipu3/algorithms/agc.cpp\nindex 39d0aebb0838..98a034a47625 100644\n--- a/src/ipa/ipu3/algorithms/agc.cpp\n+++ b/src/ipa/ipu3/algorithms/agc.cpp\n@@ -27,6 +27,7 @@\n namespace libcamera {\n \n using namespace std::literals::chrono_literals;\n+using namespace std::placeholders;\n \n namespace ipa::ipu3::algorithms {\n \n@@ -224,7 +225,8 @@ void Agc::process(IPAContext &context, [[maybe_unused]] const uint32_t frame,\n \tutils::Duration newExposureTime;\n \tdouble aGain, dGain;\n \tstd::tie(newExposureTime, aGain, dGain) =\n-\t\tcalculateNewEv(context.activeState.agc.constraintMode,\n+\t\tcalculateNewEv(std::bind(&Agc::estimateLuminance, this, _1),\n+\t\t\t context.activeState.agc.constraintMode,\n \t\t\t context.activeState.agc.exposureMode, hist,\n \t\t\t effectiveExposureValue);\n \ndiff --git a/src/ipa/ipu3/algorithms/agc.h b/src/ipa/ipu3/algorithms/agc.h\nindex 890c271b4462..8e182cd7cff3 100644\n--- a/src/ipa/ipu3/algorithms/agc.h\n+++ b/src/ipa/ipu3/algorithms/agc.h\n@@ -38,7 +38,7 @@ public:\n \t\t ControlList &metadata) override;\n \n private:\n-\tdouble estimateLuminance(double gain) const override;\n+\tdouble estimateLuminance(double gain) const;\n \tHistogram parseStatistics(const ipu3_uapi_stats_3a *stats,\n \t\t\t\t const ipu3_uapi_grid_config &grid);\n \ndiff --git a/src/ipa/libipa/agc_mean_luminance.cpp b/src/ipa/libipa/agc_mean_luminance.cpp\nindex ff96a381ffce..df7efb284a89 100644\n--- a/src/ipa/libipa/agc_mean_luminance.cpp\n+++ b/src/ipa/libipa/agc_mean_luminance.cpp\n@@ -18,7 +18,7 @@ using namespace libcamera::controls;\n \n /**\n * \\file agc_mean_luminance.h\n- * \\brief Base class implementing mean luminance AEGC\n+ * \\brief Class implementing mean luminance AEGC\n */\n \n namespace libcamera {\n@@ -53,6 +53,21 @@ static constexpr double kDefaultRelativeLuminanceTarget = 0.16;\n */\n static constexpr double kMaxRelativeLuminanceTarget = 0.95;\n \n+/**\n+ * \\fn AgcMeanLuminance::EstimateLuminanceFn\n+ * \\brief Function to estimate the mean luminance given a gain\n+ * \\param[in] gain The gain with which to adjust the luminance estimate\n+ *\n+ * Callback functions of this type are used within \\a calculateNewEv to estimate\n+ * the average relative luminance of the frame that would be output by the\n+ * sensor if an additional \\a gain was applied. It is a is implemented as\n+ * callback function because estimation of luminance is a hardware-specific\n+ * operation, which depends wholly on the format of the stats that are delivered\n+ * to libcamera from the ISP.\n+ *\n+ * \\return The normalised relative luminance of the image\n+ */\n+\n /**\n * \\struct AgcMeanLuminance::AgcConstraint\n * \\brief The boundaries and target for an AeConstraintMode constraint\n@@ -133,13 +148,11 @@ static constexpr double kMaxRelativeLuminanceTarget = 0.95;\n * will determine the supportable precision of the constraints.\n *\n * IPA modules that want to use this class to implement their AEGC algorithm\n- * should derive it and provide an overriding estimateLuminance() function for\n- * this class to use. They must call parseTuningData() in init(), and must also\n- * call setLimits() and resetFrameCounter() in configure(). They may then use\n- * calculateNewEv() in process(). If the limits passed to setLimits() change for\n- * any reason (for example, in response to a FrameDurationLimit control being\n- * passed in queueRequest()) then setLimits() must be called again with the new\n- * values.\n+ * must call parseTuningData() in init(), and must also call setLimits() and\n+ * resetFrameCounter() in configure(). They may then use calculateNewEv() in\n+ * process(). If the limits passed to setLimits() change for any reason (for\n+ * example, in response to a FrameDurationLimit control being passed in\n+ * queueRequest()) then setLimits() must be called again with the new values.\n */\n \n AgcMeanLuminance::AgcMeanLuminance()\n@@ -420,28 +433,12 @@ void AgcMeanLuminance::setLimits(utils::Duration minExposureTime,\n * \\brief Get the controls that have been generated after parsing tuning data\n */\n \n-/**\n- * \\fn AgcMeanLuminance::estimateLuminance(const double gain)\n- * \\brief Estimate the luminance of an image, adjusted by a given gain\n- * \\param[in] gain The gain with which to adjust the luminance estimate\n- *\n- * This function estimates the average relative luminance of the frame that\n- * would be output by the sensor if an additional \\a gain was applied. It is a\n- * pure virtual function because estimation of luminance is a hardware-specific\n- * operation, which depends wholly on the format of the stats that are delivered\n- * to libcamera from the ISP. Derived classes must override this function with\n- * one that calculates the normalised mean luminance value across the entire\n- * image.\n- *\n- * \\return The normalised relative luminance of the image\n- */\n-\n /**\n * \\brief Estimate the initial gain needed to achieve a relative luminance\n * target\n * \\return The calculated initial gain\n */\n-double AgcMeanLuminance::estimateInitialGain() const\n+double AgcMeanLuminance::estimateInitialGain(EstimateLuminanceFn estimateLuminance) const\n {\n \tdouble yTarget = std::min(relativeLuminanceTarget_ * exposureCompensation_,\n \t\t\t\t kMaxRelativeLuminanceTarget);\n@@ -542,6 +539,7 @@ utils::Duration AgcMeanLuminance::filterExposure(utils::Duration exposureValue)\n /**\n * \\brief Calculate the new exposure value and splut it between exposure time\n * and gain\n+ * \\param[in] estimateLuminance A function to get luminance estimates\n * \\param[in] constraintModeIndex The index of the current constraint mode\n * \\param[in] exposureModeIndex The index of the current exposure mode\n * \\param[in] yHist A Histogram from the ISP statistics to use in constraining\n@@ -553,10 +551,15 @@ utils::Duration AgcMeanLuminance::filterExposure(utils::Duration exposureValue)\n * exposure value is filtered to prevent rapid changes from frame to frame, and\n * divided into exposure time, analogue and digital gain.\n *\n+ * The \\a estimateLuminance shall estimate the average relative luminance of the\n+ * frame that would be output by the sensor if an additional \\a gain was\n+ * applied.\n+ *\n * \\return Tuple of exposure time, analogue gain, and digital gain\n */\n std::tuple\n-AgcMeanLuminance::calculateNewEv(uint32_t constraintModeIndex,\n+AgcMeanLuminance::calculateNewEv(EstimateLuminanceFn estimateLuminance,\n+\t\t\t\t uint32_t constraintModeIndex,\n \t\t\t\t uint32_t exposureModeIndex,\n \t\t\t\t const Histogram &yHist,\n \t\t\t\t utils::Duration effectiveExposureValue)\n@@ -580,7 +583,7 @@ AgcMeanLuminance::calculateNewEv(uint32_t constraintModeIndex,\n \t\treturn exposureModeHelper->splitExposure(10ms);\n \t}\n \n-\tdouble gain = estimateInitialGain();\n+\tdouble gain = estimateInitialGain(estimateLuminance);\n \tgain = constraintClampGain(constraintModeIndex, yHist, gain);\n \n \t/*\ndiff --git a/src/ipa/libipa/agc_mean_luminance.h b/src/ipa/libipa/agc_mean_luminance.h\nindex cad7ef845487..5e4c598c8ab9 100644\n--- a/src/ipa/libipa/agc_mean_luminance.h\n+++ b/src/ipa/libipa/agc_mean_luminance.h\n@@ -31,6 +31,8 @@ public:\n \tAgcMeanLuminance();\n \tvirtual ~AgcMeanLuminance();\n \n+\tusing EstimateLuminanceFn = std::function;\n+\n \tstruct AgcConstraint {\n \t\tenum class Bound {\n \t\t\tLower = 0,\n@@ -68,7 +70,8 @@ public:\n \t}\n \n \tstd::tuple\n-\tcalculateNewEv(uint32_t constraintModeIndex, uint32_t exposureModeIndex,\n+\tcalculateNewEv(EstimateLuminanceFn estimateLuminance,\n+\t\t uint32_t constraintModeIndex, uint32_t exposureModeIndex,\n \t\t const Histogram &yHist, utils::Duration effectiveExposureValue);\n \n \tvoid resetFrameCount()\n@@ -77,13 +80,11 @@ public:\n \t}\n \n private:\n-\tvirtual double estimateLuminance(const double gain) const = 0;\n-\n \tvoid parseRelativeLuminanceTarget(const YamlObject &tuningData);\n \tvoid parseConstraint(const YamlObject &modeDict, int32_t id);\n \tint parseConstraintModes(const YamlObject &tuningData);\n \tint parseExposureModes(const YamlObject &tuningData);\n-\tdouble estimateInitialGain() const;\n+\tdouble estimateInitialGain(EstimateLuminanceFn estimateLuminance) const;\n \tdouble constraintClampGain(uint32_t constraintModeIndex,\n \t\t\t\t const Histogram &hist,\n \t\t\t\t double gain);\ndiff --git a/src/ipa/mali-c55/algorithms/agc.cpp b/src/ipa/mali-c55/algorithms/agc.cpp\nindex 15963994b2d6..4bfb4aaeedf0 100644\n--- a/src/ipa/mali-c55/algorithms/agc.cpp\n+++ b/src/ipa/mali-c55/algorithms/agc.cpp\n@@ -8,6 +8,7 @@\n #include \"agc.h\"\n \n #include \n+#include \n \n #include \n #include \n@@ -21,6 +22,7 @@\n namespace libcamera {\n \n using namespace std::literals::chrono_literals;\n+using namespace std::placeholders;\n \n namespace ipa::mali_c55::algorithms {\n \n@@ -383,7 +385,8 @@ void Agc::process(IPAContext &context,\n \tutils::Duration shutterTime;\n \tdouble aGain, dGain;\n \tstd::tie(shutterTime, aGain, dGain) =\n-\t\tcalculateNewEv(activeState.agc.constraintMode,\n+\t\tcalculateNewEv(std::bind(&Agc::estimateLuminance, this, _1),\n+\t\t\t activeState.agc.constraintMode,\n \t\t\t activeState.agc.exposureMode, statistics_.yHist,\n \t\t\t effectiveExposureValue);\n \ndiff --git a/src/ipa/mali-c55/algorithms/agc.h b/src/ipa/mali-c55/algorithms/agc.h\nindex 0b4bf7eda1c2..698de57e1ba8 100644\n--- a/src/ipa/mali-c55/algorithms/agc.h\n+++ b/src/ipa/mali-c55/algorithms/agc.h\n@@ -64,7 +64,7 @@ public:\n \t\t ControlList &metadata) override;\n \n private:\n-\tdouble estimateLuminance(const double gain) const override;\n+\tdouble estimateLuminance(const double gain) const;\n \tsize_t fillGainParamBlock(IPAContext &context,\n \t\t\t\t IPAFrameContext &frameContext,\n \t\t\t\t mali_c55_params_block block);\ndiff --git a/src/ipa/rkisp1/algorithms/agc.cpp b/src/ipa/rkisp1/algorithms/agc.cpp\nindex 35440b67e999..3a078f9753f6 100644\n--- a/src/ipa/rkisp1/algorithms/agc.cpp\n+++ b/src/ipa/rkisp1/algorithms/agc.cpp\n@@ -440,16 +440,17 @@ void Agc::fillMetadata(IPAContext &context, IPAFrameContext &frameContext,\n *\n * \\return The relative luminance\n */\n-double Agc::estimateLuminance(double gain) const\n+double Agc::estimateLuminance(Span expMeans,\n+\t\t\t Span weights, double gain)\n {\n-\tASSERT(expMeans_.size() == weights_.size());\n+\tASSERT(expMeans.size() == weights.size());\n \tdouble ySum = 0.0;\n \tdouble wSum = 0.0;\n \n \t/* Sum the averages, saturated to 255. */\n-\tfor (unsigned i = 0; i < expMeans_.size(); i++) {\n-\t\tdouble w = weights_[i];\n-\t\tySum += std::min(expMeans_[i] * gain, 255.0) * w;\n+\tfor (unsigned i = 0; i < expMeans.size(); i++) {\n+\t\tdouble w = weights[i];\n+\t\tySum += std::min(expMeans[i] * gain, 255.0) * w;\n \t\twSum += w;\n \t}\n \n@@ -522,9 +523,7 @@ void Agc::process(IPAContext &context, [[maybe_unused]] const uint32_t frame,\n \t/* The lower 4 bits are fractional and meant to be discarded. */\n \tHistogram hist({ params->hist.hist_bins, context.hw->numHistogramBins },\n \t\t [](uint32_t x) { return x >> 4; });\n-\texpMeans_ = { params->ae.exp_mean, context.hw->numAeCells };\n \tstd::vector &modeWeights = meteringModes_.at(frameContext.agc.meteringMode);\n-\tweights_ = { modeWeights.data(), modeWeights.size() };\n \n \t/*\n \t * Set the AGC limits using the fixed exposure time and/or gain in\n@@ -566,10 +565,17 @@ void Agc::process(IPAContext &context, [[maybe_unused]] const uint32_t frame,\n \n \tsetExposureCompensation(pow(2.0, frameContext.agc.exposureValue));\n \n+\tAgcMeanLuminance::EstimateLuminanceFn estimateLuminanceFn = std::bind(\n+\t\t&Agc::estimateLuminance, this,\n+\t\tSpan(params->ae.exp_mean, context.hw->numAeCells),\n+\t\tSpan(modeWeights.data(), modeWeights.size()),\n+\t\tstd::placeholders::_1);\n+\n \tutils::Duration newExposureTime;\n \tdouble aGain, dGain;\n \tstd::tie(newExposureTime, aGain, dGain) =\n-\t\tcalculateNewEv(frameContext.agc.constraintMode,\n+\t\tcalculateNewEv(estimateLuminanceFn,\n+\t\t\t frameContext.agc.constraintMode,\n \t\t\t frameContext.agc.exposureMode,\n \t\t\t hist, effectiveExposureValue);\n \n@@ -590,7 +596,6 @@ void Agc::process(IPAContext &context, [[maybe_unused]] const uint32_t frame,\n \t\t\t std::max(frameContext.agc.minFrameDuration, newExposureTime));\n \n \tfillMetadata(context, frameContext, metadata);\n-\texpMeans_ = {};\n }\n \n REGISTER_IPA_ALGORITHM(Agc, \"Agc\")\ndiff --git a/src/ipa/rkisp1/algorithms/agc.h b/src/ipa/rkisp1/algorithms/agc.h\nindex 7867eed9c4e3..742c8f7371f3 100644\n--- a/src/ipa/rkisp1/algorithms/agc.h\n+++ b/src/ipa/rkisp1/algorithms/agc.h\n@@ -43,19 +43,18 @@ public:\n \t\t ControlList &metadata) override;\n \n private:\n+\tdouble estimateLuminance(Span expMeans,\n+\t\t\t\t Span weights, double gain);\n \tint parseMeteringModes(IPAContext &context, const YamlObject &tuningData);\n \tuint8_t computeHistogramPredivider(const Size &size,\n \t\t\t\t\t enum rkisp1_cif_isp_histogram_mode mode);\n \n \tvoid fillMetadata(IPAContext &context, IPAFrameContext &frameContext,\n \t\t\t ControlList &metadata);\n-\tdouble estimateLuminance(double gain) const override;\n \tvoid processFrameDuration(IPAContext &context,\n \t\t\t\t IPAFrameContext &frameContext,\n \t\t\t\t utils::Duration frameDuration);\n \n-\tSpan expMeans_;\n-\tSpan weights_;\n \n \tstd::map> meteringModes_;\n };\n","prefixes":["RFC","1/4"]}