SDK Script API documentation

Version: alpha

FUNCTION
dmJson::Type()	convert a dmJson::Document to a Lua table
dmScript::CheckBuffer()	retrieve a HBuffer from the supplied lua state
dmScript::CheckMatrix4()	check if the value is a Vectormath::Aos::Matrix4
dmScript::CheckQuat()	check if the value is a Vectormath::Aos::Vector3
dmScript::CheckVector3()	check if the value is a Vectormath::Aos::Vector3
dmScript::CheckVector4()	check if the value is a Vectormath::Aos::Vector3
dmScript::CreateCallback()	Register a Lua callback.
dmScript::DestroyCallback()	Deletes the Lua callback
dmScript::GetCallbackLuaContext()	Gets the Lua context from a callback struct
dmScript::GetInstance()
dmScript::GetMainThread()
dmScript::IsBuffer()	check if the value is a dmScript::LuaHBuffer
dmScript::IsCallbackValid()	Check if Lua callback is valid.
dmScript::IsInstanceValid()
dmScript::IsVector3()
dmScript::IsVector4()
dmScript::PCall()
dmScript::PushBuffer()	push a LuaHBuffer onto the supplied lua state
dmScript::PushMatrix4()	push a Vectormath::Aos::Matrix4 onto the Lua stack
dmScript::PushQuat()	push a Vectormath::Aos::Quat onto the Lua stack
dmScript::PushVector3()	push a Vectormath::Aos::Vector3 onto the Lua stack
dmScript::PushVector4()	push a Vectormath::Aos::Vector4 on the stack
dmScript::Ref()	wrapper for luaL_ref.
dmScript::SetInstance()
dmScript::SetupCallback()	Setups up the Lua callback prior to a call to dmScript::PCall()
dmScript::TeardownCallback()	Cleans up the stack after SetupCallback+PCall calls
dmScript::ToMatrix4()	get the value at index as a Vectormath::Aos::Matrix4*
dmScript::ToQuat()	get the value at index as a Vectormath::Aos::Quat*
dmScript::ToVector3()	get the value at index as a Vectormath::Aos::Vector3*
dmScript::ToVector4()	get the value at index as a Vectormath::Aos::Vector4*
dmScript::Unref()	wrapper for luaL_unref.

Functions

dmJson::Type()

dmJson::Type(L,doc,index,error_str_out,error_str_size)

Convert a dmJson::Document document to Lua table.

PARAMETERS

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

RETURNS

int

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

dmScript::CheckBuffer()

dmScript::CheckBuffer(L,index)

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

PARAMETERS

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

RETURNS

buffer

LuaHBuffer* pointer to dmScript::LuaHBuffer

dmScript::CheckMatrix4()

dmScript::CheckMatrix4(L,index)

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

PARAMETERS

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

RETURNS

matrix

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

dmScript::CheckQuat()

dmScript::CheckQuat(L,index)

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

PARAMETERS

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

RETURNS

quat

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

dmScript::CheckVector3()

dmScript::CheckVector3(L,index)

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

PARAMETERS

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

RETURNS

vector3

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

dmScript::CheckVector4()

dmScript::CheckVector4(L,index)

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

PARAMETERS

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

RETURNS

vector4

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

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

Lua

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::DestroyCallback()

dmScript::DestroyCallback(cbk)

PARAMETERS

cbk

Lua callback struct

dmScript::GetCallbackLuaContext()

dmScript::GetCallbackLuaContext(cbk)

PARAMETERS

cbk

Lua callback struct

RETURNS

L

Lua state

dmScript::GetInstance()

