Anti-Alias.Me

This post is the logical sequel to my previous post on Lua. In the previous post I went over the basics of exposing functions and data from C to Lua, and vice versus. In this post, I want to expand on that by exploring the possibilities of exposing full Objective-C objects to our Lua runtime.

The direction that I’m taking these posts is from the perspective of a game developer, wanting to expose some of their native code to scripters in order to quickly develop features of their game. The Lua runtime is super small, so even using it to store configuration data is not a huge waste of time and space though using it to control actual gameplay is a much more interesting usage I must admit.

In this particular post, I’d like to go over what we need to do in order to expose an obj-c object to the Lua runtime, as well as set up the stage for a means to limit the functionality that the Lua runtime has access to. My reasoning for this is to provide an engine developer with a safety net to stop scripters from making use of every function available to an object. By providing this capability developers won’t need to create an extra “Script Object” layer that ultimately gets exposed to the Lua runtime, and can instead expose the objects closest to the inner workings of the game.

LuaEngine.h/.m

All of the code for this post will be in the same class, LuaEngine. Pretty much everything for the rest of this series of posts will be in here, all nice and contained. The only time we’ll venture off into other classes, is when we actually expose an object.

First, we’ll obviously want to re-create the functionality that we had in the last post. The ability to expose basic data, and basic functions to the Lua runtime from our obj-c code. To do this, I’ve created some basic messages on the LuaEngine class, as follows:

-(void)registerFunction:(lua_CFunction)func withName:(NSString*)name;
-(void)setGlobal:(NSString*)name toNumber:(NSNumber*)number;
-(int)doFile:(NSString*)file;
-(int)callFunction:(NSString*)func;

The code for these functions can be found here, and I won’t spend too much time on them, except for the setGlobal:toNumber, which might need a little bit of explanation. Here are the two functions involved:

void lua_pushnsnumber(lua_State *l, NSNumber *number) {
   switch ([number objCType][0]) {
      case _C_FLT:
      case _C_DBL:
         lua_pushnumber(l, [number doubleValue]);
         break;
      case _C_INT:
      case _C_LNG:
      case _C_ULNG:
      case _C_USHT:
      case _C_SHT:
         lua_pushinteger(l, [number longValue]);
         break;
   }
} 
 
-(void)setGlobal:(NSString*)name toNumber:(NSNumber*)number {
	lua_pushnsnumber(_luaState, number);
	lua_setglobal(_luaState, [name UTF8String]);
}

The part that might need a little bit of explanation is the lua_pushnsnumber function, and the objCType message at line 2. Basically what that is doing is asking the NSNumber object what the runtime type is for the number it is representing. The objective-c runtime keeps track of data types using a single character (or multi-character in some situations, like blocks) value for each primitive type (int, float, id, SEL, char, etc.). We’ll be seeing these constants again, but for our purposes here, we’re using the Lua C API functions lua_pushnumber and lua_pushinteger depending on the data type that the NSNumber has. Using lua_pushnumber if the data is a float, or double, and lua_pushinteger if the data is an int, long, unsigned long, unsigned short, or short.

By using the runtime data when/where we can, we can help to generalize our code so we don’t have to keep writing specific implementations. For instance, the message setGlobal:toNumber is a lot nicer than having to write setGlobal:toFloat, setGlobal:toInteger, setGlobal:toDouble, etc.

Now that we have those methods defined, we’re basically right where we left off last time. To expose the same data that we did in the last post, we’d use the following code:

LuaEngine luaEngine = [[LuaEngine alloc] init]; // Create our Lua stack
[luaEngine setGlobal:@"MAX_WIDTH" toNumber:[NSNumber numberWithFloat:1.0f]];
[luaEngine setGlobal:@"MIN_WIDTH" toNumber:[NSNumber numberWithFloat:-1.0f]];
// And so on..

Object Oriented Exposure

Now that we’re back to where we ended last post, lets consider what we need to do in order to expose an object to Lua.

Lua Syntax

First thing is first, we need to figure out how we would provide access to an object from Lua. Since Lua doesn’t have a typical object-oriented functionality, we can’t just expose an object and tell Lua that it is an object. What Lua does have though are tables, and a very extensible method for adding functionality to tables.

Lua’s tables are of the typical hash-table variety. So syntactically in Lua one would probably use them like so,

someTable = {} -- Initialize table
someTable["key"] = value -- Set value to the table entry 'key'

