path_measure.hpp

Go to the documentation of this file.

#pragma once
 
// PathMeasure — arc length over a `Path`, measured once and queried forever.
//
// A `Path` knows its verbs; it does not know how long it is. Everything that
// walks a path by DISTANCE rather than by verb — a knob's value arc, a ring
// meter filling to 0.7, an envelope or waveform revealing left to right, a
// label riding a curve — needs arc length, and each of those callers would
// otherwise re-derive it, differently and wrongly.
//
//   PathMeasure m{ring};                       // once, when the ring changes
//   Path filled = m.segment(0.0f, m.length() * value);   // every frame
//
// ── Why this is a value, not a method on Path ────────────────────────────
// Measuring is the expensive half: every quad and cubic is flattened until it
// is flat to `tolerance`, and the cumulative distance table is built. Querying
// is a binary search over that table. Collapsing the two into
// `Path::point_at()` would hide a full re-flatten inside something that reads
// like an accessor, and a per-frame caller would pay it every frame. So the
// expensive intermediate is the public value — the same shape as
// `TextShaper::prepare()` returning `PreparedText`, and for the same reason.
//
// A PathMeasure holds a COPY of the path's geometry, so it stays valid if the
// source `Path` is mutated or destroyed. Copying a Path is O(1), so this is
// cheap.
//
// ── Accuracy ─────────────────────────────────────────────────────────────
// `tolerance` is the maximum distance (in path units) between a flattened
// chord and the true curve. Lengths are therefore slight UNDER-estimates of
// THE PATH'S OWN arc length, converging as tolerance falls. The default of
// 0.25 keeps that error far below a pixel at ordinary widget scale.
//
// "The path's own" is the part worth reading twice. A PathMeasure measures the
// geometry the Path actually holds — never the ideal shape that geometry was
// built to approximate. `Path::add_circle` flattens to four cubics at build
// time (see path.hpp: the verb set is closed, with no conic), and those cubics
// are very slightly longer than the circle they stand for. Measuring a
// radius-100 circle therefore converges to 628.405, not 2*pi*100 = 628.319 —
// about +0.014%, and it converges from BELOW, crossing the true circumference
// once the tolerance is fine enough. Code that needs the analytic
// circumference of a circle should compute it, not measure it.
//
// `segment()` is exact in a different sense: it splits the bracketing curve
// with de Casteljau, so a trimmed cubic comes back as a cubic, not as a
// polyline. Only the DISTANCE at which the split happens carries the
// flattening error; the curve itself is not degraded.
//
// ── Threading ────────────────────────────────────────────────────────────
// Standard value-type contract: concurrent reads of one PathMeasure are safe;
// concurrent mutation is not. All query methods are const.
 
#include <cstddef>
#include <cstdint>
#include <optional>
#include <vector>
 
#include <pulp/canvas/path.hpp>
 
namespace pulp::canvas {

struct PathPose {
    Point2D position{};
    Point2D tangent{1.0f, 0.0f};
};
 
class PathMeasure {
  public:
    static constexpr float default_tolerance = 0.25f;
 
    PathMeasure() = default;

    explicit PathMeasure(const Path& path, float tolerance = default_tolerance);

    float length() const {
        return total_length_;
    }
 
    bool is_empty() const {
        return contours_.empty();
    }

    size_t contour_count() const {
        return contours_.size();
    }
 
    float contour_length(size_t index) const;

    bool contour_is_closed(size_t index) const;

    float contour_start(size_t index) const;

    std::optional<PathPose> pose_at(float distance) const;

    std::optional<Point2D> position_at(float distance) const;

    std::optional<Point2D> tangent_at(float distance) const;

    Path segment(float start, float end) const;
 
  private:
    struct Sample {
        float distance = 0.0f; 
        Point2D position{};
        uint32_t segment_index = 0;
        float t = 0.0f; 
    };

    struct Segment {
        Point2D points[4]{};
        uint8_t count = 2;
        uint32_t contour_index = 0;
    };
 
    struct Contour {
        size_t first_sample = 0;
        size_t sample_count = 0;
        size_t first_segment = 0;
        size_t segment_count = 0;
        float start_distance = 0.0f;
        float length = 0.0f;
        bool closed = false;
    };
 
    std::vector<Sample> samples_;
    std::vector<Segment> segments_;
    std::vector<Contour> contours_;
    float total_length_ = 0.0f;
    float tolerance_ = default_tolerance;

    size_t sample_index_for(float distance) const;
};
 
} // namespace pulp::canvas