guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
guillaume::ecs::ComponentRegistry Class Reference

Stores every component of a scene, per component type and per entity identifier, and knows which ones changed this frame. More...

#include <headers/guillaume/ecs/component_registry.hpp>

Inheritance diagram for guillaume::ecs::ComponentRegistry:
Collaboration diagram for guillaume::ecs::ComponentRegistry:

Public Member Functions

 ComponentRegistry (void)=default
 Create a registry that holds no component.
 ~ComponentRegistry (void)=default
 Destroy the registry and every component it stores.
template<InheritFromComponent... NeededComponentTypes>
void registerComponentsForEntity (const Entity::Identifier &entityIdentifier)
 Give an entity one default-constructed component of each listed type.
template<InheritFromComponent ComponentType, typename... Args>
ComponentType & addComponent (const Entity::Identifier &entityIdentifier, Args &&...args)
 Construct a component for an entity, replacing the one it already has, if any.
template<InheritFromComponent ComponentType>
bool hasComponent (const Entity::Identifier &entityIdentifier) const
 Tell whether an entity has a component of a given type.
template<InheritFromComponent ComponentType>
void removeComponent (const Entity::Identifier &entityIdentifier)
 Delete one component of an entity. Does nothing when the entity does not have it.
void removeEntity (const Entity::Identifier &entityIdentifier)
 Delete every component of an entity, of every type.
bool hasChanged (const Entity::Identifier &entityIdentifier) const
 Tell whether at least one component of an entity was modified since the flags were last reset.
void resetChangedFlags (void)
 Mark every component of every entity as unchanged.
template<InheritFromComponent ComponentType>
ComponentType & getComponent (const Entity::Identifier &entityIdentifier)
 Get a component of an entity, to read or modify it.
template<InheritFromComponent ComponentType>
const ComponentType & getComponent (const Entity::Identifier &entityIdentifier) const
 Get a component of an entity, read-only.

Protected Member Functions

template<InheritFromComponent ComponentType>
void registerNewComponentType (void)
 Create the (empty) storage of a component type ahead of its first use.

Detailed Description

Stores every component of a scene, per component type and per entity identifier, and knows which ones changed this frame.

This is where all the state of the UI lives. Each Scene owns one registry. Widgets write to it when they are built and when their setters are called; systems read and write it every frame through System::getComponent. Everything is addressed by entity identifier, so no entity object is needed to use it.

Storage for a component type is created the first time that type is used: there is no list of component types to maintain.

const ecs::Entity::Identifier id = entity->getIdentifier();
if (registry.hasComponent<components::Bound>(id)) {
registry.getComponent<components::Bound>(id).setWidth(120.0f);
}
registry.hasChanged(id); // true: Bound was modified
registry.resetChangedFlags();
registry.hasChanged(id); // false until the next modification
Size of an entity: the width and height, in dp, of the rectangle that starts at the position of its c...
Definition bound.hpp:62
Stores every component of a scene, per component type and per entity identifier, and knows which ones...
void resetChangedFlags(void)
Mark every component of every entity as unchanged.
ComponentType & getComponent(const Entity::Identifier &entityIdentifier)
Get a component of an entity, to read or modify it.
ComponentType & addComponent(const Entity::Identifier &entityIdentifier, Args &&...args)
Construct a component for an entity, replacing the one it already has, if any.
bool hasComponent(const Entity::Identifier &entityIdentifier) const
Tell whether an entity has a component of a given type.
bool hasChanged(const Entity::Identifier &entityIdentifier) const
Tell whether at least one component of an entity was modified since the flags were last reset.
std::size_t Identifier
The key under which an entity's components are stored. Systems and components refer to entities by th...
Definition entity.hpp:86

The changed flags. Every component carries a flag (Component::hasChanged) that its setters raise when a value really changes. hasChanged(identifier) tells whether any component of an entity has its flag raised; resetChangedFlags() lowers all of them and is called by Application::routine once the four phases have run. So a flag raised during a frame, or between two frames by application code, stays visible until the end of the frame in progress. A frame in which no flag is raised means the UI has settled. The flags are information only: System::routine visits every matching entity every frame, whether it changed or not.

Things to watch out for:

  • Adding a component here does not update the signature of the entity (Entity::setSignature). A system only visits an entity whose signature contains the system's components.
  • addComponent on an entity that already has the component replaces it with a newly constructed one.
  • A reference returned by getComponent or addComponent stays valid until that component is removed or replaced.
See also
Component
Entity
System

Definition at line 133 of file component_registry.hpp.

Member Function Documentation

◆ addComponent()

template<InheritFromComponent ComponentType, typename... Args>
ComponentType & guillaume::ecs::ComponentRegistry::addComponent ( const Entity::Identifier & entityIdentifier,
Args &&... args )

Construct a component for an entity, replacing the one it already has, if any.

The new component is not marked as changed, and the signature of the entity is left as it is.

Template Parameters
ComponentTypeThe component type to add.
ArgsThe types of the constructor arguments.
Parameters
entityIdentifierThe identifier of the entity that receives the component.
argsArguments forwarded to the constructor of ComponentType; none builds a default component.
Returns
Reference to the stored component, so setters can be chained on it.
Here is the caller graph for this function:

◆ getComponent() [1/2]

template<InheritFromComponent ComponentType>
ComponentType & guillaume::ecs::ComponentRegistry::getComponent ( const Entity::Identifier & entityIdentifier)

Get a component of an entity, to read or modify it.

Template Parameters
ComponentTypeThe component type to get.
Parameters
entityIdentifierThe identifier of the entity.
Returns
Reference to the stored component. It stays valid until the component is removed or replaced.
Exceptions
EntityComponentNotFoundException<ComponentType>When the entity does not have the component.

◆ getComponent() [2/2]

template<InheritFromComponent ComponentType>
const ComponentType & guillaume::ecs::ComponentRegistry::getComponent ( const Entity::Identifier & entityIdentifier) const

Get a component of an entity, read-only.

Template Parameters
ComponentTypeThe component type to get.
Parameters
entityIdentifierThe identifier of the entity.
Returns
Const reference to the stored component. It stays valid until the component is removed or replaced.
Exceptions
EntityComponentNotFoundException<ComponentType>When the entity does not have the component.

◆ hasChanged()

bool guillaume::ecs::ComponentRegistry::hasChanged ( const Entity::Identifier & entityIdentifier) const

Tell whether at least one component of an entity was modified since the flags were last reset.

Parameters
entityIdentifierThe identifier of the entity.
Returns
True when at least one of its components is marked as changed; false when none is, or when the entity has no component.
See also
Component::hasChanged

Definition at line 29 of file component_registry.cpp.

◆ hasComponent()

template<InheritFromComponent ComponentType>
bool guillaume::ecs::ComponentRegistry::hasComponent ( const Entity::Identifier & entityIdentifier) const

Tell whether an entity has a component of a given type.

Template Parameters
ComponentTypeThe component type to look for.
Parameters
entityIdentifierThe identifier of the entity.
Returns
True when the component exists. False for an unknown identifier, including Entity::InvalidIdentifier.
Here is the caller graph for this function:

◆ registerComponentsForEntity()

template<InheritFromComponent... NeededComponentTypes>
void guillaume::ecs::ComponentRegistry::registerComponentsForEntity ( const Entity::Identifier & entityIdentifier)

Give an entity one default-constructed component of each listed type.

EntityFiller calls it from its constructor with the component list of the widget. A listed component the entity already has is replaced by a default one.

Template Parameters
NeededComponentTypesThe component types to create.
Parameters
entityIdentifierThe identifier of the entity that receives the components.

◆ registerNewComponentType()

template<InheritFromComponent ComponentType>
void guillaume::ecs::ComponentRegistry::registerNewComponentType ( void )
protected

Create the (empty) storage of a component type ahead of its first use.

Optional: storages are created on demand anyway. ComponentRegistryFiller uses it to prepare a fixed list of types.

Template Parameters
ComponentTypeThe component type to prepare storage for.

◆ removeComponent()

template<InheritFromComponent ComponentType>
void guillaume::ecs::ComponentRegistry::removeComponent ( const Entity::Identifier & entityIdentifier)

Delete one component of an entity. Does nothing when the entity does not have it.

Template Parameters
ComponentTypeThe component type to remove.
Parameters
entityIdentifierThe identifier of the entity.
Here is the caller graph for this function:

◆ removeEntity()

void guillaume::ecs::ComponentRegistry::removeEntity ( const Entity::Identifier & entityIdentifier)

Delete every component of an entity, of every type.

Only the components are touched: the entity object and its place in the tree are not. To remove an entity completely, call EntityRegistry::removeEntity, which ends up here.

Parameters
entityIdentifierThe identifier of the entity.

Definition at line 48 of file component_registry.cpp.

◆ resetChangedFlags()

void guillaume::ecs::ComponentRegistry::resetChangedFlags ( void )

Mark every component of every entity as unchanged.

Application::routine calls it once per frame, after the Render phase. Code that drives systems by hand (a test, for instance) calls it itself between two frames.

Definition at line 40 of file component_registry.cpp.


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