Which is a pretty ugly way to access objects and their members. Luckily, Lua also provides a syntactical sugar which allows us to use tables like so:

someTable = {} -- Initialize table
someTable.key = value -- Set value to the table entry 'key'

This, is starting to look MUCH better.

So we know in Lua, functions are first class citizens. Meaning, we can pass a function around just like it was a normal piece of data. So, we could do something like this:

function someFunc()
   print "Hi"
end
someTable = {} -- initialize table
someTable.blah = someFunc
someTable.blah()

..and the output we should get is a simple, “Hi”.

So, what we’ve just proved, is that Lua knows how to treat functions as data. So if we’re able to expose our object as a table, and somehow let Lua know each of the functions and data members that we want to provide, via entries in the table, we can give Lua access to C functions, and data via the table.

Now, remember how I said Lua makes extending tables super easy? Every time a value is requested from a table, Lua triggers a meta method called “index” which will ask the table “what is the data associated with this key?”. Normally, the standard Lua “index” method is used, and data is found using the built in hashing algorithm, and returned nice and smooth. Lua knows to call this internal index method by looking at the table’s “metatable”. The metatable is another table, that keeps track of what functions are available for a given table. Think of it like a Lua version of C++’s vtable, only there isn’t any inheritance, only one table.

We can play with this using straight Lua like this:

1
2
3
4
5
6
7
8
9

function lookup(table, key)
   print("Lookup: " .. key)
   return "BEWM"
end
mt = {}              -- Initialize our metatable
mt.__index = lookup  -- Set a new function for the "index" metamethod
t = {}               -- Create a new empty table
setmetatable(t, mt)  -- Set the metatable for t to mt
print(t.asdf)        -- Try to find a value in t...

First I’ve defined a new function called lookup, note the two parameters. The first, is a table, which represents the table the lookup is being requested for. The second parameter, is the value for the key. Keep in mind, that a key doesn’t necessarily have to be a string value, it can be anything, including a function. For our test purposes though, I’m assuming it’s a string.

Next, I create a new table, mt, which represents our metatable. I set the “__index” value to our lookup function. Remember that when a value is requested for a table entry, the “index” metamethod is called. Metamethods like index, are preceded by two underscores when referencing the actual table entry for their functions.

After setting the index function, I create a new empty table, and call setmetatable which is a Lua function that replaces the current metatable for a table, with one provided. So, I’ve set the metatable for t to the table mt.

The last line, is where the magic comes together. In attempting to print out the value for “asdf” in the table t, I trigger the index metamethod on t, which is now wired up to my lookup function. When lookup is called, it’s given a reference to t and the key that it wants the value for. So, when the code is run, we get the output:

Lookup: asdf
BEWM

Which shows the output from lookup, telling us that the value for “asdf” was requested. As well as the output “BEWM” which, as far as Lua knows, is the value for “asdf” in the table t.

So now it should be pretty clear that if we can associate an object with a Lua table, then we can hijack the metamethods in order to return appropriate values for whatever members are requested by the Lua script.

The Almighty User Data

Now, our last challenge, exposing the object itself comes pretty quickly to realization with the usage of Lua’s user data type.

Lua’s userdata allows us to allocate memory in the Lua runtime, and store a value there. For all intents and purposes, that new data we store is Lua data. Which means it can have its own metatable. It can also be collected via the Lua’s garbage collection. Super.

Bringing it all together..

Lets introduce a new message in LuaEngine..

-(void)setGlobal:(NSString*)name toObject:(NSObject*)obj;

So, we need a userdata for each object, and ideally a metatable for each object type. Though, we can really get by with only a single metatable for our entire bridge, since we’ll be exposing objects the same way no matter the object. So, lets start out with the following code,

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

static int luaEngine_methodcall(lua_State *l) { 
}
 
static int luaEngine_methodLookup(lua_State *l) {
	const char *s = luaL_checkstring(l, 2); 
	lua_pushstring(l, s);
	lua_pushcclosure(l, &luaEngine_methodcall, 1);
	return 1;
}           
 
