MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
ControlValueStore.hpp
Go to the documentation of this file.
1#pragma once
2
4
5namespace MayaFlux {
6
7/**
8 * @concept ControlSlot
9 * @brief What ControlValueStore needs of the slot type it owns.
10 *
11 * A slot reports has_value, takes another slot's state with assign, can be
12 * settled and refreshed from a source. ControlValue, ControlSnapshot and
13 * anything derived from them qualify.
14 */
15template <typename S>
16concept ControlSlot = requires(S slot, const S& other) {
17 { slot.has_value() } -> std::convertible_to<bool>;
18 slot.assign(other);
19 slot.refresh();
20 slot.settle();
21};
22
23/**
24 * @concept NumericControlSlot
25 * @brief A ControlSlot that also reads as a number, which the named access and the scale mirror need.
26 *
27 * It reports width, reads as a double, hands out a pending value once per
28 * change, is shown the owner's real value with observe, and is made from a
29 * number. ControlValue and anything derived from it qualify.
30 */
31template <typename S>
32concept NumericControlSlot = ControlSlot<S> && requires(S slot, double number) {
33 { slot.width() } -> std::convertible_to<size_t>;
34 { slot.value() } -> std::convertible_to<double>;
35 { slot.pending() } -> std::same_as<std::optional<double>>;
36 slot.observe(number);
37 S(number);
38};
39
40/**
41 * @class ControlValueStore
42 * @brief Owns one described struct of Slot members for a host such as a network, an operator or an input node.
43 *
44 * A host holds one as a member and forwards to it. It is not a base class.
45 * declare() creates the struct and keeps it for the host's lifetime, merge()
46 * applies the members an incoming struct holds, snapshot() copies the struct for
47 * get(), and refresh() reads sources once per block. A member named `scale` is
48 * mirrored to a value the host passes in, and a host with no scale passes nothing.
49 * Every member is a Slot or a described struct of the same, nested to any depth.
50 *
51 * A member is also reachable by name through set_named() and read_named(), which
52 * back an operator's string based set_parameter and query_state. A member of a
53 * nested struct is named by its path joined with dots, such as `left.deadzone`.
54 * Only a top level member named `scale` is mirrored. Named number access and the
55 * scale mirror need a NumericControlSlot.
56 *
57 * @tparam Slot A ControlSlot, the one slot type of every member.
58 */
59template <ControlSlot Slot>
61public:
62 ControlValueStore() = default;
63 ~ControlValueStore() = default;
64
69
70 /** @brief Creates the struct and returns it, for the host to hold by reference. */
71 template <typename C>
72 [[nodiscard]] C& declare()
73 {
74 auto storage = std::make_shared<C>();
75 C& controls = *storage;
76
77 m_storage = std::move(storage);
78 m_tag = tag<C>();
79 m_slots.clear();
80 m_scale = nullptr;
81
82 add_members(controls, std::string());
83
84 return controls;
85 }
86
87 /** @brief Applies every member of @p incoming that holds a value. */
88 template <typename C>
89 void merge(const C& incoming)
90 {
91 if (m_tag != tag<C>()) {
92 return;
93 }
94
95 merge_members(*static_cast<C*>(m_storage.get()), incoming);
96 }
97
98 /**
99 * @brief A copy of the struct.
100 * @param scale The value a top level member named `scale` really holds, or null.
101 */
102 template <typename C>
103 [[nodiscard]] C snapshot(const double* scale = nullptr) const
104 {
105 C current = m_tag == tag<C>()
106 ? *static_cast<const C*>(m_storage.get())
107 : C {};
108 if (scale) {
109 std::apply(
110 [&](const auto&... member) {
111 (observe_scale(member, current, *scale), ...);
112 },
114 }
115 return current;
116 }
117
118 /**
119 * @brief Reads sources into their slots.
120 * @param scale Where a member named `scale` is written when it is due, or null.
121 */
122 void refresh(double* scale = nullptr)
123 {
124 for (const Entry& entry : m_slots) {
125 entry.slot->refresh();
126 }
127
128 if constexpr (NumericControlSlot<Slot>) {
129 if (scale && m_scale) {
130 if (const auto due = m_scale->pending()) {
131 *scale = std::max(0.0, *due);
132 }
133 }
134 }
135 }
136
137 /**
138 * @brief Sets the member called @p name to the number @p value.
139 * @return False when no member has that name.
140 *
141 * The same as set() with that one member, so it applies at the next block.
142 * A member that holds a vector is left alone, so a number cannot retype it.
143 */
144 bool set_named(std::string_view name, double value)
146 {
147 for (const Entry& entry : m_slots) {
148 if (entry.name == name) {
149 if (entry.slot->width() > 1) {
150 return false;
151 }
152 entry.slot->assign(Slot(value));
153 return true;
154 }
155 }
156 return false;
157 }
158
159 /**
160 * @brief Drops the pending value of the member called @p name.
161 * @return False when no member has that name.
162 *
163 * For an immediate write made by name: a typed value set earlier would
164 * otherwise be applied at the next block over it.
165 */
166 bool settle_named(std::string_view name)
167 {
168 for (const Entry& entry : m_slots) {
169 if (entry.name == name) {
170 entry.slot->settle();
171 return true;
172 }
173 }
174 return false;
175 }
176
177 /**
178 * @brief The number held by the member called @p name, or nullopt for none or a vector.
179 * @param controls A copy from get(), so values the owner holds outside the struct are real.
180 */
181 template <typename C>
183 [[nodiscard]] static std::optional<double> read_named(const C& controls, std::string_view name)
184 {
185 std::optional<double> found;
186 std::apply(
187 [&](const auto&... member) {
188 (read_member(member, controls, name, found), ...);
189 },
191 return found;
192 }
193
194private:
195 struct Entry {
196 std::string name;
197 Slot* slot {};
198 };
199
200 template <typename C>
201 [[nodiscard]] static const void* tag() noexcept
202 {
203 static constexpr char value = 0;
204 return &value;
205 }
206
207 template <typename C>
208 void add_members(C& owner, const std::string& prefix)
209 {
210 std::apply(
211 [&](const auto&... member) {
212 (add_member(member, owner, prefix), ...);
213 },
215 }
216
217 template <typename Member, typename C>
218 void add_member(const Member& member, C& owner, const std::string& prefix)
219 {
220 using Value = typename Member::value_type;
221 auto& value = member.get(owner);
222 if constexpr (std::same_as<Value, Slot>) {
223 m_slots.push_back({ prefix + std::string(member.name), &value });
224 if constexpr (NumericControlSlot<Slot>) {
225 if (prefix.empty() && member.name == "scale") {
226 m_scale = &value;
227 }
228 }
229 } else {
230 static_assert(Reflect::Described<Value>,
231 "every member of a controls struct must be the store's slot type or a described struct of them");
232 add_members(value, prefix + std::string(member.name) + ".");
233 }
234 }
235
236 template <typename C>
237 static void merge_members(C& live, const C& incoming)
238 {
239 std::apply(
240 [&](const auto&... member) {
241 (merge_member(member, live, incoming), ...);
242 },
244 }
245
246 template <typename Member, typename C>
247 static void merge_member(const Member& member, C& live, const C& incoming)
248 {
249 using Value = typename Member::value_type;
250 if constexpr (std::same_as<Value, Slot>) {
251 const Slot& given = member.get(incoming);
252 if (given.has_value()) {
253 member.get(live).assign(given);
254 }
255 } else {
256 merge_members(member.get(live), member.get(incoming));
257 }
258 }
259
260 template <typename Member, typename C>
261 static void observe_scale(const Member& member, C& current, double scale)
262 {
263 if constexpr (NumericControlSlot<Slot> && std::same_as<typename Member::value_type, Slot>) {
264 if (member.name == "scale") {
265 member.get(current).observe(scale);
266 }
267 }
268 }
269
270 template <typename Member, typename C>
271 static void read_member(const Member& member, const C& owner, std::string_view name,
272 std::optional<double>& found)
273 {
274 const auto& value = member.get(owner);
275 if constexpr (std::same_as<typename Member::value_type, Slot>) {
276 if (member.name == name && value.has_value() && value.width() == 1) {
277 found = value.value();
278 }
279 } else if (name.size() > member.name.size() && name.starts_with(member.name)
280 && name[member.name.size()] == '.') {
281 if (const auto inner = read_named(value, name.substr(member.name.size() + 1))) {
282 found = inner;
283 }
284 }
285 }
286
287 std::shared_ptr<void> m_storage;
288 const void* m_tag = nullptr;
289 std::vector<Entry> m_slots;
290 Slot* m_scale = nullptr;
291};
292
293/**
294 * @class ControlValueTable
295 * @brief One ControlValueStore per key, for a host with a runtime count of tunable groups.
296 *
297 * Each key owns its own store and so its own described struct, for example one
298 * per control of a device. declare() creates or replaces the store of a key, and
299 * the store is then used through find(). Adding or removing a key belongs
300 * outside the block that reads the stores, as with any source change.
301 *
302 * @tparam Key An ordered key type.
303 * @tparam Slot A ControlSlot, the slot type of every store.
304 */
305template <typename Key, ControlSlot Slot>
307public:
309
310 /** @brief Creates the store of @p key, replacing any it had, and returns its struct. */
311 template <typename C>
312 [[nodiscard]] C& declare(const Key& key)
313 {
314 auto& store = m_stores[key];
315 store = std::make_unique<Store>();
316 return store->template declare<C>();
317 }
318
319 /** @brief The store of @p key, or null when it has none. */
320 [[nodiscard]] Store* find(const Key& key) noexcept
321 {
322 const auto found = m_stores.find(key);
323 return found == m_stores.end() ? nullptr : found->second.get();
324 }
325
326 [[nodiscard]] const Store* find(const Key& key) const noexcept
327 {
328 const auto found = m_stores.find(key);
329 return found == m_stores.end() ? nullptr : found->second.get();
330 }
331
332 /** @brief Drops the store of @p key. @return False when it had none. */
333 bool erase(const Key& key) { return m_stores.erase(key) != 0; }
334
335 [[nodiscard]] size_t size() const noexcept { return m_stores.size(); }
336
337 /** @brief Reads the sources of every store. */
338 void refresh()
339 {
340 for (const auto& entry : m_stores) {
341 entry.second->refresh();
342 }
343 }
344
345 /** @brief Calls visit(key, store) for every store in key order. */
346 template <typename Visit>
347 void for_each(const Visit& visit)
348 {
349 for (const auto& entry : m_stores) {
350 visit(entry.first, *entry.second);
351 }
352 }
353
354private:
355 std::map<Key, std::unique_ptr<Store>> m_stores;
356};
357
358}
bool settle_named(std::string_view name)
Drops the pending value of the member called name.
bool set_named(std::string_view name, double value)
Sets the member called name to the number value.
ControlValueStore & operator=(ControlValueStore &&)=delete
ControlValueStore & operator=(const ControlValueStore &)=delete
static std::optional< double > read_named(const C &controls, std::string_view name)
The number held by the member called name, or nullopt for none or a vector.
static void read_member(const Member &member, const C &owner, std::string_view name, std::optional< double > &found)
static const void * tag() noexcept
C & declare()
Creates the struct and returns it, for the host to hold by reference.
static void observe_scale(const Member &member, C &current, double scale)
ControlValueStore(ControlValueStore &&)=delete
static void merge_member(const Member &member, C &live, const C &incoming)
C snapshot(const double *scale=nullptr) const
A copy of the struct.
static void merge_members(C &live, const C &incoming)
void refresh(double *scale=nullptr)
Reads sources into their slots.
void add_members(C &owner, const std::string &prefix)
ControlValueStore(const ControlValueStore &)=delete
void add_member(const Member &member, C &owner, const std::string &prefix)
void merge(const C &incoming)
Applies every member of incoming that holds a value.
Owns one described struct of Slot members for a host such as a network, an operator or an input node.
const Store * find(const Key &key) const noexcept
size_t size() const noexcept
ControlValueStore< Slot > Store
void for_each(const Visit &visit)
Calls visit(key, store) for every store in key order.
std::map< Key, std::unique_ptr< Store > > m_stores
bool erase(const Key &key)
Drops the store of key.
C & declare(const Key &key)
Creates the store of key, replacing any it had, and returns its struct.
void refresh()
Reads the sources of every store.
Store * find(const Key &key) noexcept
The store of key, or null when it has none.
One ControlValueStore per key, for a host with a runtime count of tunable groups.
What ControlValueStore needs of the slot type it owns.
A ControlSlot that also reads as a number, which the named access and the scale mirror need.
A type whose generated sidecar defines Generated::Description<T>::members().
Definition Describe.hpp:86
std::shared_ptr< T > store(std::shared_ptr< T > obj)
Transfer ownership of an existing object to the persistent store for process lifetime.
Definition Persist.hpp:28
Main namespace for the Maya Flux audio engine.