[RFC,v4,09/23] ipa: libipa: exposure_mode_helper: Consider last stage as hard-limit
diff mbox series

Message ID 20261026132045.269007-10-barnabas.pocze@ideasonboard.com
State Superseded
Headers show
Series
  • ipa: libipa: agc: Take exposure margin into account
Related show

Commit Message

Barnabás Pőcze Oct. 26, 2026, 1:20 p.m. UTC
Currently `splitExposure()` will raise the exposure and analogue gain above
what is specified in the last stage, if the desired exposure could not be
reached. This behaviour is different from that of the raspberry pi ipa,
and also could be surprising to the user / tuning file creator.

So make sure that the exposure time and analogue gain is limited by the
last stage, in addition to the runtime controlled upper bound.

With this change, at least one stage is required, so an assertion is added
in the constructor. Also modify the general agc algorithm to provide
stages for the implicitly instantiated "Maximize" mode.

Closes: https://gitlab.freedesktop.org/camera/libcamera/-/work_items/362
Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
---
 src/ipa/libipa/agc.cpp                  | 13 +++++++++----
 src/ipa/libipa/exposure_mode_helper.cpp | 16 +++++++---------
 2 files changed, 16 insertions(+), 13 deletions(-)

Comments

Jacopo Mondi Oct. 27, 2026, 8:28 a.m. UTC | #1
Hi Barnabás

On Mon, Oct 26, 2026 at 02:20:31PM +0100, Barnabás Pőcze wrote:
> Currently `splitExposure()` will raise the exposure and analogue gain above
> what is specified in the last stage, if the desired exposure could not be
> reached. This behaviour is different from that of the raspberry pi ipa,
> and also could be surprising to the user / tuning file creator.
>
> So make sure that the exposure time and analogue gain is limited by the
> last stage, in addition to the runtime controlled upper bound.
>
> With this change, at least one stage is required, so an assertion is added
> in the constructor. Also modify the general agc algorithm to provide
> stages for the implicitly instantiated "Maximize" mode.
>
> Closes: https://gitlab.freedesktop.org/camera/libcamera/-/work_items/362
> Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>

Ack, this will make handling all modes equal now that we require
stages, and also align libipa and rpi

> ---
>  src/ipa/libipa/agc.cpp                  | 13 +++++++++----
>  src/ipa/libipa/exposure_mode_helper.cpp | 16 +++++++---------
>  2 files changed, 16 insertions(+), 13 deletions(-)
>
> diff --git a/src/ipa/libipa/agc.cpp b/src/ipa/libipa/agc.cpp
> index b899f7c643..fb615f0af2 100644
> --- a/src/ipa/libipa/agc.cpp
> +++ b/src/ipa/libipa/agc.cpp
> @@ -442,14 +442,19 @@ void fillMissing(AgcMeanLuminance::Configuration &config)
>  {
>  	/*
>  	 * If we don't have any exposure modes in the tuning data we create an
> -	 * ExposureModeHelper using an empty vector of stages. This will result
> -	 * in the ExposureModeHelper simply driving the exposure time as high as
> -	 * possible before touching gain.
> +	 * ExposureModeHelper using a single stage of effectively unlimited exposure
> +	 * and gain. This will result in the ExposureModeHelper simply driving the
> +	 * exposure time as high as possible before touching gain.
>  	 */
>  	if (config.exposureModeHelpers.empty())
>  		config.exposureModeHelpers.try_emplace(
>  			controls::ExposureMaximize,
> -			std::vector<ExposureModeHelper::Stage>{});
> +			std::vector{
> +				ExposureModeHelper::Stage{
> +					.exposureTime = utils::Duration::max(),
> +					.gain = std::numeric_limits<double>::max(),
> +				},
> +			});
>
>  	/*
>  	 * If the tuning data file contains no constraints then we use the
> diff --git a/src/ipa/libipa/exposure_mode_helper.cpp b/src/ipa/libipa/exposure_mode_helper.cpp
> index 8a712c6da9..4123f73cc8 100644
> --- a/src/ipa/libipa/exposure_mode_helper.cpp
> +++ b/src/ipa/libipa/exposure_mode_helper.cpp
> @@ -84,6 +84,7 @@ ExposureModeHelper::ExposureModeHelper(std::vector<Stage> &&stages)
>  	: stages_(std::move(stages)), lineDuration_(1us), minExposureTime_(0us),
>  	  maxExposureTime_(0us), minGain_(0), maxGain_(0), sensorHelper_(nullptr)
>  {
> +	ASSERT(!stages_.empty());
>  }
>
>  /**
> @@ -203,8 +204,8 @@ double ExposureModeHelper::clampGain(double gain, double *quantizationGain) cons
>   * value.
>   *
>   * If no combination of exposure time and gain limits is found that meets the
> - * required exposure, the helper falls-back to simply maximising the exposure
> - * time first, followed by analogue gain, followed by digital gain.
> + * required exposure, then the exposure and gain of the last stage will be used,
> + * and the digital gain will be increased as necessary.
>   *
>   * During the calculations the gain missed due to quantization is recorded and
>   * returned as quantization gain. The quantization gain is not included in the
> @@ -280,14 +281,11 @@ ExposureModeHelper::splitExposure(utils::Duration exposure) const
>  	}
>
>  	/*
> -	 * From here on all we can do is max out the exposure time, followed by
> -	 * the analogue gain. If we still haven't achieved the target we send
> -	 * the rest of the exposure time to digital gain. If we were given no
> -	 * stages to use then the default gain of 1.0 is used so that exposure
> -	 * time is maxed before gain is touched at all.
> +	 * If no stages could satisfy the desired exposure, then use the last
> +	 * stage's exposure time and gain.
>  	 */

