MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
SegmentedArgMax.hpp
Go to the documentation of this file.
1#pragma once
2
5
6#include "SegmentGeometry.hpp"
7
8/**
9 * @file SegmentedArgMax.hpp
10 * @brief The largest value of each segment of doubles and where it is, on the GPU, with no fp64 on the device.
11 *
12 * The SegmentedArgMax kernel is run on a plain WordPairExecutionContext. This
13 * file holds what is specific to it: the spec, the stage and the decoding of
14 * its result.
15 */
16
17namespace MayaFlux::Yantra {
18
19/** @brief The index reported for a segment that holds no value to select. */
20inline constexpr uint32_t no_argmax_index = 0xFFFFFFFFU;
21
22/**
23 * @struct ArgMaxResult
24 * @brief The selected value of one segment and its position inside the segment.
25 */
27 /** The largest value, NaN when the segment holds none. */
28 double value { std::numeric_limits<double>::quiet_NaN() };
29 /** Position of the first occurrence of the value, or no_argmax_index. */
30 uint32_t index { no_argmax_index };
31
32 [[nodiscard]] bool found() const noexcept { return index != no_argmax_index; }
33};
34
35/**
36 * @brief The spec of a SegmentedArgMax kernel.
37 *
38 * Segment s covers length elements from offset + s * stride. Values compare by
39 * the library order key, where -0.0 equals +0.0, with every NaN smaller than
40 * any other value, so a NaN is never selected. Of equal values the lowest
41 * index wins. Bindings: values 0, result 1.
42 *
43 * @param workgroup Invocations per segment. A power of two from 2 to 1024.
44 */
45[[nodiscard]] inline Portal::Graphics::ShaderSpec segmented_argmax_spec(uint32_t workgroup = 256)
46{
50 .ssbo("values", BindingDirection::Input, Kakshya::GpuDataFormat::VEC2_U32)
51 .ssbo("result", BindingDirection::Output, Kakshya::GpuDataFormat::VEC2_U32)
55 .workgroup(workgroup)
56 .build();
57}
58
59/**
60 * @brief The stage that selects the largest value of every segment of values already on the device.
61 *
62 * The values are whatever binding 0 resolves to: a shared buffer of the
63 * context, or one imported from another context with import_shared, for
64 * instance the result of a LaggedPair pass recorded earlier on the same
65 * recording. Nothing is staged from the host.
66 *
67 * @code
68 * const auto spec = segmented_argmax_spec();
69 * const auto config = config_from_spec(spec);
70 * WordPairExecutionContext select(config, bindings_from_spec(spec), false, "SegmentedArgMax");
71 * select.set_recording(recording);
72 * select.import_shared(0, 0, correlation, 0, 1, GpuBufferBinding::ElementType::VEC2_U32);
73 * select.record_stages({ segmented_argmax_stage(select, config, geometry) });
74 * const auto best = read_argmax(select, geometry.count);
75 * @endcode
76 *
77 * @param context Context built with config.
78 * @param config Config of the spec the context was built from.
79 * @param geometry Segment length, stride, first offset and count. Every segment must lie inside the values.
80 */
82 WordPairExecutionContext& context, const GpuComputeConfig& config, const SegmentGeometry& geometry)
83{
84 const std::array<uint32_t, 3> push { geometry.length, geometry.stride, geometry.offset };
85 const size_t result_bytes = static_cast<size_t>(geometry.count) * 2U * sizeof(uint64_t);
86
87 return DependencyStage {
88 .config = config,
89 .stage_fn = [&context, result_bytes, push](GpuDispatchCore&) {
90 if (!context.shared_buffer_info(0, 1)) {
91 context.set_output_size(1, result_bytes);
92 }
93 context.set_push_constants(push);
94 },
95 .explicit_groups = std::array<uint32_t, 3> { geometry.count, 1U, 1U },
96 };
97}
98
99/**
100 * @brief The stage that selects the largest value of every segment of a host sequence.
101 *
102 * @param context Context built with config.
103 * @param config Config of the spec the context was built from.
104 * @param values Doubles the segments index into.
105 * @param geometry Segment length, stride, first offset and count. Every segment must lie inside values.
106 */
108 WordPairExecutionContext& context, const GpuComputeConfig& config, std::span<const double> values,
109 const SegmentGeometry& geometry)
110{
111 auto stage = segmented_argmax_stage(context, config, geometry);
112 stage.stage_fn = [&context, values, resident = std::move(stage.stage_fn)](GpuDispatchCore& core) {
113 context.stage_words(0, values);
114 resident(core);
115 };
116 return stage;
117}
118
119/**
120 * @brief Read the selections of the segments of the last recorded stage.
121 * @param context The context the stage was recorded on.
122 * @param segments Number of segments of that stage.
123 */
124[[nodiscard]] inline std::vector<ArgMaxResult> read_argmax(WordPairExecutionContext& context, size_t segments)
125{
126 const auto words = context.download_words(1, segments * 2U);
127 std::vector<ArgMaxResult> out;
128 out.reserve(segments);
129 for (size_t s = 0; s < segments && 2U * s + 1U < words.size(); ++s) {
130 out.push_back({ .value = words[2U * s],
131 .index = static_cast<uint32_t>(std::bit_cast<uint64_t>(words[2U * s + 1U]) & 0xFFFFFFFFULL) });
132 }
133 return out;
134}
135
136} // 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 & 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.
std::vector< double > download_words(size_t binding, size_t count)
Read a binding back as doubles after a recorded stage.
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
@ SegmentedArgMax
The first maximum of each segment of word-pair doubles, one workgroup per segment.
BindingDirection
Data flow direction for a shader binding slot.
constexpr uint32_t no_argmax_index
The index reported for a segment that holds no value to select.
std::vector< ArgMaxResult > read_argmax(WordPairExecutionContext &context, size_t segments)
Read the selections of the segments of the last recorded stage.
DependencyStage segmented_argmax_stage(WordPairExecutionContext &context, const GpuComputeConfig &config, const SegmentGeometry &geometry)
The stage that selects the largest value of every segment of values already on the device.
Portal::Graphics::ShaderSpec segmented_argmax_spec(uint32_t workgroup=256)
The spec of a SegmentedArgMax kernel.
Plain-data description of the compute shader to dispatch.
Complete declarative description of a generated compute shader.
uint32_t index
Position of the first occurrence of the value, or no_argmax_index.
double value
The largest value, NaN when the segment holds none.
The selected value of one segment and its position inside the segment.
One stage in a record_stages call.
Where the windows of a GPU pass sit in the value array.