Tracks transient scene nodes and removes them according to configurable policies. More...

#include <a3d/extension/Transients.h>

Classes
struct	DistanceLimit
	Maximum permitted world-space distance from a fixed point. More...

struct	Policy
	Removal limits applied globally or to a named group. More...

struct	SweepPolicy
	Scheduling policy controlling when update() performs a sweep. More...

Public Member Functions
	Transients (SweepPolicy sweepPolicy=SweepPolicy::EveryUpdate())
	Creates an empty registry with the supplied sweep policy. More...

	~Transients ()=default
	Destroys the registry without removing tracked nodes. More...

void	track (const std::shared_ptr< Node > &node, const std::string &group={})
	Tracks a transient node and immediately enforces applicable count limits. More...

void	track (const std::vector< std::shared_ptr< Node > > &nodes, const std::string &group={})
	Tracks a collection of nodes as members of the same transient group. More...

void	untrack (const Node &node)
	Stops tracking a node without removing it from its parent. More...

const Policy &	policy () const
	Returns the global removal policy. More...

void	policy (const Policy &policy)
	Replaces the global removal policy. More...

void	groupPolicy (const std::string &group, const Policy &policy)
	Replaces the removal policy for a named group. More...

const SweepPolicy &	sweepPolicy () const
	Returns the scheduling policy used by update(). More...

void	sweepPolicy (const SweepPolicy &policy)
	Replaces the scheduling policy used by update(). More...

void	update (const Scene::StepInfo &info)
	Advances registry scheduling and sweeps when the configured policy is due. More...

void	sweep (const Scene::StepInfo &info)
	Immediately evaluates all swept removal policies. More...

void	clear ()
	Forgets every tracked node and resets runtime scheduling state. More...

void	removeAll ()
	Removes every live tracked node from its parent and clears the registry. More...

Detailed Description

Tracks transient scene nodes and removes them according to configurable policies.

The registry stores weak references and never owns tracked nodes. Count limits are enforced immediately when nodes are tracked or policies change. Age and distance limits are evaluated only when a configured sweep is due or sweep() is called explicitly.

Functions that may remove nodes must be called only from a point where scene mutation is safe, such as after a physics simulation step has completed.

Definition at line 42 of file Transients.h.

Constructor & Destructor Documentation

◆ Transients()

a3d::ext::Transients::Transients ( SweepPolicy sweepPolicy = SweepPolicy::EveryUpdate() )

explicit

Creates an empty registry with the supplied sweep policy.

Parameters

sweepPolicy Scheduling policy used by update().

Exceptions

std::invalid_argument if sweepPolicy is invalid.

◆ ~Transients()

a3d::ext::Transients::~Transients ( )

default

Destroys the registry without removing tracked nodes.

Member Function Documentation

◆ clear()

void a3d::ext::Transients::clear ( )

Forgets every tracked node and resets runtime scheduling state.

Tracked nodes are not removed from their parents. Global, group, and sweep policies are retained.

◆ groupPolicy()

void a3d::ext::Transients::groupPolicy	(	const std::string &	group,
		const Policy &	policy
	)

Replaces the removal policy for a named group.

A reduced maxCount is enforced immediately. Age and distance limits take effect on the next sweep. An empty group name configures the policy applied to nodes tracked without a group name.

Parameters

group	Group whose policy is replaced.
policy	New group policy.

Exceptions

std::invalid_argument if policy contains an invalid age or distance limit.

◆ policy() [1/2]

const Policy & a3d::ext::Transients::policy ( ) const

Returns the global removal policy.

◆ policy() [2/2]

void a3d::ext::Transients::policy ( const Policy & policy )

Replaces the global removal policy.

A reduced maxCount is enforced immediately. Age and distance limits take effect on the next sweep.

Parameters

policy New global policy.

Exceptions

std::invalid_argument if policy contains an invalid age or distance limit.

◆ removeAll()

void a3d::ext::Transients::removeAll ( )

Removes every live tracked node from its parent and clears the registry.

Global, group, and sweep policies are retained.

◆ sweep()

void a3d::ext::Transients::sweep ( const Scene::StepInfo & info )

Immediately evaluates all swept removal policies.

Calling this function restarts the configured update-count or simulation-time cadence from this sweep.

Parameters

info	Information for the completed simulation step.

◆ sweepPolicy() [1/2]

const SweepPolicy & a3d::ext::Transients::sweepPolicy ( ) const

Returns the scheduling policy used by update().

◆ sweepPolicy() [2/2]

void a3d::ext::Transients::sweepPolicy ( const SweepPolicy & policy )

Replaces the scheduling policy used by update().

The current scheduling cadence is restarted when the policy changes.

Parameters

policy New sweep policy.

Exceptions

std::invalid_argument if policy is invalid.

◆ track() [1/2]

void a3d::ext::Transients::track	(	const std::shared_ptr< Node > &	node,
		const std::string &	group = `{}`
	)

Tracks a transient node and immediately enforces applicable count limits.

The node's creation time is the most recently observed simulation time. Before the first update() or sweep(), tracked nodes are assigned the start time of the first supplied Scene::StepInfo.

Parameters

node	Node to track. The registry retains only a weak reference.
group	Optional group used to select an additional group policy.

Exceptions

std::invalid_argument	if node is null or is not attached beneath a Scene root.
std::logic_error	if node is already tracked.

◆ track() [2/2]

void a3d::ext::Transients::track	(	const std::vector< std::shared_ptr< Node > > &	nodes,
		const std::string &	group = `{}`
	)

Tracks a collection of nodes as members of the same transient group.

Each node is registered using the same behavior as the single-node track() overload. Group and global count limits are enforced as nodes are added.

Parameters

nodes	Nodes to track.
group	Optional transient group shared by all nodes.

◆ untrack()

void a3d::ext::Transients::untrack ( const Node & node )

Stops tracking a node without removing it from its parent.

Parameters

node	Node to stop tracking.

◆ update()

void a3d::ext::Transients::update ( const Scene::StepInfo & info )

Advances registry scheduling and sweeps when the configured policy is due.

One call to this function counts as one update for SweepPolicy::EveryNUpdates. Time-based scheduling uses Scene::StepInfo::endTime and therefore advances in simulation time rather than wall-clock time.

Parameters

info	Information for the completed simulation step.

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

a3d/extension/Transients.h

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Transients()

◆ ~Transients()

Member Function Documentation

◆ clear()

◆ groupPolicy()

◆ policy() [1/2]

◆ policy() [2/2]

◆ removeAll()

◆ sweep()

◆ sweepPolicy() [1/2]

◆ sweepPolicy() [2/2]

◆ track() [1/2]

◆ track() [2/2]

◆ untrack()

◆ update()