extern/solid/SOLID/SOLID.h

   1 /*
   2  * SOLID - Software Library for Interference Detection
   3  *
   4  * Copyright (C) 2001-2003  Dtecta.  All rights reserved.
   5  *
   6  * This library may be distributed under the terms of the Q Public License
   7  * (QPL) as defined by Trolltech AS of Norway and appearing in the file
   8  * LICENSE.QPL included in the packaging of this file.
   9  *
  10  * This library may be distributed and/or modified under the terms of the
  11  * GNU General Public License (GPL) version 2 as published by the Free Software
  12  * Foundation and appearing in the file LICENSE.GPL included in the
  13  * packaging of this file.
  14  *
  15  * This library is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
  16  * WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  17  *
  18  * Commercial use or any other use of this library not covered by either
  19  * the QPL or the GPL requires an additional license from Dtecta.
  20  * Please contact info@dtecta.com for enquiries about the terms of commercial
  21  * use of this library.
  22  */
  23
  24 #ifndef SOLID_H
  25 #define SOLID_H
  26
  27 #include "SOLID_types.h"
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33         DT_DECLARE_HANDLE(DT_ObjectHandle);
  34         DT_DECLARE_HANDLE(DT_SceneHandle);
  35         DT_DECLARE_HANDLE(DT_ShapeHandle);
  36         DT_DECLARE_HANDLE(DT_VertexBaseHandle);
  37         DT_DECLARE_HANDLE(DT_RespTableHandle);
  38         DT_DECLARE_HANDLE(DT_ArchiveHandle);
  39
  40         typedef unsigned int DT_ResponseClass;
  41
  42         typedef enum DT_ResponseType {
  43                 DT_NO_RESPONSE,                  /* No response (obsolete) */
  44                 DT_BROAD_RESPONSE,
  45                 DT_SIMPLE_RESPONSE,              /* No collision data */
  46                 DT_WITNESSED_RESPONSE,           /* A point common to both objects
  47                                                                                         is returned as collision data
  48                                                                                  */
  49                 DT_DEPTH_RESPONSE                /* The penetration depth is returned
  50                                                                                         as collision data. The penetration depth
  51                                                                                         is the shortest vector over which one
  52                                                                                         object needs to be translated in order
  53                                                                                         to bring the objects in touching contact.
  54                                                                                  */
  55         } DT_ResponseType;
  56
  57 /* For witnessed response, the following structure represents a common point. The world
  58    coordinates of 'point1' and 'point2' coincide. 'normal' is the zero vector.
  59
  60    For depth response, the following structure represents the penetration depth.
  61    'point1' en 'point2' are the witness points of the penetration depth in world coordinates.
  62    The penetration depth vector in world coordinates is represented by 'normal'.
  63 */
  64
  65         typedef struct DT_CollData {
  66                 DT_Vector3 point1;               /* Point in object1 in world coordinates */
  67                 DT_Vector3 point2;               /* Point in object2 in world coordinates */
  68                 DT_Vector3 normal;               /* point2 - point1 */
  69         } DT_CollData;
  70
  71 /* A response callback is called by SOLID for each pair of collding objects. 'client-data'
  72    is a pointer to an arbitrary structure in the client application. The client objects are
  73    pointers to structures in the client application associated with the coliding objects.
  74    'coll_data' is the collision data computed by SOLID.
  75 */
  76
  77         typedef DT_Bool (*DT_ResponseCallback)(void *client_data,
  78                                                                                    void *client_object1,
  79                                                                                    void *client_object2,
  80                                                                                    const DT_CollData *coll_data);
  81
  82 /* Shape definition */
  83
  84
  85         extern DECLSPEC DT_ShapeHandle DT_NewBox(DT_Scalar x, DT_Scalar y, DT_Scalar z);
  86         extern DECLSPEC DT_ShapeHandle DT_NewCone(DT_Scalar radius, DT_Scalar height);
  87         extern DECLSPEC DT_ShapeHandle DT_NewCylinder(DT_Scalar radius, DT_Scalar height);
  88         extern DECLSPEC DT_ShapeHandle DT_NewSphere(DT_Scalar radius);
  89         extern DECLSPEC DT_ShapeHandle DT_NewPoint(const DT_Vector3 point);
  90         extern DECLSPEC DT_ShapeHandle DT_NewLineSegment(const DT_Vector3 source, const DT_Vector3 target);
  91         extern DECLSPEC DT_ShapeHandle DT_NewMinkowski(DT_ShapeHandle shape1, DT_ShapeHandle shape2);
  92         extern DECLSPEC DT_ShapeHandle DT_NewHull(DT_ShapeHandle shape1, DT_ShapeHandle shape2);
  93
  94         extern DECLSPEC DT_VertexBaseHandle DT_NewVertexBase(const void *pointer, DT_Size stride);
  95         extern DECLSPEC void DT_DeleteVertexBase(DT_VertexBaseHandle vertexBase);
  96         extern DECLSPEC void DT_ChangeVertexBase(DT_VertexBaseHandle vertexBase, const void *pointer);
  97
  98         extern DECLSPEC DT_ShapeHandle DT_NewComplexShape(DT_VertexBaseHandle vertexBase);
  99         extern DECLSPEC void           DT_EndComplexShape();
 100
 101         extern DECLSPEC DT_ShapeHandle DT_NewPolytope(DT_VertexBaseHandle vertexBase);
 102         extern DECLSPEC void           DT_EndPolytope();
 103
 104         extern DECLSPEC void DT_Begin();
 105         extern DECLSPEC void DT_End();
 106
 107         extern DECLSPEC void DT_Vertex(const DT_Vector3 vertex);
 108         extern DECLSPEC void DT_VertexIndex(DT_Index index);
 109
 110         extern DECLSPEC void DT_VertexIndices(DT_Count count, const DT_Index *indices);
 111         extern DECLSPEC void DT_VertexRange(DT_Index first, DT_Count count);
 112
 113         extern DECLSPEC void DT_DeleteShape(DT_ShapeHandle shape);
 114
 115 /* Object  */
 116
 117         extern DECLSPEC DT_ObjectHandle DT_CreateObject(
 118                 void *client_object,      /* pointer to object in client memory */
 119                 DT_ShapeHandle shape  /* the shape or geometry of the object */
 120                 );
 121
 122         extern DECLSPEC void DT_DestroyObject(DT_ObjectHandle object);
 123
 124
 125
 126         extern DECLSPEC void DT_SetPosition(DT_ObjectHandle object, const DT_Vector3 position);
 127         extern DECLSPEC void DT_SetOrientation(DT_ObjectHandle object, const DT_Quaternion orientation);
 128         extern DECLSPEC void DT_SetScaling(DT_ObjectHandle object, const DT_Vector3 scaling);
 129
 130 /* The margin is an offset from the actual shape. The actual geometry of an
 131    object is the set of points whose distance to the transformed shape is at
 132    most the  margin. During the lifetime of an object the margin can be
 133    modified.
 134 */
 135
 136         extern DECLSPEC void DT_SetMargin(DT_ObjectHandle object, DT_Scalar margin);
 137
 138
 139 /* These commands assume a column-major 4x4 OpenGL matrix representation */
 140
 141         extern DECLSPEC void DT_SetMatrixf(DT_ObjectHandle object, const float *m);
 142         extern DECLSPEC void DT_GetMatrixf(DT_ObjectHandle object, float *m);
 143
 144         extern DECLSPEC void DT_SetMatrixd(DT_ObjectHandle object, const double *m);
 145         extern DECLSPEC void DT_GetMatrixd(DT_ObjectHandle object, double *m);
 146
 147         extern DECLSPEC void DT_GetBBox(DT_ObjectHandle object, DT_Vector3 min, DT_Vector3 max);
 148
 149
 150         extern DECLSPEC DT_Bool  DT_GetIntersect(DT_ObjectHandle object1, DT_ObjectHandle object2,
 151                                                                                                 DT_Vector3 v);
 152 /* This next command returns the distance between the objects. De returned
 153    closest points are given in world coordinates.
 154 */
 155         extern DECLSPEC DT_Scalar DT_GetClosestPair(DT_ObjectHandle object1, DT_ObjectHandle object2,
 156                                                                                                 DT_Vector3 point1, DT_Vector3 point2);
 157
 158         extern DECLSPEC DT_Bool   DT_GetCommonPoint(DT_ObjectHandle object1, DT_ObjectHandle object2,
 159                                                                                                 DT_Vector3 point);
 160
 161         extern DECLSPEC DT_Bool   DT_GetPenDepth(DT_ObjectHandle object1, DT_ObjectHandle object2,
 162                                                                                          DT_Vector3 point1, DT_Vector3 point2);
 163
 164 /* Scene */
 165
 166         extern DECLSPEC DT_SceneHandle DT_CreateScene();
 167         extern DECLSPEC void           DT_DestroyScene(DT_SceneHandle scene);
 168
 169         extern DECLSPEC void DT_AddObject(DT_SceneHandle scene, DT_ObjectHandle object);
 170         extern DECLSPEC void DT_RemoveObject(DT_SceneHandle scene, DT_ObjectHandle object);
 171
 172 /* Note that objects can be assigned to multiple scenes! */
 173
 174 /* Response */
 175
 176 /* Response tables are defined independent of the scenes in which they are used.
 177    Multiple response tables can be used in one scene, and a response table
 178    can be shared among scenes.
 179 */
 180         extern DECLSPEC DT_RespTableHandle DT_CreateRespTable();
 181         extern DECLSPEC void               DT_DestroyRespTable(DT_RespTableHandle respTable);
 182
 183 /* Responses are defined on (pairs of) response classes. Each response table
 184    maintains its set of response classes.
 185 */
 186         extern DECLSPEC DT_ResponseClass DT_GenResponseClass(DT_RespTableHandle respTable);
 187
 188 /* To each object for which a response is defined in the response table a
 189    response class needs to be assigned.
 190 */
 191
 192         extern DECLSPEC void DT_SetResponseClass(DT_RespTableHandle respTable,
 193                                                                                          DT_ObjectHandle object,
 194                                                                                          DT_ResponseClass responseClass);
 195
 196         extern DECLSPEC void DT_ClearResponseClass(DT_RespTableHandle respTable,
 197                                                                                            DT_ObjectHandle object);
 198
 199         extern DECLSPEC void DT_CallResponse(DT_RespTableHandle respTable,
 200                                                                                  DT_ObjectHandle object1,
 201                                                                                  DT_ObjectHandle object2,
 202                                                                                  const DT_CollData *coll_data);
 203
 204 /* For each pair of objects multiple responses can be defined. A response is a callback
 205    together with its response type and client data. */
 206
 207 /* Responses can be defined for all pairs of response classes... */
 208         extern DECLSPEC void DT_AddDefaultResponse(DT_RespTableHandle respTable,
 209                                                                                            DT_ResponseCallback response,
 210                                                                                            DT_ResponseType type, void *client_data);
 211
 212         extern DECLSPEC void DT_RemoveDefaultResponse(DT_RespTableHandle respTable,
 213                                                                                                   DT_ResponseCallback response);
 214 /* ...per response class... */
 215         extern DECLSPEC void DT_AddClassResponse(DT_RespTableHandle respTable,
 216                                                                                          DT_ResponseClass responseClass,
 217                                                                                          DT_ResponseCallback response,
 218                                                                                          DT_ResponseType type, void *client_data);
 219
 220         extern DECLSPEC void DT_RemoveClassResponse(DT_RespTableHandle respTable,
 221                                                                                                 DT_ResponseClass responseClass,
 222                                                                                                 DT_ResponseCallback response);
 223
 224 /* ... and per pair of response classes...*/
 225         extern DECLSPEC void DT_AddPairResponse(DT_RespTableHandle respTable,
 226                                                                                         DT_ResponseClass responseClass1,
 227                                                                                         DT_ResponseClass responseClass2,
 228                                                                                         DT_ResponseCallback response,
 229                                                                                         DT_ResponseType type, void *client_data);
 230         extern DECLSPEC void DT_RemovePairResponse(DT_RespTableHandle respTable,
 231                                                                                            DT_ResponseClass responseClass1,
 232                                                                                            DT_ResponseClass responseClass2,
 233                                                                                            DT_ResponseCallback response);
 234
 235 /* The next command calls the response callbacks for all intersecting pairs of objects in a scene.
 236    'DT_Test' returns the number of pairs of objects for which callbacks have been called.
 237 */
 238
 239         extern DECLSPEC DT_Count DT_Test(DT_SceneHandle scene, DT_RespTableHandle respTable);
 240
 241 /* Set the maximum relative error in the closest points and penetration depth
 242    computation. The default for `max_error' is 1.0e-3. Larger errors result
 243    in better performance. Non-positive error tolerances are ignored.
 244 */
 245
 246         extern DECLSPEC void DT_SetAccuracy(DT_Scalar max_error);
 247
 248 /* Set the maximum tolerance on relative errors due to rounding.  The default for `tol_error'
 249    is the machine epsilon. Very large tolerances result in false collisions. Setting tol_error too small
 250    results in missed collisions. Non-positive error tolerances are ignored.
 251 */
 252
 253         extern DECLSPEC void DT_SetTolerance(DT_Scalar tol_error);
 254
 255
 256 /* This function returns the client pointer to the first object in a scene hit by the ray
 257    (actually a line segment) defined by the points 'from' en 'to'. The spot is the hit point
 258    on the object in local coordinates. 'normal' is the normal to the surface of the object in
 259    world coordinates. The ignore_client pointer is used to make one of the objects transparent.
 260
 261    NB: Currently ray tests are implemented for spheres, boxes, and meshes only!!
 262 */
 263
 264         extern DECLSPEC void *DT_RayCast(DT_SceneHandle scene, void *ignore_client,
 265                                                                          const DT_Vector3 source, const DT_Vector3 target,
 266                                                                          DT_Scalar max_param, DT_Scalar *param, DT_Vector3 normal);
 267
 268 /* Similar, only here a single object is tested and a boolean is returned */
 269
 270         extern DECLSPEC DT_Bool DT_ObjectRayCast(DT_ObjectHandle object,
 271                                                                                          const DT_Vector3 source, const DT_Vector3 target,
 272                                                                                          DT_Scalar max_param, DT_Scalar *param, DT_Vector3 normal);
 273
 274
 275 #ifdef __cplusplus
 276 }
 277 #endif
 278
 279 #endif