Inheritance diagram for plGameApplicationBase:

[legend]

Public Types
using	SUPER = plApplication

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

Public Member Functions
	plGameApplicationBase (plStringView sAppName)

Public Member Functions inherited from plApplication
	plApplication (plStringView sAppName)
	Constructor.

virtual	~plApplication ()
	Virtual destructor.

void	SetApplicationName (plStringView sAppName)
	Changes the application name.

const plString &	GetApplicationName () const
	Returns the application name.

virtual void	AfterHighLevelSystemsShutdown ()
	Called after plStartup::ShutdownHighLevelSystems() has been executed.

virtual void	AfterCoreSystemsShutdown ()
	This function is called after plStartup::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.

void	SetReturnCode (plInt32 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.

plInt32	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 (plUInt32 uiArgumentCount, const char **pArguments)
	Will set the command line arguments that were passed to the app by the OS. This is automatically called by PL_APPLICATION_ENTRY_POINT() and PL_CONSOLEAPP_ENTRY_POINT().

plUInt32	GetArgumentCount () const
	Returns the number of command line arguments that were passed to the application.

const char *	GetArgument (plUInt32 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.

PL_ALWAYS_INLINE bool	WasQuitRequested () const
	Returns whether RequestQuit() was called.

Protected Member Functions
Application Shutdown
virtual void	BeforeHighLevelSystemsShutdown () override
	This function is called after the application main loop has run for the last time, before engine deinitialization.

virtual void	BeforeCoreSystemsShutdown () override
	This function is called after the application main loop has run for the last time, before engine deinitialization.

virtual void	Deinit_ShutdownGraphicsDevice ()=0

virtual void	Deinit_UnloadPlugins ()

virtual void	Deinit_ShutdownLogging ()

Basics
static plGameApplicationBase *	s_pGameApplicationBaseInstance = nullptr

static plGameApplicationBase *	GetGameApplicationBaseInstance ()
	Returns the plGameApplicationBase singleton.

Capturing Data
bool	m_bTakeScreenshot = false

plConsoleFunction< void()>	m_ConFunc_TakeScreenshot
	expose TakeScreenshot() as a console function

void	TakeProfilingCapture ()
	Does a profiling capture and writes it to disk at ':appdata'.

void	TakeScreenshot ()
	Schedules a screenshot to be taken at the end of the frame.

virtual void	StoreScreenshot (plImage &&image, plStringView sContext={})
	Called with the result from taking a screenshot. The default implementation writes the image to disk at ':appdata/Screenshots'.

void	ExecuteTakeScreenshot (plWindowOutputTargetBase *pOutputTarget, plStringView sContext={})

Frame Captures
bool	m_bContinuousFrameCapture = false

bool	m_bCaptureFrame = false

plConsoleFunction< void()>	m_ConFunc_CaptureFrame
	expose CaptureFrame() as a console function

void	CaptureFrame ()
	Schedules a frame capture if the corresponding plugin is loaded.

void	SetContinuousFrameCapture (bool bEnable)
	Controls if frame captures are taken continuously (without being persisted) or only on-demand.

bool	GetContinousFrameCapture () const

virtual plResult	GetAbsFrameCaptureOutputPath (plStringBuilder &ref_sOutputPath)
	Get the absolute base output path for frame captures.

void	ExecuteFrameCapture (plWindowHandle targetWindowHandle, plStringView sContext={})

GameState
plUniquePtr< plGameStateBase >	m_pGameState

plWorld *	m_pWorldLinkedWithGameState = nullptr

plResult	ActivateGameState (plWorld pWorld=nullptr, const plTransform pStartPosition=nullptr)
	Creates and activates the game state for this application.

void	DeactivateGameState ()
	Deactivates and destroys the active game state.

plGameStateBase *	GetActiveGameState () const
	Returns the currently active game state. Could be nullptr.

plGameStateBase *	GetActiveGameStateLinkedToWorld (const plWorld *pWorld) const
	Returns the currently active game state IF it was created for the given world.

virtual plUniquePtr< plGameStateBase >	CreateGameState (plWorld *pWorld)
	Creates a game state for the application to use.

virtual void	ActivateGameStateAtStartup ()
	Allows to override whether a game state is created and activated at application startup.

Platform Profile
plPlatformProfile	m_PlatformProfile

const plPlatformProfile &	GetPlatformProfile () const
	Returns the plPlatformProfile that has been loaded for this application.

Application Startup
plEventSubscriptionID	m_LogToConsoleID = 0

plEventSubscriptionID	m_LogToVsID = 0

plEvent< const plGameApplicationStaticEvent & >	m_StaticEvents

virtual plResult	BeforeCoreSystemsStartup () override
	This function is called before any kind of engine initialization is done.

virtual void	AfterCoreSystemsStartup () override
	This function is called after basic engine initialization has been done.

virtual plString	FindProjectDirectory () const =0
	Returns the target of the 'project' special data directory.

virtual plString	GetBaseDataDirectoryPath () const
	Returns the target of the 'base' data directory.

virtual plString	GetProjectDataDirectoryPath () const
	Returns the target of the 'project' data directory.

virtual void	ExecuteBaseInitFunctions ()
	Executes all 'BaseInit_' functions. Typically done very early, before core system startup.

virtual void	BaseInit_ConfigureLogging ()

virtual void	ExecuteInitFunctions ()
	Executes all 'Init_' functions. Typically done after core system startup.

virtual void	Init_PlatformProfile_SetPreferred ()

virtual void	Init_ConfigureTelemetry ()

virtual void	Init_FileSystem_SetSpecialDirs ()

virtual void	Init_LoadRequiredPlugins ()

virtual void	Init_ConfigureAssetManagement ()

virtual void	Init_FileSystem_ConfigureDataDirs ()

virtual void	Init_LoadWorldModuleConfig ()

virtual void	Init_LoadProjectPlugins ()

virtual void	Init_PlatformProfile_LoadForRuntime ()

virtual void	Init_ConfigureInput ()

virtual void	Init_ConfigureTags ()

virtual void	Init_ConfigureCVars ()

virtual void	Init_SetupGraphicsDevice ()=0

virtual void	Init_SetupDefaultResources ()

Application Execution
plTime	m_FrameTime

plCopyOnBroadcastEvent< const plGameApplicationExecutionEvent & >	m_ExecutionEvents

virtual plApplication::Execution	Run () override
	Main run function which is called periodically. This function must be overridden.

void	RunOneFrame ()

plTime	GetFrameTime () const

virtual bool	IsGameUpdateEnabled () const

virtual void	Run_InputUpdate ()

virtual bool	Run_ProcessApplicationInput ()

virtual void	Run_AcquireImage ()
	This function can be used to acquire a new window from a swap-chain or do any other update operations on windows before the multi-threaded rendering and update phase starts.

virtual void	Run_WorldUpdateAndRender ()=0

virtual void	Run_BeforeWorldUpdate ()

virtual void	Run_AfterWorldUpdate ()

virtual void	Run_UpdatePlugins ()

virtual void	Run_PresentImage ()
	This function can be used to present the final image to a window. It is run at the end of the rendering phase. It can also be used to inspect the swap-chain e.g. for screenshot purposes before presenting.

virtual void	Run_FinishFrame ()

void	UpdateFrameTime ()

Additional Inherited Members
Static Public Member Functions inherited from plApplication
static plApplication *	GetApplicationInstance ()
	Returns the one instance of plApplication that is available.

Protected Attributes inherited from plApplication
bool	m_bWasQuitRequested = false

Member Function Documentation

◆ ActivateGameState()

plResult plGameApplicationBase::ActivateGameState	(	plWorld *	pWorld = nullptr,
		const plTransform *	pStartPosition = nullptr )

Creates and activates the game state for this application.

If the application already has a world (such as the editor), it can pass this to the newly created game state. Otherwise the game state should create its own world.

In the editor case, there are cases where a 'player start position' is specified, which can be used by the game state to place the player.

Broadcasts local event: plGameApplicationStaticEvent::AfterGameStateActivated Broadcasts global event: AfterGameStateActivation(plGameStateBase*)

◆ ActivateGameStateAtStartup()

void plGameApplicationBase::ActivateGameStateAtStartup ( )

protectedvirtual

Allows to override whether a game state is created and activated at application startup.

The default implementation just calls ActivateGameState(), but applications that run inside the editor override this to do nothing, as they only want the game state to become active during simulation, not during editing.

Reimplemented in plEngineProcessGameApplication.

◆ AfterCoreSystemsStartup()

void plGameApplicationBase::AfterCoreSystemsStartup ( )

overrideprotectedvirtual

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

plApplication will automatically call plStartup::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 plStartup and plSubSystem.

Reimplemented from plApplication.

Reimplemented in plEngineProcessGameApplication, plPlayerApplication, and plShaderCompilerApplication.

◆ BeforeCoreSystemsShutdown()

void plGameApplicationBase::BeforeCoreSystemsShutdown ( )

overrideprotectedvirtual

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

Reimplemented from plApplication.

Reimplemented in plEngineProcessGameApplication.

◆ BeforeCoreSystemsStartup()

plResult plGameApplicationBase::BeforeCoreSystemsStartup ( )

overrideprotectedvirtual

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

Reimplemented from plApplication.

Reimplemented in plEngineProcessGameApplication, plPlayerApplication, and plShaderCompilerApplication.

◆ BeforeHighLevelSystemsShutdown()

void plGameApplicationBase::BeforeHighLevelSystemsShutdown ( )

overrideprotectedvirtual

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

After this function call, plApplication executes plStartup::ShutdownHighLevelSystems().

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

Reimplemented from plApplication.

◆ CaptureFrame()

void plGameApplicationBase::CaptureFrame ( )

Schedules a frame capture if the corresponding plugin is loaded.

If continuous capture mode is enabled the currently running frame capture is persisted (and not discarded). Otherwise, the next frame will be captured and persisted.

◆ CreateGameState()

plUniquePtr< plGameStateBase > plGameApplicationBase::CreateGameState ( plWorld * pWorld )

protectedvirtual

Creates a game state for the application to use.

pWorld is typically nullptr in a stand-alone app, but may be existing already when called from the editor.

The default implementation will query all available game states for the best match. By overriding this, one can also just create a specific game state directly.

◆ DeactivateGameState()

void plGameApplicationBase::DeactivateGameState ( )

Deactivates and destroys the active game state.

Broadcasts local event: plGameApplicationStaticEvent::BeforeGameStateDeactivated Broadcasts global event: BeforeGameStateDeactivation(plGameStateBase*)

◆ FindProjectDirectory()

virtual plString plGameApplicationBase::FindProjectDirectory ( ) const

protectedpure virtual

Returns the target of the 'project' special data directory.

The return value of this function will be passed into plFileSystem::SetSpecialDirectory. Afterwards, any path starting with the special directory marker (">project/") will point into this directory.

Implemented in plEngineProcessGameApplication, and plGameApplication.

◆ GetActiveGameStateLinkedToWorld()

plGameStateBase * plGameApplicationBase::GetActiveGameStateLinkedToWorld ( const plWorld * pWorld ) const

Returns the currently active game state IF it was created for the given world.

This is mostly for editor use cases, where some documents want to handle the game state, but only it it was set up for a particular document.

◆ GetBaseDataDirectoryPath()

plString plGameApplicationBase::GetBaseDataDirectoryPath ( ) const

protectedvirtual

Returns the target of the 'base' data directory.

Path needs to start with a special directory marker (">marker/"). This is passed into the target of the 'base' data directory. Target defaults to ">sdk/Data/Base".

◆ GetProjectDataDirectoryPath()

plString plGameApplicationBase::GetProjectDataDirectoryPath ( ) const

protectedvirtual

Returns the target of the 'project' data directory.

Path needs to start with a special directory marker (">marker/"). This is passed into the target of the 'project' data directory. Target defaults to ">project/".

◆ Init_SetupDefaultResources()

void plGameApplicationBase::Init_SetupDefaultResources ( )

protectedvirtual

Reimplemented in plGameApplication.

◆ Run()

plApplication::Execution plGameApplicationBase::Run ( )

overridevirtual

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.

Implements plApplication.

Reimplemented in plEngineProcessGameApplication, and plShaderCompilerApplication.

◆ Run_AcquireImage()

void plGameApplicationBase::Run_AcquireImage ( )

protectedvirtual

This function can be used to acquire a new window from a swap-chain or do any other update operations on windows before the multi-threaded rendering and update phase starts.

Reimplemented in plGameApplication.

◆ Run_PresentImage()

void plGameApplicationBase::Run_PresentImage ( )

protectedvirtual

This function can be used to present the final image to a window. It is run at the end of the rendering phase. It can also be used to inspect the swap-chain e.g. for screenshot purposes before presenting.

Reimplemented in plGameApplication.

◆ SetContinuousFrameCapture()

void plGameApplicationBase::SetContinuousFrameCapture ( bool bEnable )

Controls if frame captures are taken continuously (without being persisted) or only on-demand.

If continuous frame capture is enabled, calling CaptureFrame() will persist the result of the frame capture that is currently in progress. If continuous frame capture is disabled, CaptureFrame() will capture and persist the next frame. Note that continuous capture mode comes with a performance cost, but allows the user to decide on-the-fly if the current frame capture is to be persisted, e.g., when a unit test image comparison fails.

◆ TakeScreenshot()

void plGameApplicationBase::TakeScreenshot ( )

Schedules a screenshot to be taken at the end of the frame.

After taking a screenshot, StoreScreenshot() is executed, which may decide where to write the result to.

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

Code/Engine/Core/GameApplication/GameApplicationBase.h
Code/Engine/Core/GameApplication/Implementation/GameApplicationBase.cpp
Code/Engine/Core/GameApplication/Implementation/GameApplicationBaseInit.cpp

Public Types

Public Member Functions

Protected Member Functions

Basics

Capturing Data

Frame Captures

GameState

Platform Profile

Application Startup

Application Execution

Additional Inherited Members

Member Function Documentation

◆ ActivateGameState()

◆ ActivateGameStateAtStartup()

◆ AfterCoreSystemsStartup()

◆ BeforeCoreSystemsShutdown()

◆ BeforeCoreSystemsStartup()

◆ BeforeHighLevelSystemsShutdown()

◆ CaptureFrame()

◆ CreateGameState()

◆ DeactivateGameState()

◆ FindProjectDirectory()

◆ GetActiveGameStateLinkedToWorld()

◆ GetBaseDataDirectoryPath()

◆ GetProjectDataDirectoryPath()

◆ Init_SetupDefaultResources()

◆ Run()

◆ Run_AcquireImage()

◆ Run_PresentImage()

◆ SetContinuousFrameCapture()

◆ TakeScreenshot()