xiiApplication Class Reference

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

#include <Application.h>

Inheritance diagram for xiiApplication:

Public Types
enum class	Execution { Continue , Quit }
	Defines the possible return values for the xiiApplication::Run() function. More...

Public Member Functions
	xiiApplication (xiiStringView sAppName)
	Constructor.
virtual	~xiiApplication ()
	Virtual destructor.
void	SetApplicationName (xiiStringView sAppName)
	Changes the application name.
const xiiString &	GetApplicationName () const
	Returns the application name.
virtual xiiResult	BeforeCoreSystemsStartup ()
	This function is called before any kind of engine initialization is done.
virtual void	AfterCoreSystemsStartup ()
	This function is called after basic engine initialization has been done.
virtual void	BeforeHighLevelSystemsShutdown ()
	This function is called after the application main loop has run for the last time, before engine deinitialization.
virtual void	AfterHighLevelSystemsShutdown ()
	Called after xiiStartup::ShutdownHighLevelSystems() has been executed.
virtual void	BeforeCoreSystemsShutdown ()
	This function is called after the application main loop has run for the last time, before engine deinitialization.
virtual void	AfterCoreSystemsShutdown ()
	This function is called after xiiStartup::ShutdownCoreSystems() has been called.
virtual void	BeforeEnterBackground ()
	This function is called when an application is moved to the background.
virtual void	BeforeEnterForeground ()
	This function is called whenever an application is resumed from background mode.
virtual Execution	Run ()=0
	Main run function which is called periodically. This function must be overridden.
