messiah_plugin.h


Provides functionality needed by all plugins.

Version:
1.1
Date:
6/07/03
Topics
Description
This header provides you with the functionality you'll need to create an empty plugin. The signatures of your plugin's entry and exit points are defined here as messiahEntry() and messiahExit() respectively. There are also a number of macros that can be used to set up your plugin. These macros will help you check version and program compatibility, request and verify retrieval of specific API components, as well as identifying your plugin to messiah.


Entry Point Macros

The following symbols must be exported by your plugin. The symbol messiahVersion() is already implemented for you so there's nothing you need to do there. The messiahEntry() and messiahExit() symbols however are only declared, you must define them. It is recommended that you use the _pluginEntry and _pluginExit macros instead of the messiahEntry() and messiahExit() function signatures directly, this will keep your code safe from many API modifications.

#define _pluginEntry
 Macro used in place of messiahEntry() signature.

#define _pluginExit
 Macro used in place of messiahExit() signature.

FXint messiahEntry (FXchar pname[256], FXvoid *api_func, FXint api, FXint program, const FXchar *rev)
 User Implemented entry point for your plugin.

FXvoid messiahExit (FXvoid)
 User Implemented exit point for your plugin.


Return Codes

Return these codes from your messiahEntry() function to indicate success or failure of the loading process.

#define FX_PLUGIN_OK
 Everything proceeded according to plan.

#define FX_PLUGIN_BADAPI
 The api versions were incompatible.

#define FX_PLUGIN_BADPROGRAM
 The plugin was written for a different program (e.g. messiah:animate, messiah:studio).

#define FX_PLUGIN_BADAPIFUNC
 One or more API functions was not retrieved successfully.

#define FX_PLUGIN_BADREVISION
 The plugin is not compatible with the revision of the program.

#define FX_PLUGIN_BADAPIREV
 The plugin is not compatible with the revistion of the API.

#define FX_PLUGIN_BADVERSION
 The plugin is not compatible with the version of the program.

#define FX_PLUGIN_BADBUILD
 The plugin is not compatible with the build of the program.


Easy Plugin Setup Macros

It is highly recomended that you use these Easy Plugin Setup Macros to do all of the setup for your plugin. Using these macros you can ignore almost everything else in this header file (entry/exit points excepted). If you want the easiest possible way to setup your plugin's entry point here it is:
_pluginEntry
{
        _MESSIAH_PLUGIN_ALL("PluginName");

        // register your modules here

        return FX_PLUGIN_OK;
}
That's all there is to it. See Concepts - Plugin Entry/Exit for more information.

#define _MESSIAH_PLUGIN_ANIMATE(n)
 Sets up your plugin for use with messiah:animate.

#define _MESSIAH_PLUGIN_STUDIO(n)
 Sets up your plugin for use with messiah:studio.

#define _MESSIAH_PLUGIN_FUNCS(n)
 Sets up your plugin for creating messiah function modules.

#define _MESSIAH_PLUGIN_COMMANDS(n)
 Sets up your plugin for creating messiah command modules.

#define _MESSIAH_PLUGIN_EFFECTS(n)
 Sets up your plugin for creating messiah effect modules.

#define _MESSIAH_PLUGIN_SHADERS(n)
 Sets up your plugin for creating messiah shader modules.

#define _MESSIAH_PLUGIN_ALL(n)
 Sets up your plugin for creating any messiah module.


Plugin Entry Point Setup Macros

If you choose not to use the _MESSIAH_PLUGIN_* macros to setup your plugin you can use these macros to help you with some of the initial setup. You will also need to use the API Component Request and Retrieval Macros (described next) to get the appropriate API components for your project.

#define _API_CHECKVERSION(v)
 Verifies that this plugin is compatible with the version of messiah that is loading it.

#define _API_CHECKREV(v)
 Verifies that this plugin is compatible with the specified revision.

#define _API_CHECKPROGRAM(p)
 Verifies that this plugin is compatible with the program that is loading it.

#define _API_GETAPIFUNC
 Sets your fxGetAPIFunc variable.

#define _API_PLUGIN_NAME(n)
 Tells messiah the name of your plugin, and stores a global copy in plugin_name.


API Component Retrieval Macros

If you choose not to use the provided _MESSIAH_PLUGIN_* macros to handle your plugin setup you can use the following macros to help you retrieve the API components you need.

