All Hollywood objects like brushes, videos, samples, etc. have an object identifier
that is used to refer to the object when calling a function that deals with this
object type. Hollywood objects can use two different kinds of identifiers: They can
either use a numerical identifier or an automatically chosen identifier that uses the
LUA_TLIGHTUSERDATA object type internally. The user can request an automatically chosen
identifier by passing Nil as the desired identifier when creating the object. In that
case, Hollywood will automatically choose an identifier for the object and return it.
This is usually done by using the raw memory pointer to the newly allocated object as
an identifier because this guarantees its uniqueness.
Internally, Hollywood object identifiers are managed using the lua_ID structure which
looks like this:
typedef struct _lua_ID
{
int num;
void *ptr;
} lua_ID;
|
Every Hollywood object has such a lua_ID associated with it. The two structure members
are initialized like this:
num:num and the ptr
member is set to NULL. If the ptr member is not NULL, Hollywood will ignore whatever is
in num and the object will automatically use the value in ptr as its identifier.
ptr:LUA_TLIGHTUSERDATA. This is typically set to the
raw memory pointer of the newly allocated object. If ptr is NULL, Hollywood will
automatically use the numerical identifier specified in num.
Whenever you call an API function that expects an object identifier you need to pass
a pointer to a lua_ID to it. For example, let's assume you want to use hw_LockBrush()
to access the raw pixel data of brush 1. In that case, you'd have to call hw_LockBrush()
like this:
lua_ID id = {1, NULL};
struct hwos_LockBrushStruct lb;
APTR handle;
handle = hw_LockBrush(&id, NULL, &lb);
if(handle) hw_UnLockBrush(handle);
|
If you are writing a plugin that has the HWPLUG_CAPS_LIBRARY capability flag set
and you want to offer a function that accepts either a numerical or an automatically
chosen object identifier, you can use the luaL_checkid()
function for that. luaL_checkid() will check whether the
value at the specified stack position is a number or a light userdata value and
then it will initialize the lua_ID structure accordingly. The function from above
would look like this then:
static SAVEDS int plug_LockBrush(lua_State *L)
{
lua_ID id;
struct hwos_LockBrushStruct lb;
APTR handle;
luaL_checkid(L, 1, &id);
handle = hw_LockBrush(&id, NULL, &lb);
if(handle) hw_UnLockBrush(handle);
}
|
By using luaL_checkid() your function can be made to accept numerical as well as light user data identifiers without much hassle.
You can also register your own Hollywood object types by calling the hw_RegisterUserObject() function. See hw_RegisterUserObject for details.