messiah_arg.h


Provides functions for working with the FXarg data type.

Version:
1.1
Date:
6/7/03
Topics
Data Types ( FX_ARG_* )
Format Functions ( fxFormat* )
Argument "Set" Functions ( fxArgSet* )
Argument "Get" Functions ( fxArgGet* )
Argument "Load" Functions ( fxArgLoad* )
Argument "Save" Functions ( fxArgSave* )
Description
The FX_Arg data type is the primary focus of ARG. An FX_Arg variable contains data packed inside of it, you need special functions to get and set the values of those data. As an example of where this might be employed, consider the control_func() of INTERFACE. This user-defined callback accepts a FX_Arg* arg. This callback is called whenever messiah needs to notify the owner of the control of some event, the information contained in the arg parameter may contain information specific to the type of control that generated the message. Another common situation where you will be interested in FX_Arg variables is in the loading and saving of information to and from messiah files.

//...
FX_Format *f = fxFormatNew( ai, "MyFormat", FX_NOFLAG);
        fxArgSaveObj( f, "weight", some_obj );
        fxArgSaveInt( f, "scan", some_int );
In this case we use the FX_Format structure which is a type of FX_Arg used for File IO. Data is stored in this FX_Format using the fxArgSave* functions and is identified by a name; "weight" and "scan" in the example above. Before storing these values in the FX_Format* f we first have to create and store f in the FX_AccessInfo* ai. FX_AccessInfo is also another form of FX_Arg and is passed to your module's access_func() as ai. When the scene file is saved the following block of data will be saved with the module (TestEffectModule in this case):

<snip>
BeginModuleData TestEffectModule
        FormatType 0
        FormatEntries 2 LagData
                weight 11 MetaEffector
                scan 9 1
EndModuleData
<snip>
Retrieving the data from a file is just as easy as it was to save it, we use the fxArgLoad* functions and fxFormatGet().

//...
FX_Format *f = fxFormatGet( ai, "MyFormat");
        fxArgLoadObj( f, "weight", &some_obj );
        fxArgLoadInt( f, "scan", &some_int );
You can see an example of loading and saving data to a scene file in the Lag Points Tutorial. There is also a discussion on File IO that may help you become more familiar with the FX_Arg data type and it's variants.


Argument Data Types

These symbols are used to identify data types.

#define FX_ARG_TIME
 data type: FXdouble

#define FX_ARG_FRAME
 data type: FXdouble

#define FX_ARG_DOUBLE
 data type: FXdouble

#define FX_ARG_VECTORD3
 data type: FXvecd

#define FX_ARG_VECTORD4
 data type: FXvecd4

#define FX_ARG_CHAR
 data type: FXchar

#define FX_ARG_STRING
 data type: FXchar *

#define FX_ARG_RGB
 data type: FXchar

#define FX_ARG_RGBA
 data type: FXchar

#define FX_ARG_INT
 data type: FXint

#define FX_ARG_CHANNEL_INT
 data type: FXint

#define FX_ARG_OBJECT
 data type: FXobject

#define FX_ARG_VOID
 data type: FXvoid

#define FX_ARG_POINTER
 data type: FXvoid *

#define FX_ARG_POINTER_INT
 data type: FXint *

#define FX_ARG_POINTER_DOUBLE
 data type: FXdouble *

#define FX_ARG_POINTER_FLOAT
 data type: FXfloat *

#define FX_ARG_POINTER_STRING
 data type: FXchar **

#define FX_ARG_POINTER_CHAR
 data type: FXchar *

#define FX_ARG_STRING_LIST
 data type: FXchar **

#define FX_ARG_DOUBLEPOINTER
 data type: FXvoid **

#define FX_ARG_TRIPLEPOINTER
 data type: FXvoid ***

#define FX_ARG_FLOAT
 data type: FXfloat

#define FX_ARG_VECTORF3
 data type: FXvecf

#define FX_ARG_VECTORF4
 data type: FXvecf4

#define FX_ARG_VECTORI3
 data type: FXveci

#define FX_ARG_VECTORI4
 data type: FXveci4

#define FX_ARG_INT64
 data type: FXint64

#define FX_ARG_IMAGE
 data type: FXimage


Format functions

A format is a block inside of a messiah file that has the following form:

FormatEntries 2 LagData
        weight 0 0.000000
        scan 9 1
The number following FormatEntries indicates the number of entries in the format to follow, LagData is the name of this particular format. Each entry then follows with it's name, type and value.
There are a few places you will typically work with formats, the most common is probably in response to the O_LOAD() and O_SAVE() AN messages. This is where you will load and save information about your effect or shader module, typically this will be information the user has provided through your INTERFACE. See File IO for more information


FX_FormatfxFormatNew (FX_AccessInfo *ai, FXchar *name, FXint flags)
 Creates a new format in the given ai called name.

FX_FormatfxFormatGet (FX_AccessInfo *ai, FXchar *name)
 Retrieves an existing format from the ai named name.

FX_FormatfxFormatNext (FX_AccessInfo *ai, FX_Format *next)
 Retrieve the next format in a given ai.

FX_FormatfxFormatPrev (FX_AccessInfo *ai, FX_Format *prev)
 Retreive the previous format in a given ai.

FXvoid fxArgResetLoad (FXvoid *args)
 UNKNOWN.


Argument "get" functions

Each of these functions is used to retrieve data from an FX_Arg type variable. There exists a function for each type of data that can be stored in an FX_Arg variable and all but one are nearly identical.

Parameters:
args [in] FX_Arg type variable to get data from
name [in] name of the element in the FX_Arg
ID [in] 0 based index of the data in the FX_Arg
var [out] storage for the data to be retrieved
You can get a value from an FX_Arg variable either by name or ID (name has precedence over ID). In all cases you must supply the storage for the data to be retrieved, in the case of the fxArgGetString() function you must also indicate the length of the buffer.


FXint fxArgGetInt (FXvoid *args, FXchar *name, FXint ID, FXint *var)
 Get an FXint value.

FXint fxArgGetDouble (FXvoid *args, FXchar *name, FXint ID, FXdouble *var)
 Get an FXdouble value.

FXint fxArgGetFloat (FXvoid *args, FXchar *name, FXint ID, FXfloat *var)
 Get an FXfloat value.

FXint fxArgGetVeci3 (FXvoid *args, FXchar *name, FXint ID, FXveci var)
 Get an FXveci value.

FXint fxArgGetVecd3 (FXvoid *args, FXchar *name, FXint ID, FXvecd var)
 Get an FXvecd value.

FXint fxArgGetVecf3 (FXvoid *args, FXchar *name, FXint ID, FXvecf var)
 Get an FXvecf value.

FXint fxArgGetVeci4 (FXvoid *args, FXchar *name, FXint ID, FXveci4 var)
 Get an FXveci4 value.

FXint fxArgGetVecd4 (FXvoid *args, FXchar *name, FXint ID, FXvecd4 var)
 Get an FXvecd4 value.

FXint fxArgGetVecf4 (FXvoid *args, FXchar *name, FXint ID, FXvecf4 var)
 Get an FXvecf4 value.

FXint fxArgGetCharRGB (FXvoid *args, FXchar *name, FXint ID, FXchar *var)
 Get an RGB value.

FXint fxArgGetCharRGBA (FXvoid *args, FXchar *name, FXint ID, FXchar *var)
 Get an RGBA value.

FXint fxArgGetChar (FXvoid *args, FXchar *name, FXint ID, FXchar *var)
 Get an FXchar value.

FXint fxArgGetString (FXvoid *args, FXchar *name, FXint ID, FXchar *var, FXint buffer_length)
 Get an FXchar * value.

FXint fxArgGetObj (FXvoid *args, FXchar *name, FXint ID, FXobject *var)
 Get an FXobject value.

FXint fxArgGetImage (FXvoid *args, FXchar *name, FXint ID, FXimage *var)
 Get an FXimage value.

FXint fxArgGetVoid (FXvoid *args, FXchar *name, FXint ID, FXvoid **var)
 Get an FXvoid * value.

FXint fxArgGetInt64 (FXvoid *args, FXchar *name, FXint ID, FXint64 *var)
 Get an FXint64 value.


Argument "set" functions

