18.1 Overview

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.

Show TOC