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

One screen of the application: it owns the entities shown and the components that hold their state. More...

#include <headers/guillaume/scene.hpp>

Inheritance diagram for guillaume::Scene:
Collaboration diagram for guillaume::Scene:

Public Member Functions

void placeEntitiesInFrontOfView (const utility::graphic::ViewF &view)
 Line up the scene's entities in front of a view.
template<typename NextScene>
void goToScene (void)
 Ask to leave this scene for another one.
 Scene (std::shared_ptr< utility::RessourceProvider > ressourceProvider, LocalStorage &localStorage, SessionStorage &sessionStorage)
 Create an empty scene with its registries and its builders.
virtual ~Scene (void)
 Destroy the scene with its entities and components.
ecs::ComponentRegistry & getComponentRegistry (void)
 Get the registry holding the components of every entity of this scene.
ecs::EntityRegistry & getEntityRegistry (void)
 Get the scene as the registry that owns its entities.
bool wantsToSwitch (void) const noexcept
 Tell whether goToScene() was called and the switch has not happened yet.
std::type_index getNextSceneType (void) const noexcept
 Get the scene type asked for by goToScene().
void clearNextScene (void) noexcept
 Forget the pending switch request, if any.
virtual void onEnter (void)
 Called each time the scene becomes the active one: at start-up for the default scene, then after each switch to it.
virtual void onExit (void)
 Called each time the scene stops being the active one, before onEnter() of the next scene.
Public Member Functions inherited from guillaume::ecs::EntityRegistry
 EntityRegistry (void)=default
 Create a registry.
virtual ~EntityRegistry (void)=default
 Virtual destructor.
void addEntity (std::shared_ptr< Entity > entity)
 Make this registry own an entity, so that it stays alive and systems visit it.
bool removeEntity (Entity::Identifier identifier)
 Remove an entity, with its children and all their components.
void clearEntities (void)
 Remove every entity owned by this registry, with everything they own and all their components.
const std::vector< std::shared_ptr< Entity > > & getEntities (void) const
 Get the entities this registry owns directly.
std::vector< std::shared_ptr< Entity > > getEntitiesBreadthFirst (void)
 List every entity of this registry and of the registries nested in it, level by level.
std::vector< std::shared_ptr< Entity > > getEntitiesBreadthFirst (void) const
 List every entity of this registry and of the registries nested in it, level by level (const overload).
template<InheritFromEntity EntityType>
std::shared_ptr< EntityType > getEntity (Entity::Identifier identifier)
 Find an entity owned directly by this registry, by identifier.
template<InheritFromEntity EntityType>
std::shared_ptr< const EntityType > getEntity (Entity::Identifier identifier) const
 Find an entity owned directly by this registry, by identifier (const overload).
std::vector< Entity::Identifier > getEntityWithSignature (Entity::Signature systemSignature) const
 List the entities that have every component type of a signature, from the root down.
std::vector< Entity::Identifier > getEntityWithSignature (Entity::Signature systemSignature, const EntityTreeTraveler &traveler) const
 List the entities that have every component type of a signature, in the order chosen by a traveler.

Protected Member Functions

std::shared_ptr< utility::RessourceProvider > getRessourceProvider (void)
 Get the resource provider given to the constructor.
ecs::EntityBuilderManager & getBuilderManager (void)
 Get the builders of this scene, one per widget of the library.
void addRootEntity (const std::string &name, std::shared_ptr< ecs::Entity > entity)
 Give an entity a name, to find it again with getRootEntity().
template<ecs::InheritFromEntity EntityType>
std::shared_ptr< EntityType > getRootEntity (const std::string &name)
 Find an entity by the name given to addRootEntity().
Protected Member Functions inherited from guillaume::ecs::EntityRegistryContainer
std::vector< std::shared_ptr< Entity > > & accessDirectEntities (void) override
 Give access to the list of entities this registry owns directly.
const std::vector< std::shared_ptr< Entity > > & accessDirectEntities (void) const override
 Give read access to the list of entities this registry owns directly.

