libcamera: libcamera::ipa::ExposureModeHelper Class Reference

libcamera v0.7.1 Supporting cameras in Linux since 2019

Loading...
Searching...
No Matches
libcamera::ipa::ExposureModeHelper Class Reference

Class for splitting exposure into exposure time and total gain. More...

## Public Member Functions
| ExposureModeHelper (const Span< std::pair< utils::Duration, double > > stages)
| Construct an ExposureModeHelper instance.
void | configure (utils::Duration lineLength, const CameraSensorHelper *sensorHelper)
| Configure sensor details.
void | setLimits (utils::Duration minExposureTime, utils::Duration maxExposureTime, double minGain, double maxGain)
| Set the exposure time and gain limits.
std::tuple< utils::Duration, double, double, double > | splitExposure (utils::Duration exposure) const
| Split exposure into exposure time and gain.
utils::Duration | minExposureTime () const
| Retrieve the configured minimum exposure time limit set through setLimits().
utils::Duration | maxExposureTime () const
| Retrieve the configured maximum exposure time set through setLimits().
double | minGain () const
| Retrieve the configured minimum gain set through setLimits().
double | maxGain () const
| Retrieve the configured maximum gain set through setLimits().

## Detailed Description

Class for splitting exposure into exposure time and total gain.

The ExposureModeHelper class provides a standard interface through which an AEGC algorithm can divide exposure between exposure time and gain. It is configured with a set of exposure time and gain pairs and works by initially fixing gain at 1.0 and increasing exposure time up to the exposure time value from the first pair in the set in an attempt to meet the required exposure value.

If the required exposure is not achievable by the first exposure time value alone it ramps gain up to the value from the first pair in the set. If the required exposure is still not met it then allows exposure time to ramp up to the exposure time value from the second pair in the set, and continues in this vein until either the required exposure time is met, or else the hardware's exposure time or gain limits are reached.

This method allows users to strike a balance between a well-exposed image and an acceptable frame-rate, as opposed to simply maximising exposure time followed by gain. The same helpers can be used to perform the latter operation if needed by passing an empty set of pairs to the initialisation function.

The gain values may exceed a camera sensor's analogue gain limits if either it or the IPA is also capable of digital gain. The configure() function must be called with the hardware's limits to inform the helper of those constraints. Any gain that is needed will be applied as analogue gain first until the hardware's limit is reached, following which digital gain will be used.

## Constructor & Destructor Documentation

## ◆ ExposureModeHelper()

libcamera::ipa::ExposureModeHelper::ExposureModeHelper | ( | const Span< std::pair< utils::Duration, double > > | stages | ) |

Construct an ExposureModeHelper instance.

Parameters

  [in] | stages | The vector of paired exposure time and gain limits

The input stages are exposure time and total gain pairs; the gain encompasses both analogue and digital gain.

The vector of stages may be empty. In that case, the helper will simply use the runtime limits set through setLimits() instead.

## Member Function Documentation

## ◆ configure()

void libcamera::ipa::ExposureModeHelper::configure | ( | utils::Duration | lineDuration,
|  | const CameraSensorHelper * | sensorHelper )

Configure sensor details.

Parameters

  [in] | lineDuration | The current line length of the sensor
  [in] | sensorHelper | The sensor helper

This function sets the line length and sensor helper. These are used in splitExposure() to take the quantization of the exposure and gain into account.

When this has not been called, it is assumed that exposure is in micro second granularity and gain has no quantization at all.

ExposureModeHelper keeps a pointer to the CameraSensorHelper, so the caller has to ensure that sensorHelper is valid until the next call to configure().

## ◆ maxExposureTime()

utils::Duration libcamera::ipa::ExposureModeHelper::maxExposureTime | ( |  | ) | const
| inline

Retrieve the configured maximum exposure time set through setLimits().

Returns
  The maxExposureTime_ value

## ◆ maxGain()

double libcamera::ipa::ExposureModeHelper::maxGain | ( |  | ) | const
| inline

Retrieve the configured maximum gain set through setLimits().

Returns
  The maxGain_ value

## ◆ minExposureTime()

utils::Duration libcamera::ipa::ExposureModeHelper::minExposureTime | ( |  | ) | const
| inline

Retrieve the configured minimum exposure time limit set through setLimits().

Returns
  The minExposureTime_ value

## ◆ minGain()

double libcamera::ipa::ExposureModeHelper::minGain | ( |  | ) | const
| inline

Retrieve the configured minimum gain set through setLimits().

Returns
  The minGain_ value

## ◆ setLimits()

void libcamera::ipa::ExposureModeHelper::setLimits | ( | utils::Duration | minExposureTime,
|  | utils::Duration | maxExposureTime,
|  | double | minGain,
|  | double | maxGain )

Set the exposure time and gain limits.

Parameters

  [in] | minExposureTime | The minimum exposure time supported
  [in] | maxExposureTime | The maximum exposure time supported
  [in] | minGain | The minimum analogue gain supported
  [in] | maxGain | The maximum analogue 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.

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.

## ◆ splitExposure()

std::tuple< utils::Duration, double, double, double > libcamera::ipa::ExposureModeHelper::splitExposure | ( | utils::Duration | exposure | ) | const

Split exposure into exposure time and gain.

Parameters

  [in] | exposure | Exposure value

This function divides a given exposure into exposure time, analogue and digital gain by iterating through stages of exposure time and gain limits. At each stage the current stage's exposure time limit is multiplied by the previous stage's gain limit (or 1.0 initially) to see if the combination of the two can meet the required exposure. If they cannot then the current stage's exposure time limit is multiplied by the same stage's gain limit to see if that combination can meet the required exposure time. If they cannot then the function moves to consider the next stage.

When a combination of exposure time and gain stage limits are found that are sufficient to meet the required exposure, the function attempts to reduce exposure time as much as possible whilst fixing gain and still meeting the exposure. If a runtime limit prevents exposure time from being lowered enough to meet the exposure with gain fixed at the stage limit, gain is also lowered to compensate.

Once the exposure time and gain values are ascertained, gain is assigned as analogue gain as much as possible, with digital gain only in use if the maximum analogue gain runtime limit is unable to accommodate the exposure 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.

During the calculations the gain missed due to quantization is recorded and returned as quantization gain. The quantization gain is not included in the digital gain. So to exactly apply the given exposure, both quantization gain and digital gain must be applied.

Returns
  Tuple of exposure time, analogue gain, quantization gain and digital gain

The documentation for this class was generated from the following files:

- src/ipa/libipa/exposure_mode_helper.h
- src/ipa/libipa/exposure_mode_helper.cpp