Components


Introduction
The functionality of messiahAPI is broken up into logical groups called Components. Each Component handles interaction with a specific area of messiah. For example, to get information about, or to alter an object's mesh, you would use functions from the MESH Component.
All of the functions in the messiahAPI are Callbacks. Each Component has an associated header file: messiah_mesh.h for MESH, messiah_object.h for OBJECT and so on. When these headers are included into your project they will declare global function pointers for each of the Callbacks in that component. These function pointers will be declared in your Main Plugin File and extern in all other files (don't worry if you don't understand that, just follow the conventions in the docs and example projects and you could live a happy life without ever having read that last sentence).
ComponentDiagram.gif
Component Initialization
You will ask messiah for the addresses of each of the Component's functions and assign them to the global funtion pointers. messiahAPI provides several macros to help automate this process for you. The simplest scenario would be retrieving all functions at once.

_MESSIAH_PLUGIN_ALL("YourPluginName");
This macro will perform several operations including the initialization of all of the global function pointers for all Components.
You may also choose to retrieve only those functions belonging to specific Components. The safest way to do this is to use the Easy Plugin Setup Macro for the type of Module(s) you are creating. There is no harm in using more than one of these macros (as long as you pass the same name to each one). For example, suppose you were writing a plugin that contains Effect Modules and Function Modules, you could use the following macros to retrieve all of the necessary functions:

_MESSIAH_PLUGIN_EFFECTS("YourPluginName");
_MESSIAH_PLUGIN_FUNCS("YourPluginName");
I say that this is the safe way of retrieving selective components because there is a sort of hierarchy to them. For example, if you are writing an Effect Module you will need to use OBJECT, EFFECT, INTERFACE and one or both of MESH and MOTION. When you use the _MESSIAH_PLUGIN_EFFECTS() macro all of those Components will be retrieved automatically.
If you're feeling slightly adventerous you can select exactly which components you want retrieved, you will simply need to make certain that you are only calling functions from those components. You will use the API Component Retrieval Macros to flag the Components that you want. After all of the Components have been flagged then use _API_GETCOMPONENTS() to initialize the function pointers:

// Flag EFFECT, INTERFACE, OBJECT, and DATA for retrieval
_API_EFFECT;
_API_INTERFACE;
_API_OBJECT;
_API_DATA;

// Initialize function pointers for flagged components
_API_GETCOMPONENTS;
Note:
If you do use this method as opposed to the Easy Plugin Setup Macro method, you will need to manually check for version and program compatibility (see messiah_plugin.h for more info).
There will be times when you will want to manually retrieve individual function addresses. Generally this will only be when those functions have been published by another plugin. For more information on this see Publishing Function Modules.
Header Files
The only header file that you need to include directly is messiah_main.h. Prior to including that file however you will need to define various symbols indicating which Components you will be using. To include all Components' header files you would use the following:

#define _MESSIAH_FULL_API
#include <messiah_main.h>
A list of symbols is provided in messiah_main.h to allow for selective inclusion of Component's header files.
Common Errors
Since a Component's function pointers are declared in its header file, you will get a compile time error if you attempt to retrieve a Component without including its header (the compiler will complain that all of the function pointers are undefined). That make this an easy problem to identify and fix, simply define the correct symbol before including messiah_main.h (see the docs for messiah_main.h for a list of those symbols).
If you include the header of a Component and make calls through its function pointers but failed to initialize them, you will get an access violation and the program will crash. The easiest way to determine if this is the case is to debug the plugin to the point that it's crashing, if its at a call to messiah then check to make sure that the function pointer being called is not NULL. If it is then there was never an attempt to retrieve the Component. If there had been, and one of the functions was not found in a Component, then your plugin would fail to load (returning FX_PLUGIN_BADAPIFUNC() to messiah). Make sure you are using the appropriate macro(s) to retrieve the Components (see above).
Components
Here is a list of all Components and a brief description of their uses. Each one has its own documentation under Reference, and in some cases supplemental documentation under Concepts. It is advisable to review the material under Concepts before proceeding to the Reference section.


© 2003 pmG WorldWide, LLC.


www.projectmessiah.com

groups.yahoo.com/pmGmessiah

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