ezEngine  Milestone 9
ezGameApplication Class Reference

The base class for all typical game applications made with ezEngine. More...

#include <GameApplication.h>

Inheritance diagram for ezGameApplication:

Public Types

typedef ezGameApplicationBase SUPER
 
- Public Types inherited from ezGameApplicationBase
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

 ezGameApplication (const char *szAppName, const char *szProjectPath)
 szProjectPath may be nullptr, if FindProjectDirectory() is overridden.
 
virtual ezString FindProjectDirectory () const override
 virtual function that is called by DoProjectSetup(). The result is passed to ezFileSystem::SetProjectDirectory More...
 
void ReinitializeInputConfig ()
 Used at runtime (by the editor) to reload input maps. Forwards to Init_ConfigureInput()
 
- Public Member Functions inherited from ezGameApplicationBase
 ezGameApplicationBase (const char *szAppName)
 
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.
 
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'.
 
void TakeScreenshot ()
 Schedules a screenshot to be taken at the end of the frame. More...
 
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.
 
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...
 
const ezPlatformProfileGetPlatformProfile () const
 Returns the ezPlatformProfile that has been loaded for this application.
 
virtual ezApplication::ApplicationExecution Run () override
 Main run function which is called periodically. This function must be overridden. More...
 
- 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
 

Static Public Member Functions

static ezGameApplicationGetGameApplicationInstance ()
 Returns the ezGameApplication singleton.
 
static void SetOverrideDefaultDeviceCreator (ezDelegate< ezGALDevice *(const ezGALDeviceCreationDescription &)> creator)
 When the graphics device is created, by default the game application will pick a platform specific implementation. This function allows to override that by setting a custom function that creates a graphics device.
 
- Static Public Member Functions inherited from ezGameApplicationBase
static ezGameApplicationBaseGetGameApplicationBaseInstance ()
 Returns the ezGameApplicationBase singleton.
 
- Static Public Member Functions inherited from ezApplication
static ezApplicationGetApplicationInstance ()
 Returns the one instance of ezApplication that is available.
 

Protected Member Functions

virtual ezUniquePtr< ezWindowOutputTargetBaseCreateWindowOutputTarget (ezWindowBase *pWindow) override
 
virtual void DestroyWindowOutputTarget (ezUniquePtr< ezWindowOutputTargetBase > pOutputTarget) override
 
virtual void BeforeCoreSystemsStartup () override
 This function is called before any kind of engine initialization is done. More...
 
virtual void Init_ConfigureInput () override
 
virtual void Init_ConfigureAssetManagement () override
 
virtual void Init_LoadRequiredPlugins () override
 
virtual void Init_SetupDefaultResources () override
 
virtual void Init_SetupGraphicsDevice () override
 
virtual void Deinit_ShutdownGraphicsDevice () override
 
virtual bool IsGameUpdateEnabled () const
 
virtual bool Run_ProcessApplicationInput ()
 
virtual void Run_WorldUpdateAndRender () override
 
void RenderFps ()
 
void RenderConsole ()
 
void UpdateWorldsAndExtractViews ()
 
- Protected Member Functions inherited from ezGameApplicationBase
virtual void AfterCoreSystemsStartup () override
 This function is called after basic engine initialization has been done. More...
 
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_FileSystem_ConfigureDataDirs ()
 
virtual void Init_LoadProjectPlugins ()
 
virtual void Init_PlatformProfile_LoadForRuntime ()
 
virtual void Init_ConfigureTags ()
 
virtual void Init_ConfigureCVars ()
 
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_UnloadPlugins ()
 
virtual void Deinit_ShutdownLogging ()
 
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)
 
void ExecuteFrameCapture (ezWindowHandle targetWindowHandle, const char *szContext=nullptr)
 
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...
 
virtual void Run_InputUpdate ()
 
virtual void Run_BeforeWorldUpdate ()
 
virtual void Run_AfterWorldUpdate ()
 
virtual void Run_UpdatePlugins ()
 
virtual void Run_FinishFrame ()
 

Protected Attributes

ezString m_sAppProjectPath
 Stores what is given to the constructor.
 
ezDelegateTask< void > m_UpdateTask
 
bool m_bShowConsole = false
 
ezUniquePtr< ezConsolem_pConsole
 
- Protected Attributes inherited from ezGameApplicationBase
bool m_bWasQuitRequested = false
 
ezDynamicArray< WindowContextm_Windows
 
bool m_bTakeScreenshot = false
 
ezConsoleFunction< void()> m_ConFunc_TakeScreenshot
 expose TakeScreenshot() as a console function
 
bool m_bContinuousFrameCapture = false
 
bool m_bCaptureFrame = false
 
ezConsoleFunction< void()> m_ConFunc_CaptureFrame
 expose CaptureFrame() as a console function
 
ezUniquePtr< ezGameStateBasem_pGameState
 
ezWorldm_pWorldLinkedWithGameState = nullptr
 
ezPlatformProfile m_PlatformProfile
 

Static Protected Attributes

static ezGameApplications_pGameApplicationInstance = nullptr
 
static ezDelegate< ezGALDevice *(const ezGALDeviceCreationDescription &)> s_DefaultDeviceCreator
 
- Static Protected Attributes inherited from ezGameApplicationBase
static ezGameApplicationBases_pGameApplicationBaseInstance = nullptr
 

Additional Inherited Members

- Public Attributes inherited from ezGameApplicationBase
ezEvent< const ezGameApplicationExecutionEvent & > m_ExecutionEvents
 

Detailed Description

The base class for all typical game applications made with ezEngine.

While ezApplication is an abstraction for the operating system entry point, ezGameApplication extends this to implement startup and tear down functionality of a typical game that uses the standard functionality of ezEngine.

ezGameApplication implements a lot of functionality needed by most games, such as setting up data directories, loading plugins, configuring the input system, etc.

For every such step a virtual function is called, allowing to override steps in custom applications.

The default implementation tries to do as much of this in a data-driven way. E.g. plugin and data directory configurations are read from DDL files. These can be configured by hand or using ezEditor.

You are NOT supposed to implement game functionality by deriving from ezGameApplication. Instead see ezGameState.

ezGameApplication will create exactly one ezGameState by looping over all available ezGameState types (through reflection) and picking the one whose DeterminePriority function returns the highest priority. That game state will live throughout the entire application life-time and will be stepped every frame.

Member Function Documentation

◆ BeforeCoreSystemsStartup()

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

Reimplemented in ezEngineProcessGameApplication.

◆ FindProjectDirectory()

ezString ezGameApplication::FindProjectDirectory ( ) const
overridevirtual

virtual function that is called by DoProjectSetup(). The result is passed to ezFileSystem::SetProjectDirectory

Todo:
Fix this comment

The default implementation relies on a valid path in m_sAppProjectPath. It passes that to SearchProjectDirectory() together with the path to the application binary, to search for a project somewhere relative to where the application is installed.

Override this, if your application uses a different folder structure or way to specify the project directory.

Implements ezGameApplicationBase.

◆ Init_SetupDefaultResources()

void ezGameApplication::Init_SetupDefaultResources ( )
overrideprotectedvirtual
Todo:
Loading Cubemap Texture

Reimplemented from ezGameApplicationBase.


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