donner::svg::compositor::ScopedCompositorHint Class Reference

RAII handle that adds a HintEntry to an entity's CompositorHintComponent on construction and removes exactly that entry on destruction. More...

#include "donner/svg/compositor/ScopedCompositorHint.h"

Public Member Functions
	ScopedCompositorHint (Registry &registry, Entity entity, HintSource source, uint16_t weight)
	Attach a hint to entity.
	~ScopedCompositorHint ()
	Removes the hint entry, and drops the component entirely if it was the last entry.
	ScopedCompositorHint (const ScopedCompositorHint &)=delete
ScopedCompositorHint &	operator= (const ScopedCompositorHint &)=delete
	ScopedCompositorHint (ScopedCompositorHint &&other) noexcept
ScopedCompositorHint &	operator= (ScopedCompositorHint &&other) noexcept
Entity	entity () const
	Returns the entity this handle targets. Returns entt::null if the handle has been moved from.
HintSource	source () const
	Returns the hint source. Undefined if the handle has been moved from.
uint16_t	weight () const
	Returns the hint weight. Undefined if the handle has been moved from.
std::optional< InteractionHint >	interactionKind () const
	Returns the InteractionHint kind if this handle was produced by Interaction(); std::nullopt otherwise. Recorded for introspection only — the resolver ignores it.
bool	active () const
	Returns true if this handle is still live (has not been moved from).
void	release ()
	Defuse the handle without touching the registry — subsequent destruction becomes a no-op. Used by CompositorController:: resetAllLayers when the underlying document has been replaced (ReplaceDocumentCommand): the old Registry was destroyed in place and the new one at the same storage address has no knowledge of the entity IDs these hints were built from, so calling registry.valid(old_entity) in the dtor dereferences into entt sparse-set pages that don't exist — SIGSEGV. The old CompositorHint Components went down with the old entity space, so there's nothing to clean up anyway; we just need to make sure the dtor doesn't try.
void	remapToNewEntity (Registry &newRegistry, Entity newEntity)
	Re-target the handle at (newRegistry, newEntity) and publish a fresh hint on the new entity. Used by CompositorController:: remapAfterStructuralReplace to preserve the hint graph across a structurally-equivalent setDocument.

Static Public Member Functions
static ScopedCompositorHint	Mandatory (Registry &registry, Entity entity)
	Factory: publish a Mandatory hint at the infinite-weight sentinel (0xFFFF).
static ScopedCompositorHint	Explicit (Registry &registry, Entity entity, uint16_t weight=0x4000)
	Factory: publish an Explicit hint with caller-chosen weight (defaults to the mid-range weight 0x4000, matching the design-doc default).
static ScopedCompositorHint	Interaction (Registry &registry, Entity entity, InteractionHint kind, uint16_t weight=0x8000)
	Factory: publish an Interaction hint. kind records the interaction semantics for future introspection; the resolver only reads the weight. Default weight 0x8000 matches the Medium slot in the design-doc weight hierarchy.
static ScopedCompositorHint	Animation (Registry &registry, Entity entity, uint16_t weight=0xC000)
	Factory: publish an Animation hint. Default weight 0xC000 matches the High slot in the design-doc weight hierarchy — higher than Interaction so an actively-animating entity wins over a merely-selected one under budget pressure.

Detailed Description

RAII handle that adds a HintEntry to an entity's CompositorHintComponent on construction and removes exactly that entry on destruction.

The primary API for hint producers. Drop the handle and the hint disappears; the resolver will demote the entity on the next frame automatically.

If the target entity has no CompositorHintComponent yet, one is created. When the destructor removes the last entry, the component itself is removed so entity storage stays lean and the resolver's view iteration stays tight.

Non-copyable; movable. A moved-from handle is inert — its destructor does nothing. The usual RAII pattern.

Constructor & Destructor Documentation

ScopedCompositorHint()

donner::svg::compositor::ScopedCompositorHint::ScopedCompositorHint	(	Registry &	registry,
		Entity	entity,
		HintSource	source,
		uint16_t	weight )

Attach a hint to entity.

Creates CompositorHintComponent if absent.

Parameters

registry	Registry owning the entity.
entity	Target entity.
source	Hint source enum.
weight	Hint weight (use 0xFFFF with HintSource::Mandatory).

Member Function Documentation

remapToNewEntity()

void donner::svg::compositor::ScopedCompositorHint::remapToNewEntity ( Registry & newRegistry, Entity newEntity )

inline

Re-target the handle at (newRegistry, newEntity) and publish a fresh hint on the new entity. Used by CompositorController:: remapAfterStructuralReplace to preserve the hint graph across a structurally-equivalent setDocument.

SVGDocument::registry_ is a shared_ptr<Registry> — a setDocument frees the old Registry outright, making any raw Registry* the hint was holding a dangling pointer. The caller must supply the NEW registry's address (the one backing the freshly-swapped document) so we re-seat the pointer before touching any ECS state.

The old entity id is NOT touched — the old Registry is destroyed, and the old CompositorHintComponent went with it.

Preconditions:

• active() — the handle is not moved-from.
• newEntity is a valid entity in newRegistry.

---

The documentation for this class was generated from the following file:

• donner/svg/compositor/ScopedCompositorHint.h