[01/10] libipa: exposure_mode_helper: Add digital gain support
diff mbox series

Message ID 20261117-sklug-digital-gain-support-v1-v1-1-f0aa342ca877@ideasonboard.com
State New
Headers show
Series
  • libipa: agc: Add digital gain support
Related show

Commit Message

Stefan Klug Nov. 17, 2026, 8:47 a.m. UTC
The exposure mode helper splits a requested exposure into exposure time
and gain according to the configured stages. Extend this to support
digital gain. Per stage the specified exposure time, gain and then
digital gain get maxed out until the algorithm goes to the next stage.

Extend the setLimits function, so that digital gain can be constrained
by external limits the same way as exposure time and gain.

AgcMeanLuminance hardcodes a fixed digital gain limit of 1 for now and
will be extended in upcoming patches.

Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
---
 src/ipa/libipa/agc_mean_luminance.cpp   |  5 +-
 src/ipa/libipa/exposure_mode_helper.cpp | 90 +++++++++++++++++++++++----------
 src/ipa/libipa/exposure_mode_helper.h   |  8 ++-
 3 files changed, 73 insertions(+), 30 deletions(-)

Comments

Barnabás Pőcze Nov. 17, 2026, 10:38 a.m. UTC | #1
Hi

2026. 11. 17. 9:47 keltezéssel, Stefan Klug írta:
> The exposure mode helper splits a requested exposure into exposure time
> and gain according to the configured stages. Extend this to support
> digital gain. Per stage the specified exposure time, gain and then
> digital gain get maxed out until the algorithm goes to the next stage.
> 
> Extend the setLimits function, so that digital gain can be constrained
> by external limits the same way as exposure time and gain.
> 
> AgcMeanLuminance hardcodes a fixed digital gain limit of 1 for now and
> will be extended in upcoming patches.
> 
> Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
> ---

As a data point, in the raspberry pi world, there is an "agc global" parameter
for maximum digital gain, and the stage "gain" parameter restricts the combined
analogue and digital gain. This is also what the libipa documentation stated
(until that was removed since it wasn't in line with the implementation).

This proposed approach is more flexible, as digital gain can be applied even if there
is more exposure time or analogue gain available. Although I wonder what the practical
advantages of preferring digital over analogue gain are.

In any case this change or this series should close
https://gitlab.freedesktop.org/camera/libcamera/-/work_items/373
in one way or another.


>   src/ipa/libipa/agc_mean_luminance.cpp   |  5 +-
>   src/ipa/libipa/exposure_mode_helper.cpp | 90 +++++++++++++++++++++++----------
>   src/ipa/libipa/exposure_mode_helper.h   |  8 ++-
>   3 files changed, 73 insertions(+), 30 deletions(-)
> 
> [...]
> diff --git a/src/ipa/libipa/exposure_mode_helper.cpp b/src/ipa/libipa/exposure_mode_helper.cpp
> index 5c4242519bc1..e3a7d096aea6 100644
> --- a/src/ipa/libipa/exposure_mode_helper.cpp
> +++ b/src/ipa/libipa/exposure_mode_helper.cpp
> [...]
> @@ -226,29 +237,32 @@ ExposureModeHelper::splitExposure(utils::Duration exposure) const
>   	double gain;
>   	double quantGain;
>   	double quantGain2;
> -	bool gainFixed = minGain_ == maxGain_;
> -	bool exposureTimeFixed = minExposureTime_ == maxExposureTime_;
> +	double digitalGain;
>   
>   	/*
> -	 * There's no point entering the loop if we cannot change either gain
> -	 * nor exposure time anyway.
> +	 * There's no point entering the loop if we cannot change anything.
>   	 */
> -	if (exposureTimeFixed && gainFixed) {
> +	if (minExposureTime_ == maxExposureTime_ &&
> +	    minGain_ == maxGain_ &&
> +	    minDigitalGain_ == maxDigitalGain_) {
>   		exposureTime = clampExposureTime(minExposureTime_, &quantGain);
>   		gain = clampGain(minGain_, &quantGain2);
>   		quantGain *= quantGain2;
> +		digitalGain = clampDigitalGain(minDigitalGain_);

   digitalGain = minDigitalGain_;

?

Or I suppose you wanted to preserve the pattern?


>   
> -		return { exposureTime, gain, quantGain,
> -			 exposure / (exposureTime * gain * quantGain) };
> +		return { exposureTime, gain, quantGain, digitalGain };
>   	}
> [...]
> diff --git a/src/ipa/libipa/exposure_mode_helper.h b/src/ipa/libipa/exposure_mode_helper.h
> index d33a0fd822e4..aeae5a9cb700 100644
> --- a/src/ipa/libipa/exposure_mode_helper.h
> +++ b/src/ipa/libipa/exposure_mode_helper.h
> @@ -23,14 +23,15 @@ public:
>   	struct Stage {
>   		utils::Duration exposureTime;
>   		double gain;
> +		double digitalGain;

I think the documentation for this new member is missing.


> [...]

Patch
diff mbox series

diff --git a/src/ipa/libipa/agc_mean_luminance.cpp b/src/ipa/libipa/agc_mean_luminance.cpp
index 0c5ad469ae0e..33d938cc6a87 100644
--- a/src/ipa/libipa/agc_mean_luminance.cpp
+++ b/src/ipa/libipa/agc_mean_luminance.cpp
@@ -370,6 +370,7 @@  int parseExposureModes(AgcMeanLuminance::Configuration &config, const ValueNode
 				stages.push_back({
 					.exposureTime = std::chrono::microseconds(exposureTimes[i]),
 					.gain = gains[i],
+					.digitalGain = 1.0,
 				});
 			}
 
@@ -501,6 +502,7 @@  AgcMeanLuminance::AgcMeanLuminance(Configuration &&config)
 				{
 					.exposureTime = utils::Duration::max(),
 					.gain = std::numeric_limits<double>::max(),
+					.digitalGain = 1.0,
 				},
 			});
 }
