scene_node.hpp

Go to the documentation of this file.

// SceneNode — abstract base of Pulp's retained vector scene graph.
//
// License-lineage note: the Pulp scene-graph primitives use Pulp-native
// names (`VectorScene`, `SceneNode`, `ScenePath`, `SceneShape`,
// `SceneImage`, `SceneText`, `SceneGroup`) rather than any reference
// framework's class names. The design is derived from Skia's
// SVG rendering literature plus what custom-paint widgets actually need
// (mutate a sub-tree → re-paint only its bounding box), not from any
// single C++ framework's headers.
#pragma once
 
#include <pulp/canvas/canvas.hpp>
 
#include <cstdint>
#include <string>
 
namespace pulp::canvas {
 
class SceneGroup;  // fwd-decl for parent pointer

struct SceneRect {
    float x = 0.0f;
    float y = 0.0f;
    float w = 0.0f;
    float h = 0.0f;
 
    constexpr bool empty() const { return w <= 0.0f || h <= 0.0f; }

    constexpr SceneRect united(const SceneRect& other) const {
        if (empty()) return other;
        if (other.empty()) return *this;
        const float minx = x < other.x ? x : other.x;
        const float miny = y < other.y ? y : other.y;
        const float maxx = (x + w) > (other.x + other.w) ? (x + w) : (other.x + other.w);
        const float maxy = (y + h) > (other.y + other.h) ? (y + h) : (other.y + other.h);
        return {minx, miny, maxx - minx, maxy - miny};
    }
 
    constexpr bool operator==(const SceneRect& o) const {
        return x == o.x && y == o.y && w == o.w && h == o.h;
    }
    constexpr bool operator!=(const SceneRect& o) const { return !(*this == o); }
};

struct SceneTransform {
    float a = 1.0f, b = 0.0f;
    float c = 0.0f, d = 1.0f;
    float e = 0.0f, f = 0.0f;
 
    static constexpr SceneTransform identity() { return {}; }
    static constexpr SceneTransform translation(float tx, float ty) {
        return {1, 0, 0, 1, tx, ty};
    }
 
    constexpr bool is_identity() const {
        return a == 1.0f && b == 0.0f && c == 0.0f && d == 1.0f && e == 0.0f && f == 0.0f;
    }

    constexpr SceneTransform composed_with(const SceneTransform& r) const {
        return {
            a * r.a + c * r.b,
            b * r.a + d * r.b,
            a * r.c + c * r.d,
            b * r.c + d * r.d,
            a * r.e + c * r.f + e,
            b * r.e + d * r.f + f,
        };
    }

    SceneRect map_rect(const SceneRect& r) const;
};

enum class SceneNodeKind {
    group,
    path,
    shape,
    image,
    text,
};

class SceneNode {
public:
    explicit SceneNode(SceneNodeKind kind) : kind_(kind) {}
    virtual ~SceneNode() = default;
 
    SceneNode(const SceneNode&) = delete;
    SceneNode& operator=(const SceneNode&) = delete;
 
    SceneNodeKind kind() const { return kind_; }
 
    // ── Identity (debugging / SVG `<g id="...">` round-trip) ───────────
    const std::string& id() const { return id_; }
    void set_id(std::string v) { id_ = std::move(v); /* identity-only, no dirty */ }
 
    // ── Visibility ───────────────────────────────────────────────────────
    bool visible() const { return visible_; }
    void set_visible(bool v) {
        if (visible_ == v) return;
        visible_ = v;
        mark_dirty();
    }
 
    // ── Opacity ──────────────────────────────────────────────────────────
    float opacity() const { return opacity_; }
    void set_opacity(float a) {
        if (opacity_ == a) return;
        opacity_ = a;
        mark_dirty();
    }
 
    // ── Transform ────────────────────────────────────────────────────────
    const SceneTransform& transform() const { return transform_; }
    void set_transform(const SceneTransform& t) {
        if (transform_.a == t.a && transform_.b == t.b &&
            transform_.c == t.c && transform_.d == t.d &&
            transform_.e == t.e && transform_.f == t.f) return;
        transform_ = t;
        mark_dirty();
    }
 
    // ── Parent linkage (set by SceneGroup) ───────────────────────────────
    SceneGroup* parent() const { return parent_; }
 
    // ── Bounds ───────────────────────────────────────────────────────────
    virtual SceneRect local_bounds() const = 0;

    SceneRect transformed_local_bounds() const {
        return transform_.map_rect(local_bounds());
    }
 
    // ── Paint ────────────────────────────────────────────────────────────
    virtual void paint_geometry(Canvas& canvas) const = 0;
 
    // ── Dirty tracking ───────────────────────────────────────────────────
    bool dirty() const { return dirty_; }

    void mark_dirty();

    void mark_clean(const SceneRect& painted_scene_bounds) {
        dirty_ = false;
        last_painted_bounds_ = painted_scene_bounds;
    }

    const SceneRect& last_painted_bounds() const { return last_painted_bounds_; }
 
protected:
    friend class SceneGroup;  // sets parent_ during add_child()
 
private:
    SceneNodeKind kind_;
    std::string id_;
    SceneGroup* parent_ = nullptr;
    SceneTransform transform_{};
    float opacity_ = 1.0f;
    bool visible_ = true;
    bool dirty_ = true;
    SceneRect last_painted_bounds_{};
};
 
}  // namespace pulp::canvas