libcamera  v0.2.0+85-1c5830a9
Supporting cameras in Linux since 2019
Public Types | Public Member Functions | List of all members
libcamera::ControlList Class Reference

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 ControlValueget (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 ControlInfoMapinfoMap () const
 Retrieve the ControlInfoMap used to construct the ControlList. More...
 
const ControlIdMapidMap () 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]idmapThe ControlId map for the control list target object
[in]validatorThe 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]infoMapThe ControlInfoMap for the control list target object
[in]validatorThe 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]idThe 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]ctrlThe 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]idThe 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]sourceThe ControlList to merge into this object
[in]policyControls 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]ctrlThe control
[in]valueThe 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]ctrlThe control
[in]valueThe 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]idThe control ID
[in]valueThe 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: