libcamera: include/libcamera/controls.h Source File

libcamera v0.0.5 Supporting cameras in Linux since 2019

Loading...
Searching...
No Matches
controls.h
Go to the documentation of this file.
1/* SPDX-License-Identifier: LGPL-2.1-or-later */
2/*
3 * Copyright (C) 2019, Google Inc.
4 *
5 * controls.h - Control handling
6 */
7
8#pragma once
9
10#include <assert.h>
11#include <optional>
12#include <set>
13#include <stdint.h>
14#include <string>
15#include <unordered_map>
16#include <vector>
17
18#include <libcamera/base/class.h>
19#include <libcamera/base/span.h>
20
21#include <libcamera/geometry.h>
22
23namespace libcamera {
24
25class ControlValidator;
26
27 enum ControlType {
28 ControlTypeNone,
29 ControlTypeBool,
30 ControlTypeByte,
31 ControlTypeInteger32,
32 ControlTypeInteger64,
33 ControlTypeFloat,
34 ControlTypeString,
35 ControlTypeRectangle,
36 ControlTypeSize,
37};
38
39namespace details {
40
41template<typename T>
42struct control_type {
43};
44
45template<>
46struct control_type<void> {
47 static constexpr ControlType value = ControlTypeNone;
48};
49
50template<>
51struct control_type<bool> {
52 static constexpr ControlType value = ControlTypeBool;
53};
54
55template<>
56struct control_type<uint8_t> {
57 static constexpr ControlType value = ControlTypeByte;
58};
59
60template<>
61struct control_type<int32_t> {
62 static constexpr ControlType value = ControlTypeInteger32;
63};
64
65template<>
66struct control_type<int64_t> {
67 static constexpr ControlType value = ControlTypeInteger64;
68};
69
70template<>
71struct control_type<float> {
72 static constexpr ControlType value = ControlTypeFloat;
73};
74
75template<>
76struct control_type<std::string> {
77 static constexpr ControlType value = ControlTypeString;
78};
79
80template<>
81struct control_type<Rectangle> {
82 static constexpr ControlType value = ControlTypeRectangle;
83};
84
85template<>
86struct control_type<Size> {
87 static constexpr ControlType value = ControlTypeSize;
88};
89
90template<typename T, std::size_t N>
91struct control_type<Span<T, N>> : public control_type<std::remove_cv_t<T>> {
92};
93
94} /* namespace details */
95
96 class ControlValue
97{
98public:
99 ControlValue();
100
101#ifndef __DOXYGEN__
102 template<typename T, std::enable_if_t<!details::is_span<T>::value &&
103 details::control_type<T>::value &&
104 !std::is_same<std::string, std::remove_cv_t<T>>::value,
105 std::nullptr_t> = nullptr>
106 ControlValue(const T &value)
107 : type_(ControlTypeNone), numElements_(0)
108 {
109 set(details::control_type<std::remove_cv_t<T>>::value, false,
110 &value, 1, sizeof(T));
111 }
112
113 template<typename T, std::enable_if_t<details::is_span<T>::value ||
114 std::is_same<std::string, std::remove_cv_t<T>>::value,
115 std::nullptr_t> = nullptr>
116#else
117 template<typename T>
118#endif
119 ControlValue(const T &value)
120 : type_(ControlTypeNone), numElements_(0)
121 {
122 set(details::control_type<std::remove_cv_t<T>>::value, true,
123 value.data(), value.size(), sizeof(typename T::value_type));
124 }
125
126 ~ControlValue();
127
128 ControlValue(const ControlValue &other);
129 ControlValue &operator=(const ControlValue &other);
130
131 ControlType type() const { return type_; }
132 bool isNone() const { return type_ == ControlTypeNone; }
133 bool isArray() const { return isArray_; }
134 std::size_t numElements() const { return numElements_; }
135 Span<const uint8_t> data() const;
136 Span<uint8_t> data();
137
138 std::string toString() const;
139
140 bool operator==(const ControlValue &other) const;
141 bool operator!=(const ControlValue &other) const
142 {
143 return !(*this == other);
144 }
145
146#ifndef __DOXYGEN__
147 template<typename T, std::enable_if_t<!details::is_span<T>::value &&
148 !std::is_same<std::string, std::remove_cv_t<T>>::value,
149 std::nullptr_t> = nullptr>
150 T get() const
151 {
152 assert(type_ == details::control_type<std::remove_cv_t<T>>::value);
153 assert(!isArray_);
154
155 return *reinterpret_cast<const T *>(data().data());
156 }
157
158 template<typename T, std::enable_if_t<details::is_span<T>::value ||
159 std::is_same<std::string, std::remove_cv_t<T>>::value,
160 std::nullptr_t> = nullptr>
161#else
162 template<typename T>
163#endif
164 T get() const
165 {
166 assert(type_ == details::control_type<std::remove_cv_t<T>>::value);
167 assert(isArray_);
168
169 using V = typename T::value_type;
170 const V *value = reinterpret_cast<const V *>(data().data());
171 return T{ value, numElements_ };
172 }
173
174#ifndef __DOXYGEN__
175 template<typename T, std::enable_if_t<!details::is_span<T>::value &&
176 !std::is_same<std::string, std::remove_cv_t<T>>::value,
177 std::nullptr_t> = nullptr>
178 void set(const T &value)
179 {
180 set(details::control_type<std::remove_cv_t<T>>::value, false,
181 reinterpret_cast<const void *>(&value), 1, sizeof(T));
182 }
183
184 template<typename T, std::enable_if_t<details::is_span<T>::value ||
185 std::is_same<std::string, std::remove_cv_t<T>>::value,
186 std::nullptr_t> = nullptr>
187#else
188 template<typename T>
189#endif
190 void set(const T &value)
191 {
192 set(details::control_type<std::remove_cv_t<T>>::value, true,
193 value.data(), value.size(), sizeof(typename T::value_type));
194 }
195
196 void reserve(ControlType type, bool isArray = false,
197 std::size_t numElements = 1);
198
199private:
200 ControlType type_ : 8;
201 bool isArray_;
202 std::size_t numElements_ : 32;
203 union {
204 uint64_t value_;
205 void *storage_;
206 };
207
208 void release();
209 void set(ControlType type, bool isArray, const void *data,
210 std::size_t numElements, std::size_t elementSize);
211};
212
213 class ControlId
214{
215public:
216 ControlId(unsigned int id, const std::string &name, ControlType type)
217 : id_(id), name_(name), type_(type)
218 {
219 }
220
221 unsigned int id() const { return id_; }
222 const std::string &name() const { return name_; }
223 ControlType type() const { return type_; }
224
225private:
226 LIBCAMERA_DISABLE_COPY_AND_MOVE(ControlId)
227
228 unsigned int id_;
229 std::string name_;
230 ControlType type_;
231};
232
233static inline bool operator==(unsigned int lhs, const ControlId &rhs)
234{
235 return lhs == rhs.id();
236}
237
238static inline bool operator!=(unsigned int lhs, const ControlId &rhs)
239{
240 return !(lhs == rhs);
241}
242
243static inline bool operator==(const ControlId &lhs, unsigned int rhs)
244{
245 return lhs.id() == rhs;
246}
247
248static inline bool operator!=(const ControlId &lhs, unsigned int rhs)
249{
250 return !(lhs == rhs);
251}
252
253template<typename T>
254 class Control : public ControlId
255{
256public:
257 using type = T;
258
259 Control(unsigned int id, const char *name)
260 : ControlId(id, name, details::control_type<std::remove_cv_t<T>>::value)
261 {
262 }
263
264private:
265 LIBCAMERA_DISABLE_COPY_AND_MOVE(Control)
266};
267
268 class ControlInfo
269{
270public:
271 explicit ControlInfo(const ControlValue &min = {},
272 const ControlValue &max = {},
273 const ControlValue &def = {});
274 explicit ControlInfo(Span<const ControlValue> values,
275 const ControlValue &def = {});
276 explicit ControlInfo(std::set<bool> values, bool def);
277 explicit ControlInfo(bool value);
278
279 const ControlValue &min() const { return min_; }
280 const ControlValue &max() const { return max_; }
281 const ControlValue &def() const { return def_; }
282 const std::vector<ControlValue> &values() const { return values_; }
283
284 std::string toString() const;
285
286 bool operator==(const ControlInfo &other) const
287 {
288 return min_ == other.min_ && max_ == other.max_;
289 }
290
291 bool operator!=(const ControlInfo &other) const
292 {
293 return !(*this == other);
294 }
295
296private:
297 ControlValue min_;
298 ControlValue max_;
299 ControlValue def_;
300 std::vector<ControlValue> values_;
301};
302
303 using ControlIdMap = std::unordered_map<unsigned int, const ControlId *>;
304
305 class ControlInfoMap : private std::unordered_map<const ControlId *, ControlInfo>
306{
307public:
308 using Map = std::unordered_map<const ControlId *, ControlInfo>;
309
310 ControlInfoMap() = default;
311 ControlInfoMap(const ControlInfoMap &other) = default;
312 ControlInfoMap(std::initializer_list<Map::value_type> init,
313 const ControlIdMap &idmap);
314 ControlInfoMap(Map &&info, const ControlIdMap &idmap);
315
316 ControlInfoMap &operator=(const ControlInfoMap &other) = default;
317
318 using Map::key_type;
319 using Map::mapped_type;
320 using Map::value_type;
321 using Map::size_type;
322 using Map::iterator;
323 using Map::const_iterator;
324
325 using Map::begin;
326 using Map::cbegin;
327 using Map::end;
328 using Map::cend;
329 using Map::at;
330 using Map::empty;
331 using Map::size;
332 using Map::count;
333 using Map::find;
334
335 mapped_type &at(unsigned int key);
336 const mapped_type &at(unsigned int key) const;
337 size_type count(unsigned int key) const;
338 iterator find(unsigned int key);
339 const_iterator find(unsigned int key) const;
340
341 const ControlIdMap &idmap() const { return *idmap_; }
342
343private:
344 bool validate();
345
346 const ControlIdMap *idmap_ = nullptr;
347};
348
349 class ControlList
350{
351private:
352 using ControlListMap = std::unordered_map<unsigned int, ControlValue>;
353
354public:
355 ControlList();
356 ControlList(const ControlIdMap &idmap, const ControlValidator *validator = nullptr);
357 ControlList(const ControlInfoMap &infoMap, const ControlValidator *validator = nullptr);
358
359 using iterator = ControlListMap::iterator;
360 using const_iterator = ControlListMap::const_iterator;
361
362 iterator begin() { return controls_.begin(); }
363 iterator end() { return controls_.end(); }
364 const_iterator begin() const { return controls_.begin(); }
365 const_iterator end() const { return controls_.end(); }
366
367 bool empty() const { return controls_.empty(); }
368 std::size_t size() const { return controls_.size(); }
369
370 void clear() { controls_.clear(); }
371 void merge(const ControlList &source);
372
373 bool contains(unsigned int id) const;
374
375 template<typename T>
376 std::optional<T> get(const Control<T> &ctrl) const
377 {
378 const auto entry = controls_.find(ctrl.id());
379 if (entry == controls_.end())
380 return std::nullopt;
381
382 const ControlValue &val = entry->second;
383 return val.get<T>();
384 }
385
386 template<typename T, typename V>
387 void set(const Control<T> &ctrl, const V &value)
388 {
389 ControlValue *val = find(ctrl.id());
390 if (!val)
391 return;
392
393 val->set<T>(value);
394 }
395
396 template<typename T, typename V, size_t Size>
397 void set(const Control<Span<T, Size>> &ctrl, const std::initializer_list<V> &value)
398 {
399 ControlValue *val = find(ctrl.id());
400 if (!val)
401 return;
402
403 val->set(Span<const typename std::remove_cv_t<V>, Size>{ value.begin(), value.size() });
404 }
405
406 const ControlValue &get(unsigned int id) const;
407 void set(unsigned int id, const ControlValue &value);
408
409 const ControlInfoMap *infoMap() const { return infoMap_; }
410 const ControlIdMap *idMap() const { return idmap_; }
411
412private:
413 const ControlValue *find(unsigned int id) const;
414 ControlValue *find(unsigned int id);
415
416 const ControlValidator *validator_;
417 const ControlIdMap *idmap_;
418 const ControlInfoMap *infoMap_;
419
420 ControlListMap controls_;
421};
422
423} /* namespace libcamera */
class.h
Utilities to help constructing class interfaces.
LIBCAMERA_DISABLE_COPY_AND_MOVE
#define LIBCAMERA_DISABLE_COPY_AND_MOVE(klass)
Disable copy and move construction and assignment of the klass.
libcamera::ControlId
Control static metadata.
Definition: controls.h:214
libcamera::ControlId::ControlId
ControlId(unsigned int id, const std::string &name, ControlType type)
Construct a ControlId instance.
Definition: controls.h:216
libcamera::ControlId::type
ControlType type() const
Retrieve the control data type.
Definition: controls.h:223
libcamera::ControlId::name
const std::string & name() const
Retrieve the control name.
Definition: controls.h:222
libcamera::ControlId::id
unsigned int id() const
Retrieve the control numerical ID.
Definition: controls.h:221
libcamera::ControlInfoMap
A map of ControlId to ControlInfo.
Definition: controls.h:306
libcamera::ControlInfoMap::at
mapped_type & at(unsigned int key)
Access specified element by numerical ID.
Definition: controls.cpp:723
libcamera::ControlInfoMap::idmap
const ControlIdMap & idmap() const
Retrieve the ControlId map.
Definition: controls.h:341
libcamera::ControlInfoMap::operator=
ControlInfoMap & operator=(const ControlInfoMap &other)=default
Copy assignment operator, replace the contents with a copy of other.
libcamera::ControlInfoMap::Map
std::unordered_map< const ControlId *, ControlInfo > Map
The base std::unsorted_map<> container.
Definition: controls.h:308
libcamera::ControlInfoMap::find
iterator find(unsigned int key)
Find the element matching a numerical ID.
Definition: controls.cpp:766
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:747
libcamera::ControlInfo
Describe the limits of valid values for a Control.
Definition: controls.h:269
libcamera::ControlInfo::values
const std::vector< ControlValue > & values() const
Retrieve the list of valid values.
Definition: controls.h:282
libcamera::ControlInfo::toString
std::string toString() const
Provide a string representation of the ControlInfo.
Definition: controls.cpp:588
libcamera::ControlInfo::operator==
bool operator==(const ControlInfo &other) const
Compare ControlInfo instances for equality.
Definition: controls.h:286
libcamera::ControlInfo::operator!=
bool operator!=(const ControlInfo &other) const
Compare ControlInfo instances for non equality.
Definition: controls.h:291
libcamera::ControlInfo::max
const ControlValue & max() const
Retrieve the maximum value of the control.
Definition: controls.h:280
libcamera::ControlInfo::def
const ControlValue & def() const
Retrieve the default value of the control.
Definition: controls.h:281
libcamera::ControlInfo::min
const ControlValue & min() const
Retrieve the minimum value of the control.
Definition: controls.h:279
libcamera::ControlList
Associate a list of ControlId with their values for an object.
Definition: controls.h:350
libcamera::ControlList::clear
void clear()
Removes all controls from the list.
Definition: controls.h:370
libcamera::ControlList::infoMap
const ControlInfoMap * infoMap() const
Retrieve the ControlInfoMap used to construct the ControlList.
Definition: controls.h:409
libcamera::ControlList::idMap
const ControlIdMap * idMap() const
Retrieve the ControlId map used to construct the ControlList.
Definition: controls.h:410
libcamera::ControlList::set
void set(const Control< Span< T, Size > > &ctrl, const std::initializer_list< V > &value)
Definition: controls.h:397
libcamera::ControlList::const_iterator
ControlListMap::const_iterator const_iterator
Const iterator for the controls contained within the list.
Definition: controls.h:360
libcamera::ControlList::end
iterator end()
Retrieve an iterator pointing to the past-the-end control in the list.
Definition: controls.h:363
libcamera::ControlList::size
std::size_t size() const
Retrieve the number of controls in the list.
Definition: controls.h:368
libcamera::ControlList::iterator
ControlListMap::iterator iterator
Iterator for the controls contained within the list.
Definition: controls.h:359
libcamera::ControlList::get
std::optional< T > get(const Control< T > &ctrl) const
Get the value of control ctrl.
Definition: controls.h:376
libcamera::ControlList::empty
bool empty() const
Identify if the list is empty.
Definition: controls.h:367
libcamera::ControlList::set
void set(const Control< T > &ctrl, const V &value)
Set the control ctrl value to value.
Definition: controls.h:387
libcamera::ControlList::begin
iterator begin()
Retrieve an iterator to the first Control in the list.
Definition: controls.h:362
libcamera::ControlList::contains
bool contains(unsigned int id) const
Check if the list contains a control with the specified id.
Definition: controls.cpp:956
libcamera::ControlList::begin
const_iterator begin() const
Retrieve a const_iterator to the first Control in the list.
Definition: controls.h:364
libcamera::ControlList::ControlList
ControlList()
Construct a ControlList not associated with any object.
Definition: controls.cpp:826
libcamera::ControlList::end
const_iterator end() const
Retrieve a const iterator pointing to the past-the-end control in the list.
Definition: controls.h:365
libcamera::ControlList::merge
void merge(const ControlList &source)
Merge the source into the ControlList.
Definition: controls.cpp:924
libcamera::ControlValidator
Interface for the control validator.
Definition: control_validator.h:17
libcamera::ControlValue
Abstract type representing the value of a control.
Definition: controls.h:97
libcamera::ControlValue::get
T get() const
Get the control value.
Definition: controls.h:164
libcamera::ControlValue::isArray
bool isArray() const
Determine if the value stores an array.
Definition: controls.h:133
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:146
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:355
libcamera::ControlValue::operator==
bool operator==(const ControlValue &other) const
Compare ControlValue instances for equality.
Definition: controls.cpp:279
libcamera::ControlValue::set
void set(const T &value)
Set the control value to value.
Definition: controls.h:190
libcamera::ControlValue::ControlValue
ControlValue()
Construct an empty ControlValue.
Definition: controls.cpp:98
libcamera::ControlValue::operator!=
bool operator!=(const ControlValue &other) const
Compare ControlValue instances for non equality.
Definition: controls.h:141
libcamera::ControlValue::ControlValue
ControlValue(const T &value)
Construct a ControlValue of type T.
Definition: controls.h:119
libcamera::ControlValue::type
ControlType type() const
Retrieve the data type of the value.
Definition: controls.h:131
libcamera::ControlValue::toString
std::string toString() const
Assemble and return a string describing the value.
Definition: controls.cpp:208
libcamera::ControlValue::isNone
bool isNone() const
Determine if the value is not initialised.
Definition: controls.h:132
libcamera::ControlValue::numElements
std::size_t numElements() const
Retrieve the number of elements stored in the ControlValue.
Definition: controls.h:134
libcamera::ControlValue::data
Span< const uint8_t > data() const
Retrieve the raw data of a control value.
Definition: controls.cpp:186
libcamera::Control
Describe a control and its intrinsic properties.
Definition: controls.h:255
libcamera::Control::type
T type
The Control template type T.
Definition: controls.h:257
libcamera::Control::Control
Control(unsigned int id, const char *name)
Construct a Control instance.
Definition: controls.h:259
libcamera::Size
Describe a two-dimensional size.
Definition: geometry.h:53
geometry.h
Data structures related to geometric objects.
libcamera
Top-level libcamera namespace.
Definition: backtrace.h:17
libcamera::ControlType
ControlType
Define the data type of a Control.
Definition: controls.h:27
libcamera::ControlTypeNone
@ ControlTypeNone
Definition: controls.h:28
libcamera::ControlTypeFloat
@ ControlTypeFloat
Definition: controls.h:33
libcamera::ControlTypeBool
@ ControlTypeBool
Definition: controls.h:29
libcamera::ControlTypeInteger32
@ ControlTypeInteger32
Definition: controls.h:31
libcamera::ControlTypeString
@ ControlTypeString
Definition: controls.h:34
libcamera::ControlTypeInteger64
@ ControlTypeInteger64
Definition: controls.h:32
libcamera::ControlTypeByte
@ ControlTypeByte
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:303
libcamera::operator==
bool operator==(const ColorSpace &lhs, const ColorSpace &rhs)
Compare color spaces for equality.
Definition: color_space.cpp:506