[libcamera-devel] Configuration API

[Dorota Czaplejewicz]

Hi,

I've had some trouble understanding various configs as I messed with them, and several times I stood on the wrong side of what is a concrete set of parameters versus what is a description of possible parameters.

Following the IRC invitation for me to come up with a proposal, here's the simplest change to the public API I can imagine, which also solves the mixed responsibilities.

First off, an overview of the current state:

1. Call camera.generateConfiguration() to get an example configuration (which also contains some, but not all, possibilities via StreamConfiguration->formats())
2. Call camera.adjust(my_config) to get an updated config with a concrete configuration
3. Pass this updated config to the camera as the final one

Improvement that makes it clear what is a possibility and what is a chosen config (pardon the Python-like pseudocode):

1. Get ~all possible configurations via camera.getConfigSpace() returning all configurations: for each stream return Vec<StreamFormats>, e.g. formats = PossibleFormats
2. Choose one concrete configuration out of the PossibleFormats. Such a configuration will carry one concrete pair (size, format) per numbered stream.
E.g. concreteConfig = formats.choose([formats.streamConfig[0][0], formats.streamConfig[1][0]]).
If the selected combination is not supported, e.g. the user passed a format valid for stream 1 in the 0th place in the array, this can fail.
3. Call camera.adjust(concreteConfig), receive StreamConfiguration with filled in buffer count and other stuff the user typically does not care about.

In this scenario, StreamConfiguration does not have a ::formats() describing possible configurations at all. This becomes something the pipeline doesn't explicitly tell anyone except the user.

The immediate advantage to the user is that all configuration are available at the start, and selecting a configuration doesn't need a round trip to the camera.

The advantage to the pipeline writer is that StreamConfiguration now has only one responsibility: to contain a concrete configuration of the stream, and may no longer be seen as a source of knowledge about possible configurations (being a source of knowledge introduces concerns about persistence; a single configuration is ephemeral).

In terms of effort, this adds 2 user-accessible classes (PossibleFormats, ConcreteConfig), and 1 call on Camera::getConfigSpace. It removes StreamConfiguration::formats, meaning that pipelines need to be reworked to not rely on it.

Does this sound anywhere close to reasonable?
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://lists.libcamera.org/pipermail/libcamera-devel/attachments/20220624/14536874/attachment.sig>