MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
WordPairExecutionContext.hpp
Go to the documentation of this file.
1#pragma once
2
4
6
7/**
8 * @file WordPairExecutionContext.hpp
9 * @brief Runs a shader on doubles carried as two 32-bit words, with no fp64 on the device.
10 */
11
12namespace MayaFlux::Yantra {
13
14/**
15 * @class WordPairExecutionContext
16 * @brief Shader context whose numeric input is staged as a uvec2 per double.
17 *
18 * Each double is encoded as one 64-bit word, low word first, so the shader sees
19 * a VEC2_U32 binding and needs neither shaderFloat64 nor lossy narrowing to
20 * float. The word is the double's order key, whose unsigned order is the
21 * numeric order, or its IEEE 754 bits unchanged. The context stages any
22 * binding from a span of doubles. The primary output of a dispatch is kept as
23 * raw words, and in IEEE mode also decoded to doubles. Element types are set by
24 * the caller. Bindings, push constants and multipass come from ShaderExecutionContext.
25 */
27public:
28 /**
29 * @param config Pipeline of the shader.
30 * @param bindings Binding list. The first output or in/out binding is the primary output.
31 * @param order_key True to stage order keys, false to stage the IEEE 754 bits unchanged.
32 * @param name Name used in diagnostics.
33 */
35 GpuComputeConfig config,
36 std::vector<GpuBufferBinding> bindings,
37 bool order_key,
38 std::string name = "WordPairExecutionContext")
39 : ShaderExecutionContext<>(std::move(config), std::move(bindings), std::move(name))
40 , m_order_key(order_key)
41 {
42 }
43
44 [[nodiscard]] bool order_keyed() const noexcept { return m_order_key; }
45
46 /**
47 * @brief Encode values and stage them as the data of a binding.
48 * @param binding Binding that receives the words.
49 * @param values Doubles to encode.
50 * @param padded_count Word count to stage. Words past values are all ones, the largest key.
51 * @param complement Complements every encoded word, which reverses an order key's order.
52 */
53 void stage_words(uint32_t binding, std::span<const double> values, size_t padded_count = 0, bool complement = false)
54 {
55 set_binding_data(binding, OperationHelper::encode_word_pairs(values, padded_count, m_order_key, complement));
56 }
57
58 /**
59 * @brief The primary output of the last dispatch as 32-bit words, empty if it produced none.
60 */
61 [[nodiscard]] std::span<const uint32_t> primary_words() const noexcept { return m_primary_words; }
62
63 /**
64 * @brief The primary output of the last dispatch decoded to doubles.
65 *
66 * Empty when the context stages order keys, because its words are not
67 * samples, or when the dispatch produced no output.
68 */
69 [[nodiscard]] std::span<const double> primary_values() const noexcept { return m_primary_values; }
70
71 /**
72 * @brief Decode a dispatch result, as returned by an asynchronous collect, to doubles.
73 * @param result Result whose primary output holds word pairs.
74 * @return The decoded doubles, or empty when the context stages order keys.
75 */
76 [[nodiscard]] std::vector<double> decode_primary(const GpuChannelResult& result) const
77 {
78 if (m_order_key) {
79 return {};
80 }
81 const auto* bytes = reinterpret_cast<const uint8_t*>(result.primary.data());
82 return OperationHelper::decode_word_pairs(std::span<const uint8_t>(bytes, result.primary.size() * sizeof(float)));
83 }
84
85 /**
86 * @brief Read a binding back as doubles after a recorded stage.
87 *
88 * For stages recorded with record_stages, which leave nothing in
89 * primary_values. The context must have been built with the config the
90 * stage ran under. A binding that resolves to a shared buffer of set 0, its
91 * own or an imported one, is read from that buffer, as the shaders see it.
92 *
93 * @param binding Binding that holds word pairs.
94 * @param count Doubles to read.
95 * @return The decoded doubles, or empty when the context stages order keys.
96 */
97 [[nodiscard]] std::vector<double> download_words(size_t binding, size_t count)
98 {
99 if (m_order_key) {
100 return {};
101 }
102 std::vector<uint8_t> bytes(count * sizeof(uint64_t));
103 if (shared_buffer_info(0, binding)) {
104 download_shared(0, binding, bytes.data(), bytes.size());
105 } else {
106 download_binding(binding, bytes.data(), bytes.size());
107 }
109 }
110
111protected:
112 /**
113 * @brief Keeps the primary output as words; the context returns no Datum.
114 */
116 const GpuChannelResult& raw,
117 const std::vector<std::vector<double>>& /*channels*/,
118 const DataStructureInfo& /*structure_info*/) override
119 {
120 const size_t count = raw.primary.size();
121 m_primary_words.resize(count);
122 const auto* src = reinterpret_cast<const uint8_t*>(raw.primary.data());
123 for (size_t i = 0; i < count; ++i) {
124 m_primary_words[i] = Transitive::Protocol::load_le_u32(src + i * sizeof(uint32_t));
125 }
127 return output_type {};
128 }
129
130private:
132 std::vector<uint32_t> m_primary_words;
133 std::vector<double> m_primary_values;
134};
135
136} // namespace MayaFlux::Yantra
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_binding_data(size_t index, std::span< const T > data)
Pre-stage typed data for a specific binding slot, bypassing the default channel-flattening path in pr...
static std::vector< double > decode_word_pairs(std::span< const uint8_t > bytes)
Decode little-endian 64-bit words as IEEE 754 doubles.
static std::vector< uint8_t > encode_word_pairs(std::span< const double > values, size_t padded_words=0, bool order_key=false, bool complement=false)
Encode doubles as little-endian 64-bit words, two 32-bit lanes each.
ShaderExecutionContext(GpuComputeConfig config, std::vector< GpuBufferBinding > bindings={}, std::string name="ShaderExecutionContext", bool compute_isolated=true)
Construct with shader config and optional pre-built binding list.
typename GpuExecutionContext< InputType, OutputType >::output_type output_type
std::vector< double > download_words(size_t binding, size_t count)
Read a binding back as doubles after a recorded stage.
std::vector< double > decode_primary(const GpuChannelResult &result) const
Decode a dispatch result, as returned by an asynchronous collect, to doubles.
output_type collect_gpu_outputs(const GpuChannelResult &raw, const std::vector< std::vector< double > > &, const DataStructureInfo &) override
Keeps the primary output as words; the context returns no Datum.
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.
std::span< const uint32_t > primary_words() const noexcept
The primary output of the last dispatch as 32-bit words, empty if it produced none.
uint32_t load_le_u32(const uint8_t *src) noexcept
Load a uint32 from four little-endian bytes.
Plain-data description of the compute shader to dispatch.
Dimensions, modality, source type, and optional Composite field schema.
Erased output of a GPU dispatch: reconstructed float data plus any raw auxiliary outputs keyed by bin...