API reference (Extension)

Defold c++

Defold lua

Extension

Version

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
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 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 AppParams	The extension app parameters
struct Event	Extension event
struct ExtensionAppParams	The extension app parameters
struct ExtensionEvent	Extension event
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(void* 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(void* 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

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

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

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)

PARAMETERS

void* delegate An id, 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(void* delegate)

PARAMETERS

void* delegate An id, 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

AppParams

TYPE

struct AppParams

The extension app parameters

MEMBERS

`HConfigFile`	`m_ConfigFile`	Deprecated
`ExtensionAppExitCode`	`m_ExitStatus`	App exit code

Event

TYPE

struct Event

Extension event

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.

Params

TYPE

struct Params

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.

ExtensionResult EXTENSION_RESULT_OK if all went ok

FExtensionOnEvent

void FExtensionOnEvent(ExtensionParams params, ExtensionEvent event)

Receives an event from the engine

PARAMETERS

`ExtensionParams`	`params`
`ExtensionEvent`	`event`	The current event

FExtensionUpdate

ExtensionResult FExtensionUpdate(ExtensionParams params)

Updates an extension. Called for each game frame.

PARAMETERS

ExtensionParams params

RETURNS

ExtensionResult EXTENSION_RESULT_OK if all went ok

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

DM_DECLARE_EXTENSION(MyExt, "MyExt", AppInitializeMyExt, AppFinalizeMyExt, InitializeMyExt, UpdateMyExt, OnEventMyExt, FinalizeMyExt);