Associate a list of ControlId with their values for an object. More...

Public Types
enum	MergePolicy { KeepExisting = 0, OverwriteExisting }
	The policy used by the merge function.

using	iterator = ControlListMap::iterator
	Iterator for the controls contained within the list.

using	const_iterator = ControlListMap::const_iterator
	Const iterator for the controls contained within the list.

Public Member Functions
	ControlList ()
	Construct a ControlList not associated with any object. More...

	ControlList (const ControlIdMap &idmap, const ControlValidator *validator=nullptr)
	Construct a ControlList with an optional control validator. More...

	ControlList (const ControlInfoMap &infoMap, const ControlValidator *validator=nullptr)
	Construct a ControlList with the idmap of a control info map. More...

iterator	begin ()
	Retrieve an iterator to the first Control in the list. More...

iterator	end ()
	Retrieve an iterator pointing to the past-the-end control in the list. More...

const_iterator	begin () const
	Retrieve a const_iterator to the first Control in the list. More...

const_iterator	end () const
	Retrieve a const iterator pointing to the past-the-end control in the list. More...

bool	empty () const
	Identify if the list is empty. More...

std::size_t	size () const
	Retrieve the number of controls in the list. More...

void	clear ()
	Removes all controls from the list.

void	merge (const ControlList &source, MergePolicy policy=MergePolicy::KeepExisting)
	Merge the source into the ControlList. More...

bool	contains (unsigned int id) const
	Check if the list contains a control with the specified id. More...

template<typename T >
std::optional< T >	get (const Control< T > &ctrl) const
	Get the value of control ctrl. More...

template<typename T , typename V >
void	set (const Control< T > &ctrl, const V &value)
	Set the control ctrl value to value. More...

template<typename T , typename V , size_t Size>
void	set (const Control< Span< T, Size >> &ctrl, const std::initializer_list< V > &value)
	Set the control ctrl value to value. More...

const ControlValue &	get (unsigned int id) const
	Get the value of control id. More...

void	set (unsigned int id, const ControlValue &value)
	Set the value of control id to value. More...

const ControlInfoMap *	infoMap () const
	Retrieve the ControlInfoMap used to construct the ControlList. More...

const ControlIdMap *	idMap () const
	Retrieve the ControlId map used to construct the ControlList. More...

Detailed Description

Associate a list of ControlId with their values for an object.

The ControlList class stores values of controls exposed by an object. The lists returned by the Request::controls() and Request::metadata() functions refer to the camera that the request belongs to.

Control lists are constructed with a map of all the controls supported by their object, and an optional ControlValidator to further validate the controls.

Constructor & Destructor Documentation

◆ ControlList() [1/3]

libcamera::ControlList::ControlList ( )

Construct a ControlList not associated with any object.

This constructor is meant to support ControlList serialization and shall not be used directly by application.

◆ ControlList() [2/3]

libcamera::ControlList::ControlList	(	const ControlIdMap &	idmap,
		const ControlValidator *	validator = `nullptr`
	)

Construct a ControlList with an optional control validator.

Parameters

[in]	idmap	The ControlId map for the control list target object
[in]	validator	The validator (may be null)

For ControlList containing libcamera controls, a global map of all libcamera controls is provided by controls::controls and can be used as the idmap argument.

◆ ControlList() [3/3]

libcamera::ControlList::ControlList	(	const ControlInfoMap &	infoMap,
		const ControlValidator *	validator = `nullptr`
	)

Construct a ControlList with the idmap of a control info map.

Parameters

[in]	infoMap	The ControlInfoMap for the control list target object
[in]	validator	The validator (may be null)

Member Function Documentation

◆ begin() [1/2]

iterator libcamera::ControlList::begin ( )

inline

Retrieve an iterator to the first Control in the list.

Returns: An iterator to the first Control in the list

◆ begin() [2/2]

const_iterator libcamera::ControlList::begin ( ) const

inline

Retrieve a const_iterator to the first Control in the list.

Returns: A const_iterator to the first Control in the list

◆ contains()

bool libcamera::ControlList::contains ( unsigned int id ) const

Check if the list contains a control with the specified id.

Parameters

[in] id The control numerical ID

Returns: True if the list contains a matching control, false otherwise

◆ empty()

libcamera::ControlList::empty ( ) const

inline

Identify if the list is empty.

Returns: True if the list does not contain any control, false otherwise

◆ end() [1/2]

iterator libcamera::ControlList::end ( )

inline

Retrieve an iterator pointing to the past-the-end control in the list.

Returns: An iterator to the element following the last control in the list

◆ end() [2/2]

const_iterator libcamera::ControlList::end ( ) const

inline

