SDK Script API documentation

Version: alpha

<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::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::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


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::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

error

code from pcall


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::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


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