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

The engine objects one render system owns, keyed by entity identifier. More...

#include <headers/guillaume/systems/render_handle_map.hpp>

Inheritance diagram for guillaume::systems::RenderHandleMap:

Public Member Functions

 RenderHandleMap (void)=default
 Create an empty map.
 ~RenderHandleMap (void)=default
 Destroy the map without removing the engine objects it refers to.
void markAllUnused (void)
 Clear the used flag of every handle. Call it from the system's prepare(), before any entity is drawn.
void removeUnused (utility::Engine &engine)
 Remove from the engine, then from the map, every handle whose used flag is still false. Call it from the system's cleanup().
RenderHandle * find (const ecs::Entity::Identifier &identifier)
 Look up the handle of an entity.
void insert (const ecs::Entity::Identifier &identifier, RenderHandle handle)
 Store the handle of an entity, replacing the one it had.
std::size_t size (void) const
 Count the entities that have an engine object in this map.
void clear (void)
 Forget every handle without calling utility::Engine::removeObject. Use it only when the engine objects are gone already or are destroyed with the engine.

Detailed Description

The engine objects one render system owns, keyed by entity identifier.

Every render system (RectangleRender, TextRender, ...) inherits from this class. An engine object is created the first time an entity is drawn and updated in place afterwards. An entity that is not drawn during a frame (it was destroyed or lost a component) has its engine object removed at the end of that frame.

The sequence in a render system is:

void MyRender::prepare(void) { markAllUnused(); }
void MyRender::update(const ecs::Entity::Identifier &identifier)
{
auto renderable = buildRenderable(identifier);
RenderHandle *handle = find(identifier);
if (handle == nullptr) {
insert(identifier, RenderHandle {
_engine.createObject(renderable), renderable, true });
} else {
_engine.updateObject(renderable, handle->objectId);
handle->renderable = renderable;
handle->used = true;
}
}
void MyRender::cleanup(void) { removeUnused(_engine); }
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
void insert(const ecs::Entity::Identifier &identifier, RenderHandle handle)
Store the handle of an entity, replacing the one it had.
void markAllUnused(void)
Clear the used flag of every handle. Call it from the system's prepare(), before any entity is drawn.
void removeUnused(utility::Engine &engine)
Remove from the engine, then from the map, every handle whose used flag is still false....
RenderHandle * find(const ecs::Entity::Identifier &identifier)
Look up the handle of an entity.
What a render system remembers about the engine object it created for one entity.
bool used
Whether the entity was drawn this frame.
std::shared_ptr< utility::graphic::Renderable > renderable
Renderable uploaded last for this object.
size_t objectId
Identifier given by the engine.

find() does not set used: a system that finds a handle and forgets to set the flag loses the engine object at cleanup.

See also
RenderHandle

Definition at line 88 of file render_handle_map.hpp.

Member Function Documentation

◆ clear()

void guillaume::systems::RenderHandleMap::clear ( void )
inline

Forget every handle without calling utility::Engine::removeObject. Use it only when the engine objects are gone already or are destroyed with the engine.

Definition at line 185 of file render_handle_map.hpp.

Here is the caller graph for this function:

◆ find()

RenderHandle * guillaume::systems::RenderHandleMap::find ( const ecs::Entity::Identifier & identifier)
inline

Look up the handle of an entity.

The used flag is left as it is: the caller sets it once the entity has been drawn.

Parameters
identifierThe entity to look up.
Returns
The handle, or nullptr when the entity has no engine object in this map. The pointer is valid until the handle is removed.

Definition at line 146 of file render_handle_map.hpp.

Here is the caller graph for this function:

◆ insert()

void guillaume::systems::RenderHandleMap::insert ( const ecs::Entity::Identifier & identifier,
RenderHandle handle )
inline

Store the handle of an entity, replacing the one it had.

A replaced handle is dropped without calling utility::Engine::removeObject: remove the engine object first when the entity already has one.

Parameters
identifierThe entity the engine object belongs to.
handleThe handle to store, with used set to true if the entity was drawn this frame.

Definition at line 165 of file render_handle_map.hpp.

Here is the caller graph for this function:

◆ markAllUnused()

void guillaume::systems::RenderHandleMap::markAllUnused ( void )
inline

Clear the used flag of every handle. Call it from the system's prepare(), before any entity is drawn.

Definition at line 110 of file render_handle_map.hpp.

Here is the caller graph for this function:

◆ removeUnused()

void guillaume::systems::RenderHandleMap::removeUnused ( utility::Engine & engine)
inline

Remove from the engine, then from the map, every handle whose used flag is still false. Call it from the system's cleanup().

Parameters
engineThe engine the objects were created in.

Definition at line 123 of file render_handle_map.hpp.

Here is the caller graph for this function:

◆ size()

std::size_t guillaume::systems::RenderHandleMap::size ( void ) const
inline

Count the entities that have an engine object in this map.

Returns
The number of handles stored.

Definition at line 175 of file render_handle_map.hpp.


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