Martino Ferrari
fb2c2f5e4d
Findings from the review of the sliding-window change: - A level >= 1 gather emitted only complete, wholly-retained buckets, so the geometry stopped at the last bucket boundary inside the range: the newest samples of a live window -- up to `span - 1` of them, about a pixel at the level level_for() picks -- were not drawn, on the right edge, which is the part of a scrolling trace that gets watched, and the oldest retained samples fell outside the geometry too (the level-1 gather of a sliding window started 51 samples in). The two partial edge buckets are now gathered as raw samples through copy_raw() and bracketed around the envelope -- the same exactness split reduce/sum/sumsq already use -- so the emitted geometry spans the requested range exactly. The pyramid still stores no partial bucket, so append stays amortised O(1); at 1 MS/s the demo stages 511 extra sub-pixel segments and still draws at 1.05 ms/frame, and the screenshot's trace now reaches one column further at each end. - `drop_before`'s doc claimed a no-op "for an empty pyramid": false, and backwards -- the restart branch is exactly what an empty pyramid hits, which is what StreamSeries::acquire() depends on when the ring saturated before the first acquire. The precondition is `absolute_sample <= window_base()`, and the restart is documented as what it is. - The pyramid's memory figure was 3x optimistic: an entry is 24 bytes (MinMax plus the exact sum/sumsq doubles), so level 0 costs 0.375n bytes and the whole pyramid ~0.75n -- about 19% of 4-byte raw samples, not the 6% a min/max-only index would cost. Corrected in the header, spec 4.2 and 4.5, with the trade stated (the doubles buy O(log n) sum/mean/RMS/integral from whole buckets), and the plan's Task 3 sketch no longer describes per-level prefix sums, a level() span or an unaligned-end widening that does not exist. Tests: `gather_at_a_lod_level_reaches_both_ends_of_the_window` pins that the first and last emitted points are the oldest and newest retained samples -- with spike values no bucket envelope can produce -- at level 1, at the level a dense view picks, and for a static series whose end is unaligned. It fails against the previous commit (first point at the first whole bucket), and so does the sliding gather mapping check, which now accounts for the raw edge pairs.
92 lines
4.4 KiB
C++
92 lines
4.4 KiB
C++
#pragma once
|
|
#include <vector>
|
|
|
|
#include <plot/core/types.hpp>
|
|
#include <plot/data/minmax_pyramid.hpp>
|
|
|
|
namespace plot::data {
|
|
|
|
/// A uniform-grid series of y samples: sample i lives at x = x0() + i*dx().
|
|
///
|
|
/// Every concrete series answers range queries exactly, and never by scanning the
|
|
/// whole range: the bucket-aligned interior comes from the pyramid (O(log n)
|
|
/// bucket aggregates) and at most two partial edge buckets are read through
|
|
/// copy_raw() and scanned. Cost is independent of series length and no query
|
|
/// allocates.
|
|
///
|
|
/// Indexing is over the series' own window: index 0 is the oldest sample the
|
|
/// series currently holds (for a ring-backed series that is the oldest retained
|
|
/// one), so reduce(start, end) and gather() are in the same coordinates as
|
|
/// size(), x0() and pyramid().
|
|
class Series {
|
|
public:
|
|
virtual ~Series() = default;
|
|
|
|
virtual u64 size() const = 0;
|
|
/// x of sample 0, i.e. of the oldest sample currently held.
|
|
virtual f64 x0() const = 0;
|
|
/// Uniform x spacing between consecutive samples.
|
|
virtual f64 dx() const = 0;
|
|
virtual Range x_bounds() const = 0;
|
|
virtual Range y_bounds() const = 0;
|
|
virtual const MinMaxPyramid& pyramid() const = 0;
|
|
|
|
/// Appends interleaved (x, y) pairs in data coordinates for level `level`.
|
|
///
|
|
/// Level 0 emits the raw samples of [begin, end). Level >= 1 emits one (min, max)
|
|
/// envelope pair per *complete* level bucket wholly inside the retained window,
|
|
/// bounded by the two partial buckets at the edges of the requested range — the
|
|
/// bucket the window starts inside and the bucket the newest samples are in —
|
|
/// which it emits as raw samples through copy_raw(). A bucket that is only partly
|
|
/// retained holds aggregates of samples the window no longer has and a partial
|
|
/// trailing bucket is not stored at all, so neither may be drawn as an envelope.
|
|
///
|
|
/// The emitted geometry therefore always spans [begin, end) exactly, for at most
|
|
/// two buckets of extra raw work (about two pixels at the level level_for()
|
|
/// picks), and never reaches outside the retained window. Pairs are appended to
|
|
/// out_xy, which is never cleared.
|
|
virtual void gather(u32 level, u64 begin, u64 end, std::vector<f32>& out_xy) const = 0;
|
|
|
|
/// Exact min/max, sum and sum-of-squares over [begin, end).
|
|
/// Preconditions: begin < end, end <= size(); a degenerate range yields a
|
|
/// zero-span Range and zero sums. Implemented once, non-virtually, over
|
|
/// copy_raw() in src/data/series.cpp.
|
|
Range reduce(u64 begin, u64 end) const;
|
|
f64 sum(u64 begin, u64 end) const;
|
|
f64 sumsq(u64 begin, u64 end) const;
|
|
|
|
protected:
|
|
/// Copies raw y samples for [begin, end) into `out`, which the caller sized to
|
|
/// (end - begin). Handles ring wraparound. Only ever called with the small edge
|
|
/// spans of the queries above, never on a per-sample path. Out-of-range spans
|
|
/// are clamped and the unwritten tail is zero-filled.
|
|
virtual void copy_raw(u64 begin, u64 end, f32* out) const = 0;
|
|
|
|
/// The shared body of the concrete gather() overrides: raw samples at level 0,
|
|
/// bucket min/max envelope above it.
|
|
void gather_impl(u32 level, u64 begin, u64 end, std::vector<f32>& out_xy) const;
|
|
|
|
private:
|
|
/// [begin, end) split into the bucket-aligned interior the pyramid can answer
|
|
/// exactly, plus the at most two partial edge spans it cannot.
|
|
struct QueryParts {
|
|
u64 interior_begin = 0, interior_end = 0; // whole level-0 buckets, may be empty
|
|
u64 left_begin = 0, left_end = 0; // partial head bucket
|
|
u64 right_begin = 0, right_end = 0; // partial tail bucket
|
|
};
|
|
/// Needs the pyramid's window base: the bucket grid it aligns to is absolute,
|
|
/// while begin/end are window coordinates.
|
|
QueryParts split_query(u64 begin, u64 end) const;
|
|
/// Reads both edge spans through copy_raw() into `out` (which must hold at
|
|
/// least 2*kBucket samples) and returns how many were written.
|
|
u64 copy_edges(const QueryParts& parts, f32* out) const;
|
|
/// Appends the raw samples of [begin, end) as (x, y) pairs, in copy_raw()'s
|
|
/// bounded chunks. The one path that reads samples rather than aggregates: level
|
|
/// 0 is entirely this, and a level >= 1 gather uses it for the two partial edge
|
|
/// buckets a pyramid of complete buckets cannot answer for. Precondition:
|
|
/// begin < end, end <= size().
|
|
void gather_raw(u64 begin, u64 end, std::vector<f32>& out_xy) const;
|
|
};
|
|
|
|
} // namespace plot::data
|