SDK Script API documentation

<dmsdk/script/script.h>

Built-in scripting functions.

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

check if the value is a dmScript::LuaHBuffer

dmScript::IsInstanceValid()
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::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::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::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::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, true };
PushBuffer(L, luabuf);

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

dmScript::LuaHBuffer luabuf = { buffer, false };
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::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


dmScript::Unref()

dmScript::Unref(L,table,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

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);