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>

1 files changed, 92 insertions, 0 deletions

diff --git a/src/libcamera/stream.cpp b/src/libcamera/stream.cpp
index c4943c91..85cd5256 100644
--- a/src/libcamera/stream.cpp
+++ b/src/libcamera/stream.cpp
@@ -61,6 +61,65 @@ namespace libcamera {
  */
 
 /**
+ * \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
  *
@@ -79,6 +138,39 @@ namespace libcamera {
  */
 
 /**
+ * \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
  */
 Stream::Stream()