messiah_mesh.h


Provides functionality relating to an object's mesh.

Version:
1.1
Date:
7/08/03
Topics


Data Structures

struct  FX_DisplacePoint_St
 Point displacement structure. More...


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_DISPLACESCAN(f, dt, ed)
 Used to declare/define a disp_func() FIX ME that will get called once for each point in a mesh being displaced.


Weight Type Macros



#define FX_WEIGHT_SETUP
 Calculate the weights while in Setup Mode only.

#define FX_WEIGHT_ANIMATE
 Calculate the weights while outside of Setup Mode.

#define FX_WEIGHT_COMBO
 Calculate the weights based on the position of the points in Setup Mode, but use the position of the weight tool outside of Setup Mode.

#define FX_WEIGHT_DONTCREATE
 Do not use weights for this displacement scan.

#define FX_DISPFLAG_WEIGHT
 Flag set on FX_DisplacePoint_St::flags to indicate that the point has weight information stored in FX_DisplacePoint_St::weight.


Structures



typedef FX_DisplacePoint_St FX_DisplacePoint

Callback Functions

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


FXint disp_func (FX_DisplacePoint *p, FXvoid *ed)
 user-implemented callback that will be called once for each point in a mesh being displaced


Mesh Functions



FXint fxMeshNumPoints (FXobject objID, FXint *num_points, FXint flags)
 Get number of points.

FXint fxMeshNumPolys (FXobject objID, FXint *num_polys, FXint flags)
 Get number of polygons.

FXint fxMeshPoly (FXobject objID, FXint polyID, FXint pnt_array[], FXint array_size, FXint *num_points, FXint *surfID, FXint flags)
 Get information about a particular polygon.

FXint fxMeshPolyNormal (FXobject objID, FXint polyID, FXdouble norm[3], FXint flags)
 Get a polygon's surface normal.

FXint fxMeshPoint (FXobject objID, FXint pointID, FXdouble pos[3], FXint flags)
 Get a point's position.

FXint fxMeshPointNormal (FXobject objID, FXint pointID, FXdouble norm[3], FXint flags)
 Get surface normal at a given point.

FXint fxMeshPointPolys (FXobject objID, FXint pointID, FXint poly_array[], FXint array_size, FXint *num_polys, FXint flags)
 Get the polygons connected to a given point.


Displacement Functions



FXint fxDisplaceScan (FXobject objID, FXtool weightID, FXint weight_flags, FXint(*scan_func)(FX_DisplacePoint *, FXvoid *), FXvoid *data, FXint flags)
 Send all points, in turn, to a user supplied callback for displacement.

FXint fxDisplaceBegin (FXobject objID, FXint flags)
 Begin a manual (non-sequential) displacement.

FXint fxDisplacePoint (FXobject objID, FXint pointID, FXdouble x, FXdouble y, FXdouble z)
 Set a point's position, inside an fxDisplaceBegin() / fxDisplaceEnd() block.

FXint fxDisplaceEnd (FXobject objID, FXint flags)
 End a manual (non-sequential) displacement.


Define Documentation

#define FX_DISPFLAG_WEIGHT
 

Flag set on FX_DisplacePoint_St::flags to indicate that the point has weight information stored in FX_DisplacePoint_St::weight.

#define FX_DISPLACESCAN f,
dt,
ed   
 

Used to declare/define a disp_func() FIX ME that will get called once for each point in a mesh being displaced.

Expands to:
FXint f(FX_DisplacePoint *p, dt *ed)
Parameters:
f The name of the callback being defined
dt Data type of the data passed to fxDisplaceScan()
ed Name of the data variable
You will pass this callback to fxDisplaceScan() to begin iterating over all points in an object and displacing them. If you would like to pass your own data to your callback you may do so by giving it a name and data type with this macro.
Example:

FX_DISPLACESCAN( MyCallback, MyDataStruct, mydata );

// expands to:

FXint MyCallback( FX_DisplacePoint *p, MyDataStruct *mydata );
Now when you call fxDisplaceScan() you'll pass it the address of a MyDataStruct as its data parameter. A very common use for this is to store information that only needs to be computed once per frame rather than once per point (e.g. NOW ).
See also:
FIX ME, Mesh Deformation

