libcamera: libcamera::GlobalConfiguration Class Reference

libcamera v0.7.0 Supporting cameras in Linux since 2019

Loading...
Searching...
No Matches
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

using libcamera::GlobalConfiguration::Configuration = const YamlObject &

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