Name
RequirePlugin -- require a plugin (V6.0)
Synopsis
int error = RequirePlugin(lua_State *L, int version, int revision,
                ULONG flags, struct hwTagList *tags);
Function
This function will be called when the user runs the @REQUIRE preprocessor command on the plugin. It is especially useful to initialize plugins that are not automatically set up when Hollywood starts. You will typically initialize these plugin types from your RequirePlugin() function then. See Auto and manual plugin initialization for details.

RequirePlugin() can also be used to perform some custom initialization or configuration according to the user's specific needs as it is possible to pass parameters from the @REQUIRE preprocessor statement to your RequirePlugin() implementation through the HWRPTAG_USERTAGS tag item (see below).

Here is a list of tags supported by this function:

HWRPTAG_USERTAGS:
Hollywood will set this tag to a struct hwRequireUserTagList containing a list of all parameters the user has passed to the @REQUIRE preprocessor command. The struct hwRequireUserTagList looks like this:

 
struct hwRequireUserTagList
{
    struct hwRequireUserTagList *Succ;
    STRPTR Name;
    STRPTR Str;
    double Val;
};

Here is a description each member variable:

Succ:
Contains a pointer to the next node in the list or NULL for the tail node.

Name:
Name of the parameter.

Str:
If the user has set the parameter to a string value, it is passed here. If this is NULL, then you have to examine the Val member below.

Val:
If the user has set the parameter to a numerical value, it is passed in this structure member.

HWRPTAG_PLUGINFLAGS:
This tag is used to return plugin flags back to Hollywood. Hollywood will pass a pointer to a ULONG variable here which you can write to if your plugin wants to request certain features. The following flags are currently recognized:

HWPLUGINFLAGS_HIDEDISPLAYS:
If you set this flag, Hollywood will hide all displays upon startup. Even the ones that have been explicitly declared as open will be hidden if this tag is set.

HWPLUGINFLAGS_SCALEDISPLAYS:
If you set this flag, Hollywood will apply system scaling to all displays, i.e. this flag will do the same as setting the SystemScale tag to True for all displays. (V8.0)

HWPLUGINFLAGS_INTERPOLATE:
If HWPLUGINFLAGS_SCALEDISPLAYS is set and the current monitor's density setting requires scaling, setting HWPLUGINFLAGS_INTERPOLATE will use bilinear interpolation when scaling. (V8.0)

Note that if you want your plugin to be compatible with Hollywood Designer you need to set the HWEXT_REQUIRE_LUALESS extension and make sure your implementation of RequirePlugin() doesn't crash when a NULL pointer is passed in the L argument. Since Designer doesn't contain a Lua virtual machine, it won't be able to pass a lua_State pointer to RequirePlugin(). That is why by default, Designer ignores plugins which depend on RequirePlugin() to be called. However, if you set HWEXT_REQUIRE_LUALESS and then make sure that your RequirePlugin() implementation can handle a NULL pointer in the lua_State argument, your plugin will be compatible with Designer as well. See GetExtensions for details.

Inputs
L
pointer to the lua_State
version
plugin version requested in @REQUIRE call
revision
plugin revision requested in @REQUIRE call
flags
currently unused, will be 0
tags
pointer to a taglist or NULL (see above)
Results
error
error code or 0 for success
Show TOC