#define _API_OBJECT
 Flag the OBJECT component to be retrieved.

#define _API_MESH
 Flag the MESH component to be retrieved.

#define _API_MOTION
 Flag the MOTION component to be retrieved.

#define _API_INTERFACE
 Flag the GUI component to be retrieved.

#define _API_EFFECT
 Flag the EFFECT component to be retrieved.

#define _API_SHADER
 Flag the SHADER component to be retrieved.

#define _API_IMAGE
 Flag the IMAGE component to be retrieved.

#define _API_FUNCTION
 Flag the FUNCTION component to be retrieved.

#define _API_COMMAND
 Flag the COMMAND component to be retrieved.

#define _API_MESSAGE
 Flag the MESSAGE component to be retrieved.

#define _API_ARG
 Flag the ARG component to be retrieved.

#define _API_DATA
 Flag the DATA component to be retrieved.

#define _API_FILE
 Flag the FILE component to be retrieved.

#define _API_STRING
 Flag the STRING component to be retrieved.

#define _API_TIME
 Flag the TIME component to be retrieved.

#define _API_MODULE
 Flag the MODULE component to be retrieved.

#define _API_EXPFUNC
 Flag the EXPFUNC component to be retrieved.

#define _API_VARIABLE
 Flag the VARIABLE component to be retrieved.

#define _API_GROUP
 Flag the GROUP component to be retrieved.

#define _API_ARMATURE
 Flag the ARMATURE component to be retrieved.

#define _API_ACTION
 Flag the ACTION component to be retrieved.

#define _API_ALL
 Flag all components to be retrieved.

#define _API_GETCOMPONENTS
 Retrieves all API components that you have flagged to be retrieved with the previous _API_* macros.


Variables

FXchar plugin_name [256]
 The name of your plugin.


Define Documentation

#define _API_CHECKPROGRAM  
 

Verifies that this plugin is compatible with the program that is loading it.

For example, if this plugin contains a shader module it would be inapropriate to attempt to load it in messiah:animate. If the programs are incompatible then your messiahEntry will return FX_PLUGIN_BADPROGRAM.

#define _API_CHECKREV  
 

Verifies that this plugin is compatible with the specified revision.

You should always pass this macro _MESSIAH_API_REV. If the plugin is not compatible with the revision of the program loading it the your messiahEntry() will return with FX_PLUGIN_BADAPIREV.

#define _API_CHECKVERSION  
 

Verifies that this plugin is compatible with the version of messiah that is loading it.

You should always pass this macro _MESSIAH_API_VERSION. If the versions are incompatible then your messiahEntry() will exit with FX_PLUGIN_BADAPI.

#define _API_GETAPIFUNC
 

Sets your fxGetAPIFunc variable.

If you use the macros provided by the messiahAPI then chances are slim that you will directly interact with the fxGetAPIFunc variable. Nevertheless this API function, provided by messiah, is the heart of the system. Through this callback you retrieve the addresses of all of the API functions you call. A messiahEntry() is not complete without assigning the fxGetAPIFunc so make sure that you either use this macro or assign fxGetAPIFunc directly from the api_func passed to messiahEntry().

#define _API_GETCOMPONENTS
 

Retrieves all API components that you have flagged to be retrieved with the previous _API_* macros.

