MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
FftContext.hpp
Go to the documentation of this file.
1#pragma once
2
3#include <bit>
4
7
8#include "SegmentGeometry.hpp"
9
10/**
11 * @file FftContext.hpp
12 * @brief Batched FFT of doubles on the GPU, exactly, with no fp64 on the device.
13 */
14
15namespace MayaFlux::Yantra {
16
17/**
18 * @class FftContext
19 * @brief One FFT per window, as one dispatch of the FFT template.
20 *
21 * Windows are read from the input at a length, stride and offset given in
22 * complex elements, multiplied by a window function and zero padded to the
23 * point count. The butterflies run in the template's emulated IEEE double
24 * arithmetic on word pairs, with twiddle factors computed here in double, so a
25 * result agrees with a host transform to rounding. An inverse context uses the
26 * conjugate twiddles and scales its output by one over the point count.
27 *
28 * Complex output is points bins per window as interleaved re, im. Power output
29 * is points / 2 + 1 bins per window of re * re + im * im, which is the
30 * non-redundant half for a real signal. A projection context takes rows of
31 * weights, one per power bin, and returns one value per row and window: the
32 * weights summed against the power spectrum, so band energies, spectral
33 * moments and filterbank outputs leave the device as a few doubles per window.
34 *
35 * The point count is a power of two from 2 to 2048. The input must hold at
36 * least one complex element.
37 */
39public:
40 /**
41 * @param points Points per window.
42 * @param output Complex bins or the power spectrum.
43 * @param inverse True for the inverse transform, scaled by 1 / points.
44 */
45 explicit FftContext(
46 uint32_t points,
48 bool inverse = false)
50 {
51 }
52
53 /**
54 * @brief A projecting context.
55 * @param points Points per window.
56 * @param weights Rows of points / 2 + 1 weights, row major. The row count is weights.size() divided by that.
57 */
58 FftContext(uint32_t points, std::span<const double> weights)
59 : FftContext(
62 {
63 }
64
65 /** @brief The binding that holds the result of a dispatch. */
66 static constexpr uint32_t result_binding = 3;
67
68 [[nodiscard]] uint32_t points() const noexcept { return m_points; }
69
70 /**
71 * @brief Rows of weights of a projecting context, zero otherwise.
72 */
73 [[nodiscard]] uint32_t descriptors() const noexcept { return m_descriptors; }
74
75 /**
76 * @brief Doubles in the result of one window.
77 */
78 [[nodiscard]] size_t values_per_window() const noexcept
79 {
80 if (m_projection) {
81 return m_descriptors;
82 }
83 return m_power ? static_cast<size_t>(m_points) / 2 + 1 : static_cast<size_t>(m_points) * 2;
84 }
85
86 /**
87 * @brief Transform windows of a real signal.
88 * @param real Samples the windows index into.
89 * @param geometry Window length, stride, first offset and count, in samples.
90 * @param window Coefficients applied to each window, points of them. Empty is rectangular.
91 * @return values_per_window() doubles per window, empty when there are no windows.
92 */
93 [[nodiscard]] std::vector<double> transform(
94 std::span<const double> real, const SegmentGeometry& geometry, std::span<const double> window = {})
95 {
96 std::vector<double> interleaved(real.size() * 2, 0.0);
97 for (size_t i = 0; i < real.size(); ++i) {
98 interleaved[2 * i] = real[i];
99 }
100 return transform_complex(interleaved, geometry, window);
101 }
102
103 /**
104 * @brief Transform windows of a complex signal.
105 * @param interleaved Re, im pairs the windows index into.
106 * @param geometry Window length, stride, first offset and count, in complex elements.
107 * @param window Coefficients applied to each window, points of them. Empty is rectangular.
108 */
109 [[nodiscard]] std::vector<double> transform_complex(
110 std::span<const double> interleaved, const SegmentGeometry& geometry, std::span<const double> window = {})
111 {
112 if (geometry.count == 0) {
113 return {};
114 }
115 stage(interleaved, geometry, window);
116 execute(Datum<std::vector<Kakshya::DataVariant>> {}, ExecutionContext {});
117
118 const auto result = primary_values();
119 return { result.begin(), result.end() };
120 }
121
122 /**
123 * @brief Record the transform of windows of a real signal without waiting for it.
124 *
125 * The context needs a recording (set_recording), which the dispatch appends
126 * to. The result stays on the device, in the result binding: make it a
127 * shared buffer with ensure_shared_buffer(0, result_binding, windows *
128 * values_per_window(), VEC2_U32) before this call and a consumer on the
129 * same recording reads it in place with import_shared.
130 *
131 * @param real Samples the windows index into.
132 * @param geometry Window length, stride, first offset and count, in samples.
133 * @param window Coefficients applied to each window, points of them. Empty is rectangular.
134 */
135 void record_real(std::span<const double> real, const SegmentGeometry& geometry, std::span<const double> window = {})
136 {
137 if (geometry.count == 0) {
138 return;
139 }
140 std::vector<double> interleaved(real.size() * 2, 0.0);
141 for (size_t i = 0; i < real.size(); ++i) {
142 interleaved[2 * i] = real[i];
143 }
144 stage(interleaved, geometry, window);
145 static_cast<void>(dispatch_async(Datum<std::vector<Kakshya::DataVariant>> {}));
146 }
147
148 /**
149 * @brief Stage input, window and geometry for the next dispatch without running it.
150 *
151 * Follow with dispatch_async and collect_result, then decode_primary.
152 */
153 void stage(std::span<const double> interleaved, const SegmentGeometry& geometry, std::span<const double> window = {})
154 {
155 m_windows = geometry.count;
156
157 std::vector<double> coefficients(m_points, window.empty() ? 1.0 : 0.0);
158 std::copy_n(window.begin(), std::min<size_t>(window.size(), m_points), coefficients.begin());
159
160 stage_words(0, interleaved);
162 stage_words(2, coefficients);
163 if (m_projection) {
165 }
167 set_output_size(result_binding, static_cast<size_t>(geometry.count) * values_per_window() * sizeof(uint64_t));
168 }
169
170 const auto scale_bits = std::bit_cast<uint64_t>(m_scale);
171 push(Push {
172 .length = geometry.length,
173 .stride = geometry.stride,
174 .offset = geometry.offset,
175 .scale_lo = static_cast<uint32_t>(scale_bits & 0xFFFFFFFFU),
176 .scale_hi = static_cast<uint32_t>(scale_bits >> 32U) });
177 }
178
179 /**
180 * @brief The spec of the template instance this context drives.
181 */
184 {
188 .points(points)
191 .ssbo("values", BindingDirection::Input, Kakshya::GpuDataFormat::VEC2_U32)
192 .ssbo("twiddle", BindingDirection::Input, Kakshya::GpuDataFormat::VEC2_U32)
193 .ssbo("window", BindingDirection::Input, Kakshya::GpuDataFormat::VEC2_U32)
194 .ssbo("result", BindingDirection::Output, Kakshya::GpuDataFormat::VEC2_U32);
196 assemble.ssbo("weights", BindingDirection::Input, Kakshya::GpuDataFormat::VEC2_U32);
197 }
198 return assemble
204 .workgroup(std::max<uint32_t>(std::min<uint32_t>(points / 2, 256U), 1U))
205 .build();
206 }
207
208protected:
209 /**
210 * @brief One workgroup per window.
211 */
212 [[nodiscard]] std::array<uint32_t, 3> calculate_dispatch_size(
213 size_t /*total_elements*/, const DataStructureInfo& /*structure_info*/) const override
214 {
215 return { m_windows, 1U, 1U };
216 }
217
218private:
219 struct Push {
220 uint32_t length;
221 uint32_t stride;
222 uint32_t offset;
223 uint32_t scale_lo;
224 uint32_t scale_hi;
225 };
226
227 static uint32_t row_count(uint32_t points, size_t weights) noexcept
228 {
229 const size_t bins = static_cast<size_t>(points) / 2 + 1;
230 return weights != 0 && weights % bins == 0 ? static_cast<uint32_t>(weights / bins) : 0U;
231 }
232
234 Portal::Graphics::SpectrumOutput output, bool inverse, std::span<const double> weights = {})
235 : WordPairExecutionContext(config_from_spec(spec), bindings_from_spec(spec), false, "FftContext")
240 , m_scale(inverse && points > 0 ? 1.0 / static_cast<double>(points) : 1.0)
241 , m_weights(weights.begin(), weights.end())
242 {
243 const uint32_t half = points / 2;
244 m_twiddle.reserve(static_cast<size_t>(half) * 2);
245 for (uint32_t k = 0; k < half; ++k) {
246 const double angle = 2.0 * std::numbers::pi * static_cast<double>(k) / static_cast<double>(points);
247 m_twiddle.push_back(std::cos(angle));
248 m_twiddle.push_back(inverse ? std::sin(angle) : -std::sin(angle));
249 }
250 }
251
252 uint32_t m_points;
256 double m_scale;
257 std::vector<double> m_weights;
258 uint32_t m_windows { 1 };
259 std::vector<double> m_twiddle;
260};
261
262} // namespace MayaFlux::Yantra
Runs a shader on doubles carried as two 32-bit words, with no fp64 on the device.
Assemble & spectrum(SpectrumOutput s)
Set what an FFT writes for each window.
Assemble & descriptors(uint32_t n)
Set the rows of weights of a projecting FFT.
ShaderSpec build()
Finalise and return the ShaderSpec.
Assemble & pc(std::string name, Kakshya::GpuDataFormat format)
Declare a push constant field with explicit format.
Assemble & ssbo(std::string name, BindingDirection direction, Kakshya::GpuDataFormat format, Kakshya::DataModality modality=Kakshya::DataModality::SCALAR_F32)
Declare an SSBO binding.
Assemble & workgroup(uint32_t x, uint32_t y=1, uint32_t z=1)
Override workgroup size.
Assemble & points(uint32_t n)
Set the points per window of an FFT.
Assemble & tmpl(KernelTemplate t)
Set the kernel template.
Fluent assembler producing a ShaderSpec.
void stage(std::span< const double > interleaved, const SegmentGeometry &geometry, std::span< const double > window={})
Stage input, window and geometry for the next dispatch without running it.
std::vector< double > m_weights
static constexpr uint32_t result_binding
The binding that holds the result of a dispatch.
static Portal::Graphics::ShaderSpec fft_spec(uint32_t points, Portal::Graphics::SpectrumOutput output, uint32_t descriptors=0)
The spec of the template instance this context drives.
std::vector< double > m_twiddle
static uint32_t row_count(uint32_t points, size_t weights) noexcept
uint32_t descriptors() const noexcept
Rows of weights of a projecting context, zero otherwise.
std::array< uint32_t, 3 > calculate_dispatch_size(size_t, const DataStructureInfo &) const override
One workgroup per window.
std::vector< double > transform_complex(std::span< const double > interleaved, const SegmentGeometry &geometry, std::span< const double > window={})
Transform windows of a complex signal.
std::vector< double > transform(std::span< const double > real, const SegmentGeometry &geometry, std::span< const double > window={})
Transform windows of a real signal.
uint32_t points() const noexcept
void record_real(std::span< const double > real, const SegmentGeometry &geometry, std::span< const double > window={})
Record the transform of windows of a real signal without waiting for it.
FftContext(uint32_t points, Portal::Graphics::SpectrumOutput output=Portal::Graphics::SpectrumOutput::Complex, bool inverse=false)
FftContext(uint32_t points, std::span< const double > weights)
A projecting context.
FftContext(const Portal::Graphics::ShaderSpec &spec, uint32_t points, Portal::Graphics::SpectrumOutput output, bool inverse, std::span< const double > weights={})
size_t values_per_window() const noexcept
Doubles in the result of one window.
std::optional< SharedBufferInfo > shared_buffer_info(uint32_t set, size_t binding_index) const
What the shared buffer at (set, binding_index) declares, or nothing when absent.
void set_output_size(size_t index, size_t byte_size)
Declare the byte capacity of an output binding independently of input data.
ShaderExecutionContext & push(const T &data)
Set push constants from a trivially copyable struct or value.
output_type execute(const input_type &input, const ExecutionContext &ctx) override
Injects multipass configuration into the context before dispatch when set_multipass() has been called...
Portal::Graphics::FenceID dispatch_async(const input_type &input)
Dispatch asynchronously and return a fence for polling.
ShaderExecutionContext & output(size_t byte_size, GpuBufferBinding::ElementType type=GpuBufferBinding::ElementType::FLOAT32)
Add an OUTPUT binding, inferring the next available binding index.
WordPairExecutionContext(GpuComputeConfig config, std::vector< GpuBufferBinding > bindings, bool order_key, std::string name="WordPairExecutionContext")
std::span< const double > primary_values() const noexcept
The primary output of the last dispatch decoded to doubles.
void stage_words(uint32_t binding, std::span< const double > values, size_t padded_count=0, bool complement=false)
Encode values and stage them as the data of a binding.
Shader context whose numeric input is staged as a uvec2 per double.
@ VEC2_U32
glm::uvec2: a 64-bit value as low word (x) and high word (y), not a sampled image format
@ FFT
Radix 2 FFT of word-pair doubles, one workgroup per window, points a power of two up to 2048.
SpectrumOutput
What an FFT template writes for each window.
@ Complex
points complex bins, interleaved re, im, scaled
@ Projection
descriptors values per window: row r of a weights binding, one weight per power bin,...
@ Power
points / 2 + 1 bins of re * re + im * im, after scaling
BindingDirection
Data flow direction for a shader binding slot.
GpuComputeConfig config_from_spec(const Portal::Graphics::ShaderSpec &spec)
Derive a GpuComputeConfig from a ShaderSpec.
std::vector< GpuBufferBinding > bindings_from_spec(const Portal::Graphics::ShaderSpec &spec)
Derive a GpuBufferBinding list from a ShaderSpec.
static constexpr DomainSpec Graphics
Domain constant for Graphics domain.
Definition Creator.hpp:516
Complete declarative description of a generated compute shader.
Dimensions, modality, source type, and optional Composite field schema.
Where the windows of a GPU pass sit in the value array.