guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
guillaume::Application< DefaultSceneType, SceneTypes > Class Template Reference

The entry point of a program: owns the engine, the scenes and the systems, and runs the frame loop. More...

#include <headers/guillaume/application.hpp>

Inheritance diagram for guillaume::Application< DefaultSceneType, SceneTypes >:
Collaboration diagram for guillaume::Application< DefaultSceneType, SceneTypes >:

Public Member Functions

 Application (std::shared_ptr< utility::RessourceProvider > ressourceProvider, std::unique_ptr< utility::Engine > engine)
 Build the application and enter the default scene.
virtual ~Application (void)
 Destroy the application with its scenes, systems and engine.
void routine (void)
 Run one frame.
bool shouldQuit (void)
 Tell whether a quit event was received since the last call.
int run (void)
 Run frames until a quit event is received.

Protected Member Functions

std::shared_ptr< utility::RessourceProvider > getRessourceProvider (void)
 Get the resource provider given to the constructor.

Detailed Description

template<InheritFromScene DefaultSceneType, InheritFromScene... SceneTypes>
requires AllDistinct<DefaultSceneType, SceneTypes...>
class guillaume::Application< DefaultSceneType, SceneTypes >

The entry point of a program: owns the engine, the scenes and the systems, and runs the frame loop.

An application is declared with the list of its scene types. It creates one instance of each, enters the first one, and then repeats routine() until the engine reports a quit event. The engine (utility::Engine) is the platform layer the program provides: it opens the window or the XR session, draws, and reports input.

A minimal program:

class HomeScene: public guillaume::Scene
{
public:
void onEnter(void) override
{
auto &builder = getBuilderManager()
builder.makeButton(nullptr, "Save", [] {},
guillaume::entities::Button::Color::Filled,
guillaume::entities::Button::Shape::Round,
guillaume::entities::Button::Size::Medium, false);
}
};
int main(void)
{
utility::DefaultSystemIO systemIo;
auto resources =
std::make_shared<utility::RessourceProvider>(systemIo);
// MyEngine is the program's implementation of utility::Engine.
guillaume::Application<HomeScene> app(
resources, std::make_unique<MyEngine>());
return app.run();
}
One screen of the application: it owns the entities shown and the components that hold their state.
Definition scene.hpp:117
ecs::EntityBuilderManager & getBuilderManager(void)
Get the builders of this scene, one per widget of the library.
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.
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

One frame (routine()), in order:

  1. the engine polls input; each event is published on the event bus and queued by the systems that subscribed to its type;
  2. the engine clears the frame and updates;
  3. the four phases run on the active scene: Event, Measure, Layout, Render. In each phase, every system of the phase runs once over the whole scene (ecs::System::routine);
  4. the changed flags of the active scene's components are reset (ecs::ComponentRegistry::resetChangedFlags);
  5. a scene switch requested with Scene::goToScene is carried out;
  6. the engine presents the frame.

Things to watch out for:

  • Systems belong to the application and are shared by all scenes; components and entities belong to each scene.
  • Only the active scene is processed.
  • The constructor already enters the default scene, so DefaultSceneType::onEnter runs before run() is called.
Template Parameters
DefaultSceneTypeThe scene activated when the application starts.
SceneTypesThe other scenes of the application. Every scene type must inherit from Scene, appear only once, and be constructible from the arguments of the Scene constructor.
See also
Scene
ecs::System::routine
systems::registerCoreSystems

Definition at line 133 of file application.hpp.

Constructor & Destructor Documentation

◆ Application()

template<InheritFromScene DefaultSceneType, InheritFromScene... SceneTypes>
guillaume::Application< DefaultSceneType, SceneTypes >::Application ( std::shared_ptr< utility::RessourceProvider > ressourceProvider,
std::unique_ptr< utility::Engine > engine )

Build the application and enter the default scene.

In order: registers the core systems (systems::registerCoreSystems), routes the engine's events to the event bus, creates one instance of every scene type, then calls onEnter() on the default scene and places its root entities in front of the engine's view.

Parameters
ressourceProviderGives access to the files the systems and the scenes load (fonts, images, meshes). Shared with them.
engineThe engine that renders and polls events. The application takes ownership.
Exceptions
std::invalid_argumentWhen the engine is null.

Member Function Documentation

◆ getRessourceProvider()

template<InheritFromScene DefaultSceneType, InheritFromScene... SceneTypes>
std::shared_ptr< utility::RessourceProvider > guillaume::Application< DefaultSceneType, SceneTypes >::getRessourceProvider ( void )
inlineprotected

Get the resource provider given to the constructor.

Returns
The shared resource provider.

Definition at line 199 of file application.hpp.

◆ routine()

template<InheritFromScene DefaultSceneType, InheritFromScene... SceneTypes>
void guillaume::Application< DefaultSceneType, SceneTypes >::routine ( void )

Run one frame.

Polls the engine's events, clears and updates the engine, runs the Event, Measure, Layout and Render phases on the active scene, resets the changed flags of its components, carries out a pending scene switch and presents the frame. See the class description.

run() calls it in a loop; call it directly to drive the loop from outside. Exceptions thrown by a system, a handler or a scene switch to an unknown scene propagate to the caller.

◆ run()

template<InheritFromScene DefaultSceneType, InheritFromScene... SceneTypes>
int guillaume::Application< DefaultSceneType, SceneTypes >::run ( void )

Run frames until a quit event is received.

Returns
EXIT_SUCCESS after a quit event; EXIT_FAILURE when a frame threw a std::exception, which is logged and ends the loop.

◆ shouldQuit()

template<InheritFromScene DefaultSceneType, InheritFromScene... SceneTypes>
bool guillaume::Application< DefaultSceneType, SceneTypes >::shouldQuit ( void )

Tell whether a quit event was received since the last call.

The pending quit event is consumed: a second call returns false until the engine reports another one.

Returns
True when the engine reported a quit event (window closed, for instance).

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