How can we even get here now that the last stage uses max() as its
limit ?


> -	exposureTime = clampExposureTime(exposure / lastStageGain, &quantGain);
> -	gain = clampGain(exposure / exposureTime, &quantGain2);
> +	exposureTime = clampExposureTime(stages_.back().exposureTime, &quantGain);
> +	gain = clampGain(stages_.back().gain, &quantGain2);
>  	quantGain *= quantGain2;
>
>  	return { exposureTime, gain, quantGain,
> --
> 2.56.0
>
Barnabás Pőcze Oct. 27, 2026, 8:35 a.m. UTC | #2
2026. 10. 27. 9:28 keltezéssel, Jacopo Mondi írta:
> Hi Barnabás
> 
> On Mon, Oct 26, 2026 at 02:20:31PM +0100, Barnabás Pőcze wrote:
>> Currently `splitExposure()` will raise the exposure and analogue gain above
>> what is specified in the last stage, if the desired exposure could not be
>> reached. This behaviour is different from that of the raspberry pi ipa,
>> and also could be surprising to the user / tuning file creator.
>>
>> So make sure that the exposure time and analogue gain is limited by the
>> last stage, in addition to the runtime controlled upper bound.
>>
>> With this change, at least one stage is required, so an assertion is added
>> in the constructor. Also modify the general agc algorithm to provide
>> stages for the implicitly instantiated "Maximize" mode.
>>
>> Closes: https://gitlab.freedesktop.org/camera/libcamera/-/work_items/362
>> Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
> 
> Ack, this will make handling all modes equal now that we require
> stages, and also align libipa and rpi
> 
>> ---
>>   src/ipa/libipa/agc.cpp                  | 13 +++++++++----
>>   src/ipa/libipa/exposure_mode_helper.cpp | 16 +++++++---------
>>   2 files changed, 16 insertions(+), 13 deletions(-)
>>
>> diff --git a/src/ipa/libipa/agc.cpp b/src/ipa/libipa/agc.cpp
>> index b899f7c643..fb615f0af2 100644
>> --- a/src/ipa/libipa/agc.cpp
>> +++ b/src/ipa/libipa/agc.cpp
>> @@ -442,14 +442,19 @@ void fillMissing(AgcMeanLuminance::Configuration &config)
>>   {
>>   	/*
>>   	 * If we don't have any exposure modes in the tuning data we create an
>> -	 * ExposureModeHelper using an empty vector of stages. This will result
>> -	 * in the ExposureModeHelper simply driving the exposure time as high as
>> -	 * possible before touching gain.
>> +	 * ExposureModeHelper using a single stage of effectively unlimited exposure
>> +	 * and gain. This will result in the ExposureModeHelper simply driving the
>> +	 * exposure time as high as possible before touching gain.
>>   	 */
>>   	if (config.exposureModeHelpers.empty())
>>   		config.exposureModeHelpers.try_emplace(
>>   			controls::ExposureMaximize,
>> -			std::vector<ExposureModeHelper::Stage>{});
>> +			std::vector{
>> +				ExposureModeHelper::Stage{
>> +					.exposureTime = utils::Duration::max(),
>> +					.gain = std::numeric_limits<double>::max(),
>> +				},
>> +			});
>>
>>   	/*
>>   	 * If the tuning data file contains no constraints then we use the
>> diff --git a/src/ipa/libipa/exposure_mode_helper.cpp b/src/ipa/libipa/exposure_mode_helper.cpp
>> index 8a712c6da9..4123f73cc8 100644
>> --- a/src/ipa/libipa/exposure_mode_helper.cpp
>> +++ b/src/ipa/libipa/exposure_mode_helper.cpp
>> @@ -84,6 +84,7 @@ ExposureModeHelper::ExposureModeHelper(std::vector<Stage> &&stages)
>>   	: stages_(std::move(stages)), lineDuration_(1us), minExposureTime_(0us),
>>   	  maxExposureTime_(0us), minGain_(0), maxGain_(0), sensorHelper_(nullptr)
>>   {
>> +	ASSERT(!stages_.empty());
>>   }
>>
>>   /**
>> @@ -203,8 +204,8 @@ double ExposureModeHelper::clampGain(double gain, double *quantizationGain) cons
>>    * value.
>>    *
>>    * If no combination of exposure time and gain limits is found that meets the
>> - * required exposure, the helper falls-back to simply maximising the exposure
>> - * time first, followed by analogue gain, followed by digital gain.
>> + * required exposure, then the exposure and gain of the last stage will be used,
>> + * and the digital gain will be increased as necessary.
>>    *
>>    * During the calculations the gain missed due to quantization is recorded and
>>    * returned as quantization gain. The quantization gain is not included in the
>> @@ -280,14 +281,11 @@ ExposureModeHelper::splitExposure(utils::Duration exposure) const
>>   	}
>>
>>   	/*
>> -	 * From here on all we can do is max out the exposure time, followed by
>> -	 * the analogue gain. If we still haven't achieved the target we send
>> -	 * the rest of the exposure time to digital gain. If we were given no
>> -	 * stages to use then the default gain of 1.0 is used so that exposure
>> -	 * time is maxed before gain is touched at all.
>> +	 * If no stages could satisfy the desired exposure, then use the last
>> +	 * stage's exposure time and gain.
>>   	 */
> 
> How can we even get here now that the last stage uses max() as its
> limit ?

How do you mean? This can always be reached, even with the fallback "Maximize" mode
as defined above, because in the end, both parameters are limited by the sensors
capabilities, so even in that case it is possible that the requested exposure cannot
be satisfied by the sensor, then the execution will reach this part.

And the same applies to any other exposure mode, if the smallest of the (last exposure stage)
and (sensor capabilities) cannot satisfy the required exposure, then execution will
reach this point.


> 
> 
>> -	exposureTime = clampExposureTime(exposure / lastStageGain, &quantGain);
>> -	gain = clampGain(exposure / exposureTime, &quantGain2);
>> +	exposureTime = clampExposureTime(stages_.back().exposureTime, &quantGain);
>> +	gain = clampGain(stages_.back().gain, &quantGain2);
>>   	quantGain *= quantGain2;
>>
>>   	return { exposureTime, gain, quantGain,
>> --
>> 2.56.0
>>
Jacopo Mondi Oct. 27, 2026, 12:16 p.m. UTC | #3
Hi Barnabás

On Tue, Oct 27, 2026 at 09:35:04AM +0100, Barnabás Pőcze wrote:
> 2026. 10. 27. 9:28 keltezéssel, Jacopo Mondi írta:
> > Hi Barnabás
> >
> > On Mon, Oct 26, 2026 at 02:20:31PM +0100, Barnabás Pőcze wrote:
> > > Currently `splitExposure()` will raise the exposure and analogue gain above
> > > what is specified in the last stage, if the desired exposure could not be
> > > reached. This behaviour is different from that of the raspberry pi ipa,
> > > and also could be surprising to the user / tuning file creator.
> > >
> > > So make sure that the exposure time and analogue gain is limited by the
> > > last stage, in addition to the runtime controlled upper bound.
> > >
> > > With this change, at least one stage is required, so an assertion is added
> > > in the constructor. Also modify the general agc algorithm to provide
> > > stages for the implicitly instantiated "Maximize" mode.
> > >
> > > Closes: https://gitlab.freedesktop.org/camera/libcamera/-/work_items/362
> > > Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
> >
> > Ack, this will make handling all modes equal now that we require
> > stages, and also align libipa and rpi
> >
> > > ---
> > >   src/ipa/libipa/agc.cpp                  | 13 +++++++++----
> > >   src/ipa/libipa/exposure_mode_helper.cpp | 16 +++++++---------
> > >   2 files changed, 16 insertions(+), 13 deletions(-)
> > >
> > > diff --git a/src/ipa/libipa/agc.cpp b/src/ipa/libipa/agc.cpp
> > > index b899f7c643..fb615f0af2 100644
> > > --- a/src/ipa/libipa/agc.cpp
> > > +++ b/src/ipa/libipa/agc.cpp
> > > @@ -442,14 +442,19 @@ void fillMissing(AgcMeanLuminance::Configuration &config)
> > >   {
> > >   	/*
> > >   	 * If we don't have any exposure modes in the tuning data we create an
> > > -	 * ExposureModeHelper using an empty vector of stages. This will result
> > > -	 * in the ExposureModeHelper simply driving the exposure time as high as
> > > -	 * possible before touching gain.
> > > +	 * ExposureModeHelper using a single stage of effectively unlimited exposure
> > > +	 * and gain. This will result in the ExposureModeHelper simply driving the
> > > +	 * exposure time as high as possible before touching gain.
> > >   	 */
> > >   	if (config.exposureModeHelpers.empty())
> > >   		config.exposureModeHelpers.try_emplace(
> > >   			controls::ExposureMaximize,
> > > -			std::vector<ExposureModeHelper::Stage>{});
> > > +			std::vector{
> > > +				ExposureModeHelper::Stage{
> > > +					.exposureTime = utils::Duration::max(),
> > > +					.gain = std::numeric_limits<double>::max(),
> > > +				},
> > > +			});
> > >
> > >   	/*
> > >   	 * If the tuning data file contains no constraints then we use the
> > > diff --git a/src/ipa/libipa/exposure_mode_helper.cpp b/src/ipa/libipa/exposure_mode_helper.cpp
> > > index 8a712c6da9..4123f73cc8 100644
> > > --- a/src/ipa/libipa/exposure_mode_helper.cpp
> > > +++ b/src/ipa/libipa/exposure_mode_helper.cpp
> > > @@ -84,6 +84,7 @@ ExposureModeHelper::ExposureModeHelper(std::vector<Stage> &&stages)
> > >   	: stages_(std::move(stages)), lineDuration_(1us), minExposureTime_(0us),
> > >   	  maxExposureTime_(0us), minGain_(0), maxGain_(0), sensorHelper_(nullptr)
> > >   {
> > > +	ASSERT(!stages_.empty());
> > >   }
> > >
> > >   /**
> > > @@ -203,8 +204,8 @@ double ExposureModeHelper::clampGain(double gain, double *quantizationGain) cons
> > >    * value.
> > >    *
> > >    * If no combination of exposure time and gain limits is found that meets the
> > > - * required exposure, the helper falls-back to simply maximising the exposure
> > > - * time first, followed by analogue gain, followed by digital gain.
> > > + * required exposure, then the exposure and gain of the last stage will be used,
> > > + * and the digital gain will be increased as necessary.
> > >    *
> > >    * During the calculations the gain missed due to quantization is recorded and
> > >    * returned as quantization gain. The quantization gain is not included in the
> > > @@ -280,14 +281,11 @@ ExposureModeHelper::splitExposure(utils::Duration exposure) const
> > >   	}
> > >
> > >   	/*
> > > -	 * From here on all we can do is max out the exposure time, followed by
> > > -	 * the analogue gain. If we still haven't achieved the target we send
> > > -	 * the rest of the exposure time to digital gain. If we were given no
> > > -	 * stages to use then the default gain of 1.0 is used so that exposure
> > > -	 * time is maxed before gain is touched at all.
> > > +	 * If no stages could satisfy the desired exposure, then use the last
> > > +	 * stage's exposure time and gain.
> > >   	 */
> >
> > How can we even get here now that the last stage uses max() as its
> > limit ?
>
> How do you mean? This can always be reached, even with the fallback "Maximize" mode

I'm looking at the above for loop

		if (stageExposureTime * stageGain >= exposure) {
			exposureTime = stageExposureTime;
			gain = clampGain(exposure / exposureTime, &quantGain2);
			quantGain *= quantGain2;

			return { exposureTime, gain, quantGain,
				 exposure / (exposureTime * gain * quantGain) };
		}

> as defined above, because in the end, both parameters are limited by the sensors
> capabilities, so even in that case it is possible that the requested exposure cannot
> be satisfied by the sensor, then the execution will reach this part.

I might have missed where the Maximize stage is limited by the
sensor's capabilities

		config.exposureModeHelpers.try_emplace(
			controls::ExposureMaximize,
			std::vector{
				ExposureModeHelper::Stage{
					.exposureTime = utils::Duration::max(),
					.gain = std::numeric_limits<double>::max(),
				},
			});


>
> And the same applies to any other exposure mode, if the smallest of the (last exposure stage)
> and (sensor capabilities) cannot satisfy the required exposure, then execution will
> reach this point.
>

You're right about other exposure modes.

>
> >
> >
> > > -	exposureTime = clampExposureTime(exposure / lastStageGain, &quantGain);
> > > -	gain = clampGain(exposure / exposureTime, &quantGain2);
> > > +	exposureTime = clampExposureTime(stages_.back().exposureTime, &quantGain);
> > > +	gain = clampGain(stages_.back().gain, &quantGain2);

Bu tn that case however can't we use lastStageGain as we looped over
all stages ? This doesn't make much difference though, and your way is
nicer.

> > >   	quantGain *= quantGain2;
> > >
> > >   	return { exposureTime, gain, quantGain,
> > > --
> > > 2.56.0
> > >
>
Barnabás Pőcze Oct. 27, 2026, 12:37 p.m. UTC | #4
2026. 10. 27. 13:16 keltezéssel, Jacopo Mondi írta:
> Hi Barnabás
> 
> On Tue, Oct 27, 2026 at 09:35:04AM +0100, Barnabás Pőcze wrote:
>> 2026. 10. 27. 9:28 keltezéssel, Jacopo Mondi írta:
>>> Hi Barnabás
>>>
>>> On Mon, Oct 26, 2026 at 02:20:31PM +0100, Barnabás Pőcze wrote:
>>>> Currently `splitExposure()` will raise the exposure and analogue gain above
>>>> what is specified in the last stage, if the desired exposure could not be
>>>> reached. This behaviour is different from that of the raspberry pi ipa,
>>>> and also could be surprising to the user / tuning file creator.
>>>>
>>>> So make sure that the exposure time and analogue gain is limited by the
>>>> last stage, in addition to the runtime controlled upper bound.
>>>>
>>>> With this change, at least one stage is required, so an assertion is added
>>>> in the constructor. Also modify the general agc algorithm to provide
>>>> stages for the implicitly instantiated "Maximize" mode.
>>>>
>>>> Closes: https://gitlab.freedesktop.org/camera/libcamera/-/work_items/362
>>>> Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
>>>
>>> Ack, this will make handling all modes equal now that we require
>>> stages, and also align libipa and rpi
>>>
>>>> ---
>>>>    src/ipa/libipa/agc.cpp                  | 13 +++++++++----
>>>>    src/ipa/libipa/exposure_mode_helper.cpp | 16 +++++++---------
>>>>    2 files changed, 16 insertions(+), 13 deletions(-)
>>>>
>>>> diff --git a/src/ipa/libipa/agc.cpp b/src/ipa/libipa/agc.cpp
>>>> index b899f7c643..fb615f0af2 100644
>>>> --- a/src/ipa/libipa/agc.cpp
>>>> +++ b/src/ipa/libipa/agc.cpp
>>>> @@ -442,14 +442,19 @@ void fillMissing(AgcMeanLuminance::Configuration &config)
>>>>    {
>>>>    	/*
>>>>    	 * If we don't have any exposure modes in the tuning data we create an
>>>> -	 * ExposureModeHelper using an empty vector of stages. This will result
>>>> -	 * in the ExposureModeHelper simply driving the exposure time as high as
>>>> -	 * possible before touching gain.
>>>> +	 * ExposureModeHelper using a single stage of effectively unlimited exposure
>>>> +	 * and gain. This will result in the ExposureModeHelper simply driving the
>>>> +	 * exposure time as high as possible before touching gain.
>>>>    	 */
>>>>    	if (config.exposureModeHelpers.empty())
>>>>    		config.exposureModeHelpers.try_emplace(
>>>>    			controls::ExposureMaximize,
>>>> -			std::vector<ExposureModeHelper::Stage>{});
>>>> +			std::vector{
>>>> +				ExposureModeHelper::Stage{
>>>> +					.exposureTime = utils::Duration::max(),
>>>> +					.gain = std::numeric_limits<double>::max(),
>>>> +				},
>>>> +			});
>>>>
>>>>    	/*
>>>>    	 * If the tuning data file contains no constraints then we use the
>>>> diff --git a/src/ipa/libipa/exposure_mode_helper.cpp b/src/ipa/libipa/exposure_mode_helper.cpp
>>>> index 8a712c6da9..4123f73cc8 100644
>>>> --- a/src/ipa/libipa/exposure_mode_helper.cpp
>>>> +++ b/src/ipa/libipa/exposure_mode_helper.cpp
>>>> @@ -84,6 +84,7 @@ ExposureModeHelper::ExposureModeHelper(std::vector<Stage> &&stages)
>>>>    	: stages_(std::move(stages)), lineDuration_(1us), minExposureTime_(0us),
>>>>    	  maxExposureTime_(0us), minGain_(0), maxGain_(0), sensorHelper_(nullptr)
>>>>    {
>>>> +	ASSERT(!stages_.empty());
>>>>    }
>>>>
>>>>    /**
>>>> @@ -203,8 +204,8 @@ double ExposureModeHelper::clampGain(double gain, double *quantizationGain) cons
>>>>     * value.
>>>>     *
>>>>     * If no combination of exposure time and gain limits is found that meets the
>>>> - * required exposure, the helper falls-back to simply maximising the exposure
>>>> - * time first, followed by analogue gain, followed by digital gain.
>>>> + * required exposure, then the exposure and gain of the last stage will be used,
>>>> + * and the digital gain will be increased as necessary.
>>>>     *
>>>>     * During the calculations the gain missed due to quantization is recorded and
>>>>     * returned as quantization gain. The quantization gain is not included in the
>>>> @@ -280,14 +281,11 @@ ExposureModeHelper::splitExposure(utils::Duration exposure) const
>>>>    	}
>>>>
>>>>    	/*
>>>> -	 * From here on all we can do is max out the exposure time, followed by
>>>> -	 * the analogue gain. If we still haven't achieved the target we send
>>>> -	 * the rest of the exposure time to digital gain. If we were given no
>>>> -	 * stages to use then the default gain of 1.0 is used so that exposure
>>>> -	 * time is maxed before gain is touched at all.
>>>> +	 * If no stages could satisfy the desired exposure, then use the last
>>>> +	 * stage's exposure time and gain.
>>>>    	 */
>>>
>>> How can we even get here now that the last stage uses max() as its
>>> limit ?
>>
>> How do you mean? This can always be reached, even with the fallback "Maximize" mode
> 
> I'm looking at the above for loop
> 
> 		if (stageExposureTime * stageGain >= exposure) {
> 			exposureTime = stageExposureTime;
> 			gain = clampGain(exposure / exposureTime, &quantGain2);
> 			quantGain *= quantGain2;
> 
> 			return { exposureTime, gain, quantGain,
> 				 exposure / (exposureTime * gain * quantGain) };
> 		}
> 
>> as defined above, because in the end, both parameters are limited by the sensors
>> capabilities, so even in that case it is possible that the requested exposure cannot
>> be satisfied by the sensor, then the execution will reach this part.
> 
> I might have missed where the Maximize stage is limited by the
> sensor's capabilities
> 
> 		config.exposureModeHelpers.try_emplace(
> 			controls::ExposureMaximize,
> 			std::vector{
> 				ExposureModeHelper::Stage{
> 					.exposureTime = utils::Duration::max(),
> 					.gain = std::numeric_limits<double>::max(),
> 				},
> 			});

Both `stageExposureTime` and `stageGain` go through the `clamp*()` functions, which does the clamping,
so they will be `maxExposureTime_` and `maxAnalogueGain_`, respectively, which corresponds
to the sensor capabilities (ignoring `FrameDurationLimits` and manual exp/gain control).


> 
> 
>>
>> And the same applies to any other exposure mode, if the smallest of the (last exposure stage)
>> and (sensor capabilities) cannot satisfy the required exposure, then execution will
>> reach this point.
>>
> 
> You're right about other exposure modes.
> 
>>
>>>
>>>
>>>> -	exposureTime = clampExposureTime(exposure / lastStageGain, &quantGain);
>>>> -	gain = clampGain(exposure / exposureTime, &quantGain2);
>>>> +	exposureTime = clampExposureTime(stages_.back().exposureTime, &quantGain);
>>>> +	gain = clampGain(stages_.back().gain, &quantGain2);
> 
> Bu tn that case however can't we use lastStageGain as we looped over
> all stages ? This doesn't make much difference though, and your way is
> nicer.

Hmmm... yes, I think one could use `lastStageGain`, but you'd need to
get the quantization gain somehow as well. Possibly something like this:


```
diff --git a/src/ipa/libipa/exposure_mode_helper.cpp b/src/ipa/libipa/exposure_mode_helper.cpp
index 4123f73cc8..3d18c066af 100644
--- a/src/ipa/libipa/exposure_mode_helper.cpp
+++ b/src/ipa/libipa/exposure_mode_helper.cpp
@@ -241,11 +241,11 @@ ExposureModeHelper::splitExposure(utils::Duration exposure) const
                          exposure / (exposureTime * gain * quantGain) };
         }
  
-       double lastStageGain = clampGain(1.0);
+       utils::Duration stageExposureTime = {};
+       double lastStageGain = clampGain(1.0, &quantGain2);
  
         for (const auto &stage : stages_) {
-               utils::Duration stageExposureTime = clampExposureTime(stage.exposureTime,
-                                                                     &quantGain);
+               stageExposureTime = clampExposureTime(stage.exposureTime, &quantGain);
  
                 /*
                  * We perform the clamping on both exposure time and gain in
@@ -284,8 +284,8 @@ ExposureModeHelper::splitExposure(utils::Duration exposure) const
          * If no stages could satisfy the desired exposure, then use the last
          * stage's exposure time and gain.
          */
-       exposureTime = clampExposureTime(stages_.back().exposureTime, &quantGain);
-       gain = clampGain(stages_.back().gain, &quantGain2);
+       exposureTime = stageExposureTime;
+       gain = lastStageGain;
         quantGain *= quantGain2;
  
         return { exposureTime, gain, quantGain,
```


> 
>>>>    	quantGain *= quantGain2;
>>>>
>>>>    	return { exposureTime, gain, quantGain,
>>>> --
>>>> 2.56.0
>>>>
>>
Jacopo Mondi Oct. 27, 2026, 1:51 p.m. UTC | #5
Hi Barnabás

On Tue, Oct 27, 2026 at 01:37:48PM +0100, Barnabás Pőcze wrote:
> 2026. 10. 27. 13:16 keltezéssel, Jacopo Mondi írta:
> > Hi Barnabás
> >
> > On Tue, Oct 27, 2026 at 09:35:04AM +0100, Barnabás Pőcze wrote:
> > > 2026. 10. 27. 9:28 keltezéssel, Jacopo Mondi írta:
> > > > Hi Barnabás
> > > >
> > > > On Mon, Oct 26, 2026 at 02:20:31PM +0100, Barnabás Pőcze wrote:
> > > > > Currently `splitExposure()` will raise the exposure and analogue gain above
> > > > > what is specified in the last stage, if the desired exposure could not be
> > > > > reached. This behaviour is different from that of the raspberry pi ipa,
> > > > > and also could be surprising to the user / tuning file creator.
> > > > >
> > > > > So make sure that the exposure time and analogue gain is limited by the
> > > > > last stage, in addition to the runtime controlled upper bound.
> > > > >
> > > > > With this change, at least one stage is required, so an assertion is added
> > > > > in the constructor. Also modify the general agc algorithm to provide
> > > > > stages for the implicitly instantiated "Maximize" mode.
> > > > >
> > > > > Closes: https://gitlab.freedesktop.org/camera/libcamera/-/work_items/362
> > > > > Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
> > > >
> > > > Ack, this will make handling all modes equal now that we require
> > > > stages, and also align libipa and rpi
> > > >
> > > > > ---
> > > > >    src/ipa/libipa/agc.cpp                  | 13 +++++++++----
> > > > >    src/ipa/libipa/exposure_mode_helper.cpp | 16 +++++++---------
> > > > >    2 files changed, 16 insertions(+), 13 deletions(-)
> > > > >
> > > > > diff --git a/src/ipa/libipa/agc.cpp b/src/ipa/libipa/agc.cpp
> > > > > index b899f7c643..fb615f0af2 100644
> > > > > --- a/src/ipa/libipa/agc.cpp
> > > > > +++ b/src/ipa/libipa/agc.cpp
> > > > > @@ -442,14 +442,19 @@ void fillMissing(AgcMeanLuminance::Configuration &config)
> > > > >    {
> > > > >    	/*
> > > > >    	 * If we don't have any exposure modes in the tuning data we create an
> > > > > -	 * ExposureModeHelper using an empty vector of stages. This will result
> > > > > -	 * in the ExposureModeHelper simply driving the exposure time as high as
> > > > > -	 * possible before touching gain.
> > > > > +	 * ExposureModeHelper using a single stage of effectively unlimited exposure
> > > > > +	 * and gain. This will result in the ExposureModeHelper simply driving the
> > > > > +	 * exposure time as high as possible before touching gain.
> > > > >    	 */
> > > > >    	if (config.exposureModeHelpers.empty())
> > > > >    		config.exposureModeHelpers.try_emplace(
> > > > >    			controls::ExposureMaximize,
> > > > > -			std::vector<ExposureModeHelper::Stage>{});
> > > > > +			std::vector{
> > > > > +				ExposureModeHelper::Stage{
> > > > > +					.exposureTime = utils::Duration::max(),
> > > > > +					.gain = std::numeric_limits<double>::max(),
> > > > > +				},
> > > > > +			});
> > > > >
> > > > >    	/*
> > > > >    	 * If the tuning data file contains no constraints then we use the
> > > > > diff --git a/src/ipa/libipa/exposure_mode_helper.cpp b/src/ipa/libipa/exposure_mode_helper.cpp
> > > > > index 8a712c6da9..4123f73cc8 100644
> > > > > --- a/src/ipa/libipa/exposure_mode_helper.cpp
> > > > > +++ b/src/ipa/libipa/exposure_mode_helper.cpp
> > > > > @@ -84,6 +84,7 @@ ExposureModeHelper::ExposureModeHelper(std::vector<Stage> &&stages)
> > > > >    	: stages_(std::move(stages)), lineDuration_(1us), minExposureTime_(0us),
> > > > >    	  maxExposureTime_(0us), minGain_(0), maxGain_(0), sensorHelper_(nullptr)
> > > > >    {
> > > > > +	ASSERT(!stages_.empty());
> > > > >    }
> > > > >
> > > > >    /**
> > > > > @@ -203,8 +204,8 @@ double ExposureModeHelper::clampGain(double gain, double *quantizationGain) cons
> > > > >     * value.
> > > > >     *
> > > > >     * If no combination of exposure time and gain limits is found that meets the
> > > > > - * required exposure, the helper falls-back to simply maximising the exposure
> > > > > - * time first, followed by analogue gain, followed by digital gain.
> > > > > + * required exposure, then the exposure and gain of the last stage will be used,
> > > > > + * and the digital gain will be increased as necessary.
> > > > >     *
> > > > >     * During the calculations the gain missed due to quantization is recorded and
> > > > >     * returned as quantization gain. The quantization gain is not included in the
> > > > > @@ -280,14 +281,11 @@ ExposureModeHelper::splitExposure(utils::Duration exposure) const
> > > > >    	}
> > > > >
> > > > >    	/*
> > > > > -	 * From here on all we can do is max out the exposure time, followed by
> > > > > -	 * the analogue gain. If we still haven't achieved the target we send
> > > > > -	 * the rest of the exposure time to digital gain. If we were given no
> > > > > -	 * stages to use then the default gain of 1.0 is used so that exposure
> > > > > -	 * time is maxed before gain is touched at all.
> > > > > +	 * If no stages could satisfy the desired exposure, then use the last
> > > > > +	 * stage's exposure time and gain.
> > > > >    	 */
> > > >
> > > > How can we even get here now that the last stage uses max() as its
> > > > limit ?
> > >
> > > How do you mean? This can always be reached, even with the fallback "Maximize" mode
> >
> > I'm looking at the above for loop
> >
> > 		if (stageExposureTime * stageGain >= exposure) {
> > 			exposureTime = stageExposureTime;
> > 			gain = clampGain(exposure / exposureTime, &quantGain2);
> > 			quantGain *= quantGain2;
> >
> > 			return { exposureTime, gain, quantGain,
> > 				 exposure / (exposureTime * gain * quantGain) };
> > 		}
> >
> > > as defined above, because in the end, both parameters are limited by the sensors
> > > capabilities, so even in that case it is possible that the requested exposure cannot
> > > be satisfied by the sensor, then the execution will reach this part.
> >
> > I might have missed where the Maximize stage is limited by the
> > sensor's capabilities
> >
> > 		config.exposureModeHelpers.try_emplace(
> > 			controls::ExposureMaximize,
> > 			std::vector{
> > 				ExposureModeHelper::Stage{
> > 					.exposureTime = utils::Duration::max(),
> > 					.gain = std::numeric_limits<double>::max(),
> > 				},
> > 			});
>
> Both `stageExposureTime` and `stageGain` go through the `clamp*()` functions, which does the clamping,
> so they will be `maxExposureTime_` and `maxAnalogueGain_`, respectively, which corresponds
> to the sensor capabilities (ignoring `FrameDurationLimits` and manual exp/gain control).

Ack, if I traced the code correctly, the exposure helper receives the
limits though setLimits(), with an upper limit of

	session.maxFrameDuration = config.sensorInfo.maxFrameLength * session.lineDuration;

>
>
> >
> >
> > >
> > > And the same applies to any other exposure mode, if the smallest of the (last exposure stage)
> > > and (sensor capabilities) cannot satisfy the required exposure, then execution will
> > > reach this point.
> > >
> >
> > You're right about other exposure modes.
> >
> > >
> > > >
> > > >
> > > > > -	exposureTime = clampExposureTime(exposure / lastStageGain, &quantGain);
> > > > > -	gain = clampGain(exposure / exposureTime, &quantGain2);
> > > > > +	exposureTime = clampExposureTime(stages_.back().exposureTime, &quantGain);
> > > > > +	gain = clampGain(stages_.back().gain, &quantGain2);
> >
> > Bu tn that case however can't we use lastStageGain as we looped over
> > all stages ? This doesn't make much difference though, and your way is
> > nicer.
>
> Hmmm... yes, I think one could use `lastStageGain`, but you'd need to
> get the quantization gain somehow as well. Possibly something like this:
>
>
> ```
> diff --git a/src/ipa/libipa/exposure_mode_helper.cpp b/src/ipa/libipa/exposure_mode_helper.cpp
> index 4123f73cc8..3d18c066af 100644
> --- a/src/ipa/libipa/exposure_mode_helper.cpp
> +++ b/src/ipa/libipa/exposure_mode_helper.cpp
> @@ -241,11 +241,11 @@ ExposureModeHelper::splitExposure(utils::Duration exposure) const
>                          exposure / (exposureTime * gain * quantGain) };
>         }
> -       double lastStageGain = clampGain(1.0);
> +       utils::Duration stageExposureTime = {};
> +       double lastStageGain = clampGain(1.0, &quantGain2);
>         for (const auto &stage : stages_) {
> -               utils::Duration stageExposureTime = clampExposureTime(stage.exposureTime,
> -                                                                     &quantGain);
> +               stageExposureTime = clampExposureTime(stage.exposureTime, &quantGain);
>                 /*
>                  * We perform the clamping on both exposure time and gain in
> @@ -284,8 +284,8 @@ ExposureModeHelper::splitExposure(utils::Duration exposure) const
>          * If no stages could satisfy the desired exposure, then use the last
>          * stage's exposure time and gain.
>          */
> -       exposureTime = clampExposureTime(stages_.back().exposureTime, &quantGain);
> -       gain = clampGain(stages_.back().gain, &quantGain2);
> +       exposureTime = stageExposureTime;
> +       gain = lastStageGain;
>         quantGain *= quantGain2;
>         return { exposureTime, gain, quantGain,
> ```
>

Up to you to consider if this iw worth it or not!

>
> >
> > > > >    	quantGain *= quantGain2;
> > > > >
> > > > >    	return { exposureTime, gain, quantGain,
> > > > > --
> > > > > 2.56.0
> > > > >
> > >
>

Patch
diff mbox series

diff --git a/src/ipa/libipa/agc.cpp b/src/ipa/libipa/agc.cpp
index b899f7c643..fb615f0af2 100644
--- a/src/ipa/libipa/agc.cpp
+++ b/src/ipa/libipa/agc.cpp
@@ -442,14 +442,19 @@  void fillMissing(AgcMeanLuminance::Configuration &config)
 {
 	/*
 	 * If we don't have any exposure modes in the tuning data we create an
-	 * ExposureModeHelper using an empty vector of stages. This will result
-	 * in the ExposureModeHelper simply driving the exposure time as high as
-	 * possible before touching gain.
+	 * ExposureModeHelper using a single stage of effectively unlimited exposure
+	 * and gain. This will result in the ExposureModeHelper simply driving the
+	 * exposure time as high as possible before touching gain.
 	 */
 	if (config.exposureModeHelpers.empty())
 		config.exposureModeHelpers.try_emplace(
 			controls::ExposureMaximize,
-			std::vector<ExposureModeHelper::Stage>{});
+			std::vector{
+				ExposureModeHelper::Stage{
+					.exposureTime = utils::Duration::max(),
+					.gain = std::numeric_limits<double>::max(),
+				},
+			});
 
 	/*
 	 * If the tuning data file contains no constraints then we use the
diff --git a/src/ipa/libipa/exposure_mode_helper.cpp b/src/ipa/libipa/exposure_mode_helper.cpp
index 8a712c6da9..4123f73cc8 100644
--- a/src/ipa/libipa/exposure_mode_helper.cpp
+++ b/src/ipa/libipa/exposure_mode_helper.cpp
@@ -84,6 +84,7 @@  ExposureModeHelper::ExposureModeHelper(std::vector<Stage> &&stages)
 	: stages_(std::move(stages)), lineDuration_(1us), minExposureTime_(0us),
 	  maxExposureTime_(0us), minGain_(0), maxGain_(0), sensorHelper_(nullptr)
 {
+	ASSERT(!stages_.empty());
 }
 
 /**
@@ -203,8 +204,8 @@  double ExposureModeHelper::clampGain(double gain, double *quantizationGain) cons
  * value.
  *
  * If no combination of exposure time and gain limits is found that meets the
- * required exposure, the helper falls-back to simply maximising the exposure
- * time first, followed by analogue gain, followed by digital gain.
+ * required exposure, then the exposure and gain of the last stage will be used,
+ * and the digital gain will be increased as necessary.
  *
  * During the calculations the gain missed due to quantization is recorded and
  * returned as quantization gain. The quantization gain is not included in the
@@ -280,14 +281,11 @@  ExposureModeHelper::splitExposure(utils::Duration exposure) const
 	}
 
 	/*
-	 * From here on all we can do is max out the exposure time, followed by
-	 * the analogue gain. If we still haven't achieved the target we send
-	 * the rest of the exposure time to digital gain. If we were given no
-	 * stages to use then the default gain of 1.0 is used so that exposure
-	 * time is maxed before gain is touched at all.
+	 * If no stages could satisfy the desired exposure, then use the last
+	 * stage's exposure time and gain.
 	 */
-	exposureTime = clampExposureTime(exposure / lastStageGain, &quantGain);
-	gain = clampGain(exposure / exposureTime, &quantGain2);
+	exposureTime = clampExposureTime(stages_.back().exposureTime, &quantGain);
+	gain = clampGain(stages_.back().gain, &quantGain2);
 	quantGain *= quantGain2;
 
 	return { exposureTime, gain, quantGain,