The engine control class. More...

#include "murl_platform_engine_control.h"

Public Member Functions
	EngineControl ()
	The default constructor.

virtual	~EngineControl ()
	The destructor.

Bool	Init (IPlatform *platform)
	Initialize the engine control. More...

Bool	DeInit ()
	Deinitialize the engine control. More...

Bool	CreateEngine (IApp application, IFileInterface fileInterface)
	Create the engine instance. More...

Bool	DestroyEngine ()
	Destroy the engine instance. More...

Bool	InitEngine () const
	Initialize the engine instance. More...

Bool	DeInitEngine () const
	De-Initialize the engine instance. More...

Bool	StartEngine ()
	Start the engine. More...

Bool	IsStarted () const
	Check if the engine is started. More...

Bool	StopEngine ()
	Stop the engine. More...

Bool	PauseEngine ()
	Pause the engine. More...

Bool	IsPaused () const
	Check if the engine is paused. More...

Bool	ContinueEngine ()
	Continue the engine. More...

Bool	SaveEngineData () const
	Save the engine's data. More...

Bool	SuspendEngine ()
	Suspend the engine. More...

Bool	IsSuspended () const
	Check if the engine is suspended. More...

Bool	ResumeEngine ()
	Resume the engine. More...

Bool	Activate ()
	Activate the engine. More...

Bool	DeActivate ()
	Deactivate the engine. More...

Bool	BeginFrame () const
	Begin rendering a frame. More...

Bool	EndFrame () const
	End rendering a frame. More...

Bool	Invoke (const IMethodCall *call, Bool waitForMore) const
	Invoke a method in the render thread context. More...

virtual Bool	AppFinishLaunching (void *launchOptions)
	Execute AppFinishLaunching() method for all custom ICustomControlable objects. More...

Bool	AppOpenURL (String url, String sourceApplication, void *annotation) const
	Execute AppOpenURL() method for all custom ICustomControlable objects. More...

Bool	AppOpenURL (String url, void *options) const
	Execute AppOpenURL() method for all custom ICustomControlable objects. More...

void	AppReceiveNotification (void *notification) const
	Execute AppReceiveNotification() method for all custom ICustomControlable objects. More...

void	AppRegisterForRemoteNotification (const ConstData &deviceToken, void *error) const
	Execute AppRegisterForRemoteNotification() method for all custom ICustomControlable objects. More...

void	AppRegisterUserNotificationSettings (void *notificationSettings) const
	Execute AppRegisterUserNotificationSettings() method for all custom ICustomControlable objects. More...

void	AppHandleActionWithIdentifier (const String &identifier, void notification, void userInfo) const
	Execute AppHandleActionWithIdentifier() method for all custom ICustomControlable objects. More...

ICustomControlable::FetchResult	AppReceiveRemoteNotification (void *userInfo) const
	Execute AppReceiveRemoteNotification() method for all custom ICustomControlable objects. More...

ICustomControlable::FetchResult	AppPerformBackgroundFetch () const
	Execute AppPerformBackgroundFetch() method for all custom ICustomControlable objects. More...

void	AppHandleEventsForBackgroundURLSession (const String &identifier) const
	Execute AppHandleEventsForBackgroundURLSession() method for all custom ICustomControlable objects. More...

void	AppWillTerminate () const
	Execute AppWillTerminate() method for all custom ICustomControlable objects. More...

void	FrameUpdate () const
	Execute FrameUpdate() method for all custom ICustomControlable objects. More...

IPlatformConfiguration *	GetPlatformConfiguration () const
	Get the platform configuration object. More...

IEngineConfiguration *	GetEngineConfiguration () const
	Get the engine configuration object. More...

IAppConfiguration *	GetAppConfiguration () const
	Get the application configuration object. More...

IDeviceHandler *	GetDeviceHandler () const
	Get the device handler object. More...

Detailed Description

The engine control class.

The engine control class implements methods for creating an instance of the engine, attaching an application and controlling the engine.

A typical sequence for creating an engine instance is:

