ezEngine  Milestone 9
ezGameApplicationBase Class Referenceabstract
Inheritance diagram for ezGameApplicationBase:

Classes

struct  WindowContext
 

Public Types

typedef ezApplication SUPER
 
- Public Types inherited from ezApplication
enum  ApplicationExecution { Continue, Quit }
 Defines the possible return values for the ezApplication::Run() function. More...
 

Public Member Functions

 ezGameApplicationBase (const char *szAppName)
 
- Public Member Functions inherited from ezApplication
 ezApplication (const char *szAppName)
 Constructor.
 
virtual ~ezApplication ()
 Virtual destructor.
 
void SetApplicationName (const char *szAppName)
 Changes the application name.
 
const ezStringGetApplicationName () const
 Returns the application name.
 
virtual void AfterHighLevelSystemsShutdown ()
 Called after ezStartup::ShutdownHighLevelSystems() has been executed.
 
virtual void AfterCoreSystemsShutdown ()
 This function is called after ezStartup::ShutdownCoreSystems() 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...
 
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.
 
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 (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)
 
bool IsMemoryLeakReportingEnabled () const
 

Protected Member Functions

Application Startup
virtual void BeforeCoreSystemsStartup () override
 This function is called before any kind of engine initialization is done. More...
 
virtual void AfterCoreSystemsStartup () override
 This function is called after basic engine initialization has been done. More...
 
virtual ezString FindProjectDirectory () const =0
 
virtual ezString GetBaseDataDirectoryPath () const
 
virtual void ExecuteInitFunctions ()
 
virtual void Init_PlatformProfile_SetPreferred ()
 
virtual void Init_ConfigureLogging ()
 
virtual void Init_ConfigureTelemetry ()
 
virtual void Init_FileSystem_SetSpecialDirs ()
 
virtual void Init_FileSystem_SetDataDirFactories ()
 
virtual void Init_LoadRequiredPlugins ()
 
virtual void Init_ConfigureAssetManagement ()
 
virtual void Init_FileSystem_ConfigureDataDirs ()
 
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 Shutdown
virtual void BeforeHighLevelSystemsShutdown () override
 This function is called after the application main loop has run for the last time, before engine deinitialization. More...
 
virtual void BeforeCoreSystemsShutdown () override
 This function is called after the application main loop has run for the last time, before engine deinitialization. More...
 
virtual void Deinit_ShutdownGraphicsDevice ()=0
 
virtual void Deinit_UnloadPlugins ()
 
virtual void Deinit_ShutdownLogging ()
 

Basics

static ezGameApplicationBases_pGameApplicationBaseInstance = nullptr
 
bool m_bWasQuitRequested = false
 
virtual void RequestQuit ()
 Calling this function requests that the application quits after the current invocation of Run() finishes. More...
 
EZ_ALWAYS_INLINE bool WasQuitRequested () const
 Returns whether RequestQuit() was called.
 
static ezGameApplicationBaseGetGameApplicationBaseInstance ()
 Returns the ezGameApplicationBase singleton.
 

Window Management

ezDynamicArray< WindowContextm_Windows
 
ezWindowOutputTargetBaseAddWindow (ezWindowBase *pWindow)
 Adds a top level window to the application. More...
 
void AddWindow (ezWindowBase *pWindow, ezUniquePtr< ezWindowOutputTargetBase > pOutputTarget)
 Adds a top level window to the application with a custom output target.
 
void RemoveWindow (ezWindowBase *pWindow)
 Removes a previously added window. Destroys its output target. Should be called at application shutdown.
 
virtual void AdjustWindowCreation (ezWindowCreationDesc &desc)
 Can be called by code that creates windows (e.g. an ezGameStateBase) to adjust or override settings, such as the window title or resolution.
 
bool ProcessWindowMessages ()
 Calls ezWindowBase::ProcessWindowMessages() on all known windows. Returns true, if any windows are available, at all. More...
 
ezWindowOutputTargetBaseGetWindowOutputTarget (const ezWindowBase *pWindow) const
 Returns the ezWindowOutputTargetBase object that is associated with the given window. The window must have been added via AddWindow()
 
void SetWindowOutputTarget (const ezWindowBase *pWindow, ezUniquePtr< ezWindowOutputTargetBase > pOutputTarget)
 Sets the ezWindowOutputTargetBase for a given window. The window must have been added via AddWindow() More...
 
void TakeProfilingCapture ()
 Does a profiling capture and writes it to disk at ':appdata'.
 
virtual ezUniquePtr< ezWindowOutputTargetBaseCreateWindowOutputTarget (ezWindowBase *pWindow)=0
 
virtual void DestroyWindowOutputTarget (ezUniquePtr< ezWindowOutputTargetBase > pOutputTarget)=0
 

Screenshots

bool m_bTakeScreenshot = false
 
ezConsoleFunction< void()> m_ConFunc_TakeScreenshot
 expose TakeScreenshot() as a console function
 
void TakeScreenshot ()
 Schedules a screenshot to be taken at the end of the frame. More...
 
virtual void StoreScreenshot (ezImage &&image, const char *szContext=nullptr)
 Called with the result from taking a screenshot. The default implementation writes the image to disk at ':appdata/Screenshots'.
 
void ExecuteTakeScreenshot (ezWindowOutputTargetBase *pOutputTarget, const char *szContext=nullptr)
 

Frame Captures

bool m_bContinuousFrameCapture = false
 
bool m_bCaptureFrame = false
 
ezConsoleFunction< void()> m_ConFunc_CaptureFrame
 expose CaptureFrame() as a console function
 
void CaptureFrame ()
 Schedules a frame capture if the corresponding plugin is loaded. More...
 
void SetContinuousFrameCapture (bool enable)
 Controls if frame captures are taken continuously (without being persisted) or only on-demand. More...
 
bool GetContinousFrameCapture () const
 
virtual ezResult GetAbsFrameCaptureOutputPath (ezStringBuilder &sOutputPath)
 Get the absolute base output path for frame captures.
 
void ExecuteFrameCapture (ezWindowHandle targetWindowHandle, const char *szContext=nullptr)
 

GameState

ezUniquePtr< ezGameStateBasem_pGameState
 
ezWorldm_pWorldLinkedWithGameState = nullptr
 
ezResult ActivateGameState (ezWorld *pWorld=nullptr, const ezTransform *pStartPosition=nullptr)
 Creates and activates the game state for this application. More...
 
void DeactivateGameState ()
 Deactivates and destroys the active game state.
 
ezGameStateBaseGetActiveGameState () const
 Returns the currently active game state. Could be nullptr.
 
ezGameStateBaseGetActiveGameStateLinkedToWorld (ezWorld *pWorld) const
 Returns the currently active game state IF it was created for the given world. More...
 
virtual ezUniquePtr< ezGameStateBaseCreateGameState (ezWorld *pWorld)
 Creates a game state for the application to use. More...
 
virtual void ActivateGameStateAtStartup ()
 Allows to override whether a game state is created and activated at application startup. More...
 

Platform Profile

ezPlatformProfile m_PlatformProfile
 
const ezPlatformProfileGetPlatformProfile () const
 Returns the ezPlatformProfile that has been loaded for this application.
 

Application Execution

ezEvent< const ezGameApplicationExecutionEvent & > m_ExecutionEvents
 
virtual ezApplication::ApplicationExecution Run () override
 Main run function which is called periodically. This function must be overridden. More...
 
virtual bool IsGameUpdateEnabled () const
 
virtual void Run_InputUpdate ()
 
virtual bool Run_ProcessApplicationInput ()
 
virtual void Run_WorldUpdateAndRender ()=0
 
virtual void Run_BeforeWorldUpdate ()
 
virtual void Run_AfterWorldUpdate ()
 
virtual void Run_UpdatePlugins ()
 
virtual void Run_FinishFrame ()
 

Additional Inherited Members

- Static Public Member Functions inherited from ezApplication
static ezApplicationGetApplicationInstance ()
 Returns the one instance of ezApplication that is available.
 

Member Function Documentation

◆ ActivateGameState()

ezResult ezGameApplicationBase::ActivateGameState ( ezWorld pWorld = nullptr,
const ezTransform 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.

◆ ActivateGameStateAtStartup()

void ezGameApplicationBase::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 ezEngineProcessGameApplication.

◆ AddWindow()

ezWindowOutputTargetBase * ezGameApplicationBase::AddWindow ( ezWindowBase pWindow)

Adds a top level window to the application.

An output target is created for that window. Run() will call ezWindowBase::ProcessWindowMessages() on all windows that have been added. Most applications should add exactly one such window to the game application. Only few applications will add zero or multiple windows.

◆ AfterCoreSystemsStartup()

void ezGameApplicationBase::AfterCoreSystemsStartup ( )
overrideprotectedvirtual

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

ezApplication will automatically call ezStartup::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 ezStartup and ezSubSystem.

Reimplemented from ezApplication.

Reimplemented in ezEngineProcessGameApplication.

◆ BeforeCoreSystemsShutdown()

void ezGameApplicationBase::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 ezStartup::ShutdownCoreSystems() 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 from ezApplication.

Reimplemented in ezEngineProcessGameApplication.

◆ BeforeCoreSystemsStartup()

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

Reimplemented from ezApplication.

Reimplemented in ezGameApplication, and ezEngineProcessGameApplication.

◆ BeforeHighLevelSystemsShutdown()

void ezGameApplicationBase::BeforeHighLevelSystemsShutdown ( )
overrideprotectedvirtual

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

After this function call, ezApplication executes ezStartup::ShutdownHighLevelSystems().

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

Reimplemented from ezApplication.

◆ CaptureFrame()

void ezGameApplicationBase::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()

ezUniquePtr< ezGameStateBase > ezGameApplicationBase::CreateGameState ( ezWorld 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.

◆ GetActiveGameStateLinkedToWorld()

ezGameStateBase * ezGameApplicationBase::GetActiveGameStateLinkedToWorld ( ezWorld 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.

◆ ProcessWindowMessages()

bool ezGameApplicationBase::ProcessWindowMessages ( )

Calls ezWindowBase::ProcessWindowMessages() on all known windows. Returns true, if any windows are available, at all.

Note
This should actually never be executed manually. It is only public for very specific edge cases. Otherwise this function is automatically executed once every frame.

◆ RequestQuit()

void ezGameApplicationBase::RequestQuit ( )
virtual

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

Can be overridden to prevent quitting under certain conditions.

◆ Run()

ezApplication::ApplicationExecution ezGameApplicationBase::Run ( )
overridevirtual

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.

Implements ezApplication.

Reimplemented in ezEngineProcessGameApplication, and ezShaderCompilerApplication.

◆ SetContinuousFrameCapture()

void ezGameApplicationBase::SetContinuousFrameCapture ( bool  enable)

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.

◆ SetWindowOutputTarget()

void ezGameApplicationBase::SetWindowOutputTarget ( const ezWindowBase pWindow,
ezUniquePtr< ezWindowOutputTargetBase pOutputTarget 
)

Sets the ezWindowOutputTargetBase for a given window. The window must have been added via AddWindow()

The previous ezWindowOutputTargetBase object (if any) will be destroyed.

◆ TakeScreenshot()

void ezGameApplicationBase::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: