path.hpp

Go to the documentation of this file.

#pragma once
 
// Path — a retained 2D vector path VALUE type.
//
// A path is fundamentally a value: you build an icon once (in a constructor,
// or from an SVG string at load time), store it as a member, transform copies
// of it, and fill it every frame. The immediate-mode builder on `Canvas`
// (`begin_path` / `move_to` / ... / `fill_current_path`) cannot express that —
// it streams geometry into the backend and forgets it. `Path` is the retained
// half of the pair.
//
//   Path icon = Path::from_svg_string("M0 0 L10 0 L5 8 Z");   // once
//   ...
//   void paint(Canvas& c) {                                    // every frame
//       c.set_fill_color(color);
//       c.fill_path(icon, FillRule::nonzero);
//   }
//
// ── Copy cost ────────────────────────────────────────────────────────────
// Copying a Path is O(1): the geometry sits behind a copy-on-write buffer, so
// a copy is a refcount bump, not a memcpy. Mutating a shared Path detaches it
// first (O(n), once). This is deliberate — if copying were O(n) every caller
// would hoist paths out of `paint()` and the value semantics would be a lie.
// `test_canvas_path.cpp` pins this with a benchmark.
//
// ── Curve representation ─────────────────────────────────────────────────
// Every curve is stored as a line, quadratic, or cubic. Arcs, ellipses, and
// SVG elliptical-arc segments are flattened to cubics AT BUILD TIME, so the
// verb set is closed at five and every backend (Skia, CoreGraphics, the
// recording target) replays byte-identical geometry. There is no conic verb
// and no backend-specific escape hatch.
//
// ── Threading ────────────────────────────────────────────────────────────
// Standard value-type contract, same as std::vector: concurrent reads of one
// Path are safe; concurrent mutation of the SAME Path object is not. Copies
// handed to other threads are independent even though they share a buffer —
// the copy-on-write detach makes the sharing invisible.
 
#include <pulp/canvas/affine_transform.hpp>
#include <pulp/canvas/rectangle_list.hpp>  // pulp::canvas::Rect2D
 
#include <cstdint>
#include <memory>
#include <optional>
#include <string>
#include <vector>
 
namespace pulp::canvas {

enum class FillRule { nonzero, evenodd };

enum class LineCap { butt, round, square };

enum class LineJoin { miter, round, bevel };

struct StrokeStyle {
    float width = 1.0f;
    LineCap cap = LineCap::butt;
    LineJoin join = LineJoin::miter;
    float miter_limit = 4.0f;

    std::vector<float> dash;
    float dash_phase = 0.0f;
 
    bool operator==(const StrokeStyle& o) const {
        return width == o.width && cap == o.cap && join == o.join &&
               miter_limit == o.miter_limit && dash == o.dash &&
               dash_phase == o.dash_phase;
    }
    bool operator!=(const StrokeStyle& o) const { return !(*this == o); }
};
 
class Path {
public:
    enum class Verb : uint8_t {
        move,   
        line,   
        quad,   
        cubic,  
        close,  
    };

    static constexpr int points_for(Verb v) {
        switch (v) {
            case Verb::move:  return 1;
            case Verb::line:  return 1;
            case Verb::quad:  return 2;
            case Verb::cubic: return 3;
            case Verb::close: return 0;
        }
        return 0;
    }

    struct Element {
        Verb verb = Verb::move;
        const Point2D* points = nullptr;  
        int count = 0;
    };
 
    Path() = default;
 
    // Value semantics. Copy is O(1) (copy-on-write); see the header comment.
    Path(const Path&) = default;
    Path& operator=(const Path&) = default;
    Path(Path&&) noexcept = default;
    Path& operator=(Path&&) noexcept = default;
    ~Path() = default;

    bool operator==(const Path& o) const;
    bool operator!=(const Path& o) const { return !(*this == o); }
 
    // ── Building ─────────────────────────────────────────────────────────
    Path& move_to(float x, float y);
    Path& line_to(float x, float y);
    Path& quad_to(float cx, float cy, float x, float y);
    Path& cubic_to(float c1x, float c1y, float c2x, float c2y, float x, float y);

    Path& arc_to(float x1, float y1, float x2, float y2, float radius);
 
    Path& close();

    void clear();
 
    // ── Shape helpers ────────────────────────────────────────────────────
    Path& add_rect(float x, float y, float w, float h);
    Path& add_rect(const Rect2D& r) { return add_rect(r.x, r.y, r.width, r.height); }

    Path& add_rounded_rect(float x, float y, float w, float h, float radius);

