int success = InitPlugin(hwPluginBase *self, hwPluginAPI *cl, STRPTR path);

typedef struct _hwPluginBase { ULONG CapsMask; // [out] int Version; // [out] int Revision; // [out] int hwVersion; // [in/out] int hwRevision; // [in/out] STRPTR Name; // [out] STRPTR ModuleName; // [out] STRPTR Author; // [out] STRPTR Description; // [out] STRPTR Copyright; // [out] STRPTR URL; // [out] STRPTR Date; // [out] STRPTR Settings; // [out] STRPTR HelpFile; // [out] } hwPluginBase;

Here is an explanation about the function of the different structure members:

CapsMask:

This is a bitmask describing the capabilities of your plugin, i.e. which features your plugin provides. Hollywood uses this bitmask to determine which function pointers it has to import from your plugin. This member must be set to one or more of the following capabilities:

HWPLUG_CAPS_CONVERT

Plugin can convert custom file types into Hollywood scripts. See Convert script plugins for details.

HWPLUG_CAPS_LIBRARY

Plugin adds new commands and constants. See Library plugins for details.

HWPLUG_CAPS_IMAGE

Plugin provides a loader for additional image formats. See Image plugins for details.

HWPLUG_CAPS_ANIM

Plugin provides a loader for additional animation formats. See Animation plugins for details.

HWPLUG_CAPS_SOUND

Plugin provides a loader for additional sound formats. See Sound plugins for details.

HWPLUG_CAPS_VECTOR

Plugin provides an implementation to draw vector graphics. See Vectorgraphics plugins for details.

HWPLUG_CAPS_VIDEO

Plugin provides a loader for additional video formats. See Video plugins for details.

HWPLUG_CAPS_SAVEIMAGE

Plugin provides a saver for additional image formats. See Image saver plugins for details.

HWPLUG_CAPS_SAVEANIM

Plugin provides a saver for additional animation formats. See Animation saver plugins for details.

HWPLUG_CAPS_SAVESAMPLE

Plugin provides a saver for additional sound formats. See Sample saver plugins for details.

HWPLUG_CAPS_REQUIRE

Plugin wants to be called when the user does a @REQUIRE on it. See Require hook plugins for details. (V6.0)

HWPLUG_CAPS_DISPLAYADAPTER

Plugin replaces Hollywood's inbuilt display handler. See Display adapter plugins for details. (V6.0)

HWPLUG_CAPS_TIMERADAPTER

Plugin replaces Hollywood's inbuilt timer handler. See Timer adapter plugins for details. (V6.0)

HWPLUG_CAPS_REQUESTERADAPTER

Plugin replaces Hollywood's inbuilt requester handler. See Requester adapter plugins for details. (V6.0)

HWPLUG_CAPS_FILEADAPTER

Plugin provides a loader for additional file formats. See File adapter plugins for details. (V6.0)

HWPLUG_CAPS_DIRADAPTER

Plugin provides a loader for additional directory formats. See Directory adapter plugins for details. (V6.0)

HWPLUG_CAPS_AUDIOADAPTER

Plugin replaces Hollywood's inbuilt audio driver. See Audio adapter plugins for details. (V6.0)

HWPLUG_CAPS_EXTENSION

This is a special plugin type that does not offer any functionality on its own. Its only purpose is to extend other plugin types. See Extension plugins for details. (V6.0)

HWPLUG_CAPS_NETWORKADAPTER

Plugin provides a handler for custom network protocols. See Network adapter plugins for details. (V8.0)

HWPLUG_CAPS_SERIALIZE

Plugin provides a new data serializer. See Serializer plugins for details. (V9.0)

HWPLUG_CAPS_ICON

Plugin provides a loader for additional icon formats. See Icon plugins for details. (V9.0)

HWPLUG_CAPS_SAVEICON

Plugin provides a saver for additional icon formats. See Icon saver plugins for details. (V9.0)

HWPLUG_CAPS_IPCADAPTER

Plugin replaces Hollywood's inbuilt IPC handler. See IPC adapter plugins for details. (V9.0)

HWPLUG_CAPS_FONT

Plugin provides a loader for additional font formats. See Font plugins for details. (V10.0)

HWPLUG_CAPS_FILESYSADAPTER

Plugin replaces Hollywood's inbuilt filesystem handler. See Filesystem adapter plugins for details. (V10.0)

You have to implement all functions for every capability bit you set in CapsMask otherwise Hollywood will fail to load your plugin.

Version:

Set this to the current version of your plugin.

Revision:

Set this to the current revision of your plugin.

hwVersion:

This contains the Hollywood version that has just opened your plugin. You should store this value somewhere because you might need it later to check whether a certain feature is available in this Hollywood version or not. After that, set this member to the minimum Hollywood version required by your plugin.

hwRevision:

This contains the Hollywood revision that has just opened your plugin. You should store this value somewhere because you might need it later to check whether a certain feature is available in this Hollywood revision or not. After that, set this to the minimum Hollywood revision required by your plugin.

Name:

Set this to a string describing the name of your plugin. This can contain spaces and need not be unique. Non-ASCII characters must be encoded as UTF-8.

ModuleName:

Set this to the module name of your plugin. The module name of your plugin must be identical to its file name minus the *.hwp extension. If file and module names do not match, Hollywood will refuse to load your plugin. This may only contain ASCII characters which are allowed in file names.

Author:

Set this to the name(s) of the plugin author(s). Non-ASCII characters must be encoded as UTF-8.

Description:

Set this to a string describing the plugin's functionality. Non-ASCII characters must be encoded as UTF-8.

Copyright:

Set this to a string containing relevant copyright information. Non-ASCII characters must be encoded as UTF-8.

URL:

Set this to a string containing a link to the plugin's website. This may be NULL.

Date:

Set this to the build date of the plugin. This may be NULL. If set, it should use the format "dd.mm.yy".

Settings:

This can be set to the full path of an external program that can be used to configure settings for your plugin. It is advised to store this program relative to your plugin's path. You can find out the full path of your plugin by looking at the third argument that is passed to InitPlugin(). This will tell you where the user has installed your plugin. If you set this member, the user will be able to launch the external program from the Hollywood GUI. If your plugin doesn't feature such a program, set this member to NULL.

HelpFile:

This can be set to the full path of a help file that acts as a user manual for the plugin. It is advised to store this help file relative to your plugin's path. You can find out the full path of your plugin by looking at the third argument that is passed to InitPlugin(). This will tell you where the user has installed your plugin. If you set this member, the user will be able to open this help file from the Hollywood GUI. If your plugin doesn't come with a help file, set this member to NULL.

Note that all string pointers you use to initialize the hwPluginBase structure must stay valid until ClosePlugin() is called.

The second parameter that is passed to InitPlugin() is a pointer to a hwPluginAPI vector which is the gateway to all plugin API functions provided by Hollywood. Plugin API functions are grouped into several different library bases like GfxBase and SysBase. Please note that this parameter can be NULL. If this is the case, your plugin should not initialize itself but just fill out the hwPluginBase structure and return True. If Hollywood passes NULL in hwPluginAPI it only wants to collect information about your plugin without actually loading it.

Important: You have to be very careful about the plugin API functions you call from your InitPlugin() implementation. This is because an older Hollywood version might have called your InitPlugin() function and if you try to call newer plugin API functions that are unavailable in the Hollywood version that has just called InitPlugin(), your plugin will crash terribly. You always have to check the hwVersion and hwRevision members of the hwPluginBase structure that is passed to your InitPlugin() function before you call any of the plugin APIs. These checks only have to be done in InitPlugin() and ClosePlugin() since they can be called by any Hollywood version. All the other functions of your plugin will only be called if the host Hollywood version matches the one you request in your InitPlugin() implementation using the hwVersion and hwRevision members. InitPlugin() and ClosePlugin(), however, may be called by any arbitrary Hollywood version and the only assumption you can make is that it will be at least Hollywood 5.0 which is calling you because 5.0 is the version that introduced the new plugin system explained here. Please take this advice very seriously because a plugin which does not cleanly work with older Hollywood versions will also crash all executables compiled by these previous Hollywood versions because they will usually also scan and load all available plugins and if there is a plugin which isn't compatible with older versions, projects compiled with older Hollywood versions will suddenly crash badly.

Additionally, InitPlugin() can also be called by Hollywood Designer. In that case you have to be careful as well, because Hollywood Designer supports only a subset of the official Hollywood plugin API so many function pointers inside hwPluginBase will be NULL and you cannot call them. That is why your InitPlugin() implementation also has to check whether it was called by Hollywood or by Hollywood Designer and act accordingly then. See Designer compatibility for details.

The third parameter contains the full path to the plugin's location on the user's hard drive. This may be useful information if you need to load files from the plugin's directory or store preferences files in the plugin's directory, etc.

InitPlugin() has to return either True or False to signal success or failure. If it returns False, ClosePlugin() won't ever be called on this plugin.

self

pointer to structure that your plugin has to fill out

cl

pointer to Hollywood's plugin API functions or NULL (see above)

path

full path to the plugin's shared library file

success

True or False indicating whether initialization was successful