libcamera::GlobalConfiguration Class Reference

Support for global libcamera configuration. More...

Public Types
using	Configuration = const YamlObject &
	Type representing global libcamera configuration.

Public Member Functions
	GlobalConfiguration ()
	Initialize the global configuration.
unsigned int	version () const
	Retrieve the configuration version.
Configuration	configuration () const
	Retrieve the libcamera global configuration.
template<typename T >
std::optional< T >	option (const std::initializer_list< std::string_view > confPath) const
	Retrieve the value of configuration option confPath.
std::optional< std::vector< std::string > >	listOption (const std::initializer_list< std::string_view > confPath) const
	Retrieve the value of configuration option confPath.
std::optional< std::string >	envOption (const char *const envVariable, const std::initializer_list< std::string_view > confPath) const
	Retrieve the value of environment variable with a fallback on the configuration file.
std::optional< std::vector< std::string > >	envListOption (const char *const envVariable, const std::initializer_list< std::string_view > confPath, const std::string delimiter=":") const
	Retrieve the value of the configuration option from a file or environment.

Detailed Description

Support for global libcamera configuration.

The configuration file is a YAML file and the configuration itself is stored under a configuration top-level item.

The configuration file is looked up in the user's home directory first and, if it is not found, then in system-wide configuration directories. If multiple configuration files exist then only the first one found is used and no configuration merging is performed.

If the first found configuration file cannot be opened or parsed, an error is reported and no configuration file is used. This is to prevent libcamera from using an unintended configuration file.

The configuration can be accessed using the provided helpers, namely option(), envOption(), listOption() and envListOption() to access individual options, or configuration() to access the whole configuration.

Member Typedef Documentation

Configuration

libcamera::GlobalConfiguration::Configuration

Type representing global libcamera configuration.

All code outside GlobalConfiguration must use this type declaration and not the underlying type.

Member Function Documentation

configuration()

GlobalConfiguration::Configuration libcamera::GlobalConfiguration::configuration

(

)

const

Retrieve the libcamera global configuration.

This returns the whole configuration stored in the top-level section configuration of the YAML configuration file.

The requested part of the configuration can be accessed using YamlObject methods.

Note

YamlObject type itself shouldn't be used in type declarations to avoid trouble if we decide to change the underlying data objects in future.

Returns

The whole configuration section

envListOption()

std::optional< std::vector< std::string > > libcamera::GlobalConfiguration::envListOption	(	const char *const	envVariable,
		const std::initializer_list< std::string_view >	confPath,
		const std::string	delimiter = ":"
	)		const

Retrieve the value of the configuration option from a file or environment.

Parameters

[in]	envVariable	Environment variable to get the value from
[in]	confPath	The same as in GlobalConfiguration::option
[in]	delimiter	Items separator in the environment variable

This helper looks first at the given environment variable and if it is defined (even if it is empty) then it splits its value by semicolons and returns the resulting list of strings. Otherwise it looks for confPath the same way as in GlobalConfiguration::option, value of which must be a list of strings.

Note

Support for using environment variables to configure libcamera behavior is provided here mostly for backward compatibility reasons. Introducing new configuration environment variables is discouraged.

Returns

A vector of strings retrieved from the given environment option or configuration file or no value if not found; the vector may be empty

envOption()

std::optional< std::string > libcamera::GlobalConfiguration::envOption	(	const char *const	envVariable,
		const std::initializer_list< std::string_view >	confPath
	)		const

Retrieve the value of environment variable with a fallback on the configuration file.

Parameters

[in]	envVariable	Environment variable to get the value from
[in]	confPath	The sequence of YAML section names to fall back on when envVariable is unavailable

This helper looks first at the given environment variable and if it is defined then it returns its value (even if it is empty). Otherwise it looks for confPath the same way as in GlobalConfiguration::option. Only string values are supported.

Note

Support for using environment variables to configure libcamera behavior is provided here mostly for backward compatibility reasons. Introducing new configuration environment variables is discouraged.

Returns

The value retrieved from the given environment if it is set, otherwise the value from the configuration file if it exists, or no value if it does not

listOption()

std::optional< std::vector< std::string > > libcamera::GlobalConfiguration::listOption

(

const std::initializer_list< std::string_view >

confPath

)

const

Retrieve the value of configuration option confPath.

Parameters

[in]

confPath

Sequence of the YAML section names (excluding configuration) leading to the requested list option, separated by dots

Returns

A vector of strings or no value if not found

option()

template<typename T >

std::optional< T > libcamera::GlobalConfiguration::option ( const std::initializer_list< std::string_view >  confPath ) const

inline

Retrieve the value of configuration option confPath.

Template Parameters

T	The type of the retrieved configuration value

Parameters

[in]

confPath

Sequence of the YAML section names (excluding configuration) leading to the requested option

Returns

The value of the configuration item corresponding to confPath if it exists in the configuration file, or no value otherwise

version()

unsigned int libcamera::GlobalConfiguration::version

(

)

const

Retrieve the configuration version.

The version is declared in the configuration file in the top-level version element, alongside configuration. This has currently no real use but may be needed in future if configuration incompatibilities occur.

Returns

Configuration version as declared in the configuration file or 0 if no global configuration is available

---

The documentation for this class was generated from the following files:

• include/libcamera/internal/global_configuration.h
• src/libcamera/global_configuration.cpp