Main application base class. More...

#include <donut/application/Application.hpp>

Public Member Functions
	Application (const ApplicationOptions &options={})
	Construct the base of the main application. More...

virtual	~Application ()=default
	Virtual destructor which must be overridden by the concrete application class in order to perform any application-specific cleanup before shutdown. More...

void	run ()
	Start the main loop of the application and keep running until the application quits or an unhandled exception is thrown. More...

virtual void	quit ()
	Initiate the shutdown process, meaning that the current frame will be the last to be processed and displayed before the main loop ends. More...

bool	isRunning () const noexcept
	Check if the application is currently running, meaning that it is fully initialized, that run() has been called and has started the main loop, and that it is not in the process of shutting down. More...

unsigned	getLastSecondFrameCount () const noexcept
	Get the number of frames displayed during the last measured second of the application's run time, which approximates the average frame rate. More...

void	setFrameRateParameters (float tickRate, float minFrameRate, float maxFrameRate)
	Set the frame rate parameters of the application. More...

void	setFrameRateLimiterSleepEnabled (bool frameRateLimiterSleepEnabled)
	Enable or disable frame rate limiter sleep. More...

void	setFrameRateLimiterSleepBias (std::chrono::steady_clock::duration frameRateLimiterSleepBias)
	Set the frame rate limiter sleep bias. More...

TickInfo	getLatestTickInfo () const noexcept
	Get information about the latest tick. More...

FrameInfo	getLatestFrameInfo () const noexcept
	Get information about the latest frame. More...

Protected Member Functions
virtual void	update (FrameInfo frameInfo)
	Per-frame update callback, called in the main loop once at the beginning of each frame, before processing ticks. More...

virtual void	tick (TickInfo tickInfo)
	Fixed-rate tick callback, called in the main loop 0 or more times during tick processing, which happens on each frame after calling update() and before calling display(). More...

virtual void	display (TickInfo tickInfo, FrameInfo frameInfo)
	Frame rendering callback, called in the main loop once at the end of each frame after processing ticks, in order to render the latest state of the application. More...

Detailed Description

Main application base class.

The application controls the main loop, including frame pacing and fixed-interval frame rate-independent tick updates.

Concrete applications should derive from this class and implement the associated virtual functions in order to receive all of the relevant callbacks. Deriving from this class also ensures that it is constructed before any code in the concrete application is executed, which means that any global systems will be properly initialized before any code that may depend on them is able to run, assuming all user code is constrained to being called from an instance of the concrete application class.

Examples: example_game.cpp, and example_rectangle.cpp.

Constructor & Destructor Documentation

◆ Application()

donut::application::Application::Application ( const ApplicationOptions & options = {} )

explicit

Construct the base of the main application.

Parameters

options initial configuration of the application, see ApplicationOptions.

◆ ~Application()

virtual donut::application::Application::~Application ( )

virtualdefault

Virtual destructor which must be overridden by the concrete application class in order to perform any application-specific cleanup before shutdown.

May also be overridden implicitly by the compiler-generated destructor of the derived class.

Member Function Documentation

◆ run()

void donut::application::Application::run ( )

Start the main loop of the application and keep running until the application quits or an unhandled exception is thrown.

Note: Under emscripten-based WebAssembly builds, this function will never return. Instead, it explicitly calls the virtual application destructor in order to perform any necessary cleanup when the main loop has ended. It is therefore expected that any application- specific cleanup or shutdown code be called from the overriden destructor, rather than being called from main after run() has finished.

Exceptions

any	unhandled exception which was thrown during the execution of the main loop, unless running under emscripten, in which case exceptions are simply printed before shutting down.

Remarks: The intended usage of this function is to call it once at the end of main function of the program as the last code to be executed, save for any catch blocks that are specific to non-emscripten builds.

Warning: The result of calling this function while the application is already running is undefined.

◆ quit()

virtual void donut::application::Application::quit ( )

virtual

Initiate the shutdown process, meaning that the current frame will be the last to be processed and displayed before the main loop ends.

This method may be overridden by the concrete application to intercept requests to quit and perform application-specific processing before deciding whether to actually quit or not by either calling the base implementation or choosing to ignore the request.

Exceptions

any	exception thrown by the concrete implementation.

Examples: example_game.cpp, and example_rectangle.cpp.

◆ isRunning()

bool donut::application::Application::isRunning ( ) const

inlinenoexcept

Check if the application is currently running, meaning that it is fully initialized, that run() has been called and has started the main loop, and that it is not in the process of shutting down.

Returns: true if the application is currently running, false otherwise.

◆ getLastSecondFrameCount()

unsigned donut::application::Application::getLastSecondFrameCount ( ) const

inlinenoexcept

Get the number of frames displayed during the last measured second of the application's run time, which approximates the average frame rate.

This is measured automatically by counting the number of frames displayed between each second that passes while the application is running.

Returns: the number of frames displayed during the last second that was measured, or 0 if less than one full second has passed since the start of the application.

