23/1/2015 Calling C++ functions from Lua 5.

2 | Pistachio Brainstorming

Pistachio Brainstorming
Ideas about science and game development

ABOUT THIS BLOG PIPERINE HUFFMANCODE Search...

PAGES
CALLING C++ FUNCTIONS FROM LUA 5.2
Home > Gamedev > Tutorials > Calling C++ functions from Lua 5.2 About this blog
[A­] | [A+]
Piperine
HuffmanCode

ARCHIVES

April 2014
January 2014
Welcome to the third part of these Lua 5.2 personal notes. If you have not yet, you may want to read my previous
April 2013
notes on running Lua 5.2 scripts from C++ or passing variables from Lua 5.2 to C++.
January 2013
December 2012
This new tutorial explains how to call C++ functions from Lua 5.2, including passing and receiving arguments
August 2012
from them. These notes are based on the Lua­User Wiki Sample Code and the Lua 5.2 Reference Manual, as
February 2012
usual, and on the tutorial by Christian Stigen Larsen.
July 2011
May 2011
First, I will show you some code (in Lua and C++) and the execution output. Afterwards comes the details of the
March 2011
most difficult parts.
February 2011
November 2010
Lua script September 2010
The Lua script will just call a C++ function with some input arguments, and then will receive and print two output August 2010
arguments. The code looks like this: July 2010
June 2010
‐‐ call the registered C‐function April 2010
io.write('[Lua] Calling the C functionn') December 2009
a,b = displayLuaFunction(12, 3.141592, 'hola')
November 2009
October 2009
‐‐ print the return values
September 2009
io.write('[Lua] The C function returned <' .. a .. '> and <' .. b .. '>n')
July 2009
C++ program June 2009
The C++ code is almost exactly the same as in the previous tutorial. The only differences are the declaration and May 2009

pushing of the function that Lua will call. The whole code is:

#include <iostream>
CATEGORIES
#include <sstream>

Gamedev (9) General (43)

#include <lua.hpp>

Stories (3) Tutorials (15)

int displayLuaFunction(lua_State*);

int main(int argc, char* argv[])

{
// new Lua state
std::cout << "[C++] Starting Lua state" << std::endl;
lua_State *lua_state = luaL_newstate();

// load Lua libraries

std::cout << "[C++] Loading Lua libraries" << std::endl;
static const luaL_Reg lualibs[] =
{
{"base", luaopen_base},
{"io", luaopen_io},
{NULL, NULL}

};
const luaL_Reg *lib = lualibs;
http://acamara.es/blog/calling­c­functions­from­lua­5­2/ 1/6
23/1/2015 Calling C++ functions from Lua 5.2 | Pistachio Brainstorming
const luaL_Reg *lib = lualibs;
for(; lib‐>func != NULL; lib++)
{
std::cout << " loading '" << lib‐>name << "'" << std::endl;
luaL_requiref(lua_state, lib‐>name, lib‐>func, 1);
lua_settop(lua_state, 0);
}

// push the C++ function to be called from Lua

std::cout << "[C++] Pushing the C++ function" << std::endl;
lua_pushcfunction(lua_state, displayLuaFunction);
lua_setglobal(lua_state, "displayLuaFunction");

// load the script

std::cout << "[C++] Loading the Lua script" << std::endl;
int status = luaL_loadfile(lua_state, "parrotscript.lua");
std::cout << " return: " << status << std::endl;

// run the script with the given arguments

std::cout << "[C++] Running script" << std::endl;
int result = 0;
if(status == LUA_OK)
{
result = lua_pcall(lua_state, 0, LUA_MULTRET, 0);
}
else
{
std::cout << " Could not load the script." << std::endl;
}

// close the Lua state

std::cout << "[C++] Closing the Lua state" << std::endl;
return 0;
}

int displayLuaFunction(lua_State *l)

{
// number of input arguments
int argc = lua_gettop(l);

// print input arguments

std::cout << "[C++] Function called from Lua with " << argc
<< " input arguments" << std::endl;
for(int i=0; i<argc; i++)
{
std::cout << " input argument #" << argc‐i << ": "
<< lua_tostring(l, lua_gettop(l)) << std::endl;
lua_pop(l, 1);
}

// push to the stack the multiple return values

std::cout << "[C++] Returning some values" << std::endl;
lua_pushnumber(l, 12);
lua_pushstring(l, "See you space cowboy");

// number of return values

return 2;
}

