API reference (dmScript)

Sdk script api documentation

Built-in scripting functions.


Namespace:	`dmScript`
Include:	`#include <dmsdk/script/script.h>`

STRUCTS
struct dmScript::LuaHBuffer	Lua wrapper for a dmBuffer::HBuffer
struct dmScript::LuaCallbackInfo	callback info struct

FUNCTIONS
int dmScript::Ref(lua_State* L, int table)	wrapper for luaL_ref.
void dmScript::Unref(lua_State* L, int table, int reference)	wrapper for luaL_unref.
void dmScript::GetInstance(lua_State* L)	Retrieve current script instance from the global t...
void dmScript::SetInstance(lua_State* L)	Sets the current script instance Set the value on ...
bool dmScript::IsInstanceValid(lua_State* L)	Check if the script instance in the lua state is v...
lua_State* dmScript::GetMainThread(lua_State* L)	Retrieve the main thread lua state from any lua st...
boolean dmScript::IsBuffer(lua_State* L, int index)	check if the value is a dmScript::LuaHBuffer
void dmScript::PushBuffer(lua_State* L, dmScript::LuaHBuffer buffer)	push a LuaHBuffer onto the supplied lua state
LuaHBuffer* dmScript::CheckBuffer(lua_State* L, int index)	retrieve a HBuffer from the supplied lua state
Vectormath::Aos::Vector3* dmScript::ToVector3(lua_State* L, int index)	get the value at index as a Vectormath::Aos::Vector3*
dmScript::IsVector3( L, index)	Check if the value at #index is a Vectormath::Aos:...
void dmScript::PushVector3(lua_State* L, Vectormath::Aos::Vector3 v)	push a Vectormath::Aos::Vector3 onto the Lua stack
Vectormath::Aos::Vector3* dmScript::CheckVector3(lua_State* L, int index)	check if the value is a Vectormath::Aos::Vector3
Vectormath::Aos::Vector4* dmScript::ToVector4(lua_State* L, int index)	get the value at index as a Vectormath::Aos::Vector4*
dmScript::IsVector4( L, index)	Check if the value at #index is a Vectormath::Aos:...
void dmScript::PushVector4(lua_State* L, Vectormath::Aos::Vector4 v)	push a Vectormath::Aos::Vector4 on the stack
Vectormath::Aos::Vector4* dmScript::CheckVector4(lua_State* L, int index)	check if the value is a Vectormath::Aos::Vector3
Vectormath::Aos::Quat* dmScript::ToQuat(lua_State* L, int index)	get the value at index as a Vectormath::Aos::Quat*
void dmScript::PushQuat(lua_State* L, Vectormath::Aos::Quat quat)	push a Vectormath::Aos::Quat onto the Lua stack
Vectormath::Aos::Quat* dmScript::CheckQuat(lua_State* L, int index)	check if the value is a Vectormath::Aos::Vector3
Vectormath::Aos::Matrix4* dmScript::ToMatrix4(lua_State* L, int index)	get the value at index as a Vectormath::Aos::Matrix4*
void dmScript::PushMatrix4(lua_State* L, Vectormath::Aos::Matrix4 matrix)	push a Vectormath::Aos::Matrix4 onto the Lua stack
Vectormath::Aos::Matrix4* dmScript::CheckMatrix4(lua_State* L, int index)	check if the value is a Vectormath::Aos::Matrix4
int dmJson::Type(lua_State* L, dmJson::Document doc, int index, char* error_str_out, size_t error_str_size)	convert a dmJson::Document to a Lua table
dmScript::CreateCallback( L, index)	Register a Lua callback.
void dmScript::IsCallbackValid( cbk)	Check if Lua callback is valid.
void dmScript::DestroyCallback( cbk)	Deletes the Lua callback
dmScript::GetCallbackLuaContext( cbk)	Gets the Lua context from a callback struct
dmScript::SetupCallback( cbk)	Setups up the Lua callback prior to a call to dmScript::PCall()
void dmScript::TeardownCallback( cbk)	Cleans up the stack after SetupCallback+PCall calls
dmScript::PCall( L, nargs, nresult)	This function wraps lua_pcall with the addition of...

MACROS
DM_LUA_STACK_CHECK(L, diff)	helper macro to validate the Lua stack state before leaving a function.
DM_LUA_ERROR(fmt, args)	helper macro to validate the Lua stack state and throw a lua error.

Functions

dmScript::Unref

void dmScript::Unref(lua_State* L, int table, int reference)

Releases reference ref from the table at index t (see luaL_ref). The entry is removed from the table, so that the referred object can be collected. It also decreases the number of global references kept

PARAMETERS