Call Init().
Setup configuration items.
Create an application.
Call CreateEngine().
Create and attach devices, video, audio and file interface.
Call InitEngine().
Call StartEngine().
Call ContinueEngine() to update custom controls.

After successfully initialization the engine can be controlled by:

The rendering context provided by the video interface is controlled by:

Call BeginFrame().
Swap the rendering buffers.
Call EndFrame().

To update custom ICustomControlable objects:

Call ApplOpenURL() if the application is started with an URL.
Call ApplWillTerminate() if the application will be terminated.
Call FrameUpdate() each frame.

A typical sequence for destroying an engine instance is:

Call StopEngine().
Call DeInitEngine().
Call DestroyEngine().
Destroy the application.
Destroy the devices, video, audio and file interface.
Call DeInit().

Member Function Documentation

◆ Init()

Bool Murl::Platform::EngineControl::Init ( IPlatform * platform )

Initialize the engine control.

Creates the platform, engine and application configuration and the device handler.

Parameters

platform The platform.

Returns: true if successful.

◆ DeInit()

Bool Murl::Platform::EngineControl::DeInit ( )

Deinitialize the engine control.

Destroys the platform, engine and application configuration and the device handler.

Returns: true if successful.

◆ CreateEngine()

Bool Murl::Platform::EngineControl::CreateEngine	(	IApp *	application,
		IFileInterface *	fileInterface
	)

Create the engine instance.

Creates the engine and calls IApp::Configure().

Parameters

application	The application to configure.
fileInterface	The file interface for application setup.

Returns: true if successful.

◆ DestroyEngine()

Bool Murl::Platform::EngineControl::DestroyEngine ( )

Destroy the engine instance.

Calls IEngine::DeInit() and destroys the engine instance.

Returns: true if successful.

◆ InitEngine()

Bool Murl::Platform::EngineControl::InitEngine ( ) const

Initialize the engine instance.

Calls IEngine::Init().

Returns: true if successful.

◆ DeInitEngine()

Bool Murl::Platform::EngineControl::DeInitEngine ( ) const

De-Initialize the engine instance.

Calls IEngine::DeInit().

Returns: true if successful.

◆ StartEngine()

Bool Murl::Platform::EngineControl::StartEngine ( )

Start the engine.

Calls IEngine::Start().

Returns: true if successful.

◆ IsStarted()

Bool Murl::Platform::EngineControl::IsStarted ( ) const

Check if the engine is started.

Returns: true if the engine is started.

◆ StopEngine()

Bool Murl::Platform::EngineControl::StopEngine ( )

Stop the engine.

Calls IEngine::Stop().

Returns: true if successful.

◆ PauseEngine()

Bool Murl::Platform::EngineControl::PauseEngine ( )

Pause the engine.

Has to be called if the application will resign active. Calls IEngine::Pause().

Returns: true if successful.

◆ IsPaused()

Bool Murl::Platform::EngineControl::IsPaused ( ) const

Check if the engine is paused.

Returns: true if the engine is paused.

◆ ContinueEngine()

Bool Murl::Platform::EngineControl::ContinueEngine ( )

Continue the engine.

Has to be called if the application did become active. Calls IEngine::Continue().

Returns: true if successful.

◆ SaveEngineData()

Bool Murl::Platform::EngineControl::SaveEngineData ( ) const

Save the engine's data.

Has to be called if the application did enter background. Unlike SuspendEngine it is guaranteed to be finished. Calls IEngine::SaveData().

Returns: true if successful.

◆ SuspendEngine()

Bool Murl::Platform::EngineControl::SuspendEngine ( )

Suspend the engine.

Has to be called if the application did enter background. Calls IEngine::Suspend().

Returns: true if successful.

◆ IsSuspended()

Bool Murl::Platform::EngineControl::IsSuspended ( ) const

Check if the engine is suspended.

Returns: true if the engine is suspended.

◆ ResumeEngine()

Bool Murl::Platform::EngineControl::ResumeEngine ( )

Resume the engine.

