MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
LaggedPair.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 LaggedPair.hpp
12 * @brief Lagged pairwise sums of doubles on the GPU, exactly, with no fp64 on the device.
13 *
14 * The LaggedPair kernel is run on a plain WordPairExecutionContext. This file
15 * holds what is specific to it: the spec and the stage.
16 */
17
18namespace MayaFlux::Yantra {
19
20/**
21 * @brief The spec of a LaggedPair kernel.
22 *
23 * For window w and lag l the kernel sums map(x[i], x[i + l]) over the window,
24 * with i + l inside it, in the template's emulated IEEE double arithmetic on
25 * word pairs. A centred kernel subtracts each window's mean from both operands
26 * first; the mean is the window sum divided by the window length, exactly
27 * rounded like a host quotient. A lag of the window length or more sums
28 * nothing. Bindings: values 0, result 1.
29 *
30 * @param map Pairwise map summed over the window.
31 * @param centred True to remove each window's mean before the map.
32 * @param workgroup Invocations per sum. A power of two from 2 to 1024.
33 */
35 Portal::Graphics::PairMap map, bool centred, uint32_t workgroup = 256)
36{
40 .pair_map(map)
41 .centred(centred)
42 .ssbo("values", BindingDirection::Input, Kakshya::GpuDataFormat::VEC2_U32)
43 .ssbo("result", BindingDirection::Output, Kakshya::GpuDataFormat::VEC2_U32)
51 .workgroup(workgroup)
52 .build();
53}
54
55/**
56 * @brief The stage that sums every window at every lag in a range, over values already on the device.
57 *
58 * The values are whatever binding 0 resolves to: a shared buffer of the
59 * context, or one imported from another context with import_shared. Nothing is
60 * staged from the host. Many passes over one input then share a single upload.
61 *
62 * @param context Context built with config.
63 * @param config Config of the spec the context was built from.
64 * @param geometry Window length, stride, first offset and count. Every window must lie inside the values.
65 * @param first_lag Shortest lag.
66 * @param lag_count Number of consecutive lags.
67 */
69 WordPairExecutionContext& context, const GpuComputeConfig& config,
70 const SegmentGeometry& geometry, uint32_t first_lag, uint32_t lag_count)
71{
72 const auto length_bits = std::bit_cast<uint64_t>(static_cast<double>(geometry.length));
73 const std::array<uint32_t, 7> push {
74 geometry.length, geometry.stride, geometry.offset, first_lag, lag_count,
75 static_cast<uint32_t>(length_bits & 0xFFFFFFFFU), static_cast<uint32_t>(length_bits >> 32U)
76 };
77 const size_t result_bytes = static_cast<size_t>(geometry.count) * lag_count * sizeof(uint64_t);
78
79 return DependencyStage {
80 .config = config,
81 .stage_fn = [&context, result_bytes, push](GpuDispatchCore&) {
82 if (!context.shared_buffer_info(0, 1)) {
83 context.set_output_size(1, result_bytes);
84 }
85 context.set_push_constants(push);
86 },
87 .explicit_groups = std::array<uint32_t, 3> { lag_count, geometry.count, 1U },
88 };
89}
90
91/**
92 * @brief The stage that sums every window at every lag in a range.
93 *
94 * One workgroup runs per lag and window, so the lag count and the window count
95 * are each limited to the device's maximum workgroup count, 65535 at least.
96 * The result is geometry.count * lag_count doubles, window major.
97 *
98 * @code
99 * const auto spec = lagged_pair_spec(PairMap::Product, true);
100 * const auto config = config_from_spec(spec);
101 * WordPairExecutionContext context(config, bindings_from_spec(spec), false, "LaggedPair");
102 * context.record_stages({ lagged_pair_stage(context, config, values, geometry, 0, 64) });
103 * const auto sums = context.download_words(1, geometry.count * 64);
104 * @endcode
105 *
106 * @param context Context built with config.
107 * @param config Config of the spec the context was built from.
108 * @param values Doubles the windows index into. Every window must lie inside it.
109 * @param geometry Window length, stride, first offset and count.
110 * @param first_lag Shortest lag.
111 * @param lag_count Number of consecutive lags.
112 */
114 WordPairExecutionContext& context, const GpuComputeConfig& config, std::span<const double> values,
115 const SegmentGeometry& geometry, uint32_t first_lag, uint32_t lag_count)
116{
117 auto stage = lagged_pair_stage(context, config, geometry, first_lag, lag_count);
118 stage.stage_fn = [&context, values, resident = std::move(stage.stage_fn)](GpuDispatchCore& core) {
119 context.stage_words(0, values);
120 resident(core);
121 };
122 return stage;
123}
124
125} // namespace MayaFlux::Yantra
Runs a shader on doubles carried as two 32-bit words, with no fp64 on the device.
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 & pair_map(PairMap m)
Set the pairwise map of a LaggedPair.
Assemble & centred(bool c=true)
Subtract each window's mean from both operands of a LaggedPair before the map.
Assemble & workgroup(uint32_t x, uint32_t y=1, uint32_t z=1)
Override workgroup size.
Assemble & tmpl(KernelTemplate t)
Set the kernel template.
Fluent assembler producing a ShaderSpec.
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.
@ VEC2_U32
glm::uvec2: a 64-bit value as low word (x) and high word (y), not a sampled image format
@ LaggedPair
Sums a pairwise map of x[i] and x[i + lag] over a window, for every lag in a range,...
BindingDirection
Data flow direction for a shader binding slot.
PairMap
Map of two elements, x[i] and x[i + lag], summed by a LaggedPair kernel.
Portal::Graphics::ShaderSpec lagged_pair_spec(Portal::Graphics::PairMap map, bool centred, uint32_t workgroup=256)
The spec of a LaggedPair kernel.
DependencyStage lagged_pair_stage(WordPairExecutionContext &context, const GpuComputeConfig &config, const SegmentGeometry &geometry, uint32_t first_lag, uint32_t lag_count)
The stage that sums every window at every lag in a range, over values already on the device.
Plain-data description of the compute shader to dispatch.
Complete declarative description of a generated compute shader.
One stage in a record_stages call.
Where the windows of a GPU pass sit in the value array.