libcamera: Rename "shutter speed" to "exposure time"

The terms "shutter" and "shutter speed" are used through libcamera to
mean "exposure time". This is confusing, both due to "speed" being used
as "time" while it should be the inverse (i.e. a maximum speed should
correspond to the minimum time), and due to "shutter speed" and
"exposure time" being used in different places with the same meaning.

To improve clarity of the code base and the documentation, use "exposure
time" consistently to replace "shutter speed".

This rename highlighted another vocabulary issue in libcamera. The
ExposureModeHelper::splitExposure() function used to document that it
splits "exposure time into shutter time and gain". It has been reworded
to "split exposure into exposure time and gain". That is not entirely
satisfactory, as "exposure" has a defined meaning in photography (see
https://en.wikipedia.org/wiki/Exposure_(photography)) that is not
expressed as a duration. This issue if left to be addressed separately.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Naushir Patuck <naush@raspberrypi.com>
Acked-by: Kieran Bingham <kieran.bingham@ideasonboard.com>

5 files changed, 26 insertions, 26 deletions

diff --git a/src/ipa/ipu3/algorithms/agc.cpp b/src/ipa/ipu3/algorithms/agc.cpp
index 466b3fb3..46669203 100644
--- a/src/ipa/ipu3/algorithms/agc.cpp
+++ b/src/ipa/ipu3/algorithms/agc.cpp
@@ -34,7 +34,7 @@ namespace ipa::ipu3::algorithms {
  * \class Agc
  * \brief A mean-based auto-exposure algorithm
  *
- * This algorithm calculates a shutter time and an analogue gain so that the
+ * This algorithm calculates an exposure time and an analogue gain so that the
  * average value of the green channel of the brightest 2% of pixels approaches
  * 0.5. The AWB gains are not used here, and all cells in the grid have the same
  * weight, like an average-metering case. In this metering mode, the camera uses
@@ -52,13 +52,13 @@ LOG_DEFINE_CATEGORY(IPU3Agc)
 static constexpr double kMinAnalogueGain = 1.0;
 
 /* \todo Honour the FrameDurationLimits control instead of hardcoding a limit */
-static constexpr utils::Duration kMaxShutterSpeed = 60ms;
+static constexpr utils::Duration kMaxExposureTime = 60ms;
 
 /* Histogram constants */
 static constexpr uint32_t knumHistogramBins = 256;
 
 Agc::Agc()
-	: minShutterSpeed_(0s), maxShutterSpeed_(0s)
+	: minExposureTime_(0s), maxExposureTime_(0s)
 {
 }
 
@@ -101,9 +101,9 @@ int Agc::configure(IPAContext &context,
 	stride_ = configuration.grid.stride;
 	bdsGrid_ = configuration.grid.bdsGrid;
 
-	minShutterSpeed_ = configuration.agc.minShutterSpeed;
-	maxShutterSpeed_ = std::min(configuration.agc.maxShutterSpeed,
-				    kMaxShutterSpeed);
+	minExposureTime_ = configuration.agc.minExposureTime;
+	maxExposureTime_ = std::min(configuration.agc.maxExposureTime,
+				    kMaxExposureTime);
 
 	minAnalogueGain_ = std::max(configuration.agc.minAnalogueGain, kMinAnalogueGain);
 	maxAnalogueGain_ = configuration.agc.maxAnalogueGain;
@@ -116,7 +116,7 @@ int Agc::configure(IPAContext &context,
 	context.activeState.agc.exposureMode = exposureModeHelpers().begin()->first;
 
 	/* \todo Run this again when FrameDurationLimits is passed in */
-	setLimits(minShutterSpeed_, maxShutterSpeed_, minAnalogueGain_,
+	setLimits(minExposureTime_, maxExposureTime_, minAnalogueGain_,
 		  maxAnalogueGain_);
 	resetFrameCount();
 
@@ -223,20 +223,20 @@ void Agc::process(IPAContext &context, [[maybe_unused]] const uint32_t frame,
 	double analogueGain = frameContext.sensor.gain;
 	utils::Duration effectiveExposureValue = exposureTime * analogueGain;
 
-	utils::Duration shutterTime;
+	utils::Duration newExposureTime;
 	double aGain, dGain;
-	std::tie(shutterTime, aGain, dGain) =
+	std::tie(newExposureTime, aGain, dGain) =
 		calculateNewEv(context.activeState.agc.constraintMode,
 			       context.activeState.agc.exposureMode, hist,
 			       effectiveExposureValue);
 
 	LOG(IPU3Agc, Debug)
-		<< "Divided up shutter, analogue gain and digital gain are "
-		<< shutterTime << ", " << aGain << " and " << dGain;
+		<< "Divided up exposure time, analogue gain and digital gain are "
+		<< newExposureTime << ", " << aGain << " and " << dGain;
 
 	IPAActiveState &activeState = context.activeState;
-	/* Update the estimated exposure and gain. */
-	activeState.agc.exposure = shutterTime / context.configuration.sensor.lineDuration;
+	/* Update the estimated exposure time and gain. */
+	activeState.agc.exposure = newExposureTime / context.configuration.sensor.lineDuration;
 	activeState.agc.gain = aGain;
 
 	metadata.set(controls::AnalogueGain, frameContext.sensor.gain);
diff --git a/src/ipa/ipu3/algorithms/agc.h b/src/ipa/ipu3/algorithms/agc.h
index 411f4da0..890c271b 100644
--- a/src/ipa/ipu3/algorithms/agc.h
+++ b/src/ipa/ipu3/algorithms/agc.h
@@ -42,8 +42,8 @@ private:
 	Histogram parseStatistics(const ipu3_uapi_stats_3a *stats,
 				  const ipu3_uapi_grid_config &grid);
 
-	utils::Duration minShutterSpeed_;
-	utils::Duration maxShutterSpeed_;
+	utils::Duration minExposureTime_;
+	utils::Duration maxExposureTime_;
 
 	double minAnalogueGain_;
 	double maxAnalogueGain_;
diff --git a/src/ipa/ipu3/ipa_context.cpp b/src/ipa/ipu3/ipa_context.cpp
index 917d0654..fe455e07 100644
--- a/src/ipa/ipu3/ipa_context.cpp
+++ b/src/ipa/ipu3/ipa_context.cpp
@@ -92,11 +92,11 @@ namespace libcamera::ipa::ipu3 {
  * \var IPASessionConfiguration::agc
  * \brief AGC parameters configuration of the IPA
  *
- * \var IPASessionConfiguration::agc.minShutterSpeed
- * \brief Minimum shutter speed supported with the configured sensor
+ * \var IPASessionConfiguration::agc.minExposureTime
+ * \brief Minimum exposure time supported with the configured sensor
  *
- * \var IPASessionConfiguration::agc.maxShutterSpeed
- * \brief Maximum shutter speed supported with the configured sensor
+ * \var IPASessionConfiguration::agc.maxExposureTime
+ * \brief Maximum exposure time supported with the configured sensor
  *
  * \var IPASessionConfiguration::agc.minAnalogueGain
  * \brief Minimum analogue gain supported with the configured sensor
diff --git a/src/ipa/ipu3/ipa_context.h b/src/ipa/ipu3/ipa_context.h
index c85d1e34..29f38b36 100644
--- a/src/ipa/ipu3/ipa_context.h
+++ b/src/ipa/ipu3/ipa_context.h
@@ -33,8 +33,8 @@ struct IPASessionConfiguration {
 	} af;
 
 	struct {
-		utils::Duration minShutterSpeed;
-		utils::Duration maxShutterSpeed;
+		utils::Duration minExposureTime;
+		utils::Duration maxExposureTime;
 		double minAnalogueGain;
 		double maxAnalogueGain;
 	} agc;
diff --git a/src/ipa/ipu3/ipu3.cpp b/src/ipa/ipu3/ipu3.cpp
index 89c3192c..44c98cbf 100644
--- a/src/ipa/ipu3/ipu3.cpp
+++ b/src/ipa/ipu3/ipu3.cpp
@@ -112,7 +112,7 @@ namespace ipa::ipu3 {
  * blue gains to apply to generate a neutral grey frame overall.
  *
  * AGC is handled by calculating a histogram of the green channel to estimate an
- * analogue gain and shutter time which will provide a well exposed frame. A
+ * analogue gain and exposure time which will provide a well exposed frame. A
  * low-pass IIR filter is used to smooth the changes to the sensor to reduce
  * perceivable steps.
  *
@@ -215,13 +215,13 @@ void IPAIPU3::updateSessionConfiguration(const ControlInfoMap &sensorControls)
 
 	/*
 	 * When the AGC computes the new exposure values for a frame, it needs
-	 * to know the limits for shutter speed and analogue gain.
+	 * to know the limits for exposure time and analogue gain.
 	 * As it depends on the sensor, update it with the controls.
 	 *
-	 * \todo take VBLANK into account for maximum shutter speed
+	 * \todo take VBLANK into account for maximum exposure time
 	 */
-	context_.configuration.agc.minShutterSpeed = minExposure * context_.configuration.sensor.lineDuration;
-	context_.configuration.agc.maxShutterSpeed = maxExposure * context_.configuration.sensor.lineDuration;
+	context_.configuration.agc.minExposureTime = minExposure * context_.configuration.sensor.lineDuration;
+	context_.configuration.agc.maxExposureTime = maxExposure * context_.configuration.sensor.lineDuration;
 	context_.configuration.agc.minAnalogueGain = camHelper_->gain(minGain);
 	context_.configuration.agc.maxAnalogueGain = camHelper_->gain(maxGain);
 }