Detailed Description

One screen of the application: it owns the entities shown and the components that hold their state.

A program derives one class per screen and overrides onEnter() to build its widgets. Application creates one instance of each scene type at start-up and keeps it until the program ends; exactly one scene is active at a time, and only that one is processed by the systems each frame.

A scene is three things:

class HomeScene: public guillaume::Scene
{
public:
void onEnter(void) override
{
auto &builder = getBuilderManager()
builder.makeButton(
nullptr, "Settings",
[this] { goToScene<SettingsScene>(); },
guillaume::entities::Button::Color::Filled,
guillaume::entities::Button::Shape::Round,
guillaume::entities::Button::Size::Medium, false);
}
void onExit(void) override
{
}
};
guillaume::Application<HomeScene, SettingsScene> app(
resources, std::move(engine));
One screen of the application: it owns the entities shown and the components that hold their state.
Definition scene.hpp:117
virtual void onExit(void)
Called each time the scene stops being the active one, before onEnter() of the next scene.
ecs::EntityBuilderManager & getBuilderManager(void)
Get the builders of this scene, one per widget of the library.
void goToScene(void)
Ask to leave this scene for another one.
Scene(std::shared_ptr< utility::RessourceProvider > ressourceProvider, LocalStorage &localStorage, SessionStorage &sessionStorage)
Create an empty scene with its registries and its builders.
virtual void onEnter(void)
Called each time the scene becomes the active one: at start-up for the default scene,...
BuilderType & getBuilder(void)
Get the builder of a given type.
void clearEntities(void)
Remove every entity owned by this registry, with everything they own and all their components.
Configures, creates and registers Button widgets.
Definition button.hpp:97
std::shared_ptr< Button > makeButton(std::shared_ptr< Entity > parent, const std::string &labelContent, std::function< void(void)> onClick, Color colorStyle, Shape shape, Size size, bool isMorph)
Build a button with a label and no icon, register it under parent and reset the builder.
Definition button.cpp:145

Things to watch out for:

  • onEnter() runs every time the scene becomes active, and the scene keeps its entities while it is inactive. A scene that can be entered twice either removes its entities in onExit(), as above, or builds them only once.
  • Right after onEnter(), the entities the scene owns directly that have a Transform and a Bound are placed side by side in front of the engine's view (placeEntitiesInFrontOfView()).
  • goToScene() only records a request; the switch happens at the end of the frame.
  • A builder registers what it creates in the scene. addRootEntity() only gives an entity a name to find it again with getRootEntity(); it does not register it. A name cannot be taken back or reused, so a scene that names entities in onEnter() must build them only once.
See also
Application
SceneManager
ecs::EntityBuilderManager

Definition at line 113 of file scene.hpp.

Constructor & Destructor Documentation

◆ Scene()

guillaume::Scene::Scene ( std::shared_ptr< utility::RessourceProvider > ressourceProvider,
LocalStorage & localStorage,
SessionStorage & sessionStorage )

Create an empty scene with its registries and its builders.

Called by SceneManager. A derived scene inherits this constructor (using guillaume::Scene::Scene;) or forwards the three arguments, and builds its widgets in onEnter(), not here.

Parameters
ressourceProviderGives access to the files the scene loads, see getRessourceProvider().
localStorageThe application's persistent storage. The scene keeps a reference; it must outlive the scene.
sessionStorageThe application's session storage. The scene keeps a reference; it must outlive the scene.

Member Function Documentation

◆ addRootEntity()

void guillaume::Scene::addRootEntity ( const std::string & name,
std::shared_ptr< ecs::Entity > entity )
protected

Give an entity a name, to find it again with getRootEntity().

The name table also keeps the entity alive. The entity is not registered in the scene by this call: an entity that does not come from a builder must also be passed to addEntity() to be processed by the systems. Removing the entity from the scene does not remove its name.

