Script

<dmsdk/script/script.h>

Built-in scripting functions.

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.

PARAMETERS

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.

PARAMETERS

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

dmJson::Type()

convert a dmJson::Document to a Lua table

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

RETURN

int -

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

dmScript::CheckBuffer()

retrieve a HBuffer from the supplied lua state

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

RETURN

buffer -

LuaHBuffer* pointer to dmScript::LuaHBuffer

dmScript::CheckMatrix4()

check if the value is a Vectormath::Aos::Matrix4

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

RETURN

matrix -

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

dmScript::CheckQuat()

check if the value is a Vectormath::Aos::Vector3

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

RETURN

quat -

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

dmScript::CheckVector3()

check if the value is a Vectormath::Aos::Vector3

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

RETURN

vector3 -

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

dmScript::CheckVector4()

check if the value is a Vectormath::Aos::Vector3

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

RETURN

vector4 -

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

dmScript::GetInstance()

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

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

PARAMETERS

L -

lua_State* lua state

RETURN

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

check if the value is a dmScript::LuaHBuffer

Check if the value is a dmScript::LuaHBuffer

PARAMETERS

L -

lua_State* lua state

index -

int Index of the value

RETURN

boolean -

boolean True if value at index is a LuaHBuffer

dmScript::IsInstanceValid()

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

RETURN

boolean -

bool Returns true if the instance is valid

dmScript::LuaHBuffer()

Lua wrapper for a dmBuffer::HBuffer

Holds info about the buffer and who owns it.

MEMBERS

m_Buffer -

dmBuffer::HBuffer The buffer

m_UseLuaGC -

bool If true, it will be garbage collected by Lua. If false, the C++ extension still owns the reference.

dmScript::PushBuffer()

push a LuaHBuffer onto the supplied lua state

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

push a Vectormath::Aos::Matrix4 onto the Lua stack

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

push a Vectormath::Aos::Quat onto the Lua stack

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

push a Vectormath::Aos::Vector3 onto the Lua stack

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

push a Vectormath::Aos::Vector4 on the stack

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

wrapper for luaL_ref.

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

RETURN

reference -

int the new reference

dmScript::SetInstance()

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

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

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

PARAMETERS

L -

lua_State* Lua state

index -

int Index of the value

RETURN

quat -

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

dmScript::ToQuat()

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

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

PARAMETERS

L -

lua_State* Lua state

index -

int Index of the value

RETURN

quat -

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

dmScript::ToVector3()

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

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

PARAMETERS

L -

lua_State* Lua state

index -

int Index of the value

RETURN

v -

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

dmScript::ToVector4()

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

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

PARAMETERS

L -

lua_State* Lua state

index -

int Index of the value

RETURN

v -

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

dmScript::Unref()

wrapper for luaL_unref.

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