Loading...
Searching...
No Matches
controls.h
Go to the documentation of this file.
/* SPDX-License-Identifier: LGPL-2.1-or-later */
/*
* Copyright (C) 2019, Google Inc.
*
* Control handling
*/
#pragma once
#include <assert.h>
#include <map>
#include <optional>
#include <stdint.h>
#include <string>
#include <string_view>
#include <unordered_map>
#include <vector>
#include <libcamera/base/class.h>
#include <libcamera/base/flags.h>
#include <libcamera/base/span.h>
#include <libcamera/geometry.h>
namespace libcamera {
class ControlValidator;
enum ControlType {
ControlTypeNone,
ControlTypeBool,
ControlTypeByte,
ControlTypeUnsigned16,
ControlTypeUnsigned32,
ControlTypeInteger32,
ControlTypeInteger64,
ControlTypeFloat,
ControlTypeString,
ControlTypeRectangle,
ControlTypeSize,
ControlTypePoint,
};
namespace details {
template<typename T, typename = void>
struct control_type {
};
template<>
struct control_type<void> {
static constexpr ControlType value = ControlTypeNone;
static constexpr std::size_t size = 0;
};
template<>
struct control_type<bool> {
static constexpr ControlType value = ControlTypeBool;
static constexpr std::size_t size = 0;
};
template<>
struct control_type<uint8_t> {
static constexpr ControlType value = ControlTypeByte;
static constexpr std::size_t size = 0;
};
template<>
struct control_type<uint16_t> {
static constexpr ControlType value = ControlTypeUnsigned16;
static constexpr std::size_t size = 0;
};
template<>
struct control_type<uint32_t> {
static constexpr ControlType value = ControlTypeUnsigned32;
static constexpr std::size_t size = 0;
};
template<>
struct control_type<int32_t> {
static constexpr ControlType value = ControlTypeInteger32;
static constexpr std::size_t size = 0;
};
template<>
struct control_type<int64_t> {
static constexpr ControlType value = ControlTypeInteger64;
static constexpr std::size_t size = 0;
};
template<>
struct control_type<float> {
static constexpr ControlType value = ControlTypeFloat;
static constexpr std::size_t size = 0;
};
template<>
struct control_type<std::string_view> {
static constexpr ControlType value = ControlTypeString;
static constexpr std::size_t size = 0;
};
template<>
struct control_type<Rectangle> {
static constexpr ControlType value = ControlTypeRectangle;
static constexpr std::size_t size = 0;
};
template<>
struct control_type<Size> {
static constexpr ControlType value = ControlTypeSize;
static constexpr std::size_t size = 0;
};
template<>
struct control_type<Point> {
static constexpr ControlType value = ControlTypePoint;
static constexpr std::size_t size = 0;
};
template<typename T, std::size_t N>
struct control_type<Span<T, N>, std::enable_if_t<control_type<std::remove_cv_t<T>>::size == 0>> : public control_type<std::remove_cv_t<T>> {
static constexpr std::size_t size = N;
};
template<typename T>
struct control_type<T, std::enable_if_t<std::is_enum_v<T> && sizeof(T) == sizeof(int32_t)>> : public control_type<int32_t> {
};
} /* namespace details */
class ControlValue
{
public:
ControlValue();
#ifndef __DOXYGEN__
template<typename T, std::enable_if_t<!details::is_span<T>::value &&
details::control_type<T>::value &&
!std::is_same<std::string_view, std::remove_cv_t<T>>::value,
std::nullptr_t> = nullptr>
ControlValue(const T &value)
: type_(ControlTypeNone), numElements_(0)
{
set(details::control_type<std::remove_cv_t<T>>::value, false,
&value, 1, sizeof(T));
}
template<typename T, std::enable_if_t<details::is_span<T>::value ||
std::is_same<std::string_view, std::remove_cv_t<T>>::value,
std::nullptr_t> = nullptr>
#else
template<typename T>
#endif
ControlValue(const T &value)
: type_(ControlTypeNone), numElements_(0)
{
set(details::control_type<std::remove_cv_t<T>>::value, true,
value.data(), value.size(), sizeof(typename T::value_type));
}
~ControlValue();
ControlValue(const ControlValue &other);
ControlValue &operator=(const ControlValue &other);
ControlType type() const { return type_; }
bool isNone() const { return type_ == ControlTypeNone; }
bool isArray() const { return isArray_; }
std::size_t numElements() const { return numElements_; }
Span<const uint8_t> data() const;
Span<uint8_t> data();
std::string toString() const;
bool operator==(const ControlValue &other) const;
bool operator!=(const ControlValue &other) const
{
return !(*this == other);
}
#ifndef __DOXYGEN__
template<typename T, std::enable_if_t<!details::is_span<T>::value &&
!std::is_same<std::string_view, std::remove_cv_t<T>>::value,
std::nullptr_t> = nullptr>
T get() const
{
assert(type_ == details::control_type<std::remove_cv_t<T>>::value);
assert(!isArray_);
return *reinterpret_cast<const T *>(data().data());
}
template<typename T, std::enable_if_t<details::is_span<T>::value ||
std::is_same<std::string_view, std::remove_cv_t<T>>::value,
std::nullptr_t> = nullptr>
#else
template<typename T>
#endif
T get() const
{
assert(type_ == details::control_type<std::remove_cv_t<T>>::value);
assert(isArray_);
using V = typename T::value_type;
const V *value = reinterpret_cast<const V *>(data().data());
return T{ value, numElements_ };
}
#ifndef __DOXYGEN__
template<typename T, std::enable_if_t<!details::is_span<T>::value &&
!std::is_same<std::string_view, std::remove_cv_t<T>>::value,
std::nullptr_t> = nullptr>
void set(const T &value)
{
set(details::control_type<std::remove_cv_t<T>>::value, false,
reinterpret_cast<const void *>(&value), 1, sizeof(T));
}
template<typename T, std::enable_if_t<details::is_span<T>::value ||
std::is_same<std::string_view, std::remove_cv_t<T>>::value,
std::nullptr_t> = nullptr>
#else
template<typename T>
#endif
void set(const T &value)
{
set(details::control_type<std::remove_cv_t<T>>::value, true,
value.data(), value.size(), sizeof(typename T::value_type));
}
void reserve(ControlType type, bool isArray = false,
std::size_t numElements = 1);
private:
ControlType type_ : 8;
bool isArray_;
std::size_t numElements_ : 32;
union {
uint64_t value_;
void *storage_;
};
void release();
void set(ControlType type, bool isArray, const void *data,
std::size_t numElements, std::size_t elementSize);
};
class ControlId
{
public:
enum class Direction {
In = (1 << 0),
Out = (1 << 1),
};
using DirectionFlags = Flags<Direction>;
ControlId(unsigned int id, const std::string &name, const std::string &vendor,
ControlType type, DirectionFlags direction,
std::size_t size = 0,
const std::map<std::string, int32_t> &enumStrMap = {});
unsigned int id() const { return id_; }
const std::string &name() const { return name_; }
const std::string &vendor() const { return vendor_; }
ControlType type() const { return type_; }
DirectionFlags direction() const { return direction_; }
bool isInput() const { return !!(direction_ & Direction::In); }
bool isOutput() const { return !!(direction_ & Direction::Out); }
bool isArray() const { return size_ > 0; }
std::size_t size() const { return size_; }
const std::map<int32_t, std::string> &enumerators() const { return reverseMap_; }
private:
LIBCAMERA_DISABLE_COPY_AND_MOVE(ControlId)
unsigned int id_;
std::string name_;
std::string vendor_;
ControlType type_;
DirectionFlags direction_;
std::size_t size_;
std::map<std::string, int32_t> enumStrMap_;
std::map<int32_t, std::string> reverseMap_;
};
LIBCAMERA_FLAGS_ENABLE_OPERATORS(ControlId::Direction)
static inline bool operator==(unsigned int lhs, const ControlId &rhs)
{
return lhs == rhs.id();
}
static inline bool operator!=(unsigned int lhs, const ControlId &rhs)
{
return !(lhs == rhs);
}
static inline bool operator==(const ControlId &lhs, unsigned int rhs)
{
return lhs.id() == rhs;
}
static inline bool operator!=(const ControlId &lhs, unsigned int rhs)
{
return !(lhs == rhs);
}
template<typename T>
class Control : public ControlId
{
public:
using type = T;
Control(unsigned int id, const char *name, const char *vendor,
ControlId::DirectionFlags direction,
const std::map<std::string, int32_t> &enumStrMap = {})
: ControlId(id, name, vendor, details::control_type<std::remove_cv_t<T>>::value,
direction, details::control_type<std::remove_cv_t<T>>::size, enumStrMap)
{
}
private:
LIBCAMERA_DISABLE_COPY_AND_MOVE(Control)
};
class ControlInfo
{
public:
explicit ControlInfo(const ControlValue &min = {},
const ControlValue &max = {},
const ControlValue &def = {});
explicit ControlInfo(Span<const ControlValue> values,
const ControlValue &def = {});
const ControlValue &min() const { return min_; }
const ControlValue &max() const { return max_; }
const ControlValue &def() const { return def_; }
const std::vector<ControlValue> &values() const { return values_; }
std::string toString() const;
bool operator==(const ControlInfo &other) const
{
return min_ == other.min_ && max_ == other.max_;
}
bool operator!=(const ControlInfo &other) const
{
return !(*this == other);
}
private:
ControlValue min_;
ControlValue max_;
ControlValue def_;
std::vector<ControlValue> values_;
};
using ControlIdMap = std::unordered_map<unsigned int, const ControlId *>;
class ControlInfoMap : private std::unordered_map<const ControlId *, ControlInfo>
{
public:
using Map = std::unordered_map<const ControlId *, ControlInfo>;
ControlInfoMap() = default;
ControlInfoMap(const ControlInfoMap &other) = default;
ControlInfoMap(std::initializer_list<Map::value_type> init,
const ControlIdMap &idmap);
ControlInfoMap(Map &&info, const ControlIdMap &idmap);
ControlInfoMap &operator=(const ControlInfoMap &other) = default;
using Map::key_type;
using Map::mapped_type;
using Map::value_type;
using Map::size_type;
using Map::iterator;
using Map::const_iterator;
using Map::begin;
using Map::cbegin;
using Map::end;
using Map::cend;
using Map::at;
using Map::empty;
using Map::size;
using Map::count;
using Map::find;
mapped_type &at(unsigned int key);
const mapped_type &at(unsigned int key) const;
size_type count(unsigned int key) const;
iterator find(unsigned int key);
const_iterator find(unsigned int key) const;
const ControlIdMap &idmap() const { return *idmap_; }
private:
bool validate();
const ControlIdMap *idmap_ = nullptr;
};
class ControlList
{
private:
using ControlListMap = std::unordered_map<unsigned int, ControlValue>;
public:
enum class MergePolicy {
KeepExisting = 0,
OverwriteExisting,
};
ControlList();
ControlList(const ControlIdMap &idmap, const ControlValidator *validator = nullptr);
ControlList(const ControlInfoMap &infoMap, const ControlValidator *validator = nullptr);
using iterator = ControlListMap::iterator;
using const_iterator = ControlListMap::const_iterator;
iterator begin() { return controls_.begin(); }
iterator end() { return controls_.end(); }
const_iterator begin() const { return controls_.begin(); }
const_iterator end() const { return controls_.end(); }
bool empty() const { return controls_.empty(); }
std::size_t size() const { return controls_.size(); }
void clear() { controls_.clear(); }
void merge(const ControlList &source, MergePolicy policy = MergePolicy::KeepExisting);
bool contains(unsigned int id) const;
template<typename T>
std::optional<T> get(const Control<T> &ctrl) const
{
const auto entry = controls_.find(ctrl.id());
if (entry == controls_.end())
return std::nullopt;
const ControlValue &val = entry->second;
return val.get<T>();
}
template<typename T, typename V>
void set(const Control<T> &ctrl, const V &value)
{
ControlValue *val = find(ctrl.id());
if (!val)
return;
val->set<T>(value);
}
template<typename T, typename V, size_t Size>
void set(const Control<Span<T, Size>> &ctrl, const std::initializer_list<V> &value)
{
ControlValue *val = find(ctrl.id());
if (!val)
return;
val->set(Span<const typename std::remove_cv_t<V>, Size>{ value.begin(), value.size() });
}
const ControlValue &get(unsigned int id) const;
void set(unsigned int id, const ControlValue &value);
const ControlInfoMap *infoMap() const { return infoMap_; }
const ControlIdMap *idMap() const { return idmap_; }
private:
const ControlValue *find(unsigned int id) const;
ControlValue *find(unsigned int id);
const ControlValidator *validator_;
const ControlIdMap *idmap_;
const ControlInfoMap *infoMap_;
ControlListMap controls_;
};
} /* namespace libcamera */
libcamera::ControlId
Control static metadata.
Definition controls.h:251
libcamera::ControlId::enumerators
const std::map< int32_t, std::string > & enumerators() const
Retrieve the map of enum values to enum names.
Definition controls.h:274
libcamera::ControlId::type
ControlType type() const
Retrieve the control data type.
Definition controls.h:268
libcamera::ControlId::name
const std::string & name() const
Retrieve the control name.
Definition controls.h:266
libcamera::ControlId::ControlId
ControlId(unsigned int id, const std::string &name, const std::string &vendor, ControlType type, DirectionFlags direction, std::size_t size=0, const std::map< std::string, int32_t > &enumStrMap={})
Construct a ControlId instance.
Definition controls.cpp:419
libcamera::ControlId::isOutput
bool isOutput() const
Determine if the control is available to be used in output metadata.
Definition controls.h:271
libcamera::ControlId::isInput
bool isInput() const
Determine if the control is available to be used as an input control.
Definition controls.h:270
libcamera::ControlId::DirectionFlags
Flags< Direction > DirectionFlags
A wrapper for ControlId::Direction so that it can be used as flags.
Definition controls.h:258
libcamera::ControlId::Direction
Direction
The direction the control is capable of being passed from/to.
Definition controls.h:253
libcamera::ControlId::Direction::Out
@ Out
The control can be returned as output in metadata.
Definition controls.h:255
libcamera::ControlId::Direction::In
@ In
The control can be passed as input in controls.
Definition controls.h:254
libcamera::ControlId::vendor
const std::string & vendor() const
Retrieve the vendor name.
Definition controls.h:267
libcamera::ControlId::isArray
bool isArray() const
Determine if the control is an array control.
Definition controls.h:272
libcamera::ControlId::direction
DirectionFlags direction() const
Return the direction that the control can be used in.
Definition controls.h:269
libcamera::ControlId::size
std::size_t size() const
Retrieve the size of the control if it is an array control.
Definition controls.h:273
libcamera::ControlId::id
unsigned int id() const
Retrieve the control numerical ID.
Definition controls.h:265
libcamera::ControlInfoMap
A map of ControlId to ControlInfo.
Definition controls.h:365
libcamera::ControlInfoMap::at
mapped_type & at(unsigned int key)
Access specified element by numerical ID.
Definition controls.cpp:805
libcamera::ControlInfoMap::idmap
const ControlIdMap & idmap() const
Retrieve the ControlId map.
Definition controls.h:400
libcamera::ControlInfoMap::operator=
ControlInfoMap & operator=(const ControlInfoMap &other)=default
Copy assignment operator, replace the contents with a copy of other.
libcamera::ControlInfoMap::find
iterator find(unsigned int key)
Find the element matching a numerical ID.
Definition controls.cpp:840
libcamera::ControlInfoMap::ControlInfoMap
ControlInfoMap(const ControlInfoMap &other)=default
Copy constructor, construct a ControlInfoMap from a copy of other.
libcamera::ControlInfoMap::count
size_type count(unsigned int key) const
Count the number of elements matching a numerical ID.
Definition controls.cpp:829
libcamera::ControlInfoMap::Map
std::unordered_map< const ControlId *, ControlInfo > Map
The base std::unsorted_map<> container.
Definition controls.h:367
libcamera::ControlInfo::values
const std::vector< ControlValue > & values() const
Retrieve the list of valid values.
Definition controls.h:341
libcamera::ControlInfo::toString
std::string toString() const
Provide a string representation of the ControlInfo.
Definition controls.cpp:670
libcamera::ControlInfo::ControlInfo
ControlInfo(const ControlValue &min={}, const ControlValue &max={}, const ControlValue &def={})
Construct a ControlInfo with minimum and maximum range parameters.
Definition controls.cpp:599
libcamera::ControlInfo::max
const ControlValue & max() const
Retrieve the maximum value of the control.
Definition controls.h:339
libcamera::ControlInfo::def
const ControlValue & def() const
Retrieve the default value of the control.
Definition controls.h:340
libcamera::ControlInfo::operator==
bool operator==(const ControlInfo &other) const
Compare ControlInfo instances for equality.
Definition controls.h:345
libcamera::ControlInfo::operator!=
bool operator!=(const ControlInfo &other) const
Compare ControlInfo instances for non equality.
Definition controls.h:350
libcamera::ControlInfo::min
const ControlValue & min() const
Retrieve the minimum value of the control.
Definition controls.h:338
libcamera::ControlList
Associate a list of ControlId with their values for an object.
Definition controls.h:409
libcamera::ControlList::empty
bool empty() const
Identify if the list is empty.
Definition controls.h:431
libcamera::ControlList::merge
void merge(const ControlList &source, MergePolicy policy=MergePolicy::KeepExisting)
Merge the source into the ControlList.
Definition controls.cpp:1012
libcamera::ControlList::iterator
ControlListMap::iterator iterator
Iterator for the controls contained within the list.
Definition controls.h:423
libcamera::ControlList::infoMap
const ControlInfoMap * infoMap() const
Retrieve the ControlInfoMap used to construct the ControlList.
Definition controls.h:473
libcamera::ControlList::end
iterator end()
Retrieve an iterator pointing to the past-the-end control in the list.
Definition controls.h:427
libcamera::ControlList::MergePolicy
MergePolicy
The policy used by the merge function.
Definition controls.h:414
libcamera::ControlList::MergePolicy::OverwriteExisting
@ OverwriteExisting
Existing controls in the target list are updated.
Definition controls.h:416
libcamera::ControlList::MergePolicy::KeepExisting
@ KeepExisting
Existing controls in the target list are kept.
Definition controls.h:415
libcamera::ControlList::size
std::size_t size() const
Retrieve the number of controls in the list.
Definition controls.h:432
libcamera::ControlList::set
void set(const Control< Span< T, Size > > &ctrl, const std::initializer_list< V > &value)
Set the control ctrl value to value.
Definition controls.h:461
libcamera::ControlList::set
void set(const Control< T > &ctrl, const V &value)
Set the control ctrl value to value.
Definition controls.h:451
libcamera::ControlList::clear
void clear()
Removes all controls from the list.
Definition controls.h:434
libcamera::ControlList::get
std::optional< T > get(const Control< T > &ctrl) const
Get the value of control ctrl.
Definition controls.h:440
libcamera::ControlList::begin
iterator begin()
Retrieve an iterator to the first Control in the list.
Definition controls.h:426
libcamera::ControlList::const_iterator
ControlListMap::const_iterator const_iterator
Const iterator for the controls contained within the list.
Definition controls.h:424
libcamera::ControlList::contains
bool contains(unsigned int id) const
Check if the list contains a control with the specified id.
Definition controls.cpp:1044
libcamera::ControlList::idMap
const ControlIdMap * idMap() const
Retrieve the ControlId map used to construct the ControlList.
Definition controls.h:474
libcamera::ControlList::begin
const_iterator begin() const
Retrieve a const_iterator to the first Control in the list.
Definition controls.h:428
libcamera::ControlList::ControlList
ControlList()
Construct a ControlList not associated with any object.
Definition controls.cpp:900
libcamera::ControlList::end
const_iterator end() const
Retrieve a const iterator pointing to the past-the-end control in the list.
Definition controls.h:429
libcamera::ControlValue
Abstract type representing the value of a control.
Definition controls.h:134
libcamera::ControlValue::ControlValue
ControlValue(const T &value)
Construct a ControlValue of type T.
Definition controls.h:156
libcamera::ControlValue::isArray
bool isArray() const
Determine if the value stores an array.
Definition controls.h:170
libcamera::ControlValue::numElements
std::size_t numElements() const
Retrieve the number of elements stored in the ControlValue.
Definition controls.h:171
libcamera::ControlValue::isNone
bool isNone() const
Determine if the value is not initialised.
Definition controls.h:169
libcamera::ControlValue::operator=
ControlValue & operator=(const ControlValue &other)
Replace the content of the ControlValue with a copy of the content of other.
Definition controls.cpp:152
libcamera::ControlValue::reserve
void reserve(ControlType type, bool isArray=false, std::size_t numElements=1)
Set the control type and reserve memory.
Definition controls.cpp:376
libcamera::ControlValue::operator==
bool operator==(const ControlValue &other) const
Compare ControlValue instances for equality.
Definition controls.cpp:300
libcamera::ControlValue::ControlValue
ControlValue()
Construct an empty ControlValue.
Definition controls.cpp:104
libcamera::ControlValue::operator!=
bool operator!=(const ControlValue &other) const
Compare ControlValue instances for non equality.
Definition controls.h:178
libcamera::ControlValue::toString
std::string toString() const
Assemble and return a string describing the value.
Definition controls.cpp:214
libcamera::ControlValue::set
void set(const T &value)
Set the control value to value.
Definition controls.h:227
libcamera::ControlValue::get
T get() const
Get the control value.
Definition controls.h:201
libcamera::ControlValue::type
ControlType type() const
Retrieve the data type of the value.
Definition controls.h:168
libcamera::ControlValue::data
Span< const uint8_t > data() const
Retrieve the raw data of a control value.
Definition controls.cpp:192
libcamera::Control
Describe a control and its intrinsic properties.
Definition controls.h:313
libcamera::Control::Control
Control(unsigned int id, const char *name, const char *vendor, ControlId::DirectionFlags direction, const std::map< std::string, int32_t > &enumStrMap={})
Construct a Control instance.
Definition controls.h:317
libcamera::Control::type
T type
The Control template type T.
Definition controls.h:315
libcamera::Flags
Type-safe container for enum-based bitfields.
Definition flags.h:16
libcamera::Size
Describe a two-dimensional size.
Definition geometry.h:51
flags.h
Enum-based bit fields.
LIBCAMERA_FLAGS_ENABLE_OPERATORS
#define LIBCAMERA_FLAGS_ENABLE_OPERATORS(_enum)
Enable bitwise operations on the enum enumeration.
Definition flags.h:189
geometry.h
Data structures related to geometric objects.
libcamera
Top-level libcamera namespace.
Definition bound_method.h:15
libcamera::ControlType
ControlType
Define the data type of a Control.
Definition controls.h:29
libcamera::ControlTypeUnsigned16
@ ControlTypeUnsigned16
Definition controls.h:33
libcamera::ControlTypeInteger32
@ ControlTypeInteger32
Definition controls.h:35
libcamera::ControlTypeBool
@ ControlTypeBool
Definition controls.h:31
libcamera::ControlTypeString
@ ControlTypeString
Definition controls.h:38
libcamera::ControlTypeUnsigned32
@ ControlTypeUnsigned32
Definition controls.h:34
libcamera::ControlTypeFloat
@ ControlTypeFloat
Definition controls.h:37
libcamera::ControlTypeByte
@ ControlTypeByte
Definition controls.h:32
libcamera::ControlTypeInteger64
@ ControlTypeInteger64
Definition controls.h:36
libcamera::ControlTypeNone
@ ControlTypeNone
Definition controls.h:30
libcamera::ControlIdMap
std::unordered_map< unsigned int, const ControlId * > ControlIdMap
A map of numerical control ID to ControlId.
Definition controls.h:362