libcamera v0.0.3
Supporting cameras in Linux since 2019
Public Types | Public Member Functions | Public Attributes | Protected Types | Protected Member Functions | Protected Attributes | List of all members
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...
 
StreamConfigurationat (unsigned int index)
 Retrieve a reference to a stream configuration. More...
 
const StreamConfigurationat (unsigned int index) const
 Retrieve a const reference to a stream configuration. More...
 
StreamConfigurationoperator[] (unsigned int index)
 Retrieve a reference to a stream configuration. More...
 
const StreamConfigurationoperator[] (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...
 

Public Attributes

Transform transform
 User-specified transform to be applied to the image. More...
 

Protected Types

enum class  ColorSpaceFlag { None , StreamsShareColorSpace }
 Specify the behaviour of validateColorSpaces. More...
 
using ColorSpaceFlags = Flags< ColorSpaceFlag >
 A bitwise combination of ColorSpaceFlag values.
 

Protected Member Functions

 CameraConfiguration ()
 Create an empty camera configuration.
 
Status validateColorSpaces (ColorSpaceFlags flags=ColorSpaceFlag::None)
 Check the color spaces requested for each stream. More...
 

Protected Attributes

std::vector< StreamConfigurationconfig_
 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 at() function or operator[] return 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

◆ ColorSpaceFlag

Specify the behaviour of validateColorSpaces.

Enumerator
None 

No extra validation of color spaces is required.

StreamsShareColorSpace 

Non-raw output streams must share the same color space.

◆ 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]cfgThe stream configuration

◆ at() [1/2]

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

Retrieve a reference to a stream configuration.

Parameters
[in]indexNumerical index

The index represents the zero based insertion order of stream configuration into the camera configuration with addConfiguration(). Calling this function 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]indexNumerical index

The index represents the zero based insertion order of stream configuration into the camera configuration with addConfiguration(). Calling this function 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]indexNumerical index

The index represents the zero based insertion order of stream configuration into the camera configuration with addConfiguration(). Calling this function 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]indexNumerical index

The index represents the zero based insertion order of stream configuration into the camera configuration with addConfiguration(). Calling this function 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 function 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::InvalidThe configuration is invalid and can't be adjusted. This may only occur in extreme cases such as when the configuration is empty.
CameraConfigutation::AdjustedThe 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::ValidThe configuration was already valid and hasn't been adjusted.

◆ validateColorSpaces()

CameraConfiguration::Status libcamera::CameraConfiguration::validateColorSpaces ( ColorSpaceFlags  flags = ColorSpaceFlag::None)
protected

Check the color spaces requested for each stream.

Parameters
[in]flagsFlags to control the behaviour of this function

This function performs certain consistency checks on the color spaces of the streams and may adjust them so that:

  • Any raw streams have the Raw color space
  • If the StreamsShareColorSpace flag is set, all output streams are forced to share the same color space (this may be a constraint on some platforms).

It is optional for a pipeline handler to use this function.

Returns
A CameraConfiguration::Status value that describes the validation status.
Return values
CameraConfigutation::AdjustedThe configuration has been adjusted and is now valid. The color space of some or all of the streams may have been changed. The caller shall check the color spaces carefully.
CameraConfiguration::ValidThe configuration was already valid and hasn't been adjusted.

Member Data Documentation

◆ transform

libcamera::CameraConfiguration::transform

User-specified transform to be applied to the image.

The transform is a user-specified 2D plane transform that will be applied to the camera images by the processing pipeline before being handed to the application. This is subsequent to any transform that is already required to fix up any platform-defined rotation.

The usual 2D plane transforms are allowed here (horizontal/vertical flips, multiple of 90-degree rotations etc.), but the validate() function may adjust this field at its discretion if the selection is not supported.


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