libcamera: stream: Add basic stream usages

In preparation of reworking how a default configuration is retrieved
from a camera add stream usages. The usages will be used by applications
to describe how they intend to use a camera and replace the Stream IDs
when retrieving default configuration from the camera using
streamConfiguration().

Signed-off-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

include/libcamera/stream.h

@@ -8,6 +8,7 @@
 #define __LIBCAMERA_STREAM_H__
 
 #include <libcamera/buffer.h>
+#include <libcamera/geometry.h>
 
 namespace libcamera {
 
@@ -21,9 +22,48 @@ struct StreamConfiguration {
 	unsigned int bufferCount;
 };
 
+class StreamUsage
+{
+public:
+	enum Role {
+		StillCapture,
+		VideoRecording,
+		Viewfinder,
+	};
+
+	Role role() const { return role_; }
+	const Size &size() const { return size_; }
+
+protected:
+	explicit StreamUsage(Role role);
+	StreamUsage(Role role, int width, int height);
+
+private:
+	Role role_;
+	Size size_;
+};
+
 class Stream final
 {
 public:
+	class StillCapture : public StreamUsage
+	{
+	public:
+		StillCapture();
+	};
+
+	class VideoRecording : public StreamUsage
+	{
+	public:
+		VideoRecording();
+	};
+
+	class Viewfinder : public StreamUsage
+	{
+	public:
+		Viewfinder(int width, int height);
+	};
+
 	Stream();
 	BufferPool &bufferPool() { return bufferPool_; }
 	const StreamConfiguration &configuration() const { return configuration_; }

src/libcamera/stream.cpp

@@ -60,6 +60,65 @@ namespace libcamera {
  * \brief Requested number of buffers to allocate for the stream
  */
 
+/**
+ * \class StreamUsage
+ * \brief Stream usage information
+ *
+ * The StreamUsage class describes how an application intends to use a stream.
+ * Usages are specified by applications and passed to cameras, that then select
+ * the most appropriate streams and their default configurations.
+ */
+
+/**
+ * \enum StreamUsage::Role
+ * \brief Identify the role a stream is intended to play
+ * \var StreamUsage::StillCapture
+ * The stream is intended to capture high-resolution, high-quality still images
+ * with low frame rate. The captured frames may be exposed with flash.
+ * \var StreamUsage::VideoRecording
+ * The stream is intended to capture video for the purpose of recording or
+ * streaming. The video stream may produce a high frame rate and may be
+ * enhanced with video stabilization.
+ * \var StreamUsage::Viewfinder
+ * The stream is intended to capture video for the purpose of display on the
+ * local screen. The StreamUsage includes the desired resolution. Trade-offs
+ * between quality and usage of system resources are acceptable.
+ */
+
+/**
+ * \fn StreamUsage::role()
+ * \brief Retrieve the stream role
+ *
+ * \return The stream role
+ */
+
+/**
+ * \fn StreamUsage::size()
+ * \brief Retrieve desired size
+ *
+ * \return The desired size
+ */
+
+/**
+ * \brief Create a stream usage
+ * \param[in] role Stream role
+ */
+StreamUsage::StreamUsage(Role role)
+	: role_(role)
+{
+}
+
+/**
+ * \brief Create a stream usage with a desired size
+ * \param[in] role Stream role
+ * \param[in] width The desired width
+ * \param[in] height The desired height
+ */
+StreamUsage::StreamUsage(Role role, int width, int height)
+	: role_(role), size_(Size(width, height))
+{
+}
+
 /**
  * \class Stream
  * \brief Video stream for a camera
@@ -78,6 +137,39 @@ namespace libcamera {
  * optimal stream for the task.
  */
 
+/**
+ * \class Stream::StillCapture
+ * \brief Describe a still capture usage
+ */
+Stream::StillCapture::StillCapture()
+	: StreamUsage(Role::StillCapture)
+{
+}
+
+/**
+ * \class Stream::VideoRecording
+ * \brief Describe a video recording usage
+ */
+Stream::VideoRecording::VideoRecording()
+	: StreamUsage(Role::VideoRecording)
+{
+}
+
+/**
+ * \class Stream::Viewfinder
+ * \brief Describe a viewfinder usage
+ */
+
+/**
+ * \brief Create a viewfinder usage with a desired dimension
+ * \param[in] width The desired viewfinder width
+ * \param[in] height The desired viewfinder height
+ */
+Stream::Viewfinder::Viewfinder(int width, int height)
+	: StreamUsage(Role::Viewfinder, width, height)
+{
+}
+
 /**
  * \brief Construct a stream with default parameters
  */