Has to be called if the application did enter fourceground. Calls IEngine::Resume().

Returns: true if successful.

◆ Activate()

Bool Murl::Platform::EngineControl::Activate ( )

Activate the engine.

Calls ContinueEngine() or ResumeEngine() if the engine is paused or suspended.

Returns: true if successful.

◆ DeActivate()

Bool Murl::Platform::EngineControl::DeActivate ( )

Deactivate the engine.

Performes depending on IEngineConfiguration::GetDeactivatedAppRunState():

Calls PauseEngine() if IEnums::APP_RUN_STATE_PAUSED.
Calls SuspendEngine() if IEnums::APP_RUN_STATE_SUSPENDED.
otherwise no action is performed.
Returns
true if successful.

◆ BeginFrame()

Bool Murl::Platform::EngineControl::BeginFrame ( ) const

Begin rendering a frame.

Calls IEngine::BeginFrame().

Returns: true if successful.

◆ EndFrame()

Bool Murl::Platform::EngineControl::EndFrame ( ) const

End rendering a frame.

Calls IEngine::EndFrame().

Returns: true if successful.

◆ Invoke()

Bool Murl::Platform::EngineControl::Invoke	(	const IMethodCall *	call,
		Bool	waitForMore
	)		const

Invoke a method in the render thread context.

The render thread context is the context of the EndFrame() caller. The invoke call is waiting until the method was processed. This method is intend for internal use only.

Parameters

call	The method call object.
waitForMore	If true, the engine continues processing the message loop for a given maximum amount of time, in order to e.g. speed up initialization of multiple render objects in a sequence. The maximum time can be set via IEngineConfiguration::SetSyncLoadingTimeout().

Returns: true if successful.

◆ AppFinishLaunching()

virtual Bool Murl::Platform::EngineControl::AppFinishLaunching ( void * launchOptions )

virtual

Execute AppFinishLaunching() method for all custom ICustomControlable objects.

Has to be called if the application did finish launching.

Parameters

launchOptions The launch options dictionary (NSDictionary*).

Returns: true if any control returns true.

◆ AppOpenURL() [1/2]

Bool Murl::Platform::EngineControl::AppOpenURL	(	String	url,
		String	sourceApplication,
		void *	annotation
	)		const

Execute AppOpenURL() method for all custom ICustomControlable objects.

Has to be called if the application is opened by an url.

Parameters

url	The url string.
sourceApplication	The source application string.
annotation	A property-list object supplied by the source application.

Returns: true if any control returns true.

◆ AppOpenURL() [2/2]

Bool Murl::Platform::EngineControl::AppOpenURL	(	String	url,
		void *	options
	)		const

Execute AppOpenURL() method for all custom ICustomControlable objects.

Has to be called if the application is opened by an url with options.

Parameters

url	The url string.
options	A dictionary of launch options.

Returns: true if any control returns true.

◆ AppReceiveNotification()

void Murl::Platform::EngineControl::AppReceiveNotification ( void * notification ) const

Execute AppReceiveNotification() method for all custom ICustomControlable objects.

Parameters

notification Encapsulates details about the notification (UILocalNotification*).

◆ AppRegisterForRemoteNotification()

void Murl::Platform::EngineControl::AppRegisterForRemoteNotification	(	const ConstData &	deviceToken,
		void *	error
	)		const

Execute AppRegisterForRemoteNotification() method for all custom ICustomControlable objects.

Parameters

deviceToken	The device token.
error	An optional error (NSError*) or null.

◆ AppRegisterUserNotificationSettings()

void Murl::Platform::EngineControl::AppRegisterUserNotificationSettings ( void * notificationSettings ) const

Execute AppRegisterUserNotificationSettings() method for all custom ICustomControlable objects.

Parameters

notificationSettings The user notification settings (UIUserNotificationSettings*).

◆ AppHandleActionWithIdentifier()

void Murl::Platform::EngineControl::AppHandleActionWithIdentifier	(	const String &	identifier,
		void *	notification,
		void *	userInfo
	)		const

