MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
WordPairMap.hpp
Go to the documentation of this file.
1#pragma once
2
6
7/**
8 * @file WordPairMap.hpp
9 * @brief Element-wise IEEE double arithmetic on the GPU, exactly rounded, with no fp64 on the device.
10 *
11 * The WordPairMap kernel is run on a plain WordPairExecutionContext. This file
12 * holds what is specific to it: the spec and the stage.
13 */
14
15namespace MayaFlux::Yantra {
16
17/**
18 * @brief True for an operation that takes no second operand.
19 */
20[[nodiscard]] constexpr bool word_pair_unary(Portal::Graphics::WordPairOp op) noexcept
21{
23}
24
25/**
26 * @brief Bytes of one result element: a word pair, or a float32 for ToFloat32.
27 */
28[[nodiscard]] constexpr size_t word_pair_result_bytes(Portal::Graphics::WordPairOp op) noexcept
29{
30 return op == Portal::Graphics::WordPairOp::ToFloat32 ? sizeof(float) : sizeof(uint64_t);
31}
32
33/**
34 * @brief The spec of a WordPairMap kernel.
35 *
36 * Result i is op(a[i], b[i]) in the template's emulated IEEE 754 binary64
37 * arithmetic, rounded to nearest even, with the IEEE results for signed zeros,
38 * infinities, NaN and subnormals. Sqrt and ToFloat32 take only a. Bindings: a 0,
39 * b 1, result 2, or a 0 and result 1 for Sqrt and ToFloat32. The result of ToFloat32
40 * is float32, the double rounded to nearest even, so it can feed a network.
41 *
42 * @param op Operation applied to every element.
43 * @param workgroup Invocations per group, from 1 to 1024.
44 */
46 Portal::Graphics::WordPairOp op, uint32_t workgroup = 256)
47{
51 .word_op(op)
52 .ssbo("a", BindingDirection::Input, Kakshya::GpuDataFormat::VEC2_U32);
53 if (!word_pair_unary(op)) {
54 assemble.ssbo("b", BindingDirection::Input, Kakshya::GpuDataFormat::VEC2_U32);
55 }
57 return assemble.ssbo("result", BindingDirection::Output, result)
59 .workgroup(workgroup)
60 .build();
61}
62
63/**
64 * @brief The stage that applies the operation to count elements whose operands are already on the device.
65 *
66 * The operands are whatever the context's bindings resolve to: shared buffers
67 * of the context, or buffers imported from another context with
68 * import_shared. Nothing is staged from the host. Give the context that owns
69 * the operands and this one the same recording, and record the owner's stage
70 * first.
71 *
72 * @code
73 * producer.ensure_shared_buffer(0, 2, count, GpuBufferBinding::ElementType::VEC2_U32);
74 * consumer.import_shared(0, 0, producer, 0, 2, GpuBufferBinding::ElementType::VEC2_U32);
75 * producer.record_stages({ word_pair_map_stage(producer, product_config, WordPairOp::Mul, a, b) });
76 * consumer.record_stages({ word_pair_map_stage(consumer, root_config, WordPairOp::Sqrt, count) });
77 * const auto roots = consumer.download_words(1, count);
78 * @endcode
79 *
80 * @param context Context built with config.
81 * @param config Config of the spec the context was built from.
82 * @param op Operation of the spec.
83 * @param count Elements to compute. The operand buffers must hold at least this many.
84 * @param workgroup Workgroup size of the spec.
85 */
88 size_t count, uint32_t workgroup = 256)
89{
90 const uint32_t result_binding = word_pair_unary(op) ? 1U : 2U;
91 const std::array<uint32_t, 1> push { static_cast<uint32_t>(count) };
92 const uint32_t groups = std::max<uint32_t>(1U, static_cast<uint32_t>((count + workgroup - 1) / workgroup));
93
94 return DependencyStage {
95 .config = config,
96 .stage_fn = [&context, count, result_binding, element_bytes = word_pair_result_bytes(op), push](GpuDispatchCore&) {
97 if (!context.shared_buffer_info(0, result_binding)) {
98 context.set_output_size(result_binding, count * element_bytes);
99 }
100 context.set_push_constants(push);
101 },
102 .explicit_groups = std::array<uint32_t, 3> { groups, 1U, 1U },
103 };
104}
105
106/**
107 * @struct WordPairOperand
108 * @brief Where one operand of a WordPairMap stage comes from.
109 *
110 * A host sequence is staged by the stage. An operand on the device is whatever
111 * its binding already resolves to, a shared buffer of the context or one
112 * imported from another context.
113 */
115 std::span<const double> host;
116 bool resident { false };
117
118 WordPairOperand() = default;
119 WordPairOperand(std::span<const double> values)
120 : host(values)
121 {
122 }
123
124 WordPairOperand(const std::vector<double>& values)
125 : host(values)
126 {
127 }
128
129 /** @brief The operand is already on the device. */
130 [[nodiscard]] static WordPairOperand on_device()
131 {
132 WordPairOperand operand;
133 operand.resident = true;
134 return operand;
135 }
136};
137
138/**
139 * @brief The stage that applies the operation to count elements, each operand from the host or the device.
140 *
141 * @code
142 * consumer.record_stages({ word_pair_map_stage(*consumer, config, WordPairOp::Div, count,
143 * WordPairOperand::on_device(), divisors) });
144 * @endcode
145 *
146 * @param context Context built with config.
147 * @param config Config of the spec the context was built from.
148 * @param op Operation of the spec.
149 * @param count Elements to compute.
150 * @param a First operand. A host operand must hold at least count elements.
151 * @param b Second operand, ignored for Sqrt. A host operand must hold at least count elements.
152 * @param workgroup Workgroup size of the spec.
153 * @throws std::invalid_argument when a host operand holds fewer than count elements.
154 */
157 size_t count, const WordPairOperand& a, const WordPairOperand& b, uint32_t workgroup = 256)
158{
159 const bool unary = word_pair_unary(op);
160 const auto check = [count](const WordPairOperand& operand) {
161 if (!operand.resident && operand.host.size() < count) {
163 std::source_location::current(),
164 "word_pair_map_stage: a host operand holds {} elements, {} are required", operand.host.size(), count);
165 }
166 };
167 check(a);
168 if (!unary) {
169 check(b);
170 }
171
172 auto stage = word_pair_map_stage(context, config, op, count, workgroup);
173 stage.stage_fn = [&context, a, b, unary, count, resident = std::move(stage.stage_fn)](GpuDispatchCore& core) {
174 if (!a.resident) {
175 context.stage_words(0, a.host.first(count));
176 }
177 if (!unary && !b.resident) {
178 context.stage_words(1, b.host.first(count));
179 }
180 resident(core);
181 };
182 return stage;
183}
184
185/**
186 * @brief The stage that applies the operation to every element of two host sequences.
187 *
188 * The element count is the length of a, or the shorter of a and b for a binary
189 * operation. The result is that many doubles.
190 *
191 * @code
192 * const auto spec = word_pair_map_spec(WordPairOp::Div);
193 * const auto config = config_from_spec(spec);
194 * WordPairExecutionContext context(config, bindings_from_spec(spec), false, "WordPairMap");
195 * context.record_stages({ word_pair_map_stage(context, config, WordPairOp::Div, numerators, denominators) });
196 * const auto quotients = context.download_words(2, numerators.size());
197 * @endcode
198 *
199 * @param context Context built with config.
200 * @param config Config of the spec the context was built from.
201 * @param op Operation of the spec.
202 * @param a First operand of every element.
203 * @param b Second operand of every element, ignored for Sqrt.
204 * @param workgroup Workgroup size of the spec.
205 */
208 std::span<const double> a, std::span<const double> b, uint32_t workgroup = 256)
209{
210 const bool unary = word_pair_unary(op);
211 const size_t count = unary ? a.size() : std::min(a.size(), b.size());
212
213 return word_pair_map_stage(context, config, op, count, WordPairOperand(a), WordPairOperand(b), workgroup);
214}
215
216/**
217 * @brief Read the float32 results of a ToFloat32 stage recorded on the context.
218 *
219 * Reads the shared buffer of the result binding when it has one, otherwise the
220 * context's own.
221 *
222 * @param context The context the stage was recorded on.
223 * @param count Elements the stage converted.
224 */
225[[nodiscard]] inline std::vector<float> read_float_results(WordPairExecutionContext& context, size_t count)
226{
227 std::vector<float> out(count);
228 if (count == 0) {
229 return out;
230 }
231 if (context.shared_buffer_info(0, 1)) {
232 context.download_shared(0, 1, out.data(), count * sizeof(float));
233 } else {
234 context.download_binding(1, out.data(), count * sizeof(float));
235 }
236 return out;
237}
238
239} // namespace MayaFlux::Yantra
Runs a shader on doubles carried as two 32-bit words, with no fp64 on the device.
Assemble & ssbo(std::string name, BindingDirection direction, Kakshya::GpuDataFormat format, Kakshya::DataModality modality=Kakshya::DataModality::SCALAR_F32)
Declare an SSBO binding.
Assemble & tmpl(KernelTemplate t)
Set the kernel template.
Assemble & word_op(WordPairOp o)
Set the operation of a WordPairMap.
Fluent assembler producing a ShaderSpec.
void download_binding(size_t index, void *dest, size_t byte_size)
Read back a specific binding into a caller-provided destination.
void download_shared(uint32_t set, size_t binding_index, void *dest, size_t byte_size)
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.
void set_push_constants(const void *data, size_t bytes)
Set push constant data from a raw byte pointer.
Non-template base that owns all type-independent GPU dispatch logic.
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.
@ BufferProcessing
Buffer processing (Buffers::BufferManager, processing chains).
@ Yantra
DSP algorithms, computational units, matrix operations, Grammar.
@ VEC2_U32
glm::uvec2: a 64-bit value as low word (x) and high word (y), not a sampled image format
@ FLOAT32
32-bit float (standard GPU)
@ WordPairMap
Applies one IEEE double operation to word-pair doubles, one thread per element.
BindingDirection
Data flow direction for a shader binding slot.
WordPairOp
Operation applied by a WordPairMap kernel.
@ ToFloat32
float32(a) rounded to nearest even, with IEEE results for zeros, infinities, NaN, overflow and float ...
@ Sqrt
sqrt(a). Unary: no b binding.
DependencyStage word_pair_map_stage(WordPairExecutionContext &context, const GpuComputeConfig &config, Portal::Graphics::WordPairOp op, size_t count, uint32_t workgroup=256)
The stage that applies the operation to count elements whose operands are already on the device.
Portal::Graphics::ShaderSpec word_pair_map_spec(Portal::Graphics::WordPairOp op, uint32_t workgroup=256)
The spec of a WordPairMap kernel.
constexpr size_t word_pair_result_bytes(Portal::Graphics::WordPairOp op) noexcept
Bytes of one result element: a word pair, or a float32 for ToFloat32.
constexpr bool word_pair_unary(Portal::Graphics::WordPairOp op) noexcept
True for an operation that takes no second operand.
std::vector< float > read_float_results(WordPairExecutionContext &context, size_t count)
Read the float32 results of a ToFloat32 stage recorded on the context.
Plain-data description of the compute shader to dispatch.
Complete declarative description of a generated compute shader.
One stage in a record_stages call.
static WordPairOperand on_device()
The operand is already on the device.
WordPairOperand(const std::vector< double > &values)
WordPairOperand(std::span< const double > values)
std::span< const double > host
Where one operand of a WordPairMap stage comes from.