scene.hpp

Go to the documentation of this file.

// VectorScene — the root of Pulp's retained vector scene graph.
//
// License-lineage note: the Pulp-side primitives use Pulp-native names
// (`VectorScene`, `SceneNode`, `ScenePath`, `SceneShape`, `SceneImage`,
// `SceneText`, `SceneGroup`) rather than any reference framework's
// class names.
//
// Why a retained scene graph for Pulp:
//   - Custom paint widgets that build a vector composition once and
//     mutate a child's opacity / transform every frame should not have
//     to re-stream the whole command buffer to the canvas. The retained
//     model lets them surface only the dirty sub-tree to the host.
//   - SVG import (via the existing nanosvg path in `core/canvas/svg.hpp`)
//     wants a structured destination so the host can address individual
//     shapes — toggle visibility, swap a fill, animate a transform —
//     without re-parsing.
//   - Design-tool imports need a one-to-one container per design node so
//     round-tripping stays predictable.
//
// Current behavior:
//   - SVG loads as a `VectorScene` or `SceneGroup`.
//   - Mutating a child's opacity re-paints only that sub-tree's
//     bounding box (see `take_dirty_rect()`).
//   - Renders through the existing Canvas backends.
#pragma once
 
#include <pulp/canvas/scene/scene_group.hpp>
#include <pulp/canvas/scene/scene_image.hpp>
#include <pulp/canvas/scene/scene_node.hpp>
#include <pulp/canvas/scene/scene_path.hpp>
#include <pulp/canvas/scene/scene_shape.hpp>
#include <pulp/canvas/scene/scene_text.hpp>
 
#include <memory>
#include <string>
 
namespace pulp::canvas {
 
class VectorScene {
public:
    VectorScene() : root_(std::make_unique<SceneGroup>()) {}
 
    SceneGroup& root() { return *root_; }
    const SceneGroup& root() const { return *root_; }

    void set_root(std::unique_ptr<SceneGroup> r) {
        if (!r) r = std::make_unique<SceneGroup>();
        root_ = std::move(r);
        dirty_rect_pending_ = root_->transformed_local_bounds();
    }
 
    // ── Painting ─────────────────────────────────────────────────────────
    void paint(Canvas& canvas);
 
    // ── Dirty-rect query (the whole point of a retained graph) ───────────
    SceneRect take_dirty_rect();

    SceneRect peek_dirty_rect() const { return dirty_rect_pending_; }

    void note_node_dirtied(const SceneNode& node);
 
    // ── SVG ingest ───────────────────────────────────────────────────────
    static VectorScene from_svg_string(const std::string& svg_data);

    static VectorScene from_svg_file(const std::string& path);
 
private:
    std::unique_ptr<SceneGroup> root_;
    SceneRect dirty_rect_pending_{};  // accumulates across mutations
};
 
}  // namespace pulp::canvas