#define FX_WEIGHT_ANIMATE
 

Calculate the weights while outside of Setup Mode.

#define FX_WEIGHT_COMBO
 

Calculate the weights based on the position of the points in Setup Mode, but use the position of the weight tool outside of Setup Mode.

#define FX_WEIGHT_DONTCREATE
 

Do not use weights for this displacement scan.

#define FX_WEIGHT_SETUP
 

Calculate the weights while in Setup Mode only.


Function Documentation

FXint disp_func FX_DisplacePoint   p,
FXvoid   ed
 

user-implemented callback that will be called once for each point in a mesh being displaced

Parameters:
p [in] FX_DisplacePoint structure containing information about the point
ed [in] value passed as data to fxDisplaceScan()
disp_func() is just a name we are giving to any callback function that you create with the FX_DISPLACESCAN() macro. You will pass the address of this function as a callback to messiah when you call the fxDisplaceScan() function. From there messiah will call your callback once for each point contained in the mesh passed to fxDisplaceScan().
See also:
FIX ME, Mesh Deformation

FXint fxDisplaceBegin FXobject    objID,
FXint    flags
 

Begin a manual (non-sequential) displacement.

Parameters:
objID [in] Object ID
flags [in] Reserved for future use
Return values:
FX_TRUE on success
FX_FALSE on failure
See also:
fxDisplacePoint(), Mesh Deformation

FXint fxDisplaceEnd FXobject    objID,
FXint    flags
 

End a manual (non-sequential) displacement.

Parameters:
objID [in] Object ID
flags [in] Reserved for future use
Return values:
FX_TRUE on success
FX_FALSE on failure
See also:
fxDisplacePoint(), Mesh Deformation

FXint fxDisplacePoint FXobject    objID,
FXint    pointID,
FXdouble    x,
FXdouble    y,
FXdouble    z
 

Set a point's position, inside an fxDisplaceBegin() / fxDisplaceEnd() block.

Parameters:
objID [in] Object ID
pointID [in] 0 based point index
x,y,z [in] new point position in worldspace
Return values:
FX_TRUE on success
FX_FALSE on failure
Use this function to displace an object's geometry. It is more effecient to use the fxDisplaceScan() function, however if you only wish to displace a few points or need to displace them non-sequentially you will need to use this function. You will need to place all calls to fxDisplacePoint() between matching calls to fxDisplaceBegin() and fxDisplaceEnd().

FXint fxDisplaceScan FXobject    objID,
FXtool    weightID,
FXint    weight_flags,
FXint(*    scan_func)(FX_DisplacePoint *, FXvoid *),
FXvoid   data,
FXint    flags
 

Send all points, in turn, to a user supplied callback for displacement.

Parameters:
objID [in] Object ID
weightID [in] ID of the weight tool to use for this displacement (or FX_NULLID)
weight_flags [in] See Flag Values Below
scan_func [in] User callback
data [in] User data
flags [in] Reserved for future use
Return values:
FX_TRUE on success
FX_FALSE on failure
Flag Values: weight_flags
FX_WEIGHT_SETUP() Calculate the weights while in Setup Mode only
FX_WEIGHT_ANIMATE() Calculate the weights while outside of Setup Mode
FX_WEIGHT_COMBO() Calculate the weights based on the position of the points in Setup Mode, but use the position of the weight tool outside of Setup Mode
FX_WEIGHT_DONTCREATE() Do not use weights for this displacement scan
This function is normally called from an effect's fxEffectTargetScan() Callback, that is itself called from the effect's P_POST_POINT_DISPLACE() Access Notification. The user supplied Callback scan_func() will be called once for each point in objID. The user's scan_func() will get passed a FX_DisplacePoint struct as well as whatever was passed as the data arg to this function. Inside the scan_func() callback you will set the FX_DisplacePoint::new_pos member to the new worldspace position of the point.
See also:
FIX ME, Mesh Deformation

FXint fxMeshNumPoints FXobject    objID,
FXint   num_points,
FXint    flags
 

Get number of points.

Parameters:
objID [in] Identifier of the object whose point count you want.
num_points [out] Pointer to User Allocated FXint to hold resulting value.
flags [in] Reserved for future use
Return values:
FX_TRUE on success
FX_FALSE on failure

FXint fxMeshNumPolys FXobject    objID,
FXint   num_polys,
FXint    flags
 

Get number of polygons.

Parameters:
objID [in] Identifier of the object whose poly count you want.
num_polys [out] Pointer to User Allocated FXint to hold resulting value.
flags [in] Reserved for future use
Return values:
FX_TRUE on success
FX_FALSE on failure

FXint fxMeshPoint FXobject    objID,
FXint    pointID,
FXdouble    pos[3],
FXint    flags
 

Get a point's position.

Parameters:
objID [in] Object ID
pointID [in] 0 based point index
pos [out] User Allocated FXdouble array to hold point's position in worldspace
flags [in] Reserved for future use
Return values:
FX_TRUE on success
FX_FALSE on failure

FXint fxMeshPointNormal FXobject    objID,
FXint    pointID,
FXdouble    norm[3],
FXint    flags
 

Get surface normal at a given point.

Parameters:
objID [in] Object ID
pointID [in] 0 based point index
norm [out] User Allocated FXdouble array to hold point's normal
flags [in] Reserved for future use
Return values:
FX_TRUE on success
FX_FALSE on failure
The normal for a point is the average of the normals of all polygons adjacent to the point.

FXint fxMeshPointPolys FXobject    objID,
FXint    pointID,
FXint    poly_array[],
FXint    array_size,
FXint   num_polys,
FXint    flags
 

Get the polygons connected to a given point.

Parameters:
objID [in] Object ID
pointID [in] 0 based point index
poly_array [out] User Allocated FXint array to hold polygon indices
array_size [in] number of elements in the poly_array buffer
num_polys [out] User Allocated FXint to hold the number of polygons attached to pointID
flags [in] Reserved for future use
Return values:
FX_TRUE on success
FX_FALSE on failure
This function will store at most array_size polygon ID's in the poly_array. The actual number of polygon ID's stored will be stored in the num_polys variable.

FXint fxMeshPoly FXobject    objID,
FXint    polyID,
FXint    pnt_array[],
FXint    array_size,
FXint   num_points,
FXint   surfID,
FXint    flags
 

Get information about a particular polygon.

Parameters:
objID [in] Identifier of the object
polyID [in] 0 based polygon index
pnt_array [out] User Allocated FXint array to hold point indices for specified polygon
array_size [in] Size (in number of elements) of the array passed as pnt_array
num_points [out] User Allocated FXint to hold actual number of points for this polygon
surfID [out] User Allocated FXint to hold the surface ID for this polygon (or NULL if you are not interested in the surface ID)
flags [in] Reserved for future use
Return values:
FX_TRUE on success
FX_FALSE on failure
Use this function when you need to get information about a specific polygon, identified by it's 0 based polyID. You must supply pointers to variables to hold several pieces of information with this function. The pnt_array array will be filled with the indices of each point associated with this polygon. The order of the points will be clockwise when viewing the polygon front-facing. You must specify the size of the buffer you are passing as pnt_array in the variable array_size.
Example:
FXint buffer[MY_PNT_BUFFER_SIZE];
FXint numPnts;
FXint srfID;

fxMeshPoly( objID, polyID, buffer, MY_PNT_BUFFER_SIZE, &numPnts, &srfID, 0);

FXint fxMeshPolyNormal FXobject    objID,
FXint    polyID,
FXdouble    norm[3],
FXint    flags
 

Get a polygon's surface normal.

Parameters:
objID [in] Object ID
polyID [in] Polygon ID
norm [out] User Allocated FXdouble array to hold normal value
flags [in] Reserved for future use
Return values:
FX_TRUE on success
FX_FALSE on failure


© 2003 pmG WorldWide, LLC.


www.projectmessiah.com

groups.yahoo.com/pmGmessiah

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