ezEngine  Milestone 7
ezApplication Class Referenceabstract

Base class to be used by applications based on ezEngine. More...

#include <Application.h>

Inheritance diagram for ezApplication:

Public Types

enum  ApplicationExecution { Continue, Quit }
 Defines the possible return values for the ezApplication::Run() function. More...
 

Public Member Functions

 ezApplication ()
 Constructor.
 
virtual ~ezApplication ()
 Virtual destructor.
 
virtual void BeforeEngineInit ()
 This function is called before any kind of engine initialization is done. More...
 
virtual void AfterEngineInit ()
 This function is called after basic engine initialization has been done. More...
 
virtual void BeforeEngineShutdown ()
 This function is called after the application main loop has run for the last time, before engine deinitialization. More...
 
virtual void AfterEngineShutdown ()
 This function is called after ezStartup::ShutdownBase() has been called. More...
 
virtual void BeforeEnterBackground ()
 This function is called when an application is moved to the background. More...
 
virtual void BeforeEnterForeground ()
 This function is called whenever an application is resumed from background mode. More...
 
virtual ApplicationExecution Run ()=0
 Main run function which is called periodically. This function must be overridden. More...
 
void SetReturnCode (ezInt32 iReturnCode)
 Sets the value that the application will return to the OS. You can call this function at any point during execution to update the return value of the application. Default is zero.
 
ezInt32 GetReturnCode () const
 Returns the currently set value that the application will return to the OS.
 
void SetCommandLineArguments (ezUInt32 uiArgumentCount, const char **ppArguments)
 Will set the command line arguments that were passed to the app by the OS. This is automatically called by EZ_APPLICATION_ENTRY_POINT() and EZ_CONSOLEAPP_ENTRY_POINT().
 
ezUInt32 GetArgumentCount () const
 Returns the number of command lien arguments that were passed to the application. More...
 
const char * GetArgument (ezUInt32 uiArgument) const
 Returns one of the command line arguments that was passed to the application.
 
const char ** GetArgumentsArray () const
 Returns the complete array of command line arguments that were passed to the application.
 
void EnableMemoryLeakReporting (bool bEnable)
 

Static Public Member Functions

static ezApplicationGetApplicationInstance ()
 Returns the one instance of ezApplication that is available.
 

Private Attributes

ezInt32 m_iReturnCode
 
ezUInt32 m_uiArgumentCount
 
const char ** m_ppArguments
 
bool m_bReportMemoryLeaks
 

Static Private Attributes

static ezApplications_pApplicationInstance = nullptr
 

Friends

EZ_CORE_DLL void ezRun (ezApplication *pApplicationInstance)
 Platform independent run function for main loop based systems (e.g. Win32, ..) More...
 

Detailed Description

Base class to be used by applications based on ezEngine.

The platform abstraction layer will ensure that the correct functions are called independent of the basic main loop structure (traditional or event-based). Derive an application specific class from ezApplication and implement at least the abstract Run() function. Additional virtual functions allow to hook into specific events to run application specific code at the correct times.

Finally pass the name of your derived class to one of the macros EZ_APPLICATION_ENTRY_POINT() or EZ_CONSOLEAPP_ENTRY_POINT(). Those are used to abstract away the platform specific code to run an application.

A simple example how to get started is as follows:

class ezSampleApp : public ezApplication
{
public:
virtual void AfterEngineInit() override
{
// Setup Filesystem, Logging, etc.
}
virtual void BeforeEngineShutdown() override
{
// Close log file, etc.
}
{
// Either run a one-time application (e.g. console script) and return ezApplication::Quit
// Or run one update (frame) of your game loop and return ezApplication::Continue
}
};

Member Enumeration Documentation

Defines the possible return values for the ezApplication::Run() function.

Enumerator
Continue 

The 'Run' function should return this to keep the application running.

Quit 

The 'Run' function should return this to quit the application.

Member Function Documentation

virtual void ezApplication::AfterEngineInit ( )
inlinevirtual

This function is called after basic engine initialization has been done.

ezApplication will automatically call ezStartup::StartupCore() to initialize the application. This function can be overridden to do additional application specific initialization. To startup entire subsystems, you should however use the features provided by ezStartup and ezSubSystem.

Reimplemented in ezGameApplication.

virtual void ezApplication::AfterEngineShutdown ( )
inlinevirtual

This function is called after ezStartup::ShutdownBase() has been called.

It is unlikely that there is any kind of deinitialization left, that can still be run at this point.

virtual void ezApplication::BeforeEngineInit ( )
inlinevirtual

This function is called before any kind of engine initialization is done.

Override this function to be able to configure subsystems, before they are initialized. After this function returns, ezStartup::StartupCore() is automatically called. If you need to set up custom allocators, this is the place to do this.

virtual void ezApplication::BeforeEngineShutdown ( )
inlinevirtual

This function is called after the application main loop has run for the last time, before engine deinitialization.

Override this function to do application specific deinitialization that still requires a running engine. After this function returns ezStartup::ShutdownBase() is called and thus everything, including allocators, is shut down. To shut down entire subsystems, you should however use the features provided by ezStartup and ezSubSystem.

Reimplemented in ezGameApplication.

virtual void ezApplication::BeforeEnterBackground ( )
inlinevirtual

This function is called when an application is moved to the background.

On Windows that might simply mean that the main window lost the focus. On other devices this might mean that the application is not visible at all anymore and might even get shut down later. Override this function to be able to put the application into a proper sleep mode.

virtual void ezApplication::BeforeEnterForeground ( )
inlinevirtual

This function is called whenever an application is resumed from background mode.

On Windows that might simply mean that the main window received focus again. On other devices this might mean that the application was suspended and is now active again. Override this function to reload the apps state or other resources, etc.

ezUInt32 ezApplication::GetArgumentCount ( ) const
inline

Returns the number of command lien arguments that were passed to the application.

Note that the very first command line argument is typically the path to the application itself.

virtual ApplicationExecution ezApplication::Run ( )
pure virtual

Main run function which is called periodically. This function must be overridden.

Return ApplicationExecution::Quit when the application should quit. You may set a return code via SetReturnCode() beforehand.

Implemented in ezGameApplication.

Friends And Related Function Documentation

EZ_CORE_DLL void ezRun ( ezApplication pApplicationInstance)
friend

Platform independent run function for main loop based systems (e.g. Win32, ..)

This is automatically called by EZ_APPLICATION_ENTRY_POINT() and EZ_CONSOLEAPP_ENTRY_POINT().


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