ECS Components

Components are the data layer of the ECS architecture. More...

Classes
struct	donner::svg::components::DirtyFlagsComponent
	Tracks which computed properties are stale and need recomputation after a DOM mutation. More...
struct	donner::svg::components::NodeLifetimeComponent
	Tracks whether an SVG DOM node is attached to the document tree or currently detached. More...
struct	donner::svg::compositor::CompositorHintComponent
	Author-layer ECS component carrying the set of weighted hints published against an entity. More...
struct	donner::svg::compositor::ComputedLayerAssignmentComponent
	Resolved-layer ECS component written by LayerResolver each frame; must not be hand-edited. More...

Detailed Description

Components are the data layer of the ECS architecture.

Each component holds a specific piece of state and is attached to an entity. Components contain no logic — systems read and write them.

Components are typically small structs or classes that store the results of a computation stage (e.g., computed styles, resolved transforms, cached geometry). They are attached to entities via the entt registry and accessed by systems during processing.

---

Class Documentation

donner::svg::components::DirtyFlagsComponent

struct donner::svg::components::DirtyFlagsComponent

Tracks which computed properties are stale and need recomputation after a DOM mutation.

Attached to entities that have been mutated since the last render. Systems check these flags during createComputedComponents() to skip clean entities and only recompute what changed.

Public Types
enum	Flags : uint16_t {   None = 0 ,   Style = 1 << 0 ,   Layout = 1 << 1 ,   Transform = 1 << 2 ,   WorldTransform = 1 << 3 ,   Shape = 1 << 4 ,   Paint = 1 << 5 ,   Filter = 1 << 6 ,   RenderInstance = 1 << 7 ,   ShadowTree = 1 << 8 ,   TextGeometry = 1 << 9 ,   StyleCascade = Style | Paint | Filter | RenderInstance ,   LayoutCascade = Layout | Transform | WorldTransform | RenderInstance ,   All = 0xFFFF }
	Individual dirty flags for each computation stage. More...
Public Member Functions
void	mark (uint16_t f)
	Mark additional flags as dirty.
bool	test (uint16_t f) const
	Test whether any of the given flags are set.
void	clear (uint16_t f)
	Clear specific flags.
void	clearAll ()
	Clear all flags.
Public Attributes
uint16_t	flags = Flags::None
	Bitfield of dirty flags.

Member Enumeration Documentation

Flags

enum donner::svg::components::DirtyFlagsComponent::Flags : uint16_t

Individual dirty flags for each computation stage.

Enumerator
Style	ComputedStyleComponent needs recomputation.
Layout	ComputedSizedElementComponent / viewBox needs recomputation.
Transform	ComputedLocalTransformComponent needs recomputation.
WorldTransform	ComputedAbsoluteTransformComponent needs recomputation.
Shape	ComputedPathComponent needs recomputation.
Paint	ResolvedPaintServer (fill/stroke) needs re-resolution.
Filter	Filter effect chain needs re-resolution.
RenderInstance	RenderingInstanceComponent needs update.
ShadowTree	Shadow tree needs re-instantiation.
TextGeometry	ComputedTextGeometryComponent needs recomputation.
StyleCascade	Compound flag: style change that may affect paint, filter, and render instance.
LayoutCascade	Compound flag: layout change that affects transforms and render instance.
All	All flags set.

donner::svg::components::NodeLifetimeComponent

struct donner::svg::components::NodeLifetimeComponent

Tracks whether an SVG DOM node is attached to the document tree or currently detached.

This is the first step toward collecting removed subtrees without breaking public DOM handles. Attached nodes are reachable from the document root. Detached nodes retain their internal subtree links, but their detached root is recorded so a later collector can reclaim the whole subtree once no public handles or render snapshots retain it.

Collaboration diagram for donner::svg::components::NodeLifetimeComponent:

Public Types
enum class	TreeState : uint8_t {   Attached ,   Detached ,   Destroying }
	Tree reachability state for the node. More...
Public Member Functions
	NodeLifetimeComponent ()=default
	Create lifetime state with a fresh public-handle control block.
	NodeLifetimeComponent (const NodeLifetimeComponent &other)
	Copy lifetime metadata while starting a fresh public-handle control block.
NodeLifetimeComponent &	operator= (const NodeLifetimeComponent &other)
	Assign lifetime metadata while starting a fresh public-handle control block.
	NodeLifetimeComponent (NodeLifetimeComponent &&other) noexcept=default
	Moving lifetime components is allowed.
NodeLifetimeComponent &	operator= (NodeLifetimeComponent &&other) noexcept=default
	Moving lifetime components is allowed.
void	markAttached ()
	Mark this node as attached to the document tree.
void	markDetached (Entity root)
	Mark this node as part of a detached subtree.
