messiah_access.h


Provides Access Notification related information.

Version:
1.1
Date:
6/07/03
Topics
Description
While Components are the way you tell messiah to do something, Access Notification (AN) is the way messiah tells you to do something. See Access Notification for details related to informing messiah about the AN messages you are interested in recieving, as well as how to handle those messages (by creating access_func()'s) once messiah sends them.


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_ACCESSFUNC(f)
 Used to declare/define an access_func() which is a AN message handler.

#define FX_ENTRYFUNC(f)
 Used to declare/define an entry_func() which is an AL specific AN message handler.


Return Codes

Return these values from your access_func() or entry_func()

#define ENTRY_BREAK
 Break from access_func(), no more AN's will be sent.

#define ENTRY_REPLACE
 Break from access_func(), no more AN's will be sent.

#define ENTRY_CONTINUE
 Return successfully from access_func().

#define ENTRY_OK
 Return successfully from access_func().

#define BREAK_ENTRY
 Break from access_func(), no more AN's will be sent.

#define REPLACE_ENTRY
 Break from access_func(), no more AN's will be sent.

#define CONTINUE_ENTRY
 Return successfully from access_func().

#define OK_ENTRY
 Return successfully from access_func().


Access Levels

Access Levels (AL) represent groupings of related Access Notifications (AN). You inform messiah about which AN messages you are interested in by calling fxModuleAccess() prior to registering your module. You will need to specify the AL as well as which AN messages you are interested in.

#define ACCESS_PROCESS
 Animation processing stage notifications, SEE LIST.

#define ACCESS_OBJECT
 Object related notifications, SEE LIST.

#define ACCESS_EFFECT
 Effect related notifications, SEE LIST.

#define ACCESS_ARMATURE
 Armature related notifications, SEE LIST.

#define ACCESS_ACTION
 Action related notifications, SEE LIST.

#define ACCESS_INTERFACE
 GUI related notifications, SEE LIST.

#define ACCESS_SYSTEM
 Module related notifications, SEE LIST.

#define ACCESS_GENERAL
 General notifications, SEE LIST.


ACCESS_ARMATURE

These are notifications relating to messiah's Armature system and its related handles.

#define ARM_CREATE
 A new armature has been created.

#define ARM_DESTROY
 Armature is about to be destoryed.

#define ARM_COPY
 Armature is being copied.

#define ARM_RENAME
 Armature has been renamed.

#define ARM_SELECT
 Armature has been selected.

#define ARM_HANDLE_CREATE
 A new handle has been created.

#define ARM_HANDLE_DESTROY
 Handle is about to be destroyed.

#define ARM_HANDLE_COPY
 Handle has been copied.

#define ARM_HANDLE_RENAME
 Handle has been renamed.

#define ARM_HANDLE_SELECT
 Handle has been selected (single click).

#define ARM_HANDLE_DRAG
 Handle is being dragged.

#define ARM_HANDLE_DOUBLECLICK
 Handle has been double clicked.


ACCESS_ACTION

These are notifications relating to Action.

#define ACT_CREATE
 Action has been created.

#define ACT_DESTROY
 Action has been destroyed.

#define ACT_COPY
 Action has been copied.

#define ACT_RENAME
 Action has been renamed.

#define ACT_SELECT
 Action has been selected.

#define ACT_SAVE
#define ACT_LOAD
#define ACT_PROCESS
 Process the action (i.e. execution of the action).

#define ACT_ALL
 Flag passed to fxModuleAccess() to request all ACCESS_ACTION() AN messages.


ACCESS_PROCESS

Whenever the time changes messiah must go through several stages of processing in order to update the items in the scene. It might be necessary for your module to perform an action only at a specific stage in that processing. For example if your module is a motion effect, you might want to be notified when IK has already been computed. In that case you would respond to the P_POST_IK() AN.

#define P_PRE_MOTION
 Notification that messiah is processing before keyframe animation has been taken into account.

#define P_POST_MOTION
 Notification that messiah is processing after keygrame animation has been taken into account.

#define P_PRE_IK
 Notification that messiah is processing before inverse kinematics has been taken into account.

#define P_POST_IK
 Notification that messiah is processing after inverse kinematics has been taken into account.

#define P_PRE_POINT_DISPLACE
 Notification that messiah is processing before point displacement has taken place.

#define P_POST_POINT_DISPLACE
 Notification that messiah is processing after point displacement has taken place.

#define P_DONE
 Notification that all processing is done.

#define P_ALL
 Flag passed to fxModuleAccess() to request all ACCESS_PROCESS() AN messages.


ACCESS_OBJECT

These are notifications relating to FXobject based items (meshes, tools, effects etc.). These AN messages are sent differently depending on the type of module that requested them. If the module is object-based, such as a Shader or Effect Module then these AN messages will only be sent in reference to instances of that object-based module. If the module is not object-based, like a Customize Module, then it will recieve these AN messages for all objects.

#define O_CREATE
 Object has been created.

#define O_INIT
 NOT CURRENTLY SUPPORTED.

#define O_DESTROY
 Object is being destroyed.

#define O_COPY
 Object is being coppied.

#define O_RENAME
 Object is being renamed.

#define O_DESTROY_PRE
 Object is about to be destroyed.

#define O_COPY_PRE
 Object is about to be copied.

#define O_RENAME_PRE
 Object is about to be renamed.

#define O_DESTROY_POST
 Object has been destoryed - object-based modules will not recieve this message.

#define O_COPY_POST
 Object has been copied.

#define O_RENAME_POST
 Object has been renamed.

#define O_LOAD
 Load data for object from FX_AccessInfo *ai.

#define O_SAVE
 Save data for object to FX_AccessInfo *ai.

#define O_REPLACE
 Object has been replaced - ID will remain the same.

#define O_SELECT_PRE
 Object is about to be selected.

#define O_SELECT_POST
 Object has been selected.

#define O_DESELECT_PRE
 Object is about to be deselected.

#define O_DESELECT_POST
 Object has been deselected.

#define O_SELECT_CHANNEL
 Object's active channel has changed.

#define O_ENTER_SETUP
 Object has entered Setup mode.

#define O_EXIT_SETUP
 Object has left Setup mode.

#define O_MODIFY_REST_PRE
 Rest values (Setup) are about to be modified.

#define O_MODIFY_REST_POST
 Rest values (Setup) have been modified.

#define O_REPLACE_PRE
 Object is about to be replaced.

#define O_EDIT_PARAM
 NOT CURRENTLY SUPPORTED.

#define O_ALL
 Flag passed to fxModuleAccess() to request all ACCESS_OBJECT() AN messages.


ACCESS_EFFECT

These are notifications of changes to your Effect Modules target or tool objects.

#define E_XFORM_TOOL
 Your effect's tool has been moved.

#define E_MODIFY_TOOL
 Your effect's tool has been modified in some way.

#define E_CHANGE_TOOL
 Your effect's tool has been changed.

#define E_ADD_TARGET
 A target object has been added to your effect.

#define E_DELETE_TARGET
 A target object has been deleted from your effect.

#define E_XFORM_TARGET
 One of your effect's targets has been moved.

#define E_MODIFY_TARGET
 One of your effect's targets has been modified in some way.

#define E_CHANGE_TARGET
 One of your effect's targets has been changed.

#define E_ALL
 Flag passed to fxModuleAccess() to request all ACCESS_EFFECT() AN messages.


ACCESS_INTERFACE

These are notifications of events relating to your module's interface.

#define IN_CREATE
 Your module's interface is being created.

#define IN_DESTROY
 NOT CURRENTLY SUPPORTED.

#define IN_CONFIG
 Configure the module's interface.

#define IN_ACTIVATE
 Your module's interface is about to be activated.

#define IN_DEACTIVATE
 Your module's interface is about to be deactivated.

#define IN_ACTIVATE_POST
 Your module's interface has been activated.

#define IN_DEACTIVATE_POST
 Your module's interface has been deactivated.

#define IN_ALL
 Flag passed to fxModuleAccess() to request all ACCESS_INTERFACE() AN messages.


ACCESS_SYSTEM

These are notifications of events relating to your module.

#define S_MODULE_INIT
 Initialize your module data.

#define S_MODULE_UNLOAD
 Your module is being unloaded.

#define S_ALL
 Flag passed to fxModuleAccess() to request all ACCESS_SYSTEM() AN messages.


ACCESS_GENERAL

These are notifications of events such as scene state (i.e. loading, saving etc.), config file state and other general messages.

#define GEN_GET_GLOBALS
 Load any published functions.

#define GEN_GET_INTERFACE_GLOBALS
 UNKNOWN.

#define GEN_CLEAR_SCENE_PRE
 Scene is about to be cleared.

#define GEN_CLEAR_SCENE_POST
 Scene has been cleared.

#define GEN_LOAD_SCENE_PRE
 Scene is about to be loaded.

#define GEN_LOAD_SCENE_POST
 Scene has been loaded.

#define GEN_APPEND_SCENE_PRE
 A scene is about to be appended to the current one.

#define GEN_APPEND_SCENE_POST
 A scene has been appended to the current one.

#define GEN_LOAD_SCENE
 Scene is loading.

#define GEN_SAVE_SCENE
 Scene is saving.

#define GEN_LOAD_CONFIG
 Config file is loading.

#define GEN_SAVE_CONFIG
 Config file is saving.

#define GEN_LOAD_CONFIG_POST
 Config file has loaded.

#define GEN_SAVE_CONFIG_POST
 Config file has saved.

#define GEN_ALL
 Flag passed to fxModuleAccess() to request all ACCESS_GENERAL() AN messages.


Callback Functions

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

FXintf access_func (FX_AccessInfo *ai, FXentity ID, FXint level, FXint64 entry)
 User implemented AN message handler.

FXintf entry_func (FX_AccessInfo *ai, FXentity ID, FXint64 entry)
 User implemented, AL specific, AN message handler.


Typedefs

typedef FX_Arg_St FX_Arg
 Opaque argument type, see ARG.

typedef FX_Format_St FX_Format
 File I/O FX_Arg type.

typedef FX_AccessInfo_St FX_AccessInfo
 Access Info FX_Arg type.


Define Documentation

#define FX_ACCESSFUNC  
 

Used to declare/define an access_func() which is a AN message handler.

Expands to:
FXintf f(FX_AccessInfo *ai, FXentity ID, FXint level, FXint64 entry)
Parameters:
f Name of the callback
Use this macro to create the signature of your access_func(). You will pass this callback to fxModuleRegister() to specify which function will handle Access Notification messages for this module.
See also:
access_func()

#define FX_ENTRYFUNC  
 

Used to declare/define an entry_func() which is an AL specific AN message handler.

Expands to:
FXintf f(FX_AccessInfo *ai, FXentity ID, FXint64 entry)
Parameters:
f Name of the callback
Use this macro to create the signature of your entry_func(). You delegate Access Notification messages from your access_func() to this function.
See also:
access_func()

#define GEN_LOAD_CONFIG
 

Config file is loading.

If your module has saved data to the config file, you will want to respond to this AN in order to retrieve it. You're module's data will be stored in the FX_AccessInfo *ai variable.

See also:
File IO

#define GEN_LOAD_SCENE
 

Scene is loading.

If your module has saved data to the scene file, you will want to respond to this AN in order to retrieve it. You're module's data will be stored in the FX_AccessInfo *ai variable.

See also:
File IO

#define GEN_SAVE_CONFIG
 

Config file is saving.

If your module needs to save data to the config file, you will want to respond to this AN. You will store your module's data in the FX_AccessInfo *ai variable.

See also:
File IO

#define GEN_SAVE_SCENE
 

Scene is saving.

If your module needs to save data to the scene file, you will want to respond to this AN. You will store your module's data in the FX_AccessInfo *ai variable.

See also:
File IO

#define IN_CREATE
 

Your module's interface is being created.

You must create any controls your interface will need in response to this AN. When the interface is destroyed, the controls will be automatically destroyed.

#define O_COPY
 

Object is being coppied.

If you have attached data to the object with fxObjectSetTypeData(), fxDataCreate() or fxDataSet(), then you should respond to this AN to copy that data to the new object.

#define O_CREATE
 

Object has been created.

You will probably want to store some type of data with object-based modules. You should allocate that data and then attach it using fxObjectSetTypeData() in response to this AN.

#define O_DESTROY
 

Object is being destroyed.

If you had attached allocated data to the object using fxObjectSetTypeData() then you should retrieve that data using fxObjectGetTypeData() and free it in response to this AN.

#define O_LOAD
 

Load data for object from FX_AccessInfo *ai.

See also:
File IO

#define O_SAVE
 

Save data for object to FX_AccessInfo *ai.

See also:
File IO


Function Documentation

FXintf access_func FX_AccessInfo   ai,
FXentity    ID,
FXint    level,
FXint64    entry
 

User implemented AN message handler.

Parameters:
ai [in] Access info structure
ID [in] The ID of the Entity that caused this notification to be sent
level [in] Access Level of the notification message
entry [in] Access Entry of the notification message
Return values:
ENTRY_CONTINUE on success
ENTRY_BREAK on failure
access_func() is just a name we are giving to any callback function that you create with the FX_ACCESSFUNC() macro. The access_func() acts as a handler for all Access Notification messages sent to your module. You will pass the address of this function as a callback to messiah when you register your module with fxModuleRegister().
Note:
You will only recieve AN messages that you request with fxModuleAccess()!
You determine the specific AN message by the combinarion of AL and AN, level and entry respectively. The ID of the Entity that caused this message to be sent will be passed in the ID parameter. If this access_func() belongs to an Object Based Module then you may safely cast this ID to a specific Entity type. For example, if the module were an Effect Module you would be able to do the following:

FXeffect effect = (FXeffect)ID;
Messages are usually handled with a nested switch statement:

FX_ACCESSFUNC(MyAccessFunc)
// FXint f(FX_AccessInfo *ai, FXentity ID, FXint level, FXint64 entry)
{
        switch( level ) // Access Level, e.g. ACCESS_OBJECT
        {
                case ACCESS_OBJECT:             // all ACCESS_OBJECT messages
                        switch( entry )
                        {
                                case O_LOAD:    
                                        // handle O_LOAD
                                        break;

                                case O_SAVE:
                                        // handle O_SAVE
                                        break;

                                // etc.
                        }
                        break;

                // handle next access level
        }

        return ENTRY_OK;
}
You are advised to declare/define this function with the FX_ACCESSFUNC() macro.
See also:
Access Notification for an example.

FXint entry_func FX_AccessInfo   ai,
FXentity    ID,
FXint64    entry
 

User implemented, AL specific, AN message handler.

Parameters:
ai [in] Access info structure
ID [in] Arbitrary ID of the module that the notification is intended for
entry [in] Access Entry of the notification message
Return values:
ENTRY_CONTINUE on success
ENTRY_BREAK on failure
entry_func() is just a name we are giving to any function that you create with the FX_ENTRYFUNC() macro. An entry_func() acts as a handler for all AN messages for a given Access Level. For example you could create an entry_func() for the ACCESS_OBJECT() AL like so:

FX_ENTRYFUNC(MyAccessObjectFunc)
// FXint f(FX_AccessInfo *ai, FXentity ID, FXint64 entry)
{
        switch( entry )
        {
                case O_CREATE:
                        //...

                case O_LOAD:
                        //...

        }

        return ENTRY_OK;
}
Now you would simply delegate to this function all AN messages with ACCESS_OBJECT() AL from your access_func():

FX_ACCESSFUNC(MyAccessFunc)
// FXint f(FX_AccessInfo *ai, FXentity ID, FXint level, FXint64 entry)
{
        switch( level )
        {
                case ACCESS_OBJECT:
                        return MyAccessObjectFunc( ai, ID, entry );

                // other access levels...
        }

        return ENTRY_OK;

}
As you can see in the example above, entry_func() is not really a callback (since it does not get called directly by messiah), but it's close enough.
You are advised to declare/define this function with the FX_ENTRYFUNC() macro.
See also:
Access Notification for an example.


© 2003 pmG WorldWide, LLC.


www.projectmessiah.com

groups.yahoo.com/pmGmessiah

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