The output is:

http://acamara.es/blog/calling­c­functions­from­lua­5­2/ 2/6
23/1/2015 Calling C++ functions from Lua 5.2 | Pistachio Brainstorming

The details
Lua functions are first­class values. This means that they can be treated as conventional values, in particular, they
can be stored in variables. Thus, one can pass a function to Lua by simply pushing the value to the Lua stack and
making its name global:

// push the C++ function to be called from Lua

lua_pushcfunction(lua_state, displayLuaFunction);
lua_setglobal(lua_state, "displayLuaFunction");

Lua will be able to access displayLuaFunction() from its global name “displayLuaFunction”. Also, there is a
macro, lua_register(), that allows writing these two steps in one sentence. Instead of the previous code, one
might have coded it as:

// push the C++ function to be called from Lua

lua_register(lua_state, "displayLuaFunction", displayLuaFunction);

(my thanks to kpityu for pointing this out in the comments).

In order C++ functions to communicate properly with Lua, they must follow some rules. The first one is its
signature, which has to be consistent with the type defined by lua_CFcuntion:

typedef int (*lua_CFunction) (lua_State *L);

i. e., the function must return an integer and only accept one input argument of type pointer­to lua_state.

The second rule is just a protocol to follow for input/output function argument interchange between Lua and
C++. As you may have guessed, all this passing of variables is done via the Lua stack. When a C++ function is
called from Lua, for example

displayLuaFunction(a, b, c)

a new Lua stack, independent of the rest of stacks, is generated for the function. This stack contains the input
arguments of the function. Thus, from inside of the C++ function one knows the amount of input arguments by
getting the position of the top of this stack:

// number of input arguments

int argc = lua_gettop(l);

and the input arguments can be accessed directly from the stack:

lua_tostring(l, lua_gettop(l));

Notice that the order in the stack is the same as in the function call, hence, the first element popped is actually the
last input argument. Since initially the only elements of the stack are the input arguments, you may access a given
index by directly pointing to it. For instance, for the second input argument can be converted to a string — having
checked the stack has at least two elements — by this statement:

lua_tostring(l, 2);

Once the function has finished, the return values must be placed in the stack so Lua can reach them:

// push to the stack the multiple return values

lua_pushnumber(l, 12);
lua_pushstring(l, "See you space cowboy");

The final part is to return the number of variables pushed to the stack that we want Lua to see as the C++
function return value:

http://acamara.es/blog/calling­c­functions­from­lua­5­2/ 3/6
23/1/2015 Calling C++ functions from Lua 5.2 | Pistachio Brainstorming

// number of return values

return 2;

And that is it!

With this we have covered the basic protocol for creating new C++ functions that are Lua compatible. In case you
want more examples you can check the Lua libraries, which are made of C++ functions following these rules.

Stay tuned for the next episode of these personal notes. I am not sure if I will be talking about linking C++
dynamic libraries to Lua or about encapsulating and passing objects from and to Lua.

Read the next tutorial!

Tags: C++ GAMEDEV LUA PROGRAMMING TUTORIAL

About SOY_YUMA
View all posts by Soy_yuma →

By Soy_yuma | 19th August 2012 | SHOW COMMENTS (10)

PASSING VARIABLES FROM LUA CREATING A LUA 5.2 DYNAMIC

5.2 TO C++ (AND VICE­VERSA) LINK LIBRARY OF C FUNCTIONS

POST A COMMENT

Submit Comment

Notify me of follow­up comments by email.

Notify me of new posts by email.

10 Responses

Doug says
Tuesday, January 14th 2014 at 6:53 pm
Fantastic job! One minor nit, “First” is misspelled “Frist” in third paragraph….

Reply ↓

Soy_yuma says
Tuesday, January 14th 2014 at 9:48 pm
Good spot! Thanks!

Reply ↓

http://acamara.es/blog/calling­c­functions­from­lua­5­2/ 4/6