misc/builddeps/linux64/ode/include/ode/collision.h

   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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 dHashSpaceClass
 297  *  @li dQuadTreeSpaceClass
 298  *  @li dFirstUserClass
 299  *  @li dLastUserClass
 300  *
 301  * User-defined class will return their own number.
 302  *
 303  * @param geom the geom to query
 304  * @returns The geom class ID.
 305  * @ingroup collide
 306  */
 307 ODE_API int dGeomGetClass (dGeomID geom);
 308
 309
 310 /**
 311  * @brief Set the "category" bitfield for the given geom.
 312  *
 313  * The category bitfield is used by spaces to govern which geoms will
 314  * interact with each other. The bitfield is guaranteed to be at least
 315  * 32 bits wide. The default category values for newly created geoms
 316  * have all bits set.
 317  *
 318  * @param geom the geom to set
 319  * @param bits the new bitfield value
 320  * @ingroup collide
 321  */
 322 ODE_API void dGeomSetCategoryBits (dGeomID geom, unsigned long bits);
 323
 324
 325 /**
 326  * @brief Set the "collide" bitfield for the given geom.
 327  *
 328  * The collide bitfield is used by spaces to govern which geoms will
 329  * interact with each other. The bitfield is guaranteed to be at least
 330  * 32 bits wide. The default category values for newly created geoms
 331  * have all bits set.
 332  *
 333  * @param geom the geom to set
 334  * @param bits the new bitfield value
 335  * @ingroup collide
 336  */
 337 ODE_API void dGeomSetCollideBits (dGeomID geom, unsigned long bits);
 338
 339
 340 /**
 341  * @brief Get the "category" bitfield for the given geom.
 342  *
 343  * @param geom the geom to set
 344  * @param bits the new bitfield value
 345  * @sa dGeomSetCategoryBits
 346  * @ingroup collide
 347  */
 348 ODE_API unsigned long dGeomGetCategoryBits (dGeomID);
 349
 350
 351 /**
 352  * @brief Get the "collide" bitfield for the given geom.
 353  *
 354  * @param geom the geom to set
 355  * @param bits the new bitfield value
 356  * @sa dGeomSetCollideBits
 357  * @ingroup collide
 358  */
 359 ODE_API unsigned long dGeomGetCollideBits (dGeomID);
 360
 361
 362 /**
 363  * @brief Enable a geom.
 364  *
 365  * Disabled geoms are completely ignored by dSpaceCollide and dSpaceCollide2,
 366  * although they can still be members of a space. New geoms are created in
 367  * the enabled state.
 368  *
 369  * @param geom   the geom to enable
 370  * @sa dGeomDisable
 371  * @sa dGeomIsEnabled
 372  * @ingroup collide
 373  */
 374 ODE_API void dGeomEnable (dGeomID geom);
 375
 376
 377 /**
 378  * @brief Disable a geom.
 379  *
 380  * Disabled geoms are completely ignored by dSpaceCollide and dSpaceCollide2,
 381  * although they can still be members of a space. New geoms are created in
 382  * the enabled state.
 383  *
 384  * @param geom   the geom to disable
 385  * @sa dGeomDisable
 386  * @sa dGeomIsEnabled
 387  * @ingroup collide
 388  */
 389 ODE_API void dGeomDisable (dGeomID geom);
 390
 391
 392 /**
 393  * @brief Check to see if a geom is enabled.
 394  *
 395  * Disabled geoms are completely ignored by dSpaceCollide and dSpaceCollide2,
 396  * although they can still be members of a space. New geoms are created in
 397  * the enabled state.
 398  *
 399  * @param geom   the geom to query
 400  * @returns Non-zero if the geom is enabled, zero otherwise.
 401  * @sa dGeomDisable
 402  * @sa dGeomIsEnabled
 403  * @ingroup collide
 404  */
 405 ODE_API int dGeomIsEnabled (dGeomID geom);
 406
 407
 408 enum
 409 {
 410         dGeomCommonControlClass = 0,
 411         dGeomColliderControlClass = 1
 412 };
 413
 414 enum
 415 {
 416         dGeomCommonAnyControlCode = 0,
 417
 418         dGeomColliderSetMergeSphereContactsControlCode = 1,
 419         dGeomColliderGetMergeSphereContactsControlCode = 2
 420 };
 421
 422 enum
 423 {
 424     dGeomColliderMergeContactsValue__Default = 0, /* Used with Set... to restore default value*/
 425         dGeomColliderMergeContactsValue_None = 1,
 426         dGeomColliderMergeContactsValue_Normals = 2,
 427         dGeomColliderMergeContactsValue_Full = 3
 428 };
 429
 430 /**
 431  * @brief Execute low level control operation for geometry.
 432  *
 433  * The variable the dataSize points to must be initialized before the call.
 434  * If the size does not match the one expected for the control class/code function
 435  * changes it to the size expected and returns failure. This implies the function
 436  * can be called with NULL data and zero size to test if control class/code is supported
 437  * and obtain required data size for it.
 438  *
 439  * dGeomCommonAnyControlCode applies to any control class and returns success if
 440  * at least one control code is available for the given class with given geom.
 441  *
 442  * Currently there are the folliwing control classes supported:
 443  *  @li dGeomColliderControlClass
 444  *
 445  * For dGeomColliderControlClass there are the following codes available:
 446  *  @li dGeomColliderSetMergeSphereContactsControlCode (arg of type int, dGeomColliderMergeContactsValue_*)
 447  *  @li dGeomColliderGetMergeSphereContactsControlCode (arg of type int, dGeomColliderMergeContactsValue_*)
 448  *
 449  * @param geom   the geom to control
 450  * @param controlClass   the control class
 451  * @param controlCode   the control code for the class
 452  * @param dataValue   the control argument pointer
 453  * @param dataSize   the control argument size provided or expected
 454  * @returns Boolean execution status
 455  * @ingroup collide
 456  */
 457 ODE_API int dGeomLowLevelControl (dGeomID geom, int controlClass, int controlCode, void *dataValue, int *dataSize);
 458
 459
 460 /**
 461  * @brief Get world position of a relative point on geom.
 462  *
 463  * Calling this function on a non-placeable geom results in the same point being
 464  * returned.
 465  *
 466  * @ingroup collide
 467  * @param result will contain the result.
 468  */
 469 ODE_API void dGeomGetRelPointPos
 470 (
 471   dGeomID geom, dReal px, dReal py, dReal pz,
 472   dVector3 result
 473 );
 474
 475 /**
 476  * @brief takes a point in global coordinates and returns
 477  * the point's position in geom-relative coordinates.
 478  *
 479  * Calling this function on a non-placeable geom results in the same point being
 480  * returned.
 481  *
 482  * @remarks
 483  * This is the inverse of dGeomGetRelPointPos()
 484  * @ingroup collide
 485  * @param result will contain the result.
 486  */
 487 ODE_API void dGeomGetPosRelPoint
 488 (
 489   dGeomID geom, dReal px, dReal py, dReal pz,
 490   dVector3 result
 491 );
 492
 493 /**
 494  * @brief Convert from geom-local to world coordinates.
 495  *
 496  * Calling this function on a non-placeable geom results in the same vector being
 497  * returned.
 498  *
 499  * @ingroup collide
 500  * @param result will contain the result.
 501  */
 502 ODE_API void dGeomVectorToWorld
 503 (
 504   dGeomID geom, dReal px, dReal py, dReal pz,
 505   dVector3 result
 506 );
 507
 508 /**
 509  * @brief Convert from world to geom-local coordinates.
 510  *
 511  * Calling this function on a non-placeable geom results in the same vector being
 512  * returned.
 513  *
 514  * @ingroup collide
 515  * @param result will contain the result.
 516  */
 517 ODE_API void dGeomVectorFromWorld
 518 (
 519   dGeomID geom, dReal px, dReal py, dReal pz,
 520   dVector3 result
 521 );
 522
 523
 524 /* ************************************************************************ */
 525 /* geom offset from body */
 526
 527 /**
 528  * @brief Set the local offset position of a geom from its body.
 529  *
 530  * Sets the geom's positional offset in local coordinates.
 531  * After this call, the geom will be at a new position determined from the
 532  * body's position and the offset.
 533  * The geom must be attached to a body.
 534  * If the geom did not have an offset, it is automatically created.
 535  *
 536  * @param geom the geom to set.
 537  * @param x the new X coordinate.
 538  * @param y the new Y coordinate.
 539  * @param z the new Z coordinate.
 540  * @ingroup collide
 541  */
 542 ODE_API void dGeomSetOffsetPosition (dGeomID geom, dReal x, dReal y, dReal z);
 543
 544
 545 /**
 546  * @brief Set the local offset rotation matrix of a geom from its body.
 547  *
 548  * Sets the geom's rotational offset in local coordinates.
 549  * After this call, the geom will be at a new position determined from the
 550  * body's position and the offset.
 551  * The geom must be attached to a body.
 552  * If the geom did not have an offset, it is automatically created.
 553  *
 554  * @param geom the geom to set.
 555  * @param R the new rotation matrix.
 556  * @ingroup collide
 557  */
 558 ODE_API void dGeomSetOffsetRotation (dGeomID geom, const dMatrix3 R);
 559
 560
 561 /**
 562  * @brief Set the local offset rotation of a geom from its body.
 563  *
 564  * Sets the geom's rotational offset in local coordinates.
 565  * After this call, the geom will be at a new position determined from the
 566  * body's position and the offset.
 567  * The geom must be attached to a body.
 568  * If the geom did not have an offset, it is automatically created.
 569  *
 570  * @param geom the geom to set.
 571  * @param Q the new rotation.
 572  * @ingroup collide
 573  */
 574 ODE_API void dGeomSetOffsetQuaternion (dGeomID geom, const dQuaternion Q);
 575
 576
 577 /**
 578  * @brief Set the offset position of a geom from its body.
 579  *
 580  * Sets the geom's positional offset to move it to the new world
 581  * coordinates.
 582  * After this call, the geom will be at the world position passed in,
 583  * and the offset will be the difference from the current body position.
 584  * The geom must be attached to a body.
 585  * If the geom did not have an offset, it is automatically created.
 586  *
 587  * @param geom the geom to set.
 588  * @param x the new X coordinate.
 589  * @param y the new Y coordinate.
 590  * @param z the new Z coordinate.
 591  * @ingroup collide
 592  */
 593 ODE_API void dGeomSetOffsetWorldPosition (dGeomID geom, dReal x, dReal y, dReal z);
 594
 595
 596 /**
 597  * @brief Set the offset rotation of a geom from its body.
 598  *
 599  * Sets the geom's rotational offset to orient it to the new world
 600  * rotation matrix.
 601  * After this call, the geom will be at the world orientation passed in,
 602  * and the offset will be the difference from the current body orientation.
 603  * The geom must be attached to a body.
 604  * If the geom did not have an offset, it is automatically created.
 605  *
 606  * @param geom the geom to set.
 607  * @param R the new rotation matrix.
 608  * @ingroup collide
 609  */
 610 ODE_API void dGeomSetOffsetWorldRotation (dGeomID geom, const dMatrix3 R);
 611
 612
 613 /**
 614  * @brief Set the offset rotation of a geom from its body.
 615  *
 616  * Sets the geom's rotational offset to orient it to the new world
 617  * rotation matrix.
 618  * After this call, the geom will be at the world orientation passed in,
 619  * and the offset will be the difference from the current body orientation.
 620  * The geom must be attached to a body.
 621  * If the geom did not have an offset, it is automatically created.
 622  *
 623  * @param geom the geom to set.
 624  * @param Q the new rotation.
 625  * @ingroup collide
 626  */
 627 ODE_API void dGeomSetOffsetWorldQuaternion (dGeomID geom, const dQuaternion);
 628
 629
 630 /**
 631  * @brief Clear any offset from the geom.
 632  *
 633  * If the geom has an offset, it is eliminated and the geom is
 634  * repositioned at the body's position.  If the geom has no offset,
 635  * this function does nothing.
 636  * This is more efficient than calling dGeomSetOffsetPosition(zero)
 637  * and dGeomSetOffsetRotation(identiy), because this function actually
 638  * eliminates the offset, rather than leaving it as the identity transform.
 639  *
 640  * @param geom the geom to have its offset destroyed.
 641  * @ingroup collide
 642  */
 643 ODE_API void dGeomClearOffset(dGeomID geom);
 644
 645
 646 /**
 647  * @brief Check to see whether the geom has an offset.
 648  *
 649  * This function will return non-zero if the offset has been created.
 650  * Note that there is a difference between a geom with no offset,
 651  * and a geom with an offset that is the identity transform.
 652  * In the latter case, although the observed behaviour is identical,
 653  * there is a unnecessary computation involved because the geom will
 654  * be applying the transform whenever it needs to recalculate its world
 655  * position.
 656  *
 657  * @param geom the geom to query.
 658  * @returns Non-zero if the geom has an offset, zero otherwise.
 659  * @ingroup collide
 660  */
 661 ODE_API int dGeomIsOffset(dGeomID geom);
 662
 663
 664 /**
 665  * @brief Get the offset position vector of a geom.
 666  *
 667  * Returns the positional offset of the geom in local coordinates.
 668  * If the geom has no offset, this function returns the zero vector.
 669  *
 670  * @param geom the geom to query.
 671  * @returns A pointer to the geom's offset vector.
 672  * @remarks The returned value is a pointer to the geom's internal
 673  *          data structure. It is valid until any changes are made
 674  *          to the geom.
 675  * @ingroup collide
 676  */
 677 ODE_API const dReal * dGeomGetOffsetPosition (dGeomID geom);
 678
 679
 680 /**
 681  * @brief Copy the offset position vector of a geom.
 682  *
 683  * Returns the positional offset of the geom in local coordinates.
 684  * If the geom has no offset, this function returns the zero vector.
 685  *
 686  * @param geom   the geom to query.
 687  * @param pos    returns the offset position
 688  * @ingroup collide
 689  */
 690 ODE_API void dGeomCopyOffsetPosition (dGeomID geom, dVector3 pos);
 691
 692
 693 /**
 694  * @brief Get the offset rotation matrix of a geom.
 695  *
 696  * Returns the rotational offset of the geom in local coordinates.
 697  * If the geom has no offset, this function returns the identity
 698  * matrix.
 699  *
 700  * @param geom the geom to query.
 701  * @returns A pointer to the geom's offset rotation matrix.
 702  * @remarks The returned value is a pointer to the geom's internal
 703  *          data structure. It is valid until any changes are made
 704  *          to the geom.
 705  * @ingroup collide
 706  */
 707 ODE_API const dReal * dGeomGetOffsetRotation (dGeomID geom);
 708
 709
 710 /**
 711  * @brief Copy the offset rotation matrix of a geom.
 712  *
 713  * Returns the rotational offset of the geom in local coordinates.
 714  * If the geom has no offset, this function returns the identity
 715  * matrix.
 716  *
 717  * @param geom   the geom to query.
 718  * @param R      returns the rotation matrix.
 719  * @ingroup collide
 720  */
 721 ODE_API void dGeomCopyOffsetRotation (dGeomID geom, dMatrix3 R);
 722
 723
 724 /**
 725  * @brief Get the offset rotation quaternion of a geom.
 726  *
 727  * Returns the rotation offset of the geom as a quaternion.
 728  * If the geom has no offset, the identity quaternion is returned.
 729  *
 730  * @param geom the geom to query.
 731  * @param result a copy of the rotation quaternion.
 732  * @ingroup collide
 733  */
 734 ODE_API void dGeomGetOffsetQuaternion (dGeomID geom, dQuaternion result);
 735
 736
 737 /* ************************************************************************ */
 738 /* collision detection */
 739
 740 /*
 741  *      Just generate any contacts (disables any contact refining).
 742  */
 743 #define CONTACTS_UNIMPORTANT                    0x80000000
 744
 745 /**
 746  *
 747  * @brief Given two geoms o1 and o2 that potentially intersect,
 748  * generate contact information for them.
 749  *
 750  * Internally, this just calls the correct class-specific collision
 751  * functions for o1 and o2.
 752  *
 753  * @param o1 The first geom to test.
 754  * @param o2 The second geom to test.
 755  *
 756  * @param flags The flags specify how contacts should be generated if
 757  * the geoms touch. The lower 16 bits of flags is an integer that
 758  * specifies the maximum number of contact points to generate. You must
 759  * ask for at least one contact.
 760  * Additionally, following bits may be set:
 761  * CONTACTS_UNIMPORTANT -- just generate any contacts (skip contact refining).
 762  * All other bits in flags must be set to zero. In the future the other bits
 763  * may be used to select from different contact generation strategies.
 764  *
 765  * @param contact Points to an array of dContactGeom structures. The array
 766  * must be able to hold at least the maximum number of contacts. These
 767  * dContactGeom structures may be embedded within larger structures in the
 768  * array -- the skip parameter is the byte offset from one dContactGeom to
 769  * the next in the array. If skip is sizeof(dContactGeom) then contact
 770  * points to a normal (C-style) array. It is an error for skip to be smaller
 771  * than sizeof(dContactGeom).
 772  *
 773  * @returns If the geoms intersect, this function returns the number of contact
 774  * points generated (and updates the contact array), otherwise it returns 0
 775  * (and the contact array is not touched).
 776  *
 777  * @remarks If a space is passed as o1 or o2 then this function will collide
 778  * all objects contained in o1 with all objects contained in o2, and return
 779  * the resulting contact points. This method for colliding spaces with geoms
 780  * (or spaces with spaces) provides no user control over the individual
 781  * collisions. To get that control, use dSpaceCollide or dSpaceCollide2 instead.
 782  *
 783  * @remarks If o1 and o2 are the same geom then this function will do nothing
 784  * and return 0. Technically speaking an object intersects with itself, but it
 785  * is not useful to find contact points in this case.
 786  *
 787  * @remarks This function does not care if o1 and o2 are in the same space or not
 788  * (or indeed if they are in any space at all).
 789  *
 790  * @ingroup collide
 791  */
 792 ODE_API int dCollide (dGeomID o1, dGeomID o2, int flags, dContactGeom *contact,
 793               int skip);
 794
 795 /**
 796  * @brief Determines which pairs of geoms in a space may potentially intersect,
 797  * and calls the callback function for each candidate pair.
 798  *
 799  * @param space The space to test.
 800  *
 801  * @param data Passed from dSpaceCollide directly to the callback
 802  * function. Its meaning is user defined. The o1 and o2 arguments are the
 803  * geoms that may be near each other.
 804  *
 805  * @param callback A callback function is of type @ref dNearCallback.
 806  *
 807  * @remarks Other spaces that are contained within the colliding space are
 808  * not treated specially, i.e. they are not recursed into. The callback
 809  * function may be passed these contained spaces as one or both geom
 810  * arguments.
 811  *
 812  * @remarks dSpaceCollide() is guaranteed to pass all intersecting geom
 813  * pairs to the callback function, but may also pass close but
 814  * non-intersecting pairs. The number of these calls depends on the
 815  * internal algorithms used by the space. Thus you should not expect
 816  * that dCollide will return contacts for every pair passed to the
 817  * callback.
 818  *
 819  * @sa dSpaceCollide2
 820  * @ingroup collide
 821  */
 822 ODE_API void dSpaceCollide (dSpaceID space, void *data, dNearCallback *callback);
 823
 824
 825 /**
 826  * @brief Determines which geoms from one space may potentially intersect with
 827  * geoms from another space, and calls the callback function for each candidate
 828  * pair.
 829  *
 830  * @param space1 The first space to test.
 831  *
 832  * @param space2 The second space to test.
 833  *
 834  * @param data Passed from dSpaceCollide directly to the callback
 835  * function. Its meaning is user defined. The o1 and o2 arguments are the
 836  * geoms that may be near each other.
 837  *
 838  * @param callback A callback function is of type @ref dNearCallback.
 839  *
 840  * @remarks This function can also test a single non-space geom against a
 841  * space. This function is useful when there is a collision hierarchy, i.e.
 842  * when there are spaces that contain other spaces.
 843  *
 844  * @remarks Other spaces that are contained within the colliding space are
 845  * not treated specially, i.e. they are not recursed into. The callback
 846  * function may be passed these contained spaces as one or both geom
 847  * arguments.
 848  *
 849  * @remarks Sublevel value of space affects how the spaces are iterated.
 850  * Both spaces are recursed only if their sublevels match. Otherwise, only
 851  * the space with greater sublevel is recursed and the one with lesser sublevel
 852  * is used as a geom itself.
 853  *
 854  * @remarks dSpaceCollide2() is guaranteed to pass all intersecting geom
 855  * pairs to the callback function, but may also pass close but
 856  * non-intersecting pairs. The number of these calls depends on the
 857  * internal algorithms used by the space. Thus you should not expect
 858  * that dCollide will return contacts for every pair passed to the
 859  * callback.
 860  *
 861  * @sa dSpaceCollide
 862  * @sa dSpaceSetSublevel
 863  * @ingroup collide
 864  */
 865 ODE_API void dSpaceCollide2 (dGeomID space1, dGeomID space2, void *data, dNearCallback *callback);
 866
 867
 868 /* ************************************************************************ */
 869 /* standard classes */
 870
 871 /* the maximum number of user classes that are supported */
 872 enum {
 873   dMaxUserClasses = 4
 874 };
 875
 876 /* class numbers - each geometry object needs a unique number */
 877 enum {
 878   dSphereClass = 0,
 879   dBoxClass,
 880   dCapsuleClass,
 881   dCylinderClass,
 882   dPlaneClass,
 883   dRayClass,
 884   dConvexClass,
 885   dGeomTransformClass,
 886   dTriMeshClass,
 887   dHeightfieldClass,
 888
 889   dFirstSpaceClass,
 890   dSimpleSpaceClass = dFirstSpaceClass,
 891   dHashSpaceClass,
 892   dSweepAndPruneSpaceClass, /* SAP */
 893   dQuadTreeSpaceClass,
 894   dLastSpaceClass = dQuadTreeSpaceClass,
 895
 896   dFirstUserClass,
 897   dLastUserClass = dFirstUserClass + dMaxUserClasses - 1,
 898   dGeomNumClasses
 899 };
 900
 901
 902 /**
 903  * @defgroup collide_sphere Sphere Class
 904  * @ingroup collide
 905  */
 906
 907 /**
 908  * @brief Create a sphere geom of the given radius, and return its ID.
 909  *
 910  * @param space   a space to contain the new geom. May be null.
 911  * @param radius  the radius of the sphere.
 912  *
 913  * @returns A new sphere geom.
 914  *
 915  * @remarks The point of reference for a sphere is its center.
 916  *
 917  * @sa dGeomDestroy
 918  * @sa dGeomSphereSetRadius
 919  * @ingroup collide_sphere
 920  */
 921 ODE_API dGeomID dCreateSphere (dSpaceID space, dReal radius);
 922
 923
 924 /**
 925  * @brief Set the radius of a sphere geom.
 926  *
 927  * @param sphere  the sphere to set.
 928  * @param radius  the new radius.
 929  *
 930  * @sa dGeomSphereGetRadius
 931  * @ingroup collide_sphere
 932  */
 933 ODE_API void dGeomSphereSetRadius (dGeomID sphere, dReal radius);
 934
 935
 936 /**
 937  * @brief Retrieves the radius of a sphere geom.
 938  *
 939  * @param sphere  the sphere to query.
 940  *
 941  * @sa dGeomSphereSetRadius
 942  * @ingroup collide_sphere
 943  */
 944 ODE_API dReal dGeomSphereGetRadius (dGeomID sphere);
 945
 946
 947 /**
 948  * @brief Calculate the depth of the a given point within a sphere.
 949  *
 950  * @param sphere  the sphere to query.
 951  * @param x       the X coordinate of the point.
 952  * @param y       the Y coordinate of the point.
 953  * @param z       the Z coordinate of the point.
 954  *
 955  * @returns The depth of the point. Points inside the sphere will have a
 956  * positive depth, points outside it will have a negative depth, and points
 957  * on the surface will have a depth of zero.
 958  *
 959  * @ingroup collide_sphere
 960  */
 961 ODE_API dReal dGeomSpherePointDepth (dGeomID sphere, dReal x, dReal y, dReal z);
 962
 963
 964 /*--> Convex Functions*/
 965 ODE_API dGeomID dCreateConvex (dSpaceID space,
 966                                const dReal *_planes,
 967                                unsigned int _planecount,
 968                                const dReal *_points,
 969                                unsigned int _pointcount,
 970                    const unsigned int *_polygons);
 971
 972 ODE_API void dGeomSetConvex (dGeomID g,
 973                              const dReal *_planes,
 974                              unsigned int _count,
 975                              const dReal *_points,
 976                              unsigned int _pointcount,
 977                  const unsigned int *_polygons);
 978 /*<-- Convex Functions*/
 979
 980 /**
 981  * @defgroup collide_box Box Class
 982  * @ingroup collide
 983  */
 984
 985 /**
 986  * @brief Create a box geom with the provided side lengths.
 987  *
 988  * @param space   a space to contain the new geom. May be null.
 989  * @param lx      the length of the box along the X axis
 990  * @param ly      the length of the box along the Y axis
 991  * @param lz      the length of the box along the Z axis
 992  *
 993  * @returns A new box geom.
 994  *
 995  * @remarks The point of reference for a box is its center.
 996  *
 997  * @sa dGeomDestroy
 998  * @sa dGeomBoxSetLengths
 999  * @ingroup collide_box
1000  */
1001 ODE_API dGeomID dCreateBox (dSpaceID space, dReal lx, dReal ly, dReal lz);
1002
1003
1004 /**
1005  * @brief Set the side lengths of the given box.
1006  *
1007  * @param box  the box to set
1008  * @param lx      the length of the box along the X axis
1009  * @param ly      the length of the box along the Y axis
1010  * @param lz      the length of the box along the Z axis
1011  *
1012  * @sa dGeomBoxGetLengths
1013  * @ingroup collide_box
1014  */
1015 ODE_API void dGeomBoxSetLengths (dGeomID box, dReal lx, dReal ly, dReal lz);
1016
1017
1018 /**
1019  * @brief Get the side lengths of a box.
1020  *
1021  * @param box     the box to query
1022  * @param result  the returned side lengths
1023  *
1024  * @sa dGeomBoxSetLengths
1025  * @ingroup collide_box
1026  */
1027 ODE_API void dGeomBoxGetLengths (dGeomID box, dVector3 result);
1028
1029
1030 /**
1031  * @brief Return the depth of a point in a box.
1032  *
1033  * @param box  the box to query
1034  * @param x    the X coordinate of the point to test.
1035  * @param y    the Y coordinate of the point to test.
1036  * @param z    the Z coordinate of the point to test.
1037  *
1038  * @returns The depth of the point. Points inside the box will have a
1039  * positive depth, points outside it will have a negative depth, and points
1040  * on the surface will have a depth of zero.
1041  */
1042 ODE_API dReal dGeomBoxPointDepth (dGeomID box, dReal x, dReal y, dReal z);
1043
1044
1045 ODE_API dGeomID dCreatePlane (dSpaceID space, dReal a, dReal b, dReal c, dReal d);
1046 ODE_API void dGeomPlaneSetParams (dGeomID plane, dReal a, dReal b, dReal c, dReal d);
1047 ODE_API void dGeomPlaneGetParams (dGeomID plane, dVector4 result);
1048 ODE_API dReal dGeomPlanePointDepth (dGeomID plane, dReal x, dReal y, dReal z);
1049
1050 ODE_API dGeomID dCreateCapsule (dSpaceID space, dReal radius, dReal length);
1051 ODE_API void dGeomCapsuleSetParams (dGeomID ccylinder, dReal radius, dReal length);
1052 ODE_API void dGeomCapsuleGetParams (dGeomID ccylinder, dReal *radius, dReal *length);
1053 ODE_API dReal dGeomCapsulePointDepth (dGeomID ccylinder, dReal x, dReal y, dReal z);
1054
1055 /* For now we want to have a backwards compatible C-API, note: C++ API is not.*/
1056 #define dCreateCCylinder dCreateCapsule
1057 #define dGeomCCylinderSetParams dGeomCapsuleSetParams
1058 #define dGeomCCylinderGetParams dGeomCapsuleGetParams
1059 #define dGeomCCylinderPointDepth dGeomCapsulePointDepth
1060 #define dCCylinderClass dCapsuleClass
1061
1062 ODE_API dGeomID dCreateCylinder (dSpaceID space, dReal radius, dReal length);
1063 ODE_API void dGeomCylinderSetParams (dGeomID cylinder, dReal radius, dReal length);
1064 ODE_API void dGeomCylinderGetParams (dGeomID cylinder, dReal *radius, dReal *length);
1065
1066 ODE_API dGeomID dCreateRay (dSpaceID space, dReal length);
1067 ODE_API void dGeomRaySetLength (dGeomID ray, dReal length);
1068 ODE_API dReal dGeomRayGetLength (dGeomID ray);
1069 ODE_API void dGeomRaySet (dGeomID ray, dReal px, dReal py, dReal pz,
1070                   dReal dx, dReal dy, dReal dz);
1071 ODE_API void dGeomRayGet (dGeomID ray, dVector3 start, dVector3 dir);
1072
1073 /*
1074  * Set/get ray flags that influence ray collision detection.
1075  * These flags are currently only noticed by the trimesh collider, because
1076  * they can make a major differences there.
1077  */
1078 ODE_API_DEPRECATED ODE_API void dGeomRaySetParams (dGeomID g, int FirstContact, int BackfaceCull);
1079 ODE_API_DEPRECATED ODE_API void dGeomRayGetParams (dGeomID g, int *FirstContact, int *BackfaceCull);
1080 ODE_API void dGeomRaySetFirstContact (dGeomID g, int firstContact);
1081 ODE_API int dGeomRayGetFirstContact (dGeomID g);
1082 ODE_API void dGeomRaySetBackfaceCull (dGeomID g, int backfaceCull);
1083 ODE_API int dGeomRayGetBackfaceCull (dGeomID g);
1084 ODE_API void dGeomRaySetClosestHit (dGeomID g, int closestHit);
1085 ODE_API int dGeomRayGetClosestHit (dGeomID g);
1086
1087 #include "collision_trimesh.h"
1088
1089 ODE_API_DEPRECATED ODE_API dGeomID dCreateGeomTransform (dSpaceID space);
1090 ODE_API_DEPRECATED ODE_API void dGeomTransformSetGeom (dGeomID g, dGeomID obj);
1091 ODE_API_DEPRECATED ODE_API dGeomID dGeomTransformGetGeom (dGeomID g);
1092 ODE_API_DEPRECATED ODE_API void dGeomTransformSetCleanup (dGeomID g, int mode);
1093 ODE_API_DEPRECATED ODE_API int dGeomTransformGetCleanup (dGeomID g);
1094 ODE_API_DEPRECATED ODE_API void dGeomTransformSetInfo (dGeomID g, int mode);
1095 ODE_API_DEPRECATED ODE_API int dGeomTransformGetInfo (dGeomID g);
1096
1097
1098 /* ************************************************************************ */
1099 /* heightfield functions */
1100
1101
1102 /* Data storage for heightfield data.*/
1103 struct dxHeightfieldData;
1104 typedef struct dxHeightfieldData* dHeightfieldDataID;
1105
1106
1107 /**
1108  * @brief Callback prototype
1109  *
1110  * Used by the callback heightfield data type to sample a height for a
1111  * given cell position.
1112  *
1113  * @param p_user_data User data specified when creating the dHeightfieldDataID
1114  * @param x The index of a sample in the local x axis. It is a value
1115  * in the range zero to ( nWidthSamples - 1 ).
1116  * @param x The index of a sample in the local z axis. It is a value
1117  * in the range zero to ( nDepthSamples - 1 ).
1118  *
1119  * @return The sample height which is then scaled and offset using the
1120  * values specified when the heightfield data was created.
1121  *
1122  * @ingroup collide
1123  */
1124 typedef dReal dHeightfieldGetHeight( void* p_user_data, int x, int z );
1125
1126
1127
1128 /**
1129  * @brief Creates a heightfield geom.
1130  *
1131  * Uses the information in the given dHeightfieldDataID to construct
1132  * a geom representing a heightfield in a collision space.
1133  *
1134  * @param space The space to add the geom to.
1135  * @param data The dHeightfieldDataID created by dGeomHeightfieldDataCreate and
1136  * setup by dGeomHeightfieldDataBuildCallback, dGeomHeightfieldDataBuildByte,
1137  * dGeomHeightfieldDataBuildShort or dGeomHeightfieldDataBuildFloat.
1138  * @param bPlaceable If non-zero this geom can be transformed in the world using the
1139  * usual functions such as dGeomSetPosition and dGeomSetRotation. If the geom is
1140  * not set as placeable, then it uses a fixed orientation where the global y axis
1141  * represents the dynamic 'height' of the heightfield.
1142  *
1143  * @return A geom id to reference this geom in other calls.
1144  *
1145  * @ingroup collide
1146  */
1147 ODE_API dGeomID dCreateHeightfield( dSpaceID space,
1148                                         dHeightfieldDataID data, int bPlaceable );
1149
1150
1151 /**
1152  * @brief Creates a new empty dHeightfieldDataID.
1153  *
1154  * Allocates a new dHeightfieldDataID and returns it. You must call
1155  * dGeomHeightfieldDataDestroy to destroy it after the geom has been removed.
1156  * The dHeightfieldDataID value is used when specifying a data format type.
1157  *
1158  * @return A dHeightfieldDataID for use with dGeomHeightfieldDataBuildCallback,
1159  * dGeomHeightfieldDataBuildByte, dGeomHeightfieldDataBuildShort or
1160  * dGeomHeightfieldDataBuildFloat.
1161  * @ingroup collide
1162  */
1163 ODE_API dHeightfieldDataID dGeomHeightfieldDataCreate(void);
1164
1165
1166 /**
1167  * @brief Destroys a dHeightfieldDataID.
1168  *
1169  * Deallocates a given dHeightfieldDataID and all managed resources.
1170  *
1171  * @param d A dHeightfieldDataID created by dGeomHeightfieldDataCreate
1172  * @ingroup collide
1173  */
1174 ODE_API void dGeomHeightfieldDataDestroy( dHeightfieldDataID d );
1175
1176
1177
1178 /**
1179  * @brief Configures a dHeightfieldDataID to use a callback to
1180  * retrieve height data.
1181  *
1182  * Before a dHeightfieldDataID can be used by a geom it must be
1183  * configured to specify the format of the height data.
1184  * This call specifies that the heightfield data is computed by
1185  * the user and it should use the given callback when determining
1186  * the height of a given element of it's shape.
1187  *
1188  * @param d A new dHeightfieldDataID created by dGeomHeightfieldDataCreate
1189  *
1190  * @param width Specifies the total 'width' of the heightfield along
1191  * the geom's local x axis.
1192  * @param depth Specifies the total 'depth' of the heightfield along
1193  * the geom's local z axis.
1194  *
1195  * @param widthSamples Specifies the number of vertices to sample
1196  * along the width of the heightfield. Each vertex has a corresponding
1197  * height value which forms the overall shape.
1198  * Naturally this value must be at least two or more.
1199  * @param depthSamples Specifies the number of vertices to sample
1200  * along the depth of the heightfield.
1201  *
1202  * @param scale A uniform scale applied to all raw height data.
1203  * @param offset An offset applied to the scaled height data.
1204  *
1205  * @param thickness A value subtracted from the lowest height
1206  * value which in effect adds an additional cuboid to the base of the
1207  * heightfield. This is used to prevent geoms from looping under the
1208  * desired terrain and not registering as a collision. Note that the
1209  * thickness is not affected by the scale or offset parameters.
1210  *
1211  * @param bWrap If non-zero the heightfield will infinitely tile in both
1212  * directions along the local x and z axes. If zero the heightfield is
1213  * bounded from zero to width in the local x axis, and zero to depth in
1214  * the local z axis.
1215  *
1216  * @ingroup collide
1217  */
1218 ODE_API void dGeomHeightfieldDataBuildCallback( dHeightfieldDataID d,
1219                                 void* pUserData, dHeightfieldGetHeight* pCallback,
1220                                 dReal width, dReal depth, int widthSamples, int depthSamples,
1221                                 dReal scale, dReal offset, dReal thickness, int bWrap );
1222
1223 /**
1224  * @brief Configures a dHeightfieldDataID to use height data in byte format.
1225  *
1226  * Before a dHeightfieldDataID can be used by a geom it must be
1227  * configured to specify the format of the height data.
1228  * This call specifies that the heightfield data is stored as a rectangular
1229  * array of bytes (8 bit unsigned) representing the height at each sample point.
1230  *
1231  * @param d A new dHeightfieldDataID created by dGeomHeightfieldDataCreate
1232  *
1233  * @param pHeightData A pointer to the height data.
1234  * @param bCopyHeightData When non-zero the height data is copied to an
1235  * internal store. When zero the height data is accessed by reference and
1236  * so must persist throughout the lifetime of the heightfield.
1237  *
1238  * @param width Specifies the total 'width' of the heightfield along
1239  * the geom's local x axis.
1240  * @param depth Specifies the total 'depth' of the heightfield along
1241  * the geom's local z axis.
1242  *
1243  * @param widthSamples Specifies the number of vertices to sample
1244  * along the width of the heightfield. Each vertex has a corresponding
1245  * height value which forms the overall shape.
1246  * Naturally this value must be at least two or more.
1247  * @param depthSamples Specifies the number of vertices to sample
1248  * along the depth of the heightfield.
1249  *
1250  * @param scale A uniform scale applied to all raw height data.
1251  * @param offset An offset applied to the scaled height data.
1252  *
1253  * @param thickness A value subtracted from the lowest height
1254  * value which in effect adds an additional cuboid to the base of the
1255  * heightfield. This is used to prevent geoms from looping under the
1256  * desired terrain and not registering as a collision. Note that the
1257  * thickness is not affected by the scale or offset parameters.
1258  *
1259  * @param bWrap If non-zero the heightfield will infinitely tile in both
1260  * directions along the local x and z axes. If zero the heightfield is
1261  * bounded from zero to width in the local x axis, and zero to depth in
1262  * the local z axis.
1263  *
1264  * @ingroup collide
1265  */
1266 ODE_API void dGeomHeightfieldDataBuildByte( dHeightfieldDataID d,
1267                                 const unsigned char* pHeightData, int bCopyHeightData,
1268                                 dReal width, dReal depth, int widthSamples, int depthSamples,
1269                                 dReal scale, dReal offset, dReal thickness,     int bWrap );
1270
1271 /**
1272  * @brief Configures a dHeightfieldDataID to use height data in short format.
1273  *
1274  * Before a dHeightfieldDataID can be used by a geom it must be
1275  * configured to specify the format of the height data.
1276  * This call specifies that the heightfield data is stored as a rectangular
1277  * array of shorts (16 bit signed) representing the height at each sample point.
1278  *
1279  * @param d A new dHeightfieldDataID created by dGeomHeightfieldDataCreate
1280  *
1281  * @param pHeightData A pointer to the height data.
1282  * @param bCopyHeightData When non-zero the height data is copied to an
1283  * internal store. When zero the height data is accessed by reference and
1284  * so must persist throughout the lifetime of the heightfield.
1285  *
1286  * @param width Specifies the total 'width' of the heightfield along
1287  * the geom's local x axis.
1288  * @param depth Specifies the total 'depth' of the heightfield along
1289  * the geom's local z axis.
1290  *
1291  * @param widthSamples Specifies the number of vertices to sample
1292  * along the width of the heightfield. Each vertex has a corresponding
1293  * height value which forms the overall shape.
1294  * Naturally this value must be at least two or more.
1295  * @param depthSamples Specifies the number of vertices to sample
1296  * along the depth of the heightfield.
1297  *
1298  * @param scale A uniform scale applied to all raw height data.
1299  * @param offset An offset applied to the scaled height data.
1300  *
1301  * @param thickness A value subtracted from the lowest height
1302  * value which in effect adds an additional cuboid to the base of the
1303  * heightfield. This is used to prevent geoms from looping under the
1304  * desired terrain and not registering as a collision. Note that the
1305  * thickness is not affected by the scale or offset parameters.
1306  *
1307  * @param bWrap If non-zero the heightfield will infinitely tile in both
1308  * directions along the local x and z axes. If zero the heightfield is
1309  * bounded from zero to width in the local x axis, and zero to depth in
1310  * the local z axis.
1311  *
1312  * @ingroup collide
1313  */
1314 ODE_API void dGeomHeightfieldDataBuildShort( dHeightfieldDataID d,
1315                                 const short* pHeightData, int bCopyHeightData,
1316                                 dReal width, dReal depth, int widthSamples, int depthSamples,
1317                                 dReal scale, dReal offset, dReal thickness, int bWrap );
1318
1319 /**
1320  * @brief Configures a dHeightfieldDataID to use height data in
1321  * single precision floating point format.
1322  *
1323  * Before a dHeightfieldDataID can be used by a geom it must be
1324  * configured to specify the format of the height data.
1325  * This call specifies that the heightfield data is stored as a rectangular
1326  * array of single precision floats representing the height at each
1327  * sample point.
1328  *
1329  * @param d A new dHeightfieldDataID created by dGeomHeightfieldDataCreate
1330  *
1331  * @param pHeightData A pointer to the height data.
1332  * @param bCopyHeightData When non-zero the height data is copied to an
1333  * internal store. When zero the height data is accessed by reference and
1334  * so must persist throughout the lifetime of the heightfield.
1335  *
1336  * @param width Specifies the total 'width' of the heightfield along
1337  * the geom's local x axis.
1338  * @param depth Specifies the total 'depth' of the heightfield along
1339  * the geom's local z axis.
1340  *
1341  * @param widthSamples Specifies the number of vertices to sample
1342  * along the width of the heightfield. Each vertex has a corresponding
1343  * height value which forms the overall shape.
1344  * Naturally this value must be at least two or more.
1345  * @param depthSamples Specifies the number of vertices to sample
1346  * along the depth of the heightfield.
1347  *
1348  * @param scale A uniform scale applied to all raw height data.
1349  * @param offset An offset applied to the scaled height data.
1350  *
1351  * @param thickness A value subtracted from the lowest height
1352  * value which in effect adds an additional cuboid to the base of the
1353  * heightfield. This is used to prevent geoms from looping under the
1354  * desired terrain and not registering as a collision. Note that the
1355  * thickness is not affected by the scale or offset parameters.
1356  *
1357  * @param bWrap If non-zero the heightfield will infinitely tile in both
1358  * directions along the local x and z axes. If zero the heightfield is
1359  * bounded from zero to width in the local x axis, and zero to depth in
1360  * the local z axis.
1361  *
1362  * @ingroup collide
1363  */
1364 ODE_API void dGeomHeightfieldDataBuildSingle( dHeightfieldDataID d,
1365                                 const float* pHeightData, int bCopyHeightData,
1366                                 dReal width, dReal depth, int widthSamples, int depthSamples,
1367                                 dReal scale, dReal offset, dReal thickness, int bWrap );
1368
1369 /**
1370  * @brief Configures a dHeightfieldDataID to use height data in
1371  * double precision floating point format.
1372  *
1373  * Before a dHeightfieldDataID can be used by a geom it must be
1374  * configured to specify the format of the height data.
1375  * This call specifies that the heightfield data is stored as a rectangular
1376  * array of double precision floats representing the height at each
1377  * sample point.
1378  *
1379  * @param d A new dHeightfieldDataID created by dGeomHeightfieldDataCreate
1380  *
1381  * @param pHeightData A pointer to the height data.
1382  * @param bCopyHeightData When non-zero the height data is copied to an
1383  * internal store. When zero the height data is accessed by reference and
1384  * so must persist throughout the lifetime of the heightfield.
1385  *
1386  * @param width Specifies the total 'width' of the heightfield along
1387  * the geom's local x axis.
1388  * @param depth Specifies the total 'depth' of the heightfield along
1389  * the geom's local z axis.
1390  *
1391  * @param widthSamples Specifies the number of vertices to sample
1392  * along the width of the heightfield. Each vertex has a corresponding
1393  * height value which forms the overall shape.
1394  * Naturally this value must be at least two or more.
1395  * @param depthSamples Specifies the number of vertices to sample
1396  * along the depth of the heightfield.
1397  *
1398  * @param scale A uniform scale applied to all raw height data.
1399  * @param offset An offset applied to the scaled height data.
1400  *
1401  * @param thickness A value subtracted from the lowest height
1402  * value which in effect adds an additional cuboid to the base of the
1403  * heightfield. This is used to prevent geoms from looping under the
1404  * desired terrain and not registering as a collision. Note that the
1405  * thickness is not affected by the scale or offset parameters.
1406  *
1407  * @param bWrap If non-zero the heightfield will infinitely tile in both
1408  * directions along the local x and z axes. If zero the heightfield is
1409  * bounded from zero to width in the local x axis, and zero to depth in
1410  * the local z axis.
1411  *
1412  * @ingroup collide
1413  */
1414 ODE_API void dGeomHeightfieldDataBuildDouble( dHeightfieldDataID d,
1415                                 const double* pHeightData, int bCopyHeightData,
1416                                 dReal width, dReal depth, int widthSamples, int depthSamples,
1417                                 dReal scale, dReal offset, dReal thickness, int bWrap );
1418
1419 /**
1420  * @brief Manually set the minimum and maximum height bounds.
1421  *
1422  * This call allows you to set explicit min / max values after initial
1423  * creation typically for callback heightfields which default to +/- infinity,
1424  * or those whose data has changed. This must be set prior to binding with a
1425  * geom, as the the AABB is not recomputed after it's first generation.
1426  *
1427  * @remarks The minimum and maximum values are used to compute the AABB
1428  * for the heightfield which is used for early rejection of collisions.
1429  * A close fit will yield a more efficient collision check.
1430  *
1431  * @param d A dHeightfieldDataID created by dGeomHeightfieldDataCreate
1432  * @param min_height The new minimum height value. Scale, offset and thickness is then applied.
1433  * @param max_height The new maximum height value. Scale and offset is then applied.
1434  * @ingroup collide
1435  */
1436 ODE_API void dGeomHeightfieldDataSetBounds( dHeightfieldDataID d,
1437                                 dReal minHeight, dReal maxHeight );
1438
1439
1440 /**
1441  * @brief Assigns a dHeightfieldDataID to a heightfield geom.
1442  *
1443  * Associates the given dHeightfieldDataID with a heightfield geom.
1444  * This is done without affecting the GEOM_PLACEABLE flag.
1445  *
1446  * @param g A geom created by dCreateHeightfield
1447  * @param d A dHeightfieldDataID created by dGeomHeightfieldDataCreate
1448  * @ingroup collide
1449  */
1450 ODE_API void dGeomHeightfieldSetHeightfieldData( dGeomID g, dHeightfieldDataID d );
1451
1452
1453 /**
1454  * @brief Gets the dHeightfieldDataID bound to a heightfield geom.
1455  *
1456  * Returns the dHeightfieldDataID associated with a heightfield geom.
1457  *
1458  * @param g A geom created by dCreateHeightfield
1459  * @return The dHeightfieldDataID which may be NULL if none was assigned.
1460  * @ingroup collide
1461  */
1462 ODE_API dHeightfieldDataID dGeomHeightfieldGetHeightfieldData( dGeomID g );
1463
1464
1465
1466 /* ************************************************************************ */
1467 /* utility functions */
1468
1469 ODE_API void dClosestLineSegmentPoints (const dVector3 a1, const dVector3 a2,
1470                                 const dVector3 b1, const dVector3 b2,
1471                                 dVector3 cp1, dVector3 cp2);
1472
1473 ODE_API int dBoxTouchesBox (const dVector3 _p1, const dMatrix3 R1,
1474                     const dVector3 side1, const dVector3 _p2,
1475                     const dMatrix3 R2, const dVector3 side2);
1476
1477 /* The meaning of flags parameter is the same as in dCollide()*/
1478 ODE_API int dBoxBox (const dVector3 p1, const dMatrix3 R1,
1479              const dVector3 side1, const dVector3 p2,
1480              const dMatrix3 R2, const dVector3 side2,
1481              dVector3 normal, dReal *depth, int *return_code,
1482              int flags, dContactGeom *contact, int skip);
1483
1484 ODE_API void dInfiniteAABB (dGeomID geom, dReal aabb[6]);
1485
1486
1487 /* ************************************************************************ */
1488 /* custom classes */
1489
1490 typedef void dGetAABBFn (dGeomID, dReal aabb[6]);
1491 typedef int dColliderFn (dGeomID o1, dGeomID o2,
1492                          int flags, dContactGeom *contact, int skip);
1493 typedef dColliderFn * dGetColliderFnFn (int num);
1494 typedef void dGeomDtorFn (dGeomID o);
1495 typedef int dAABBTestFn (dGeomID o1, dGeomID o2, dReal aabb[6]);
1496
1497 typedef struct dGeomClass {
1498   int bytes;
1499   dGetColliderFnFn *collider;
1500   dGetAABBFn *aabb;
1501   dAABBTestFn *aabb_test;
1502   dGeomDtorFn *dtor;
1503 } dGeomClass;
1504
1505 ODE_API int dCreateGeomClass (const dGeomClass *classptr);
1506 ODE_API void * dGeomGetClassData (dGeomID);
1507 ODE_API dGeomID dCreateGeom (int classnum);
1508
1509 /**
1510  * @brief Sets a custom collider function for two geom classes.
1511  *
1512  * @param i The first geom class handled by this collider
1513  * @param j The second geom class handled by this collider
1514  * @param fn The collider function to use to determine collisions.
1515  * @ingroup collide
1516  */
1517 ODE_API void dSetColliderOverride (int i, int j, dColliderFn *fn);
1518
1519
1520 /* ************************************************************************ */
1521
1522 #ifdef __cplusplus
1523 }
1524 #endif
1525
1526 #endif