-(void)setGlobal:(NSString*)name toObject:(NSObject*)obj {
   	if (luaL_newmetatable(_luaState, "LuaEngineMetaTable") != 0) {
		lua_pushstring(_luaState, "__index");
		lua_pushcfunction(_luaState, &luaEngine_methodLookup);
		lua_settable(_luaState, -3);
	}
	void **data = lua_newuserdata(_luaState, sizeof(id*));
	*data = obj;	
	luaL_getmetatable(_luaState, "LuaEngineMetaTable");
	lua_setmetatable(_luaState, -2);
	lua_setglobal(_luaState, [name UTF8String]);     
}

When we come into setGlobal:toObject the first thing we try to do is create the metatable. If the metatable exists, the call to luaL_newmetatable does nothing and we continue on. If it doesn’t exist however, we create the metatable, and set the metamethod “index” to a C function I’ve defined called luaEngine_methodLookup.

Then we create our new userdata, and set its metatable to the metatable we just created. Once that’s done, our userdata is still on the stack, so we simply call lua_setglobal to make it a global variable with the given name, name.

And we’re done. Kinda.

As you can see there are two other functions that I haven’t explained, but by now they should be pretty self explanatory in their purpose if not in their implementation.

If you recall the Lua function lookup I defined earlier, you pretty much know the purpose of luaEngine_methodLookup. Just like our Lua function, this function’s task is to supply Lua with the value of the requested table entry, for the supplied table. Obviously the only way Lua is going to call this C function is if we do an entry lookup on one of our userdata objects, so we have a pretty good idea that we’ll be wanting to send a message to the object.

That assumption is the reason luaEngine_methodLookup is so short. All it needs to do is tell Lua, “Hey, it’s a function! And here’s the address.”

You might be asking, “If that’s all it is doing what is this pushstring on line 6?? And what is it pushing a closure for??”. My astute reader, you are correct. We aren’t just returning the address of a function and calling it a day. In order to get the actual address of the function we need to call, we need to know the selector for the Objective-C message.

Note: For the purposes of this post (and this will change next post), I’m making the assumption that our Objective-C object has simple functions. Stuff like,

1
2
3
4
5

  // We can use these two..
  -(float)getX;
  -(void)setX:(float)x;
  // But not this one..
  -(void)setX:(float)x andY:(float)y;

I’ll explain why, and solve the problem next post, but for now we use the same name as the Lua value being requested for our Obj-C selector.

Since, we’re not 100% sure what selector is actually being requested (think: the # of parameters is unknown at this point, etc.) I’m telling lua to use the same function address for every function call. In order to determine what selector to use when the function is actually called, we need to provide that function with the information we do know. In order to do that, we use up-values and closures.

Up-values are similar to C’s static local variables, for a function. In Lua, a function with up-values, is a closure. So we tell Lua that the value it is requesting is a closure, and we return the function we want it to call (luaEngine_methodcall), but before doing that we set an up-value for the function to the name of the value requested (our ‘selector’). This way, when luaEngine_methodcall gets called, it will have a copy of the name requested by Lua making the job of finding what message we actually want to call, all the more easier (read: possible).

I’m going to end here, simply because this post has been sitting in my draft bin for months, and I’d like to get it out in the hopes it will motivate me to get the next one out all the sooner. Next post, we’ll solve the selector problem, and show some decent demo code which could be pieced together from what is in this post.

As always, comments are welcome.. unless you’re selling drugs, or advertising porn.. then not so much.

So this is the new site.

I’ve copied over a few of the posts that I had on the previous blog, and am in the process of polishing them up. That may take some time, as most of them were about projects I was working on a long time ago. So I’ll need to pull the code back out, and see where I was when I left off.

For the immediate future however, I’ll be using this site to help myself with a literature review I need to conduct for my honors thesis. I will basically be summarizing and discussing articles that I read to prepare for the work involved with my thesis. So, it will not only help me get work done, but also might be of benefit to anyone reading this who is interested in the topics I’ll be exploring (primarily medical visualization, mobile graphics research, and volume rendering).

I should be kicking off the first summary in the next day or two, I’m preparing for the start of the semester so it might be a bumpy start. But, I need to get this done, so it will happen.  As I get some free time, I’ll finish off the articles I have in queue, and we can explore some cool topics together. I have one more post about Lua and Objective-C lined up, which is why I brought over the previous one. I have a nearly complete Lua bridge implemented, that follows a pretty solid game-scripting guideline that I’ve been thinking about. So that will be fun to finally get out in the open.

So, wish me luck, and lets make this happen for realz this time.

As always, feel free to comment, and discuss, that’s what this is here for.

-glitch