messiah_effect.h


Provides Effect Module related information and manipulation.

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


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_EFFECTSCAN(f, dt, ed)
 Used to declare/define a scan_func() which iterates over an effect's targets.


Callback Functions

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

FXintf scan_func (FXeffect effect, FXtool tool, FXobject target, FXvoid *ed)
 User implemented effect target Enumeration Callback.


Effects Functions

These functions are used to get an effect's targets and tool. You can manually iterate over all of an effect's targets using the fxEffectTargetFirst() and fxEffectTargetNext() functions, or you can provide a callback to fxEffectTargetScan() and have messiah call this scan_func() once for each target attached to your effect.


FXeffect fxEffectCreate (FXchar *effect_type, FXchar *effect_name, FXobject target, FXint flags)
 Used to create a new instance of an effect in a messiah scene.

FXint fxEffectTargetScan (FXeffect effect, FXint(*scan_func)(FXeffect, FXtool, FXobject, FXvoid *), FXvoid *data, FXint flags)
 Specifies a scan_func() to be called once for each attached target.

FXtool fxEffectTool (FXeffect effect, FXint flags)
 Get the effect's tool.

FXobject fxEffectTargetFirst (FXeffect effect, FXint flags)
 Get the effect's first target.

FXobject fxEffectTargetNext (FXeffect effect, FXobject currentID, FXint flags)
 Get the effect's next target, given an existing one.


Initialization Functions

These functions are used to initialize some of the properties of an effect module. You should call these functions when handling the S_INIT_MODULE AN message only.


FXint fxInitEffectManipulator (FXchar *manipulator, FXint flags)
 Set the way your effect will be displayed in messiah's world view.

FXint fxInitEffectColor (FXubyte red, FXubyte green, FXubyte blue)
 Set the color of your effect.

FXint fxInitEffectTool (FXchar *tool_name, FXint flags)
 Sets the tool that your effect will use.


Define Documentation

#define FX_EFFECTSCAN f,
dt,
ed   
 

Used to declare/define a scan_func() which iterates over an effect's targets.

Expands to:
FXintf f(FXeffect effect, FXtool tool, FXobject target, dt *ed)
Parameters:
f Name of the callback
dt Data type of the "data" passed to the scan_func()
ed name of the "data" variable passed to scan_func()
Use this macro to create the signature of your scan_func() callback function. The scan_func() is used to iterate over all targets of an effect and to apply the results of that effect to them.
See also:
scan_func()


Function Documentation

FXeffect fxEffectCreate FXchar   effect_type,
FXchar   effect_name,
FXobject    target,
FXint    flags
 

Used to create a new instance of an effect in a messiah scene.

Parameters:
effect_type [in] name of the effect type (e.g. "BoneDeform")
effect_name [in] name of the effect instance object
target [in] object this effect will be targeted to
flags [in] Reserved for furure use
Return values:
FXeffect ID of the created effect upon success
FX_NULLID on failure
Use this function when you need to add an instance of an effect to a messiah scene. You must supply the name of the effect type such as BoneDeform or FlexMotion. You will also need to supply a name for the instance which messiah will validate and make unique. Finally you will need to supply the object to which this effect will be attached or targeted to.

FXobject fxEffectTargetFirst FXeffect    effect,
FXint    flags
 

Get the effect's first target.

Parameters:
effect [in] the effect
flags [in] Reserved for furure use
Return values:
FXobject ID of the first target attached to the effect
FX_NULLID if no targets

FXobject fxEffectTargetNext FXeffect    effect,
FXobject    currentID,
FXint    flags
 

Get the effect's next target, given an existing one.

Parameters:
effect [in] the effect
currentID [in] current target
flags [in] Reserved for furure use
Return values:
FXobject ID of the next target attached to the effect after currentID
FX_NULLID if no targets

FXint fxEffectTargetScan FXeffect    effect,
FXint(*    scan_func)(FXeffect, FXtool, FXobject, FXvoid *),
FXvoid   data,
FXint    flags
 

Specifies a scan_func() to be called once for each attached target.

Parameters:
effect [in] the effect who's targets you want to iterate over
scan_func [in] the scan_func() you want messiah to call
data [in] arbitrary data that you would like passed to your scan_func()
flags [in] Reserved for furure use
Return values:
FX_TRUE for success
FX_FALSE for failure
This function causes your specified scan_func() to be called once for each target attached to the effect. This is usually done when handling ACCESS_PROCESS() AN messages.
The pointer you pass as data will be passed as the ed parameter of your scan_func().
See also:
FIX ME for more info.

FXtool fxEffectTool FXeffect    effect,
FXint    flags
 

Get the effect's tool.

Parameters:
effect [in] the effect
flags [in] Reserved for furure use
Return values:
FXtool used by the effect
FX_NULLID on error

FXint fxInitEffectColor FXubyte    red,
FXubyte    green,
FXubyte    blue
 

Set the color of your effect.

Parameters:
red [in] red component
green [in] green component
blue [in] blue component
Return values:
FX_TRUE on success
FX_FALSE on failure
You effect will be displayed in messiah's item list with a diamond icon next to it. The color of that icon is determined by this function, to help the user distinguish between the different effects in their scene you should give your effect a unique color.

FXint fxInitEffectManipulator FXchar   manipulator,
FXint    flags
 

Set the way your effect will be displayed in messiah's world view.

Parameters:
manipulator [in] manipulator type
flags [in] Reserved for furure use
Return values:
FX_TRUE on success
FX_FALSE on failure
Currently you can choose to display your effect as either an Edit Sphere or a Slider depending on your needs. The value of manipulator should be one of the Manipulator Type Macros found in OBJECT.

FXint fxInitEffectTool FXchar   tool_name,
FXint    flags
 

Sets the tool that your effect will use.

Parameters:
tool_name [in] the type of tool used by your effect
flags [in] Reserved for furure use
Return values:
FX_TRUE on success
FX_FALSE on failure
All effects must have an associated tool. When an instance of your effect is created it will be parented to this tool. You can choose from Tool Type Macros for the value of tool_name.

FXintf scan_func FXeffect    effect,
FXtool    tool,
FXobject    target,
FXvoid   ed
 

User implemented effect target Enumeration Callback.

Parameters:
effect [in] effect who's targets are being iterated
tool [in] the tool used by the effect
target [in] the current target in the iteration process
ed [in] the data passed to fxEffectTargetScan() as data
Return values:
FX_TRUE on success
FX_FALSE on failure
scan_func() is just a name that we are giving to any callback function that you define using the FX_EFFECTSCAN() macro. You use this callback by passing it to fxEffectTargetScan(), your callback will then be called one time for each of the effect's targets. This is how you will make sure that your effect is applied to all of its targets.
See also:
Target Enumeration, Enumeration Callbacks


© 2003 pmG WorldWide, LLC.


www.projectmessiah.com

groups.yahoo.com/pmGmessiah

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