Execute AppHandleActionWithIdentifier() method for all custom ICustomControlable objects.

Parameters

identifier	The identifier string associated with the action.
notification	The local notification object that was triggered (UILocalNotification*).
userInfo	Dictionary containing information related to the remote notification (NSDictionary*).

◆ AppReceiveRemoteNotification()

ICustomControlable::FetchResult Murl::Platform::EngineControl::AppReceiveRemoteNotification ( void * userInfo ) const

Execute AppReceiveRemoteNotification() method for all custom ICustomControlable objects.

Parameters

userInfo Encapsulates details about the notification (NSDictionary*).

Returns: The result of any control that does not return ICustomControlable::FETCHRESULT_NONE.

◆ AppPerformBackgroundFetch()

ICustomControlable::FetchResult Murl::Platform::EngineControl::AppPerformBackgroundFetch ( ) const

Execute AppPerformBackgroundFetch() method for all custom ICustomControlable objects.

Returns: The result of any control that does not return ICustomControlable::FETCHRESULT_NONE.

◆ AppHandleEventsForBackgroundURLSession()

void Murl::Platform::EngineControl::AppHandleEventsForBackgroundURLSession ( const String & identifier ) const

Execute AppHandleEventsForBackgroundURLSession() method for all custom ICustomControlable objects.

Parameters

identifier The identifier of the URL session requiring attention.

◆ AppWillTerminate()

void Murl::Platform::EngineControl::AppWillTerminate ( ) const

Execute AppWillTerminate() method for all custom ICustomControlable objects.

Has to be called if the application will terminate.

◆ FrameUpdate()

void Murl::Platform::EngineControl::FrameUpdate ( ) const

Execute FrameUpdate() method for all custom ICustomControlable objects.

Has to be executed in the platform thread context each frame tick.

◆ GetPlatformConfiguration()

IPlatformConfiguration* Murl::Platform::EngineControl::GetPlatformConfiguration ( ) const

Get the platform configuration object.

The platform configuration object is available after calling Init().

Returns: The platform configuration object or null if not available.

◆ GetEngineConfiguration()

IEngineConfiguration* Murl::Platform::EngineControl::GetEngineConfiguration ( ) const

Get the engine configuration object.

The engine configuration object is available after calling Init().

Returns: The engine configuration object or null if not available.

◆ GetAppConfiguration()

IAppConfiguration* Murl::Platform::EngineControl::GetAppConfiguration ( ) const

Get the application configuration object.

The application configuration object is available after calling Init().

Returns: The application configuration object or null if not available.

◆ GetDeviceHandler()

IDeviceHandler* Murl::Platform::EngineControl::GetDeviceHandler ( ) const

Get the device handler object.

The device handler object is available after calling Init().

Returns: The device handler object or null if not available.

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

murl_platform_engine_control.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ Init()

◆ DeInit()

◆ CreateEngine()

◆ DestroyEngine()

◆ InitEngine()

◆ DeInitEngine()

◆ StartEngine()

◆ IsStarted()

◆ StopEngine()

◆ PauseEngine()

◆ IsPaused()

◆ ContinueEngine()

◆ SaveEngineData()

◆ SuspendEngine()

◆ IsSuspended()

◆ ResumeEngine()

◆ Activate()

◆ DeActivate()

◆ BeginFrame()

◆ EndFrame()

◆ Invoke()

◆ AppFinishLaunching()

◆ AppOpenURL() [1/2]

◆ AppOpenURL() [2/2]

◆ AppReceiveNotification()

◆ AppRegisterForRemoteNotification()

◆ AppRegisterUserNotificationSettings()

◆ AppHandleActionWithIdentifier()

◆ AppReceiveRemoteNotification()

◆ AppPerformBackgroundFetch()

◆ AppHandleEventsForBackgroundURLSession()

◆ AppWillTerminate()

◆ FrameUpdate()

◆ GetPlatformConfiguration()

◆ GetEngineConfiguration()

◆ GetAppConfiguration()

◆ GetDeviceHandler()