Name
InitPlugin -- init plugin (V5.0)
Synopsis
int success = InitPlugin(hwPluginBase *self, hwPluginAPI *cl, STRPTR path);
Function
This function must initialize your plugin and report information about it back to Hollywood. Your InitPlugin() implementation must fill out all fields of the hwPluginBase structure that is passed to it:

 
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)

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.

Inputs
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
Results
success
True or False indicating whether initialization was successful

Show TOC