Note: This approximation of the frame rate does not update frequently enough to be used as an accurate time delta between frames. Use the values that are supplied in the FrameInfo struct to each relevant callback for this purpose instead.

Examples: example_game.cpp.

◆ setFrameRateParameters()

void donut::application::Application::setFrameRateParameters	(	float	tickRate,
		float	minFrameRate,
		float	maxFrameRate
	)

Set the frame rate parameters of the application.

Parameters

tickRate	desired tick rate of the application, in hertz (ticks per second). Set to 0 or a negative value for no ticks.
minFrameRate	minimum frame rate of the application, in hertz (frames per second), before tick slowdown occurs.
maxFrameRate	maximum frame rate of the application, in hertz (frames per second), before frames are delayed. Set to 0 or a negative value for no frame rate limit.

See also: ApplicationOptions::tickRate; ApplicationOptions::minFrameRate; ApplicationOptions::maxFrameRate; setFrameRateLimiterSleepEnabled(); setFrameRateLimiterSleepBias()

◆ setFrameRateLimiterSleepEnabled()

void donut::application::Application::setFrameRateLimiterSleepEnabled ( bool frameRateLimiterSleepEnabled )

Enable or disable frame rate limiter sleep.

Parameters

frameRateLimiterSleepEnabled true to enable frame rate limiter sleep, false to disable.

See also: ApplicationOptions::frameRateLimiterSleepEnabled; setFrameRateParameters(); setFrameRateLimiterSleepBias()

◆ setFrameRateLimiterSleepBias()

void donut::application::Application::setFrameRateLimiterSleepBias ( std::chrono::steady_clock::duration frameRateLimiterSleepBias )

Set the frame rate limiter sleep bias.

Parameters

frameRateLimiterSleepBias new bias to set. Must be non-negative.

See also: ApplicationOptions::frameRateLimiterSleepBias; setFrameRateParameters(); setFrameRateLimiterSleepEnabled()

◆ getLatestTickInfo()

TickInfo donut::application::Application::getLatestTickInfo ( ) const

inlinenoexcept

Get information about the latest tick.

Returns: the latest tick information.

◆ getLatestFrameInfo()

FrameInfo donut::application::Application::getLatestFrameInfo ( ) const

inlinenoexcept

Get information about the latest frame.

Returns: the latest frame information.

◆ update()

virtual void donut::application::Application::update ( FrameInfo frameInfo )

inlineprotectedvirtual

Per-frame update callback, called in the main loop once at the beginning of each frame, before processing ticks.

This is the best time to poll events using an EventPump and apply any changes to interactive application state that depends on user input and is used by tick(), since it minimizes the average latency between processing an input event and it affecting the result of a subsequent tick.

Parameters

frameInfo information about the current frame, see FrameInfo.

Note: Any exception that is thrown out of this function will percolate up to run() and cause the main loop to stop.; The default implementation of this function does nothing.

Warning: The behavior of calling this function manually is undefined.

See also: tick(); display(); getLatestTickInfo()

Examples: example_game.cpp, and example_rectangle.cpp.

◆ tick()

virtual void donut::application::Application::tick ( TickInfo tickInfo )

inlineprotectedvirtual

Fixed-rate tick callback, called in the main loop 0 or more times during tick processing, which happens on each frame after calling update() and before calling display().

See the documentation of TickInfo::tickInterval for an explanation of what this function may be useful for.

Parameters

tickInfo information about the current tick, see TickInfo.

Note: Any exception that is thrown out of this function will percolate up to run() and cause the main loop to stop.; The default implementation of this function does nothing.

Warning: The behavior of calling this function manually is undefined.

See also: update(); display(); getLatestFrameInfo()

Examples: example_game.cpp.

◆ display()

virtual void donut::application::Application::display	(	TickInfo	tickInfo,
		FrameInfo	frameInfo
	)

inlineprotectedvirtual

Frame rendering callback, called in the main loop once at the end of each frame after processing ticks, in order to render the latest state of the application.

Before rendering, this is also the best time to apply any final cosmetic changes to the state of the application that is about to be presented, such as interpolation of data that is updated in tick().

Parameters

tickInfo	information about the latest tick, see TickInfo.
frameInfo	information about the latest frame, see FrameInfo.

Note: Any exception that is thrown out of this function will percolate up to run() and cause the main loop to stop.; The default implementation of this function does nothing.

Warning: The behavior of calling this function manually is undefined.

See also: update(); tick(); getLatestTickInfo()

Examples: example_game.cpp, and example_rectangle.cpp.

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

include/donut/application/Application.hpp

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Application()

◆ ~Application()

Member Function Documentation

◆ run()

◆ quit()

◆ isRunning()

◆ getLastSecondFrameCount()

◆ setFrameRateParameters()

◆ setFrameRateLimiterSleepEnabled()

◆ setFrameRateLimiterSleepBias()

◆ getLatestTickInfo()

◆ getLatestFrameInfo()

◆ update()

◆ tick()

◆ display()