Plugins that have the capability flag HWPLUG_CAPS_LIBRARY set can add
new commands and constants to Hollywood's set of inbuilt commands and constants.
If you want to write such a plugin, you need to familiarize yourself with the
Lua which Hollywood uses as a VM. You can access Hollywood's Lua VM through the
LuaBase pointer that is passed inside the hwPluginAPI table
which your InitPlugin() function receives.
Here is a brief explanation of how Lua calls C functions: Your function will
receive just a single parameter - a pointer to the lua_State. All
parameters that the script passes to your function will be pushed into the stack.
If you want to return values to Lua, you have to push them into the stack as
well and return the number of values you pushed. Alternatively, you can also return
an error code. Standard error codes are defined in hollywood/errors.h.
You can also register custom error codes using hw_RegisterError().
Here is how a custom function that simply divides the first parameter by the second:
static SAVEDS int MyDiv(lua_State *L)
{
double a = luaL_checknumber(L, 1);
double b = luaL_checknumber(L, 2);
// catch division by zero CPU exception and handle
// it cleanly
if(b == 0) return ERR_ZERODIVISION;
lua_pushnumber(L, a / b);
// push 1 to indicate one return value
return 1;
}
|
This is just a primitive example. Check the Lua manual for more information on how to implement Lua functions in C. Please note that Hollywood uses Lua 5.0.2 so make sure you consult the correct manual. See LuaBase functions for details.
The SDK distribution also comes with an example library plugin which adds several functions and constants to Hollywood. Feel free to study this example code to learn how library plugins are written in practice.
Starting with Hollywood 6.0 library plugins support the HWEXT_LIBRARY_MULTIPLE
extension. If this extension is set, a library can install multiple libraries
instead of just a single one. If you set the HWEXT_LIBRARY_MULTIPLE extension bit,
you need to implement the GetLibraryCount() and SetCurrentLibrary()
functions. Hollywood will then call GetLibraryCount() to
find out how many libraries your plugin wants to install. See Extension plugins to learn how to use plugin extension bits.
Starting with Hollywood 6.1 library plugins can set the HWEXT_LIBRARY_NOAUTOINIT
extension flag. If this is set, the library's commands and constants won't be
added to Hollywood's set of commands and constants automatically when the plugin
is loaded. Instead, the library's commands and constants will only be added if
the user performs a @REQUIRE on the plugin. This is useful for library plugins
which add lots of commands and constants. Adding them to every single Hollywood
script is unnecessary overhead, so it is a good idea to use HWEXT_LIBRARY_NOAUTOINIT
for those libraries so that their commands and constants are only installed when
a script explicitly requests them. See Extension plugins to learn how to use plugin extension bits.
Starting with Hollywood 7.0 library plugins support the HWEXT_LIBRARY_HELPSTRINGS
extension bit. If this is set, your plugin needs to implement a function named GetHelpStrings()
which needs to return a table containing a help string and a node in the plugin's help file
for each command. See GetHelpStrings for details.
Starting with Hollywood 7.1 library plugins support the HWEXT_LIBRARY_UPVALUES
extension bit. If this is set, your plugin needs to implement a function named PushUpvalues()
which pushes the desired upvalues to the stack and returns the number of values
pushed. See PushUpvalues for details.