void	markDestroying ()
	Mark this node as being reclaimed by the detached-subtree collector.
bool	isAttached () const
	Returns true if this node is currently attached to the document tree.
std::uint32_t	externalRefCount () const
	Number of public DOM wrappers currently retaining this node.
Public Attributes
TreeState	treeState = TreeState::Detached
	Current tree reachability.
Entity	detachedRoot = entt::null
	Detached subtree root, or null if attached.
std::uint32_t	generation = 0
	Reserved for future lifetime-aware handles.
std::shared_ptr< NodeExternalRefState >	externalRefs
	Public DOM wrapper control block.

Member Enumeration Documentation

TreeState

enum class donner::svg::components::NodeLifetimeComponent::TreeState : uint8_t

strong

Tree reachability state for the node.

Enumerator
Attached	Reachable from the document root.
Detached	Not reachable from the document root.
Destroying	Being reclaimed by the detached-subtree collector.

Constructor & Destructor Documentation

NodeLifetimeComponent()

donner::svg::components::NodeLifetimeComponent::NodeLifetimeComponent ( const NodeLifetimeComponent & other )

inline

Copy lifetime metadata while starting a fresh public-handle control block.

Component copies are used for cloned ECS storage; public wrappers for the source entity must not retain the copied entity.

Parameters

other

Source lifetime component.

Member Function Documentation

markDetached()

void donner::svg::components::NodeLifetimeComponent::markDetached ( Entity root )

inline

Mark this node as part of a detached subtree.

Parameters

root	Root entity of the detached subtree.

operator=()

NodeLifetimeComponent & donner::svg::components::NodeLifetimeComponent::operator= ( const NodeLifetimeComponent & other )

inline

Assign lifetime metadata while starting a fresh public-handle control block.

Parameters

other

Source lifetime component.

Member Data Documentation

externalRefs

std::shared_ptr<NodeExternalRefState> donner::svg::components::NodeLifetimeComponent::externalRefs

Initial value:

=
      std::make_shared<NodeExternalRefState>()

Public DOM wrapper control block.

donner::svg::compositor::CompositorHintComponent

struct donner::svg::compositor::CompositorHintComponent

Author-layer ECS component carrying the set of weighted hints published against an entity.

Multiple sources may hint the same entity at the same time. The resolver sums weights to rank candidates for layer assignment, except that any Mandatory hint short-circuits the calculation to infinite weight (UINT32_MAX) — mandatory hints are non-contestable.

Storage is a plain std::vector<HintEntry> — see Non-Goal 3 (sequential, single-threaded) in the design doc. Hints are typically 1–3 per entity.

This component mirrors StyleComponent in the CSS engine: it is the author-layer input to a resolver that produces a ComputedLayerAssignmentComponent.

Collaboration diagram for donner::svg::compositor::CompositorHintComponent:

Public Member Functions
void	addHint (HintSource source, uint16_t weight)
	Append a hint. Does not deduplicate — the same (source, weight) pair may appear more than once.
bool	removeFirstMatching (HintSource source, uint16_t weight)
	Remove exactly one entry whose source and weight both match.
uint32_t	totalWeight () const
	Saturating sum of all entry weights.
bool	empty () const
	Returns true if the hint list is empty.
Public Attributes
std::vector< HintEntry >	entries
	All hint entries currently attached to this entity.

Member Function Documentation

removeFirstMatching()

bool donner::svg::compositor::CompositorHintComponent::removeFirstMatching ( HintSource source, uint16_t weight )

inline

Remove exactly one entry whose source and weight both match.

Used by ScopedCompositorHint on destruction. If duplicate entries exist, only the first matching one is removed — callers that stacked duplicates should drop their handles in LIFO order.

Returns

true if an entry was removed, false if no match was found.

totalWeight()

uint32_t donner::svg::compositor::CompositorHintComponent::totalWeight ( ) const

inlinenodiscard

Saturating sum of all entry weights.

Any Mandatory hint short-circuits the result to UINT32_MAX — the infinite-weight sentinel. Otherwise returns the clamped sum of weight fields (clamped at UINT32_MAX - 1 so Mandatory remains distinguishable). With a std::vector of uint16_t weights the sum cannot realistically overflow uint32_t, but we clamp defensively.

donner::svg::compositor::ComputedLayerAssignmentComponent

struct donner::svg::compositor::ComputedLayerAssignmentComponent

Resolved-layer ECS component written by LayerResolver each frame; must not be hand-edited.

This mirrors the StyleComponent → ComputedStyleComponent split in Donner's CSS engine: author-layer hints live in CompositorHintComponent, and the resolver collapses them into this computed component.

Entities without this component render into the root layer (implicit layerId == 0).

Class Members
uint32_t	layerId = 0	Unique identifier for the compositor layer this entity belongs to. 0 is the root layer.