#include <CUApplication.h>

Public Types
enum	State : unsigned int { State::NONE = 0, State::STARTUP = 1, State::FOREGROUND = 2, State::BACKGROUND = 3, State::SHUTDOWN = 4 }

Public Member Functions
	Application ()

	~Application ()

virtual void	dispose ()

bool	init ()

virtual void	onStartup ()

virtual void	onShutdown ()

virtual void	onLowMemory ()

virtual void	onSuspend ()

virtual void	onResume ()

virtual void	update (float timestep)

virtual void	draw ()

bool	getInput ()

bool	step ()

void	quit ()

Uint32	schedule (std::function< bool()> callback, Uint32 time=0)

Uint32	schedule (std::function< bool()> callback, Uint32 time, Uint32 period)

void	unschedule (Uint32 id)

void	setDisplaySize (int width, int height)

int	getDisplayWidth () const

int	getDisplayHeight () const

Size	getDisplaySize () const

Rect	getDisplayBounds () const

Rect	getSafeBounds () const

void	setFullscreen (bool value)

bool	isFullscreen () const

void	setHighDPI (bool highDPI)

bool	isHighDPI () const

void	setMultiSampled (bool flag)

bool	isMultiSampled () const

void	setName (const char *name)

void	setName (const std::string &name)

const std::string &	getName () const

void	setOrganization (const char *name)

void	setOrganization (const std::string &name)

const std::string &	getOrganization () const

bool	getVSync () const

void	setVSync (bool vsync)

void	setFPS (float fps)

float	getFPS () const

float	getAverageFPS () const

void	setClearColor (Color4 color)

Color4	getClearColor () const

Uint64	getEllapsedMicros () const

State	getState () const

const std::string	getOpenGLDescription () const

std::string	getAssetDirectory ()

std::string	getSaveDirectory ()

Static Public Member Functions
static Application *	get ()

Protected Attributes
std::string	_name

std::string	_org

std::string	_assetdir

std::string	_savesdir

State	_state

Rect	_display

Rect	_safearea

bool	_fullscreen

bool	_highdpi

bool	_multisamp

float	_fps

bool	_vsync

Color4f	_clearColor

Static Protected Attributes
static Application *	_theapp

Detailed Description

This class represents a basic CUGL application

The application does not assume 2d or 3d. This application can be used with any type of graphics.

This class is not intended to be passed around as a pointer, as it is the (subclass of the) root class. Hence we only have a stack-based initializer for this class.

With that said, we do allow access to the application through static method get(). This allows other parts of the application to get important information like the display size or orientation.

Member Enumeration Documentation

◆ State

enum cugl::Application::State : unsigned int

strong

The current state of the application.

This value is used by SDL to invoke the correct update method at each frame

Enumerator
NONE	The application is not yet initialized. This state indicates that there is no OpenGL context. It is unsafe to make OpenGL calls while in this state.
STARTUP	The application is initialized, but has not yet started This state indicates there is an OpenGL context, and OpenGL calls are now safe. This is the state for initializing the application with user-defined attributes.
FOREGROUND	The application is currently running in the foreground The update-draw loop will be invoked while the application is in this state (and only in this state).
BACKGROUND	The application is currently suspended The update-draw loop will not be invoked while the application is in this state. However, no assets will be deleted unless manually deleted by the programmer.
SHUTDOWN	The application is shutting down. While in this state, the programmer should delete all custom data in the application. The OpenGL context will soon be deleted, and the application will shift back to start State#NONE.

Constructor & Destructor Documentation

◆ Application()

cugl::Application::Application ( )

Creates a degnerate application with no OpenGL context

You must initialize the application to use it. However, you may set any of the attributes before initialization.

◆ ~Application()

cugl::Application::~Application ( )

inline

Deletes this application, disposing of all resources

Member Function Documentation

◆ dispose()

virtual void cugl::Application::dispose ( )

virtual

Disposes all of the resources used by this application.

A disposed Application has no OpenGL context, and cannot be used.
However, it can be safely reinitialized.

◆ draw()

virtual void cugl::Application::draw ( )

inlinevirtual

The method called to draw the application to the screen.