dmScript::GetInstance(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

`L`	lua_State* lua state

dmScript::GetMainThread()

dmScript::GetMainThread(L)

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

PARAMETERS

`L`	lua_State* lua state

RETURNS

lua_State

lua_State* the main thread lua state

EXAMPLES

How to create a Lua callback

struct LuaCallbackInfo
{
    LuaCallbackInfo() : m_L(0), m_Callback(LUA_NOREF), m_Self(LUA_NOREF) {}
    lua_State* m_L;
    int        m_Callback;
    int        m_Self;
};

static void RegisterCallback(lua_State* L, int index, LuaCallbackInfo* cbk)
{
    if(cbk->m_Callback != LUA_NOREF)
    {
        dmScript::Unref(cbk->m_L, LUA_REGISTRYINDEX, cbk->m_Callback);
        dmScript::Unref(cbk->m_L, LUA_REGISTRYINDEX, cbk->m_Self);
    }

    cbk->m_L = dmScript::GetMainThread(L);

    luaL_checktype(L, index, LUA_TFUNCTION);
    lua_pushvalue(L, index);
    cbk->m_Callback = dmScript::Ref(L, LUA_REGISTRYINDEX);

    dmScript::GetInstance(L);
    cbk->m_Self = dmScript::Ref(L, LUA_REGISTRYINDEX);
}

static void UnregisterCallback(LuaCallbackInfo* cbk)
{
    if(cbk->m_Callback != LUA_NOREF)
    {
        dmScript::Unref(cbk->m_L, LUA_REGISTRYINDEX, cbk->m_Callback);
        dmScript::Unref(cbk->m_L, LUA_REGISTRYINDEX, cbk->m_Self);
        cbk->m_Callback = LUA_NOREF;
    }
}

LuaCallbackInfo g_MyCallbackInfo;

static void InvokeCallback(LuaCallbackInfo* cbk)
{
    if(cbk->m_Callback == LUA_NOREF)
    {
        return;
    }

    lua_State* L = cbk->m_L;
    int top = lua_gettop(L);

    lua_rawgeti(L, LUA_REGISTRYINDEX, cbk->m_Callback);

    // Setup self (the script instance)
    lua_rawgeti(L, LUA_REGISTRYINDEX, cbk->m_Self);
    lua_pushvalue(L, -1);

    dmScript::SetInstance(L);

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

    int number_of_arguments = 3; // instance + 2
    int ret = lua_pcall(L, number_of_arguments, 0, 0);
    if(ret != 0) {
        dmLogError("Error running callback: %s", lua_tostring(L, -1));
        lua_pop(L, 1);
    }
    assert(top == lua_gettop(L));
}

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

    RegisterCallback(L, 1, &g_MyCallbackInfo);

    return 0;
}

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

    static int count = 0;
    if( count++ == 5 )
    {
        InvokeCallback(&g_MyCallbackInfo);
        UnregisterCallback(&g_MyCallbackInfo);
    }
    return 0;
}

dmScript::IsBuffer()

dmScript::IsBuffer(L,index)

Check if the value is a dmScript::LuaHBuffer

PARAMETERS

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

RETURNS

boolean

boolean True if value at index is a LuaHBuffer

dmScript::IsCallbackValid()

dmScript::IsCallbackValid(cbk)

PARAMETERS

cbk

Lua callback struct

dmScript::IsInstanceValid()

dmScript::IsInstanceValid(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

`L`	lua_State* lua state

RETURNS

boolean

bool Returns true if the instance is valid

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

true

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

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

true

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

dmScript::PushBuffer()

dmScript::PushBuffer(L,buffer)

Will increase the stack by 1.

PARAMETERS

`L`	lua_State* lua state
`buffer`	dmScript::LuaHBuffer 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::PushMatrix4()

dmScript::PushMatrix4(L,matrix)

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

PARAMETERS

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

dmScript::PushQuat()

dmScript::PushQuat(L,quat)

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

PARAMETERS

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

dmScript::PushVector3()

dmScript::PushVector3(L,v)

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

PARAMETERS

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

dmScript::PushVector4()

dmScript::PushVector4(L,v)

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

PARAMETERS

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

dmScript::Ref()

dmScript::Ref(L,table)

Creates and returns a reference, in the table at index t, for the object at the top of the stack (and pops the object). It also tracks number of global references kept.

PARAMETERS

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

RETURNS

reference

int the new reference

dmScript::SetInstance()

dmScript::SetInstance(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

`L`	lua_State* 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

true

if the setup was successful

dmScript::TeardownCallback()

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::ToMatrix4()

dmScript::ToMatrix4(L,index)

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

PARAMETERS

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

RETURNS

quat

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

dmScript::ToQuat()

dmScript::ToQuat(L,index)

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

PARAMETERS

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

RETURNS

quat

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

dmScript::ToVector3()

dmScript::ToVector3(L,index)

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

PARAMETERS

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

RETURNS

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

dmScript::ToVector4()

dmScript::ToVector4(L,index)

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

PARAMETERS

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

RETURNS

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

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

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

Macros

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`	const char* 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;
}

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* lua state
`diff`	int 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);

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