messiah_function.h


Provides messiah function (Function Module) related information and manipulation.

Version:
1.1
Date:
6/07/03
Topics
Description
See Function Modules for background information on Function Modules.


Callback Signature Macros

It is recommended that you use these Callback Signature Macros to define their associated Callbacks. This will help to shield your code from changes to messiahAPI.

#define FX_EXPFUNC(f, dt, ed)
 Used to declare/define an exp_func() which is called to execute an Function Module.


mfunc Classification Macros

These macros identify classifications for Function Modules. When registering your Function Module you should choose the classification that best describes what your Function Module does.

#define FX_FUNCCLASS_GENERAL
 General purpose function.

#define FX_FUNCCLASS_FILE
 Function relates to file IO.

#define FX_FUNCCLASS_MOTION
 Function affects object's motion.

#define FX_FUNCCLASS_IK
 Function alters IK.

#define FX_FUNCCLASS_OBJECT
 Function operates on objects.

#define FX_FUNCCLASS_TOOL
 Function operates on tools.

#define FX_FUNCCLASS_EFFECT
 Function operates on effects.

#define FX_FUNCCLASS_SHADER
 Function operates on shaders.

#define FX_FUNCCLASS_SETUP
 Function should be used in Setup mode.

#define FX_FUNCCLASS_RENDER
 Function should be used in Render mode.

#define FX_FUNCCLASS_PLAY
 Function should be used in Play mode.

#define FX_FUNCCLASS_COMMAND
 Function should be used in Command mode.

#define FX_FUNCCLASS_COMPOSE
 Function should be used in Compose mode.

#define FX_FUNCCLASS_INTERFACE
 Function affects GUI.

#define FX_FUNCCLASS_ARMATURE
 Function operates on Armatures.


Return Codes

Return these codes from your exp_func().

#define FX_FUNC_OK
 Function Module operation was successful

#define FX_FUNC_FAIL
 Function Module failed


Callback Functions

The following are Callbacks that you will create and send to messiah. See Callback Types for information.

FXintf exp_func (FX_Arg *return_arg, FXvoid *arg_data)
 Function Module callback function


mfunc Registration Functions



FXint fxFunctionRegister (FXchar *name, FXchar *func_class, FXint(*exp)(FX_Arg *, FXvoid *), FXvoid *func, FXint return_type, FXint flags)
 Function Module registration function

FXint fxFunctionDescription (FXchar *desc, FXint flags)
 Provides a description of a Function Module prior to it's registration.


mfunc Argument Initialization Functions

