---

McdFrame.h

Go to the documentation of this file.

/* -*-c++-*-
  Copyright MathEngine PLC 2000. All rights reserved.
  $RCSfile: McdFrame.h,v $ $Revision: 1.32 $ $Date: 2000/08/15 19:04:55 $
*/
/**
  @file McdFrame.h
  Collision Toolkit main header file.
*/

#ifndef MCDFRAME_H
#define MCDFRAME_H

#include "MePrecision.h"
#include <stddef.h> /* for size_t */

#ifdef __cplusplus
extern "C" {
#endif
  
  typedef MeReal McdReal; /**< type used for reals in the Mcd API */
  typedef short McdBool; /**< @internal */

/*----------------------------------------------------------------
 * Error Reporting
 *---------------------------------------------------------------
 */

/** @internal */
typedef void (*McdMessageHandler)(const char *msg);

/** @internal */
McdMessageHandler McdSetFatalErrorHandler(McdMessageHandler);
/** @internal */
McdMessageHandler McdSetWarningHandler(McdMessageHandler);
/** @internal */
McdMessageHandler McdSetInfoHandler(McdMessageHandler);

/*----------------------------------------------------------------
 * memory management
 *---------------------------------------------------------------
 */

#ifdef MCD_NO_MEMEMORY

  /** @internal */
void McdMemorySetFunctions(void *(*create)(size_t bytes),
                      void *(*resize)(void * block, size_t bytes),
                      void (*destroy)(void * block) );

#endif

/*----------------------------------------------------------------
 * Framework 
 *---------------------------------------------------------------
 */

void
McdInit( int geoTypeMaxCount );

void
McdTerm();

/*---------------------------------------------------------------
 * McdGeometry
 *---------------------------------------------------------------
 */

/** Abstract "base class" for geometrical types. All concrete geometrical
    types share a common set of functionality defined by the McdGeometry
    interface.
*/

typedef struct _McdGeometry McdGeometry;

/** References to MathEngine objects are 
made using "ID" tokens instead of explicit pointers 
*/
typedef McdGeometry *McdGeometryID;

int
McdGeometryGetTypeID( McdGeometryID g );

void
McdGeometryDestroy( McdGeometryID g );

int
McdGeometryGetMassProperties( McdGeometryID g, 
                              MeMatrix4 relativeTransform, 
                              MeMatrix3 inertiaMatrix, 
                              MeReal *volume );

/*---------------------------------------------------------------
 * McdModel
 *---------------------------------------------------------------
 */

/** An McdModel represents a collision model whose geometrical shape is
    specified by a concrete McdGeometry type. Collision models are the
    principal type of object in the system, for which bounding volume,
    culling and intersections queries are available.
*/

typedef struct _McdModel McdModel; 

/** References to MathEngine objects are 
made using "ID" tokens instead of explicit pointers 
*/
typedef McdModel *McdModelID; 


/** @internal */
void
McdModelPoolSetSize( int size );

void
McdModelPoolSetIncrement( int increment );

McdModelID
McdModelCreateEmpty();

McdModelID
McdModelCreate( McdGeometryID g );

void
McdModelSetGeometry( McdModelID cm, McdGeometryID g );
/* calls build, which builds if needed */

McdGeometryID
McdModelGetGeometry( McdModelID g );

int
McdModelGetGeometryTypeID( McdModelID g );

void 
McdModelDestroy( McdModelID cm );

unsigned int
McdModelRemoveFromSpace( McdModelID cm );

void
McdUpdateModelInSpace( McdModelID cm );

unsigned int
McdModelFreezeInSpace( McdModelID cm );

unsigned int
McdModelUnfreezeInSpace( McdModelID cm );

unsigned int
McdModelIsFrozenInSpace( McdModelID cm );

  /** @internal */
void
McdModelSetResponseID( McdModelID cm, int reponseID );

  /** @internal */
int
McdModelGetResponseID( McdModelID cm );

void
McdModelSetContactTolerance( McdModelID cm , McdReal tol );

McdReal
McdModelGetContactTolerance( McdModelID cm );

void
McdModelGetBSphere( McdModelID cm, MeVector3 center, McdReal *radius );

void
McdModelGetAABB( McdModelID cm, MeVector3 minCorner, MeVector3 maxCorner );

void
McdModelSetTransformPtr( McdModelID cm, MeMatrix4 geometryTM );

MeMatrix4 *
McdModelGetTransformPtr( McdModelID cm );

void
McdModelSetUserData( McdModelID cm, void *data );

void*
McdModelGetUserData( McdModelID cm );

unsigned int
McdModelSetInteractionEnabled( McdModelID cm1, McdModelID cm2 );

unsigned int
McdModelSetInteractionDisabled( McdModelID cm1, McdModelID cm2 );

unsigned int
McdModelInteractionIsEnabled( McdModelID cm1, McdModelID cm2 );

/*---------------------------------------------------------------
 * McdModelPair
 *---------------------------------------------------------------
 */

  /** Identifies and keeps track of a particular pair of collision models
      over multiple time steps. It is used by the farfield module to
      identify pairs of models that are nearby to each other and
      potentially colliding. It is used as an argument to the McdIntersect
      functions, which rely on the same struct being re-used for the same
      pair of collision models for multiple time step.*/

typedef struct 
{ 
  /** The first model */
  McdModelID model1; 
  /** The other model */
  McdModelID model2; 
  /** @internal */
  void *pairData;

} McdModelPair;

void
McdModelPairInit( McdModelPair *mcdPair, McdModelID model1, McdModelID model2);

void
McdModelPairTerm( McdModelPair *mcdPair );

  /** @internal */
void
McdModelPairSetUserData( McdModelPair *mcdPair, void *userData );

  /** @internal */
void *
McdModelPairGetUserData( McdModelPair *mcdPair );

  /** @internal */
void
McdModelPairSetResponseData( McdModelPair *mcdPair, void *responseData );

  /** @internal */
void *
McdModelPairGetResponseData( McdModelPair *mcdPair );

/*----------------------------------------------------------------
 * McdModelPairArray 
 *---------------------------------------------------------------
 */
 
  /**
     An array of references to McdModelPair structures, in which three
     "nearby states" are distinguished:
     "hello", "staying" and "goodbye".

     The array is partioned into three index ranges, one for each of the
     distinct states:

     goodbye pairs:
     i = 0 .. goodbyeLastIndex

     hello pairs:
     i = helloFirstIndex .. stayingFirstIndex - 1

     staying pairs:
     i = stayingFirstIndex .. stayingLastIndex

     The scheme used for index ranges allows all "current pairs" ( hello +
     staying) to be iterated through in single loop using the index range
     i = helloFirstIndex .. stayingLastIndex

     The user must initialize this structure by setting @a array and @a size
     to appropriate values.

   */

  /** @internal */
typedef struct 
{
  McdModelPair **array;  /**< array of McdModel pairs */
  
  int size;              /**< number of elements in @a array */
  
  int goodbyeLastIndex;  /**< index range for "goodbye" pairs is:
                            i = 0 ,,, goodbyeLastIndex  */
  
  int helloFirstIndex;   /**< index range for "hello" pairs is:
                            i = helloFirstIndex ,,, stayingFirstIndex - 1
                         */
                            
  int stayingFirstIndex; /**< index range for "staying" pairs is:
                            i = stayingFirstIndex ,,, stayingLastIndex */
  
   int stayingLastIndex;  /**< index range for "staying" pairs is:
                             i = stayingFirstIndex ,,, stayingLastIndex */
} McdModelPairArray;

/** @internal */

void
McdModelPairArrayReset( McdModelPairArray* );

/*----------------------------------------------------------------
 * McdContact 
 *---------------------------------------------------------------
 */

/** Geometric contact point information. Typically, a number of McdContact
    structs are associated with a given McdModelPair. Some of the
    information in the McdContact struct depends on the order of the @arg
    model1 and @arg model2 fields of the associated McdModelPair.
    @see McdModelPair
*/

typedef struct
{

  /** position, in world coordinates, of the point of contact */

    McdReal position[3];            

  /** surface normal at the contact position. Sign chosen so as to point
      from @arg model1 to @arg model2 in the associated McdModelPair. */

    McdReal normal[3];              

  /** separation between objects. Negative if there is penetration */

    McdReal separation;             

  /** local curvature of @arg model1's surface at the contact position */

    McdReal curvature1;             

  /** local curvature of @arg model2's surface at the contact position */

    McdReal curvature2;             

  /** dimensional characterisation of the contact. Possible values are  0,
      1 and 2, corresponding to  point, line and surface, respectively */ 

  short dims;                     

  /** auxiliary data. Used by some intersection functions. This API element
      is subject to change */

  void *auxPtr;    

  /** an auxiliary integer field. Used by some intersection functions. 
      This API element is subject to change */ 

  int auxTag;                   

} McdContact;


/** Utility function for reducing a list of contacts to
    a smaller list. Useful mostly when several models compose one object.
*/
int
McdContactSimplify( McdReal* avgNormal, 
                    McdContact* contacts_src, int nContacts_src,
                    McdContact* contacts_dst, int nContacts_dest );


/*----------------------------------------------------------------
 * McdIntersect 
 *---------------------------------------------------------------
 */

/** Intersection query data. */
typedef struct
{
    McdModelID model1;              /**< one of the collision models */
    McdModelID model2;              /**< the other collision model */
    McdContact *contacts;           /**< array of contacts to be filled */
    int maxContactCount;            /**< size of array */
    int contactCount;               /**< number of contacts returned in array */
    int touch;                      /**< 1 if objects are in contact, 0 otherwise */
    McdReal normal[3];              /**< average normal of contacts returned */
} McdIntersectResult;

int
McdIntersectHello( McdModelPair* );

int
McdIntersect( McdModelPair*, McdIntersectResult* );

int
McdIntersectGoodbye( McdModelPair* );

/*----------------------------------------------------------------
 * McdLineSegIntersect 
 *---------------------------------------------------------------
 */

/** Line segment query data. */
typedef struct {
    McdReal     isctPoint[3];       /**< Intersection point */
    McdReal     normal[3];          /**< Model normal at intersection point */
    McdReal     distance;           /**< Distance from the first end point of line segment
                                      to the intersection point. */
    McdModelID  model;              /**< Collision model intersecting with the 
                                      line segment */
} McdLineSegIntersectResult;

/** Intersect a linesegment with a collision model */
unsigned int
McdLineSegIntersect( McdModelID cm, McdReal* inOrig, McdReal* inDest, 
                     McdLineSegIntersectResult *outOverlap);



/*----------------------------------------------------------------
 * McdSpace 
 *---------------------------------------------------------------
 */

/**
    McdSpace keeps track of where collision models are in 3D space.
    @see McdSpaceAxisSortCreate
*/
typedef struct _McdSpace McdSpace; 

/** References to MathEngine objects are 
made using "ID" tokens instead of explicit pointers 
*/
typedef McdSpace *McdSpaceID; 


extern int McdXAxis;    /**< X-axis to be or'ed with McdYAxis and McdZAxis */
extern int McdYAxis;    /**< Y-axis to be or'ed with McdXAxis and McdZAxis */
extern int McdZAxis;    /**< Z-axis to be or'ed with McdXAxis and McdYAxis */
extern int McdAllAxes;  /**< A constant equal to McdXAxis+McdYAxis+McdZAxis.*/

McdSpaceID
McdSpaceAxisSortCreate( int axes, int objectCount, int pairCount );

void 
McdSpaceDestroy( McdSpaceID s );

void
McdSpaceBuild( McdSpaceID s );

void
McdSpaceUpdate( McdSpaceID s );

unsigned int
McdSpaceInsertModel( McdSpaceID s, McdModelID cm );

void
McdSpaceSetUserData( McdSpaceID s, void *data );

void *
McdSpaceGetUserData( McdSpaceID s );

int
McdSpaceGetLineSegIntersections( McdSpaceID space, 
                                 McdReal* inOrig, McdReal* inDest,
                                 McdLineSegIntersectResult *outList, 
                                 int inMaxListSize); 


/** Iterator for obtaining the "hello" pairs from McdSpace */
typedef struct 
{ 
  void *d; /**< @internal */ 

} McdSpaceHelloPairIterator;

/** Iterator for obtaining the "staying" pairs from McdSpace */
typedef struct 
{ 
  void *d; /**< @internal */ 

} McdSpaceStayingPairIterator;

/** Iterator for obtaining the "goodbye" pairs from McdSpace */
typedef struct 
{ 
  void *d; /**< @internal */ 

} McdSpaceGoodbyePairIterator;

void
McdSpaceHelloPairIteratorInit( McdSpaceID, McdSpaceHelloPairIterator* );

void
McdSpaceStayingPairIteratorInit( McdSpaceID, McdSpaceStayingPairIterator* );

void
McdSpaceGoodbyePairIteratorInit( McdSpaceID, McdSpaceGoodbyePairIterator* );

int
McdSpaceGetHelloPairs( McdSpaceID, McdSpaceHelloPairIterator*, 
                         McdModelPair**, int pairMaxCount );
int
McdSpaceGetStayingPairs( McdSpaceID, McdSpaceStayingPairIterator*, 
                         McdModelPair**, int pairMaxCount );
int
McdSpaceGetGoodbyePairs( McdSpaceID, McdSpaceGoodbyePairIterator*, 
                         McdModelPair**, int pairMaxCount );
 


/* An iterator for pairs of McdModel's identified by McdSpace.

    McdSpace identifies three distinct states for pairs of McdModels:
    "hello", "staying" and "goodbye".

    The "hello" pairs are those
    pairs of McdModel's that McdSpace identifies as in close proximity to
    each other, but which where not in close proximity after the previous
    call to McdSpaceUpdate(). 

    If a pair is found to be in close proximity, and that pair was a
    "hello" pair after the previous call to
    McdSpaceUpdate(), it becomes a "staying" pair. Pairs that remain in close proximity
    remain in the "staying" state after each subsequent call to McdSpaceUpdate().

    When a pair is no longer in close proximity, but
    _was_ in close proximity after the previous call to McdSpaceUpdate(),
    then it is identified as a "goodbye" pair. 

    When a pair is not in close
    proximity, and was not in close proximity after the previous call to
    McdSpaceUpdate(), then it is ignored by McdSpace.

    @see McdSpaceUpdate
    @see McdSpaceGetHelloPairs
    @see McdSpaceGetStayingPairs
    @see McdSpaceGetGoodbyePairs
    @see McdSpaceGetHelloPairIterator
    @see McdSpaceGetStayingPairIterator
    @see McdSpaceGetGoodbyePairIterator
    @see McdModelPair
*/

/** @internal */
typedef struct 
{ 
  void *m_h; /**< @internal */
  void *m_s; /**< @internal */
  void *m_g; /**< @internal */

} McdSpacePairIterator;

/** @internal */
void
McdSpacePairIteratorInit( McdSpaceID, McdSpacePairIterator* );

/** @internal */
McdBool
McdSpaceGetPairs( McdSpaceID, McdSpacePairIterator*, McdModelPairArray* );


/*----------------------------------------------------------------
 * McdPairHandler
 *---------------------------------------------------------------
 */

/** @internal */
void
McdPairHandlerDataPoolSetSize( int size );

void
McdPairHandlerDataPoolSetIncrement( int increment );

void
McdPairHandlerSetSpaceMaxCount( int count );

/** @internal */
int
McdPairHandlerGetNewResponseID( );

/** @internal */
int
McdPairHandlerGetDefaultResponseID( );

/** @internal */
void
McdPairHandlerSetResponseIDMaxCount( int count );

/** @internal */
int
McdPairHandlerGetResponseIDMaxCount( );

void
McdPairHandlerRegisterSpace( McdSpaceID s );

void
McdPairHandlerUnregisterSpace( McdSpaceID s );

void
McdPairHandlerUpdate( );


/*---------------------------------------------------------------
 * McdIntersect
 *---------------------------------------------------------------
 */

void
McdIntersectSetContactBufferSize( int count );

int
McdIntersectGetContactBufferSize( );

int
McdIntersectGetNewRequestID();

int
McdIntersectGetDefaultRequestID();

void
McdIntersectSetRequestID( McdModelID cm, int requestID );

int
McdIntersectGetRequestID( McdModelID cm );

void
McdIntersectSetRequestIDMaxCount( int count );

int
McdIntersectGetRequestIDMaxCount( );

void
McdIntersectRequestSetContactMaxCount( int requestID1, int requestID2, int count );

int
McdIntersectRequestGetContactMaxCount( int requestID1, int requestID2 );

void
McdIntersectSetFaceNormalsFirst( int requestID1, int requestID2,
                                  unsigned int faceNormalsFirst );

unsigned int
McdIntersectGetFaceNormalsFirst( int requestID1, int requestID2 );

   
#ifdef __cplusplus
} /* extern "C" */
#endif



#endif /* #ifndef MCDFRAME_H */

---