CUGL 2.1
Cornell University Game Library
Public Types | Public Member Functions | Static Public Member Functions | Protected Attributes | Static Protected Attributes | List of all members
cugl::Application Class Reference

#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 Applicationget ()
 

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
callbackThe callback function
timeThe number of milliseconds to delay the callback.
periodThe 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
callbackThe callback function
timeThe 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
colorThe 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
widthThe screen width
heightThe 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
fpsThe 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
valueWhether 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
highDPIWhether 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
flagWhether 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
nameThe 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
nameThe 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
nameThe 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
nameThe 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
vsyncWhether 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
idThe 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
timestepThe 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: