libcamera::CameraConfiguration Class Referenceabstract

Hold configuration for streams of the camera. More...

## Public Types

enum | Status { Valid , Adjusted , Invalid }
| Validity of a camera configuration. More...
using | iterator = std::vector< StreamConfiguration >::iterator
| Iterator for the stream configurations in the camera configuration.
using | const_iterator = std::vector< StreamConfiguration >::const_iterator
| Const iterator for the stream configuration in the camera configuration.

## Public Member Functions

void | addConfiguration (const StreamConfiguration &cfg)
| Add a stream configuration to the camera configuration. More...
virtual Status | validate ()=0
| Validate and possibly adjust the camera configuration. More...
StreamConfiguration & | at (unsigned int index)
| Retrieve a reference to a stream configuration. More...
const StreamConfiguration & | at (unsigned int index) const
| Retrieve a const reference to a stream configuration. More...
StreamConfiguration & | operator[] (unsigned int index)
| Retrieve a reference to a stream configuration. More...
const StreamConfiguration & | operator[] (unsigned int index) const
| Retrieve a const reference to a stream configuration. More...
iterator | begin ()
| Retrieve an iterator to the first stream configuration in the sequence. More...
const_iterator | begin () const
| Retrieve a const iterator to the first element of the stream configurations. More...
iterator | end ()
| Retrieve an iterator pointing to the past-the-end stream configuration in the sequence. More...
const_iterator | end () const
| Retrieve a const iterator pointing to the past-the-end stream configuration in the sequence. More...
bool | empty () const
| Check if the camera configuration is empty. More...
std::size_t | size () const
| Retrieve the number of stream configurations. More...

## Protected Member Functions

| CameraConfiguration ()
| Create an empty camera configuration.

## Protected Attributes

std::vector< StreamConfiguration > | config_
| The vector of stream configurations.

## Detailed Description

Hold configuration for streams of the camera.

The CameraConfiguration holds an ordered list of stream configurations. It supports iterators and operates as a vector of StreamConfiguration instances. The stream configurations are inserted by addConfiguration(), and the operator[](int) returns a reference to the StreamConfiguration based on its insertion index. Accessing a stream configuration with an invalid index results in undefined behaviour.

CameraConfiguration instances are retrieved from the camera with Camera::generateConfiguration(). Applications may then inspect the configuration, modify it, and possibly add new stream configuration entries with addConfiguration(). Once the camera configuration satisfies the application, it shall be validated by a call to validate(). The validation implements "try" semantics: it adjusts invalid configurations to the closest achievable parameters instead of rejecting them completely. Applications then decide whether to accept the modified configuration, or try again with a different set of parameters. Once the configuration is valid, it is passed to Camera::configure().

## Member Enumeration Documentation

## Status

enum libcamera::CameraConfiguration::Status

Validity of a camera configuration.

Enumerator
Valid | The configuration is fully valid
Adjusted | The configuration has been adjusted to a valid configuration
Invalid | The configuration is invalid and can't be adjusted automatically

## Member Function Documentation

## addConfiguration()

void libcamera::CameraConfiguration::addConfiguration | ( | const StreamConfiguration & | cfg | ) |

Add a stream configuration to the camera configuration.

Parameters

  [in] | cfg | The stream configuration

## at() [1/2]

StreamConfiguration & libcamera::CameraConfiguration::at | ( | unsigned int | index | ) |

Retrieve a reference to a stream configuration.

Parameters

  [in] | index | Numerical index

The index represents the zero based insertion order of stream configuration into the camera configuration with addConfiguration(). Calling this method with an invalid index results in undefined behaviour.

Returns
  The stream configuration

## at() [2/2]

const StreamConfiguration & libcamera::CameraConfiguration::at | ( | unsigned int | index | ) | const

Retrieve a const reference to a stream configuration.

Parameters

  [in] | index | Numerical index

The index represents the zero based insertion order of stream configuration into the camera configuration with addConfiguration(). Calling this method with an invalid index results in undefined behaviour.

Returns
  The stream configuration

## begin() [1/2]

CameraConfiguration::iterator libcamera::CameraConfiguration::begin | ( |  | ) |

Retrieve an iterator to the first stream configuration in the sequence.

Returns
  An iterator to the first stream configuration

## begin() [2/2]

CameraConfiguration::const_iterator libcamera::CameraConfiguration::begin | ( |  | ) | const

Retrieve a const iterator to the first element of the stream configurations.

Returns
  A const iterator to the first stream configuration

## empty()

bool libcamera::CameraConfiguration::empty | ( |  | ) | const

Check if the camera configuration is empty.

Returns
  True if the configuration is empty

## end() [1/2]

CameraConfiguration::iterator libcamera::CameraConfiguration::end | ( |  | ) |

Retrieve an iterator pointing to the past-the-end stream configuration in the sequence.

Returns
  An iterator to the element following the last stream configuration

## end() [2/2]

CameraConfiguration::const_iterator libcamera::CameraConfiguration::end | ( |  | ) | const

Retrieve a const iterator pointing to the past-the-end stream configuration in the sequence.

Returns
  A const iterator to the element following the last stream configuration

## operator[]() [1/2]

StreamConfiguration & libcamera::CameraConfiguration::operator[] | ( | unsigned int | index | ) |

inline

Retrieve a reference to a stream configuration.

Parameters

  [in] | index | Numerical index

The index represents the zero based insertion order of stream configuration into the camera configuration with addConfiguration(). Calling this method with an invalid index results in undefined behaviour.

Returns
  The stream configuration

## operator[]() [2/2]

const StreamConfiguration & libcamera::CameraConfiguration::operator[] | ( | unsigned int | index | ) | const

inline

Retrieve a const reference to a stream configuration.

Parameters

  [in] | index | Numerical index

The index represents the zero based insertion order of stream configuration into the camera configuration with addConfiguration(). Calling this method with an invalid index results in undefined behaviour.

Returns
  The stream configuration

## size()

std::size_t libcamera::CameraConfiguration::size | ( |  | ) | const

Retrieve the number of stream configurations.

Returns
  Number of stream configurations

## validate()

libcamera::CameraConfiguration::validate | ( |  | ) |

pure virtual

Validate and possibly adjust the camera configuration.

This method adjusts the camera configuration to the closest valid configuration and returns the validation status.

Todo:
  : Define exactly when to return each status code. Should stream parameters set to 0 by the caller be adjusted without returning Adjusted ? This would potentially be useful for applications but would get in the way in Camera::configure(). Do we need an extra status code to signal this ?

Todo:
  : Handle validation of buffers count when refactoring the buffers API.

Returns
  A CameraConfiguration::Status value that describes the validation status.

Return values

  CameraConfiguration::Invalid | The configuration is invalid and can't be adjusted. This may only occur in extreme cases such as when the configuration is empty.
  CameraConfigutation::Adjusted | The configuration has been adjusted and is now valid. Parameters may have changed for any stream, and stream configurations may have been removed. The caller shall check the configuration carefully.
  CameraConfiguration::Valid | The configuration was already valid and hasn't been adjusted.

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

- include/libcamera/camera.h
- src/libcamera/camera.cpp