MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
DuctNetwork.hpp
Go to the documentation of this file.
1#pragma once
2
3#include "NodeNetwork.hpp"
4
8
10
11/**
12 * @struct DuctControls
13 * @brief Controls of a DuctNetwork, each a number or a mapped node.
14 *
15 * Every member but scale, pickup and output is offered to both terminations,
16 * as the string names of the same spelling always were. A termination that does not know a
17 * name ignores it. A network source is not used by any of them.
18 */
20 Control scale; ///< Output scale
21 Control pickup; ///< Pickup position, 0 to 1 along the duct
22 Control pressure; ///< Reed blowing pressure
23 Control smoothing; ///< Reed pressure smoothing
24 Control resonance; ///< Reed resonance
25 Control reed_damping; ///< Reed damping
26 Control noise; ///< Reed breath noise
27 Control noise_cutoff; ///< Reed breath noise cutoff
28 Control reed_area; ///< Reed area
29 Control lip; ///< Lip pressure on the reed
30 Control closing_pressure; ///< Reed closing pressure
31 Control opening; ///< Reed rest opening
32 Control width; ///< Reed width
33 Control driving_pressure; ///< Junction driving pressure
34 Control maximum_flow; ///< Junction maximum flow
35 Control output; ///< Above one half the output is the pickup pressure, not the radiated one
36};
37
39
40/**
41 * @class DuctNetwork
42 * @brief A one dimensional acoustic duct of any bore shape, solved by finite
43 * differences, with a termination at each end.
44 *
45 * Pressure and volume velocity sit on an interleaved grid along the duct, one
46 * sample per step, with the cross section read from a radius profile. A
47 * cylinder, a cone and any other shape differ only in the profile. Each end is
48 * a TerminationOperator: by default a ReedOperator at the mouth, so the duct
49 * sounds when blown, and a RadiationOperator at the bell, so it radiates. A
50 * WallOperator closes an end, and a JunctionOperator takes any pressure
51 * dependent flow.
52 *
53 * ```cpp
54 * auto duct = std::make_shared<DuctNetwork>(0.6, 0.0075) | Audio[0];
55 * duct->map_parameter("pressure", breath);
56 * duct->set_output_scale(100.0);
57 * ```
58 *
59 * The output is the pressure radiated at one metre in pascals, or the
60 * pressure at a pickup position. Pascals are small as audio, so scale it with
61 * set_output_scale.
62 *
63 * Mapped parameters (BROADCAST): "pickup" (0 to 1 along the duct), "scale",
64 * and anything else is offered to both terminations, so "pressure",
65 * "closing_pressure" and "opening" reach the reed.
66 *
67 * Changing the length, the profile or a termination builds the new grid on the
68 * calling thread and installs it at a block boundary without waiting, so none
69 * of that touches the audio path. The state restarts from rest when it is
70 * installed. These calls come from one thread at a time, not from the audio
71 * thread, and return false, leaving the duct as it was, when the new grid or a
72 * termination cannot be built.
73 *
74 * The sample rate is fixed at construction and sets the grid.
75 */
76class MAYAFLUX_API DuctNetwork final : public NodeNetwork {
77public:
79
80 /** @brief What the network publishes. */
81 enum class Output : uint8_t {
82 RADIATED, ///< Pressure radiated at one metre, from the flow out of the bell
83 PICKUP ///< Pressure inside the duct at the pickup position
84 };
85
86 /**
87 * @brief A cylinder.
88 * @param length Length in metres
89 * @param radius Radius in metres
90 * @param sample_rate Sample rate in Hz
91 */
92 DuctNetwork(double length, double radius, double sample_rate = 48000.0);
93
94 /**
95 * @brief A duct from radii sampled evenly along its length.
96 * @param length Length in metres
97 * @param radii At least two radii in metres, from the mouth to the bell
98 * @param sample_rate Sample rate in Hz
99 */
100 DuctNetwork(double length, const std::vector<double>& radii, double sample_rate = 48000.0);
101
102 /**
103 * @brief A duct from a radius function.
104 * @param length Length in metres
105 * @param radius Callable giving the radius in metres at a distance in
106 * metres from the mouth
107 * @param sample_rate Sample rate in Hz
108 */
109 DuctNetwork(double length, std::function<double(double)> radius, double sample_rate = 48000.0);
110
111 ~DuctNetwork() override;
112
113 DuctNetwork(const DuctNetwork&) = delete;
117
118 //-------------------------------------------------------------------------
119 // NodeNetwork Interface
120 //-------------------------------------------------------------------------
121
122 void process_batch(unsigned int num_samples) override;
123
124 /** @brief Number of pressure points along the duct. */
125 [[nodiscard]] size_t get_node_count() const override { return m_field_points.load(std::memory_order_relaxed); }
126
127 void initialize() override;
128
129 /** @brief Return the duct to rest, installed at the next block. */
130 void reset() override;
131
132 /** @brief Pressure at one point along the duct, from the last block. */
133 [[nodiscard]] std::optional<double> get_node_output(size_t index) const override;
134 [[nodiscard]] std::optional<std::span<const double>> get_node_audio_buffer(size_t index) const override;
135 [[nodiscard]] std::unordered_map<std::string, std::string> get_metadata() const override;
136
137 void map_parameter(const std::string& param_name,
138 const std::shared_ptr<Node>& source,
139 MappingMode mode = MappingMode::BROADCAST) override;
140
141 void map_parameter(const std::string& param_name,
142 const std::shared_ptr<NodeNetwork>& source) override;
143
144 void unmap_parameter(const std::string& param_name) override;
145
146 //-------------------------------------------------------------------------
147 // Shape
148 //-------------------------------------------------------------------------
149
150 /** @brief Change the length in metres, keeping the profile. */
151 [[nodiscard]] bool set_length(double length);
152
153 /** @brief Make the duct a cylinder of this radius in metres. */
154 [[nodiscard]] bool set_radius(double radius);
155
156 /** @brief Replace the profile with radii sampled evenly from mouth to bell. */
157 [[nodiscard]] bool set_profile(const std::vector<double>& radii);
158
159 /** @brief Replace the profile with a radius function of distance from the mouth. */
160 [[nodiscard]] bool set_profile(std::function<double(double)> radius);
161
162 /**
163 * @brief Add air behind the mouth end, in cubic metres.
164 * @return False, changing nothing, for a volume that is negative or not finite
165 *
166 * A mouthpiece cavity, or the tip a truncated cone lacks: pi r^2 x / 3 for
167 * apex radius r and distance x to the apex. It lets a cone keep its whole
168 * number series of modes.
169 */
170 [[nodiscard]] bool set_mouth_volume(double volume);
171
172 //-------------------------------------------------------------------------
173 // Wall losses
174 //-------------------------------------------------------------------------
175
176 /**
177 * @brief Set the wall losses by hand.
178 * @param friction Friction in 1/s, not negative
179 * @param viscosity Viscosity in m^2/s, not negative
180 * @return False, changing nothing, for a rate that is negative or not finite
181 *
182 * Zero for both gives the lossless duct. The default is
183 * use_viscothermal_losses.
184 */
185 [[nodiscard]] bool set_wall_losses(double friction, double viscosity);
186
187 /**
188 * @brief Take the wall losses from the duct's mean radius, fitted to the
189 * viscothermal attenuation of a tube at 150 Hz and 3 kHz.
190 */
191 [[nodiscard]] bool use_viscothermal_losses();
192
193 //-------------------------------------------------------------------------
194 // Terminations
195 //-------------------------------------------------------------------------
196
197 /**
198 * @brief Replace the termination at the mouth.
199 * @return False, changing nothing, when it cannot terminate this duct
200 */
201 [[nodiscard]] bool set_mouth(std::shared_ptr<TerminationOperator> termination);
202
203 /** @brief Replace the termination at the bell. */
204 [[nodiscard]] bool set_bell(std::shared_ptr<TerminationOperator> termination);
205
206 [[nodiscard]] std::shared_ptr<TerminationOperator> get_mouth() const;
207 [[nodiscard]] std::shared_ptr<TerminationOperator> get_bell() const;
208
209 /** @brief Fills the controls whose value the network holds outside the struct. */
210 void read_controls(DuctControls& controls) const
211 {
212 controls.pickup.observe(m_pickup.load(std::memory_order_relaxed));
213 controls.output.observe(m_output.load(std::memory_order_relaxed) == Output::PICKUP ? 1.0 : 0.0);
214 }
215
216 /** @brief Copy of the pressures along the duct from the last block. */
217 [[nodiscard]] std::vector<double> pressure_field() const;
218
219private:
221
222 struct Prepared;
223
224 struct Profile {
225 std::vector<double> radii;
226 std::function<double(double)> function;
227 };
228
229 struct Losses {
230 bool automatic { true };
231 double friction {};
232 double viscosity {};
233 };
234
235 void setup(double length, Profile profile, double sample_rate);
236
237 [[nodiscard]] std::shared_ptr<Prepared> build(
238 double length,
239 const Profile& profile,
240 const Losses& losses,
241 double mouth_volume,
242 const std::shared_ptr<TerminationOperator>& mouth,
243 const std::shared_ptr<TerminationOperator>& bell) const;
244
245 void publish(std::shared_ptr<Prepared> next);
246 void install_pending();
247 void bind(Prepared& prepared, bool keep);
248 void update_mapped_parameters();
249 void apply_controls();
250 void apply_pickup_position(double position);
251 void publish_block(std::span<const double> block);
252
253 mutable std::mutex m_producer_mutex;
254 double m_length {};
255 double m_rate {};
258 double m_mouth_volume {};
261 std::shared_ptr<TerminationOperator> m_mouth;
262 std::shared_ptr<TerminationOperator> m_bell;
263 size_t m_intervals {};
264 double m_courant {};
265 double m_bandwidth {};
266
267 std::shared_ptr<Prepared> m_active;
268 std::shared_ptr<Prepared> m_slot;
269 std::atomic<uint8_t> m_handoff { 0 };
270
271 std::atomic<Output> m_output { Output::RADIATED };
272 std::atomic<double> m_pickup { 0.5 };
273 std::atomic<size_t> m_field_points { 0 };
274
275 std::vector<double> m_scratch;
276 std::vector<double> m_field;
278 double m_last_output {};
279};
280
281} // namespace MayaFlux::Nodes::Network
#define MF_DESCRIBE(...)
Requests a generated member description for a struct at namespace scope.
Definition Describe.hpp:14
Interleaved grid of a one dimensional acoustic bore.
Wall losses of a duct as friction and viscosity on the volume velocity.
void observe(T actual) noexcept
Shows the value the owner really has, unless a source is feeding it.
Definition Control.hpp:134
One named control of a network or operator: empty, a value, or a mapped source.
Definition Control.hpp:34
std::shared_ptr< TerminationOperator > m_mouth
size_t get_node_count() const override
Number of pressure points along the duct.
std::shared_ptr< Prepared > m_slot
DuctNetwork(double length, double radius, double sample_rate=48000.0)
A cylinder.
std::shared_ptr< Prepared > m_active
Output
What the network publishes.
@ PICKUP
Pressure inside the duct at the pickup position.
@ RADIATED
Pressure radiated at one metre, from the flow out of the bell.
void process_batch(unsigned int num_samples) override
Process the network for the given number of samples.
std::shared_ptr< TerminationOperator > m_bell
void read_controls(DuctControls &controls) const
Fills the controls whose value the network holds outside the struct.
DuctNetwork & operator=(const DuctNetwork &)=delete
DuctNetwork & operator=(DuctNetwork &&)=delete
DuctNetwork(DuctNetwork &&)=delete
DuctNetwork(const DuctNetwork &)=delete
A one dimensional acoustic duct of any bore shape, solved by finite differences, with a termination a...
Abstract base class for structured collections of nodes with defined relationships.
void initialize()
Definition main.cpp:10
MappingMode
How one source maps to a network's elements.
@ BROADCAST
One source value applies to every network element.
Control pickup
Pickup position, 0 to 1 along the duct.
Control noise_cutoff
Reed breath noise cutoff.
Control driving_pressure
Junction driving pressure.
Control output
Above one half the output is the pickup pressure, not the radiated one.
Control maximum_flow
Junction maximum flow.
Control lip
Lip pressure on the reed.
Control pressure
Reed blowing pressure.
Control closing_pressure
Reed closing pressure.
Control smoothing
Reed pressure smoothing.
Control opening
Reed rest opening.
Control noise
Reed breath noise.
Controls of a DuctNetwork, each a number or a mapped node.
std::function< double(double)> function