void	SetReturnCode (xiiInt32 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.
xiiInt32	GetReturnCode () const
	Returns the currently set value that the application will return to the OS.
virtual const char *	TranslateReturnCode () const
	If the return code is not zero, this function might be called to get a string to print the error code in human readable form.
void	SetCommandLineArguments (xiiUInt32 uiArgumentCount, const char **pArguments)
	Will set the command line arguments that were passed to the app by the OS. This is automatically called by XII_APPLICATION_ENTRY_POINT() and XII_CONSOLEAPP_ENTRY_POINT().
xiiUInt32	GetArgumentCount () const
	Returns the number of command line arguments that were passed to the application.
const char *	GetArgument (xiiUInt32 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)
bool	IsMemoryLeakReportingEnabled () const
virtual void	RequestQuit ()
	Calling this function requests that the application quits after the current invocation of Run() finishes.
XII_ALWAYS_INLINE bool	WasQuitRequested () const
	Returns whether RequestQuit() was called.

Static Public Member Functions
static xiiApplication *	GetApplicationInstance ()
	Returns the one instance of xiiApplication that is available.

Protected Attributes
bool	m_bWasQuitRequested = false

Friends
XII_FOUNDATION_DLL_FRIEND void	xiiRun (xiiApplication *pApplicationInstance)
	Platform independent run function for main loop based systems (e.g. Win32, ..)
XII_FOUNDATION_DLL_FRIEND xiiResult	xiiRun_Startup (xiiApplication *pApplicationInstance)
	[internal] Called by xiiRun()
XII_FOUNDATION_DLL_FRIEND void	xiiRun_MainLoop (xiiApplication *pApplicationInstance)
	[internal] Called by xiiRun()
XII_FOUNDATION_DLL_FRIEND void	xiiRun_Shutdown (xiiApplication *pApplicationInstance)
	[internal] Called by xiiRun()

Detailed Description

Base class to be used by applications based on XII.

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 xiiApplication 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 XII_APPLICATION_ENTRY_POINT() or XII_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 xiiSampleApp : public xiiApplication
{
public:
 
  virtual void AfterCoreSystemsStartup() override
  {
    // Setup Filesystem, Logging, etc.
  }
 
  virtual void BeforeCoreSystemsShutdown() override
  {
    // Close log file, etc.
  }
 
  virtual xiiApplication::Execution Run() override
  {
    // Either run a one-time application (e.g. console script) and return xiiApplication::Quit
    // Or run one update (frame) of your game loop and return xiiApplication::Continue
 
    return xiiApplication::Quit;
  }
};
 
XII_APPLICATION_ENTRY_POINT(xiiSampleApp);

Member Enumeration Documentation

Execution

enum class xiiApplication::Execution

strong

Defines the possible return values for the xiiApplication::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

AfterCoreSystemsShutdown()

virtual void xiiApplication::AfterCoreSystemsShutdown ( )

inlinevirtual

This function is called after xiiStartup::ShutdownCoreSystems() has been called.

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

AfterCoreSystemsStartup()

virtual void xiiApplication::AfterCoreSystemsStartup ( )

inlinevirtual

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

xiiApplication will automatically call xiiStartup::StartupCoreSystems() 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 xiiStartup and xiiSubSystem.

Reimplemented in xiiEngineProcessGameApplication, xiiFileserverApp, xiiGameApplicationBase, xiiPlayerApplication, xiiShaderCompilerApplication, and xiiTexConv.

BeforeCoreSystemsShutdown()

virtual void xiiApplication::BeforeCoreSystemsShutdown ( )

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 xiiStartup::ShutdownCoreSystems() is called and thus everything, including allocators, is shut down. To shut down entire subsystems, you should, however, use the features provided by xiiStartup and xiiSubSystem.

Reimplemented in xiiEngineProcessGameApplication, xiiFileserverApp, xiiGameApplicationBase, and xiiTexConv.

BeforeCoreSystemsStartup()

xiiResult xiiApplication::BeforeCoreSystemsStartup ( )

virtual

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, xiiStartup::StartupCoreSystems() is automatically called. If you need to set up custom allocators, this is the place to do this.

Reimplemented in xiiEngineProcessGameApplication, xiiFileserverApp, xiiGameApplicationBase, xiiPlayerApplication, xiiShaderCompilerApplication, and xiiTexConv.

BeforeEnterBackground()

virtual void xiiApplication::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.

BeforeEnterForeground()

virtual void xiiApplication::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.

BeforeHighLevelSystemsShutdown()

virtual void xiiApplication::BeforeHighLevelSystemsShutdown ( )

inlinevirtual

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

After this function call, xiiApplication executes xiiStartup::ShutdownHighLevelSystems().

Note

xiiApplication does NOT call xiiStartup::StartupHighLevelSystems() as it may be a window-less application. This is left to xiiGameApplicationBase to do. However, it does make sure to shut down the high-level systems, in case they were started.

Reimplemented in xiiGameApplicationBase.

GetArgumentCount()

xiiUInt32 xiiApplication::GetArgumentCount ( ) const

inline

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

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

RequestQuit()

void xiiApplication::RequestQuit ( )

virtual

Calling this function requests that the application quits after the current invocation of Run() finishes.

Sets the m_bWasQuitRequested to true as an indicator for derived application objects to engage shutdown procedures. Can be overridden to implement custom behavior. There is no other logic associated with this function and flag so the respective derived application class has to implement logic to perform the actual quit when this function is called or m_bWasQuitRequested is set to true.

Run()

virtual Execution xiiApplication::Run ( )

pure virtual

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

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

Implemented in xiiEngineProcessGameApplication, xiiFileserverApp, xiiGameApplicationBase, xiiShaderCompilerApplication, and xiiTexConv.

Friends And Related Symbol Documentation

xiiRun

XII_FOUNDATION_DLL_FRIEND void xiiRun ( xiiApplication * pApplicationInstance )

friend

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

This is automatically called by XII_APPLICATION_ENTRY_POINT() and XII_CONSOLEAPP_ENTRY_POINT().

xiiRun simply calls xiiRun_Startup(), xiiRun_MainLoop() and xiiRun_Shutdown().

---

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

• /home/runner/work/XII/XII/Source/Engine/Foundation/Application/Application.h
• /home/runner/work/XII/XII/Source/Engine/Foundation/Application/Implementation/Application.cpp