libcamera: camera: Introduce Orientation

Introduce the Orientation enumeration which describes the possible 2D
transformations that can be applied to an image using two basic plane
transformations.

Add to the CameraConfiguration class a new member 'orientation' which is
used to specify the image orientation in the memory buffers delivered to
applications.

The enumeration values follow the ones defined by the EXIF specification at
revision 2.32, Tag 274 'orientation'.

The newly introduced field is meant to replace
CameraConfiguration::transform which is not removed yet not to break
compilation.

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>

6 files changed, 149 insertions, 1 deletions

diff --git a/include/libcamera/camera.h b/include/libcamera/camera.h
index decf4ec0..a4536c72 100644
--- a/include/libcamera/camera.h
+++ b/include/libcamera/camera.h
@@ -21,6 +21,7 @@
 
 #include <libcamera/controls.h>
 #include <libcamera/geometry.h>
+#include <libcamera/orientation.h>
 #include <libcamera/request.h>
 #include <libcamera/stream.h>
 #include <libcamera/transform.h>
@@ -94,6 +95,7 @@ public:
 
 	std::optional<SensorConfiguration> sensorConfig;
 	Transform transform;
+	Orientation orientation;
 
 protected:
 	CameraConfiguration();
diff --git a/include/libcamera/meson.build b/include/libcamera/meson.build
index 408b7acf..a24c50d6 100644
--- a/include/libcamera/meson.build
+++ b/include/libcamera/meson.build
@@ -12,6 +12,7 @@ libcamera_public_headers = files([
     'framebuffer_allocator.h',
     'geometry.h',
     'logging.h',
+    'orientation.h',
     'pixel_format.h',
     'request.h',
     'stream.h',
diff --git a/include/libcamera/orientation.h b/include/libcamera/orientation.h
new file mode 100644
index 00000000..9a2c2fb2
--- /dev/null
+++ b/include/libcamera/orientation.h
@@ -0,0 +1,30 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+/*
+ * Copyright (C) 2023, Ideas On Board Oy
+ *
+ * orientation.h - Image orientation
+ */
+
+#pragma once
+
+#include <iostream>
+
+namespace libcamera {
+
+enum class Orientation {
+	/* EXIF tag 274 starts from '1' */
+	Rotate0 = 1,
+	Rotate0Mirror,
+	Rotate180,
+	Rotate180Mirror,
+	Rotate90Mirror,
+	Rotate270,
+	Rotate270Mirror,
+	Rotate90,
+};
+
+Orientation orientationFromRotation(int angle, bool *success = nullptr);
+
+std::ostream &operator<<(std::ostream &out, const Orientation &orientation);
+
+} /* namespace libcamera */
diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp
index b940647d..59ee3c40 100644
--- a/src/libcamera/camera.cpp
+++ b/src/libcamera/camera.cpp
@@ -291,7 +291,8 @@ bool SensorConfiguration::isValid() const
  * \brief Create an empty camera configuration
  */
 CameraConfiguration::CameraConfiguration()
-	: transform(Transform::Identity), config_({})
+	: transform(Transform::Identity), orientation(Orientation::Rotate0),
+	  config_({})
 {
 }
 
@@ -553,6 +554,21 @@ CameraConfiguration::Status CameraConfiguration::validateColorSpaces(ColorSpaceF
  */
 
 /**
+ * \var CameraConfiguration::orientation
+ * \brief The desired orientation of the images produced by the camera
+ *
+ * The orientation field is a user-specified 2D plane transformation that
+ * specifies how the application wants the camera images to be rotated in
+ * the memory buffers.
+ *
+ * If the orientation requested by the application cannot be obtained, the
+ * camera will not rotate or flip the images, and the validate() function will
+ * Adjust this value to the native image orientation produced by the camera.
+ *
+ * By default the orientation field is set to Orientation::Rotate0.
+ */
+
+/**
  * \var CameraConfiguration::config_
  * \brief The vector of stream configurations
  */
diff --git a/src/libcamera/meson.build b/src/libcamera/meson.build
index b24f8296..d0e26f6b 100644
--- a/src/libcamera/meson.build
+++ b/src/libcamera/meson.build
@@ -34,6 +34,7 @@ libcamera_sources = files([
     'mapped_framebuffer.cpp',
     'media_device.cpp',
     'media_object.cpp',
+    'orientation.cpp',
     'pipeline_handler.cpp',
     'pixel_format.cpp',
     'process.cpp',
diff --git a/src/libcamera/orientation.cpp b/src/libcamera/orientation.cpp
new file mode 100644
index 00000000..a3465383
--- /dev/null
+++ b/src/libcamera/orientation.cpp
@@ -0,0 +1,98 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+/*
+ * Copyright (C) 2023, Ideas On Board Oy
+ *
+ * orientation.cpp - Image orientation
+ */
+
+#include <libcamera/orientation.h>
+
+#include <array>
+#include <string>
+
+/**
+ * \file libcamera/orientation.h
+ * \brief Image orientation definition
+ */
+
+namespace libcamera {
+
+/**
+ * \enum Orientation
+ * \brief The image orientation in a memory buffer
+ *
+ * The Orientation enumeration describes the orientation of the images
+ * produced by the camera pipeline as they get received by the application
+ * inside memory buffers.
+ *
+ * The image orientation expressed using the Orientation enumeration can be then
+ * inferred by applying to a naturally oriented image a multiple of a 90 degrees
+ * rotation in the clockwise direction from the origin and then by applying an
+ * optional horizontal mirroring.
+ *
+ * The enumeration numerical values follow the ones defined by the EXIF
+ * Specification version 2.32, Tag 274 "Orientation", while the names of the
+ * enumerated values report the rotation and mirroring operations performed.
+ *
+ * For example, Orientation::Rotate90Mirror describes the orientation obtained
+ * by rotating the image 90 degrees clockwise first and then applying a
+ * horizontal mirroring.
+ */
+
+/**
+ * \brief Return the orientation representing a rotation of the given angle
+ * clockwise
+ * \param[in] angle The angle of rotation in a clockwise sense. Negative values
+ * can be used to represent anticlockwise rotations
+ * \param[out] success Set to `true` if the angle is a multiple of 90 degrees,
+ * otherwise `false`
+ * \return The orientation corresponding to the rotation if \a success was set
+ * to `true`, otherwise the `Rotate0` orientation
+ */
+Orientation orientationFromRotation(int angle, bool *success)
+{
+	angle = angle % 360;
+	if (angle < 0)
+		angle += 360;
+
+	if (success != nullptr)
+		*success = true;
+
+	switch (angle) {
+	case 0:
+		return Orientation::Rotate0;
+	case 90:
+		return Orientation::Rotate90;
+	case 180:
+		return Orientation::Rotate180;
+	case 270:
+		return Orientation::Rotate270;
+	}
+
+	if (success != nullptr)
+		*success = false;
+
+	return Orientation::Rotate0;
+}
+
+/**
+ * \brief Prints human-friendly names for Orientation items
+ * \param[in] out The output stream
+ * \param[in] orientation The Orientation item
+ * \return The output stream \a out
+ */
+std::ostream &operator<<(std::ostream &out, const Orientation &orientation)
+{
+	constexpr std::array<const char *, 9> orientationNames = {
+		"", /* Orientation starts counting from 1. */
+		"Rotate0", "Rotate0Mirror",
+		"Rotate180", "Rotate180Mirror",
+		"Rotate90Mirror", "Rotate270",
+		"Rotate270Mirror", "Rotate90",
+	};
+
+	out << orientationNames[static_cast<unsigned int>(orientation)];
+	return out;
+}
+
+} /* namespace libcamera */