`lua_State*`	`L`	lua state
`int`	`table`	table the lua table that stores the references. E.g LUA_REGISTRYINDEX
`int`	`reference`	the reference to the object

dmScript::GetInstance

void dmScript::GetInstance(lua_State* L)

Retrieve current script instance from the global table and place it on the top of the stack, only valid when set. (see dmScript::GetMainThread)

PARAMETERS

lua_State* L lua state

dmScript::SetInstance

void dmScript::SetInstance(lua_State* L)

Sets the current script instance Set the value on the top of the stack as the instance into the global table and pops it from the stack. (see dmScript::GetMainThread)

PARAMETERS

lua_State* L lua state

dmScript::IsInstanceValid

bool dmScript::IsInstanceValid(lua_State* L)

Check if the script instance in the lua state is valid. The instance is assumed to have been previously set by dmScript::SetInstance.

PARAMETERS

lua_State* L lua state

RETURNS

bool Returns true if the instance is valid

dmScript::GetMainThread

lua_State* dmScript::GetMainThread(lua_State* L)

Retrieve the main thread lua state from any lua state (main thread or coroutine).

PARAMETERS

lua_State* L lua state

RETURNS

lua_State* the main thread lua state

EXAMPLES

How to create a Lua callback

dmScript::LuaCallbackInfo* g_MyCallbackInfo = 0;

static void InvokeCallback(dmScript::LuaCallbackInfo* cbk)
{
    if (!dmScript::IsCallbackValid(cbk))
        return;

    lua_State* L = dmScript::GetCallbackLuaContext(cbk);
    DM_LUA_STACK_CHECK(L, 0)

    if (!dmScript::SetupCallback(cbk))
    {
        dmLogError("Failed to setup callback");
        return;
    }

    lua_pushstring(L, "Hello from extension!");
    lua_pushnumber(L, 76);

    dmScript::PCall(L, 3, 0); // instance + 2

    dmScript::TeardownCallback(cbk);
}

static int Start(lua_State* L)
{
    DM_LUA_STACK_CHECK(L, 0);

    g_MyCallbackInfo = dmScript::CreateCallback(L, 1);

    return 0;
}

static int Update(lua_State* L)
{
    DM_LUA_STACK_CHECK(L, 0);

    static int count = 0;
    if( count++ == 5 )
    {
        InvokeCallback(g_MyCallbackInfo);
        if (g_MyCallbackInfo)
            dmScript::DestroyCallback(g_MyCallbackInfo);
        g_MyCallbackInfo = 0;
    }
    return 0;
}

dmScript::IsBuffer

boolean dmScript::IsBuffer(lua_State* L, int index)

Check if the value is a dmScript::LuaHBuffer

PARAMETERS

`lua_State*`	`L`	lua state
`int`	`index`	Index of the value

RETURNS

boolean True if value at index is a LuaHBuffer

dmScript::PushBuffer

void dmScript::PushBuffer(lua_State* L, dmScript::LuaHBuffer buffer)

Will increase the stack by 1.

PARAMETERS

`lua_State*`	`L`	lua state
`dmScript::LuaHBuffer`	`buffer`	buffer to push

EXAMPLES

How to push a buffer and give Lua ownership of the buffer (GC)

dmScript::LuaHBuffer luabuf = { buffer, dmScript::OWNER_LUA };
PushBuffer(L, luabuf);

How to push a buffer and keep ownership in C++

dmScript::LuaHBuffer luabuf = { buffer, dmScript::OWNER_C };
PushBuffer(L, luabuf);

dmScript::CheckBuffer

LuaHBuffer* dmScript::CheckBuffer(lua_State* L, int index)

Check if the value in the supplied index on the lua stack is a HBuffer and returns it.

PARAMETERS

`lua_State*`	`L`	lua state
`int`	`index`	Index of the value

RETURNS

LuaHBuffer* pointer to dmScript::LuaHBuffer

dmScript::ToVector3

Vectormath::Aos::Vector3* dmScript::ToVector3(lua_State* L, int index)

Get the value at index as a Vectormath::Aos::Vector3*

PARAMETERS

`lua_State*`	`L`	Lua state
`int`	`index`	Index of the value

RETURNS

Vectormath::Aos::Vector3* The pointer to the value, or 0 if not correct type

dmScript::IsVector3

dmScript::IsVector3( L, index)

Check if the value at #index is a Vectormath::Aos::Vector3*

PARAMETERS

	`L`	Lua state
	`index`	Index of the value

RETURNS

if value at #index is a Vectormath::Aos::Vector3*

dmScript::PushVector3

void dmScript::PushVector3(lua_State* L, Vectormath::Aos::Vector3 v)