This is your core loop and should be replaced with your custom implementation. This method should OpenGL and related drawing calls.

When overriding this method, you do not need to call the parent method at all. The default implmentation does nothing.

◆ get()

static Application* cugl::Application::get ( )

inlinestatic

Returns the current running application

There can only be one application running a time. While this should never happen, this method will return nullptr if there is no application.

Returns: the current running application

◆ getAssetDirectory()

std::string cugl::Application::getAssetDirectory ( )

Returns the base directory for all assets (e.g. the assets folder).

The assets folder is a READ-ONLY folder for providing assets for the game. Its path depends on the platform involved. Android uses this to refer to the dedicated assets folder, while MacOS/iOS refers to the resource bundle. On Windows, this is the working directory.

The value returned is an absolute path in UTF-8 encoding, and has the appropriate path separator for the given platform ('\' on Windows, '/' most other places). In addition, it is guaranteed to end with a path separator, so that you can append a file name to the path.

It is possible that the the string is empty. For example, the assets directory for Android is not a proper directory (unlike the save directory) and should not be treated as such.

Asset loaders use this directory by default.

Returns: the base directory for all assets (e.g. the assets folder).

◆ getAverageFPS()

float cugl::Application::getAverageFPS ( ) const

Returns the average frames per second over the last 10 frames.

The method provides a way of computing the curren frames per second that smooths out any one-frame anomolies. The FPS is averages over the exact rate of the past 10 frames.

Returns: the average frames per second over the last 10 frames.

◆ getClearColor()

Color4 cugl::Application::getClearColor ( ) const

inline

Returns the clear color of this application

This color is the default background color. The window will be cleared using this color before draw() is called.

Returns: the clear color of this application

◆ getDisplayBounds()

Rect cugl::Application::getDisplayBounds ( ) const

inline

Returns the screen bounds of this application.

If the application is running in windowed mode on a desktop, the bounds origin is the position of the bottom left corner of the window. Otherwise the origin is (0,0).

This value is in pixels, representing the view port size of the OpenGL context. It is never changed, even if the orientation of the device changes. For display information that takes into account the current device orientation, see Display.

Returns: the screen bounds of this application.

◆ getDisplayHeight()

int cugl::Application::getDisplayHeight ( ) const

inline

Returns the screen height of this application.

This value is in pixels, representing the safe view port size of the OpenGL context. It is never changed, even if the orientation of the device changes. For display information that takes into account the current device orientation, see Display.

Returns: the screen height of this application.

◆ getDisplaySize()

Size cugl::Application::getDisplaySize ( ) const

inline

Returns the screen size of this application.

This value is in pixels, representing the safe view port size of the OpenGL context. It is never changed, even if the orientation of the device changes. For display information that takes into account the current device orientation, see Display.

Returns: the screen size of this application.

◆ getDisplayWidth()

int cugl::Application::getDisplayWidth ( ) const

inline

Returns the screen width of this application.

This value is in pixels, representing the safe view port size of the OpenGL context. It is never changed, even if the orientation of the device changes. For display information that takes into account the current device orientation, see Display.

Returns: the screen width of this application.

◆ getEllapsedMicros()

Uint64 cugl::Application::getEllapsedMicros ( ) const

inline

Returns the number of total microseconds that have ellapsed

This is value is measured from the call to init to the current time step. The value is undefined if the application has not been initialized.

Returns: the number of total microseconds that have ellapsed

◆ getFPS()

float cugl::Application::getFPS ( ) const

inline

Returns the target frames per second of this application.

The application does not guarantee that the fps target will always be met. In particular, if the update() and draw() methods are expensive, it may run slower. In addition, if vsync is enabled, it may be ignored entirely (especially if the refresh rate is faster).

This method may be safely changed at any time while the application is running. By default, this value will match the refresh rate of the display, even if vsync is disabled.

Returns: the target frames per second of this application.

◆ getInput()

bool cugl::Application::getInput ( )

Gathers SDL input and distributes it to the event handlers.

Input is gathered at the state of the animation frame, before update is called. As it sends all of its information to the appropriate handlers, you should never need to override this method.

Returns: false if the input indicates that the application should quit.

◆ getName()

const std::string& cugl::Application::getName ( ) const

inline

Returns the name of this application

On a desktop, the name will be displayed at the top of the window. The name also defines the preferences directory – the place where it is safe to write save files.

Returns: the name of this application

◆ getOpenGLDescription()

const std::string cugl::Application::getOpenGLDescription ( ) const

Returns the OpenGL description for this application

Returns: the OpenGL description for this application

◆ getOrganization()

const std::string& cugl::Application::getOrganization ( ) const

inline

Returns the organization name for this application

This name defines the preferences directory – the place where it is safe to write save files. Applications of the same organization will save in the same location.

Returns: the organization name for this application

◆ getSafeBounds()

Rect cugl::Application::getSafeBounds ( ) const

inline

Returns the safe area of this application.

The safe area is a subset of getDisplayBounds() that is safe for UI and interactive elements. For phones with notches or rounded corners, it removes those areas that may be hidden.

This value is in pixels, representing the safe view port size of the OpenGL context. It is never changed, even if the orientation of the device changes. For display information that takes into account the current device orientation, see Display.

Returns: the safe area of this application.

◆ getSaveDirectory()

std::string cugl::Application::getSaveDirectory ( )

Returns the base directory for writing save files and preferences.

The save folder is a READ-WRITE folder for storing saved games and preferences. The folder is unique to the current user. On desktop platforms, it is typically in the user's home directory. You must use this folder (and not the asset folder) if you are writing any files.

The value returned is an absolute path in UTF-8 encoding, and has the appropriate path separator for the given platform ('\' on Windows, '/' most other places). In addition, it is guaranteed to end with a path separator, so that you can append a file name to the path.

I/O classes (both readers and writers) use this directory by default.
However, if you are want to use this directory in an asset loader (e.g. for a saved game file), you you may want to refer to the path directly.

Returns: the base directory for writing save files and preferences.

◆ getState()

State cugl::Application::getState ( ) const

inline

Returns the current state of this application.

This state is guaranteed to be FOREGROUND whenever update() or draw() are called.

◆ getVSync()

bool cugl::Application::getVSync ( ) const

inline

Returns true if this application obeys the display refresh rate

A vsync-enabled application will always match the refresh rate of the display. Otherwise, the application will attempt to match the value of getFPS(), which could be faster than the refresh rate.

Note that some platforms (notably macOS) will always use vsync no matter the settings. In that case, setting this value to false will actually hurt the performance of your application. As a general rule, it is best to set this value to true, and perform any simulations that must be done at a faster rate in a separate thread.

Returns: true if this application obeys the display refresh rate

◆ init()

bool cugl::Application::init ( )

Initializes this application, creating an OpenGL context.

The initialization will use the current value of all of the attributes, like application name, orientation, and size. These values should be set before calling init().

CUGL only supports one application running at a time. This method will fail if there is another application object.

You should not override this method to initialize user-defined attributes. Use the method onStartup() instead.

Returns: true if initialization was successful.

◆ isFullscreen()

bool cugl::Application::isFullscreen ( ) const

inline

Returns true if this application is running fullscreen

Mobile devices must always run fullscreen, and can never be windowed.

On desktop/laptop platforms, going fullscreen will hide the mouse. The mouse cursor is only visible in windowed mode.

Returns: true if this application is running fullscreen

◆ isHighDPI()

bool cugl::Application::isHighDPI ( ) const

inline

Returns true if this application supports high dpi resolution.

For devices that have high dpi screens (e.g. a pixel ration greater than 1), this will enable that feature. Otherwise, this value will do nothing.

Setting high dpi to true is highly recommended for devides that support it (e.g. iPhones). It makes the edges of textures much smoother. However, rendering is slightly slower as it effectively doubles (and in some cases triples) the resolution.

Returns: true if this application supports high dpi resolution.

◆ isMultiSampled()

bool cugl::Application::isMultiSampled ( ) const

inline

Returns true if this application supports graphics multisampling.

Multisampling adds anti-aliasing to OpenGL so that polygon edges are not so hard and jagged. This does add some extra overhead, and is not really necessary on Retina or high DPI displays. However, it is pretty much a must in Windows and normal displays.

By default, this is false on any platform other than Windows.

Returns: true if this application supports graphics multisampling.

◆ onLowMemory()

virtual void cugl::Application::onLowMemory ( )

inlinevirtual

The method called when you are running out of memory.

When this method is called, you should immediately free memory or cause the application to quit. Texture memory is generally the biggest candidate for freeing memory; delete all textures you are not using.

When overriding this method, you do not need to call the parent method at all. The default implmentation does nothing.

◆ onResume()

virtual void cugl::Application::onResume ( )

inlinevirtual

The method called when the application resumes and put in the foreground.

If you saved any state before going into the background, now is the time to restore it. This guarantees that the application looks the same as when it was suspended.

If you are using audio, you should use this method to resume any audio paused before app suspension.

◆ onShutdown()

virtual void cugl::Application::onShutdown ( )

virtual

The method called when the application is ready to quit.

This is the method to dispose of all resources allocated by this application. As a rule of thumb, everything created in onStartup() should be deleted here.

When overriding this method, you should call the parent method as the very last line. This ensures that the state will transition to NONE, causing the application to be deleted.

◆ onStartup()

virtual void cugl::Application::onStartup ( )

virtual

The method called after OpenGL is initialized, but before running the application.

This is the method in which all user-defined program intialization should take place. You should not create a new init() method.

When overriding this method, you should call the parent method as the very last line. This ensures that the state will transition to FOREGROUND, causing the application to run.

◆ onSuspend()

virtual void cugl::Application::onSuspend ( )

inlinevirtual

The method called when the application is suspended and put in the background.

When this method is called, you should store any state that you do not want to be lost. There is no guarantee that an application will return from the background; it may be terminated instead.

If you are using audio, it is critical that you pause it on suspension. Otherwise, the audio thread may persist while the application is in the background.

◆ quit()

void cugl::Application::quit ( )

Cleanly shuts down the application.

This method will shutdown the application in a way that is guaranteed to call onShutdown() for clean-up. You should use this method instead of a general C++ exit() function.

This method uses the SDL event system. Therefore, the application will quit at the start of the next animation frame, when all events are processed.

◆ schedule() [1/2]

Uint32 cugl::Application::schedule	(	std::function< bool()>	callback,
		Uint32	time,
		Uint32	period
	)

Schedules a reoccuring callback function time milliseconds in the future.

This method allows the user to delay an operation until a certain length of time has passed. If time is 0, it will be called the next animation frame. Otherwise, it will be called the first animation frame equal to or more than time steps in the future (so there is no guarantee that the callback will be invoked at exactly time milliseconds in the future).

The callback will only be executed on a regular basis. Once it is called, the timer will be reset and it will not be called for another period milliseconds. Hence it is possible to delay the callback for a long time, but then have it execute every frame. If the callback started late, that extra time waited will be credited to the next call.

The callback is guaranteed to be executed in the main thread, so it is safe to access the OpenGL context or any low-level SDL operations. It will be executed after the input has been processed, but before the main update thread.

Parameters

callback	The callback function
time	The number of milliseconds to delay the callback.
period	The delay until the callback is executed again.

Returns: a unique identifier for the schedule callback

◆ schedule() [2/2]

Uint32 cugl::Application::schedule	(	std::function< bool()>	callback,
		Uint32	time = `0`
	)

Schedules a reoccuring callback function time milliseconds in the future.

This method allows the user to delay an operation until a certain length of time has passed. If time is 0, it will be called the next animation frame. Otherwise, it will be called the first animation frame equal to or more than time steps in the future (so there is no guarantee that the callback will be invoked at exactly time milliseconds in the future).

The callback will only be executed on a regular basis. Once it is called, the timer will be reset and it will not be called for another time milliseconds. If the callback started late, that extra time waited will be credited to the next call.

The callback is guaranteed to be executed in the main thread, so it is safe to access the OpenGL context or any low-level SDL operations. It will be executed after the input has been processed, but before the main update thread.

Parameters

callback	The callback function
time	The number of milliseconds to delay the callback.

Returns: a unique identifier for the schedule callback

◆ setClearColor()

void cugl::Application::setClearColor ( Color4 color )

inline

Sets the clear color of this application

This color is the default background color. The window will be cleared using this color before draw() is called.

This method may be safely changed at any time while the application is running.

Parameters

color The clear color of this application

◆ setDisplaySize()

void cugl::Application::setDisplaySize	(	int	width,
		int	height
	)

Sets the screen size of this application.

If the application is set to be full screen, this value will be ignored. Instead, the application size will be the same as the Display.

This method may only be safely called before the application is initialized. Once the application is initialized; this value may not be changed.

Parameters

width	The screen width
height	The screen height

◆ setFPS()

void cugl::Application::setFPS ( float fps )

Sets the target frames per second of this application.

The application does not guarantee that the fps target will always be met. In particular, if the update() and draw() methods are expensive, it may run slower. In addition, if vsync is enabled, it may be ignored entirely (especially if the refresh rate is faster).

This method may be safely changed at any time while the application is running. By default, this value will match the refresh rate of the display, even if vsync is disabled.

Parameters

fps	The target frames per second

◆ setFullscreen()

void cugl::Application::setFullscreen ( bool value )

Sets whether this application is running fullscreen

Mobile devices must always run fullscreen, and can never be windowed. In addition, this method may only be safely called before the application is initialized. Once the application is initialized; this value may not be changed.

On desktop/laptop platforms, going fullscreen will hide the mouse. The mouse cursor is only visible in windowed mode.

Parameters

value Whether this application is running fullscreen

◆ setHighDPI()

void cugl::Application::setHighDPI ( bool highDPI )

Sets whether this application supports high dpi resolution.

For devices that have high dpi screens (e.g. a pixel ration greater than 1), this will enable that feature. Otherwise, this value will do nothing.

Setting high dpi to true is highly recommended for devides that support it (e.g. iPhones). It makes the edges of textures much smoother. However, rendering is slightly slower as it effectively doubles (and in some cases triples) the resolution.

This method may only be safely called before the application is initialized. Once the application is initialized; this value may not be changed.

Parameters

highDPI Whether to enable high dpi

◆ setMultiSampled()

void cugl::Application::setMultiSampled ( bool flag )

Sets whether this application supports graphics multisampling.

Multisampling adds anti-aliasing to OpenGL so that polygon edges are not so hard and jagged. This does add some extra overhead, and is not really necessary on Retina or high DPI displays. However, it is pretty much a must in Windows and normal displays.

By default, this is false on any platform other than Windows.

Parameters

flag	Whether this application should support graphics multisampling.

◆ setName() [1/2]

void cugl::Application::setName ( const char * name )

Sets the name of this application

On a desktop, the name will be displayed at the top of the window. The name also defines the preferences directory – the place where it is safe to write save files.

This method may be safely changed at any time while the application is running.

Parameters

name	The name of this application

◆ setName() [2/2]

void cugl::Application::setName ( const std::string & name )

Sets the name of this application

On a desktop, the name will be displayed at the top of the window. The name also defines the preferences directory – the place where it is safe to write save files.

This method may be safely changed at any time while the application is running.

Parameters

name	The name of this application

◆ setOrganization() [1/2]

void cugl::Application::setOrganization ( const char * name )

Sets the organization name for this application

This name defines the preferences directory – the place where it is safe to write save files. Applications of the same organization will save in the same location.

This method may be safely changed at any time while the application is running.

Parameters

name	The organization name for this application

◆ setOrganization() [2/2]

void cugl::Application::setOrganization ( const std::string & name )

Sets the organization name for this application

This name defines the preferences directory – the place where it is safe to write save files. Applications of the same organization will save in the same location.

This method may be safely changed at any time while the application is running.

Parameters

name	The organization name for this application

◆ setVSync()

void cugl::Application::setVSync ( bool vsync )

Sets whether this application obeys the display refresh rate

A vsync-enabled application will always match the refresh rate of the display. Otherwise, the application will attempt to match the value of getFPS(), which could be faster than the refresh rate.

Note that some platforms (notably macOS) will always use vsync no matter the settings. In that case, setting this value to false will actually hurt the performance of your application. As a general rule, it is best to set this value to true, and perform any simulations that must be done at a faster rate in a separate thread.

Parameters

vsync Whether this application obeys the display refresh rate

◆ step()

bool cugl::Application::step ( )

Processes a single animation frame.

This method processes the input, calls the update method, and then draws it. It also updates any running statics, like the average FPS.

Returns: false if the application should quit next frame

◆ unschedule()

void cugl::Application::unschedule ( Uint32 id )

Stops a callback function from being executed.

This method may be used to disable a reoccuring callback. If called soon enough, it can also disable a one-time callback that is yet to be executed. Once unscheduled, a callback must be re-scheduled in order to be activated again.

The callback is identified by the unique identifier returned by the appropriate schedule function. Hence this value should be saved if you ever wish to unschedule a callback.

Parameters

id	The callback identifier

◆ update()

virtual void cugl::Application::update ( float timestep )

inlinevirtual

The method called to update the application data.

This is your core loop and should be replaced with your custom implementation. This method should contain any code that is not an OpenGL call.

When overriding this method, you do not need to call the parent method at all. The default implmentation does nothing.

Parameters

timestep The amount of time (in seconds) since the last frame

Member Data Documentation

◆ _assetdir

std::string cugl::Application::_assetdir

protected

The asset directory of this application

◆ _clearColor

Color4f cugl::Application::_clearColor

protected

The default background color of this application

◆ _display

Rect cugl::Application::_display

protected

The display bounds of this application

◆ _fps

float cugl::Application::_fps

protected

The target FPS of this application

◆ _fullscreen

bool cugl::Application::_fullscreen

protected

Whether this application is running in fullscreen

◆ _highdpi

bool cugl::Application::_highdpi

protected

Whether this application supports high dpi resolution

◆ _multisamp

bool cugl::Application::_multisamp

protected

Whether this application supports multisampling

◆ _name

std::string cugl::Application::_name

protected

The name of this application

◆ _org

std::string cugl::Application::_org

protected

The organization name (company) of this application

◆ _safearea

Rect cugl::Application::_safearea

protected

The SAFE display bounds of this application

◆ _savesdir

std::string cugl::Application::_savesdir

protected

The save directory of this application

◆ _state

State cugl::Application::_state

protected

The current state of this application

◆ _theapp

Application* cugl::Application::_theapp

staticprotected

A weak pointer to the single application that is running

◆ _vsync

bool cugl::Application::_vsync

protected

Whether to respect the display vsync

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

include/cugl/base/CUApplication.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ State

Constructor & Destructor Documentation

◆ Application()

◆ ~Application()

Member Function Documentation

◆ dispose()

◆ draw()

◆ get()

◆ getAssetDirectory()

◆ getAverageFPS()

◆ getClearColor()

◆ getDisplayBounds()

◆ getDisplayHeight()

◆ getDisplaySize()

◆ getDisplayWidth()

◆ getEllapsedMicros()

◆ getFPS()

◆ getInput()

◆ getName()

◆ getOpenGLDescription()

◆ getOrganization()

◆ getSafeBounds()

◆ getSaveDirectory()

◆ getState()

◆ getVSync()

◆ init()

◆ isFullscreen()

◆ isHighDPI()

◆ isMultiSampled()

◆ onLowMemory()

◆ onResume()

◆ onShutdown()

◆ onStartup()

◆ onSuspend()

◆ quit()

◆ schedule() [1/2]

◆ schedule() [2/2]

◆ setClearColor()

◆ setDisplaySize()

◆ setFPS()

◆ setFullscreen()

◆ setHighDPI()

◆ setMultiSampled()

◆ setName() [1/2]

◆ setName() [2/2]

◆ setOrganization() [1/2]

◆ setOrganization() [2/2]

◆ setVSync()

◆ step()

◆ unschedule()

◆ update()

Member Data Documentation

◆ _assetdir

◆ _clearColor

◆ _display

◆ _fps

◆ _fullscreen

◆ _highdpi

◆ _multisamp

◆ _name

◆ _org

◆ _safearea

◆ _savesdir

◆ _state

◆ _theapp

◆ _vsync