CompositorController.h File Reference

#include <atomic>
#include <cstddef>
#include <cstdint>
#include <memory>
#include <optional>
#include <string>
#include <unordered_map>
#include <utility>
#include <vector>
#include "donner/base/Box.h"
#include "donner/base/EcsRegistry.h"
#include "donner/base/Transform.h"
#include "donner/svg/SVGDocument.h"
#include "donner/svg/compositor/ComplexityBucketer.h"
#include "donner/svg/compositor/CompositorLayer.h"
#include "donner/svg/compositor/LayerResolver.h"
#include "donner/svg/compositor/MandatoryHintDetector.h"
#include "donner/svg/compositor/ScopedCompositorHint.h"
#include "donner/svg/renderer/RendererInterface.h"

Include dependency graph for CompositorController.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	donner::svg::compositor::CompositorTile
	A single bitmap cache unit the compositor exposes for GPU upload — either a static segment (non-promoted content between promoted layers) or a promoted layer's own rasterization. More...
class	donner::svg::compositor::CancellationToken
	Design doc 0033 §M4 — cancellation handle for CompositorController:: renderFrame. The token wraps a single std::atomic<bool>; the compositor's per-layer / per-segment rasterize loops poll isCancelled() at coarse safe points (between rasterizeLayer / rasterizeStaticSegment calls, not mid-rasterize, per design doc 0033 §R3 / §D4) and bail early when set. More...
struct	donner::svg::compositor::CompositorConfig
	Runtime feature gates for CompositorController. More...
class	donner::svg::compositor::CompositorController
	Controls compositor layer promotion/demotion and orchestrates composited rendering. More...
struct	donner::svg::compositor::CompositorController::PromoteResult
	Result of requesting an editor-facing compositor presentation plan. More...
struct	donner::svg::compositor::CompositorController::FastPathCounters
	Diagnostic counters for the translation-only fast path. Tests read these to assert that a drag is taking the fast path every frame, not falling through to prepareDocumentForRendering. More...
struct	donner::svg::compositor::CompositorController::LayerInspectorRow
	One row of diagnostic state per active compositor layer, intended for the editor's read-only layer-inspector panel (design doc 0033 M1). Cheap to build, cheap to copy: a few ints and one short string per layer. More...
struct	donner::svg::compositor::CompositorController::SegmentInspectorRow
	One row of diagnostic state per static segment (the non-promoted content between promoted layers, plus the pre-first and post-last slots). Sized N+1 where N is layerCount(). More...
struct	donner::svg::compositor::CompositorController::StaticSpanPlan
	Conservative draw-cost plan for one static segment slot. More...
struct	donner::svg::compositor::CompositorController::CompositeTileSnapshot
	One row of the unified "everything composited together" view that the layer-inspector panel renders in paint order — design doc 0033 §M1++. Mirrors what composeLayers actually draws so the operator sees the same sequence of blits the renderer performs. More...
struct	donner::svg::compositor::CompositorController::RenderFrameStats
	Worker render costs from the most recent renderFrame call, split by whether the work was caused by immediate-mode transient spans or retained cached tiles. More...
struct	donner::svg::compositor::CompositorController::StateSnapshot

Namespaces
namespace	donner
	Top-level Donner namespace, which is split into different sub-namespaces such as donner::svg and donner::css.
namespace	donner::svg
	Donner SVG library, which can load, manipulate and render SVG files.

Enumerations
enum class	donner::svg::compositor::CompositorTileBitmapPayload : uint8_t {   All ,   DragTargetOnly ,   ImmediateOnly ,   ImmediateAndDragTargetOnly ,   MetadataOnly }
	Bitmap payload policy for CompositorController::snapshotTilesForUpload. More...
enum class	donner::svg::compositor::StaticSpanMode : uint8_t {   CachedTile ,   Immediate }
	Presentation mode chosen for one non-promoted paint-order span. More...

Functions
std::unordered_map< Entity, Entity >	donner::svg::compositor::BuildStructuralEntityRemap (const SVGDocument &oldDoc, const SVGDocument &newDoc)
	Walk the XML trees of oldDoc and newDoc in lockstep and build a remap from old-registry entity ids → new-registry entity ids, suitable for CompositorController::remapAfterStructuralReplace.

Variables
constexpr int	donner::svg::compositor::kMaxCompositorLayers = 32
	Maximum number of compositor layers that can be simultaneously active.
constexpr size_t	donner::svg::compositor::kMaxCompositorMemoryBytes = 1024ull * 1024ull * 1024ull
	Maximum total memory budget for compositor layer bitmaps, in bytes.

---

Class Documentation

donner::svg::compositor::CompositorController::FastPathCounters

struct donner::svg::compositor::CompositorController::FastPathCounters

Diagnostic counters for the translation-only fast path. Tests read these to assert that a drag is taking the fast path every frame, not falling through to prepareDocumentForRendering.