Retrieve a const iterator pointing to the past-the-end control in the list.

Returns: A const iterator to the element following the last control in the list

◆ get() [1/2]

template<typename T >

libcamera::ControlList::get ( const Control< T > & ctrl ) const

inline

Get the value of control ctrl.

Parameters

[in] ctrl The control

Beside getting the value of a control, this function can also be used to check if a control is present in the ControlList by converting the returned std::optional<T> to bool (or calling its has_value() function).

Returns: A std::optional<T> containing the control value, or std::nullopt if the control ctrl is not present in the list

◆ get() [2/2]

const ControlValue & libcamera::ControlList::get ( unsigned int id ) const

Get the value of control id.

Parameters

[in] id The control numerical ID

The behaviour is undefined if the control id is not present in the list. Use ControlList::contains() to test for the presence of a control in the list before retrieving its value.

Returns: The control value

◆ idMap()

libcamera::ControlList::idMap ( ) const

inline

Retrieve the ControlId map used to construct the ControlList.

Returns: The ControlId map used to construct the ControlList. ControlList instances constructed with the default contructor have no associated idmap, nullptr is returned in that case.

◆ infoMap()

libcamera::ControlList::infoMap ( ) const

inline

Retrieve the ControlInfoMap used to construct the ControlList.

Returns: The ControlInfoMap used to construct the ControlList. ControlList instances constructed with ControlList() or ControlList(const ControlIdMap &idmap, ControlValidator *validator) have no associated ControlInfoMap, nullptr is returned in that case.

◆ merge()

void libcamera::ControlList::merge	(	const ControlList &	source,
		MergePolicy	policy = `MergePolicy::KeepExisting`
	)

Merge the source into the ControlList.

Parameters

[in]	source	The ControlList to merge into this object
[in]	policy	Controls if existing elements in *this shall be overwritten

Merging two control lists copies elements from the source and inserts them in *this. If the source contains elements whose key is already present in *this, then those elements are only overwritten if policy is MergePolicy::OverwriteExisting.

Only control lists created from the same ControlIdMap or ControlInfoMap may be merged. Attempting to do otherwise results in undefined behaviour.

Todo:: Reimplement or implement an overloaded version which internally uses std::unordered_map::merge() and accepts a non-const argument.

Todo:: ASSERT that the current and source ControlList are derived from a compatible ControlIdMap, to prevent undefined behaviour due to id collisions.

This can not currently be a direct pointer comparison due to the duplication of the ControlIdMaps in the isolated IPA use cases. Furthermore, manually checking each entry of the id map is identical is expensive. See https://bugs.libcamera.org/show_bug.cgi?id=31 for further details

◆ set() [1/3]

template<typename T , typename V >

libcamera::ControlList::set	(	const Control< T > &	ctrl,
		const V &	value
	)

inline

Set the control ctrl value to value.

Parameters

[in]	ctrl	The control
[in]	value	The control value

This function sets the value of a control in the control list. If the control is already present in the list, its value is updated, otherwise it is added to the list.

The behaviour is undefined if the control ctrl is not supported by the object that the list refers to.

◆ set() [2/3]

template<typename T , typename V , size_t Size>

libcamera::ControlList::set	(	const Control< Span< T, Size >> &	ctrl,
		const std::initializer_list< V > &	value
	)

inline

Set the control ctrl value to value.

Parameters

[in]	ctrl	The control
[in]	value	The control value

This function sets the value of a control in the control list. If the control is already present in the list, its value is updated, otherwise it is added to the list.

The behaviour is undefined if the control ctrl is not supported by the object that the list refers to.

◆ set() [3/3]

void libcamera::ControlList::set	(	unsigned int	id,
		const ControlValue &	value
	)

Set the value of control id to value.

Parameters

[in]	id	The control ID
[in]	value	The control value

This function sets the value of a control in the control list. If the control is already present in the list, its value is updated, otherwise it is added to the list.

The behaviour is undefined if the control id is not supported by the object that the list refers to.

◆ size()

libcamera::ControlList::size ( ) const

inline

Retrieve the number of controls in the list.

Returns: The number of Control entries stored in the list

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

include/libcamera/controls.h
src/libcamera/controls.cpp

Public Types

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ControlList() [1/3]

◆ ControlList() [2/3]

◆ ControlList() [3/3]

Member Function Documentation

◆ begin() [1/2]

◆ begin() [2/2]

◆ contains()

◆ empty()

◆ end() [1/2]

◆ end() [2/2]

◆ get() [1/2]

◆ get() [2/2]

◆ idMap()

◆ infoMap()

◆ merge()

◆ set() [1/3]

◆ set() [2/3]

◆ set() [3/3]

◆ size()