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