|
libcamera
v0.4.0
Supporting cameras in Linux since 2019
|
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. More... | |
| void | setLimits (utils::Duration minExposureTime, utils::Duration maxExposureTime, double minGain, double maxGain) |
| Set the exposure time and gain limits. More... | |
| std::tuple< utils::Duration, double, double > | splitExposure (utils::Duration exposure) const |
| Split exposure into exposure time and gain. More... | |
| utils::Duration | minExposureTime () const |
| Retrieve the configured minimum exposure time limit set through setLimits() More... | |
| utils::Duration | maxExposureTime () const |
| Retrieve the configured maximum exposure time set through setLimits() More... | |
| double | minGain () const |
| Retrieve the configured minimum gain set through setLimits() More... | |
| double | maxGain () const |
| Retrieve the configured maximum gain set through setLimits() More... | |
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.
| libcamera::ipa::ExposureModeHelper::ExposureModeHelper | ( | const Span< std::pair< utils::Duration, double >> | stages | ) |
Construct an ExposureModeHelper instance.
| [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.
|
inline |
Retrieve the configured maximum exposure time set through setLimits()
|
inline |
Retrieve the configured maximum gain set through setLimits()
|
inline |
Retrieve the configured minimum exposure time limit set through setLimits()
|
inline |
Retrieve the configured minimum gain set through setLimits()
| void libcamera::ipa::ExposureModeHelper::setLimits | ( | utils::Duration | minExposureTime, |
| utils::Duration | maxExposureTime, | ||
| double | minGain, | ||
| double | maxGain | ||
| ) |
Set the exposure time and gain limits.
| [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.
| std::tuple< utils::Duration, double, double > libcamera::ipa::ExposureModeHelper::splitExposure | ( | utils::Duration | exposure | ) | const |
Split exposure into exposure time and gain.
| [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.
1.8.13