Push a Vectormath::Aos::Vector3 value onto the supplied lua state, will increase the stack by 1.

PARAMETERS

`lua_State*`	`L`	Lua state
`Vectormath::Aos::Vector3`	`v`	Vector3 value to push

dmScript::CheckVector3

Vectormath::Aos::Vector3* dmScript::CheckVector3(lua_State* L, int index)

Check if the value in the supplied index on the lua stack is a Vectormath::Aos::Vector3.

PARAMETERS

`lua_State*`	`L`	Lua state
`int`	`index`	Index of the value

RETURNS

Vectormath::Aos::Vector3* The pointer to the value

dmScript::ToVector4

Vectormath::Aos::Vector4* dmScript::ToVector4(lua_State* L, int index)

Get the value at index as a Vectormath::Aos::Vector4*

PARAMETERS

`lua_State*`	`L`	Lua state
`int`	`index`	Index of the value

RETURNS

Vectormath::Aos::Vector4* The pointer to the value, or 0 if not correct type

dmScript::IsVector4

dmScript::IsVector4( L, index)

Check if the value at #index is a Vectormath::Aos::Vector4*

PARAMETERS

	`L`	Lua state
	`index`	Index of the value

RETURNS

if value at #index is a Vectormath::Aos::Vector4*

dmScript::PushVector4

void dmScript::PushVector4(lua_State* L, Vectormath::Aos::Vector4 v)

Push a Vectormath::Aos::Vector4 value onto the supplied lua state, will increase the stack by 1.

PARAMETERS

`lua_State*`	`L`	Lua state
`Vectormath::Aos::Vector4`	`v`	Vectormath::Aos::Vector4 value to push

dmScript::CheckVector4

Vectormath::Aos::Vector4* dmScript::CheckVector4(lua_State* L, int index)

Check if the value in the supplied index on the lua stack is a Vectormath::Aos::Vector3.

PARAMETERS

`lua_State*`	`L`	Lua state
`int`	`index`	Index of the value

RETURNS

Vectormath::Aos::Vector4* The pointer to the value

dmScript::ToQuat

Vectormath::Aos::Quat* dmScript::ToQuat(lua_State* L, int index)

Get the value at index as a Vectormath::Aos::Quat*

PARAMETERS

`lua_State*`	`L`	Lua state
`int`	`index`	Index of the value

RETURNS

Vectormath::Aos::Quat* The pointer to the value, or 0 if not correct type

dmScript::PushQuat

void dmScript::PushQuat(lua_State* L, Vectormath::Aos::Quat quat)

Push a quaternion value onto Lua stack. Will increase the stack by 1.

PARAMETERS

`lua_State*`	`L`	Lua state
`Vectormath::Aos::Quat`	`quat`	Vectormath::Aos::Quat value to push

dmScript::CheckQuat

Vectormath::Aos::Quat* dmScript::CheckQuat(lua_State* L, int index)

Check if the value in the supplied index on the lua stack is a Vectormath::Aos::Quat.

PARAMETERS

`lua_State*`	`L`	Lua state
`int`	`index`	Index of the value

RETURNS

Vectormath::Aos::Quat* The pointer to the value

dmScript::ToMatrix4

Vectormath::Aos::Matrix4* dmScript::ToMatrix4(lua_State* L, int index)

Get the value at index as a Vectormath::Aos::Matrix4*

PARAMETERS

`lua_State*`	`L`	Lua state
`int`	`index`	Index of the value

RETURNS

Vectormath::Aos::Matrix4* The pointer to the value, or 0 if not correct type

dmScript::PushMatrix4

void dmScript::PushMatrix4(lua_State* L, Vectormath::Aos::Matrix4 matrix)

Push a matrix4 value onto the Lua stack. Will increase the stack by 1.

PARAMETERS

`lua_State*`	`L`	Lua state
`Vectormath::Aos::Matrix4`	`matrix`	Vectormath::Aos::Matrix4 value to push

dmScript::CheckMatrix4

Vectormath::Aos::Matrix4* dmScript::CheckMatrix4(lua_State* L, int index)

Check if the value in the supplied index on the lua stack is a Vectormath::Aos::Matrix4.

PARAMETERS

`lua_State*`	`L`	Lua state
`int`	`index`	Index of the value

RETURNS

Vectormath::Aos::Matrix4* The pointer to the value

dmJson::Type

int dmJson::Type(lua_State* L, dmJson::Document doc, int index, char* error_str_out, size_t error_str_size)

Convert a dmJson::Document document to Lua table.

PARAMETERS

`lua_State*`	`L`	lua state
`dmJson::Document`	`doc`	JSON document
`int`	`index`	index of JSON node
`char*`	`error_str_out`	if an error is encountered, the error string is written to this argument
`size_t`	`error_str_size`	size of error_str_out

RETURNS

int <0 if it fails. >=0 if it succeeds.

dmScript::CreateCallback

dmScript::CreateCallback( L, index)

Stores the current Lua state plus references to the script instance (self) and the callback. Expects SetInstance() to have been called prior to using this method. The allocated data is created on the Lua stack and references are made against the instances own context table. If the callback is not explicitly deleted with DestroyCallback() the references and data will stay around until the script instance is deleted.

PARAMETERS

	`L`	Lua state
	`index`	Lua stack index of the function

RETURNS

callback struct if successful, 0 otherwise

EXAMPLES

static int SomeFunction(lua_State* L) // called from Lua
{
    LuaCallbackInfo* cbk = dmScript::CreateCallback(L, 1);
    ... store the callback for later
}

static void InvokeCallback(LuaCallbackInfo* cbk)
{
    lua_State* L = dmScript::GetCallbackLuaContext(cbk);
    DM_LUA_STACK_CHECK(L, 0);

    if (!dmScript::SetupCallback(callback))
    {
        return;
    }

    lua_pushstring(L, "hello");

    dmScript::PCall(L, 2, 0); // self + # user arguments

    dmScript::TeardownCallback(callback);
    dmScript::DestroyCallback(cbk); // only do this if you're not using the callback again
}

dmScript::IsCallbackValid

void dmScript::IsCallbackValid( cbk)

Check if Lua callback is valid.

PARAMETERS

cbk Lua callback struct

dmScript::DestroyCallback

void dmScript::DestroyCallback( cbk)

Deletes the Lua callback

PARAMETERS

cbk Lua callback struct

dmScript::GetCallbackLuaContext

dmScript::GetCallbackLuaContext( cbk)

Gets the Lua context from a callback struct

PARAMETERS

cbk Lua callback struct

RETURNS

Lua state

dmScript::SetupCallback

dmScript::SetupCallback( cbk)

The Lua stack after a successful call:

   [-4] old instance
   [-3] context table
   [-2] callback
   [-1] self

In the event of an unsuccessful call, the Lua stack is unchanged

PARAMETERS

cbk Lua callback struct

RETURNS

if the setup was successful

dmScript::TeardownCallback

void dmScript::TeardownCallback( cbk)

Sets the previous instance Expects Lua stack:

   [-2] old instance
   [-1] context table

Both values are removed from the stack

PARAMETERS

cbk Lua callback struct

dmScript::PCall

dmScript::PCall( L, nargs, nresult)

This function wraps lua_pcall with the addition of specifying an error handler which produces a backtrace. In the case of an error, the error is logged and popped from the stack.

PARAMETERS

	`L`	lua state
	`nargs`	number of arguments
	`nresult`	number of results

RETURNS

code from pcall

Structs

dmScript::LuaHBuffer

TYPE

struct dmScript::LuaHBuffer

Holds info about the buffer and who owns it.

MEMBERS

`dmBuffer::HBuffer`	`m_Buffer`	The buffer (or resource)
`dmScript::LuaBufferOwnership`	`m_Owner`	What ownership the pointer has

dmScript::LuaCallbackInfo

TYPE

struct dmScript::LuaCallbackInfo

callback info struct that will hold the relevant info needed to make a callback into Lua

Macros

DM_LUA_STACK_CHECK

helper macro to validate the Lua stack state before leaving a function.

Diff is the expected difference of the stack size. If luaL_error, or another function that executes a long-jump, is part of the executed code, the stack guard cannot be guaranteed to execute at the end of the function. In that case you should manually check the stack using lua_gettop. In the case of luaL_error, see DM_LUA_ERROR.

`L`	lua state
`diff`	Number of expected items to be on the Lua stack once this struct goes out of scope

EXAMPLES

DM_LUA_STACK_CHECK(L, 1);
lua_pushnumber(L, 42);

DM_LUA_ERROR

helper macro to validate the Lua stack state and throw a lua error.

This macro will verify that the Lua stack size hasn't been changed before throwing a Lua error, which will long-jump out of the current function. This macro can only be used together with DM_LUA_STACK_CHECK and should be prefered over manual checking of the stack.

`fmt`	Format string that contains error information.
`args`	Format string args (variable arg list)

EXAMPLES

static int ModuleFunc(lua_State* L)
{
    DM_LUA_STACK_CHECK(L, 1);
    if (some_error_check(L))
    {
        return DM_LUA_ERROR("some error message");
    }
    lua_pushnumber(L, 42);
    return 1;
}