|
libcamera
v0.3.1+12-19bbca3c
Supporting cameras in Linux since 2019
|
Class for splitting exposure into shutter time and total gain. More...
Public Member Functions | |
| ExposureModeHelper (const Span< std::pair< utils::Duration, double >> stages) | |
| Construct an ExposureModeHelper instance. More... | |
| void | setLimits (utils::Duration minShutter, utils::Duration maxShutter, double minGain, double maxGain) |
| Set the shutter time and gain limits. More... | |
| std::tuple< utils::Duration, double, double > | splitExposure (utils::Duration exposure) const |
| Split exposure time into shutter time and gain. More... | |
| utils::Duration | minShutter () const |
| Retrieve the configured minimum shutter time limit set through setShutterGainLimits() More... | |
| utils::Duration | maxShutter () const |
| Retrieve the configured maximum shutter time set through setShutterGainLimits() More... | |
| double | minGain () const |
| Retrieve the configured minimum gain set through setShutterGainLimits() More... | |
| double | maxGain () const |
| Retrieve the configured maximum gain set through setShutterGainLimits() More... | |
Class for splitting exposure into shutter time and total gain.
The ExposureModeHelper class provides a standard interface through which an AEGC algorithm can divide exposure between shutter time and gain. It is configured with a set of shutter time and gain pairs and works by initially fixing gain at 1.0 and increasing shutter time up to the shutter 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 shutter 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 shutter time to ramp up to the shutter 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 shutter 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 shutter 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.
| libcamera::ipa::ExposureModeHelper::ExposureModeHelper | ( | const Span< std::pair< utils::Duration, double >> | stages | ) |
Construct an ExposureModeHelper instance.
| [in] | stages | The vector of paired shutter time and gain limits |
The input stages are shutter 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 setShutterGainLimits() instead.
|
inline |
Retrieve the configured maximum gain set through setShutterGainLimits()
|
inline |
Retrieve the configured maximum shutter time set through setShutterGainLimits()
|
inline |
Retrieve the configured minimum gain set through setShutterGainLimits()
|
inline |
Retrieve the configured minimum shutter time limit set through setShutterGainLimits()
| void libcamera::ipa::ExposureModeHelper::setLimits | ( | utils::Duration | minShutter, |
| utils::Duration | maxShutter, | ||
| double | minGain, | ||
| double | maxGain | ||
| ) |
Set the shutter time and gain limits.
| [in] | minShutter | The minimum shutter time supported |
| [in] | maxShutter | The maximum shutter time supported |
| [in] | minGain | The minimum analogue gain supported |
| [in] | maxGain | The maximum analogue gain supported |
This function configures the shutter 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 shutter time or analogue gain or both should be fixed it can do so by setting both the minima and maxima to the same value.
| std::tuple< utils::Duration, double, double > libcamera::ipa::ExposureModeHelper::splitExposure | ( | utils::Duration | exposure | ) | const |
Split exposure time into shutter time and gain.
| [in] | exposure | Exposure time |
This function divides a given exposure time into shutter time, analogue and digital gain by iterating through stages of shutter time and gain limits. At each stage the current stage's shutter 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 time. If they cannot then the current stage's shutter 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 shutter time and gain stage limits are found that are sufficient to meet the required exposure time, the function attempts to reduce shutter time as much as possible whilst fixing gain and still meeting the exposure time. If a runtime limit prevents shutter time from being lowered enough to meet the exposure time with gain fixed at the stage limit, gain is also lowered to compensate.
Once the shutter 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 shutter time and gain limits is found that meets the required exposure time, the helper falls-back to simply maximising the shutter time first, followed by analogue gain, followed by digital gain.
1.8.13