Extension

Functions for creating and controlling engine native extension libraries.

Namespace: Extension
Include: #include <dmsdk/extension/extension.h>
TYPES
FExtensionAppFinalize Callback when the app is being finalized
FExtensionAppInitialize Callback when the app is being initialized. Called...
FExtensionCallback Extra extension callback typedef
FExtensionFinalize Calls for the finalization of an extension
FExtensionInitialize Callback after all extensions have been called wit...
FExtensionOnEvent Receives an event from the engine
FExtensionUpdate Updates an extension. Called for each game frame.
CONSTANTS
ExtensionDescBufferSize Used when registering new extensions
ENUMS
ExtensionAppExitCode engine exit code
ExtensionCallbackType extra callback type
ExtensionEventID event id enumeration
ExtensionResult result enumeration
STRUCTS
struct ExtensionAppParams The extension app parameters
struct ExtensionEvent Extension event
struct ExtensionParams The global parameters avalable when registering an...
FUNCTIONS
void ExtensionAppParamsFinalize(ExtensionAppParams* app_params) Finalizes an extension app params struct (dealloca...
ExtensionAppExitCode ExtensionAppParamsGetAppExitCode(dmExtension::AppParams* app_params) get the app exit code
void* ExtensionAppParamsGetContext(ExtensionAppParams params, dmhash_t name_hash) Gets a context using a specified name hash
void* ExtensionAppParamsGetContextByName(ExtensionAppParams params, const char* name) Gets a context using a specified name
void ExtensionAppParamsInitialize(ExtensionAppParams* app_params) Initializes an extension app params struct NOTE: t...
int ExtensionAppParamsSetContext(ExtensionAppParams params, const char* name, void* context) Sets a context using a specified name
void ExtensionParamsFinalize(ExtensionParams* app_params) Finalizes an extension params struct (deallocates...
void* ExtensionParamsGetContext(ExtensionParams params, dmhash_t name_hash) Gets a context using a specified name hash
void* ExtensionParamsGetContextByName(ExtensionParams params, const char* name) Gets a context using a specified name
void ExtensionParamsInitialize(ExtensionParams* app_params) Initializes an extension params struct NOTE: this ...
int ExtensionParamsSetContext(ExtensionAppParams params, const char* name, void* context) Sets a context using a specified name
void ExtensionRegister(void* desc, const char* desc_size, const char* name, FExtensionAppInitialize app_initialize, FExtensionAppFinalize app_finalize, FExtensionInitialize initialize, FExtensionFinalize finalize, FExtensionUpdate update, FExtensionOnEvent on_event) Extension declaration helper. Internal function. U...
void ExtensionRegisteriOSUIApplicationDelegate(void* delegate) Register application delegate
void ExtensionUnregisteriOSUIApplicationDelegate(void* delegate) Unregister an application delegate
MACROS
DM_DECLARE_EXTENSION(symbol, name, app_init, app_final, init, update, on_event, final) declare a new extension
DM_PLATFORM_ANDROID() Set if the platform is Android
DM_PLATFORM_HTML5() Set if the platform is Html5
DM_PLATFORM_IOS() Set if the platform is iPhoneOS
DM_PLATFORM_LINUX() Set if the platform is Linux
DM_PLATFORM_OSX() Set if the platform is OSX
DM_PLATFORM_WINDOWS() Set if the platform is Windows (on both x86 and x86_64)

Functions

ExtensionAppParamsFinalize

void ExtensionAppParamsFinalize(ExtensionAppParams* app_params)

Finalizes an extension app params struct (deallocates internal memory)

PARAMETERS

ExtensionAppParams* app_params the params

ExtensionAppParamsGetAppExitCode

ExtensionAppExitCode ExtensionAppParamsGetAppExitCode(dmExtension::AppParams* app_params)

get the app exit code

PARAMETERS

dmExtension::AppParams* app_params The app params sent to the extension dmExtension::AppInitialize / dmExtension::AppInitialize

RETURNS

ExtensionAppExitCode engine exit code

ExtensionAppParamsGetContext

void* ExtensionAppParamsGetContext(ExtensionAppParams params, dmhash_t name_hash)

Gets a context using a specified name hash

PARAMETERS

ExtensionAppParams params the params
dmhash_t name_hash the context name hash

RETURNS

void* The context, if it exists

ExtensionAppParamsGetContextByName

void* ExtensionAppParamsGetContextByName(ExtensionAppParams params, const char* name)

Gets a context using a specified name

PARAMETERS

ExtensionAppParams params the params
const char* name the context name

RETURNS

void* The context, if it exists

ExtensionAppParamsInitialize

void ExtensionAppParamsInitialize(ExtensionAppParams* app_params)

Initializes an extension app params struct NOTE: this is an opaque struct, do not use it's members directly!

PARAMETERS

ExtensionAppParams* app_params the params

ExtensionAppParamsSetContext

int ExtensionAppParamsSetContext(ExtensionAppParams params, const char* name, void* context)

Sets a context using a specified name

PARAMETERS

ExtensionAppParams params the params
const char* name the context name
void* context the context

RETURNS

int 0 if successful

ExtensionParamsFinalize

void ExtensionParamsFinalize(ExtensionParams* app_params)

Finalizes an extension params struct (deallocates internal memory)

PARAMETERS

ExtensionParams* app_params the params

ExtensionParamsGetContext

void* ExtensionParamsGetContext(ExtensionParams params, dmhash_t name_hash)

Gets a context using a specified name hash

PARAMETERS

ExtensionParams params the params
dmhash_t name_hash the context name hash

RETURNS

void* The context, if it exists

ExtensionParamsGetContextByName

void* ExtensionParamsGetContextByName(ExtensionParams params, const char* name)

Gets a context using a specified name

PARAMETERS

ExtensionParams params the params
const char* name the context name

RETURNS

void* The context, if it exists

ExtensionParamsInitialize

void ExtensionParamsInitialize(ExtensionParams* app_params)

Initializes an extension params struct NOTE: this is an opaque struct, do not use it's members directly!

PARAMETERS

ExtensionParams* app_params the params

ExtensionParamsSetContext

int ExtensionParamsSetContext(ExtensionAppParams params, const char* name, void* context)

Sets a context using a specified name

PARAMETERS

ExtensionAppParams params the params
const char* name the context name
void* context the context

RETURNS

int 0 if successful

ExtensionRegister

void ExtensionRegister(void* desc, const char* desc_size, const char* name, FExtensionAppInitialize app_initialize, FExtensionAppFinalize app_finalize, FExtensionInitialize initialize, FExtensionFinalize finalize, FExtensionUpdate update, FExtensionOnEvent on_event)

Extension declaration helper. Internal function. Use DM_DECLARE_EXTENSION

PARAMETERS

void* desc A persistent buffer of at least 128 bytes.
const char* desc_size size of buffer holding desc. in bytes
const char* name extension name. human readble. max 16 characters long.
FExtensionAppInitialize app_initialize app-init function. May be null
FExtensionAppFinalize app_finalize app-final function. May be null
FExtensionInitialize initialize init function. May not be 0
FExtensionFinalize finalize finalize function. May not be 0
FExtensionUpdate update update function. May be null
FExtensionOnEvent on_event event callback function. May be null

ExtensionRegisteriOSUIApplicationDelegate

void ExtensionRegisteriOSUIApplicationDelegate(void* delegate)

Register an iOS application delegate to the engine. Multiple delegates are supported (Max 32)

PARAMETERS

void* delegate An id, see: https://developer.apple.com/documentation/uikit/uiapplicationdelegate?language=objc

EXAMPLES

// myextension_ios.mm

id<UIApplicationDelegate> g_MyApplicationDelegate;

\@interface MyApplicationDelegate : NSObject <UIApplicationDelegate>

- (void) applicationDidBecomeActive:(UIApplication *) application;

\@end

\@implementation MyApplicationDelegate

- (void) applicationDidBecomeActive:(UIApplication *) application {
    dmLogWarning("applicationDidBecomeActive - MyAppDelegate");
}

\@end

struct MyAppDelegateRegister
{
    MyApplicationDelegate* m_Delegate;
    MyAppDelegateRegister() {
        m_Delegate = [[FacebookAppDelegate alloc] init];
        Extension::RegisteriOSUIApplicationDelegate(m_Delegate);
    }
    ~MyAppDelegateRegister() {
        Extension::UnregisteriOSUIApplicationDelegate(m_Delegate);
        [m_Delegate release];
    }
};

MyAppDelegateRegister g_FacebookDelegateRegister;

ExtensionUnregisteriOSUIApplicationDelegate

void ExtensionUnregisteriOSUIApplicationDelegate(void* delegate)

Deregister a previously registered iOS application delegate This function is only available on iOS.

PARAMETERS

void* delegate an id

Structs

ExtensionAppParams

TYPE

struct ExtensionAppParams

The extension app parameters

MEMBERS

HConfigFile m_ConfigFile Deprecated
ExtensionAppExitCode m_ExitStatus App exit code

ExtensionEvent

TYPE

struct ExtensionEvent

Extension event

ExtensionParams

TYPE

struct ExtensionParams

The global parameters avalable when registering and unregistering an extension

MEMBERS

HConfigFile m_ConfigFile The game project settings (including overrides and plugins)
HResourceFactory m_ResourceFactory The game resource factory / repository
lua_State* m_L The Lua state.

Constants

ExtensionDescBufferSize

Used when registering new extensions

Types

FExtensionAppFinalize

Callback when the app is being finalized

FExtensionAppInitialize

Callback when the app is being initialized. Called before FExtensionInitialize

FExtensionCallback

Callback typedef for functions passed to RegisterCallback().

FExtensionFinalize

Calls for the finalization of an extension

FExtensionInitialize

Callback after all extensions have been called with FExtensionAppInitialize

FExtensionOnEvent

Receives an event from the engine

FExtensionUpdate

Updates an extension. Called for each game frame.

Enums

ExtensionAppExitCode

Engine exit code.

EXTENSION_APP_EXIT_CODE_NONE
EXTENSION_APP_EXIT_CODE_REBOOT
EXTENSION_APP_EXIT_CODE_EXIT

ExtensionCallbackType

Extra callback type for RegisterCallback function.

EXTENSION_CALLBACK_PRE_RENDER
EXTENSION_CALLBACK_POST_RENDER

ExtensionEventID

Event id enumeration. EVENT_ID_ICONIFYAPP and EVENT_ID_DEICONIFYAPP only available on

EXTENSION_EVENT_ID_ACTIVATEAPP
EXTENSION_EVENT_ID_DEACTIVATEAPP
EXTENSION_EVENT_ID_ICONIFYAPP
EXTENSION_EVENT_ID_DEICONIFYAPP
EXTENSION_EVENT_ID_ENGINE_INITIALIZED
EXTENSION_EVENT_ID_ENGINE_DELETE

ExtensionResult

Result enumeration.

EXTENSION_RESULT_OK
EXTENSION_RESULT_INIT_ERROR

Macros

DM_DECLARE_EXTENSION

Declare and register new extension to the engine. This macro is used to declare the extension callback functions used by the engine to communicate with the extension.

symbol external extension symbol description (no quotes).
name extension name. Human readable.
app_init app-init function. May be null.
app_params
ExtensionAppParams* Pointer to an AppParams structure.
app_final app-final function. May be null.
app_params
ExtensionAppParams* Pointer to an AppParams structure.
init init function. May not be null.
params
ExtensionParams* Pointer to a Params structure
update update function. May be null.
params
ExtensionParams* Pointer to a Params structure
on_event event callback function. May be null.
params
ExtensionParams* Pointer to a Params structure
event
ExtensionEvent* const Pointer to an Event structure
final function. May not be null.
params
ExtensionParams* Pointer to an Params structure.

EXAMPLES

Register a new extension: 
DM_DECLARE_EXTENSION(MyExt, "MyExt", AppInitializeMyExt, AppFinalizeMyExt, InitializeMyExt, UpdateMyExt, OnEventMyExt, FinalizeMyExt);

DM_PLATFORM_ANDROID

Set if the platform is Android

DM_PLATFORM_HTML5

Set if the platform is Html5

DM_PLATFORM_IOS

Set if the platform is iPhoneOS

DM_PLATFORM_LINUX

Set if the platform is Linux

DM_PLATFORM_OSX

Set if the platform is OSX

DM_PLATFORM_WINDOWS

Set if the platform is Windows (on both x86 and x86_64)