Each of these functions is used to pack data into an FX_Arg type variable. There exists a function for each type of data that can be stored in an FX_Arg variable.

Parameters:
args [in] FX_Arg type variable to get data from
name [in] name of the element in the FX_Arg variable
ID [in] 0 based index of the element in the FX_Arg variable
var [in] value you want to pack in the FX_Arg variable
You can set a value in an FX_Arg variable either by name or ID (name has precedence over ID).


FXint fxArgSetInt (FXvoid *args, FXchar *name, FXint ID, FXint var)
 Set an FXint value.

FXint fxArgSetDouble (FXvoid *args, FXchar *name, FXint ID, FXdouble var)
 Set an FXdouble value.

FXint fxArgSetFloat (FXvoid *args, FXchar *name, FXint ID, FXfloat var)
 Set an FXfloat value.

FXint fxArgSetVeci3 (FXvoid *args, FXchar *name, FXint ID, FXveci var)
 Set an FXveci value.

FXint fxArgSetVecd3 (FXvoid *args, FXchar *name, FXint ID, FXvecd var)
 Set an FXvecd value.

FXint fxArgSetVecf3 (FXvoid *args, FXchar *name, FXint ID, FXvecf var)
 Set an FXvecf value.

FXint fxArgSetVeci4 (FXvoid *args, FXchar *name, FXint ID, FXveci4 var)
 Set an FXveci4 value.

FXint fxArgSetVecd4 (FXvoid *args, FXchar *name, FXint ID, FXvecd4 var)
 Set an FXvecd4 value.

FXint fxArgSetVecf4 (FXvoid *args, FXchar *name, FXint ID, FXvecf4 var)
 Set an FXvecf4 value.

FXint fxArgSetCharRGB (FXvoid *args, FXchar *name, FXint ID, FXchar *var)
 Set an RGB value.

FXint fxArgSetCharRGBA (FXvoid *args, FXchar *name, FXint ID, FXchar *var)
 Set an RGBA value.

FXint fxArgSetChar (FXvoid *args, FXchar *name, FXint ID, FXchar var)
 Set an FXchar value.

FXint fxArgSetString (FXvoid *args, FXchar *name, FXint ID, FXchar *var)
 Set an FXchar * value.

FXint fxArgSetObj (FXvoid *args, FXchar *name, FXint ID, FXobject var)
 Set an FXobject value.

FXint fxArgSetImage (FXvoid *args, FXchar *name, FXint ID, FXimage var)
 Set an FXimage value.

FXint fxArgSetVoid (FXvoid *args, FXchar *name, FXint ID, FXvoid *var)
 Set an FXvoid * value.

FXint fxArgSetInt64 (FXvoid *args, FXchar *name, FXint ID, FXint64 var)
 Set an FXint64 value.


Argument "load" functions

These functions are used for File IO operations. Each of these functions are used to retrieve data from an FX_AccessInfo type variable. There exists a function for each type of data that can be stored in an FX_AccessInfo variable and all but one are nearly identical.

Parameters:
args [in] FX_AccessInfo type variable (ai in access_func() ) to get data from
name [in] name of the element in the FX_AccessInfo
var [out] storage for the data to be retrieved
In all cases you must supply the storage for the data to be retrieved, in the case of the fxArgLoadString() function you must also indicate the length of the buffer.


FXint fxArgLoadInt (FXvoid *args, FXchar *name, FXint *var)
 Load an FXint value from the format.

FXint fxArgLoadDouble (FXvoid *args, FXchar *name, FXdouble *var)
 Load an FXdouble value from the format.

FXint fxArgLoadFloat (FXvoid *args, FXchar *name, FXfloat *var)
 Load an FXfloat value from the format.

FXint fxArgLoadVeci3 (FXvoid *args, FXchar *name, FXveci var)
 Load an FXveci value from the format.

FXint fxArgLoadVecd3 (FXvoid *args, FXchar *name, FXvecd var)
 Load an FXvecd value from the format.

FXint fxArgLoadVecf3 (FXvoid *args, FXchar *name, FXvecf var)
 Load an FXvecf value from the format.

FXint fxArgLoadVeci4 (FXvoid *args, FXchar *name, FXveci4 var)
 Load an FXveci4 value from the format.

