libcamera::CameraConfiguration Class Reference

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...

Public Attributes
std::optional< SensorConfiguration >	sensorConfig
	The camera sensor configuration. More...
Orientation	orientation
	The desired orientation of the images produced by the camera. More...

Protected Types
enum	ColorSpaceFlag
	Specify the behaviour of validateColorSpaces.
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< 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 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

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 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]

index

Numerical 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]

index

Numerical 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]

index

Numerical 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::Invalid	The configuration is invalid and can't be adjusted. This may only occur in extreme cases such as when the configuration is empty.
CameraConfiguration::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.

validateColorSpaces()

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

protected

Check the color spaces requested for each stream.

Parameters

[in]

flags

Flags 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::Adjusted	The 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::Valid	The configuration was already valid and hasn't been adjusted.

Member Data Documentation

orientation

libcamera::CameraConfiguration::orientation

The desired orientation of the images produced by the camera.

The orientation field is a user-specified 2D plane transformation that specifies how the application wants the camera images to be rotated in the memory buffers.

If the orientation requested by the application cannot be obtained, the camera will not rotate or flip the images, and the validate() function will Adjust this value to the native image orientation produced by the camera.

By default the orientation field is set to Orientation::Rotate0.

sensorConfig

libcamera::CameraConfiguration::sensorConfig

The camera sensor configuration.

The sensorConfig member allows manual control of the configuration of the camera sensor. By default, if sensorConfig is not set, the camera will configure the sensor automatically based on the configuration of the streams. Applications can override this by manually specifying the full sensor configuration.

Refer to the camera-sensor-model documentation and to the SensorConfiguration class documentation for details about the sensor configuration process.

The camera sensor configuration applies to all streams produced by a camera from the same image source.

---

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

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