MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
Control.hpp
Go to the documentation of this file.
1#pragma once
2
6
8
9class NodeNetwork;
10
11/**
12 * @class Control
13 * @brief One named control of a network or operator: empty, a value, or a mapped source.
14 *
15 * A Control converts implicitly from a number, a bool, an enum, a glm::vec2,
16 * glm::vec3 or glm::vec4, from a box (a struct of exactly a glm::vec3 `min` and
17 * a glm::vec3 `max`, such as Kinesis::SamplerBounds or Kinesis::AABB3D), from a node (BROADCAST) and from a network
18 * (ONE_TO_ONE), so a controls struct reads as designated initializers:
19 * `net->set({ .decay = 0.6, .amplitude = bell })` or
20 * `op->set({ .gravity = glm::vec3(0, -9.8, 0) })`. An empty Control means
21 * "leave this alone". Setting a value replaces any source held before it.
22 * The owner reads it back as the type it declared: `pending()` and `value()`
23 * give a double, and `pending<glm::vec3>()`, `pending<BoundsMode>()` and so on
24 * give that type. A read of another type than was set finds nothing.
25 *
26 * A value may be set from any thread while a block renders. Numbers are atomic,
27 * and a vector is written and read under a sequence lock, so it is never seen
28 * half written. A value is never lost to a race, only possibly applied twice
29 * with the same content. A Control holds one pending value, so a later value
30 * replaces one that no block has applied yet. Integers are carried exactly up to 2^53. Attaching, replacing
31 * or removing a node or network source belongs outside the block, as with the
32 * operator chain. A consumer calls settle() before it reads the value.
33 */
34class Control : public ControlValue {
35public:
36 Control() = default;
37
38 template <typename T>
39 requires is_value<T>
40 Control(T value) noexcept
42 {
43 }
44
45 template <typename Source>
46 requires std::derived_from<Source, Node>
47 Control(std::shared_ptr<Source> source)
48 : m_node(std::move(source))
49 {
50 set_blank();
51 }
52
53 template <typename Source>
54 requires std::derived_from<Source, NodeNetwork>
55 Control(std::shared_ptr<Source> source)
56 : m_network(std::move(source))
57 {
58 set_blank();
59 }
60
61 Control(const Control&) = default;
62 Control(Control&&) noexcept = default;
63 Control& operator=(const Control&) = default;
64 Control& operator=(Control&&) noexcept = default;
65 ~Control() = default;
66
67 /** @brief True when a node or a network feeds this control. */
68 [[nodiscard]] bool sourced() const noexcept { return m_node || m_network; }
69
70 /** @brief True when a network feeds one value per element. */
71 [[nodiscard]] bool per_element() const noexcept { return static_cast<bool>(m_network); }
72
73 /** @brief Node count of the source network, or 0 without one. */
74 [[nodiscard]] size_t element_count() const;
75
76 /** @brief Value for one element: the network's output there, else the scalar. */
77 [[nodiscard]] std::optional<double> at(size_t index) const;
78
79 /** @brief True when a consumer should apply this control now. */
80 [[nodiscard]] bool due() const noexcept
81 {
82 return has_value() && (sourced() || changed());
83 }
84
85 /**
86 * @brief The value to apply now as type T, or nullopt when nothing is due.
87 *
88 * A value is returned once per change, a node source every call. A network
89 * source is per element and is never returned here; read it with at(). A
90 * control set with another type than T returns nothing.
91 */
92 template <typename T = double>
93 requires is_value<T>
94 [[nodiscard]] std::optional<T> pending() noexcept
95 {
96 if (m_network) {
97 return std::nullopt;
98 }
99 if (m_node) {
100 if (!has_value() || width() != width_of<T>()) {
101 return std::nullopt;
102 }
103 return value<T>();
104 }
106 }
107
108 /** @brief Reads the node source into value(). Networks call this once per block. */
109 void refresh()
110 {
111 if (m_node) {
112 set_scalar(m_node->get_last_output());
113 }
114 }
115
116 /**
117 * @brief Takes everything @p incoming holds, so the next due() is true.
118 *
119 * Between two values this is safe from any thread. When either side holds
120 * a source it replaces the source pointers, which belongs outside the block.
121 */
122 void assign(const Control& incoming)
123 {
124 if (sourced() || incoming.sourced()) {
125 m_node = incoming.m_node;
126 m_network = incoming.m_network;
127 }
128 ControlValue::assign(incoming);
129 }
130
131 /** @brief Shows the value the owner really has, unless a source is feeding it. */
132 template <typename T>
133 requires is_value<T>
134 void observe(T actual) noexcept
135 {
136 if (!sourced()) {
137 ControlValue::observe(actual);
138 }
139 }
140
141private:
142 std::shared_ptr<Node> m_node;
143 std::shared_ptr<NodeNetwork> m_network;
144};
145
146/**
147 * @brief The store of Control members for a NodeNetwork or a NetworkOperator.
148 *
149 * See ControlValueStore. Every member of the declared struct is a Control or a described struct of them.
150 */
152
153}
Owns one described struct of Slot members for a host such as a network, an operator or an input node.
bool has_value() const noexcept
True once a value was given.
static constexpr uint8_t width_of() noexcept
double value() const noexcept
The value as a double.
bool changed() const noexcept
void set_scalar(double value) noexcept
void set_blank() noexcept
Marks the slot set with one zero lane and leaves it clean.
static constexpr bool is_value
size_t width() const noexcept
Components held: 0 when empty, 1 for a number, flag or enum, 2 to 4 for a vector, 6 for a box.
void observe(T actual) noexcept
Shows the value the owner really has.
void assign(const ControlValue &incoming) noexcept
Takes everything incoming holds, so the next due() is true.
std::optional< T > pending() noexcept
The value to apply now as type T, or nullopt when nothing is due.
std::optional< T > pending() noexcept
The value to apply now as type T, or nullopt when nothing is due.
Definition Control.hpp:94
std::shared_ptr< Node > m_node
Definition Control.hpp:142
void observe(T actual) noexcept
Shows the value the owner really has, unless a source is feeding it.
Definition Control.hpp:134
void refresh()
Reads the node source into value().
Definition Control.hpp:109
Control(std::shared_ptr< Source > source)
Definition Control.hpp:55
Control(Control &&) noexcept=default
Control(std::shared_ptr< Source > source)
Definition Control.hpp:47
bool sourced() const noexcept
True when a node or a network feeds this control.
Definition Control.hpp:68
std::optional< double > at(size_t index) const
Value for one element: the network's output there, else the scalar.
Control(const Control &)=default
bool per_element() const noexcept
True when a network feeds one value per element.
Definition Control.hpp:71
size_t element_count() const
Node count of the source network, or 0 without one.
bool due() const noexcept
True when a consumer should apply this control now.
Definition Control.hpp:80
std::shared_ptr< NodeNetwork > m_network
Definition Control.hpp:143
void assign(const Control &incoming)
Takes everything incoming holds, so the next due() is true.
Definition Control.hpp:122
Abstract base class for structured collections of nodes with defined relationships.
ControlValueStore< Control > ControlStore
The store of Control members for a NodeNetwork or a NetworkOperator.
Definition Control.hpp:151