Class Members
uint64_t	fastPathFrames = 0	Incremented every frame that takes the fast path and successfully handled every dirty entity via a compose-transform update.
uint64_t	noDirtyFrames = 0	Incremented every frame where the fast-path eligibility check wasn't reached because no entities were dirty (e.g. page-load, selection-change-only frames).
uint64_t	slowPathFramesWithDirty = 0	Incremented every frame whose dirty-entity set disqualified the fast path (transform+other flags, subtree with non-translation delta, missing layer, etc.) and fell through to the slow path.

donner::svg::compositor::CompositorController::LayerInspectorRow

struct donner::svg::compositor::CompositorController::LayerInspectorRow

One row of diagnostic state per active compositor layer, intended for the editor's read-only layer-inspector panel (design doc 0033 M1). Cheap to build, cheap to copy: a few ints and one short string per layer.

Collaboration diagram for donner::svg::compositor::CompositorController::LayerInspectorRow:

Class Members
Vector2i	bitmapSize = Vector2i::Zero()	Pixel size of the layer's cached bitmap. Vector2i::Zero() when the layer has not yet been rasterized (hasValidBitmap false).
Vector2d	canvasOffset = Vector2d::Zero()	Canvas-space top-left position where this layer's bitmap blits back. Vector2d::Zero() for canvas-sized layers; non-zero for intrinsic-sized layers (design doc 0033 §M2).
bool	dirty = false	Whether this layer is currently flagged dirty (a rasterize is pending on the next renderFrame call).
Entity	entity = entt::null	Root entity of the promoted subtree.
FallbackReason	fallbackReasons = FallbackReason::None	Raw fallback flags (handy for tests; the panel renders fallbackReasonsText for display).
string	fallbackReasonsText	Pre-formatted fallback flag list (e.g. "Filter | IsolatedLayer").
uint64_t	generation = 0	Monotonic generation counter from CompositorLayer::generation.
bool	hasValidBitmap = false	Whether the layer has a valid cached bitmap.
double	lastRasterizeMs = 0.0	Wall-clock duration of the most recent rasterize, in ms.
uint32_t	layerId = 0	Layer's stable numeric id (CompositorLayer::id).
uint32_t	rasterizeCount = 0	Cumulative rasterize count from CompositorLayer::rasterizeCount.
Vector2i	thumbnailDims = Vector2i::Zero()	Pixel dimensions of the downsampled thumbnail. Vector2i::Zero() when the layer has no valid bitmap. Otherwise the longer side is kLayerThumbnailMaxSide and the shorter side preserves aspect.
vector< uint8_t >	thumbnailPixels	RGBA8 thumbnail pixels, tightly packed (thumbnailDims.x * 4 row stride), suitable for direct upload via glTexImage2D. Empty when the layer has no valid bitmap.

donner::svg::compositor::CompositorController::SegmentInspectorRow

struct donner::svg::compositor::CompositorController::SegmentInspectorRow

One row of diagnostic state per static segment (the non-promoted content between promoted layers, plus the pre-first and post-last slots). Sized N+1 where N is layerCount().

Collaboration diagram for donner::svg::compositor::CompositorController::SegmentInspectorRow:

Class Members
Vector2i	bitmapSize = Vector2i::Zero()	Pixel dimensions of the cached segment bitmap. Vector2i::Zero() when the slot has no bitmap yet.
Vector2d	canvasOffset = Vector2d::Zero()	Canvas-space top-left offset where this segment's bitmap blits back (non-zero only on the tight-bounded path, design doc 0027).
bool	dirty = false	Whether this slot is currently flagged dirty (a rasterize is pending on the next renderFrame call).
uint64_t	generation = 0	Monotonic per-slot generation counter.
bool	hasValidBitmap = false	Whether the slot has a non-empty cached bitmap.
double	lastRasterizeMs = 0.0	Wall-clock duration of the most recent rasterize, in ms. Zero when this slot has never been rasterized in the current session.
size_t	slotIndex = 0	Slot index (0..N inclusive). Segment 0 is the pre-first-layer content; segment N is the post-last-layer content.

donner::svg::compositor::CompositorController::StaticSpanPlan

struct donner::svg::compositor::CompositorController::StaticSpanPlan

Conservative draw-cost plan for one static segment slot.

Collaboration diagram for donner::svg::compositor::CompositorController::StaticSpanPlan:

Class Members
Box2d	boundsCanvas	Snapped canvas-space bounds used for immediate eligibility.
bool	demotedDynamicImmediate = false	True when the span was dynamically immediate last frame but this render exceeded budget, so the freshly-rendered payload is retained as a cached tile instead of staying immediate.
bool	dynamicHeuristicImmediate = false	True when timing expanded the span into immediate presentation.
double	estimatedCacheOverheadCost = 0.0	Relative fixed/cache memory cost avoided by immediate presentation.
int	estimatedDrawOps = 0	Estimated number of direct geometry draws in the span.
int	estimatedPathVerbs = 0	Estimated number of path verbs across direct geometry draws.
double	estimatedRedrawCost = 0.0	Relative redraw cost from tight area and geometry complexity.
uint64_t	estimatedRetainedBytes = 0	Estimated presentation texture bytes retained by a cached tile.
Entity	firstEntity = entt::null	First render instance covered by the span, or null for an empty slot.
bool	hasExpensiveEffect = false	True when the span uses effects or resources that force cached-tile presentation.
double	immediateBudgetChargeMs = 0.0	Budget charged by this span when it is immediate.
double	immediateBudgetMs = 0.0	Total dynamic immediate-span frame budget for 120 Hz interaction.
Entity	lastEntity = entt::null	Last render instance covered by the span, or null for an empty slot.
double	measuredRasterizeMs = 0.0	Raster time from the most recent span render.
StaticSpanMode	mode = StaticSpanMode::CachedTile	Presentation mode selected for this span.
size_t	slotIndex = 0	Slot index in the static segment array.
string	spanRangeLabel	Human-readable first/last element range covered by this span.
bool	staticHeuristicImmediate = false	True when the static cost heuristic chose immediate presentation.
bool	visible = false	True when the span has a visible, bounded contribution to the canvas.

donner::svg::compositor::CompositorController::RenderFrameStats

struct donner::svg::compositor::CompositorController::RenderFrameStats

Worker render costs from the most recent renderFrame call, split by whether the work was caused by immediate-mode transient spans or retained cached tiles.

Class Members
double	cachedRasterizeMs = 0.0	Segment/layer raster time that produces retained cached bitmap/texture tiles.
int	cachedTileCount = 0	Count of segment/layer tiles charged to cached raster work.
double	immediateRasterizeMs = 0.0	Segment raster time caused by immediate-mode static spans.
int	immediateTileCount = 0	Count of static spans charged to immediate raster work.

donner::svg::compositor::CompositorController::StateSnapshot

struct donner::svg::compositor::CompositorController::StateSnapshot

Collaboration diagram for donner::svg::compositor::CompositorController::StateSnapshot:

Class Members
uint32_t	activeHintsCount = 0	Editor-driven explicit promotions (drag target + selection prewarm). Mandatory-detector hints don't count toward this number — they live in a separate map.
Vector2i	canvasSize = Vector2i::Zero()	Canvas size the compositor most recently rendered against.
Entity	lastPromoteRefusalEntity = entt::null	Entity the failed promoteEntity was called with. entt::null when lastPromoteRefusalReason is None.
PromoteRefusalReason	lastPromoteRefusalReason = PromoteRefusalReason::None	Reason the most-recent promoteEntity call returned false, or None when the most-recent call succeeded (or no call has happened yet). Sticky on failure.
uint32_t	layerCount = 0	Total layers currently in layers_ (mandatory + explicit).
bool	splitPathActive = false	hasSplitStaticLayers() — the editor's drag-overlay fast path is active when this is true.
Entity	splitStaticLayersEntity = entt::null	Entity the compositor cached the bg/fg split for. entt::null when split-path is inactive.

Enumeration Type Documentation

CompositorTileBitmapPayload

enum class donner::svg::compositor::CompositorTileBitmapPayload : uint8_t

strong

Bitmap payload policy for CompositorController::snapshotTilesForUpload.

Enumerator
All	Include every available tile bitmap.
DragTargetOnly	Include only the active drag-target bitmap; keep non-drag tile metadata.
ImmediateOnly	Include only static spans that are planned for immediate presentation.
ImmediateAndDragTargetOnly	Include immediate static spans plus the active drag-target bitmap.
MetadataOnly	Include tile metadata only.

StaticSpanMode

enum class donner::svg::compositor::StaticSpanMode : uint8_t

strong

Presentation mode chosen for one non-promoted paint-order span.

Enumerator
CachedTile	Rasterize once into a cached compositor tile and reuse until dirty.
Immediate	Re-rasterize as a transient tile and do not publish metadata-only reuse.

Function Documentation

BuildStructuralEntityRemap()

std::unordered_map< Entity, Entity > donner::svg::compositor::BuildStructuralEntityRemap ( const SVGDocument & oldDoc, const SVGDocument & newDoc )

nodiscard

Walk the XML trees of oldDoc and newDoc in lockstep and build a remap from old-registry entity ids → new-registry entity ids, suitable for CompositorController::remapAfterStructuralReplace.

Returns an empty map if the two trees are not structurally equivalent — defined as: same preorder walk, same element tag name at every step, and same id attribute at every step (or neither has one). Attribute values other than id are allowed to differ — the drag-end writeback case changes transform values, not tree shape.

The returned map covers every element visited in the walk. The caller is responsible for handing it to remapAfterStructuralReplace on the compositor that was previously tracking oldDoc's entity space.

Variable Documentation

kMaxCompositorMemoryBytes

size_t donner::svg::compositor::kMaxCompositorMemoryBytes = 1024ull * 1024ull * 1024ull

inlineconstexpr

Maximum total memory budget for compositor layer bitmaps, in bytes.

Sized for high-DPI editor sessions with mandatory filter, mask, and isolated-layer promotions plus one active drag target. Scale-band caching should eventually reduce per-layer memory by letting layers live below full canvas resolution.