@@ -543,7 +545,8 @@  void AgcMeanLuminance::setLimits(utils::Duration minExposureTime,
 				 std::vector<AgcMeanLuminance::AgcConstraint> constraints)
 {
 	for (auto &[id, helper] : exposureModeHelpers_)
-		helper.setLimits(minExposureTime, maxExposureTime, minGain, maxGain);
+		helper.setLimits(minExposureTime, maxExposureTime, minGain,
+				 maxGain, 1.0, 1.0);
 
 	additionalConstraints_ = std::move(constraints);
 }
diff --git a/src/ipa/libipa/exposure_mode_helper.cpp b/src/ipa/libipa/exposure_mode_helper.cpp
index 5c4242519bc1..e3a7d096aea6 100644
--- a/src/ipa/libipa/exposure_mode_helper.cpp
+++ b/src/ipa/libipa/exposure_mode_helper.cpp
@@ -82,7 +82,8 @@  namespace ipa {
  */
 ExposureModeHelper::ExposureModeHelper(std::vector<Stage> &&stages)
 	: stages_(std::move(stages)), lineDuration_(1us), minExposureTime_(0us),
-	  maxExposureTime_(0us), minGain_(0), maxGain_(0), sensorHelper_(nullptr)
+	  maxExposureTime_(0us), minGain_(0), maxGain_(0), minDigitalGain_(1.0),
+	  maxDigitalGain_(1.0), sensorHelper_(nullptr)
 {
 	ASSERT(!stages_.empty());
 }
@@ -115,24 +116,29 @@  void ExposureModeHelper::configure(utils::Duration lineDuration,
  * \param[in] maxExposureTime The maximum exposure time supported
  * \param[in] minGain The minimum analogue gain supported
  * \param[in] maxGain The maximum analogue gain supported
+ * \param[in] minDigitalGain The minimum digital gain supported
+ * \param[in] maxDigitalGain The maximum digital gain supported
  *
- * This function configures the exposure time and analogue gain limits that need
- * to be adhered to as the helper divides up exposure. Note that this function
- * *must* be called whenever those limits change and before splitExposure() is
- * used.
+ * This function configures the exposure time, analogue gain and digital gain
+ * limits that need to be adhered to as the helper divides up exposure. Note
+ * that this function *must* be called whenever those limits change and before
+ * splitExposure() is used.
  *
- * If the algorithm using the helpers needs to indicate that either exposure time
- * or analogue gain or both should be fixed it can do so by setting both the
- * minima and maxima to the same value.
+ * If the algorithm using the helpers needs to indicate that exposure time,
+ * analogue gain or digital gain should be fixed it can do so by setting the
+ * minimum and maximum to the same value.
  */
 void ExposureModeHelper::setLimits(utils::Duration minExposureTime,
 				   utils::Duration maxExposureTime,
-				   double minGain, double maxGain)
+				   double minGain, double maxGain,
+				   double minDigitalGain, double maxDigitalGain)
 {
 	minExposureTime_ = minExposureTime;
 	maxExposureTime_ = maxExposureTime;
 	minGain_ = minGain;
 	maxGain_ = maxGain;
+	minDigitalGain_ = minDigitalGain;
+	maxDigitalGain_ = maxDigitalGain;
 }
 
 utils::Duration ExposureModeHelper::clampExposureTime(utils::Duration exposureTime,
@@ -161,6 +167,11 @@  double ExposureModeHelper::clampGain(double gain, double *quantizationGain) cons
 	return clamped;
 }
 
+double ExposureModeHelper::clampDigitalGain(double gain) const
+{
+	return std::clamp(gain, minDigitalGain_, maxDigitalGain_);
+}
+
 /**
  * \struct ExposureModeHelper::Result
  * \brief Result of splitExposure()
@@ -226,29 +237,32 @@  ExposureModeHelper::splitExposure(utils::Duration exposure) const
 	double gain;
 	double quantGain;
 	double quantGain2;
-	bool gainFixed = minGain_ == maxGain_;
-	bool exposureTimeFixed = minExposureTime_ == maxExposureTime_;
+	double digitalGain;
 
 	/*
-	 * There's no point entering the loop if we cannot change either gain
-	 * nor exposure time anyway.
+	 * There's no point entering the loop if we cannot change anything.
 	 */
-	if (exposureTimeFixed && gainFixed) {
+	if (minExposureTime_ == maxExposureTime_ &&
+	    minGain_ == maxGain_ &&
+	    minDigitalGain_ == maxDigitalGain_) {
 		exposureTime = clampExposureTime(minExposureTime_, &quantGain);
 		gain = clampGain(minGain_, &quantGain2);
 		quantGain *= quantGain2;
+		digitalGain = clampDigitalGain(minDigitalGain_);
 
-		return { exposureTime, gain, quantGain,
-			 exposure / (exposureTime * gain * quantGain) };
+		return { exposureTime, gain, quantGain, digitalGain };
 	}
 
 	utils::Duration stageExposureTime = {};
 	double lastStageGain = clampGain(1.0);
+	double lastStageDigitalGain = clampDigitalGain(1.0);
 	double stageGain = {};
+	double stageDigitalGain = {};
 
 	for (const auto &stage : stages_) {
 		stageExposureTime = clampExposureTime(stage.exposureTime, &quantGain);
 		stageGain = clampGain(stage.gain, &quantGain2);
+		stageDigitalGain = clampDigitalGain(stage.digitalGain);
 
 		/*
 		 * We perform the clamping on both exposure time and gain in
@@ -259,26 +273,48 @@  ExposureModeHelper::splitExposure(utils::Duration exposure) const
 		 */
 
 		/* Clamp the gain to lastStageGain and regulate exposureTime. */
-		if (stageExposureTime * lastStageGain >= exposure) {
-			exposureTime = clampExposureTime(exposure / lastStageGain, &quantGain);
-			gain = clampGain(exposure / exposureTime, &quantGain2);
+		if (stageExposureTime * lastStageGain * lastStageDigitalGain >= exposure) {
+			auto targetExposure = exposure / (lastStageGain * lastStageDigitalGain);
+			exposureTime = clampExposureTime(targetExposure, &quantGain);
+
+			auto targetGain = exposure / (exposureTime * lastStageDigitalGain);
+			gain = clampGain(targetGain, &quantGain2);
 			quantGain *= quantGain2;
 
-			return { exposureTime, gain, quantGain,
-				 exposure / (exposureTime * gain * quantGain) };
+			auto targetDigitalGain = exposure / (exposureTime * gain * quantGain);
+			digitalGain = clampDigitalGain(targetDigitalGain);
+
+			return { exposureTime, gain, quantGain, digitalGain };
 		}
 
 		/* Clamp the exposureTime to stageExposureTime and regulate gain. */
-		if (stageExposureTime * stageGain >= exposure) {
+		if (stageExposureTime * stageGain * lastStageDigitalGain >= exposure) {
 			exposureTime = stageExposureTime;
-			gain = clampGain(exposure / exposureTime, &quantGain2);
+
+			auto targetGain = exposure / (exposureTime * lastStageDigitalGain);
+			gain = clampGain(targetGain, &quantGain2);
 			quantGain *= quantGain2;
 
-			return { exposureTime, gain, quantGain,
-				 exposure / (exposureTime * gain * quantGain) };
+			auto targetDigitalGain = exposure / (exposureTime * gain * quantGain);
+			digitalGain = clampDigitalGain(targetDigitalGain);
+
+			return { exposureTime, gain, quantGain, digitalGain };
+		}
+
+		/* Clamp the exposureTime to stageExposureTime and regulate gain. */
+		if (stageExposureTime * stageGain * stageDigitalGain >= exposure) {
+			exposureTime = stageExposureTime;
+			gain = stageGain;
+			quantGain *= quantGain2;
+
+			auto targetDigitalGain = exposure / (exposureTime * gain * quantGain);
+			digitalGain = clampDigitalGain(targetDigitalGain);
+
+			return { exposureTime, gain, quantGain, targetDigitalGain };
 		}
 
 		lastStageGain = stageGain;
+		lastStageDigitalGain = stageDigitalGain;
 	}
 
 	/*
@@ -288,9 +324,9 @@  ExposureModeHelper::splitExposure(utils::Duration exposure) const
 	exposureTime = stageExposureTime;
 	gain = stageGain;
 	quantGain *= quantGain2;
+	digitalGain = stageDigitalGain;
 
-	return { exposureTime, gain, quantGain,
-		 exposure / (exposureTime * gain * quantGain) };
+	return { exposureTime, gain, quantGain, digitalGain };
 }
 
 } /* namespace ipa */
diff --git a/src/ipa/libipa/exposure_mode_helper.h b/src/ipa/libipa/exposure_mode_helper.h
index d33a0fd822e4..aeae5a9cb700 100644
--- a/src/ipa/libipa/exposure_mode_helper.h
+++ b/src/ipa/libipa/exposure_mode_helper.h
@@ -23,14 +23,15 @@  public:
 	struct Stage {
 		utils::Duration exposureTime;
 		double gain;
+		double digitalGain;
 	};
 
 	ExposureModeHelper(std::vector<Stage> &&stages);
 
 	void configure(utils::Duration lineLength, const CameraSensorHelper *sensorHelper);
 	void setLimits(utils::Duration minExposureTime, utils::Duration maxExposureTime,
-		       double minGain, double maxGain);
-
+		       double minGain, double maxGain, double minDigitalGain,
+		       double maxDigitalGain);
 	struct Result {
 		utils::Duration exposureTime;
 		double analogueGain;
@@ -44,6 +45,7 @@  private:
 	utils::Duration clampExposureTime(utils::Duration exposureTime,
 					  double *quantizationGain = nullptr) const;
 	double clampGain(double gain, double *quantizationGain = nullptr) const;
+	double clampDigitalGain(double gain) const;
 
 	std::vector<Stage> stages_;
 
@@ -52,6 +54,8 @@  private:
 	utils::Duration maxExposureTime_;
 	double minGain_;
 	double maxGain_;
+	double minDigitalGain_;
+	double maxDigitalGain_;
 	const CameraSensorHelper *sensorHelper_;
 };