Parameters:
name [in] Name of the argument
abbr [in] Abbreviated name of the argument
def[#] [in] Default value for the argument (multiple for compound arguments like vectors)
def_command [in] Alternate default value, command will be evaluated on demand
flags [in] Reserved for future use
Note:
The abbr parameter has no affect in version 1.1, however you should still pass an abbreviated name so that you will not need to adjust your code in the future.
Description
These functions describe the arguments that your Function Module will accept, you must use them to set up the arguments prior to registering the Function Module. The order in which you call these function will determine the order of the arguments in your Function Module signature.
Warning:
The order of your arguments must match the order of the elements in your argument structure, failure to do so will result in a crash!
For example, to register an Function Module that looks like:

FXint MyFunc( FXint val1(v1) = 2, FXdouble val2(v2) = 3.14159 );
you would use the following code:

// Argument Structure
typedef struct
{
        FXint           val1;
        FXdouble        val2;
}MyArgStruct;

fxFunctionArgInt( "val1", "v1", 2, NULL, FX_NOFLAG );
fxFunctionArgDouble( "val2", "v2", 3.14159, NULL, FX_NOFLAG );
fxFunctionRegister( ... );
Notice that "val1" is registered first, followed by "val2", and that this matches the order of the elements in the argument structure.
The function fxFunctionArgStringList() takes an FXchar** as it's def parameter. It is vital that the last element in this array is NULL, so that messiah knows when it has reached the end of the list. Failure to do so will result in a crash.

FXchar * string_list[] = { "string_1", "string_2", "...", "string_n", NULL };
See also:
Function Modules


FXint fxFunctionArgInt (FXchar *name, FXchar *abbr, FXint def, FXchar *def_command, FXint flags)
 Declare an int argument.

FXint fxFunctionArgDouble (FXchar *name, FXchar *abbr, FXdouble def, FXchar *def_command, FXint flags)
 Declare an double argument.

FXint fxFunctionArgFloat (FXchar *name, FXchar *abbr, FXfloat def, FXchar *def_command, FXint flags)
 Declare an float argument.

FXint fxFunctionArgInt3 (FXchar *name, FXchar *abbr, FXint def1, FXint def2, FXint def3, FXchar *def_command, FXint flags)
 Declare an int[3] argument.

FXint fxFunctionArgDouble3 (FXchar *name, FXchar *abbr, FXdouble def1, FXdouble def2, FXdouble def3, FXchar *def_command, FXint flags)
 Declare an double[3] argument.

FXint fxFunctionArgFloat3 (FXchar *name, FXchar *abbr, FXfloat def1, FXfloat def2, FXfloat def3, FXchar *def_command, FXint flags)
 Declare an float[3] argument.

FXint fxFunctionArgInt4 (FXchar *name, FXchar *abbr, FXint def1, FXint def2, FXint def3, FXint def4, FXchar *def_command, FXint flags)
 Declare an int[4] argument.

FXint fxFunctionArgDouble4 (FXchar *name, FXchar *abbr, FXdouble def1, FXdouble def2, FXdouble def3, FXdouble def4, FXchar *def_command, FXint flags)
 Declare an double[4] argument.

FXint fxFunctionArgFloat4 (FXchar *name, FXchar *abbr, FXfloat def1, FXfloat def2, FXfloat def3, FXfloat def4, FXchar *def_command, FXint flags)
 Declare an float[4] argument.

FXint fxFunctionArgChar (FXchar *name, FXchar *abbr, FXchar def, FXchar *def_command, FXint flags)
 Declare an char argument.

FXint fxFunctionArgString (FXchar *name, FXchar *abbr, FXchar *def, FXchar *def_command, FXint flags)
 Declare an char * argument.

FXint fxFunctionArgStringList (FXchar *name, FXchar *abbr, FXchar **def, FXchar *def_command, FXint flags)
 Declare an char ** argument.

FXint fxFunctionArgVoid (FXchar *name, FXchar *abbr, FXvoid *def, FXchar *def_command, FXint flags)
 Declare an void * argument.

FXint fxFunctionArgDP (FXchar *name, FXchar *abbr, FXvoid **def, FXchar *def_command, FXint flags)
 Declare an void ** argument.

FXint fxFunctionArgObj (FXchar *name, FXchar *abbr, FXobject def, FXchar *def_command, FXint flags)
 Declare an FXobject argument.


Defines

#define FX_FUNC_SCRIPTSONLY
 Script and command line only execution flag.


Define Documentation

#define FX_EXPFUNC f,
dt,
ed   
 

Used to declare/define an exp_func() which is called to execute an Function Module.

Expands to:
FXintf f(FX_Arg *return_arg, dt *ed)
Parameters:
f Name of the callback
dt Data type of the "data" passed to the exp_func()
ed name of the "data" variable passed to exp_func()
Use this macro to create the signature of your exp_func() callback function.
See also:
exp_func()

#define FX_FUNC_SCRIPTSONLY
 

Script and command line only execution flag.

Pass this flag to fxFunctionRegister() to signal to messiah that the Function Module you are registering is only to be called from scripts or the command line. Typically this is desirable for Function Modules that perform some action that is only meant to occur when the user explicitly calls for it.


Function Documentation

FXintf exp_func FX_Arg   return_arg,
FXvoid   arg_data
 

Function Module callback function

Parameters:
return_arg [in] Return value of the Function Module
arg_data [in] Pointer to an argument structure (type will be determined by dt param of FX_EXPFUNC() )
Return values:
FX_FUNC_OK on success
FX_FUNC_FAIL on failure
exp_func() is just a name that we are giving to any callback function declared with FX_EXPFUNC(). This function will be called whenever messiah needs to execute your Function Module.
mfunc Return Value
The return_arg parameter contains one element at index 0, you will use one of the Argument "Set" Functions ( fxArgSet* ) to set this element to the return value of the Function Module. For example, if the Function Module was supposed to return an FXint, then you would set it like so:

FXint returnValue = 5;  // in this case it would return 5

fxArgSetInt( return_arg, NULL, 0, returnValue );
Arguments
The arguments that the user passed to your Function Module are passed to the exp_func() as arg_data. This is a pointer to a structure that you defined to hold the arguments. The order of the elements in this structure must match the order in which the Argument Initialization Functions( fxFunctionArg* ) were called.
For example, to register an Function Module that looks like:

FXint MyFunc( FXint val1(v1) = 2, FXdouble val2(v2) = 3.14159 );
you would use the following code:

// Argument Structure
typedef struct
{
        FXint           val1;
        FXdouble        val2;
}MyArgStruct;

fxFunctionArgInt( "val1", "v1", 2, NULL, FX_NOFLAG );
fxFunctionArgDouble( "val2", "v2", 3.14159, NULL, FX_NOFLAG );
fxFunctionRegister( ... );
Notice that "val1" is registered first, followed by "val2", and that this matches the order of the elements in the argument structure.
You would then access these arguments in your exp_func() as:

FXint           the_first_argument      = arg_data->val1;
FXdouble        the_second_arguement    = arg_data->val2.
See also:
Function Modules

FXint fxFunctionDescription FXchar   desc,
FXint    flags
 

Provides a description of a Function Module prior to it's registration.

Parameters:
desc [in] Function description
flags [in] Reserved for furure use
Return values:
FX_TRUE on success
FX_FALSE on failure

FXint fxFunctionRegister FXchar   name,
FXchar   func_class,
FXint(*    exp)(FX_Arg *, FXvoid *),
FXvoid   func,
FXint    return_type,
FXint    flags
 

Function Module registration function

Parameters:
name [in] name of the Function Module as it will appear to the user
func_class [in] classification for this Function Module, one of: Function Classifications
exp [in] optional address of the exp_func()
func [in] optional address of the published Function Module (to other plugins)
return_type [in] return type of the Function Module, one of: Argument Data Types
flags [in] Reserved for furure use
Return values:
FX_TRUE on success
FX_FALSE on failure
Since Function Modules are a different type of module than the others, you use a differnt function to register them. Noticably absent from this function is the address of an AN event handler, this is because Function Modules cannot respond to AN messages.
Prior to calling this function you must have described the arguments that this Function Module will accept. You must also have defined a structure whose element order matches that of the argument declaraction.
You will pass at least one of two function pointers to this function. The pointer exp is the function messiah will call whenever the user calls your Function Module. You must provide this pointer or fxFunctionRegister() will fail. The pointer func is the function other plugins will call whenever they want to use your Function Module. If you do not supply an address (i.e. pass NULL) then your Function Module will not be published for use by other plugins.
If you require your Function Module to be called from the command line or scripts only, you can pass FX_FUNC_SCRIPTSONLY as the flags parameter.
See also:
Function Modules


© 2003 pmG WorldWide, LLC.


www.projectmessiah.com

groups.yahoo.com/pmGmessiah

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