You must have previously used one of the _MESSIAH_PLUGIN_* macros, _API_GETAPIFUNC, or directly set fxGetAPIFunc to api_func before using this macro; failure to do so will result in enexpected behavior (actually it's quite expected that it will crash). Example:

This will flag the OBJECT and MESH components to be retrieved, then _API_GETCOMPONENTS will actually retrieve those flagged components.

#define _API_PLUGIN_NAME  
 

Tells messiah the name of your plugin, and stores a global copy in plugin_name.

The variable pname is an argument to messiahEntry(), upon returning messiah will use this to identify your plugin. You will refer to your plugin's name through the global variable plugin_name (declared in this file).

#define _MESSIAH_PLUGIN_ALL  
 

Sets up your plugin for creating any messiah module.

Parameters:
n The name of your plugin
Retrieves all API components.

#define _MESSIAH_PLUGIN_ANIMATE  
 

Sets up your plugin for use with messiah:animate.

Parameters:
n The name of your plugin
Retrieves the MESSAGE, MODULE and ARG API components.

#define _MESSIAH_PLUGIN_COMMANDS  
 

Sets up your plugin for creating messiah command modules.

Parameters:
n The name of your plugin
Retrieves the MESSAGE and COMMAND API components.

#define _MESSIAH_PLUGIN_EFFECTS  
 

Sets up your plugin for creating messiah effect modules.

Parameters:
n The name of your plugin
Retrieves the EFFECT, OBJECT, MESH, MOTION and INTERFACE API components.

#define _MESSIAH_PLUGIN_FUNCS  
 

Sets up your plugin for creating messiah function modules.

Parameters:
n The name of your plugin
Retrieves the MESSAGE, FUNCTION and ARG API components.

#define _MESSIAH_PLUGIN_SHADERS  
 

Sets up your plugin for creating messiah shader modules.

Parameters:
n The name of your plugin
Retrieves the SHADER, OBJECT, MESH, MOTION and INTERFACE API components.

#define _MESSIAH_PLUGIN_STUDIO  
 

Sets up your plugin for use with messiah:studio.

Parameters:
n The name of your plugin
Retrieves the MESSAGE, MODULE and ARG API components.

#define _pluginEntry
 

Macro used in place of messiahEntry() signature.

You will want to use this macro over the signature of the messiahEntry() function directly for compatibility reasons. Your plugin's entry point function will probably look something like this:

_pluginEntry
// _MESSIAH_EXPORT FXint messiahEntry(FXchar pname[256], FXvoid *global_func, FXint api, FXint program, const FXchar *rev)
{
        //...
        return FX_PLUGIN_OK;
}

You may or may not want to include the commented out messiahEntry() signature after _pluginEntry as I have done here. It's there only so you have a quick reference to the function's arguments.

#define _pluginExit
 

Macro used in place of messiahExit() signature.

You will want to use this macro over the signature of the messiahExit() function directly for compatibility reasons.


Function Documentation

FXint messiahEntry FXchar    pname[256],
FXvoid   global_func,
FXint    api,
FXint    program,
const FXchar   rev
 

User Implemented entry point for your plugin.

Parameters:
pname Copy your plugin's name to this variable, typically via the _API_PLUGIN_NAME or _MESSIAH_PLUGIN_* macros.
api_func API function through which you retrieve the addresses of all other API functions. Use the _API_GETAPIFUNC macro to store this in the global variable fxGetAPIFunc.
api API version of messiah.
program The program that loaded this plugin (i.e. _MESSIAH_PROGRAM_ANIMATE, _MESSIAH_PROGRAM_STUDIO)
rev String indicating the revision of messiah.
Return values:
FX_PLUGIN_OK Return this value if everything went smoothly and your plugin loaded fine.
FX_PLUGIN_BADAPI Return this value if the value of api was lower than _MESSIAH_API_VERSION. This is done automatically through the _API_VERSION() macro.
FX_PLUGIN_BADPROGRAM Return this if the value of program does not match your targeted program (animte, studio etc.) This is done automatically through the _API_PROGRAM() macro.
FX_PLUGIN_BADAPIFUNC Return this if you have any problems retrieving any messiahAPI functions through fxGetAPIFunc() This is done automatically through the _API_GETCOMPONENTS() macro.
FX_PLUGIN_BADREVISION Return this if your plugin does not work with a given revision.
Comments
You must provide the implementation (i.e. function body) for this function in your plugin. It is highly recomended that you use the _pluginEntry() macro instead of using this funciton signature directly. For information regarding what actions you need to take in your messiahEntry() function see __doc_plugin_entry_point__.

FXvoid messiahExit FXvoid   
 

User Implemented exit point for your plugin.

You must provide the implementation (i.e. function body) for this function in your plugin. It is highly recomended that you use the _pluginExit() macro instead of using this funciton signature directly. For information regarding what actions you need to take in your messiahExit() function see __doc_plugin_entry_point__.


Variable Documentation

FXchar plugin_name[256]
 

The name of your plugin.

You identify your plugin by name with messiah by filling in the pname argument passed to your entry point, you maintain a copy of that name in this global variable. This will be handled for you by the _API_PLUGIN_NAME() macro, or indirectly through one of the _MESSIAH_PLUGIN_* macros.


© 2003 pmG WorldWide, LLC.


www.projectmessiah.com

groups.yahoo.com/pmGmessiah

Last Updated on Thu Jul 10 04:49:37 2003