Extension

Functions for creating and controlling engine native extension libraries.

Namespace: dmExtension
Include: #include <dmsdk/extension/extension_gen.hpp>
TYPES
FCallback Extra extension callback typedef
FExtensionAppInitialize Callback when the app is being initialized. Called...
FExtensionCallback Extra extension callback typedef
FExtensionFinalize Calls for the finalization of an extension
FExtensionInitialize Callback when the app is being finalized
FExtensionInitialize Callback when the app is being finalized
FExtensionOnEvent Receives an event from the engine
FExtensionUpdate Updates an extension. Called for each game frame.
ENUMS
AppExitCode engine exit code
CallbackType extra callback type
EventID event id enumeration
ExtensionAppExitCode engine exit code
ExtensionCallbackType extra callback type
ExtensionEventID event id enumeration
ExtensionResult result enumeration
Result result enumeration
STRUCTS
struct ExtensionParams The global parameters avalable when registering an...
struct Params The global parameters avalable when registering an...
FUNCTIONS
void AppParamsFinalize(ExtensionAppParams* app_params) Finalizes an extension app params struct (dealloca...
ExtensionAppExitCode AppParamsGetAppExitCode(dmExtension::AppParams* app_params) get the app exit code
void* AppParamsGetContext(ExtensionAppParams params, dmhash_t name_hash) Gets a context using a specified name hash
void* AppParamsGetContextByName(ExtensionAppParams params, const char* name) Gets a context using a specified name
void AppParamsInitialize(ExtensionAppParams* app_params) Initializes an extension app params struct NOTE: t...
int AppParamsSetContext(ExtensionAppParams params, const char* name, void* context) Sets a context using a specified name
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 ExtensionDescBufferSize() Used when registering new extensions
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(id delegate) Register application delegate
void ExtensionUnregisteriOSUIApplicationDelegate(void* delegate) Unregister an application delegate
void ParamsFinalize(ExtensionParams* app_params) Finalizes an extension params struct (deallocates...
void* ParamsGetContext(ExtensionParams params, dmhash_t name_hash) Gets a context using a specified name hash
void* ParamsGetContextByName(ExtensionParams params, const char* name) Gets a context using a specified name
void ParamsInitialize(ExtensionParams* app_params) Initializes an extension params struct NOTE: this ...
int ParamsSetContext(ExtensionAppParams params, const char* name, void* context) Sets a context using a specified name
void RegisteriOSUIApplicationDelegate(id delegate) Register application delegate
void UnregisteriOSUIApplicationDelegate(void* delegate) Unregister an application delegate
MACROS
DM_DECLARE_EXTENSION() 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

AppParamsFinalize

void AppParamsFinalize(ExtensionAppParams* app_params)

Finalizes an extension app params struct (deallocates internal memory)

PARAMETERS

ExtensionAppParams* app_params the params

AppParamsGetAppExitCode

ExtensionAppExitCode AppParamsGetAppExitCode(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

AppParamsGetContext

void* AppParamsGetContext(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

AppParamsGetContextByName

void* AppParamsGetContextByName(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

AppParamsInitialize

void AppParamsInitialize(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

AppParamsSetContext

int AppParamsSetContext(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

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

ExtensionDescBufferSize

void ExtensionDescBufferSize()

Used when registering new extensions

PARAMETERS


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(id delegate)

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

PARAMETERS

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

EXAMPLES

```objective-c // myextension_ios.mm id g_MyApplicationDelegate;

ExtensionUnregisteriOSUIApplicationDelegate

void ExtensionUnregisteriOSUIApplicationDelegate(void* delegate)

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

PARAMETERS

void* delegate an id

ParamsFinalize

void ParamsFinalize(ExtensionParams* app_params)

Finalizes an extension params struct (deallocates internal memory)

PARAMETERS

ExtensionParams* app_params the params

ParamsGetContext

void* ParamsGetContext(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

ParamsGetContextByName

void* ParamsGetContextByName(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

ParamsInitialize

void ParamsInitialize(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

ParamsSetContext

int ParamsSetContext(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

RegisteriOSUIApplicationDelegate

void RegisteriOSUIApplicationDelegate(id delegate)

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

PARAMETERS

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

EXAMPLES

```objective-c // myextension_ios.mm id g_MyApplicationDelegate;

UnregisteriOSUIApplicationDelegate

void UnregisteriOSUIApplicationDelegate(void* delegate)

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

PARAMETERS

void* delegate an id

Structs

ExtensionParams

TYPE

struct ExtensionParams

The global parameters avalable when registering and unregistering an extensioin

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.


Params

TYPE

struct Params

The global parameters avalable when registering and unregistering an extensioin

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.


Types

FCallback

Callback typedef for functions passed to RegisterCallback().


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 when the app is being finalized


FExtensionInitialize

Callback when the app is being finalized


FExtensionOnEvent

Receives an event from the engine


FExtensionUpdate

Updates an extension. Called for each game frame.


Enums

AppExitCode

Engine exit code.

EXTENSION_APP_EXIT_CODE_NONE
EXTENSION_APP_EXIT_CODE_REBOOT
EXTENSION_APP_EXIT_CODE_EXIT

CallbackType

Extra callback type for RegisterCallback function.

EXTENSION_CALLBACK_PRE_RENDER
EXTENSION_CALLBACK_POST_RENDER

EventID

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

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

Result

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.

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)