FXint fxArgLoadVecd4 (FXvoid *args, FXchar *name, FXvecd4 var)
 Load an FXvecd4 value from the format.

FXint fxArgLoadVecf4 (FXvoid *args, FXchar *name, FXvecf4 var)
 Load an FXvecf4 value from the format.

FXint fxArgLoadCharRGB (FXvoid *args, FXchar *name, FXchar *var)
 Load an RGB value from the format.

FXint fxArgLoadCharRGBA (FXvoid *args, FXchar *name, FXchar *var)
 Load an RGBA value from the format.

FXint fxArgLoadChar (FXvoid *args, FXchar *name, FXchar *var)
 Load an FXchar value from the format.

FXint fxArgLoadString (FXvoid *args, FXchar *name, FXchar *var, FXint buffer_length)
 Load an FXchar * value from the format.

FXint fxArgLoadObj (FXvoid *args, FXchar *name, FXobject *var)
 Load an FXobject value from the format.

FXint fxArgLoadImage (FXvoid *args, FXchar *name, FXimage *var)
 Load an FXimage value from the format.

FXint fxArgLoadVoid (FXvoid *args, FXchar *name, FXvoid **var)
 Load an FXvoid * value from the format.

FXint fxArgLoadInt64 (FXvoid *args, FXchar *name, FXint64 *var)
 Load an FXint64 value from the format.


Argument "save" functions

These functions are used for File IO operations. Each of these functions is used to store data in an FX_AccessInfo type variable. There exists a function for each type of data that can be stored in an FX_AccessInfo variable.

Parameters:
args [in] FX_AccessInfo type variable (ai in access_func() ) to get data from
name [in] name of the element in the FX_AccessInfo
var [out] storage for the data to be retrieved


FXint fxArgSaveInt (FXvoid *args, FXchar *name, FXint var)
 Save an FXint value to the format.

FXint fxArgSaveDouble (FXvoid *args, FXchar *name, FXdouble var)
 Save an FXdouble value to the format.

FXint fxArgSaveFloat (FXvoid *args, FXchar *name, FXfloat var)
 Save an FXfloat value to the format.

FXint fxArgSaveVeci3 (FXvoid *args, FXchar *name, FXveci var)
 Save an FXveci value to the format.

FXint fxArgSaveVecd3 (FXvoid *args, FXchar *name, FXvecd var)
 Save an FXvecd value to the format.

FXint fxArgSaveVecf3 (FXvoid *args, FXchar *name, FXvecf var)
 Save an FXvecf value to the format.

FXint fxArgSaveVeci4 (FXvoid *args, FXchar *name, FXveci4 var)
 Save an FXveci4 value to the format.

FXint fxArgSaveVecd4 (FXvoid *args, FXchar *name, FXvecd4 var)
 Save an FXvecd4 value to the format.

FXint fxArgSaveVecf4 (FXvoid *args, FXchar *name, FXvecf4 var)
 Save an FXvecf4 value to the format.

FXint fxArgSaveCharRGB (FXvoid *args, FXchar *name, FXchar *var)
 Save an RGB value to the format.

FXint fxArgSaveCharRGBA (FXvoid *args, FXchar *name, FXchar *var)
 Save an RGBA value to the format.

FXint fxArgSaveChar (FXvoid *args, FXchar *name, FXchar var)
 Save an FXchar value to the format.

FXint fxArgSaveString (FXvoid *args, FXchar *name, FXchar *var)
 Save an FXchar * value to the format.

FXint fxArgSaveObj (FXvoid *args, FXchar *name, FXobject var)
 Save an FXobject value to the format.

FXint fxArgSaveImage (FXvoid *args, FXchar *name, FXimage var)
 Save an FXimage value to the format.

FXint fxArgSaveVoid (FXvoid *args, FXchar *name, FXvoid *var)
 Save an FXvoid * value to the format.

FXint fxArgSaveInt64 (FXvoid *args, FXchar *name, FXint64 var)
 Save an FXint64 value to the format.


© 2003 pmG WorldWide, LLC.


www.projectmessiah.com

groups.yahoo.com/pmGmessiah

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