libcamera: libcamera::ControlList Class Reference

libcamera v0.5.1 Supporting cameras in Linux since 2019

Loading...
Searching...
No Matches
libcamera::ControlList Class Reference

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

## Public Types
enum class | MergePolicy { KeepExisting = 0 , OverwriteExisting }
| The policy used by the merge function. More...
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.
| ControlList (const ControlIdMap &idmap, const ControlValidator *validator=nullptr)
| Construct a ControlList with an optional control validator.
| ControlList (const ControlInfoMap &infoMap, const ControlValidator *validator=nullptr)
| Construct a ControlList with the idmap of a control info map.
iterator | begin ()
| Retrieve an iterator to the first Control in the list.
iterator | end ()
| Retrieve an iterator pointing to the past-the-end control in the list.
const_iterator | begin () const
| Retrieve a const_iterator to the first Control in the list.
const_iterator | end () const
| Retrieve a const iterator pointing to the past-the-end control in the list.
bool | empty () const
| Identify if the list is empty.
std::size_t | size () const
| Retrieve the number of controls in the list.
void | clear ()
| Removes all controls from the list.
void | merge (const ControlList &source, MergePolicy policy=MergePolicy::KeepExisting)
| Merge the source into the ControlList.
bool | contains (unsigned int id) const
| Check if the list contains a control with the specified id.
template<typename T>
std::optional< T > | get (const Control< T > &ctrl) const
| Get the value of control ctrl.
template<typename T, typename V>
void | set (const Control< T > &ctrl, const V &value)
| Set the control ctrl value to value.
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.
const ControlValue & | get (unsigned int id) const
| Get the value of control id.
void | set (unsigned int id, const ControlValue &value)
| Set the value of control id to value.
const ControlInfoMap * | infoMap () const
| Retrieve the ControlInfoMap used to construct the ControlList.
const ControlIdMap * | idMap () const
| Retrieve the ControlId map used to construct the ControlList.

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

## Member Enumeration Documentation

## ◆ MergePolicy

enum class libcamera::ControlList::MergePolicy
| strong

The policy used by the merge function.

Enumerator
KeepExisting | Existing controls in the target list are kept.
OverwriteExisting | Existing controls in the target list are updated.

## 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()

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

std::optional< 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()

const ControlIdMap * 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()

const ControlInfoMap * 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, size_t Size>

void 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() [2/3]

template<typename T, typename V>

void 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() [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()

std::size_t 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