#include <CUApplication.h>

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

Public Member Functions
	Application ()

	~Application ()

virtual void	dispose ()

bool	init ()

void	setName (const std::string name)

const std::string &	getName () const

void	setVersion (const std::string value)

const std::string &	getVersion () const

void	setAppId (const std::string value)

const std::string &	getAppId () const

void	setCreator (const std::string name)

const std::string &	getCreator () const

void	setOrganization (const std::string name)

const std::string &	getOrganization () const

void	setCopyright (const std::string value)

const std::string &	getCopyright () const

void	setURL (const std::string value)

const std::string &	getURL () const

void	setVSync (bool vsync)

bool	getVSync () const

void	setFullscreen (bool value)

bool	isFullscreen () const

void	setResizable (bool flag)

bool	isResizeable () const

void	setHighDPI (bool highDPI)

bool	isHighDPI () const

void	setMultiSampled (bool flag)

bool	isMultiSampled () const

void	setFPS (float fps)

float	getFPS () const

float	getAverageFPS () const

void	setDeterministic (bool value)

bool	isDeterministic ()

void	setFixedStep (Uint64 step)

long	getFixedStep () const

Uint64	getFixedCount () const

Uint32	getFixedRemainder () const

void	resetFixedRemainder ()

void	setClearColor (Color4 color)

Color4	getClearColor () const

Uint64	getEllapsedMicros () const

State	getState () const

std::string	getAssetDirectory ()

std::string	getSaveDirectory ()

void	setDisplaySize (int width, int height)

void	setDisplayPosition (int x, int y)

void	setDisplayBounds (const Rect &bounds)

const Size &	getDisplaySize () const

const Vec2 &	getDisplayPosition () const

const Rect &	getDisplayBounds () const

const Size &	getDrawableSize () const

const Rect &	getDrawableBounds () const

const Rect &	getSafeBounds () const

float	getPixelScale () const

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

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

void	unschedule (Uint32 id)

void	quit ()

virtual void	onStartup ()

virtual void	onShutdown ()

virtual void	onLowMemory ()

virtual void	onResize ()

virtual void	onSuspend ()

virtual void	onResume ()

virtual void	onEvent (SDL_Event *event)

virtual void	update (float dt)

virtual void	preUpdate (float dt)

virtual void	fixedUpdate (Uint64 step)

virtual void	postUpdate (float dt)

virtual void	draw ()

Static Public Member Functions
static Application *	get ()

static void	setFactory (Factory f)

Protected Attributes
std::string	_name

std::string	_version

std::string	_appid

std::string	_creator

std::string	_org

std::string	_copyright

std::string	_url

std::string	_assetdir

std::string	_savesdir

State	_state

Rect	_display

Rect	_drawable

Rect	_safearea

bool	_fullscreen

bool	_resizable

bool	_highdpi

bool	_multisamp

float	_fps

Uint64	_fixstep

bool	_vsync

bool	_fixed

Color4f	_clearColor

Friends
SDL_AppResult	app_init (void appstate, int argc, char argv)

SDL_AppResult	app_event (void appstate, SDL_Event event)

SDL_AppResult	app_step (void *appstate)

void	app_quit (void *appstate, SDL_AppResult result)

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 instantiated, as it is the (subclass of the) root class. To create a CUGL application, you should subclass this class and register your subclass with the CU_ROOTCLASS macro.