    Path& add_rounded_rect(float x, float y, float w, float h,
                           float top_left, float top_right,
                           float bottom_right, float bottom_left);
 
    Path& add_ellipse(float cx, float cy, float rx, float ry);
    Path& add_circle(float cx, float cy, float radius) {
        return add_ellipse(cx, cy, radius, radius);
    }

    Path& add_arc(float cx, float cy, float rx, float ry,
                  float start_angle, float sweep_angle);

    Path& add_pie(float cx, float cy, float rx, float ry,
                  float start_angle, float sweep_angle);

    Path& add_polygon(const Point2D* points, size_t count);

    Path& add_path(const Path& other,
                   const AffineTransform& transform = AffineTransform::identity());
 
    // ── Transforms ───────────────────────────────────────────────────────
    void apply_transform(const AffineTransform& t);

    Path transformed(const AffineTransform& t) const;

    AffineTransform transform_to_fit(float x, float y, float w, float h,
                                     bool preserve_proportions) const;

    void scale_to_fit(float x, float y, float w, float h,
                      bool preserve_proportions);
 
    // ── Queries ──────────────────────────────────────────────────────────
    bool is_empty() const { return !data_ || data_->verbs.empty(); }

    size_t verb_count() const { return data_ ? data_->verbs.size() : 0; }

    Rect2D bounds() const;

    Rect2D control_bounds() const;

    bool contains(Point2D p, FillRule rule = FillRule::nonzero) const;
    bool contains(float x, float y, FillRule rule = FillRule::nonzero) const {
        return contains(Point2D{x, y}, rule);
    }

    std::optional<Point2D> current_point() const;
 
    // ── Iteration ────────────────────────────────────────────────────────
    class Iterator {
    public:
        Iterator() = default;
        Iterator(const Path* path, size_t verb_index, size_t point_index)
            : path_(path), verb_(verb_index), point_(point_index) {}
 
        Element operator*() const;
        Iterator& operator++();
        bool operator==(const Iterator& o) const { return verb_ == o.verb_ && path_ == o.path_; }
        bool operator!=(const Iterator& o) const { return !(*this == o); }
 
    private:
        const Path* path_ = nullptr;
        size_t verb_ = 0;
        size_t point_ = 0;
    };
 
    Iterator begin() const { return Iterator(this, 0, 0); }
    Iterator end() const { return Iterator(this, verb_count(), 0); }

    template <typename Sink>
    void replay(Sink& sink) const {
        for (Element el : *this) {
            switch (el.verb) {
                case Verb::move:
                    sink.move_to(el.points[0].x, el.points[0].y);
                    break;
                case Verb::line:
                    sink.line_to(el.points[0].x, el.points[0].y);
                    break;
                case Verb::quad:
                    sink.quad_to(el.points[0].x, el.points[0].y,
                                 el.points[1].x, el.points[1].y);
                    break;
                case Verb::cubic:
                    sink.cubic_to(el.points[0].x, el.points[0].y,
                                  el.points[1].x, el.points[1].y,
                                  el.points[2].x, el.points[2].y);
                    break;
                case Verb::close:
                    sink.close_path();
                    break;
            }
        }
    }

    struct FlatSubpath {
        std::vector<Point2D> points;
        bool closed = false;
    };
    std::vector<FlatSubpath> flatten(float tolerance = 0.25f) const;
 
    // ── SVG ──────────────────────────────────────────────────────────────
    static Path from_svg_string(const std::string& d);

    std::string to_svg_string() const;
 
private:
    // Copy-on-write geometry buffer. Verbs and points are stored in parallel
    // arrays rather than as a fat 32-byte command struct: a `line_to` costs
    // 1 byte + 8 bytes here, versus 32 bytes in a tagged-union layout.
    struct Data {
        std::vector<Verb> verbs;
        std::vector<Point2D> points;
    };

    Data& mutable_data();

    void append_arc_cubics(float cx, float cy, float rx, float ry,
                           float start_angle, float sweep_angle,
                           const AffineTransform& xf = AffineTransform::identity());

    void append_svg_arc(Point2D from, float rx, float ry, float x_axis_rotation_deg,
                        bool large_arc, bool sweep, Point2D to);
 
    std::shared_ptr<Data> data_;
 
    // The bounds cache lives on the Path, not in the shared Data, so two
    // copies sharing one buffer can never race computing it. Copies inherit a
    // valid cache — the geometry is identical, after all.
    mutable bool bounds_valid_ = false;
    mutable Rect2D bounds_cache_{};
 
    friend class Iterator;
};
 
}  // namespace pulp::canvas