libcamera: Use CameraConfiguration::orientation

Replace the usage of CameraConfiguration::transform with the newly
introduced CameraConfiguration::orientation.

Rework and rename the CameraSensor::validateTransform(transform) to
CameraSensor::computeTransform(orientation), that given the desired
image orientation computes the Transform that pipeline handlers should
apply to the sensor to obtain it.

Port all pipeline handlers to use the newly introduced function.

This commit breaks existing applications as it removes the public
CameraConfiguration::transform in favour of
CameraConfiguration::orientation.

Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
Reviewed-by: David Plowman <david.plowman@raspberrypi.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

1 files changed, 44 insertions, 48 deletions

diff --git a/src/libcamera/camera_sensor.cpp b/src/libcamera/camera_sensor.cpp
index 521a1997..f175f8b5 100644
--- a/src/libcamera/camera_sensor.cpp
+++ b/src/libcamera/camera_sensor.cpp
@@ -16,6 +16,7 @@
 #include <string.h>
 
 #include <libcamera/camera.h>
+#include <libcamera/orientation.h>
 #include <libcamera/property_ids.h>
 
 #include <libcamera/base/utils.h>
@@ -466,7 +467,7 @@ int CameraSensor::initProperties()
 
 		/*
 		 * Cache the Transform associated with the camera mounting
-		 * rotation for later use in validateTransform().
+		 * rotation for later use in computeTransform().
 		 */
 		bool success;
 		rotationTransform_ = transformFromRotation(propertyValue, &success);
@@ -1109,69 +1110,64 @@ void CameraSensor::updateControlInfo()
  */
 
 /**
- * \brief Validate a transform request against the sensor capabilities
- * \param[inout] transform The requested transformation, updated to match
- * the sensor capabilities
+ * \brief Compute the Transform that gives the requested \a orientation
+ * \param[inout] orientation The desired image orientation
  *
- * The input \a transform is the transform that the caller wants, and it is
- * adjusted according to the capabilities of the sensor to represent the
- * "nearest" transform that can actually be delivered.
+ * This function computes the Transform that the pipeline handler should apply
+ * to the CameraSensor to obtain the requested \a orientation.
  *
- * The returned Transform is the transform applied to the sensor in order to
- * produce the input \a transform, It is also validated against the sensor's
- * ability to perform horizontal and vertical flips.
+ * The intended caller of this function is the validate() implementation of
+ * pipeline handlers, that pass in the application requested
+ * CameraConfiguration::orientation and obtain a Transform to apply to the
+ * camera sensor, likely at configure() time.
  *
- * For example, if the requested \a transform is Transform::Identity and the
- * sensor rotation is 180 degrees, the output transform will be
- * Transform::Rot180 to correct the images so that they appear to have
- * Transform::Identity, but only if the sensor can apply horizontal and vertical
- * flips.
+ * If the requested \a orientation cannot be obtained, the \a orientation
+ * parameter is adjusted to report the current image orientation and
+ * Transform::Identity is returned.
  *
- * \return A Transform instance that represents which transformation has been
- * applied to the camera sensor
+ * If the requested \a orientation can be obtained, the function computes a
+ * Transform and does not adjust \a orientation.
+ *
+ * Pipeline handlers are expected to verify if \a orientation has been
+ * adjusted by this function and set the CameraConfiguration::status to
+ * Adjusted accordingly.
+ *
+ * \return A Transform instance that applied to the CameraSensor produces images
+ * with \a orientation
  */
-Transform CameraSensor::validateTransform(Transform *transform) const
+Transform CameraSensor::computeTransform(Orientation *orientation) const
 {
+	Orientation mountingOrientation = transformToOrientation(rotationTransform_);
+
 	/*
-	 * Combine the requested transform to compensate the sensor mounting
-	 * rotation.
+	 * If we cannot do any flips we cannot change the native camera mounting
+	 * orientation.
 	 */
-	Transform combined = rotationTransform_ * *transform;
+	if (!supportFlips_) {
+		*orientation = mountingOrientation;
+		return Transform::Identity;
+	}
 
 	/*
-	 * We combine the platform and user transform, but must "adjust away"
-	 * any combined result that includes a transposition, as we can't do
-	 * those. In this case, flipping only the transpose bit is helpful to
-	 * applications - they either get the transform they requested, or have
-	 * to do a simple transpose themselves (they don't have to worry about
-	 * the other possible cases).
+	 * Now compute the required transform to obtain 'orientation' starting
+	 * from the mounting rotation.
+	 *
+	 * As a note:
+	 * 	orientation / mountingOrientation = transform
+	 * 	mountingOrientation * transform = orientation
 	 */
-	if (!!(combined & Transform::Transpose)) {
-		/*
-		 * Flipping the transpose bit in "transform" flips it in the
-		 * combined result too (as it's the last thing that happens),
-		 * which is of course clearing it.
-		 */
-		*transform ^= Transform::Transpose;
-		combined &= ~Transform::Transpose;
-	}
+	Transform transform = *orientation / mountingOrientation;
 
 	/*
-	 * We also check if the sensor doesn't do h/vflips at all, in which
-	 * case we clear them, and the application will have to do everything.
+	 * If transform contains any Transpose we cannot do it, so adjust
+	 * 'orientation' to report the image native orientation and return Identity.
 	 */
-	if (!supportFlips_ && !!combined) {
-		/*
-		 * If the sensor can do no transforms, then combined must be
-		 * changed to the identity. The only user transform that gives
-		 * rise to this is the inverse of the rotation. (Recall that
-		 * combined = rotationTransform * transform.)
-		 */
-		*transform = -rotationTransform_;
-		combined = Transform::Identity;
+	if (!!(transform & Transform::Transpose)) {
+		*orientation = mountingOrientation;
+		return Transform::Identity;
 	}
 
-	return combined;
+	return transform;
 }
 
 std::string CameraSensor::logPrefix() const