libcamera: Use stream roles directly instead of StreamUsage

In order to prepare for an API overhall of the camera configuration
generation, remove the StreamUsage class and replace its uses by stream
roles. The size hints can't be specified anymore, and will be replaced
with an API on the StreamConfiguration to negotiate configuration
parameters with cameras.

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

include/libcamera/camera.h

@@ -14,16 +14,13 @@
 
 #include <libcamera/request.h>
 #include <libcamera/signal.h>
+#include <libcamera/stream.h>
 
 namespace libcamera {
 
 class Buffer;
 class PipelineHandler;
 class Request;
-class Stream;
-class StreamUsage;
-
-struct StreamConfiguration;
 
 class CameraConfiguration
 {
@@ -74,8 +71,7 @@ public:
 	int release();
 
 	const std::set<Stream *> &streams() const;
-	CameraConfiguration
+	CameraConfiguration generateConfiguration(const StreamRoles &roles);
-	generateConfiguration(const std::vector<StreamUsage> &usage);
 	int configure(const CameraConfiguration &config);
 
 	int allocateBuffers();

include/libcamera/stream.h

@@ -8,6 +8,7 @@
 #define __LIBCAMERA_STREAM_H__
 
 #include <string>
+#include <vector>
 
 #include <libcamera/buffer.h>
 #include <libcamera/geometry.h>
@@ -25,48 +26,17 @@ struct StreamConfiguration {
 	std::string toString() const;
 };
 
-class StreamUsage
+enum StreamRole {
-{
+	StillCapture,
-public:
+	VideoRecording,
-	enum Role {
+	Viewfinder,
-		StillCapture,
-		VideoRecording,
-		Viewfinder,
-	};
-
-	Role role() const { return role_; }
-	const Size &size() const { return size_; }
-
-protected:
-	explicit StreamUsage(Role role);
-	StreamUsage(Role role, const Size &size);
-
-private:
-	Role role_;
-	Size size_;
 };
 
+using StreamRoles = std::vector<StreamRole>;
+
 class Stream
 {
 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/cam/main.cpp

@@ -87,13 +87,13 @@ static int parseOptions(int argc, char *argv[])
 
 static int prepareCameraConfig(CameraConfiguration *config)
 {
-	std::vector<StreamUsage> roles;
+	StreamRoles roles;
 
 	streamInfo.clear();
 
 	/* If no configuration is provided assume a single video stream. */
 	if (!options.isSet(OptStream)) {
-		*config = camera->generateConfiguration({ Stream::VideoRecording() });
+		*config = camera->generateConfiguration({ StreamRole::VideoRecording });
 		streamInfo[config->front()] = "stream0";
 		return 0;
 	}
@@ -106,14 +106,13 @@ static int prepareCameraConfig(CameraConfiguration *config)
 		KeyValueParser::Options conf = value.toKeyValues();
 
 		if (!conf.isSet("role")) {
-			roles.push_back(Stream::VideoRecording());
+			roles.push_back(StreamRole::VideoRecording);
 		} else if (conf["role"].toString() == "viewfinder") {
-			roles.push_back(Stream::Viewfinder(conf["width"],
+			roles.push_back(StreamRole::Viewfinder);
-							   conf["height"]));
 		} else if (conf["role"].toString() == "video") {
-			roles.push_back(Stream::VideoRecording());
+			roles.push_back(StreamRole::VideoRecording);
 		} else if (conf["role"].toString() == "still") {
-			roles.push_back(Stream::StillCapture());
+			roles.push_back(StreamRole::StillCapture);
 		} else {
 			std::cerr << "Unknown stream role "
 				  << conf["role"].toString() << std::endl;

src/libcamera/camera.cpp

@@ -542,23 +542,23 @@ const std::set<Stream *> &Camera::streams() const
 }
 
 /**
- * \brief Generate a default camera configuration according to stream usages
+ * \brief Generate a default camera configuration according to stream roles
- * \param[in] usages A list of stream usages
+ * \param[in] roles A list of stream roles
  *
- * Generate a camera configuration for a set of desired usages. The caller
+ * Generate a camera configuration for a set of desired stream roles. The caller
- * specifies a list of stream usages and the camera returns a configuration
+ * specifies a list of stream roles and the camera returns a configuration
  * containing suitable streams and their suggested default configurations.
  *
- * \return A valid CameraConfiguration if the requested usages can be satisfied,
+ * \return A valid CameraConfiguration if the requested roles can be satisfied,
  * or a invalid one otherwise
  */
 CameraConfiguration
-Camera::generateConfiguration(const std::vector<StreamUsage> &usages)
+Camera::generateConfiguration(const StreamRoles &roles)
 {
-	if (disconnected_ || !usages.size() || usages.size() > streams_.size())
+	if (disconnected_ || !roles.size() || roles.size() > streams_.size())
 		return CameraConfiguration();
 
-	CameraConfiguration config = pipe_->generateConfiguration(this, usages);
+	CameraConfiguration config = pipe_->generateConfiguration(this, roles);
 
 	std::ostringstream msg("streams configuration:", std::ios_base::ate);
 	unsigned int index = 0;

src/libcamera/include/pipeline_handler.h

@@ -14,6 +14,8 @@
 #include <string>
 #include <vector>
 
+#include <libcamera/stream.h>
+
 namespace libcamera {
 
 class Buffer;
@@ -26,8 +28,6 @@ class DeviceMatch;
 class MediaDevice;
 class PipelineHandler;
 class Request;
-class Stream;
-class StreamUsage;
 
 class CameraData
 {
@@ -61,7 +61,7 @@ public:
 	void unlock();
 
 	virtual CameraConfiguration
-	generateConfiguration(Camera *camera, const std::vector<StreamUsage> &usages) = 0;
+	generateConfiguration(Camera *camera, const StreamRoles &roles) = 0;
 	virtual int configure(Camera *camera, const CameraConfiguration &config) = 0;
 
 	virtual int allocateBuffers(Camera *camera,

src/libcamera/pipeline/ipu3/ipu3.cpp

@@ -151,8 +151,7 @@ public:
 	PipelineHandlerIPU3(CameraManager *manager);
 
 	CameraConfiguration
-	generateConfiguration(Camera *camera,
+	generateConfiguration(Camera *camera, const StreamRoles &roles) override;
-			      const std::vector<StreamUsage> &usages) override;
 	int configure(Camera *camera,
 		      const CameraConfiguration &config) override;
 
@@ -211,7 +210,7 @@ PipelineHandlerIPU3::PipelineHandlerIPU3(CameraManager *manager)
 
 CameraConfiguration
 PipelineHandlerIPU3::generateConfiguration(Camera *camera,
-					   const std::vector<StreamUsage> &usages)
+					   const StreamRoles &roles)
 {
 	IPU3CameraData *data = cameraData(camera);
 	CameraConfiguration config = {};
@@ -220,13 +219,12 @@ PipelineHandlerIPU3::generateConfiguration(Camera *camera,
 		&data->vfStream_,
 	};
 
-	for (const StreamUsage &usage : usages) {
+	for (const StreamRole role : roles) {
 		StreamConfiguration cfg = {};
-		StreamUsage::Role role = usage.role();
 		IPU3Stream *stream = nullptr;
 
 		switch (role) {
-		case StreamUsage::Role::StillCapture:
+		case StreamRole::StillCapture:
 			/*
 			 * Pick the output stream by default as the Viewfinder
 			 * and VideoRecording roles are not allowed on
@@ -256,11 +254,11 @@ PipelineHandlerIPU3::generateConfiguration(Camera *camera,
 
 			break;
 
-		case StreamUsage::Role::Viewfinder:
+		case StreamRole::Viewfinder:
-		case StreamUsage::Role::VideoRecording: {
+		case StreamRole::VideoRecording: {
 			/*
 			 * We can't use the 'output' stream for viewfinder or
-			 * video capture usages.
+			 * video capture roles.
 			 *
 			 * \todo This is an artificial limitation until we
 			 * figure out the exact capabilities of the hardware.
@@ -275,15 +273,13 @@ PipelineHandlerIPU3::generateConfiguration(Camera *camera,
 			stream = &data->vfStream_;
 
 			/*
-			 * Align the requested viewfinder size to the
+			 * Align the default viewfinder size to the maximum
-			 * maximum available sensor resolution and to the
+			 * available sensor resolution and to the IPU3
-			 * IPU3 alignment constraints.
+			 * alignment constraints.
 			 */
 			const Size &res = data->cio2_.sensor_->resolution();
-			unsigned int width = std::min(usage.size().width,
+			unsigned int width = std::min(1280U, res.width);
-						      res.width);
+			unsigned int height = std::min(720U, res.height);
-			unsigned int height = std::min(usage.size().height,
-						       res.height);
 			cfg.size = { width & ~7, height & ~3 };
 
 			break;

src/libcamera/pipeline/rkisp1/rkisp1.cpp

@@ -35,7 +35,7 @@ public:
 	~PipelineHandlerRkISP1();
 
 	CameraConfiguration generateConfiguration(Camera *camera,
-		const std::vector<StreamUsage> &usages) override;
+		const StreamRoles &roles) override;
 	int configure(Camera *camera,
 		const CameraConfiguration &config) override;
 
@@ -107,7 +107,7 @@ PipelineHandlerRkISP1::~PipelineHandlerRkISP1()
  */
 
 CameraConfiguration PipelineHandlerRkISP1::generateConfiguration(Camera *camera,
-	const std::vector<StreamUsage> &usages)
+	const StreamRoles &roles)
 {
 	RkISP1CameraData *data = cameraData(camera);
 	CameraConfiguration config;

src/libcamera/pipeline/uvcvideo.cpp

@@ -26,8 +26,7 @@ public:
 	PipelineHandlerUVC(CameraManager *manager);
 
 	CameraConfiguration
-	generateConfiguration(Camera *camera,
+	generateConfiguration(Camera *camera, const StreamRoles &roles) override;
-			      const std::vector<StreamUsage> &usages) override;
 	int configure(Camera *camera,
 		      const CameraConfiguration &config) override;
 
@@ -77,7 +76,7 @@ PipelineHandlerUVC::PipelineHandlerUVC(CameraManager *manager)
 
 CameraConfiguration
 PipelineHandlerUVC::generateConfiguration(Camera *camera,
-					  const std::vector<StreamUsage> &usages)
+					  const StreamRoles &roles)
 {
 	UVCCameraData *data = cameraData(camera);
 	CameraConfiguration config;

src/libcamera/pipeline/vimc.cpp

@@ -26,8 +26,7 @@ public:
 	PipelineHandlerVimc(CameraManager *manager);
 
 	CameraConfiguration
-	generateConfiguration(Camera *camera,
+	generateConfiguration(Camera *camera, const StreamRoles &roles) override;
-			      const std::vector<StreamUsage> &usages) override;
 	int configure(Camera *camera,
 		      const CameraConfiguration &config) override;
 
@@ -77,7 +76,7 @@ PipelineHandlerVimc::PipelineHandlerVimc(CameraManager *manager)
 
 CameraConfiguration
 PipelineHandlerVimc::generateConfiguration(Camera *camera,
-					   const std::vector<StreamUsage> &usages)
+					   const StreamRoles &roles)
 {
 	VimcCameraData *data = cameraData(camera);
 	CameraConfiguration config;

src/libcamera/pipeline_handler.cpp

@@ -221,18 +221,18 @@ void PipelineHandler::unlock()
  * \fn PipelineHandler::generateConfiguration()
  * \brief Generate a camera configuration for a specified camera
  * \param[in] camera The camera to generate a default configuration for
- * \param[in] usages A list of stream usages
+ * \param[in] roles A list of stream roles
  *
- * Generate a default configuration for the \a camera for a specified group of
+ * Generate a default configuration for the \a camera for a specified list of
- * use-cases. The caller shall populate the \a usages array with the use-cases
+ * stream roles. The caller shall populate the \a roles with the use-cases it
- * it wishes to fetch the default configuration for. The returned configuration
+ * wishes to fetch the default configuration for. The returned configuration
  * can then be examined by the caller to learn about the selected streams and
  * their default parameters.
  *
  * The intended companion to this is \a configure() which can be used to change
  * the group of streams parameters.
  *
- * \return A valid CameraConfiguration if the requested usages can be satisfied,
+ * \return A valid CameraConfiguration if the requested roles can be satisfied,
  * or a invalid configuration otherwise
  */
 

src/libcamera/stream.cpp

@@ -75,61 +75,31 @@ std::string StreamConfiguration::toString() const
 }
 
 /**
- * \class StreamUsage
+ * \enum StreamRole
- * \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 StreamRole describes how an application intends to use a stream. Roles
+ * are specified by applications and passed to cameras, that then select the
+ * most appropriate streams and their default configurations.
+ *
+ * \var 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
+ * \var 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
+ * \var 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
+ * local screen. Trade-offs between quality and usage of system resources are
- * between quality and usage of system resources are acceptable.
+ * acceptable.
  */
 
 /**
- * \fn StreamUsage::role()
+ * \typedef StreamRoles
- * \brief Retrieve the stream role
+ * \brief A vector of StreamRole
- * \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] size The desired size
- */
-StreamUsage::StreamUsage(Role role, const Size &size)
-	: role_(role), size_(size)
-{
-}
-
 /**
  * \class Stream
  * \brief Video stream for a camera
@@ -148,39 +118,6 @@ StreamUsage::StreamUsage(Role role, const Size &size)
  * 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, Size(width, height))
-{
-}
-
 /**
  * \brief Construct a stream with default parameters
  */

src/qcam/main_window.cpp

@@ -97,7 +97,7 @@ int MainWindow::startCapture()
 {
 	int ret;
 
-	config_ = camera_->generateConfiguration({ Stream::VideoRecording() });
+	config_ = camera_->generateConfiguration({ StreamRole::VideoRecording });
 	Stream *stream = config_.front();
 	ret = camera_->configure(config_);
 	if (ret < 0) {

test/camera/capture.cpp

@@ -43,7 +43,7 @@ protected:
 	int run()
 	{
 		CameraConfiguration config =
-			camera_->generateConfiguration({ Stream::VideoRecording() });
+			camera_->generateConfiguration({ StreamRole::VideoRecording });
 		Stream *stream = config.front();
 		StreamConfiguration *cfg = &config[stream];
 

test/camera/configuration_default.cpp

@@ -21,7 +21,7 @@ protected:
 		CameraConfiguration config;
 
 		/* Test asking for configuration for a video stream. */
-		config = camera_->generateConfiguration({ Stream::VideoRecording() });
+		config = camera_->generateConfiguration({ StreamRole::VideoRecording });
 		if (!config.isValid()) {
 			cout << "Default configuration invalid" << endl;
 			return TestFail;
@@ -29,11 +29,11 @@ protected:
 
 		/*
 		 * Test that asking for configuration for an empty array of
-		 * stream usages returns an empty list of configurations.
+		 * stream roles returns an empty list of configurations.
 		 */
 		config = camera_->generateConfiguration({});
 		if (config.isValid()) {
-			cout << "Failed to retrieve configuration for empty usage list"
+			cout << "Failed to retrieve configuration for empty roles list"
 			     << endl;
 			return TestFail;
 		}

test/camera/configuration_set.cpp

@@ -19,7 +19,7 @@ protected:
 	int run()
 	{
 		CameraConfiguration config =
-			camera_->generateConfiguration({ Stream::VideoRecording() });
+			camera_->generateConfiguration({ StreamRole::VideoRecording });
 		StreamConfiguration *cfg = &config[config.front()];
 
 		if (!config.isValid()) {

test/camera/statemachine.cpp

@@ -235,7 +235,7 @@ protected:
 
 	int run()
 	{
-		defconf_ = camera_->generateConfiguration({ Stream::VideoRecording() });
+		defconf_ = camera_->generateConfiguration({ StreamRole::VideoRecording });
 
 		if (testAvailable() != TestPass) {
 			cout << "State machine in Available state failed" << endl;