Parameters
nameThe name to file the entity under, unique in the scene.
entityThe entity to name.
Exceptions
std::runtime_errorWhen the name is already used.

◆ clearNextScene()

void guillaume::Scene::clearNextScene ( void )
noexcept

Forget the pending switch request, if any.

SceneManager calls it when it carries out the switch.

◆ getBuilderManager()

ecs::EntityBuilderManager & guillaume::Scene::getBuilderManager ( void )
protected

Get the builders of this scene, one per widget of the library.

auto &builder =
Configures Text widgets and registers them in the scene's entity registry.
Definition text.hpp:98
Returns
Reference to the manager. Every builder it returns creates components in getComponentRegistry() and registers entities in this scene.

◆ getComponentRegistry()

ecs::ComponentRegistry & guillaume::Scene::getComponentRegistry ( void )

Get the registry holding the components of every entity of this scene.

Returns
Reference to the registry, valid as long as the scene. Pass it to a widget's create() or constructor.

◆ getEntityRegistry()

ecs::EntityRegistry & guillaume::Scene::getEntityRegistry ( void )

Get the scene as the registry that owns its entities.

Returns
Reference to the scene itself, seen as an ecs::EntityRegistry. Use it to add, find or remove entities.

◆ getNextSceneType()

std::type_index guillaume::Scene::getNextSceneType ( void ) const
noexcept

Get the scene type asked for by goToScene().

Returns
The type of the scene to switch to, or typeid(void) when no switch is pending.

◆ getRessourceProvider()

std::shared_ptr< utility::RessourceProvider > guillaume::Scene::getRessourceProvider ( void )
protected

Get the resource provider given to the constructor.

Returns
The shared resource provider, which loads the files (fonts, images, meshes) the scene needs.

◆ getRootEntity()

template<ecs::InheritFromEntity EntityType>
std::shared_ptr< EntityType > guillaume::Scene::getRootEntity ( const std::string & name)
protected

Find an entity by the name given to addRootEntity().

Template Parameters
EntityTypeThe type the entity is expected to have, for instance entities::Button.
Parameters
nameThe name the entity was filed under.
Returns
The entity, or nullptr when the name is unknown or when the entity is not an EntityType.

◆ goToScene()

template<typename NextScene>
void guillaume::Scene::goToScene ( void )

Ask to leave this scene for another one.

The request is recorded and carried out at the end of the frame by SceneManager::processSceneTransition: onExit() is called on this scene, then onEnter() on the other. A second call before that replaces the first request.

Template Parameters
NextSceneThe scene type to switch to. It must be one of the scene types of the Application; otherwise the switch throws std::runtime_error at the end of the frame.

◆ onEnter()

virtual void guillaume::Scene::onEnter ( void )
virtual

Called each time the scene becomes the active one: at start-up for the default scene, then after each switch to it.

Override it to build the widgets of the screen. The default implementation only logs.

◆ onExit()

virtual void guillaume::Scene::onExit ( void )
virtual

Called each time the scene stops being the active one, before onEnter() of the next scene.

Override it to remove what onEnter() built (clearEntities()) or to save state. The default implementation only logs: the entities are kept. It is not called when the application ends.

◆ placeEntitiesInFrontOfView()

void guillaume::Scene::placeEntitiesInFrontOfView ( const utility::graphic::ViewF & view)

Line up the scene's entities in front of a view.

Concerns the entities the scene owns directly that have both a components::Transform and a components::Bound. They are put in a row, in registration order, 300 units in front of the view, centered on its axis, 50 units apart, each one facing the same way as the view. The Transform position is the top-left corner of the entity. The other entities are not touched.

SceneManager calls it once after each onEnter(), with the engine's current view. The entities are not moved again when the view changes.

Parameters
viewThe view to place the entities in front of.

◆ wantsToSwitch()

bool guillaume::Scene::wantsToSwitch ( void ) const
noexcept

Tell whether goToScene() was called and the switch has not happened yet.

Returns
True when a scene switch is pending.

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