MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
IntervalScanStage.hpp
Go to the documentation of this file.
1#pragma once
2
6
7/**
8 * @file IntervalScanStage.hpp
9 * @brief The stage that runs the interval scan on device memory, its push layout and its buffer contract.
10 *
11 * The scan is the GPU form of Kinesis::Discrete::IntervalScanner and gives the
12 * same intervals. The stage reads scores through a device address, so the
13 * output buffer of a network recorded in the same submission feeds it with no
14 * read-back in between. A layout does not change once released; fields are
15 * added only by taking a reserved word.
16 */
17
18namespace MayaFlux::Yantra {
19
20inline constexpr const char* interval_scan_shader = "interval_scan.comp.spv";
21
22/** @brief Words of the state buffer. Zero it to start a stream. */
23inline constexpr uint32_t interval_scan_state_words = 16;
24/** @brief Words of the report buffer: the run count, then the open run and the pending interval. */
25inline constexpr uint32_t interval_scan_report_words = 6;
26
27inline constexpr uint32_t interval_scan_flag_longest = 1;
28inline constexpr uint32_t interval_scan_flag_flush = 2;
29inline constexpr uint32_t interval_scan_flag_gated = 4;
30inline constexpr uint32_t interval_scan_flag_emit_on_close = 8;
31
32/** @brief Push constants of interval_scan.comp. */
34 uint64_t scores;
35 uint64_t state;
36 uint64_t runs;
37 uint64_t report;
38 uint64_t gate;
39 uint32_t n;
40 uint32_t first_index;
41 uint32_t hop;
42 uint32_t min_run;
43 uint32_t min_gap;
44 uint32_t pad;
45 uint32_t gap_at_limit;
46 uint32_t run_limit;
47 uint32_t flags;
48 uint32_t total;
49 uint32_t first_sample;
50 float enter;
51 float leave;
53};
54
55static_assert(sizeof(IntervalScanPC) == 96);
56
57/**
58 * @brief Words the run list needs for n scores: a start and an end for each run that can close, plus slack.
59 */
60[[nodiscard]] constexpr size_t interval_scan_runs_words(size_t n) noexcept
61{
62 return (n + 4) * 2;
63}
64
65/**
66 * @struct IntervalScanReport
67 * @brief What one dispatch of the scan left, decoded from the report buffer.
68 */
70 /** Intervals this dispatch appended to the run list. */
71 uint32_t emitted { 0 };
72 /** Where the run in progress began. */
73 std::optional<size_t> open_start;
74 /** The closed interval waiting for its padded end: its padded start and its end before trailing padding. */
75 std::optional<std::pair<size_t, size_t>> pending;
76};
77
78/**
79 * @brief Decode the report buffer.
80 * @param words interval_scan_report_words words read back from the report buffer.
81 */
82[[nodiscard]] inline IntervalScanReport decode_interval_scan_report(std::span<const uint32_t> words)
83{
84 IntervalScanReport report;
85 if (words.size() < interval_scan_report_words) {
86 return report;
87 }
88 report.emitted = words[0];
89 if (words[1] != 0) {
90 report.open_start = words[2];
91 }
92 if (words[3] != 0) {
93 report.pending = std::pair<size_t, size_t> { words[4], words[5] };
94 }
95 return report;
96}
97
98namespace detail {
99
100 [[nodiscard]] inline float interval_scan_ceil_float(double value) noexcept
101 {
102 auto narrowed = static_cast<float>(value);
103 if (static_cast<double>(narrowed) < value) {
104 narrowed = std::nextafter(narrowed, std::numeric_limits<float>::infinity());
105 }
106 return narrowed;
107 }
108
109}
110
111/**
112 * @brief One interval_scan dispatch: continue a stream with n scores from device memory.
113 *
114 * All buffers are float32 or uint32 and addressed by device address. The
115 * thresholds are rounded up to floats, so a float score compares exactly as it
116 * does in the host scanner. The state buffer persists between calls and is
117 * zeroed to start a stream. The first word of the report buffer counts the runs
118 * appended and must be zero before each dispatch; the rest is overwritten.
119 *
120 * @param config Settings. Its length, or when 0 first_sample plus the scores seen after this call, clamps padded ends.
121 * @param scores Device address of the scores.
122 * @param gate Device address of the gate scores, one per score, or 0 for no gate.
123 * @param state Device address of interval_scan_state_words words.
124 * @param runs Device address of interval_scan_runs_words(n) words, start and end pairs.
125 * @param report Device address of interval_scan_report_words words.
126 * @param first_index Scores already seen in this stream.
127 * @param n Scores in this call.
128 * @param flush End the stream with this call.
129 * @throws std::invalid_argument When the config is not valid.
130 */
132 uint64_t scores, uint64_t gate, uint64_t state, uint64_t runs, uint64_t report,
133 uint32_t first_index, uint32_t n, bool flush)
134{
135 if (const std::string reason = Kinesis::Discrete::diagnose_interval_scan(config); !reason.empty()) {
137 std::source_location::current(), "{}", reason);
138 }
139 const auto seen_end = static_cast<uint64_t>(first_index) + n;
140 const IntervalScanPC pc {
141 .scores = scores,
142 .state = state,
143 .runs = runs,
144 .report = report,
145 .gate = gate,
146 .n = n,
147 .first_index = first_index,
148 .hop = config.hop,
149 .min_run = config.min_run,
150 .min_gap = config.min_gap,
151 .pad = config.padding,
152 .gap_at_limit = config.gap_at_limit,
153 .run_limit = config.max_run == 0 ? std::numeric_limits<uint32_t>::max() : config.max_run - config.hop - 2 * config.padding,
154 .flags = (config.use_longest_gap ? interval_scan_flag_longest : 0U)
155 | (flush ? interval_scan_flag_flush : 0U)
156 | (gate != 0 ? interval_scan_flag_gated : 0U)
158 .total = config.length != 0 ? config.length : static_cast<uint32_t>(config.first_sample + seen_end * config.hop),
159 .first_sample = config.first_sample,
162 .gate_threshold = detail::interval_scan_ceil_float(config.gate_threshold),
163 };
164 return DependencyStage {
165 .config = GpuComputeConfig { .shader_path = interval_scan_shader, .workgroup_size = { 1, 1, 1 }, .push_constant_size = sizeof(IntervalScanPC) },
166 .stage_fn = [pc](GpuDispatchCore& core) { core.set_push_constants(pc); },
167 .explicit_groups = std::array<uint32_t, 3> { 1U, 1U, 1U },
168 };
169}
170
171} // namespace MayaFlux::Yantra
Runs of a score sequence that stay above a threshold, found in order as a stream, for MayaFlux::Kines...
Non-template base that owns all type-independent GPU dispatch logic.
@ ComputeMatrix
Compute operations (Yantra - algorithms, matrices, DSP).
@ Yantra
DSP algorithms, computational units, matrix operations, Grammar.
std::string diagnose_interval_scan(const IntervalScanConfig &config)
Why a config cannot be scanned.
float interval_scan_ceil_float(double value) noexcept
constexpr uint32_t interval_scan_state_words
Words of the state buffer.
constexpr uint32_t interval_scan_flag_emit_on_close
DependencyStage interval_scan_stage(const Kinesis::Discrete::IntervalScanConfig &config, uint64_t scores, uint64_t gate, uint64_t state, uint64_t runs, uint64_t report, uint32_t first_index, uint32_t n, bool flush)
One interval_scan dispatch: continue a stream with n scores from device memory.
IntervalScanReport decode_interval_scan_report(std::span< const uint32_t > words)
Decode the report buffer.
constexpr uint32_t interval_scan_flag_flush
constexpr uint32_t interval_scan_report_words
Words of the report buffer: the run count, then the open run and the pending interval.
constexpr size_t interval_scan_runs_words(size_t n) noexcept
Words the run list needs for n scores: a start and an end for each run that can close,...
constexpr uint32_t interval_scan_flag_longest
constexpr uint32_t interval_scan_flag_gated
constexpr const char * interval_scan_shader
Plain-data description of the compute shader to dispatch.
One stage in a record_stages call.
Push constants of interval_scan.comp.
std::optional< std::pair< size_t, size_t > > pending
The closed interval waiting for its padded end: its padded start and its end before trailing padding.
uint32_t emitted
Intervals this dispatch appended to the run list.
std::optional< size_t > open_start
Where the run in progress began.
What one dispatch of the scan left, decoded from the report buffer.