libcamera: camera: Add support for stream usages

Instead of requesting the default configuration for a set of streams
where the application has to figure out which streams provided by the
camera is best suited for its intended usage, have the library figure
this out by using stream usages.

The application asks the library for a list of streams and a suggested
default configuration for them by supplying a list of stream usages.
Once the list is retrieved the application can fine-tune the returned
configuration and then try to apply it to the camera.

Currently no pipeline handler is prepared to handle stream usages but
nor did it make use of the list of Stream IDs which was the previous
interface. The main reason for this is that all cameras currently only
provide one stream each. This will still be the case but the API will be
prepared to expand both pipeline handlers and applications to support
streams usages.

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

include/libcamera/camera.h

@@ -22,6 +22,7 @@ class PipelineHandler;
 class Request;
 class Stream;
 class StreamConfiguration;
+class StreamUsage;
 
 class Camera final
 {
@@ -44,7 +45,7 @@ public:
 
 	const std::set<Stream *> &streams() const;
 	std::map<Stream *, StreamConfiguration>
-	streamConfiguration(std::set<Stream *> &streams);
+	streamConfiguration(const std::vector<StreamUsage> &usage);
 	int configureStreams(std::map<Stream *, StreamConfiguration> &config);
 
 	int allocateBuffers();

src/cam/main.cpp

@@ -80,8 +80,7 @@ static int parseOptions(int argc, char *argv[])
 
 static int prepareCameraConfig(std::map<Stream *, StreamConfiguration> *config)
 {
-	std::set<Stream *> streams = camera->streams();
+	*config = camera->streamConfiguration({ Stream::VideoRecording() });
-	*config = camera->streamConfiguration(streams);
 	Stream *stream = config->begin()->first;
 
 	if (options.isSet(OptFormat)) {

src/libcamera/camera.cpp

@@ -345,33 +345,23 @@ const std::set<Stream *> &Camera::streams() const
 }
 
 /**
- * \brief Retrieve a group of stream configurations
+ * \brief Retrieve a group of stream configurations according to stream usages
- * \param[in] streams A map of stream IDs and configurations to setup
+ * \param[in] usages A list of stream usages
  *
- * Retrieve the camera's configuration for a specified group of streams. The
+ * Retrieve configuration for a set of desired usages. The caller specifies a
- * caller can specifies which of the camera's streams to retrieve configuration
+ * list of stream usages and the camera returns a map of suitable streams and
- * from by populating \a streams.
+ * their suggested default configurations.
  *
- * The easiest way to populate the array of streams to fetch configuration from
+ * \return A map of streams to configurations if the requested usages can be
- * is to first retrieve the camera's full array of stream with streams() and
+ * satisfied, or an empty map otherwise
- * then potentially trim it down to only contain the streams the caller
- * are interested in.
- *
- * \return A map of successfully retrieved stream IDs and configurations or an
- * empty list on error.
  */
 std::map<Stream *, StreamConfiguration>
-Camera::streamConfiguration(std::set<Stream *> &streams)
+Camera::streamConfiguration(const std::vector<StreamUsage> &usages)
 {
-	if (disconnected_ || !streams.size())
+	if (disconnected_ || !usages.size() || usages.size() > streams_.size())
 		return std::map<Stream *, StreamConfiguration>{};
 
-	for (Stream *stream : streams) {
+	return pipe_->streamConfiguration(this, usages);
-		if (streams_.find(stream) == streams_.end())
-			return std::map<Stream *, StreamConfiguration>{};
-	}
-
-	return pipe_->streamConfiguration(this, streams);
 }
 
 /**

src/libcamera/include/pipeline_handler.h

@@ -53,7 +53,7 @@ public:
 	virtual bool match(DeviceEnumerator *enumerator) = 0;
 
 	virtual std::map<Stream *, StreamConfiguration>
-	streamConfiguration(Camera *camera, std::set<Stream *> &streams) = 0;
+	streamConfiguration(Camera *camera, const std::vector<StreamUsage> &usages) = 0;
 	virtual int configureStreams(Camera *camera,
 				     std::map<Stream *, StreamConfiguration> &config) = 0;
 

src/libcamera/pipeline/ipu3/ipu3.cpp

@@ -141,7 +141,7 @@ public:
 
 	std::map<Stream *, StreamConfiguration>
 	streamConfiguration(Camera *camera,
-			    std::set<Stream *> &streams) override;
+			    const std::vector<StreamUsage> &usages) override;
 	int configureStreams(Camera *camera,
 			     std::map<Stream *, StreamConfiguration> &config) override;
 
@@ -206,7 +206,7 @@ PipelineHandlerIPU3::~PipelineHandlerIPU3()
 
 std::map<Stream *, StreamConfiguration>
 PipelineHandlerIPU3::streamConfiguration(Camera *camera,
-					 std::set<Stream *> &streams)
+					 const std::vector<StreamUsage> &usages)
 {
 	std::map<Stream *, StreamConfiguration> configs;
 	IPU3CameraData *data = cameraData(camera);

src/libcamera/pipeline/uvcvideo.cpp

@@ -28,7 +28,7 @@ public:
 
 	std::map<Stream *, StreamConfiguration>
 	streamConfiguration(Camera *camera,
-			    std::set<Stream *> &streams) override;
+			    const std::vector<StreamUsage> &usages) override;
 	int configureStreams(Camera *camera,
 			     std::map<Stream *, StreamConfiguration> &config) override;
 
@@ -84,14 +84,12 @@ PipelineHandlerUVC::~PipelineHandlerUVC()
 
 std::map<Stream *, StreamConfiguration>
 PipelineHandlerUVC::streamConfiguration(Camera *camera,
-					std::set<Stream *> &streams)
+					const std::vector<StreamUsage> &usages)
 {
 	UVCCameraData *data = cameraData(camera);
-
 	std::map<Stream *, StreamConfiguration> configs;
 	StreamConfiguration config{};
 
-	LOG(UVC, Debug) << "Retrieving default format";
 	config.width = 640;
 	config.height = 480;
 	config.pixelFormat = V4L2_PIX_FMT_YUYV;

src/libcamera/pipeline/vimc.cpp

@@ -28,7 +28,7 @@ public:
 
 	std::map<Stream *, StreamConfiguration>
 	streamConfiguration(Camera *camera,
-			    std::set<Stream *> &streams) override;
+			    const std::vector<StreamUsage> &usages) override;
 	int configureStreams(Camera *camera,
 			     std::map<Stream *, StreamConfiguration> &config) override;
 
@@ -84,14 +84,12 @@ PipelineHandlerVimc::~PipelineHandlerVimc()
 
 std::map<Stream *, StreamConfiguration>
 PipelineHandlerVimc::streamConfiguration(Camera *camera,
-					 std::set<Stream *> &streams)
+					 const std::vector<StreamUsage> &usages)
 {
 	VimcCameraData *data = cameraData(camera);
 	std::map<Stream *, StreamConfiguration> configs;
-
 	StreamConfiguration config{};
 
-	LOG(VIMC, Debug) << "Retrieving default format";
 	config.width = 640;
 	config.height = 480;
 	config.pixelFormat = V4L2_PIX_FMT_RGB24;

src/libcamera/pipeline_handler.cpp

@@ -152,13 +152,13 @@ PipelineHandler::~PipelineHandler()
  * \fn PipelineHandler::streamConfiguration()
  * \brief Retrieve a group of stream configurations for a specified camera
  * \param[in] camera The camera to fetch default configuration from
- * \param[in] streams An array of streams to fetch information about
+ * \param[in] usages A list of stream usages
  *
  * Retrieve the species camera's default configuration for a specified group of
- * streams. The caller shall populate the \a streams array with the streams it
+ * use-cases. The caller shall populate the \a usages array with the use-cases it
- * wish to fetch the configuration from. The map of streams and configuration
+ * wishes to fetch the default configuration for. The map of streams and
- * returned can then be examined by the caller to learn about the defualt
+ * configurations returned can then be examined by the caller to learn about
- * parameters for the specified streams.
+ * the default parameters for the specified streams.
  *
  * The intended companion to this is \a configureStreams() which can be used to
  * change the group of streams parameters.

src/qcam/main_window.cpp

@@ -97,9 +97,8 @@ int MainWindow::startCapture()
 {
 	int ret;
 
-	Stream *stream = *camera_->streams().begin();
+	config_ = camera_->streamConfiguration({ Stream::VideoRecording() });
-	std::set<Stream *> streams{ stream };
+	Stream *stream = config_.begin()->first;
-	config_ = camera_->streamConfiguration(streams);
 	ret = camera_->configureStreams(config_);
 	if (ret < 0) {
 		std::cout << "Failed to configure camera" << std::endl;

test/camera/capture.cpp

@@ -42,10 +42,9 @@ protected:
 
 	int run()
 	{
-		Stream *stream = *camera_->streams().begin();
-		std::set<Stream *> streams = { stream };
 		std::map<Stream *, StreamConfiguration> conf =
-			camera_->streamConfiguration(streams);
+			camera_->streamConfiguration({ Stream::VideoRecording() });
+		Stream *stream = conf.begin()->first;
 		StreamConfiguration *sconf = &conf.begin()->second;
 
 		if (!configurationValid(conf)) {

test/camera/configuration_default.cpp

@@ -20,14 +20,10 @@ protected:
 	{
 		std::map<Stream *, StreamConfiguration> conf;
 
-		/*
+		/* Test asking for configuration for a video stream. */
-		 * Test that asking for default configuration for a valid
+		conf = camera_->streamConfiguration({ Stream::VideoRecording() });
-		 * array of streams returns something valid.
-		 */
-		std::set<Stream *> streams = { *camera_->streams().begin() };
-		conf = camera_->streamConfiguration(streams);
 		if (conf.empty()) {
-			cout << "Failed to retrieve configuration for valid streams"
+			cout << "Failed to retrieve configuration for video streams"
 			     << endl;
 			return TestFail;
 		}
@@ -39,12 +35,11 @@ protected:
 
 		/*
 		 * Test that asking for configuration for an empty array of
-		 * streams returns an empty list of configurations.
+		 * stream usages returns an empty list of configurations.
 		 */
-		std::set<Stream *> streams_empty = {};
+		conf = camera_->streamConfiguration({});
-		conf = camera_->streamConfiguration(streams_empty);
 		if (!conf.empty()) {
-			cout << "Failed to retrieve configuration for empty streams"
+			cout << "Failed to retrieve configuration for empty usage list"
 			     << endl;
 			return TestFail;
 		}

test/camera/configuration_set.cpp

@@ -18,9 +18,8 @@ class ConfigurationSet : public CameraTest
 protected:
 	int run()
 	{
-		std::set<Stream *> streams = { *camera_->streams().begin() };
 		std::map<Stream *, StreamConfiguration> conf =
-			camera_->streamConfiguration(streams);
+			camera_->streamConfiguration({ Stream::VideoRecording() });
 		StreamConfiguration *sconf = &conf.begin()->second;
 
 		if (!configurationValid(conf)) {

test/camera/statemachine.cpp

@@ -235,9 +235,7 @@ protected:
 
 	int run()
 	{
-		Stream *stream = *camera_->streams().begin();
+		defconf_ = camera_->streamConfiguration({ Stream::VideoRecording() });
-		std::set<Stream *> streams = { stream };
-		defconf_ = camera_->streamConfiguration(streams);
 
 		if (testAvailable() != TestPass) {
 			cout << "State machine in Available state failed" << endl;