- Select ref document -

SDK Script API documentation

version 1.2.144

<dmsdk/script/script.h>

Built-in scripting functions.

Functions

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

L

lua_State* lua state

index

int Index of the value

Returns

buffer

LuaHBuffer* pointer to dmScript::LuaHBuffer

buffer

LuaHBuffer* pointer to dmScript::LuaHBuffer

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

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

L

lua_State* lua state

Returns

lua_State

lua_State* the main thread lua state

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)

Parameters

L

lua_State* lua state

index

int Index of the value

L

lua_State* lua state

index

int Index of the value

Returns

boolean

boolean true if value at #index is a LuaHBuffer

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

L

lua_State* lua state

Returns

boolean

bool Returns true if the instance is valid

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

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

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

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

L

lua_State* lua state

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

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

DM_LUA_ERROR(fmt, args)

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)

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

DM_LUA_STACK_CHECK(L, diff)

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

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

Structs

dmScript::LuaHBuffer

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.

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.