The CU_ROOTCLASS macro will create a singleton object for your application. You can access this singleton via the 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 class 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`.
ABORT	The application has failed. This state is an alternative to `SHUTDOWN`, indicating a failure mode.

Constructor & Destructor Documentation

◆ Application()

cugl::Application::Application ( )

Creates a degnerate application with no backend.

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 backen, 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 contain graphics API calls.

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

◆ fixedUpdate()

virtual void cugl::Application::fixedUpdate ( Uint64 step )

inlinevirtual

The method called to provide a deterministic application loop.

This method provides an application loop that runs at a guaranteed fixed timestep. This method is (logically) invoked every getFixedStep microseconds. By that we mean if the method draw is called at time T, then this method is guaranteed to have been called exactly floor(T/s) times this session, where s is the fixed time step.

This method is always invoked in-between a call to preUpdate and postUpdate. However, to guarantee determinism, it is possible that this method is called multiple times between those two calls. Depending on the value of getFixedStep, it can also (periodically) be called zero times, particularly if getFPS is much faster.

As such, this method should only be used for portions of the application that must be deterministic, such as the physics simulation. It should not be used to process user input (as no user input is recorded between preUpdate and postUpdate) or to animate models.

Parameters

step	The fixed timestep in microseconds

◆ get()

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

static

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

◆ getAppId()

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

inline

Returns the appid name for this application

This should match the appid specified in the project configuration YML, but this is not enforced. If it is not set, then it will just be edu.cornell.gdiac.

Returns: the appid for this 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. This value cannot be accessed until onStartup is called.

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

◆ getCopyright()

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

inline

Returns the copyright information for this application

This copyright is simply used for metadata. If it is not set, then MIT License will be set as the copyright.

Returns: the copyright information for this application

◆ getCreator()

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

inline

Returns the creator name for this application

This creator is simply used for metadata. If it is not set, then GDIAC will be set as the creator.

Returns: the creator name for this application

◆ getDisplayBounds()

const Rect & cugl::Application::getDisplayBounds ( ) const

inline

Returns the screen bounds of this application.

This bounds returned will be in screen coordinates, which may use points instead of pixels. Note that the origin of the screen is typically the top left corner.

Returns: the screen bounds of this application.

◆ getDisplayPosition()

const Vec2 & cugl::Application::getDisplayPosition ( ) const

inline

Returns the screen position of this application.

This position returned will be in screen coordinates, which may use points instead of pixels. Note that the origin of the screen is typically the top left corner.

Returns: the screen position of this application.

◆ getDisplaySize()

const Size & cugl::Application::getDisplaySize ( ) const

inline

Returns the screen size of this application.

This size returned will be in screen coordinates, which may use points instead of pixels.

Returns: the screen size of this application.

◆ getDrawableBounds()

const Rect & cugl::Application::getDrawableBounds ( ) const

inline

Returns the internal drawable bounds of this application.

The value returned will be in pixels, making it suitable for graphics commands. With almost no exceptions, the origin will be (0,0) indicating the lower left corner of the drawable area.

Returns: the internal drawable bounds of this application.

◆ getDrawableSize()

const Size & cugl::Application::getDrawableSize ( ) const

inline

Returns the internal drawable size of this application.

The value returned will be in pixels, making it suitable for graphics commands. The origin of the drawable region will be the lower left corner

Returns: the internal drawable size 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

◆ getFixedCount()

Uint64 cugl::Application::getFixedCount ( ) const

inline

Returns the number of times fixedUpdate has been called.

This value is reset to 0 if setDeterministic is set to false.

Returns: the number of times fixedUpdate has been called.

◆ getFixedRemainder()

Uint32 cugl::Application::getFixedRemainder ( ) const

inline

Returns the time "left over" after the call to fixedUpdate.

If the FPS and the simulation timestep do not perfectly match, the draw method will be invoked with some extra time after the last call to fixedUpdate. It is useful to know this amount of time for the purposes of interpolation. The value returned is in microseconds.

This value is always guaranteed to be less than getFixedStep.

Returns: the time "left over" after the call to fixedUpdate.

◆ getFixedStep()

long cugl::Application::getFixedStep ( ) const

inline

Returns the simulation timestep of this application.

The value defines the rate at which fixedUpdate is called. The rate is a logical value, not a wall-clock value. That is, if draw is called at time T, then the method fixedUpdate will have been called T/s times, where s is the simulation timestep.

This timestep is set in microseconds for the purposes of precision. Note that this value does nothing if setDeterministic is set to false. In that case, fixedUpdate is never called, and update is called instead.

This method may be safely changed at any time while the application is running. By default, this value will match the initial FPS of the application.

Returns: the simulation timestep of this application.

◆ 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. However, it does guarantee that the program never runs faster than this FPS value.

By default, this value is the screen fresh (or 60 if undefined)

Returns: the target frames per second of this application.

◆ 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

◆ 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

◆ getPixelScale()

float cugl::Application::getPixelScale ( ) const

inline

Returns the number of pixels per points in the drawable area.

This value is the ratio of the drawable size to the display size.

Returns: the number of pixels per points in the drawable area.

◆ getSafeBounds()

const Rect & cugl::Application::getSafeBounds ( ) const

inline

Returns the safe area of this application.

The safe area is a subset of getDrawableBounds() that is safe for UI and interactive elements. For phones with notches or rounded corners, it removes those areas that may be hidden. As it is information about the drawable area, it is in pixels, and its origin is relative to the bottom left corner of the display. Note that this value can change should the application reconfigure itself.

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.

This value cannot be accessed until onStartup is called.

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.

◆ getURL()

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

inline

Returns the URL information for this application

This URL is simply used for metadata. If it is not set, then the site

   https://gdiac.cs.cornell.edu

will be used.

Returns: the URL information for this application

◆ getVersion()

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

inline

Returns the version for this application

This version is simply used for metadata. If it is not set, then 1.0 will be set as the version.

Returns: the version for this application

◆ 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 running an OpenGL backend) 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 a graphics backend.

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.

◆ isDeterministic()

bool cugl::Application::isDeterministic ( )

inline

Returns whether the application uses the deterministic loop.

If this value is set to false, then the application will use the simple structure of alternating between update and draw. However, if it is set to true, it will use a more complicated loop in place of update, consisting of a call to preUpdate, followed by zero or more calls to fixedUpdate.

This method may be safely changed at any time while the application is running. By default, this value is false.

Returns: whether the application uses the deterministic loop.

◆ isFullscreen()

bool cugl::Application::isFullscreen ( ) const

inline

Returns true if this application is running fullscreen

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

If this is false, the application will launch as a window centered in the middle of the display.

Returns: true if this application is running fullscreen

◆ isHighDPI()

bool cugl::Application::isHighDPI ( ) const

inline

Returns true if this application uses 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. The effects of this setting can be seen in the method getPixelScale.

Setting high dpi to true is highly recommended for devices 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 uses high dpi resolution.

◆ isMultiSampled()

bool cugl::Application::isMultiSampled ( ) const

inline

Returns true if this application supports graphics multisampling.

Multisampling adds anti-aliasing to the graphics 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.

Note that OpenGL does not support multisampling on mobile platforms.

Returns: true if this application supports graphics multisampling.

◆ isResizeable()

bool cugl::Application::isResizeable ( ) const

inline

Returns true if the application window is resizable

If true, the user can resize the window simply by dragging it. This setting is ignored by for fullscreen applications.

This method is intended to be set at the time the application is created. It cannot be changed once onStartup is called.

Returns: true if the application window is resizable

◆ onEvent()

virtual void cugl::Application::onEvent ( SDL_Event * event )

inlinevirtual

This method is called when an SDL_Event is received.

For the most part, input events are managed by the Input and InputDevice classes. However, SDL has many more input events that are currently supported by CUGL. Overriding this method gives access to these events. This method is called once per event, and is guaranteed to be called after the event has been processed by any relevant CUGL systems, like Input.

Note that SDL_Event objects are designed very differently than CUGL input interfaces. This method is really intended for quick testing or one-off fixes. If you application requires an input that it not currently supported by CUGL, it is better to make your own InputDevice.

◆ 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.

◆ onResize()

virtual void cugl::Application::onResize ( )

inlinevirtual

The method called when the application window is resized

This method will always be called after the size attributes for the application have been updated. You can query the new window size from methods like getDisplayBounds and getDrawableBounds.

Note that this method will be called if either the application display orientation or the safe area changes, even if the actual window size remains unchanged.

◆ 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 this method is called, the application will be in one of two states: SHUTDOWN for a successful shutdown and ABORT for a failure state.

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 the backend is initialized.

This method is called once CUGL methods are safe to access, but before the application starts to run. 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 the state 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.

◆ postUpdate()

virtual void cugl::Application::postUpdate ( float dt )

inlinevirtual

The method called to indicate the end of a deterministic loop.

This method is used instead of update if setDeterministic is set to true. It marks the end of the core application loop, which was begun with a call to preUpdate.

This method is the final portion of the update loop called before any drawing occurs. As such, it should be used to implement any final animation in response to the simulation provided by fixedUpdate. In particular, it should be used to interpolate any visual differences between the the simulation timestep and the FPS.

This method should not be used to process user input, as no new input will have been recorded since preUpdate was called.

Note that the time passed as a parameter is the time measured from the start of the previous frame to the start of the current frame. It is measured before any input or callbacks are processed. It agrees with the value sent to preUpdate this animation frame.

Parameters

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

◆ preUpdate()

virtual void cugl::Application::preUpdate ( float dt )

inlinevirtual

The method called to indicate the start of a deterministic loop.

This method is used instead of update if setDeterministic is set to true. It marks the beginning of the core application loop, which is concluded with a call to postUpdate.

This method should be used to process any events that happen early in the application loop, such as user input or events created by the schedule method. In particular, no new user input will be recorded between the time this method is called and postUpdate is invoked.

Note that the time passed as a parameter is the time measured from the start of the previous frame to the start of the current frame. It is measured before any input or callbacks are processed. It agrees with the value sent to postUpdate this animation frame.

Parameters

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

◆ 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.

◆ resetFixedRemainder()

void cugl::Application::resetFixedRemainder ( )

inline

Resets the time "left over" for fixedUpdate to 0.

This method is for when you need to reset a simulation back to its initial state.

◆ 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

◆ setAppId()

void cugl::Application::setAppId ( const std::string value )

Sets the appid for this application

This should match the appid specified in the project configuration YML, but this is not enforced. If it is not set, then it will just be edu.cornell.gdiac. This method is intended to be set at the time the application is created. It cannot be changed once onStartup is called.

Parameters

value The appid for this application

◆ 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

◆ setCopyright()

void cugl::Application::setCopyright ( const std::string value )

Sets the copyright information for this application

This copyright is simply used for metadata. If it is not set, then MIT License will be set as the copyright. This method is intended to be set at the time the application is created. It cannot be changed once onStartup is called.

Parameters

value The copyright information for this application

◆ setCreator()

void cugl::Application::setCreator ( const std::string name )

Sets the creator name for this application

This creator is simply used for metadata. If it is not set, then GDIAC will be set as the creator. This method is intended to be set at the time the application is created. It cannot be changed once onStartup is called.

Parameters

name	The creator name for this application

◆ setDeterministic()

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

Instructs the application to use the deterministic loop.

If this value is set to false, then the application will use the simple structure of alternating between update and draw. However, if it is set to true, it will use a more complicated loop in place of update, consisting of a call to preUpdate, followed by zero or more calls to fixedUpdate.

This method may be safely changed at any time while the application is running. By default, this value is false.

Parameters

value Whether to use the deterministic loop

◆ setDisplayBounds()

void cugl::Application::setDisplayBounds ( const Rect & bounds )

Sets the screen bounds of this application.

If the application is set to be full screen, this method will be ignored. In that case the application size will be the same as that of the Display. Note that the size should be in screen coordinates, which may use points instead of pixels.

This method may be safely called before the application is initialized. Once onStartup is called, it may only be changed if it is set to be resizable.

Parameters

bounds The screen width

◆ setDisplayPosition()

void cugl::Application::setDisplayPosition	(	int	x,
		int	y
	)

Sets the position of this application.

If the application is set to be full screen, this method will be ignored. Otherwise, this will set the position in screen coordinates, which typically puts the origin at the top left corner.

Parameters

x	The x-coordinate of the top-left corner
y	The y-coordinate of the top-left corner

◆ 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 method will be ignored. In that case the application size will be the same as that of the Display. Note that the size should be in screen coordinates, which may use points instead of pixels.

This method may be safely called before the application is initialized. Once onStartup is called, it may only be changed if it is set to be resizable.

Parameters

width	The screen width
height	The screen height

◆ setFactory()

static void cugl::Application::setFactory ( Factory f )

static

A registration method for setting the root class.

This method is used by CU_ROOTCLASS to set the main application class.

Parameters

f	The factory structure created by CU_ROOTCLASS.

◆ setFixedStep()

void cugl::Application::setFixedStep ( Uint64 step )

Sets the simulation timestep of this application.

The value defines the rate at which fixedUpdate is called. The rate is a logical value, not a wall-clock value. That is, if draw is called at time T, then the method fixedUpdate will have been called T/s times, where s is the simulation timestep.

This timestep is set in microseconds for the purposes of precision. Note that this value does nothing if setDeterministic is set to false. In that case, fixedUpdate is never called, and update is called instead.

This method may be safely changed at any time while the application is running. By default, this value will match the initial FPS of the application.

Parameters

step	The simulation timestep

◆ 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. However, it does guarantee that the program never runs faster than this FPS value.

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

By default, this value is the screen fresh (or 60 if undefined)

Parameters

fps	The target frames per second

◆ setFullscreen()

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

Sets whether this application is running fullscreen

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

If this is false, the application will launch as a window centered in the middle of the display.

This method is intended to be set at the time the application is created. It cannot be changed once onStartup is called.

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. The effects of this setting can be seen in the method getPixelScale.

Setting high dpi to true is highly recommended for devices 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 is intended to be set at the time the application is created. It cannot be changed once onStartup is called.

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 the graphics 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.

Note that OpenGL does not support multisampling on mobile platforms.

This method is intended to be set at the time the application is created. It cannot be changed once onStartup is called.

Parameters

flag	Whether this application should support graphics multisampling.

◆ setName()

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 is intended to be set at the time the application is created. It cannot be changed once onStartup is called.

Parameters

name	The name of this application

◆ setOrganization()

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

◆ setResizable()

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

Sets whether the application window is resizable

If true, the user can resize the window simply by dragging it. This setting is ignored by for fullscreen applications.

This method is intended to be set at the time the application is created. It cannot be changed once onStartup is called.

Parameters

flag	Whether this application is resizable

◆ setURL()

void cugl::Application::setURL ( const std::string value )

Sets the URL information for this application

This URL is simply used for metadata. If it is not set, then the site

   https://gdiac.cs.cornell.edu

will be used. This method is intended to be set at the time the application is created. It cannot be changed once onStartup is called.

Parameters

value The URL information for this application

◆ setVersion()

void cugl::Application::setVersion ( const std::string value )

Sets the version for this application

This version is simply used for metadata. If it is not set, then 1.0 will be set as the version. This method is intended to be set at the time the application is created. It cannot be changed once onStartup is called.

Parameters

value The version 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 running an OpenGL backend) 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.

This method is intended to be set at the time the application is created. It cannot be changed once onStartup is called.

Parameters

vsync Whether this application obeys the display refresh rate

◆ 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 dt )

inlinevirtual

The method called to update the application during a non-deterministic loop.

This is method is provided your core application loop, provided that setDeterministic is false. This method should be replaced with your custom implementation to define your application. This method should contain any code that is not an explicit drawing call. When overriding this method, you do not need to call the parent method at all. The default implmentation does nothing.

This method is not invoked if setDeterministic is set to true. In that case, the application uses preUpdate, fixedUpdate, and postUpdate instead.

Note that the time passed as a parameter is the time measured from the start of the previous frame to the start of the current frame. It is measured before any input or callbacks are processed.

Parameters

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

Friends And Related Symbol Documentation

◆ app_event

SDL_AppResult app_event	(	void *	appstate,
		SDL_Event *	event
	)

friend

Processes an input event for the application

This may be called zero or more times before each invocation of app_step.

This is a hook to the SDL callbacks. You should never call this function yourself.

Parameters

appstate	A reference to the application object
event	The event to process

Returns: the app running state

◆ app_init

SDL_AppResult app_init	(	void **	appstate,
		int	argc,
		char **	argv
	)

friend

Initializes the application object and calls the start-up method.

This function is called after the application singleton is constructed, but before it is properly initialized.

This is a hook to the SDL callbacks. You should never call this function yourself.

Parameters

appstate	Pointer to store the appstate (e.g. the Application object)
argc	The number of command line arguments (unused)
argv	The command line arguments (unused)

Returns: SDL_APP_CONTINUE on successful initialization

◆ app_quit

void app_quit	(	void *	appstate,
		SDL_AppResult	result
	)

friend

Cleanly shuts down the application

This is a hook to the SDL callbacks. You should never call this function yourself.

Parameters

appstate	A reference to the application object
result	The shutdown category (unused)

◆ app_step

SDL_AppResult app_step ( void * appstate )

friend

Processes a single update/draw loop step of the application.

This is a hook to the SDL callbacks. You should never call this function yourself.

Parameters

appstate A reference to the application object

Returns: the app running state

Member Data Documentation

◆ _appid

std::string cugl::Application::_appid

protected

The application id

◆ _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

◆ _copyright

std::string cugl::Application::_copyright

protected

The copyright string for this application

◆ _creator

std::string cugl::Application::_creator

protected

The creator name (can be a person or an organization)

◆ _display

Rect cugl::Application::_display

protected

The display bounds of this application

This value will be in points, not pixels, and will be relative to the global SDL coordinate system.

◆ _drawable

Rect cugl::Application::_drawable

protected

The internal window bounds of this application

This value will be in pixels. The origin will be the bottom left-corner.

◆ _fixed

bool cugl::Application::_fixed

protected

Whether to use a fixed timestep

◆ _fixstep

Uint64 cugl::Application::_fixstep

protected

The time step for the fixed loop

◆ _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) for placing save files

◆ _resizable

bool cugl::Application::_resizable

protected

Whether this application can be resized

◆ _safearea

Rect cugl::Application::_safearea

protected

The SAFE window bounds of this application

This value will be in pixels. This is a subrectangle of _drawable that indicates the area that is safe for interactive elements.

◆ _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

◆ _url

std::string cugl::Application::_url

protected

The game URL

◆ _version

std::string cugl::Application::_version

protected

The version of this application

◆ _vsync

bool cugl::Application::_vsync

protected

Whether to respect the display vsync

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

/Users/wmwhite/Developer/CUGL/include/cugl/core/CUApplication.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Friends

Detailed Description

Member Enumeration Documentation

◆ State

Constructor & Destructor Documentation

◆ Application()

◆ ~Application()

Member Function Documentation

◆ dispose()

◆ draw()

◆ fixedUpdate()

◆ get()

◆ getAppId()

◆ getAssetDirectory()

◆ getAverageFPS()

◆ getClearColor()

◆ getCopyright()

◆ getCreator()

◆ getDisplayBounds()

◆ getDisplayPosition()

◆ getDisplaySize()

◆ getDrawableBounds()

◆ getDrawableSize()

◆ getEllapsedMicros()

◆ getFixedCount()

◆ getFixedRemainder()

◆ getFixedStep()

◆ getFPS()

◆ getName()

◆ getOrganization()

◆ getPixelScale()

◆ getSafeBounds()

◆ getSaveDirectory()

◆ getState()

◆ getURL()

◆ getVersion()

◆ getVSync()

◆ init()

◆ isDeterministic()

◆ isFullscreen()

◆ isHighDPI()

◆ isMultiSampled()

◆ isResizeable()

◆ onEvent()

◆ onLowMemory()

◆ onResize()

◆ onResume()

◆ onShutdown()

◆ onStartup()

◆ onSuspend()

◆ postUpdate()

◆ preUpdate()

◆ quit()

◆ resetFixedRemainder()

◆ schedule() [1/2]

◆ schedule() [2/2]

◆ setAppId()

◆ setClearColor()

◆ setCopyright()

◆ setCreator()

◆ setDeterministic()

◆ setDisplayBounds()

◆ setDisplayPosition()

◆ setDisplaySize()

◆ setFactory()

◆ setFixedStep()

◆ setFPS()

◆ setFullscreen()

◆ setHighDPI()

◆ setMultiSampled()

◆ setName()

◆ setOrganization()

◆ setResizable()

◆ setURL()

◆ setVersion()

◆ setVSync()