CUGL 2.3
Cornell University Game Library
|
#include <CUApplication.h>
Public Types | |
enum class | State : unsigned int { NONE = 0 , STARTUP = 1 , FOREGROUND = 2 , BACKGROUND = 3 , 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 |
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.
|
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 |
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.
|
inline |
Deletes this application, disposing of all resources
|
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.
|
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.
|
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.
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.
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.
|
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.
|
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
.
|
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
.
|
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
.
|
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
.
|
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.
|
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.
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.
|
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.
const std::string cugl::Application::getOpenGLDescription | ( | ) | const |
Returns the OpenGL description for this application
|
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.
|
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
.
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.
|
inline |
|
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.
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.
|
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.
|
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.
|
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.
|
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.
|
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.
|
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.
|
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.
|
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.
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.
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.
callback | The callback function |
time | The number of milliseconds to delay the callback. |
period | The delay until the callback is executed again. |
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.
callback | The callback function |
time | The number of milliseconds to delay the callback. |
|
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.
color | The clear color of this application |
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.
width | The screen width |
height | The screen height |
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.
fps | The target frames per second |
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.
value | Whether this application is running fullscreen |
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.
highDPI | Whether to enable high dpi |
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.
flag | Whether this application should support graphics multisampling. |
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.
name | The name of this application |
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.
name | The name of this application |
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.
name | The organization name for this application |
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.
name | The organization name for this application |
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.
vsync | Whether this application obeys the display refresh rate |
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.
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.
id | The callback identifier |
|
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.
timestep | The amount of time (in seconds) since the last frame |
|
protected |
The asset directory of this application
|
protected |
The default background color of this application
|
protected |
The display bounds of this application
|
protected |
The target FPS of this application
|
protected |
Whether this application is running in fullscreen
|
protected |
Whether this application supports high dpi resolution
|
protected |
Whether this application supports multisampling
|
protected |
The name of this application
|
protected |
The organization name (company) of this application
|
protected |
The SAFE display bounds of this application
|
protected |
The save directory of this application
|
protected |
The current state of this application
|
staticprotected |
A weak pointer to the single application that is running
|
protected |
Whether to respect the display vsync