1 /*************************************************************************

     2  *                                                                       *

     3  * Open Dynamics Engine, Copyright (C) 2001-2003 Russell L. Smith.       *

     4  * All rights reserved.  Email: russ@q12.org   Web: www.q12.org          *

     5  *                                                                       *

     6  * This library is free software; you can redistribute it and/or         *

     7  * modify it under the terms of EITHER:                                  *

     8  *   (1) The GNU Lesser General Public License as published by the Free  *

     9  *       Software Foundation; either version 2.1 of the License, or (at  *

    10  *       your option) any later version. The text of the GNU Lesser      *

    11  *       General Public License is included with this library in the     *

    12  *       file LICENSE.TXT.                                               *

    13  *   (2) The BSD-style license that is included with this library in     *

    14  *       the file LICENSE-BSD.TXT.                                       *

    15  *                                                                       *

    16  * This library is distributed in the hope that it will be useful,       *

    17  * but WITHOUT ANY WARRANTY; without even the implied warranty of        *

    18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the files    *

    19  * LICENSE.TXT and LICENSE-BSD.TXT for more details.                     *

    20  *                                                                       *

    21  *************************************************************************/

    22 

    23 #ifndef _ODE_COLLISION_H_

    24 #define _ODE_COLLISION_H_

    25 

    26 #include <ode/common.h>

    27 #include <ode/collision_space.h>

    28 #include <ode/contact.h>

    29 

    30 #ifdef __cplusplus

    31 extern "C" {

    32 #endif

    33 

    34 /**

    35  * @defgroup collide Collision Detection

    36  *

    37  * ODE has two main components: a dynamics simulation engine and a collision

    38  * detection engine. The collision engine is given information about the

    39  * shape of each body. At each time step it figures out which bodies touch

    40  * each other and passes the resulting contact point information to the user.

    41  * The user in turn creates contact joints between bodies.

    42  *

    43  * Using ODE's collision detection is optional - an alternative collision

    44  * detection system can be used as long as it can supply the right kinds of

    45  * contact information.

    46  */

    47 

    48 

    49 /* ************************************************************************ */

    50 /* general functions */

    51 

    52 /**

    53  * @brief Destroy a geom, removing it from any space.

    54  *

    55  * Destroy a geom, removing it from any space it is in first. This one

    56  * function destroys a geom of any type, but to create a geom you must call

    57  * a creation function for that type.

    58  *

    59  * When a space is destroyed, if its cleanup mode is 1 (the default) then all

    60  * the geoms in that space are automatically destroyed as well.

    61  *

    62  * @param geom the geom to be destroyed.

    63  * @ingroup collide

    64  */

    65 ODE_API IMPORT_C void dGeomDestroy (dGeomID geom);

    66 

    67 

    68 /**

    69  * @brief Set the user-defined data pointer stored in the geom.

    70  *

    71  * @param geom the geom to hold the data

    72  * @param data the data pointer to be stored

    73  * @ingroup collide

    74  */

    75 ODE_API IMPORT_C void dGeomSetData (dGeomID geom, void* data);

    76 

    77 

    78 /**

    79  * @brief Get the user-defined data pointer stored in the geom.

    80  *

    81  * @param geom the geom containing the data

    82  * @ingroup collide

    83  */

    84 ODE_API IMPORT_C void *dGeomGetData (dGeomID geom);

    85 

    86 

    87 /**

    88  * @brief Set the body associated with a placeable geom.

    89  *

    90  * Setting a body on a geom automatically combines the position vector and

    91  * rotation matrix of the body and geom, so that setting the position or

    92  * orientation of one will set the value for both objects. Setting a body

    93  * ID of zero gives the geom its own position and rotation, independent

    94  * from any body. If the geom was previously connected to a body then its

    95  * new independent position/rotation is set to the current position/rotation

    96  * of the body.

    97  *

    98  * Calling these functions on a non-placeable geom results in a runtime

    99  * error in the debug build of ODE.

   100  *

   101  * @param geom the geom to connect

   102  * @param body the body to attach to the geom

   103  * @ingroup collide

   104  */

   105 ODE_API IMPORT_C void dGeomSetBody (dGeomID geom, dBodyID body);

   106 

   107 

   108 /**

   109  * @brief Get the body associated with a placeable geom.

   110  * @param geom the geom to query.

   111  * @sa dGeomSetBody

   112  * @ingroup collide

   113  */

   114 ODE_API IMPORT_C dBodyID dGeomGetBody (dGeomID geom);

   115 

   116 

   117 /**

   118  * @brief Set the position vector of a placeable geom.

   119  *

   120  * If the geom is attached to a body, the body's position will also be changed.

   121  * Calling this function on a non-placeable geom results in a runtime error in

   122  * the debug build of ODE.

   123  *

   124  * @param geom the geom to set.

   125  * @param x the new X coordinate.

   126  * @param y the new Y coordinate.

   127  * @param z the new Z coordinate.

   128  * @sa dBodySetPosition

   129  * @ingroup collide

   130  */

   131 ODE_API IMPORT_C void dGeomSetPosition (dGeomID geom, dReal x, dReal y, dReal z);

   132 

   133 

   134 /**

   135  * @brief Set the rotation matrix of a placeable geom.

   136  *

   137  * If the geom is attached to a body, the body's rotation will also be changed.

   138  * Calling this function on a non-placeable geom results in a runtime error in

   139  * the debug build of ODE.

   140  *

   141  * @param geom the geom to set.

   142  * @param R the new rotation matrix.

   143  * @sa dBodySetRotation

   144  * @ingroup collide

   145  */

   146 ODE_API IMPORT_C void dGeomSetRotation (dGeomID geom, const dMatrix3 R);

   147 

   148 

   149 /**

   150  * @brief Set the rotation of a placeable geom.

   151  *

   152  * If the geom is attached to a body, the body's rotation will also be changed.

   153  *

   154  * Calling this function on a non-placeable geom results in a runtime error in

   155  * the debug build of ODE.

   156  *

   157  * @param geom the geom to set.

   158  * @param Q the new rotation.

   159  * @sa dBodySetQuaternion

   160  * @ingroup collide

   161  */

   162 ODE_API IMPORT_C void dGeomSetQuaternion (dGeomID geom, const dQuaternion Q);

   163 

   164 

   165 /**

   166  * @brief Get the position vector of a placeable geom.

   167  *

   168  * If the geom is attached to a body, the body's position will be returned.

   169  *

   170  * Calling this function on a non-placeable geom results in a runtime error in

   171  * the debug build of ODE.

   172  *

   173  * @param geom the geom to query.

   174  * @returns A pointer to the geom's position vector.

   175  * @remarks The returned value is a pointer to the geom's internal

   176  *          data structure. It is valid until any changes are made

   177  *          to the geom.

   178  * @sa dBodyGetPosition

   179  * @ingroup collide

   180  */

   181 ODE_API IMPORT_C const dReal * dGeomGetPosition (dGeomID geom);

   182 

   183 

   184 /**

   185  * @brief Copy the position of a geom into a vector.

   186  * @ingroup collide

   187  * @param geom  the geom to query

   188  * @param pos   a copy of the geom position

   189  * @sa dGeomGetPosition

   190  */

   191 ODE_API IMPORT_C void dGeomCopyPosition (dGeomID geom, dVector3 pos);

   192 

   193 

   194 /**

   195  * @brief Get the rotation matrix of a placeable geom.

   196  *

   197  * If the geom is attached to a body, the body's rotation will be returned.

   198  *

   199  * Calling this function on a non-placeable geom results in a runtime error in

   200  * the debug build of ODE.

   201  *

   202  * @param geom the geom to query.

   203  * @returns A pointer to the geom's rotation matrix.

   204  * @remarks The returned value is a pointer to the geom's internal

   205  *          data structure. It is valid until any changes are made

   206  *          to the geom.

   207  * @sa dBodyGetRotation

   208  * @ingroup collide

   209  */

   210 ODE_API IMPORT_C const dReal * dGeomGetRotation (dGeomID geom);

   211 

   212 

   213 /**

   214  * @brief Get the rotation matrix of a placeable geom.

   215  *

   216  * If the geom is attached to a body, the body's rotation will be returned.

   217  *

   218  * Calling this function on a non-placeable geom results in a runtime error in

   219  * the debug build of ODE.

   220  *

   221  * @param geom   the geom to query.

   222  * @param R      a copy of the geom rotation

   223  * @sa dGeomGetRotation

   224  * @ingroup collide

   225  */

   226 ODE_API IMPORT_C void dGeomCopyRotation(dGeomID geom, dMatrix3 R);

   227 

   228 

   229 /**

   230  * @brief Get the rotation quaternion of a placeable geom.

   231  *

   232  * If the geom is attached to a body, the body's quaternion will be returned.

   233  *

   234  * Calling this function on a non-placeable geom results in a runtime error in

   235  * the debug build of ODE.

   236  *

   237  * @param geom the geom to query.

   238  * @param result a copy of the rotation quaternion.

   239  * @sa dBodyGetQuaternion

   240  * @ingroup collide

   241  */

   242 ODE_API IMPORT_C void dGeomGetQuaternion (dGeomID geom, dQuaternion result);

   243 

   244 

   245 /**

   246  * @brief Return the axis-aligned bounding box.

   247  *

   248  * Return in aabb an axis aligned bounding box that surrounds the given geom.

   249  * The aabb array has elements (minx, maxx, miny, maxy, minz, maxz). If the

   250  * geom is a space, a bounding box that surrounds all contained geoms is

   251  * returned.

   252  *

   253  * This function may return a pre-computed cached bounding box, if it can

   254  * determine that the geom has not moved since the last time the bounding

   255  * box was computed.

   256  *

   257  * @param geom the geom to query

   258  * @param aabb the returned bounding box

   259  * @ingroup collide

   260  */

   261 ODE_API IMPORT_C void dGeomGetAABB (dGeomID geom, dReal aabb[6]);

   262 

   263 

   264 /**

   265  * @brief Determing if a geom is a space.

   266  * @param geom the geom to query

   267  * @returns Non-zero if the geom is a space, zero otherwise.

   268  * @ingroup collide

   269  */

   270 ODE_API IMPORT_C int dGeomIsSpace (dGeomID geom);

   271 

   272 

   273 /**

   274  * @brief Query for the space containing a particular geom.

   275  * @param geom the geom to query

   276  * @returns The space that contains the geom, or NULL if the geom is

   277  *          not contained by a space.

   278  * @ingroup collide

   279  */

   280 ODE_API IMPORT_C dSpaceID dGeomGetSpace (dGeomID);

   281 

   282 

   283 /**

   284  * @brief Given a geom, this returns its class.

   285  *

   286  * The ODE classes are:

   287  *  @li dSphereClass

   288  *  @li dBoxClass

   289  *  @li dCylinderClass

   290  *  @li dPlaneClass

   291  *  @li dRayClass

   292  *  @li dConvexClass

   293  *  @li dGeomTransformClass

   294  *  @li dTriMeshClass

   295  *  @li dSimpleSpaceClass

   296  *  @li dQuadTreeSpaceClass

   297  *  @li dFirstUserClass

   298  *  @li dLastUserClass

   299  *

   300  * User-defined class will return their own number.

   301  *

   302  * @param geom the geom to query

   303  * @returns The geom class ID.

   304  * @ingroup collide

   305  */

   306 ODE_API IMPORT_C int dGeomGetClass (dGeomID geom);

   307 

   308 

   309 /**

   310  * @brief Set the "category" bitfield for the given geom.

   311  *

   312  * The category bitfield is used by spaces to govern which geoms will

   313  * interact with each other. The bitfield is guaranteed to be at least

   314  * 32 bits wide. The default category values for newly created geoms

   315  * have all bits set.

   316  *

   317  * @param geom the geom to set

   318  * @param bits the new bitfield value

   319  * @ingroup collide

   320  */

   321 ODE_API IMPORT_C void dGeomSetCategoryBits (dGeomID geom, unsigned long bits);

   322 

   323 

   324 /**

   325  * @brief Set the "collide" bitfield for the given geom.

   326  *

   327  * The collide bitfield is used by spaces to govern which geoms will

   328  * interact with each other. The bitfield is guaranteed to be at least

   329  * 32 bits wide. The default category values for newly created geoms

   330  * have all bits set.

   331  *

   332  * @param geom the geom to set

   333  * @param bits the new bitfield value

   334  * @ingroup collide

   335  */

   336 ODE_API IMPORT_C void dGeomSetCollideBits (dGeomID geom, unsigned long bits);

   337 

   338 

   339 /**

   340  * @brief Get the "category" bitfield for the given geom.

   341  *

   342  * @param geom the geom to set

   343  * @param bits the new bitfield value

   344  * @sa dGeomSetCategoryBits

   345  * @ingroup collide

   346  */

   347 ODE_API IMPORT_C unsigned long dGeomGetCategoryBits (dGeomID);

   348 

   349 

   350 /**

   351  * @brief Get the "collide" bitfield for the given geom.

   352  *

   353  * @param geom the geom to set

   354  * @param bits the new bitfield value

   355  * @sa dGeomSetCollideBits

   356  * @ingroup collide

   357  */

   358 ODE_API IMPORT_C unsigned long dGeomGetCollideBits (dGeomID);

   359 

   360 

   361 /**

   362  * @brief Enable a geom.

   363  *

   364  * Disabled geoms are completely ignored by dSpaceCollide and dSpaceCollide2,

   365  * although they can still be members of a space. New geoms are created in

   366  * the enabled state.

   367  *

   368  * @param geom   the geom to enable

   369  * @sa dGeomDisable

   370  * @sa dGeomIsEnabled

   371  * @ingroup collide

   372  */

   373 ODE_API IMPORT_C void dGeomEnable (dGeomID geom);

   374 

   375 

   376 /**

   377  * @brief Disable a geom.

   378  *

   379  * Disabled geoms are completely ignored by dSpaceCollide and dSpaceCollide2,

   380  * although they can still be members of a space. New geoms are created in

   381  * the enabled state.

   382  *

   383  * @param geom   the geom to disable

   384  * @sa dGeomDisable

   385  * @sa dGeomIsEnabled

   386  * @ingroup collide

   387  */

   388 ODE_API IMPORT_C void dGeomDisable (dGeomID geom);

   389 

   390 

   391 /**

   392  * @brief Check to see if a geom is enabled.

   393  *

   394  * Disabled geoms are completely ignored by dSpaceCollide and dSpaceCollide2,

   395  * although they can still be members of a space. New geoms are created in

   396  * the enabled state.

   397  *

   398  * @param geom   the geom to query

   399  * @returns Non-zero if the geom is enabled, zero otherwise.

   400  * @sa dGeomDisable

   401  * @sa dGeomIsEnabled

   402  * @ingroup collide

   403  */

   404 ODE_API IMPORT_C int dGeomIsEnabled (dGeomID geom);

   405 

   406 /* ************************************************************************ */

   407 /* geom offset from body */

   408 

   409 /**

   410  * @brief Set the local offset position of a geom from its body.

   411  *

   412  * Sets the geom's positional offset in local coordinates.

   413  * After this call, the geom will be at a new position determined from the

   414  * body's position and the offset.

   415  * The geom must be attached to a body.

   416  * If the geom did not have an offset, it is automatically created.

   417  *

   418  * @param geom the geom to set.

   419  * @param x the new X coordinate.

   420  * @param y the new Y coordinate.

   421  * @param z the new Z coordinate.

   422  * @ingroup collide

   423  */

   424 ODE_API IMPORT_C void dGeomSetOffsetPosition (dGeomID geom, dReal x, dReal y, dReal z);

   425 

   426 

   427 /**

   428  * @brief Set the local offset rotation matrix of a geom from its body.

   429  *

   430  * Sets the geom's rotational offset in local coordinates.

   431  * After this call, the geom will be at a new position determined from the

   432  * body's position and the offset.

   433  * The geom must be attached to a body.

   434  * If the geom did not have an offset, it is automatically created.

   435  *

   436  * @param geom the geom to set.

   437  * @param R the new rotation matrix.

   438  * @ingroup collide

   439  */

   440 ODE_API IMPORT_C void dGeomSetOffsetRotation (dGeomID geom, const dMatrix3 R);

   441 

   442 

   443 /**

   444  * @brief Set the local offset rotation of a geom from its body.

   445  *

   446  * Sets the geom's rotational offset in local coordinates.

   447  * After this call, the geom will be at a new position determined from the

   448  * body's position and the offset.

   449  * The geom must be attached to a body.

   450  * If the geom did not have an offset, it is automatically created.

   451  *

   452  * @param geom the geom to set.

   453  * @param Q the new rotation.

   454  * @ingroup collide

   455  */

   456 ODE_API IMPORT_C void dGeomSetOffsetQuaternion (dGeomID geom, const dQuaternion Q);

   457 

   458 

   459 /**

   460  * @brief Set the offset position of a geom from its body.

   461  *

   462  * Sets the geom's positional offset to move it to the new world

   463  * coordinates.

   464  * After this call, the geom will be at the world position passed in,

   465  * and the offset will be the difference from the current body position.

   466  * The geom must be attached to a body.

   467  * If the geom did not have an offset, it is automatically created.

   468  *

   469  * @param geom the geom to set.

   470  * @param x the new X coordinate.

   471  * @param y the new Y coordinate.

   472  * @param z the new Z coordinate.

   473  * @ingroup collide

   474  */

   475 ODE_API IMPORT_C void dGeomSetOffsetWorldPosition (dGeomID geom, dReal x, dReal y, dReal z);

   476 

   477 

   478 /**

   479  * @brief Set the offset rotation of a geom from its body.

   480  *

   481  * Sets the geom's rotational offset to orient it to the new world

   482  * rotation matrix.

   483  * After this call, the geom will be at the world orientation passed in,

   484  * and the offset will be the difference from the current body orientation.

   485  * The geom must be attached to a body.

   486  * If the geom did not have an offset, it is automatically created.

   487  *

   488  * @param geom the geom to set.

   489  * @param R the new rotation matrix.

   490  * @ingroup collide

   491  */

   492 ODE_API IMPORT_C void dGeomSetOffsetWorldRotation (dGeomID geom, const dMatrix3 R);

   493 

   494 

   495 /**

   496  * @brief Set the offset rotation of a geom from its body.

   497  *

   498  * Sets the geom's rotational offset to orient it to the new world

   499  * rotation matrix.

   500  * After this call, the geom will be at the world orientation passed in,

   501  * and the offset will be the difference from the current body orientation.

   502  * The geom must be attached to a body.

   503  * If the geom did not have an offset, it is automatically created.

   504  *

   505  * @param geom the geom to set.

   506  * @param Q the new rotation.

   507  * @ingroup collide

   508  */

   509 ODE_API IMPORT_C void dGeomSetOffsetWorldQuaternion (dGeomID geom, const dQuaternion);

   510 

   511 

   512 /**

   513  * @brief Clear any offset from the geom.

   514  *

   515  * If the geom has an offset, it is eliminated and the geom is

   516  * repositioned at the body's position.  If the geom has no offset,

   517  * this function does nothing.

   518  * This is more efficient than calling dGeomSetOffsetPosition(zero)

   519  * and dGeomSetOffsetRotation(identiy), because this function actually

   520  * eliminates the offset, rather than leaving it as the identity transform.

   521  *

   522  * @param geom the geom to have its offset destroyed.

   523  * @ingroup collide

   524  */

   525 ODE_API IMPORT_C void dGeomClearOffset(dGeomID geom);

   526 

   527 

   528 /**

   529  * @brief Check to see whether the geom has an offset.

   530  *

   531  * This function will return non-zero if the offset has been created.

   532  * Note that there is a difference between a geom with no offset,

   533  * and a geom with an offset that is the identity transform.

   534  * In the latter case, although the observed behaviour is identical,

   535  * there is a unnecessary computation involved because the geom will

   536  * be applying the transform whenever it needs to recalculate its world

   537  * position.

   538  *

   539  * @param geom the geom to query.

   540  * @returns Non-zero if the geom has an offset, zero otherwise.

   541  * @ingroup collide

   542  */

   543 ODE_API IMPORT_C int dGeomIsOffset(dGeomID geom);

   544 

   545 

   546 /**

   547  * @brief Get the offset position vector of a geom.

   548  *

   549  * Returns the positional offset of the geom in local coordinates.

   550  * If the geom has no offset, this function returns the zero vector.

   551  *

   552  * @param geom the geom to query.

   553  * @returns A pointer to the geom's offset vector.

   554  * @remarks The returned value is a pointer to the geom's internal

   555  *          data structure. It is valid until any changes are made

   556  *          to the geom.

   557  * @ingroup collide

   558  */

   559 ODE_API IMPORT_C const dReal * dGeomGetOffsetPosition (dGeomID geom);

   560 

   561 

   562 /**

   563  * @brief Copy the offset position vector of a geom.

   564  *

   565  * Returns the positional offset of the geom in local coordinates.

   566  * If the geom has no offset, this function returns the zero vector.

   567  *

   568  * @param geom   the geom to query.

   569  * @param pos    returns the offset position

   570  * @ingroup collide

   571  */

   572 ODE_API IMPORT_C void dGeomCopyOffsetPosition (dGeomID geom, dVector3 pos);

   573 

   574 

   575 /**

   576  * @brief Get the offset rotation matrix of a geom.

   577  *

   578  * Returns the rotational offset of the geom in local coordinates.

   579  * If the geom has no offset, this function returns the identity

   580  * matrix.

   581  *

   582  * @param geom the geom to query.

   583  * @returns A pointer to the geom's offset rotation matrix.

   584  * @remarks The returned value is a pointer to the geom's internal

   585  *          data structure. It is valid until any changes are made

   586  *          to the geom.

   587  * @ingroup collide

   588  */

   589 ODE_API IMPORT_C const dReal * dGeomGetOffsetRotation (dGeomID geom);

   590 

   591 

   592 /**

   593  * @brief Copy the offset rotation matrix of a geom.

   594  *

   595  * Returns the rotational offset of the geom in local coordinates.

   596  * If the geom has no offset, this function returns the identity

   597  * matrix.

   598  *

   599  * @param geom   the geom to query.

   600  * @param R      returns the rotation matrix.

   601  * @ingroup collide

   602  */

   603 ODE_API IMPORT_C void dGeomCopyOffsetRotation (dGeomID geom, dMatrix3 R);

   604 

   605 

   606 /**

   607  * @brief Get the offset rotation quaternion of a geom.

   608  *

   609  * Returns the rotation offset of the geom as a quaternion.

   610  * If the geom has no offset, the identity quaternion is returned.

   611  *

   612  * @param geom the geom to query.

   613  * @param result a copy of the rotation quaternion.

   614  * @ingroup collide

   615  */

   616 ODE_API IMPORT_C void dGeomGetOffsetQuaternion (dGeomID geom, dQuaternion result);

   617 

   618 

   619 /* ************************************************************************ */

   620 /* collision detection */

   621 

   622 /**

   623  *

   624  * @brief Given two geoms o1 and o2 that potentially intersect,

   625  * generate contact information for them.

   626  *

   627  * Internally, this just calls the correct class-specific collision

   628  * functions for o1 and o2.

   629  *

   630  * @param o1 The first geom to test.

   631  * @param o2 The second geom to test.

   632  *

   633  * @param flags The flags specify how contacts should be generated if

   634  * the geoms touch. The lower 16 bits of flags is an integer that

   635  * specifies the maximum number of contact points to generate. You must

   636  * ask for at least one contact. All other bits in flags must be zero.

   637  * In the future the other bits may be used to select from different

   638  * contact generation strategies.

   639  *

   640  * @param contact Points to an array of dContactGeom structures. The array

   641  * must be able to hold at least the maximum number of contacts. These

   642  * dContactGeom structures may be embedded within larger structures in the

   643  * array -- the skip parameter is the byte offset from one dContactGeom to

   644  * the next in the array. If skip is sizeof(dContactGeom) then contact

   645  * points to a normal (C-style) array. It is an error for skip to be smaller

   646  * than sizeof(dContactGeom).

   647  *

   648  * @returns If the geoms intersect, this function returns the number of contact

   649  * points generated (and updates the contact array), otherwise it returns 0

   650  * (and the contact array is not touched).

   651  *

   652  * @remarks If a space is passed as o1 or o2 then this function will collide

   653  * all objects contained in o1 with all objects contained in o2, and return

   654  * the resulting contact points. This method for colliding spaces with geoms

   655  * (or spaces with spaces) provides no user control over the individual

   656  * collisions. To get that control, use dSpaceCollide or dSpaceCollide2 instead.

   657  *

   658  * @remarks If o1 and o2 are the same geom then this function will do nothing

   659  * and return 0. Technically speaking an object intersects with itself, but it

   660  * is not useful to find contact points in this case.

   661  *

   662  * @remarks This function does not care if o1 and o2 are in the same space or not

   663  * (or indeed if they are in any space at all).

   664  *

   665  * @ingroup collide

   666  */

   667 ODE_API IMPORT_C int dCollide (dGeomID o1, dGeomID o2, int flags, dContactGeom *contact,

   668 	      int skip);

   669 

   670 /**

   671  * @brief Determines which pairs of geoms in a space may potentially intersect,

   672  * and calls the callback function for each candidate pair.

   673  *

   674  * @param space The space to test.

   675  *

   676  * @param data Passed from dSpaceCollide directly to the callback

   677  * function. Its meaning is user defined. The o1 and o2 arguments are the

   678  * geoms that may be near each other.

   679  *

   680  * @param callback A callback function is of type @ref dNearCallback.

   681  *

   682  * @remarks Other spaces that are contained within the colliding space are

   683  * not treated specially, i.e. they are not recursed into. The callback

   684  * function may be passed these contained spaces as one or both geom

   685  * arguments.

   686  *

   687  * @remarks dSpaceCollide() is guaranteed to pass all intersecting geom

   688  * pairs to the callback function, but may also pass close but

   689  * non-intersecting pairs. The number of these calls depends on the

   690  * internal algorithms used by the space. Thus you should not expect

   691  * that dCollide will return contacts for every pair passed to the

   692  * callback.

   693  *

   694  * @sa dSpaceCollide2

   695  * @ingroup collide

   696  */

   697 ODE_API IMPORT_C void dSpaceCollide (dSpaceID space, void *data, dNearCallback *callback);

   698 

   699 

   700 /**

   701  * @brief Determines which geoms from one space may potentially intersect with 

   702  * geoms from another space, and calls the callback function for each candidate 

   703  * pair. 

   704  *

   705  * @param space1 The first space to test.

   706  *

   707  * @param space2 The second space to test.

   708  *

   709  * @param data Passed from dSpaceCollide directly to the callback

   710  * function. Its meaning is user defined. The o1 and o2 arguments are the

   711  * geoms that may be near each other.

   712  *

   713  * @param callback A callback function is of type @ref dNearCallback.

   714  *

   715  * @remarks This function can also test a single non-space geom against a 

   716  * space. This function is useful when there is a collision hierarchy, i.e. 

   717  * when there are spaces that contain other spaces.

   718  *

   719  * @remarks Other spaces that are contained within the colliding space are

   720  * not treated specially, i.e. they are not recursed into. The callback

   721  * function may be passed these contained spaces as one or both geom

   722  * arguments.

   723  *

   724  * @remarks dSpaceCollide2() is guaranteed to pass all intersecting geom

   725  * pairs to the callback function, but may also pass close but

   726  * non-intersecting pairs. The number of these calls depends on the

   727  * internal algorithms used by the space. Thus you should not expect

   728  * that dCollide will return contacts for every pair passed to the

   729  * callback.

   730  *

   731  * @sa dSpaceCollide

   732  * @ingroup collide

   733  */

   734 ODE_API IMPORT_C void dSpaceCollide2 (dGeomID space1, dGeomID space2, void *data, dNearCallback *callback);

   735 

   736 

   737 /* ************************************************************************ */

   738 /* standard classes */

   739 

   740 /* the maximum number of user classes that are supported */

   741 enum {

   742   dMaxUserClasses = 4

   743 };

   744 

   745 /* class numbers - each geometry object needs a unique number */

   746 enum {

   747   dSphereClass = 0,

   748   dBoxClass,

   749   dCapsuleClass,

   750   dCylinderClass,

   751   dPlaneClass,

   752   dRayClass,

   753   dConvexClass,

   754   dGeomTransformClass,

   755   dTriMeshClass,

   756   dHeightfieldClass,

   757 

   758   dFirstSpaceClass,

   759   dSimpleSpaceClass = dFirstSpaceClass,

   760   dQuadTreeSpaceClass,

   761   dLastSpaceClass = dQuadTreeSpaceClass,

   762 

   763   dFirstUserClass,

   764   dLastUserClass = dFirstUserClass + dMaxUserClasses - 1,

   765   dGeomNumClasses

   766 };

   767 

   768 

   769 /**

   770  * @defgroup collide_sphere Sphere Class

   771  * @ingroup collide

   772  */

   773 

   774 /**

   775  * @brief Create a sphere geom of the given radius, and return its ID. 

   776  *

   777  * @param space   a space to contain the new geom. May be null.

   778  * @param radius  the radius of the sphere.

   779  *

   780  * @returns A new sphere geom.

   781  *

   782  * @remarks The point of reference for a sphere is its center.

   783  *

   784  * @sa dGeomDestroy

   785  * @sa dGeomSphereSetRadius

   786  * @ingroup collide_sphere

   787  */

   788 ODE_API IMPORT_C dGeomID dCreateSphere (dSpaceID space, dReal radius);

   789 

   790 

   791 /**

   792  * @brief Set the radius of a sphere geom.

   793  *

   794  * @param sphere  the sphere to set.

   795  * @param radius  the new radius.

   796  *

   797  * @sa dGeomSphereGetRadius

   798  * @ingroup collide_sphere

   799  */

   800 ODE_API IMPORT_C void dGeomSphereSetRadius (dGeomID sphere, dReal radius);

   801 

   802 

   803 /**

   804  * @brief Retrieves the radius of a sphere geom.

   805  *

   806  * @param sphere  the sphere to query.

   807  *

   808  * @sa dGeomSphereSetRadius

   809  * @ingroup collide_sphere

   810  */

   811 ODE_API IMPORT_C dReal dGeomSphereGetRadius (dGeomID sphere);

   812 

   813 

   814 /**

   815  * @brief Calculate the depth of the a given point within a sphere.

   816  *

   817  * @param sphere  the sphere to query.

   818  * @param x       the X coordinate of the point.

   819  * @param y       the Y coordinate of the point.

   820  * @param z       the Z coordinate of the point.

   821  *

   822  * @returns The depth of the point. Points inside the sphere will have a 

   823  * positive depth, points outside it will have a negative depth, and points

   824  * on the surface will have a depth of zero.

   825  *

   826  * @ingroup collide_sphere

   827  */

   828 ODE_API IMPORT_C dReal dGeomSpherePointDepth (dGeomID sphere, dReal x, dReal y, dReal z);

   829 

   830 

   831 //--> Convex Functions

   832 ODE_API IMPORT_C dGeomID dCreateConvex (dSpaceID space,

   833 			       dReal *_planes,

   834 			       unsigned int _planecount,

   835 			       dReal *_points,

   836 			       unsigned int _pointcount,unsigned int *_polygons);

   837 

   838 ODE_API IMPORT_C void dGeomSetConvex (dGeomID g,

   839 			     dReal *_planes,

   840 			     unsigned int _count,

   841 			     dReal *_points,

   842 			     unsigned int _pointcount,unsigned int *_polygons);

   843 //<-- Convex Functions

   844 

   845 /**

   846  * @defgroup collide_box Box Class

   847  * @ingroup collide

   848  */

   849 

   850 /**

   851  * @brief Create a box geom with the provided side lengths.

   852  *

   853  * @param space   a space to contain the new geom. May be null.

   854  * @param lx      the length of the box along the X axis

   855  * @param ly      the length of the box along the Y axis

   856  * @param lz      the length of the box along the Z axis

   857  *

   858  * @returns A new box geom.

   859  *

   860  * @remarks The point of reference for a box is its center.

   861  *

   862  * @sa dGeomDestroy

   863  * @sa dGeomBoxSetLengths

   864  * @ingroup collide_box

   865  */

   866 ODE_API IMPORT_C dGeomID dCreateBox (dSpaceID space, dReal lx, dReal ly, dReal lz);

   867 

   868 

   869 /**

   870  * @brief Set the side lengths of the given box.

   871  *

   872  * @param box  the box to set

   873  * @param lx      the length of the box along the X axis

   874  * @param ly      the length of the box along the Y axis

   875  * @param lz      the length of the box along the Z axis

   876  *

   877  * @sa dGeomBoxGetLengths

   878  * @ingroup collide_box

   879  */

   880 ODE_API IMPORT_C void dGeomBoxSetLengths (dGeomID box, dReal lx, dReal ly, dReal lz);

   881 

   882 

   883 /**

   884  * @brief Get the side lengths of a box.

   885  *

   886  * @param box     the box to query

   887  * @param result  the returned side lengths

   888  *

   889  * @sa dGeomBoxSetLengths

   890  * @ingroup collide_box

   891  */

   892 ODE_API IMPORT_C void dGeomBoxGetLengths (dGeomID box, dVector3 result);

   893 

   894 

   895 /**

   896  * @brief Return the depth of a point in a box.

   897  * 

   898  * @param box  the box to query

   899  * @param x    the X coordinate of the point to test.

   900  * @param y    the Y coordinate of the point to test.

   901  * @param z    the Z coordinate of the point to test.

   902  *

   903  * @returns The depth of the point. Points inside the box will have a 

   904  * positive depth, points outside it will have a negative depth, and points

   905  * on the surface will have a depth of zero.

   906  */

   907 ODE_API IMPORT_C dReal dGeomBoxPointDepth (dGeomID box, dReal x, dReal y, dReal z);

   908 

   909 

   910 ODE_API IMPORT_C dGeomID dCreatePlane (dSpaceID space, dReal a, dReal b, dReal c, dReal d);

   911 ODE_API IMPORT_C void dGeomPlaneSetParams (dGeomID plane, dReal a, dReal b, dReal c, dReal d);

   912 ODE_API IMPORT_C void dGeomPlaneGetParams (dGeomID plane, dVector4 result);

   913 ODE_API IMPORT_C dReal dGeomPlanePointDepth (dGeomID plane, dReal x, dReal y, dReal z);

   914 

   915 ODE_API IMPORT_C dGeomID dCreateCapsule (dSpaceID space, dReal radius, dReal length);

   916 ODE_API IMPORT_C void dGeomCapsuleSetParams (dGeomID ccylinder, dReal radius, dReal length);

   917 ODE_API IMPORT_C void dGeomCapsuleGetParams (dGeomID ccylinder, dReal *radius, dReal *length);

   918 ODE_API IMPORT_C dReal dGeomCapsulePointDepth (dGeomID ccylinder, dReal x, dReal y, dReal z);

   919 

   920 // For now we want to have a backwards compatible C-API, note: C++ API is not.

   921 #define dCreateCCylinder dCreateCapsule

   922 #define dGeomCCylinderSetParams dGeomCapsuleSetParams

   923 #define dGeomCCylinderGetParams dGeomCapsuleGetParams

   924 #define dGeomCCylinderPointDepth dGeomCapsulePointDepth

   925 #define dCCylinderClass dCapsuleClass

   926 

   927 ODE_API IMPORT_C dGeomID dCreateCylinder (dSpaceID space, dReal radius, dReal length);

   928 ODE_API IMPORT_C void dGeomCylinderSetParams (dGeomID cylinder, dReal radius, dReal length);

   929 ODE_API IMPORT_C void dGeomCylinderGetParams (dGeomID cylinder, dReal *radius, dReal *length);

   930 

   931 ODE_API IMPORT_C dGeomID dCreateRay (dSpaceID space, dReal length);

   932 ODE_API IMPORT_C void dGeomRaySetLength (dGeomID ray, dReal length);

   933 ODE_API IMPORT_C dReal dGeomRayGetLength (dGeomID ray);

   934 ODE_API IMPORT_C void dGeomRaySet (dGeomID ray, dReal px, dReal py, dReal pz,

   935 		  dReal dx, dReal dy, dReal dz);

   936 ODE_API IMPORT_C void dGeomRayGet (dGeomID ray, dVector3 start, dVector3 dir);

   937 

   938 /*

   939  * Set/get ray flags that influence ray collision detection.

   940  * These flags are currently only noticed by the trimesh collider, because

   941  * they can make a major differences there.

   942  */

   943 ODE_API IMPORT_C void dGeomRaySetParams (dGeomID g, int FirstContact, int BackfaceCull);

   944 ODE_API IMPORT_C void dGeomRayGetParams (dGeomID g, int *FirstContact, int *BackfaceCull);

   945 ODE_API IMPORT_C void dGeomRaySetClosestHit (dGeomID g, int closestHit);

   946 ODE_API IMPORT_C int dGeomRayGetClosestHit (dGeomID g);

   947 

   948 ODE_API IMPORT_C dGeomID dCreateGeomTransform (dSpaceID space);

   949 ODE_API IMPORT_C void dGeomTransformSetGeom (dGeomID g, dGeomID obj);

   950 ODE_API IMPORT_C dGeomID dGeomTransformGetGeom (dGeomID g);

   951 ODE_API IMPORT_C void dGeomTransformSetCleanup (dGeomID g, int mode);

   952 ODE_API IMPORT_C int dGeomTransformGetCleanup (dGeomID g);

   953 ODE_API IMPORT_C void dGeomTransformSetInfo (dGeomID g, int mode);

   954 ODE_API IMPORT_C int dGeomTransformGetInfo (dGeomID g);

   955 

   956 

   957 /* ************************************************************************ */

   958 /* heightfield functions */

   959 

   960 

   961 // Data storage for heightfield data.

   962 struct dxHeightfieldData;

   963 typedef struct dxHeightfieldData* dHeightfieldDataID;

   964 

   965 

   966 /**

   967  * @brief Callback prototype

   968  *

   969  * Used by the callback heightfield data type to sample a height for a

   970  * given cell position.

   971  *

   972  * @param p_user_data User data specified when creating the dHeightfieldDataID

   973  * @param x The index of a sample in the local x axis. It is a value

   974  * in the range zero to ( nWidthSamples - 1 ).

   975  * @param x The index of a sample in the local z axis. It is a value

   976  * in the range zero to ( nDepthSamples - 1 ).

   977  *

   978  * @return The sample height which is then scaled and offset using the

   979  * values specified when the heightfield data was created.

   980  *

   981  * @ingroup collide

   982  */

   983 typedef dReal dHeightfieldGetHeight( void* p_user_data, int x, int z );

   984 

   985 

   986 

   987 /**

   988  * @brief Creates a heightfield geom.

   989  *

   990  * Uses the information in the given dHeightfieldDataID to construct

   991  * a geom representing a heightfield in a collision space.

   992  *

   993  * @param space The space to add the geom to.

   994  * @param data The dHeightfieldDataID created by dGeomHeightfieldDataCreate and

   995  * setup by dGeomHeightfieldDataBuildCallback, dGeomHeightfieldDataBuildByte,

   996  * dGeomHeightfieldDataBuildShort or dGeomHeightfieldDataBuildFloat.

   997  * @param bPlaceable If non-zero this geom can be transformed in the world using the

   998  * usual functions such as dGeomSetPosition and dGeomSetRotation. If the geom is

   999  * not set as placeable, then it uses a fixed orientation where the global y axis

  1000  * represents the dynamic 'height' of the heightfield.

  1001  *

  1002  * @return A geom id to reference this geom in other calls.

  1003  *

  1004  * @ingroup collide

  1005  */

  1006 ODE_API IMPORT_C dGeomID dCreateHeightfield( dSpaceID space,

  1007 					dHeightfieldDataID data, int bPlaceable );

  1008 

  1009 

  1010 /**

  1011  * @brief Creates a new empty dHeightfieldDataID.

  1012  *

  1013  * Allocates a new dHeightfieldDataID and returns it. You must call

  1014  * dGeomHeightfieldDataDestroy to destroy it after the geom has been removed.

  1015  * The dHeightfieldDataID value is used when specifying a data format type.

  1016  *

  1017  * @return A dHeightfieldDataID for use with dGeomHeightfieldDataBuildCallback,

  1018  * dGeomHeightfieldDataBuildByte, dGeomHeightfieldDataBuildShort or

  1019  * dGeomHeightfieldDataBuildFloat.

  1020  * @ingroup collide

  1021  */

  1022 ODE_API IMPORT_C dHeightfieldDataID dGeomHeightfieldDataCreate();

  1023 

  1024 

  1025 /**

  1026  * @brief Destroys a dHeightfieldDataID.

  1027  *

  1028  * Deallocates a given dHeightfieldDataID and all managed resources.

  1029  *

  1030  * @param d A dHeightfieldDataID created by dGeomHeightfieldDataCreate

  1031  * @ingroup collide

  1032  */

  1033 ODE_API IMPORT_C void dGeomHeightfieldDataDestroy( dHeightfieldDataID d );

  1034 

  1035 

  1036 

  1037 /**

  1038  * @brief Configures a dHeightfieldDataID to use a callback to

  1039  * retrieve height data.

  1040  *

  1041  * Before a dHeightfieldDataID can be used by a geom it must be

  1042  * configured to specify the format of the height data.

  1043  * This call specifies that the heightfield data is computed by

  1044  * the user and it should use the given callback when determining

  1045  * the height of a given element of it's shape.

  1046  *

  1047  * @param d A new dHeightfieldDataID created by dGeomHeightfieldDataCreate

  1048  *

  1049  * @param width Specifies the total 'width' of the heightfield along

  1050  * the geom's local x axis.

  1051  * @param depth Specifies the total 'depth' of the heightfield along

  1052  * the geom's local z axis.

  1053  *

  1054  * @param widthSamples Specifies the number of vertices to sample

  1055  * along the width of the heightfield. Each vertex has a corresponding

  1056  * height value which forms the overall shape.

  1057  * Naturally this value must be at least two or more.

  1058  * @param depthSamples Specifies the number of vertices to sample

  1059  * along the depth of the heightfield.

  1060  *

  1061  * @param scale A uniform scale applied to all raw height data.

  1062  * @param offset An offset applied to the scaled height data.

  1063  *

  1064  * @param thickness A value subtracted from the lowest height

  1065  * value which in effect adds an additional cuboid to the base of the

  1066  * heightfield. This is used to prevent geoms from looping under the

  1067  * desired terrain and not registering as a collision. Note that the

  1068  * thickness is not affected by the scale or offset parameters.

  1069  *

  1070  * @param bWrap If non-zero the heightfield will infinitely tile in both

  1071  * directions along the local x and z axes. If zero the heightfield is

  1072  * bounded from zero to width in the local x axis, and zero to depth in

  1073  * the local z axis.

  1074  *

  1075  * @ingroup collide

  1076  */

  1077 ODE_API IMPORT_C void dGeomHeightfieldDataBuildCallback( dHeightfieldDataID d,

  1078 				void* pUserData, dHeightfieldGetHeight* pCallback,

  1079 				dReal width, dReal depth, int widthSamples, int depthSamples,

  1080 				dReal scale, dReal offset, dReal thickness, int bWrap );

  1081 

  1082 /**

  1083  * @brief Configures a dHeightfieldDataID to use height data in byte format.

  1084  *

  1085  * Before a dHeightfieldDataID can be used by a geom it must be

  1086  * configured to specify the format of the height data.

  1087  * This call specifies that the heightfield data is stored as a rectangular

  1088  * array of bytes (8 bit unsigned) representing the height at each sample point.

  1089  *

  1090  * @param d A new dHeightfieldDataID created by dGeomHeightfieldDataCreate

  1091  *

  1092  * @param pHeightData A pointer to the height data.

  1093  * @param bCopyHeightData When non-zero the height data is copied to an

  1094  * internal store. When zero the height data is accessed by reference and

  1095  * so must persist throughout the lifetime of the heightfield.

  1096  *

  1097  * @param width Specifies the total 'width' of the heightfield along

  1098  * the geom's local x axis.

  1099  * @param depth Specifies the total 'depth' of the heightfield along

  1100  * the geom's local z axis.

  1101  *

  1102  * @param widthSamples Specifies the number of vertices to sample

  1103  * along the width of the heightfield. Each vertex has a corresponding

  1104  * height value which forms the overall shape.

  1105  * Naturally this value must be at least two or more.

  1106  * @param depthSamples Specifies the number of vertices to sample

  1107  * along the depth of the heightfield.

  1108  *

  1109  * @param scale A uniform scale applied to all raw height data.

  1110  * @param offset An offset applied to the scaled height data.

  1111  *

  1112  * @param thickness A value subtracted from the lowest height

  1113  * value which in effect adds an additional cuboid to the base of the

  1114  * heightfield. This is used to prevent geoms from looping under the

  1115  * desired terrain and not registering as a collision. Note that the

  1116  * thickness is not affected by the scale or offset parameters.

  1117  *

  1118  * @param bWrap If non-zero the heightfield will infinitely tile in both

  1119  * directions along the local x and z axes. If zero the heightfield is

  1120  * bounded from zero to width in the local x axis, and zero to depth in

  1121  * the local z axis.

  1122  *

  1123  * @ingroup collide

  1124  */

  1125 

  1126 ODE_API IMPORT_C void dGeomHeightfieldDataBuildSingle( dHeightfieldDataID d,

  1127 				const float* pHeightData, int bCopyHeightData,

  1128 				dReal width, dReal depth, int widthSamples, int depthSamples,

  1129 				dReal scale, dReal offset, dReal thickness, int bWrap );

  1130 

  1131 /**

  1132  * @brief Configures a dHeightfieldDataID to use height data in 

  1133  * double precision floating point format.

  1134  *

  1135  * Before a dHeightfieldDataID can be used by a geom it must be