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

   1 /*************************************************************************
   2  *                                                                       *
   3  * Open Dynamics Engine, Copyright (C) 2001,2002 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_OBJECTS_H_
  24 #define _ODE_OBJECTS_H_
  25
  26 #include <ode/common.h>
  27 #include <ode/mass.h>
  28 #include <ode/contact.h>
  29 #include <ode/threading.h>
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /**
  36  * @defgroup world World
  37  *
  38  * The world object is a container for rigid bodies and joints. Objects in
  39  * different worlds can not interact, for example rigid bodies from two
  40  * different worlds can not collide.
  41  *
  42  * All the objects in a world exist at the same point in time, thus one
  43  * reason to use separate worlds is to simulate systems at different rates.
  44  * Most applications will only need one world.
  45  */
  46
  47 /**
  48  * @brief Create a new, empty world and return its ID number.
  49  * @return an identifier
  50  * @ingroup world
  51  */
  52 ODE_API dWorldID dWorldCreate(void);
  53
  54
  55 /**
  56  * @brief Destroy a world and everything in it.
  57  *
  58  * This includes all bodies, and all joints that are not part of a joint
  59  * group. Joints that are part of a joint group will be deactivated, and
  60  * can be destroyed by calling, for example, dJointGroupEmpty().
  61  * @ingroup world
  62  * @param world the identifier for the world the be destroyed.
  63  */
  64 ODE_API void dWorldDestroy (dWorldID world);
  65
  66
  67 /**
  68  * @brief Set the user-data pointer
  69  * @param world the world to set the data on
  70  * @param data
  71  * @ingroup world
  72  */
  73 ODE_API void dWorldSetData (dWorldID world, void* data);
  74
  75
  76 /**
  77  * @brief Get the user-data pointer
  78  * @param world the world to set the data on
  79  * @param data
  80  * @ingroup world
  81  */
  82 ODE_API void* dWorldGetData (dWorldID world);
  83
  84
  85 /**
  86  * @brief Set the world's global gravity vector.
  87  *
  88  * The units are m/s^2, so Earth's gravity vector would be (0,0,-9.81),
  89  * assuming that +z is up. The default is no gravity, i.e. (0,0,0).
  90  *
  91  * @ingroup world
  92  */
  93 ODE_API void dWorldSetGravity (dWorldID, dReal x, dReal y, dReal z);
  94
  95
  96 /**
  97  * @brief Get the gravity vector for a given world.
  98  * @ingroup world
  99  */
 100 ODE_API void dWorldGetGravity (dWorldID, dVector3 gravity);
 101
 102
 103 /**
 104  * @brief Set the global ERP value, that controls how much error
 105  * correction is performed in each time step.
 106  * @ingroup world
 107  * @param dWorldID the identifier of the world.
 108  * @param erp Typical values are in the range 0.1--0.8. The default is 0.2.
 109  */
 110 ODE_API void dWorldSetERP (dWorldID, dReal erp);
 111
 112 /**
 113  * @brief Get the error reduction parameter.
 114  * @ingroup world
 115  * @return ERP value
 116  */
 117 ODE_API dReal dWorldGetERP (dWorldID);
 118
 119
 120 /**
 121  * @brief Set the global CFM (constraint force mixing) value.
 122  * @ingroup world
 123  * @param cfm Typical values are in the range @m{10^{-9}} -- 1.
 124  * The default is 10^-5 if single precision is being used, or 10^-10
 125  * if double precision is being used.
 126  */
 127 ODE_API void dWorldSetCFM (dWorldID, dReal cfm);
 128
 129 /**
 130  * @brief Get the constraint force mixing value.
 131  * @ingroup world
 132  * @return CFM value
 133  */
 134 ODE_API dReal dWorldGetCFM (dWorldID);
 135
 136
 137 #define dWORLDSTEP_THREADCOUNT_UNLIMITED        dTHREADING_THREAD_COUNT_UNLIMITED
 138
 139 /**
 140  * @brief Set maximum threads to be used for island stepping
 141  *
 142  * The actual number of threads that is going to be used will be the minimum
 143  * of this limit and number of threads in the threading pool. By default
 144  * there is no limit (@c dWORLDSTEP_THREADCOUNT_UNLIMITED).
 145  *
 146  * @warning
 147  * WARNING! Running island stepping in multiple threads requires allocating
 148  * individual stepping memory buffer for each of those threads. The size of buffers
 149  * allocated is the size needed to handle the largest island in the world.
 150  *
 151  * Note: Setting a limit for island stepping does not affect threading at lower
 152  * levels in stepper functions. The sub-calls scheduled from them can be executed
 153  * in as many threads as there are available in the pool.
 154  *
 155  * @param w The world affected
 156  * @param count Thread count limit value for island stepping
 157  * @ingroup world
 158  * @see dWorldGetStepIslandsProcessingMaxThreadCount
 159  */
 160 ODE_API void dWorldSetStepIslandsProcessingMaxThreadCount(dWorldID w, unsigned count);
 161 /**
 162  * @brief Get maximum threads that are allowed to be used for island stepping.
 163  *
 164  * Please read commentaries to @c dWorldSetStepIslandsProcessingMaxThreadCount for
 165  * important information regarding the value returned.
 166  *
 167  * @param w The world queried
 168  * @returns Current thread count limit value for island stepping
 169  * @ingroup world
 170  * @see dWorldSetStepIslandsProcessingMaxThreadCount
 171  */
 172 ODE_API unsigned dWorldGetStepIslandsProcessingMaxThreadCount(dWorldID w);
 173
 174 /**
 175  * @brief Set the world to use shared working memory along with another world.
 176  *
 177  * The worlds allocate working memory internally for simulation stepping. This
 178  * memory is cached among the calls to @c dWordStep and @c dWorldQuickStep.
 179  * Similarly, several worlds can be set up to share this memory caches thus
 180  * reducing overall memory usage by cost of making worlds inappropriate for
 181  * simultaneous simulation in multiple threads.
 182  *
 183  * If null value is passed for @a from_world parameter the world is detached from
 184  * sharing and returns to defaults for working memory, reservation policy and
 185  * memory manager as if just created. This can also be used to enable use of shared
 186  * memory for a world that has already had working memory allocated privately.
 187  * Normally using shared memory after a world has its private working memory allocated
 188  * is prohibited.
 189  *
 190  * Allocation policy used can only increase world's internal reserved memory size
 191  * and never decreases it. @c dWorldCleanupWorkingMemory can be used to release
 192  * working memory for a world in case if number of objects/joint decreases
 193  * significantly in it.
 194  *
 195  * With sharing working memory worlds also automatically share memory reservation
 196  * policy and memory manager. Thus, these parameters need to be customized for
 197  * initial world to be used as sharing source only.
 198  *
 199  * If worlds share working memory they must also use compatible threading implementations
 200  * (i.e. it is illegal for one world to perform stepping with self-threaded implementation
 201  * when the other world is assigned a multi-threaded implementation).
 202  * For more information read section about threading approaches in ODE.
 203  *
 204  * Failure result status means a memory allocation failure.
 205  *
 206  * @param w The world to use the shared memory with.
 207  * @param from_world Null or the world the shared memory is to be used from.
 208  * @returns 1 for success and 0 for failure.
 209  *
 210  * @ingroup world
 211  * @see dWorldCleanupWorkingMemory
 212  * @see dWorldSetStepMemoryReservationPolicy
 213  * @see dWorldSetStepMemoryManager
 214  */
 215 ODE_API int dWorldUseSharedWorkingMemory(dWorldID w, dWorldID from_world/*=NULL*/);
 216
 217 /**
 218  * @brief Release internal working memory allocated for world
 219  *
 220  * The worlds allocate working memory internally for simulation stepping. This
 221  * function can be used to free world's internal memory cache in case if number of
 222  * objects/joints in the world decreases significantly. By default, internal
 223  * allocation policy is used to only increase cache size as necessary and never
 224  * decrease it.
 225  *
 226  * If a world shares its working memory with other worlds the cache deletion
 227  * affects all the linked worlds. However the shared status itself remains intact.
 228  *
 229  * The function call does affect neither memory reservation policy nor memory manager.
 230  *
 231  * @param w The world to release working memory for.
 232  *
 233  * @ingroup world
 234  * @see dWorldUseSharedWorkingMemory
 235  * @see dWorldSetStepMemoryReservationPolicy
 236  * @see dWorldSetStepMemoryManager
 237  */
 238 ODE_API void dWorldCleanupWorkingMemory(dWorldID w);
 239
 240
 241 #define dWORLDSTEP_RESERVEFACTOR_DEFAULT    1.2f
 242 #define dWORLDSTEP_RESERVESIZE_DEFAULT      65536U
 243
 244 /**
 245  * @struct dWorldStepReserveInfo
 246  * @brief Memory reservation policy descriptor structure for world stepping functions.
 247  *
 248  * @c struct_size should be assigned the size of the structure.
 249  *
 250  * @c reserve_factor is a quotient that is multiplied by required memory size
 251  *  to allocate extra reserve whenever reallocation is needed.
 252  *
 253  * @c reserve_minimum is a minimum size that is checked against whenever reallocation
 254  * is needed to allocate expected working memory minimum at once without extra
 255  * reallocations as number of bodies/joints grows.
 256  *
 257  * @ingroup world
 258  * @see dWorldSetStepMemoryReservationPolicy
 259  */
 260 typedef struct
 261 {
 262   unsigned struct_size;
 263   float reserve_factor; /* Use float as precision does not matter here*/
 264   unsigned reserve_minimum;
 265
 266 } dWorldStepReserveInfo;
 267
 268 /**
 269  * @brief Set memory reservation policy for world to be used with simulation stepping functions
 270  *
 271  * The function allows to customize reservation policy to be used for internal
 272  * memory which is allocated to aid simulation for a world. By default, values
 273  * of @c dWORLDSTEP_RESERVEFACTOR_DEFAULT and @c dWORLDSTEP_RESERVESIZE_DEFAULT
 274  * are used.
 275  *
 276  * Passing @a policyinfo argument as NULL results in reservation policy being
 277  * reset to defaults as if the world has been just created. The content of
 278  * @a policyinfo structure is copied internally and does not need to remain valid
 279  * after the call returns.
 280  *
 281  * If the world uses working memory sharing, changing memory reservation policy
 282  * affects all the worlds linked together.
 283  *
 284  * Failure result status means a memory allocation failure.
 285  *
 286  * @param w The world to change memory reservation policy for.
 287  * @param policyinfo Null or a pointer to policy descriptor structure.
 288  * @returns 1 for success and 0 for failure.
 289  *
 290  * @ingroup world
 291  * @see dWorldUseSharedWorkingMemory
 292  */
 293 ODE_API int dWorldSetStepMemoryReservationPolicy(dWorldID w, const dWorldStepReserveInfo *policyinfo/*=NULL*/);
 294
 295 /**
 296 * @struct dWorldStepMemoryFunctionsInfo
 297 * @brief World stepping memory manager descriptor structure
 298 *
 299 * This structure is intended to define the functions of memory manager to be used
 300 * with world stepping functions.
 301 *
 302 * @c struct_size should be assigned the size of the structure
 303 *
 304 * @c alloc_block is a function to allocate memory block of given size.
 305 *
 306 * @c shrink_block is a function to shrink existing memory block to a smaller size.
 307 * It must preserve the contents of block head while shrinking. The new block size
 308 * is guaranteed to be always less than the existing one.
 309 *
 310 * @c free_block is a function to delete existing memory block.
 311 *
 312 * @ingroup init
 313 * @see dWorldSetStepMemoryManager
 314 */
 315 typedef struct
 316 {
 317   unsigned struct_size;
 318   void *(*alloc_block)(dsizeint block_size);
 319   void *(*shrink_block)(void *block_pointer, dsizeint block_current_size, dsizeint block_smaller_size);
 320   void (*free_block)(void *block_pointer, dsizeint block_current_size);
 321
 322 } dWorldStepMemoryFunctionsInfo;
 323
 324 /**
 325 * @brief Set memory manager for world to be used with simulation stepping functions
 326 *
 327 * The function allows to customize memory manager to be used for internal
 328 * memory allocation during simulation for a world. By default, @c dAlloc/@c dRealloc/@c dFree
 329 * based memory manager is used.
 330 *
 331 * Passing @a memfuncs argument as NULL results in memory manager being
 332 * reset to default one as if the world has been just created. The content of
 333 * @a memfuncs structure is copied internally and does not need to remain valid
 334 * after the call returns.
 335 *
 336 * If the world uses working memory sharing, changing memory manager
 337 * affects all the worlds linked together.
 338 *
 339 * Failure result status means a memory allocation failure.
 340 *
 341 * @param w The world to change memory reservation policy for.
 342 * @param memfuncs Null or a pointer to memory manager descriptor structure.
 343 * @returns 1 for success and 0 for failure.
 344 *
 345 * @ingroup world
 346 * @see dWorldUseSharedWorkingMemory
 347 */
 348 ODE_API int dWorldSetStepMemoryManager(dWorldID w, const dWorldStepMemoryFunctionsInfo *memfuncs);
 349
 350 /**
 351  * @brief Assign threading implementation to be used for [quick]stepping the world.
 352  *
 353  * @warning It is not recommended to assign the same threading implementation to
 354  * different worlds if they are going to be called in parallel. In particular this
 355  * makes resources preallocation for threaded calls to lose its sense.
 356  * Built-in threading implementation is likely to crash if misused this way.
 357  *
 358  * @param w The world to change threading implementation for.
 359  * @param functions_info Pointer to threading functions structure
 360  * @param threading_impl ID of threading implementation object
 361  *
 362  * @ingroup world
 363  */
 364 ODE_API void dWorldSetStepThreadingImplementation(dWorldID w, const dThreadingFunctionsInfo *functions_info, dThreadingImplementationID threading_impl);
 365
 366 /**
 367  * @brief Step the world.
 368  *
 369  * This uses a "big matrix" method that takes time on the order of m^3
 370  * and memory on the order of m^2, where m is the total number of constraint
 371  * rows. For large systems this will use a lot of memory and can be very slow,
 372  * but this is currently the most accurate method.
 373  *
 374  * Failure result status means that the memory allocation has failed for operation.
 375  * In such a case all the objects remain in unchanged state and simulation can be
 376  * retried as soon as more memory is available.
 377  *
 378  * @param w The world to be stepped
 379  * @param stepsize The number of seconds that the simulation has to advance.
 380  * @returns 1 for success and 0 for failure
 381  *
 382  * @ingroup world
 383  */
 384 ODE_API int dWorldStep (dWorldID w, dReal stepsize);
 385
 386 /**
 387  * @brief Quick-step the world.
 388  *
 389  * This uses an iterative method that takes time on the order of m*N
 390  * and memory on the order of m, where m is the total number of constraint
 391  * rows N is the number of iterations.
 392  * For large systems this is a lot faster than dWorldStep(),
 393  * but it is less accurate.
 394  *
 395  * QuickStep is great for stacks of objects especially when the
 396  * auto-disable feature is used as well.
 397  * However, it has poor accuracy for near-singular systems.
 398  * Near-singular systems can occur when using high-friction contacts, motors,
 399  * or certain articulated structures. For example, a robot with multiple legs
 400  * sitting on the ground may be near-singular.
 401  *
 402  * There are ways to help overcome QuickStep's inaccuracy problems:
 403  *
 404  * \li Increase CFM.
 405  * \li Reduce the number of contacts in your system (e.g. use the minimum
 406  *     number of contacts for the feet of a robot or creature).
 407  * \li Don't use excessive friction in the contacts.
 408  * \li Use contact slip if appropriate
 409  * \li Avoid kinematic loops (however, kinematic loops are inevitable in
 410  *     legged creatures).
 411  * \li Don't use excessive motor strength.
 412  * \liUse force-based motors instead of velocity-based motors.
 413  *
 414  * Increasing the number of QuickStep iterations may help a little bit, but
 415  * it is not going to help much if your system is really near singular.
 416  *
 417  * Failure result status means that the memory allocation has failed for operation.
 418  * In such a case all the objects remain in unchanged state and simulation can be
 419  * retried as soon as more memory is available.
 420  *
 421  * @param w The world to be stepped
 422  * @param stepsize The number of seconds that the simulation has to advance.
 423  * @returns 1 for success and 0 for failure
 424  *
 425  * @ingroup world
 426  */
 427 ODE_API int dWorldQuickStep (dWorldID w, dReal stepsize);
 428
 429
 430 /**
 431 * @brief Converts an impulse to a force.
 432 * @ingroup world
 433 * @remarks
 434 * If you want to apply a linear or angular impulse to a rigid body,
 435 * instead of a force or a torque, then you can use this function to convert
 436 * the desired impulse into a force/torque vector before calling the
 437 * BodyAdd... function.
 438 * The current algorithm simply scales the impulse by 1/stepsize,
 439 * where stepsize is the step size for the next step that will be taken.
 440 * This function is given a dWorldID because, in the future, the force
 441 * computation may depend on integrator parameters that are set as
 442 * properties of the world.
 443 */
 444 ODE_API void dWorldImpulseToForce
 445 (
 446  dWorldID, dReal stepsize,
 447  dReal ix, dReal iy, dReal iz, dVector3 force
 448  );
 449
 450
 451 /**
 452  * @brief Set the number of iterations that the QuickStep method performs per
 453  *        step.
 454  * @ingroup world
 455  * @remarks
 456  * More iterations will give a more accurate solution, but will take
 457  * longer to compute.
 458  * @param num The default is 20 iterations.
 459  */
 460 ODE_API void dWorldSetQuickStepNumIterations (dWorldID, int num);
 461
 462
 463 /**
 464  * @brief Get the number of iterations that the QuickStep method performs per
 465  *        step.
 466  * @ingroup world
 467  * @return nr of iterations
 468  */
 469 ODE_API int dWorldGetQuickStepNumIterations (dWorldID);
 470
 471 /**
 472  * @brief Set the SOR over-relaxation parameter
 473  * @ingroup world
 474  * @param over_relaxation value to use by SOR
 475  */
 476 ODE_API void dWorldSetQuickStepW (dWorldID, dReal over_relaxation);
 477
 478 /**
 479  * @brief Get the SOR over-relaxation parameter
 480  * @ingroup world
 481  * @returns the over-relaxation setting
 482  */
 483 ODE_API dReal dWorldGetQuickStepW (dWorldID);
 484
 485 /* World contact parameter functions */
 486
 487 /**
 488  * @brief Set the maximum correcting velocity that contacts are allowed
 489  * to generate.
 490  * @ingroup world
 491  * @param vel The default value is infinity (i.e. no limit).
 492  * @remarks
 493  * Reducing this value can help prevent "popping" of deeply embedded objects.
 494  */
 495 ODE_API void dWorldSetContactMaxCorrectingVel (dWorldID, dReal vel);
 496
 497 /**
 498  * @brief Get the maximum correcting velocity that contacts are allowed
 499  * to generated.
 500  * @ingroup world
 501  */
 502 ODE_API dReal dWorldGetContactMaxCorrectingVel (dWorldID);
 503
 504 /**
 505  * @brief Set the depth of the surface layer around all geometry objects.
 506  * @ingroup world
 507  * @remarks
 508  * Contacts are allowed to sink into the surface layer up to the given
 509  * depth before coming to rest.
 510  * @param depth The default value is zero.
 511  * @remarks
 512  * Increasing this to some small value (e.g. 0.001) can help prevent
 513  * jittering problems due to contacts being repeatedly made and broken.
 514  */
 515 ODE_API void dWorldSetContactSurfaceLayer (dWorldID, dReal depth);
 516
 517 /**
 518  * @brief Get the depth of the surface layer around all geometry objects.
 519  * @ingroup world
 520  * @returns the depth
 521  */
 522 ODE_API dReal dWorldGetContactSurfaceLayer (dWorldID);
 523
 524
 525 /**
 526  * @defgroup disable Automatic Enabling and Disabling
 527  * @ingroup world bodies
 528  *
 529  * Every body can be enabled or disabled. Enabled bodies participate in the
 530  * simulation, while disabled bodies are turned off and do not get updated
 531  * during a simulation step. New bodies are always created in the enabled state.
 532  *
 533  * A disabled body that is connected through a joint to an enabled body will be
 534  * automatically re-enabled at the next simulation step.
 535  *
 536  * Disabled bodies do not consume CPU time, therefore to speed up the simulation
 537  * bodies should be disabled when they come to rest. This can be done automatically
 538  * with the auto-disable feature.
 539  *
 540  * If a body has its auto-disable flag turned on, it will automatically disable
 541  * itself when
 542  *   @li It has been idle for a given number of simulation steps.
 543  *   @li It has also been idle for a given amount of simulation time.
 544  *
 545  * A body is considered to be idle when the magnitudes of both its
 546  * linear average velocity and angular average velocity are below given thresholds.
 547  * The sample size for the average defaults to one and can be disabled by setting
 548  * to zero with
 549  *
 550  * Thus, every body has six auto-disable parameters: an enabled flag, a idle step
 551  * count, an idle time, linear/angular average velocity thresholds, and the
 552  * average samples count.
 553  *
 554  * Newly created bodies get these parameters from world.
 555  */
 556
 557 /**
 558  * @brief Get auto disable linear average threshold for newly created bodies.
 559  * @ingroup disable
 560  * @return the threshold
 561  */
 562 ODE_API dReal dWorldGetAutoDisableLinearThreshold (dWorldID);
 563
 564 /**
 565  * @brief Set auto disable linear average threshold for newly created bodies.
 566  * @param linear_average_threshold default is 0.01
 567  * @ingroup disable
 568  */
 569 ODE_API void  dWorldSetAutoDisableLinearThreshold (dWorldID, dReal linear_average_threshold);
 570
 571 /**
 572  * @brief Get auto disable angular average threshold for newly created bodies.
 573  * @ingroup disable
 574  * @return the threshold
 575  */
 576 ODE_API dReal dWorldGetAutoDisableAngularThreshold (dWorldID);
 577
 578 /**
 579  * @brief Set auto disable angular average threshold for newly created bodies.
 580  * @param linear_average_threshold default is 0.01
 581  * @ingroup disable
 582  */
 583 ODE_API void dWorldSetAutoDisableAngularThreshold (dWorldID, dReal angular_average_threshold);
 584
 585 /**
 586  * @brief Get auto disable sample count for newly created bodies.
 587  * @ingroup disable
 588  * @return number of samples used
 589  */
 590 ODE_API int dWorldGetAutoDisableAverageSamplesCount (dWorldID);
 591
 592 /**
 593  * @brief Set auto disable average sample count for newly created bodies.
 594  * @ingroup disable
 595  * @param average_samples_count Default is 1, meaning only instantaneous velocity is used.
 596  * Set to zero to disable sampling and thus prevent any body from auto-disabling.
 597  */
 598 ODE_API void dWorldSetAutoDisableAverageSamplesCount (dWorldID, unsigned int average_samples_count );
 599
 600 /**
 601  * @brief Get auto disable steps for newly created bodies.
 602  * @ingroup disable
 603  * @return nr of steps
 604  */
 605 ODE_API int dWorldGetAutoDisableSteps (dWorldID);
 606
 607 /**
 608  * @brief Set auto disable steps for newly created bodies.
 609  * @ingroup disable
 610  * @param steps default is 10
 611  */
 612 ODE_API void dWorldSetAutoDisableSteps (dWorldID, int steps);
 613
 614 /**
 615  * @brief Get auto disable time for newly created bodies.
 616  * @ingroup disable
 617  * @return nr of seconds
 618  */
 619 ODE_API dReal dWorldGetAutoDisableTime (dWorldID);
 620
 621 /**
 622  * @brief Set auto disable time for newly created bodies.
 623  * @ingroup disable
 624  * @param time default is 0 seconds
 625  */
 626 ODE_API void dWorldSetAutoDisableTime (dWorldID, dReal time);
 627
 628 /**
 629  * @brief Get auto disable flag for newly created bodies.
 630  * @ingroup disable
 631  * @return 0 or 1
 632  */
 633 ODE_API int dWorldGetAutoDisableFlag (dWorldID);
 634
 635 /**
 636  * @brief Set auto disable flag for newly created bodies.
 637  * @ingroup disable
 638  * @param do_auto_disable default is false.
 639  */
 640 ODE_API void dWorldSetAutoDisableFlag (dWorldID, int do_auto_disable);
 641
 642
 643 /**
 644  * @defgroup damping Damping
 645  * @ingroup bodies world
 646  *
 647  * Damping serves two purposes: reduce simulation instability, and to allow
 648  * the bodies to come to rest (and possibly auto-disabling them).
 649  *
 650  * Bodies are constructed using the world's current damping parameters. Setting
 651  * the scales to 0 disables the damping.
 652  *
 653  * Here is how it is done: after every time step linear and angular
 654  * velocities are tested against the corresponding thresholds. If they
 655  * are above, they are multiplied by (1 - scale). So a negative scale value
 656  * will actually increase the speed, and values greater than one will
 657  * make the object oscillate every step; both can make the simulation unstable.
 658  *
 659  * To disable damping just set the damping scale to zero.
 660  *
 661  * You can also limit the maximum angular velocity. In contrast to the damping
 662  * functions, the angular velocity is affected before the body is moved.
 663  * This means that it will introduce errors in joints that are forcing the body
 664  * to rotate too fast. Some bodies have naturally high angular velocities
 665  * (like cars' wheels), so you may want to give them a very high (like the default,
 666  * dInfinity) limit.
 667  *
 668  * @note The velocities are damped after the stepper function has moved the
 669  * object. Otherwise the damping could introduce errors in joints. First the
 670  * joint constraints are processed by the stepper (moving the body), then
 671  * the damping is applied.
 672  *
 673  * @note The damping happens right after the moved callback is called; this way
 674  * it still possible use the exact velocities the body has acquired during the
 675  * step. You can even use the callback to create your own customized damping.
 676  */
 677
 678 /**
 679  * @brief Get the world's linear damping threshold.
 680  * @ingroup damping
 681  */
 682 ODE_API dReal dWorldGetLinearDampingThreshold (dWorldID w);
 683
 684 /**
 685  * @brief Set the world's linear damping threshold.
 686  * @param threshold The damping won't be applied if the linear speed is
 687  *        below this threshold. Default is 0.01.
 688  * @ingroup damping
 689  */
 690 ODE_API void dWorldSetLinearDampingThreshold(dWorldID w, dReal threshold);
 691
 692 /**
 693  * @brief Get the world's angular damping threshold.
 694  * @ingroup damping
 695  */
 696 ODE_API dReal dWorldGetAngularDampingThreshold (dWorldID w);
 697
 698 /**
 699  * @brief Set the world's angular damping threshold.
 700  * @param threshold The damping won't be applied if the angular speed is
 701  *        below this threshold. Default is 0.01.
 702  * @ingroup damping
 703  */
 704 ODE_API void dWorldSetAngularDampingThreshold(dWorldID w, dReal threshold);
 705
 706 /**
 707  * @brief Get the world's linear damping scale.
 708  * @ingroup damping
 709  */
 710 ODE_API dReal dWorldGetLinearDamping (dWorldID w);
 711
 712 /**
 713  * @brief Set the world's linear damping scale.
 714  * @param scale The linear damping scale that is to be applied to bodies.
 715  * Default is 0 (no damping). Should be in the interval [0, 1].
 716  * @ingroup damping
 717  */
 718 ODE_API void dWorldSetLinearDamping (dWorldID w, dReal scale);
 719
 720 /**
 721  * @brief Get the world's angular damping scale.
 722  * @ingroup damping
 723  */
 724 ODE_API dReal dWorldGetAngularDamping (dWorldID w);
 725
 726 /**
 727  * @brief Set the world's angular damping scale.
 728  * @param scale The angular damping scale that is to be applied to bodies.
 729  * Default is 0 (no damping). Should be in the interval [0, 1].
 730  * @ingroup damping
 731  */
 732 ODE_API void dWorldSetAngularDamping(dWorldID w, dReal scale);
 733
 734 /**
 735  * @brief Convenience function to set body linear and angular scales.
 736  * @param linear_scale The linear damping scale that is to be applied to bodies.
 737  * @param angular_scale The angular damping scale that is to be applied to bodies.
 738  * @ingroup damping
 739  */
 740 ODE_API void dWorldSetDamping(dWorldID w,
 741                                 dReal linear_scale,
 742                                 dReal angular_scale);
 743
 744 /**
 745  * @brief Get the default maximum angular speed.
 746  * @ingroup damping
 747  * @sa dBodyGetMaxAngularSpeed()
 748  */
 749 ODE_API dReal dWorldGetMaxAngularSpeed (dWorldID w);
 750
 751
 752 /**
 753  * @brief Set the default maximum angular speed for new bodies.
 754  * @ingroup damping
 755  * @sa dBodySetMaxAngularSpeed()
 756  */
 757 ODE_API void dWorldSetMaxAngularSpeed (dWorldID w, dReal max_speed);
 758
 759
 760
 761 /**
 762  * @defgroup bodies Rigid Bodies
 763  *
 764  * A rigid body has various properties from the point of view of the
 765  * simulation. Some properties change over time:
 766  *
 767  *  @li Position vector (x,y,z) of the body's point of reference.
 768  *      Currently the point of reference must correspond to the body's center of mass.
 769  *  @li Linear velocity of the point of reference, a vector (vx,vy,vz).
 770  *  @li Orientation of a body, represented by a quaternion (qs,qx,qy,qz) or
 771  *      a 3x3 rotation matrix.
 772  *  @li Angular velocity vector (wx,wy,wz) which describes how the orientation
 773  *      changes over time.
 774  *
 775  * Other body properties are usually constant over time:
 776  *
 777  *  @li Mass of the body.
 778  *  @li Position of the center of mass with respect to the point of reference.
 779  *      In the current implementation the center of mass and the point of
 780  *      reference must coincide.
 781  *  @li Inertia matrix. This is a 3x3 matrix that describes how the body's mass
 782  *      is distributed around the center of mass. Conceptually each body has an
 783  *      x-y-z coordinate frame embedded in it that moves and rotates with the body.
 784  *
 785  * The origin of this coordinate frame is the body's point of reference. Some values
 786  * in ODE (vectors, matrices etc) are relative to the body coordinate frame, and others
 787  * are relative to the global coordinate frame.
 788  *
 789  * Note that the shape of a rigid body is not a dynamical property (except insofar as
 790  * it influences the various mass properties). It is only collision detection that cares
 791  * about the detailed shape of the body.
 792  */
 793
 794
 795 /**
 796  * @brief Get auto disable linear average threshold.
 797  * @ingroup bodies disable
 798  * @return the threshold
 799  */
 800 ODE_API dReal dBodyGetAutoDisableLinearThreshold (dBodyID);
 801
 802 /**
 803  * @brief Set auto disable linear average threshold.
 804  * @ingroup bodies disable
 805  * @return the threshold
 806  */
 807 ODE_API void  dBodySetAutoDisableLinearThreshold (dBodyID, dReal linear_average_threshold);
 808
 809 /**
 810  * @brief Get auto disable angular average threshold.
 811  * @ingroup bodies disable
 812  * @return the threshold
 813  */
 814 ODE_API dReal dBodyGetAutoDisableAngularThreshold (dBodyID);
 815
 816 /**
 817  * @brief Set auto disable angular average threshold.
 818  * @ingroup bodies disable
 819  * @return the threshold
 820  */
 821 ODE_API void  dBodySetAutoDisableAngularThreshold (dBodyID, dReal angular_average_threshold);
 822
 823 /**
 824  * @brief Get auto disable average size (samples count).
 825  * @ingroup bodies disable
 826  * @return the nr of steps/size.
 827  */
 828 ODE_API int dBodyGetAutoDisableAverageSamplesCount (dBodyID);
 829
 830 /**
 831  * @brief Set auto disable average buffer size (average steps).
 832  * @ingroup bodies disable
 833  * @param average_samples_count the nr of samples to review.
 834  */
 835 ODE_API void dBodySetAutoDisableAverageSamplesCount (dBodyID, unsigned int average_samples_count);
 836
 837
 838 /**
 839  * @brief Get auto steps a body must be thought of as idle to disable
 840  * @ingroup bodies disable
 841  * @return the nr of steps
 842  */
 843 ODE_API int dBodyGetAutoDisableSteps (dBodyID);
 844
 845 /**
 846  * @brief Set auto disable steps.
 847  * @ingroup bodies disable
 848  * @param steps the nr of steps.
 849  */
 850 ODE_API void dBodySetAutoDisableSteps (dBodyID, int steps);
 851
 852 /**
 853  * @brief Get auto disable time.
 854  * @ingroup bodies disable
 855  * @return nr of seconds
 856  */
 857 ODE_API dReal dBodyGetAutoDisableTime (dBodyID);
 858
 859 /**
 860  * @brief Set auto disable time.
 861  * @ingroup bodies disable
 862  * @param time nr of seconds.
 863  */
 864 ODE_API void  dBodySetAutoDisableTime (dBodyID, dReal time);
 865
 866 /**
 867  * @brief Get auto disable flag.
 868  * @ingroup bodies disable
 869  * @return 0 or 1
 870  */
 871 ODE_API int dBodyGetAutoDisableFlag (dBodyID);
 872
 873 /**
 874  * @brief Set auto disable flag.
 875  * @ingroup bodies disable
 876  * @param do_auto_disable 0 or 1
 877  */
 878 ODE_API void dBodySetAutoDisableFlag (dBodyID, int do_auto_disable);
 879
 880 /**
 881  * @brief Set auto disable defaults.
 882  * @remarks
 883  * Set the values for the body to those set as default for the world.
 884  * @ingroup bodies disable
 885  */
 886 ODE_API void  dBodySetAutoDisableDefaults (dBodyID);
 887
 888
 889 /**
 890  * @brief Retrieves the world attached to te given body.
 891  * @remarks
 892  *
 893  * @ingroup bodies
 894  */
 895 ODE_API dWorldID dBodyGetWorld (dBodyID);
 896
 897 /**
 898  * @brief Create a body in given world.
 899  * @remarks
 900  * Default mass parameters are at position (0,0,0).
 901  * @ingroup bodies
 902  */
 903 ODE_API dBodyID dBodyCreate (dWorldID);
 904
 905 /**
 906  * @brief Destroy a body.
 907  * @remarks
 908  * All joints that are attached to this body will be put into limbo:
 909  * i.e. unattached and not affecting the simulation, but they will NOT be
 910  * deleted.
 911  * @ingroup bodies
 912  */
 913 ODE_API void dBodyDestroy (dBodyID);
 914
 915 /**
 916  * @brief Set the body's user-data pointer.
 917  * @ingroup bodies
 918  * @param data arbitraty pointer
 919  */
 920 ODE_API void  dBodySetData (dBodyID, void *data);
 921
 922 /**
 923  * @brief Get the body's user-data pointer.
 924  * @ingroup bodies
 925  * @return a pointer to the user's data.
 926  */
 927 ODE_API void *dBodyGetData (dBodyID);
 928
 929 /**
 930  * @brief Set position of a body.
 931  * @remarks
 932  * After setting, the outcome of the simulation is undefined
 933  * if the new configuration is inconsistent with the joints/constraints
 934  * that are present.
 935  * @ingroup bodies
 936  */
 937 ODE_API void dBodySetPosition   (dBodyID, dReal x, dReal y, dReal z);
 938
 939 /**
 940  * @brief Set the orientation of a body.
 941  * @ingroup bodies
 942  * @remarks
 943  * After setting, the outcome of the simulation is undefined
 944  * if the new configuration is inconsistent with the joints/constraints
 945  * that are present.
 946  */
 947 ODE_API void dBodySetRotation   (dBodyID, const dMatrix3 R);
 948
 949 /**
 950  * @brief Set the orientation of a body.
 951  * @ingroup bodies
 952  * @remarks
 953  * After setting, the outcome of the simulation is undefined
 954  * if the new configuration is inconsistent with the joints/constraints
 955  * that are present.
 956  */
 957 ODE_API void dBodySetQuaternion (dBodyID, const dQuaternion q);
 958
 959 /**
 960  * @brief Set the linear velocity of a body.
 961  * @ingroup bodies
 962  */
 963 ODE_API void dBodySetLinearVel  (dBodyID, dReal x, dReal y, dReal z);
 964
 965 /**
 966  * @brief Set the angular velocity of a body.
 967  * @ingroup bodies
 968  */
 969 ODE_API void dBodySetAngularVel (dBodyID, dReal x, dReal y, dReal z);
 970
 971 /**
 972  * @brief Get the position of a body.
 973  * @ingroup bodies
 974  * @remarks
 975  * When getting, the returned values are pointers to internal data structures,
 976  * so the vectors are valid until any changes are made to the rigid body
 977  * system structure.
 978  * @sa dBodyCopyPosition
 979  */
 980 ODE_API const dReal * dBodyGetPosition (dBodyID);
 981
 982
 983 /**
 984  * @brief Copy the position of a body into a vector.
 985  * @ingroup bodies
 986  * @param body  the body to query
 987  * @param pos   a copy of the body position
 988  * @sa dBodyGetPosition
 989  */
 990 ODE_API void dBodyCopyPosition (dBodyID body, dVector3 pos);
 991
 992
 993 /**
 994  * @brief Get the rotation of a body.
 995  * @ingroup bodies
 996  * @return pointer to a 4x3 rotation matrix.
 997  */
 998 ODE_API const dReal * dBodyGetRotation (dBodyID);
 999
1000
1001 /**
1002  * @brief Copy the rotation of a body.
1003  * @ingroup bodies
1004  * @param body   the body to query
1005  * @param R      a copy of the rotation matrix
1006  * @sa dBodyGetRotation
1007  */
1008 ODE_API void dBodyCopyRotation (dBodyID, dMatrix3 R);
1009
1010
1011 /**
1012  * @brief Get the rotation of a body.
1013  * @ingroup bodies
1014  * @return pointer to 4 scalars that represent the quaternion.
1015  */
1016 ODE_API const dReal * dBodyGetQuaternion (dBodyID);
1017
1018
1019 /**
1020  * @brief Copy the orientation of a body into a quaternion.
1021  * @ingroup bodies
1022  * @param body  the body to query
1023  * @param quat  a copy of the orientation quaternion
1024  * @sa dBodyGetQuaternion
1025  */
1026 ODE_API void dBodyCopyQuaternion(dBodyID body, dQuaternion quat);
1027
1028
1029 /**
1030  * @brief Get the linear velocity of a body.
1031  * @ingroup bodies
1032  */
1033 ODE_API const dReal * dBodyGetLinearVel (dBodyID);
1034
1035 /**
1036  * @brief Get the angular velocity of a body.
1037  * @ingroup bodies
1038  */
1039 ODE_API const dReal * dBodyGetAngularVel (dBodyID);
1040
1041 /**
1042  * @brief Set the mass of a body.
1043  * @ingroup bodies
1044  */
1045 ODE_API void dBodySetMass (dBodyID, const dMass *mass);
1046
1047 /**
1048  * @brief Get the mass of a body.
1049  * @ingroup bodies
1050  */
1051 ODE_API void dBodyGetMass (dBodyID, dMass *mass);
1052
1053 /**
1054  * @brief Add force at centre of mass of body in absolute coordinates.
1055  * @ingroup bodies
1056  */
1057 ODE_API void dBodyAddForce            (dBodyID, dReal fx, dReal fy, dReal fz);
1058
1059 /**
1060  * @brief Add torque at centre of mass of body in absolute coordinates.
1061  * @ingroup bodies
1062  */
1063 ODE_API void dBodyAddTorque           (dBodyID, dReal fx, dReal fy, dReal fz);
1064
1065 /**
1066  * @brief Add force at centre of mass of body in coordinates relative to body.
1067  * @ingroup bodies
1068  */
1069 ODE_API void dBodyAddRelForce         (dBodyID, dReal fx, dReal fy, dReal fz);
1070
1071 /**
1072  * @brief Add torque at centre of mass of body in coordinates relative to body.
1073  * @ingroup bodies
1074  */
1075 ODE_API void dBodyAddRelTorque        (dBodyID, dReal fx, dReal fy, dReal fz);
1076
1077 /**
1078  * @brief Add force at specified point in body in global coordinates.
1079  * @ingroup bodies
1080  */
1081 ODE_API void dBodyAddForceAtPos       (dBodyID, dReal fx, dReal fy, dReal fz,
1082                                         dReal px, dReal py, dReal pz);
1083 /**
1084  * @brief Add force at specified point in body in local coordinates.
1085  * @ingroup bodies
1086  */
1087 ODE_API void dBodyAddForceAtRelPos    (dBodyID, dReal fx, dReal fy, dReal fz,
1088                                         dReal px, dReal py, dReal pz);
1089 /**
1090  * @brief Add force at specified point in body in global coordinates.
1091  * @ingroup bodies
1092  */
1093 ODE_API void dBodyAddRelForceAtPos    (dBodyID, dReal fx, dReal fy, dReal fz,
1094                                         dReal px, dReal py, dReal pz);
1095 /**
1096  * @brief Add force at specified point in body in local coordinates.
1097  * @ingroup bodies
1098  */
1099 ODE_API void dBodyAddRelForceAtRelPos (dBodyID, dReal fx, dReal fy, dReal fz,
1100                                         dReal px, dReal py, dReal pz);
1101
1102 /**
1103  * @brief Return the current accumulated force vector.
1104  * @return points to an array of 3 reals.
1105  * @remarks
1106  * The returned values are pointers to internal data structures, so
1107  * the vectors are only valid until any changes are made to the rigid
1108  * body system.
1109  * @ingroup bodies
1110  */
1111 ODE_API const dReal * dBodyGetForce (dBodyID);
1112
1113 /**
1114  * @brief Return the current accumulated torque vector.
1115  * @return points to an array of 3 reals.
1116  * @remarks
1117  * The returned values are pointers to internal data structures, so
1118  * the vectors are only valid until any changes are made to the rigid
1119  * body system.
1120  * @ingroup bodies
1121  */
1122 ODE_API const dReal * dBodyGetTorque (dBodyID);
1123
1124 /**
1125  * @brief Set the body force accumulation vector.
1126  * @remarks
1127  * This is mostly useful to zero the force and torque for deactivated bodies
1128  * before they are reactivated, in the case where the force-adding functions
1129  * were called on them while they were deactivated.
1130  * @ingroup bodies
1131  */
1132 ODE_API void dBodySetForce  (dBodyID b, dReal x, dReal y, dReal z);
1133
1134 /**
1135  * @brief Set the body torque accumulation vector.
1136  * @remarks
1137  * This is mostly useful to zero the force and torque for deactivated bodies
1138  * before they are reactivated, in the case where the force-adding functions
1139  * were called on them while they were deactivated.
1140  * @ingroup bodies
1141  */
1142 ODE_API void dBodySetTorque (dBodyID b, dReal x, dReal y, dReal z);
1143
1144 /**
1145  * @brief Get world position of a relative point on body.
1146  * @ingroup bodies
1147  * @param result will contain the result.
1148  */
1149 ODE_API void dBodyGetRelPointPos
1150 (
1151   dBodyID, dReal px, dReal py, dReal pz,
1152   dVector3 result
1153 );
1154
1155 /**
1156  * @brief Get velocity vector in global coords of a relative point on body.
1157  * @ingroup bodies
1158  * @param result will contain the result.
1159  */
1160 ODE_API void dBodyGetRelPointVel
1161 (
1162   dBodyID, dReal px, dReal py, dReal pz,
1163   dVector3 result
1164 );
1165
1166 /**
1167  * @brief Get velocity vector in global coords of a globally
1168  * specified point on a body.
1169  * @ingroup bodies
1170  * @param result will contain the result.
1171  */
1172 ODE_API void dBodyGetPointVel
1173 (
1174   dBodyID, dReal px, dReal py, dReal pz,
1175   dVector3 result
1176 );
1177
1178 /**
1179  * @brief takes a point in global coordinates and returns
1180  * the point's position in body-relative coordinates.
1181  * @remarks
1182  * This is the inverse of dBodyGetRelPointPos()
1183  * @ingroup bodies
1184  * @param result will contain the result.
1185  */
1186 ODE_API void dBodyGetPosRelPoint
1187 (
1188   dBodyID, dReal px, dReal py, dReal pz,
1189   dVector3 result
1190 );
1191
1192 /**
1193  * @brief Convert from local to world coordinates.
1194  * @ingroup bodies
1195  * @param result will contain the result.
1196  */
1197 ODE_API void dBodyVectorToWorld
1198 (
1199   dBodyID, dReal px, dReal py, dReal pz,
1200   dVector3 result
1201 );
1202
1203 /**
1204  * @brief Convert from world to local coordinates.
1205  * @ingroup bodies
1206  * @param result will contain the result.
1207  */
1208 ODE_API void dBodyVectorFromWorld
1209 (
1210   dBodyID, dReal px, dReal py, dReal pz,
1211   dVector3 result
1212 );
1213
1214 /**
1215  * @brief controls the way a body's orientation is updated at each timestep.
1216  * @ingroup bodies
1217  * @param mode can be 0 or 1:
1218  * \li 0: An ``infinitesimal'' orientation update is used.
1219  * This is fast to compute, but it can occasionally cause inaccuracies
1220  * for bodies that are rotating at high speed, especially when those
1221  * bodies are joined to other bodies.
1222  * This is the default for every new body that is created.
1223  * \li 1: A ``finite'' orientation update is used.
1224  * This is more costly to compute, but will be more accurate for high
1225  * speed rotations.
1226  * @remarks
1227  * Note however that high speed rotations can result in many types of
1228  * error in a simulation, and the finite mode will only fix one of those
1229  * sources of error.
1230  */
1231 ODE_API void dBodySetFiniteRotationMode (dBodyID, int mode);
1232
1233 /**
1234  * @brief sets the finite rotation axis for a body.
1235  * @ingroup bodies
1236  * @remarks
1237  * This is axis only has meaning when the finite rotation mode is set
1238  * If this axis is zero (0,0,0), full finite rotations are performed on
1239  * the body.
1240  * If this axis is nonzero, the body is rotated by performing a partial finite
1241  * rotation along the axis direction followed by an infinitesimal rotation
1242  * along an orthogonal direction.
1243  * @remarks
1244  * This can be useful to alleviate certain sources of error caused by quickly
1245  * spinning bodies. For example, if a car wheel is rotating at high speed
1246  * you can call this function with the wheel's hinge axis as the argument to
1247  * try and improve its behavior.
1248  */
1249 ODE_API void dBodySetFiniteRotationAxis (dBodyID, dReal x, dReal y, dReal z);
1250
1251 /**
1252  * @brief Get the way a body's orientation is updated each timestep.
1253  * @ingroup bodies
1254  * @return the mode 0 (infitesimal) or 1 (finite).
1255  */
1256 ODE_API int dBodyGetFiniteRotationMode (dBodyID);
1257
1258 /**
1259  * @brief Get the finite rotation axis.
1260  * @param result will contain the axis.
1261  * @ingroup bodies
1262  */
1263 ODE_API void dBodyGetFiniteRotationAxis (dBodyID, dVector3 result);
1264
1265 /**
1266  * @brief Get the number of joints that are attached to this body.
1267  * @ingroup bodies
1268  * @return nr of joints
1269  */
1270 ODE_API int dBodyGetNumJoints (dBodyID b);
1271
1272 /**
1273  * @brief Return a joint attached to this body, given by index.
1274  * @ingroup bodies
1275  * @param index valid range is  0 to n-1 where n is the value returned by
1276  * dBodyGetNumJoints().
1277  */
1278 ODE_API dJointID dBodyGetJoint (dBodyID, int index);
1279
1280
1281
1282
1283 /**
1284  * @brief Set rigid body to dynamic state (default).
1285  * @param dBodyID identification of body.
1286  * @ingroup bodies
1287  */
1288 ODE_API void dBodySetDynamic (dBodyID);
1289
1290 /**
1291  * @brief Set rigid body to kinematic state.
1292  * When in kinematic state the body isn't simulated as a dynamic
1293  * body (it's "unstoppable", doesn't respond to forces),
1294  * but can still affect dynamic bodies (e.g. in joints).
1295  * Kinematic bodies can be controlled by position and velocity.
1296  * @note A kinematic body has infinite mass. If you set its mass
1297  * to something else, it loses the kinematic state and behaves
1298  * as a normal dynamic body.
1299  * @param dBodyID identification of body.
1300  * @ingroup bodies
1301  */
1302 ODE_API void dBodySetKinematic (dBodyID);
1303
1304 /**
1305  * @brief Check wether a body is in kinematic state.
1306  * @ingroup bodies
1307  * @return 1 if a body is kinematic or 0 if it is dynamic.
1308  */
1309 ODE_API int dBodyIsKinematic (dBodyID);
1310
1311 /**
1312  * @brief Manually enable a body.
1313  * @param dBodyID identification of body.
1314  * @ingroup bodies
1315  */
1316 ODE_API void dBodyEnable (dBodyID);
1317
1318 /**
1319  * @brief Manually disable a body.
1320  * @ingroup bodies
1321  * @remarks
1322  * A disabled body that is connected through a joint to an enabled body will
1323  * be automatically re-enabled at the next simulation step.
1324  */
1325 ODE_API void dBodyDisable (dBodyID);
1326
1327 /**
1328  * @brief Check wether a body is enabled.
1329  * @ingroup bodies
1330  * @return 1 if a body is currently enabled or 0 if it is disabled.
1331  */
1332 ODE_API int dBodyIsEnabled (dBodyID);
1333
1334 /**
1335  * @brief Set whether the body is influenced by the world's gravity or not.
1336  * @ingroup bodies
1337  * @param mode when nonzero gravity affects this body.
1338  * @remarks
1339  * Newly created bodies are always influenced by the world's gravity.
1340  */
1341 ODE_API void dBodySetGravityMode (dBodyID b, int mode);
1342
1343 /**
1344  * @brief Get whether the body is influenced by the world's gravity or not.
1345  * @ingroup bodies
1346  * @return nonzero means gravity affects this body.
1347  */
1348 ODE_API int dBodyGetGravityMode (dBodyID b);
1349
1350 /**
1351  * @brief Set the 'moved' callback of a body.
1352  *
1353  * Whenever a body has its position or rotation changed during the
1354  * timestep, the callback will be called (with body as the argument).
1355  * Use it to know which body may need an update in an external
1356  * structure (like a 3D engine).
1357  *
1358  * @param b the body that needs to be watched.
1359  * @param callback the callback to be invoked when the body moves. Set to zero
1360  * to disable.
1361  * @ingroup bodies
1362  */
1363 ODE_API void dBodySetMovedCallback(dBodyID b, void (*callback)(dBodyID));
1364
1365
1366 /**
1367  * @brief Return the first geom associated with the body.
1368  *
1369  * You can traverse through the geoms by repeatedly calling
1370  * dBodyGetNextGeom().
1371  *
1372  * @return the first geom attached to this body, or 0.
1373  * @ingroup bodies
1374  */
1375 ODE_API dGeomID dBodyGetFirstGeom (dBodyID b);
1376
1377
1378 /**
1379  * @brief returns the next geom associated with the same body.
1380  * @param g a geom attached to some body.
1381  * @return the next geom attached to the same body, or 0.
1382  * @sa dBodyGetFirstGeom
1383  * @ingroup bodies
1384  */
1385 ODE_API dGeomID dBodyGetNextGeom (dGeomID g);
1386
1387
1388 /**
1389  * @brief Resets the damping settings to the current world's settings.
1390  * @ingroup bodies damping
1391  */
1392 ODE_API void dBodySetDampingDefaults(dBodyID b);
1393
1394 /**
1395  * @brief Get the body's linear damping scale.
1396  * @ingroup bodies damping
1397  */
1398 ODE_API dReal dBodyGetLinearDamping (dBodyID b);
1399
1400 /**
1401  * @brief Set the body's linear damping scale.
1402  * @param scale The linear damping scale. Should be in the interval [0, 1].
1403  * @ingroup bodies damping
1404  * @remarks From now on the body will not use the world's linear damping
1405  * scale until dBodySetDampingDefaults() is called.
1406  * @sa dBodySetDampingDefaults()
1407  */
1408 ODE_API void dBodySetLinearDamping(dBodyID b, dReal scale);
1409
1410 /**
1411  * @brief Get the body's angular damping scale.
1412  * @ingroup bodies damping
1413  * @remarks If the body's angular damping scale was not set, this function
1414  * returns the world's angular damping scale.
1415  */
1416 ODE_API dReal dBodyGetAngularDamping (dBodyID b);
1417
1418 /**
1419  * @brief Set the body's angular damping scale.
1420  * @param scale The angular damping scale. Should be in the interval [0, 1].
1421  * @ingroup bodies damping
1422  * @remarks From now on the body will not use the world's angular damping
1423  * scale until dBodyResetAngularDamping() is called.
1424  * @sa dBodyResetAngularDamping()
1425  */
1426 ODE_API void dBodySetAngularDamping(dBodyID b, dReal scale);
1427
1428 /**
1429  * @brief Convenience function to set linear and angular scales at once.
1430  * @param linear_scale The linear damping scale. Should be in the interval [0, 1].
1431  * @param angular_scale The angular damping scale. Should be in the interval [0, 1].
1432  * @ingroup bodies damping
1433  * @sa dBodySetLinearDamping() dBodySetAngularDamping()
1434  */
1435 ODE_API void dBodySetDamping(dBodyID b, dReal linear_scale, dReal angular_scale);
1436
1437 /**
1438  * @brief Get the body's linear damping threshold.
1439  * @ingroup bodies damping
1440  */
1441 ODE_API dReal dBodyGetLinearDampingThreshold (dBodyID b);
1442
1443 /**
1444  * @brief Set the body's linear damping threshold.
1445  * @param threshold The linear threshold to be used. Damping
1446  *      is only applied if the linear speed is above this limit.
1447  * @ingroup bodies damping
1448  */
1449 ODE_API void dBodySetLinearDampingThreshold(dBodyID b, dReal threshold);
1450
1451 /**
1452  * @brief Get the body's angular damping threshold.
1453  * @ingroup bodies damping
1454  */
1455 ODE_API dReal dBodyGetAngularDampingThreshold (dBodyID b);
1456
1457 /**
1458  * @brief Set the body's angular damping threshold.
1459  * @param threshold The angular threshold to be used. Damping is
1460  *      only used if the angular speed is above this limit.
1461  * @ingroup bodies damping
1462  */
1463 ODE_API void dBodySetAngularDampingThreshold(dBodyID b, dReal threshold);
1464
1465 /**
1466  * @brief Get the body's maximum angular speed.
1467  * @ingroup damping bodies
1468  * @sa dWorldGetMaxAngularSpeed()
1469  */
1470 ODE_API dReal dBodyGetMaxAngularSpeed (dBodyID b);
1471
1472 /**
1473  * @brief Set the body's maximum angular speed.
1474  * @ingroup damping bodies
1475  * @sa dWorldSetMaxAngularSpeed() dBodyResetMaxAngularSpeed()
1476  * The default value is dInfinity, but it's a good idea to limit
1477  * it at less than 500 if the body has the gyroscopic term
1478  * enabled.
1479  */
1480 ODE_API void dBodySetMaxAngularSpeed(dBodyID b, dReal max_speed);
1481
1482
1483
1484 /**
1485  * @brief Get the body's gyroscopic state.
1486  *
1487  * @return nonzero if gyroscopic term computation is enabled (default),
1488  * zero otherwise.
1489  * @ingroup bodies
1490  */
1491 ODE_API int dBodyGetGyroscopicMode(dBodyID b);
1492
1493
1494 /**
1495  * @brief Enable/disable the body's gyroscopic term.
1496  *
1497  * Disabling the gyroscopic term of a body usually improves
1498  * stability. It also helps turning spining objects, like cars'
1499  * wheels.
1500  *
1501  * @param enabled   nonzero (default) to enable gyroscopic term, 0
1502  * to disable.
1503  * @ingroup bodies
1504  */
1505 ODE_API void dBodySetGyroscopicMode(dBodyID b, int enabled);
1506
1507
1508
1509
1510 /**
1511  * @defgroup joints Joints
1512  *
1513  * In real life a joint is something like a hinge, that is used to connect two
1514  * objects.
1515  * In ODE a joint is very similar: It is a relationship that is enforced between
1516  * two bodies so that they can only have certain positions and orientations
1517  * relative to each other.
1518  * This relationship is called a constraint -- the words joint and
1519  * constraint are often used interchangeably.
1520  *
1521  * A joint has a set of parameters that can be set. These include:
1522  *
1523  *
1524  * \li  dParamLoStop Low stop angle or position. Setting this to
1525  *      -dInfinity (the default value) turns off the low stop.
1526  *      For rotational joints, this stop must be greater than -pi to be
1527  *      effective.
1528  * \li  dParamHiStop High stop angle or position. Setting this to
1529  *      dInfinity (the default value) turns off the high stop.
1530  *      For rotational joints, this stop must be less than pi to be
1531  *      effective.
1532  *      If the high stop is less than the low stop then both stops will
1533  *      be ineffective.
1534  * \li  dParamVel Desired motor velocity (this will be an angular or
1535  *      linear velocity).
1536  * \li  dParamFMax The maximum force or torque that the motor will use to
1537  *      achieve the desired velocity.
1538  *      This must always be greater than or equal to zero.
1539  *      Setting this to zero (the default value) turns off the motor.
1540  * \li  dParamFudgeFactor The current joint stop/motor implementation has
1541  *      a small problem:
1542  *      when the joint is at one stop and the motor is set to move it away
1543  *      from the stop, too much force may be applied for one time step,
1544  *      causing a ``jumping'' motion.
1545  *      This fudge factor is used to scale this excess force.
1546  *      It should have a value between zero and one (the default value).
1547  *      If the jumping motion is too visible in a joint, the value can be
1548  *      reduced.
1549  *      Making this value too small can prevent the motor from being able to
1550  *      move the joint away from a stop.
1551  * \li  dParamBounce The bouncyness of the stops.
1552  *      This is a restitution parameter in the range 0..1.
1553  *      0 means the stops are not bouncy at all, 1 means maximum bouncyness.
1554  * \li  dParamCFM The constraint force mixing (CFM) value used when not
1555  *      at a stop.
1556  * \li  dParamStopERP The error reduction parameter (ERP) used by the
1557  *      stops.
1558  * \li  dParamStopCFM The constraint force mixing (CFM) value used by the
1559  *      stops. Together with the ERP value this can be used to get spongy or
1560  *      soft stops.
1561  *      Note that this is intended for unpowered joints, it does not really
1562  *      work as expected when a powered joint reaches its limit.
1563  * \li  dParamSuspensionERP Suspension error reduction parameter (ERP).
1564  *      Currently this is only implemented on the hinge-2 joint.
1565  * \li  dParamSuspensionCFM Suspension constraint force mixing (CFM) value.
1566  *      Currently this is only implemented on the hinge-2 joint.
1567  *
1568  * If a particular parameter is not implemented by a given joint, setting it
1569  * will have no effect.
1570  * These parameter names can be optionally followed by a digit (2 or 3)
1571  * to indicate the second or third set of parameters, e.g. for the second axis
1572  * in a hinge-2 joint, or the third axis in an AMotor joint.
1573  */
1574
1575
1576 /**
1577  * @brief Create a new joint of the ball type.
1578  * @ingroup joints
1579  * @remarks
1580  * The joint is initially in "limbo" (i.e. it has no effect on the simulation)
1581  * because it does not connect to any bodies.
1582  * @param dJointGroupID set to 0 to allocate the joint normally.
1583  * If it is nonzero the joint is allocated in the given joint group.
1584  */
1585 ODE_API dJointID dJointCreateBall (dWorldID, dJointGroupID);
1586
1587 /**
1588  * @brief Create a new joint of the hinge type.
1589  * @ingroup joints
1590  * @param dJointGroupID set to 0 to allocate the joint normally.
1591  * If it is nonzero the joint is allocated in the given joint group.
1592  */
1593 ODE_API dJointID dJointCreateHinge (dWorldID, dJointGroupID);
1594
1595 /**
1596  * @brief Create a new joint of the slider type.
1597  * @ingroup joints
1598  * @param dJointGroupID set to 0 to allocate the joint normally.
1599  * If it is nonzero the joint is allocated in the given joint group.
1600  */
1601 ODE_API dJointID dJointCreateSlider (dWorldID, dJointGroupID);
1602
1603 /**
1604  * @brief Create a new joint of the contact type.
1605  * @ingroup joints
1606  * @param dJointGroupID set to 0 to allocate the joint normally.
1607  * If it is nonzero the joint is allocated in the given joint group.
1608  */
1609 ODE_API dJointID dJointCreateContact (dWorldID, dJointGroupID, const dContact *);
1610
1611 /**
1612  * @brief Create a new joint of the hinge2 type.
1613  * @ingroup joints
1614  * @param dJointGroupID set to 0 to allocate the joint normally.
1615  * If it is nonzero the joint is allocated in the given joint group.
1616  */
1617 ODE_API dJointID dJointCreateHinge2 (dWorldID, dJointGroupID);
1618
1619 /**
1620  * @brief Create a new joint of the universal type.
1621  * @ingroup joints
1622  * @param dJointGroupID set to 0 to allocate the joint normally.
1623  * If it is nonzero the joint is allocated in the given joint group.
1624  */
1625 ODE_API dJointID dJointCreateUniversal (dWorldID, dJointGroupID);
1626
1627 /**
1628  * @brief Create a new joint of the PR (Prismatic and Rotoide) type.
1629  * @ingroup joints
1630  * @param dJointGroupID set to 0 to allocate the joint normally.
1631  * If it is nonzero the joint is allocated in the given joint group.
1632  */
1633 ODE_API dJointID dJointCreatePR (dWorldID, dJointGroupID);
1634
1635 /**
1636  * @brief Create a new joint of the PU (Prismatic and Universal) type.
1637  * @ingroup joints
1638  * @param dJointGroupID set to 0 to allocate the joint normally.
1639  * If it is nonzero the joint is allocated in the given joint group.
1640  */
1641 ODE_API dJointID dJointCreatePU (dWorldID, dJointGroupID);
1642
1643 /**
1644  * @brief Create a new joint of the Piston type.
1645  * @ingroup joints
1646  * @param dJointGroupID set to 0 to allocate the joint normally.
1647  *                      If it is nonzero the joint is allocated in the given
1648  *                      joint group.
1649  */
1650 ODE_API dJointID dJointCreatePiston (dWorldID, dJointGroupID);
1651
1652 /**
1653  * @brief Create a new joint of the fixed type.
1654  * @ingroup joints
1655  * @param dJointGroupID set to 0 to allocate the joint normally.
1656  * If it is nonzero the joint is allocated in the given joint group.
1657  */
1658 ODE_API dJointID dJointCreateFixed (dWorldID, dJointGroupID);
1659
1660 ODE_API dJointID dJointCreateNull (dWorldID, dJointGroupID);
1661
1662 /**
1663  * @brief Create a new joint of the A-motor type.
1664  * @ingroup joints
1665  * @param dJointGroupID set to 0 to allocate the joint normally.
1666  * If it is nonzero the joint is allocated in the given joint group.
1667  */
1668 ODE_API dJointID dJointCreateAMotor (dWorldID, dJointGroupID);
1669
1670 /**
1671  * @brief Create a new joint of the L-motor type.
1672  * @ingroup joints
1673  * @param dJointGroupID set to 0 to allocate the joint normally.
1674  * If it is nonzero the joint is allocated in the given joint group.
1675  */
1676 ODE_API dJointID dJointCreateLMotor (dWorldID, dJointGroupID);
1677
1678 /**
1679  * @brief Create a new joint of the plane-2d type.
1680  * @ingroup joints
1681  * @param dJointGroupID set to 0 to allocate the joint normally.
1682  * If it is nonzero the joint is allocated in the given joint group.
1683  */
1684 ODE_API dJointID dJointCreatePlane2D (dWorldID, dJointGroupID);
1685
1686 /**
1687  * @brief Create a new joint of the double ball type.
1688  * @ingroup joints
1689  * @param dJointGroupID set to 0 to allocate the joint normally.
1690  * If it is nonzero the joint is allocated in the given joint group.
1691  */
1692 ODE_API dJointID dJointCreateDBall (dWorldID, dJointGroupID);
1693
1694 /**
1695  * @brief Create a new joint of the double hinge type.
1696  * @ingroup joints
1697  * @param dJointGroupID set to 0 to allocate the joint normally.
1698  * If it is nonzero the joint is allocated in the given joint group.
1699  */
1700 ODE_API dJointID dJointCreateDHinge (dWorldID, dJointGroupID);
1701
1702 /**
1703  * @brief Create a new joint of the Transmission type.
1704  * @ingroup joints
1705  * @param dJointGroupID set to 0 to allocate the joint normally.
1706  * If it is nonzero the joint is allocated in the given joint group.
1707  */
1708 ODE_API dJointID dJointCreateTransmission (dWorldID, dJointGroupID);
1709
1710
1711 /**
1712  * @brief Destroy a joint.
1713  * @ingroup joints
1714  *
1715  * disconnects it from its attached bodies and removing it from the world.
1716  * However, if the joint is a member of a group then this function has no
1717  * effect - to destroy that joint the group must be emptied or destroyed.
1718  */
1719 ODE_API void dJointDestroy (dJointID);
1720
1721
1722 /**
1723  * @brief Create a joint group
1724  * @ingroup joints
1725  * @param max_size deprecated. Set to 0.
1726  */
1727 ODE_API dJointGroupID dJointGroupCreate (int max_size);
1728
1729 /**
1730  * @brief Destroy a joint group.
1731  * @ingroup joints
1732  *
1733  * All joints in the joint group will be destroyed.
1734  */
1735 ODE_API void dJointGroupDestroy (dJointGroupID);
1736
1737 /**
1738  * @brief Empty a joint group.
1739  * @ingroup joints
1740  *
1741  * All joints in the joint group will be destroyed,
1742  * but the joint group itself will not be destroyed.
1743  */
1744 ODE_API void dJointGroupEmpty (dJointGroupID);
1745
1746 /**
1747  * @brief Return the number of bodies attached to the joint
1748  * @ingroup joints
1749  */
1750 ODE_API int dJointGetNumBodies(dJointID);
1751
1752 /**
1753  * @brief Attach the joint to some new bodies.
1754  * @ingroup joints
1755  *
1756  * If the joint is already attached, it will be detached from the old bodies
1757  * first.
1758  * To attach this joint to only one body, set body1 or body2 to zero - a zero
1759  * body refers to the static environment.
1760  * Setting both bodies to zero puts the joint into "limbo", i.e. it will
1761  * have no effect on the simulation.
1762  * @remarks
1763  * Some joints, like hinge-2 need to be attached to two bodies to work.
1764  */
1765 ODE_API void dJointAttach (dJointID, dBodyID body1, dBodyID body2);
1766
1767 /**
1768  * @brief Manually enable a joint.
1769  * @param dJointID identification of joint.
1770  * @ingroup joints
1771  */
1772 ODE_API void dJointEnable (dJointID);
1773
1774 /**
1775  * @brief Manually disable a joint.
1776  * @ingroup joints
1777  * @remarks
1778  * A disabled joint will not affect the simulation, but will maintain the anchors and
1779  * axes so it can be enabled later.
1780  */
1781 ODE_API void dJointDisable (dJointID);
1782
1783 /**
1784  * @brief Check wether a joint is enabled.
1785  * @ingroup joints
1786  * @return 1 if a joint is currently enabled or 0 if it is disabled.
1787  */
1788 ODE_API int dJointIsEnabled (dJointID);
1789
1790 /**
1791  * @brief Set the user-data pointer
1792  * @ingroup joints
1793  */
1794 ODE_API void dJointSetData (dJointID, void *data);
1795
1796 /**
1797  * @brief Get the user-data pointer
1798  * @ingroup joints
1799  */
1800 ODE_API void *dJointGetData (dJointID);
1801
1802 /**
1803  * @brief Get the type of the joint
1804  * @ingroup joints
1805  * @return the type, being one of these:
1806  * \li dJointTypeBall
1807  * \li dJointTypeHinge
1808  * \li dJointTypeSlider
1809  * \li dJointTypeContact
1810  * \li dJointTypeUniversal
1811  * \li dJointTypeHinge2
1812  * \li dJointTypeFixed
1813  * \li dJointTypeNull
1814  * \li dJointTypeAMotor
1815  * \li dJointTypeLMotor
1816  * \li dJointTypePlane2D
1817  * \li dJointTypePR
1818  * \li dJointTypePU
1819  * \li dJointTypePiston
1820  */
1821 ODE_API dJointType dJointGetType (dJointID);
1822
1823 /**
1824  * @brief Return the bodies that this joint connects.
1825  * @ingroup joints
1826  * @param index return the first (0) or second (1) body.
1827  * @remarks
1828  * If one of these returned body IDs is zero, the joint connects the other body
1829  * to the static environment.
1830  * If both body IDs are zero, the joint is in ``limbo'' and has no effect on
1831  * the simulation.
1832  */
1833 ODE_API dBodyID dJointGetBody (dJointID, int index);
1834
1835 /**
1836  * @brief Sets the datastructure that is to receive the feedback.
1837  *
1838  * The feedback can be used by the user, so that it is known how
1839  * much force an individual joint exerts.
1840  * @ingroup joints
1841  */
1842 ODE_API void dJointSetFeedback (dJointID, dJointFeedback *);
1843
1844 /**
1845  * @brief Gets the datastructure that is to receive the feedback.
1846  * @ingroup joints
1847  */
1848 ODE_API dJointFeedback *dJointGetFeedback (dJointID);
1849
1850 /**
1851  * @brief Set the joint anchor point.
1852  * @ingroup joints
1853  *
1854  * The joint will try to keep this point on each body
1855  * together. The input is specified in world coordinates.
1856  */
1857 ODE_API void dJointSetBallAnchor (dJointID, dReal x, dReal y, dReal z);
1858
1859 /**
1860  * @brief Set the joint anchor point.
1861  * @ingroup joints
1862  */
1863 ODE_API void dJointSetBallAnchor2 (dJointID, dReal x, dReal y, dReal z);
1864
1865 /**
1866  * @brief Param setting for Ball joints
1867  * @ingroup joints
1868  */
1869 ODE_API void dJointSetBallParam (dJointID, int parameter, dReal value);
1870
1871 /**
1872  * @brief Set hinge anchor parameter.
1873  * @ingroup joints
1874  */
1875 ODE_API void dJointSetHingeAnchor (dJointID, dReal x, dReal y, dReal z);
1876
1877 ODE_API void dJointSetHingeAnchorDelta (dJointID, dReal x, dReal y, dReal z, dReal ax, dReal ay, dReal az);
1878
1879 /**
1880  * @brief Set hinge axis.
1881  * @ingroup joints
1882  */
1883 ODE_API void dJointSetHingeAxis (dJointID, dReal x, dReal y, dReal z);
1884
1885 /**
1886  * @brief Set the Hinge axis as if the 2 bodies were already at angle appart.
1887  * @ingroup joints
1888  *
1889  * This function initialize the Axis and the relative orientation of each body
1890  * as if body1 was rotated around the axis by the angle value. \br
1891  * Ex:
1892  * <PRE>
1893  * dJointSetHingeAxis(jId, 1, 0, 0);
1894  * // If you request the position you will have: dJointGetHingeAngle(jId) == 0
1895  * dJointSetHingeAxisDelta(jId, 1, 0, 0, 0.23);
1896  * // If you request the position you will have: dJointGetHingeAngle(jId) == 0.23
1897  * </PRE>
1898
1899  * @param j The Hinge joint ID for which the axis will be set
1900  * @param x The X component of the axis in world frame
1901  * @param y The Y component of the axis in world frame
1902  * @param z The Z component of the axis in world frame
1903  * @param angle The angle for the offset of the relative orientation.
1904  *              As if body1 was rotated by angle when the Axis was set (see below).
1905  *              The rotation is around the new Hinge axis.
1906  *
1907  * @note Usually the function dJointSetHingeAxis set the current position of body1
1908  *       and body2 as the zero angle position. This function set the current position
1909  *       as the if the 2 bodies where \b angle appart.
1910  * @warning Calling dJointSetHingeAnchor or dJointSetHingeAxis will reset the "zero"
1911  *          angle position.
1912  */
1913 ODE_API void dJointSetHingeAxisOffset (dJointID j, dReal x, dReal y, dReal z, dReal angle);
1914
1915 /**
1916  * @brief set joint parameter
1917  * @ingroup joints
1918  */
1919 ODE_API void dJointSetHingeParam (dJointID, int parameter, dReal value);
1920
1921 /**
1922  * @brief Applies the torque about the hinge axis.
1923  *
1924  * That is, it applies a torque with specified magnitude in the direction
1925  * of the hinge axis, to body 1, and with the same magnitude but in opposite
1926  * direction to body 2. This function is just a wrapper for dBodyAddTorque()}
1927  * @ingroup joints
1928  */
1929 ODE_API void dJointAddHingeTorque(dJointID joint, dReal torque);
1930
1931 /**
1932  * @brief set the joint axis
1933  * @ingroup joints
1934  */
1935 ODE_API void dJointSetSliderAxis (dJointID, dReal x, dReal y, dReal z);
1936
1937 /**
1938  * @ingroup joints
1939  */
1940 ODE_API void dJointSetSliderAxisDelta (dJointID, dReal x, dReal y, dReal z, dReal ax, dReal ay, dReal az);
1941
1942 /**
1943  * @brief set joint parameter
1944  * @ingroup joints
1945  */
1946 ODE_API void dJointSetSliderParam (dJointID, int parameter, dReal value);
1947
1948 /**
1949  * @brief Applies the given force in the slider's direction.
1950  *
1951  * That is, it applies a force with specified magnitude, in the direction of
1952  * slider's axis, to body1, and with the same magnitude but opposite
1953  * direction to body2.  This function is just a wrapper for dBodyAddForce().
1954  * @ingroup joints
1955  */
1956 ODE_API void dJointAddSliderForce(dJointID joint, dReal force);
1957
1958 /**
1959  * @brief set anchor
1960  * @ingroup joints
1961  */
1962 ODE_API void dJointSetHinge2Anchor (dJointID, dReal x, dReal y, dReal z);
1963
1964 /**
1965  * @brief set both axes (optionally)
1966  *
1967  * This can change both axes at once avoiding transitions via invalid states
1968  * while changing axes one by one and having the first changed axis coincide
1969  * with the other axis existing direction.
1970  *
1971  * At least one of the axes must be not NULL. If NULL is passed, the corresponding
1972  * axis retains its existing value.
1973  *
1974  * @ingroup joints
1975  */
1976 ODE_API void dJointSetHinge2Axes (dJointID j, const dReal *axis1/*=[dSA__MAX],=NULL*/, const dReal *axis2/*=[dSA__MAX],=NULL*/);
1977
1978 /**
1979  * @brief set axis
1980  *
1981  * Deprecated. Use @fn dJointSetHinge2Axes instead.
1982  *
1983  * @ingroup joints
1984  * @see dJointSetHinge2Axes
1985  */
1986 ODE_API_DEPRECATED ODE_API void dJointSetHinge2Axis1 (dJointID j, dReal x, dReal y, dReal z);
1987
1988 /**
1989  * @brief set axis
1990  *
1991  * Deprecated. Use @fn dJointSetHinge2Axes instead.
1992  *
1993  * @ingroup joints
1994  * @see dJointSetHinge2Axes
1995  */
1996 ODE_API_DEPRECATED ODE_API void dJointSetHinge2Axis2 (dJointID j, dReal x, dReal y, dReal z);
1997
1998 /**
1999  * @brief set joint parameter
2000  * @ingroup joints
2001  */
2002 ODE_API void dJointSetHinge2Param (dJointID, int parameter, dReal value);
2003
2004 /**
2005  * @brief Applies torque1 about the hinge2's axis 1, torque2 about the
2006  * hinge2's axis 2.
2007  * @remarks  This function is just a wrapper for dBodyAddTorque().
2008  * @ingroup joints
2009  */
2010 ODE_API void dJointAddHinge2Torques(dJointID joint, dReal torque1, dReal torque2);
2011
2012 /**
2013  * @brief set anchor
2014  * @ingroup joints
2015  */
2016 ODE_API void dJointSetUniversalAnchor (dJointID, dReal x, dReal y, dReal z);
2017
2018 /**
2019  * @brief set axis
2020  * @ingroup joints
2021  */
2022 ODE_API void dJointSetUniversalAxis1 (dJointID, dReal x, dReal y, dReal z);
2023
2024 /**
2025  * @brief Set the Universal axis1 as if the 2 bodies were already at
2026  *        offset1 and offset2 appart with respect to axis1 and axis2.
2027  * @ingroup joints
2028  *
2029  * This function initialize the axis1 and the relative orientation of
2030  * each body as if body1 was rotated around the new axis1 by the offset1
2031  * value and as if body2 was rotated around the axis2 by offset2. \br
2032  * Ex:
2033 * <PRE>
2034  * dJointSetHuniversalAxis1(jId, 1, 0, 0);
2035  * // If you request the position you will have: dJointGetUniversalAngle1(jId) == 0
2036  * // If you request the position you will have: dJointGetUniversalAngle2(jId) == 0
2037  * dJointSetHuniversalAxis1Offset(jId, 1, 0, 0, 0.2, 0.17);
2038  * // If you request the position you will have: dJointGetUniversalAngle1(jId) == 0.2
2039  * // If you request the position you will have: dJointGetUniversalAngle2(jId) == 0.17
2040  * </PRE>
2041  *
2042  * @param j The Hinge joint ID for which the axis will be set
2043  * @param x The X component of the axis in world frame
2044  * @param y The Y component of the axis in world frame
2045  * @param z The Z component of the axis in world frame
2046  * @param angle The angle for the offset of the relative orientation.
2047  *              As if body1 was rotated by angle when the Axis was set (see below).
2048  *              The rotation is around the new Hinge axis.
2049  *
2050  * @note Usually the function dJointSetHingeAxis set the current position of body1
2051  *       and body2 as the zero angle position. This function set the current position
2052  *       as the if the 2 bodies where \b offsets appart.
2053  *
2054  * @note Any previous offsets are erased.
2055  *
2056  * @warning Calling dJointSetUniversalAnchor, dJointSetUnivesalAxis1,
2057  *          dJointSetUniversalAxis2, dJointSetUniversalAxis2Offset
2058  *          will reset the "zero" angle position.
2059  */
2060 ODE_API void dJointSetUniversalAxis1Offset (dJointID, dReal x, dReal y, dReal z,
2061                                             dReal offset1, dReal offset2);
2062
2063 /**
2064  * @brief set axis
2065  * @ingroup joints
2066  */
2067 ODE_API void dJointSetUniversalAxis2 (dJointID, dReal x, dReal y, dReal z);
2068
2069 /**
2070  * @brief Set the Universal axis2 as if the 2 bodies were already at
2071  *        offset1 and offset2 appart with respect to axis1 and axis2.
2072  * @ingroup joints
2073  *
2074  * This function initialize the axis2 and the relative orientation of
2075  * each body as if body1 was rotated around the axis1 by the offset1
2076  * value and as if body2 was rotated around the new axis2 by offset2. \br
2077  * Ex:
2078  * <PRE>
2079  * dJointSetHuniversalAxis2(jId, 0, 1, 0);
2080  * // If you request the position you will have: dJointGetUniversalAngle1(jId) == 0
2081  * // If you request the position you will have: dJointGetUniversalAngle2(jId) == 0
2082  * dJointSetHuniversalAxis2Offset(jId, 0, 1, 0, 0.2, 0.17);
2083  * // If you request the position you will have: dJointGetUniversalAngle1(jId) == 0.2
2084  * // If you request the position you will have: dJointGetUniversalAngle2(jId) == 0.17
2085  * </PRE>
2086
2087  * @param j The Hinge joint ID for which the axis will be set
2088  * @param x The X component of the axis in world frame
2089  * @param y The Y component of the axis in world frame
2090  * @param z The Z component of the axis in world frame
2091  * @param angle The angle for the offset of the relative orientation.
2092  *              As if body1 was rotated by angle when the Axis was set (see below).
2093  *              The rotation is around the new Hinge axis.
2094  *
2095  * @note Usually the function dJointSetHingeAxis set the current position of body1
2096  *       and body2 as the zero angle position. This function set the current position
2097  *       as the if the 2 bodies where \b offsets appart.
2098  *
2099  * @note Any previous offsets are erased.
2100  *
2101  * @warning Calling dJointSetUniversalAnchor, dJointSetUnivesalAxis1,
2102  *          dJointSetUniversalAxis2, dJointSetUniversalAxis2Offset
2103  *          will reset the "zero" angle position.
2104  */
2105
2106
2107 ODE_API void dJointSetUniversalAxis2Offset (dJointID, dReal x, dReal y, dReal z,
2108                                             dReal offset1, dReal offset2);
2109
2110 /**
2111  * @brief set joint parameter
2112  * @ingroup joints
2113  */
2114 ODE_API void dJointSetUniversalParam (dJointID, int parameter, dReal value);
2115
2116 /**
2117  * @brief Applies torque1 about the universal's axis 1, torque2 about the
2118  * universal's axis 2.
2119  * @remarks This function is just a wrapper for dBodyAddTorque().
2120  * @ingroup joints
2121  */
2122 ODE_API void dJointAddUniversalTorques(dJointID joint, dReal torque1, dReal torque2);
2123
2124
2125 /**
2126  * @brief set anchor
2127  * @ingroup joints
2128  */
2129 ODE_API void dJointSetPRAnchor (dJointID, dReal x, dReal y, dReal z);
2130
2131 /**
2132  * @brief set the axis for the prismatic articulation
2133  * @ingroup joints
2134  */
2135 ODE_API void dJointSetPRAxis1 (dJointID, dReal x, dReal y, dReal z);
2136
2137 /**
2138  * @brief set the axis for the rotoide articulation
2139  * @ingroup joints
2140  */
2141 ODE_API void dJointSetPRAxis2 (dJointID, dReal x, dReal y, dReal z);
2142
2143 /**
2144  * @brief set joint parameter
2145  * @ingroup joints
2146  *
2147  * @note parameterX where X equal 2 refer to parameter for the rotoide articulation
2148  */
2149 ODE_API void dJointSetPRParam (dJointID, int parameter, dReal value);
2150
2151 /**
2152  * @brief Applies the torque about the rotoide axis of the PR joint
2153  *
2154  * That is, it applies a torque with specified magnitude in the direction
2155  * of the rotoide axis, to body 1, and with the same magnitude but in opposite
2156  * direction to body 2. This function is just a wrapper for dBodyAddTorque()}
2157  * @ingroup joints
2158  */
2159 ODE_API void dJointAddPRTorque (dJointID j, dReal torque);
2160
2161
2162 /**
2163 * @brief set anchor
2164 * @ingroup joints
2165 */
2166 ODE_API void dJointSetPUAnchor (dJointID, dReal x, dReal y, dReal z);
2167
2168 /**
2169  * @brief set anchor
2170  * @ingroup joints
2171  */
2172 ODE_API_DEPRECATED ODE_API void dJointSetPUAnchorDelta (dJointID, dReal x, dReal y, dReal z,
2173                                                         dReal dx, dReal dy, dReal dz);
2174
2175 /**
2176  * @brief Set the PU anchor as if the 2 bodies were already at [dx, dy, dz] appart.
2177  * @ingroup joints
2178  *
2179  * This function initialize the anchor and the relative position of each body
2180  * as if the position between body1 and body2 was already the projection of [dx, dy, dz]
2181  * along the Piston axis. (i.e as if the body1 was at its current position - [dx,dy,dy] when the
2182  * axis is set).
2183  * Ex:
2184  * <PRE>
2185  * dReal offset = 3;
2186  * dVector3 axis;
2187  * dJointGetPUAxis(jId, axis);
2188  * dJointSetPUAnchor(jId, 0, 0, 0);
2189  * // If you request the position you will have: dJointGetPUPosition(jId) == 0
2190  * dJointSetPUAnchorOffset(jId, 0, 0, 0, axis[X]*offset, axis[Y]*offset, axis[Z]*offset);
2191  * // If you request the position you will have: dJointGetPUPosition(jId) == offset
2192  * </PRE>
2193  * @param j The PU joint for which the anchor point will be set
2194  * @param x The X position of the anchor point in world frame
2195  * @param y The Y position of the anchor point in world frame
2196  * @param z The Z position of the anchor point in world frame
2197  * @param dx A delta to be substracted to the X position as if the anchor was set
2198  *           when body1 was at current_position[X] - dx
2199  * @param dx A delta to be substracted to the Y position as if the anchor was set
2200  *           when body1 was at current_position[Y] - dy
2201  * @param dx A delta to be substracted to the Z position as if the anchor was set
2202  *           when body1 was at current_position[Z] - dz
2203  */
2204 ODE_API void dJointSetPUAnchorOffset (dJointID, dReal x, dReal y, dReal z,
2205                                      dReal dx, dReal dy, dReal dz);
2206
2207 /**
2208  * @brief set the axis for the first axis or the universal articulation
2209  * @ingroup joints
2210  */
2211 ODE_API void dJointSetPUAxis1 (dJointID, dReal x, dReal y, dReal z);
2212
2213 /**
2214  * @brief set the axis for the second axis or the universal articulation
2215  * @ingroup joints
2216  */
2217 ODE_API void dJointSetPUAxis2 (dJointID, dReal x, dReal y, dReal z);
2218
2219 /**
2220  * @brief set the axis for the prismatic articulation
2221  * @ingroup joints
2222  */
2223 ODE_API void dJointSetPUAxis3 (dJointID, dReal x, dReal y, dReal z);
2224
2225 /**
2226  * @brief set the axis for the prismatic articulation
2227  * @ingroup joints
2228  * @note This function was added for convenience it is the same as
2229  *       dJointSetPUAxis3
2230  */
2231 ODE_API void dJointSetPUAxisP (dJointID id, dReal x, dReal y, dReal z);
2232
2233
2234
2235 /**
2236  * @brief set joint parameter
2237  * @ingroup joints
2238  *
2239  * @note parameterX where X equal 2 refer to parameter for second axis of the
2240  *       universal articulation
2241  * @note parameterX where X equal 3 refer to parameter for prismatic
2242  *       articulation
2243  */
2244 ODE_API void dJointSetPUParam (dJointID, int parameter, dReal value);
2245
2246 /**
2247  * @brief Applies the torque about the rotoide axis of the PU joint
2248  *
2249  * That is, it applies a torque with specified magnitude in the direction
2250  * of the rotoide axis, to body 1, and with the same magnitude but in opposite
2251  * direction to body 2. This function is just a wrapper for dBodyAddTorque()}
2252  * @ingroup joints
2253  */
2254 ODE_API void dJointAddPUTorque (dJointID j, dReal torque);
2255
2256
2257
2258
2259 /**
2260  * @brief set the joint anchor
2261  * @ingroup joints
2262  */
2263 ODE_API void dJointSetPistonAnchor (dJointID, dReal x, dReal y, dReal z);
2264
2265 /**
2266  * @brief Set the Piston anchor as if the 2 bodies were already at [dx,dy, dz] appart.
2267  * @ingroup joints
2268  *
2269  * This function initialize the anchor and the relative position of each body
2270  * as if the position between body1 and body2 was already the projection of [dx, dy, dz]
2271  * along the Piston axis. (i.e as if the body1 was at its current position - [dx,dy,dy] when the
2272  * axis is set).
2273  * Ex:
2274  * <PRE>
2275  * dReal offset = 3;
2276  * dVector3 axis;
2277  * dJointGetPistonAxis(jId, axis);
2278  * dJointSetPistonAnchor(jId, 0, 0, 0);
2279  * // If you request the position you will have: dJointGetPistonPosition(jId) == 0
2280  * dJointSetPistonAnchorOffset(jId, 0, 0, 0, axis[X]*offset, axis[Y]*offset, axis[Z]*offset);
2281  * // If you request the position you will have: dJointGetPistonPosition(jId) == offset
2282  * </PRE>
2283  * @param j The Piston joint for which the anchor point will be set
2284  * @param x The X position of the anchor point in world frame
2285  * @param y The Y position of the anchor point in world frame
2286  * @param z The Z position of the anchor point in world frame
2287  * @param dx A delta to be substracted to the X position as if the anchor was set
2288  *           when body1 was at current_position[X] - dx
2289  * @param dx A delta to be substracted to the Y position as if the anchor was set
2290  *           when body1 was at current_position[Y] - dy
2291  * @param dx A delta to be substracted to the Z position as if the anchor was set
2292  *           when body1 was at current_position[Z] - dz
2293  */
2294 ODE_API void dJointSetPistonAnchorOffset(dJointID j, dReal x, dReal y, dReal z,
2295                                          dReal dx, dReal dy, dReal dz);
2296
2297   /**
2298    * @brief set the joint axis
2299  * @ingroup joints
2300  */
2301 ODE_API void dJointSetPistonAxis (dJointID, dReal x, dReal y, dReal z);
2302
2303 /**
2304  * This function set prismatic axis of the joint and also set the position
2305  * of the joint.
2306  *
2307  * @ingroup joints
2308  * @param j The joint affected by this function
2309  * @param x The x component of the axis
2310  * @param y The y component of the axis
2311  * @param z The z component of the axis
2312  * @param dx The Initial position of the prismatic join in the x direction
2313  * @param dy The Initial position of the prismatic join in the y direction
2314  * @param dz The Initial position of the prismatic join in the z direction
2315  */
2316 ODE_API_DEPRECATED ODE_API void dJointSetPistonAxisDelta (dJointID j, dReal x, dReal y, dReal z, dReal ax, dReal ay, dReal az);
2317
2318 /**
2319  * @brief set joint parameter
2320  * @ingroup joints
2321  */
2322 ODE_API void dJointSetPistonParam (dJointID, int parameter, dReal value);
2323
2324 /**
2325  * @brief Applies the given force in the slider's direction.
2326  *
2327  * That is, it applies a force with specified magnitude, in the direction of
2328  * prismatic's axis, to body1, and with the same magnitude but opposite
2329  * direction to body2.  This function is just a wrapper for dBodyAddForce().
2330  * @ingroup joints
2331  */
2332 ODE_API void dJointAddPistonForce (dJointID joint, dReal force);
2333
2334
2335 /**
2336  * @brief Call this on the fixed joint after it has been attached to
2337  * remember the current desired relative offset and desired relative
2338  * rotation between the bodies.
2339  * @ingroup joints
2340  */
2341 ODE_API void dJointSetFixed (dJointID);
2342
2343 /*
2344  * @brief Sets joint parameter
2345  *
2346  * @ingroup joints
2347  */
2348 ODE_API void dJointSetFixedParam (dJointID, int parameter, dReal value);
2349
2350 /**
2351  * @brief set the nr of axes
2352  * @param num 0..3
2353  * @ingroup joints
2354  */
2355 ODE_API void dJointSetAMotorNumAxes (dJointID, int num);
2356
2357 /**
2358  * @brief set axis
2359  * @ingroup joints
2360  */
2361 ODE_API void dJointSetAMotorAxis (dJointID, int anum, int rel,
2362                           dReal x, dReal y, dReal z);
2363
2364 /**
2365  * @brief Tell the AMotor what the current angle is along axis anum.
2366  *
2367  * This function should only be called in dAMotorUser mode, because in this
2368  * mode the AMotor has no other way of knowing the joint angles.
2369  * The angle information is needed if stops have been set along the axis,
2370  * but it is not needed for axis motors.
2371  * @ingroup joints
2372  */
2373 ODE_API void dJointSetAMotorAngle (dJointID, int anum, dReal angle);
2374
2375 /**
2376  * @brief set joint parameter
2377  * @ingroup joints
2378  */
2379 ODE_API void dJointSetAMotorParam (dJointID, int parameter, dReal value);
2380
2381 /**
2382  * @brief set mode
2383  * @ingroup joints
2384  */
2385 ODE_API void dJointSetAMotorMode (dJointID, int mode);
2386
2387 /**
2388  * @brief Applies torque0 about the AMotor's axis 0, torque1 about the
2389  * AMotor's axis 1, and torque2 about the AMotor's axis 2.
2390  * @remarks
2391  * If the motor has fewer than three axes, the higher torques are ignored.
2392  * This function is just a wrapper for dBodyAddTorque().
2393  * @ingroup joints
2394  */
2395 ODE_API void dJointAddAMotorTorques (dJointID, dReal torque1, dReal torque2, dReal torque3);
2396
2397 /**
2398  * @brief Set the number of axes that will be controlled by the LMotor.
2399  * @param num can range from 0 (which effectively deactivates the joint) to 3.
2400  * @ingroup joints
2401  */
2402 ODE_API void dJointSetLMotorNumAxes (dJointID, int num);
2403
2404 /**
2405  * @brief Set the AMotor axes.
2406  * @param anum selects the axis to change (0,1 or 2).
2407  * @param rel Each axis can have one of three ``relative orientation'' modes
2408  * \li 0: The axis is anchored to the global frame.
2409  * \li 1: The axis is anchored to the first body.
2410  * \li 2: The axis is anchored to the second body.
2411  * @remarks The axis vector is always specified in global coordinates
2412  * regardless of the setting of rel.
2413  * @ingroup joints
2414  */
2415 ODE_API void dJointSetLMotorAxis (dJointID, int anum, int rel, dReal x, dReal y, dReal z);
2416
2417 /**
2418  * @brief set joint parameter
2419  * @ingroup joints
2420  */
2421 ODE_API void dJointSetLMotorParam (dJointID, int parameter, dReal value);
2422
2423 /**
2424  * @ingroup joints
2425  */
2426 ODE_API void dJointSetPlane2DXParam (dJointID, int parameter, dReal value);
2427
2428 /**
2429  * @ingroup joints
2430  */
2431
2432 ODE_API void dJointSetPlane2DYParam (dJointID, int parameter, dReal value);
2433
2434 /**
2435  * @ingroup joints
2436  */
2437 ODE_API void dJointSetPlane2DAngleParam (dJointID, int parameter, dReal value);
2438
2439 /**
2440  * @brief Get the joint anchor point, in world coordinates.
2441  *
2442  * This returns the point on body 1. If the joint is perfectly satisfied,
2443  * this will be the same as the point on body 2.
2444  */
2445 ODE_API void dJointGetBallAnchor (dJointID, dVector3 result);
2446
2447 /**
2448  * @brief Get the joint anchor point, in world coordinates.
2449  *
2450  * This returns the point on body 2. You can think of a ball and socket
2451  * joint as trying to keep the result of dJointGetBallAnchor() and
2452  * dJointGetBallAnchor2() the same.  If the joint is perfectly satisfied,
2453  * this function will return the same value as dJointGetBallAnchor() to
2454  * within roundoff errors. dJointGetBallAnchor2() can be used, along with
2455  * dJointGetBallAnchor(), to see how far the joint has come apart.
2456  */
2457 ODE_API void dJointGetBallAnchor2 (dJointID, dVector3 result);
2458
2459 /**
2460  * @brief get joint parameter
2461  * @ingroup joints
2462  */
2463 ODE_API dReal dJointGetBallParam (dJointID, int parameter);
2464
2465 /**
2466  * @brief Get the hinge anchor point, in world coordinates.
2467  *
2468  * This returns the point on body 1. If the joint is perfectly satisfied,
2469  * this will be the same as the point on body 2.
2470  * @ingroup joints
2471  */
2472 ODE_API void dJointGetHingeAnchor (dJointID, dVector3 result);
2473
2474 /**
2475  * @brief Get the joint anchor point, in world coordinates.
2476  * @return The point on body 2. If the joint is perfectly satisfied,
2477  * this will return the same value as dJointGetHingeAnchor().
2478  * If not, this value will be slightly different.
2479  * This can be used, for example, to see how far the joint has come apart.
2480  * @ingroup joints
2481  */
2482 ODE_API void dJointGetHingeAnchor2 (dJointID, dVector3 result);
2483
2484 /**
2485  * @brief get axis
2486  * @ingroup joints
2487  */
2488 ODE_API void dJointGetHingeAxis (dJointID, dVector3 result);
2489
2490 /**
2491  * @brief get joint parameter
2492  * @ingroup joints
2493  */
2494 ODE_API dReal dJointGetHingeParam (dJointID, int parameter);
2495
2496 /**
2497  * @brief Get the hinge angle.
2498  *
2499  * The angle is measured between the two bodies, or between the body and
2500  * the static environment.
2501  * The angle will be between -pi..pi.
2502  * Give the relative rotation with respect to the Hinge axis of Body 1 with
2503  * respect to Body 2.
2504  * When the hinge anchor or axis is set, the current position of the attached
2505  * bodies is examined and that position will be the zero angle.
2506  * @ingroup joints
2507  */
2508 ODE_API dReal dJointGetHingeAngle (dJointID);
2509
2510 /**
2511  * @brief Get the hinge angle time derivative.
2512  * @ingroup joints
2513  */
2514 ODE_API dReal dJointGetHingeAngleRate (dJointID);
2515
2516 /**
2517  * @brief Get the slider linear position (i.e. the slider's extension)
2518  *
2519  * When the axis is set, the current position of the attached bodies is
2520  * examined and that position will be the zero position.
2521
2522  * The position is the distance, with respect to the zero position,
2523  * along the slider axis of body 1 with respect to
2524  * body 2. (A NULL body is replaced by the world).
2525  * @ingroup joints
2526  */
2527 ODE_API dReal dJointGetSliderPosition (dJointID);
2528
2529 /**
2530  * @brief Get the slider linear position's time derivative.
2531  * @ingroup joints
2532  */
2533 ODE_API dReal dJointGetSliderPositionRate (dJointID);
2534
2535 /**
2536  * @brief Get the slider axis
2537  * @ingroup joints
2538  */
2539 ODE_API void dJointGetSliderAxis (dJointID, dVector3 result);
2540
2541 /**
2542  * @brief get joint parameter
2543  * @ingroup joints
2544  */
2545 ODE_API dReal dJointGetSliderParam (dJointID, int parameter);
2546
2547 /**
2548  * @brief Get the joint anchor point, in world coordinates.
2549  * @return the point on body 1.  If the joint is perfectly satisfied,
2550  * this will be the same as the point on body 2.
2551  * @ingroup joints
2552  */
2553 ODE_API void dJointGetHinge2Anchor (dJointID, dVector3 result);
2554
2555 /**
2556  * @brief Get the joint anchor point, in world coordinates.
2557  * This returns the point on body 2. If the joint is perfectly satisfied,
2558  * this will return the same value as dJointGetHinge2Anchor.
2559  * If not, this value will be slightly different.
2560  * This can be used, for example, to see how far the joint has come apart.
2561  * @ingroup joints
2562  */
2563 ODE_API void dJointGetHinge2Anchor2 (dJointID, dVector3 result);
2564
2565 /**
2566  * @brief Get joint axis
2567  * @ingroup joints
2568  */
2569 ODE_API void dJointGetHinge2Axis1 (dJointID, dVector3 result);
2570
2571 /**
2572  * @brief Get joint axis
2573  * @ingroup joints
2574  */
2575 ODE_API void dJointGetHinge2Axis2 (dJointID, dVector3 result);
2576
2577 /**
2578  * @brief get joint parameter
2579  * @ingroup joints
2580  */
2581 ODE_API dReal dJointGetHinge2Param (dJointID, int parameter);
2582
2583 /**
2584  * @brief Get angle
2585  * @ingroup joints
2586  */
2587 ODE_API dReal dJointGetHinge2Angle1 (dJointID);
2588
2589 /**
2590  * @brief Get angle
2591  * @ingroup joints
2592  */
2593 ODE_API dReal dJointGetHinge2Angle2 (dJointID);
2594
2595 /**
2596  * @brief Get time derivative of angle
2597  * @ingroup joints
2598  */
2599 ODE_API dReal dJointGetHinge2Angle1Rate (dJointID);
2600
2601 /**
2602  * @brief Get time derivative of angle
2603  * @ingroup joints
2604  */
2605 ODE_API dReal dJointGetHinge2Angle2Rate (dJointID);
2606
2607 /**
2608  * @brief Get the joint anchor point, in world coordinates.
2609  * @return the point on body 1. If the joint is perfectly satisfied,
2610  * this will be the same as the point on body 2.
2611  * @ingroup joints
2612  */
2613 ODE_API void dJointGetUniversalAnchor (dJointID, dVector3 result);
2614
2615 /**
2616  * @brief Get the joint anchor point, in world coordinates.
2617  * @return This returns the point on body 2.
2618  * @remarks
2619  * You can think of the ball and socket part of a universal joint as
2620  * trying to keep the result of dJointGetBallAnchor() and
2621  * dJointGetBallAnchor2() the same. If the joint is
2622  * perfectly satisfied, this function will return the same value
2623  * as dJointGetUniversalAnchor() to within roundoff errors.
2624  * dJointGetUniversalAnchor2() can be used, along with
2625  * dJointGetUniversalAnchor(), to see how far the joint has come apart.
2626  * @ingroup joints
2627  */
2628 ODE_API void dJointGetUniversalAnchor2 (dJointID, dVector3 result);
2629
2630 /**
2631  * @brief Get axis
2632  * @ingroup joints
2633  */
2634 ODE_API void dJointGetUniversalAxis1 (dJointID, dVector3 result);
2635
2636 /**
2637  * @brief Get axis
2638  * @ingroup joints
2639  */
2640 ODE_API void dJointGetUniversalAxis2 (dJointID, dVector3 result);
2641
2642
2643 /**
2644  * @brief get joint parameter
2645  * @ingroup joints
2646  */
2647 ODE_API dReal dJointGetUniversalParam (dJointID, int parameter);
2648
2649 /**
2650  * @brief Get both angles at the same time.
2651  * @ingroup joints
2652  *
2653  * @param joint   The universal joint for which we want to calculate the angles
2654  * @param angle1  The angle between the body1 and the axis 1
2655  * @param angle2  The angle between the body2 and the axis 2
2656  *
2657  * @note This function combine getUniversalAngle1 and getUniversalAngle2 together
2658  *       and try to avoid redundant calculation
2659  */
2660 ODE_API void dJointGetUniversalAngles (dJointID, dReal *angle1, dReal *angle2);
2661
2662 /**
2663  * @brief Get angle
2664  * @ingroup joints
2665  */
2666 ODE_API dReal dJointGetUniversalAngle1 (dJointID);
2667
2668 /**
2669  * @brief Get angle
2670  * @ingroup joints
2671  */
2672 ODE_API dReal dJointGetUniversalAngle2 (dJointID);
2673
2674 /**
2675  * @brief Get time derivative of angle
2676  * @ingroup joints
2677  */
2678 ODE_API dReal dJointGetUniversalAngle1Rate (dJointID);
2679
2680 /**
2681  * @brief Get time derivative of angle
2682  * @ingroup joints
2683  */
2684 ODE_API dReal dJointGetUniversalAngle2Rate (dJointID);
2685
2686
2687
2688 /**
2689  * @brief Get the joint anchor point, in world coordinates.
2690  * @return the point on body 1. If the joint is perfectly satisfied,
2691  * this will be the same as the point on body 2.
2692  * @ingroup joints
2693  */
2694 ODE_API void dJointGetPRAnchor (dJointID, dVector3 result);
2695
2696 /**
2697  * @brief Get the PR linear position (i.e. the prismatic's extension)
2698  *
2699  * When the axis is set, the current position of the attached bodies is
2700  * examined and that position will be the zero position.
2701  *
2702  * The position is the "oriented" length between the
2703  * position = (Prismatic axis) dot_product [(body1 + offset) - (body2 + anchor2)]
2704  *
2705  * @ingroup joints
2706  */
2707 ODE_API dReal dJointGetPRPosition (dJointID);
2708
2709 /**
2710  * @brief Get the PR linear position's time derivative
2711  *
2712  * @ingroup joints
2713  */
2714 ODE_API dReal dJointGetPRPositionRate (dJointID);
2715
2716
2717 /**
2718  * @brief Get the PR angular position (i.e. the  twist between the 2 bodies)
2719  *
2720  * When the axis is set, the current position of the attached bodies is
2721  * examined and that position will be the zero position.
2722  * @ingroup joints
2723  */
2724 ODE_API dReal dJointGetPRAngle (dJointID);
2725
2726 /**
2727  * @brief Get the PR angular position's time derivative
2728  *
2729  * @ingroup joints
2730  */
2731 ODE_API dReal dJointGetPRAngleRate (dJointID);
2732
2733
2734 /**
2735  * @brief Get the prismatic axis
2736  * @ingroup joints
2737  */
2738 ODE_API void dJointGetPRAxis1 (dJointID, dVector3 result);
2739
2740 /**
2741  * @brief Get the Rotoide axis
2742  * @ingroup joints
2743  */
2744 ODE_API void dJointGetPRAxis2 (dJointID, dVector3 result);
2745
2746 /**
2747  * @brief get joint parameter
2748  * @ingroup joints
2749  */
2750 ODE_API dReal dJointGetPRParam (dJointID, int parameter);
2751
2752
2753
2754 /**
2755  * @brief Get the joint anchor point, in world coordinates.
2756  * @return the point on body 1. If the joint is perfectly satisfied,
2757  * this will be the same as the point on body 2.
2758  * @ingroup joints
2759  */
2760 ODE_API void dJointGetPUAnchor (dJointID, dVector3 result);
2761
2762 /**
2763  * @brief Get the PU linear position (i.e. the prismatic's extension)
2764  *
2765  * When the axis is set, the current position of the attached bodies is
2766  * examined and that position will be the zero position.
2767  *
2768  * The position is the "oriented" length between the
2769  * position = (Prismatic axis) dot_product [(body1 + offset) - (body2 + anchor2)]
2770  *
2771  * @ingroup joints
2772  */
2773 ODE_API dReal dJointGetPUPosition (dJointID);
2774
2775 /**
2776  * @brief Get the PR linear position's time derivative
2777  *
2778  * @ingroup joints
2779  */
2780 ODE_API dReal dJointGetPUPositionRate (dJointID);
2781
2782 /**
2783  * @brief Get the first axis of the universal component of the joint
2784  * @ingroup joints
2785  */
2786 ODE_API void dJointGetPUAxis1 (dJointID, dVector3 result);
2787
2788 /**
2789  * @brief Get the second axis of the Universal component of the joint
2790  * @ingroup joints
2791  */
2792 ODE_API void dJointGetPUAxis2 (dJointID, dVector3 result);
2793
2794 /**
2795  * @brief Get the prismatic axis
2796  * @ingroup joints
2797  */
2798 ODE_API void dJointGetPUAxis3 (dJointID, dVector3 result);
2799
2800 /**
2801  * @brief Get the prismatic axis
2802  * @ingroup joints
2803  *
2804  * @note This function was added for convenience it is the same as
2805  *       dJointGetPUAxis3
2806  */
2807 ODE_API void dJointGetPUAxisP (dJointID id, dVector3 result);
2808
2809
2810
2811
2812 /**
2813  * @brief Get both angles at the same time.
2814  * @ingroup joints
2815  *
2816  * @param joint   The Prismatic universal joint for which we want to calculate the angles
2817  * @param angle1  The angle between the body1 and the axis 1
2818  * @param angle2  The angle between the body2 and the axis 2
2819  *
2820  * @note This function combine dJointGetPUAngle1 and dJointGetPUAngle2 together
2821  *       and try to avoid redundant calculation
2822  */
2823 ODE_API void dJointGetPUAngles (dJointID, dReal *angle1, dReal *angle2);
2824
2825 /**
2826  * @brief Get angle
2827  * @ingroup joints
2828  */
2829 ODE_API dReal dJointGetPUAngle1 (dJointID);
2830
2831 /**
2832  * @brief * @brief Get time derivative of angle1
2833  *
2834  * @ingroup joints
2835  */
2836 ODE_API dReal dJointGetPUAngle1Rate (dJointID);
2837
2838
2839 /**
2840  * @brief Get angle
2841  * @ingroup joints
2842  */
2843 ODE_API dReal dJointGetPUAngle2 (dJointID);
2844
2845 /**
2846  * @brief * @brief Get time derivative of angle2
2847  *
2848  * @ingroup joints
2849  */
2850 ODE_API dReal dJointGetPUAngle2Rate (dJointID);
2851
2852   /**
2853    * @brief get joint parameter
2854    * @ingroup joints
2855    */
2856 ODE_API dReal dJointGetPUParam (dJointID, int parameter);
2857
2858
2859
2860
2861
2862 /**
2863  * @brief Get the Piston linear position (i.e. the piston's extension)
2864  *
2865  * When the axis is set, the current position of the attached bodies is
2866  * examined and that position will be the zero position.
2867  * @ingroup joints
2868  */
2869 ODE_API dReal dJointGetPistonPosition (dJointID);
2870
2871 /**
2872  * @brief Get the piston linear position's time derivative.
2873  * @ingroup joints
2874  */
2875 ODE_API dReal dJointGetPistonPositionRate (dJointID);
2876
2877 /**
2878  * @brief Get the Piston angular position (i.e. the  twist between the 2 bodies)
2879  *
2880  * When the axis is set, the current position of the attached bodies is
2881  * examined and that position will be the zero position.
2882  * @ingroup joints
2883  */
2884 ODE_API dReal dJointGetPistonAngle (dJointID);
2885
2886 /**
2887  * @brief Get the piston angular position's time derivative.
2888  * @ingroup joints
2889  */
2890 ODE_API dReal dJointGetPistonAngleRate (dJointID);
2891
2892
2893 /**
2894  * @brief Get the joint anchor
2895  *
2896  * This returns the point on body 1. If the joint is perfectly satisfied,
2897  * this will be the same as the point on body 2 in direction perpendicular
2898  * to the prismatic axis.
2899  *
2900  * @ingroup joints
2901  */
2902 ODE_API void dJointGetPistonAnchor (dJointID, dVector3 result);
2903
2904 /**
2905  * @brief Get the joint anchor w.r.t. body 2
2906  *
2907  * This returns the point on body 2. You can think of a Piston
2908  * joint as trying to keep the result of dJointGetPistonAnchor() and
2909  * dJointGetPistonAnchor2() the same in the direction perpendicular to the
2910  * pirsmatic axis. If the joint is perfectly satisfied,
2911  * this function will return the same value as dJointGetPistonAnchor() to
2912  * within roundoff errors. dJointGetPistonAnchor2() can be used, along with
2913  * dJointGetPistonAnchor(), to see how far the joint has come apart.
2914  *
2915  * @ingroup joints
2916  */
2917 ODE_API void dJointGetPistonAnchor2 (dJointID, dVector3 result);
2918
2919 /**
2920  * @brief Get the prismatic axis (This is also the rotoide axis.
2921  * @ingroup joints
2922  */
2923 ODE_API void dJointGetPistonAxis (dJointID, dVector3 result);
2924
2925 /**
2926  * @brief get joint parameter
2927  * @ingroup joints
2928  */
2929 ODE_API dReal dJointGetPistonParam (dJointID, int parameter);
2930
2931
2932 /**
2933  * @brief Get the number of angular axes that will be controlled by the
2934  * AMotor.
2935  * @param num can range from 0 (which effectively deactivates the
2936  * joint) to 3.
2937  * This is automatically set to 3 in dAMotorEuler mode.
2938  * @ingroup joints
2939  */
2940 ODE_API int dJointGetAMotorNumAxes (dJointID);
2941
2942 /**
2943  * @brief Get the AMotor axes.
2944  * @param anum selects the axis to change (0,1 or 2).
2945  * @param rel Each axis can have one of three ``relative orientation'' modes.
2946  * \li 0: The axis is anchored to the global frame.
2947  * \li 1: The axis is anchored to the first body.
2948  * \li 2: The axis is anchored to the second body.
2949  * @ingroup joints
2950  */
2951 ODE_API void dJointGetAMotorAxis (dJointID, int anum, dVector3 result);
2952
2953 /**
2954  * @brief Get axis
2955  * @remarks
2956  * The axis vector is always specified in global coordinates regardless
2957  * of the setting of rel.
2958  * There are two GetAMotorAxis functions, one to return the axis and one to
2959  * return the relative mode.
2960  *
2961  * For dAMotorEuler mode:
2962  * \li  Only axes 0 and 2 need to be set. Axis 1 will be determined
2963         automatically at each time step.
2964  * \li  Axes 0 and 2 must be perpendicular to each other.
2965  * \li  Axis 0 must be anchored to the first body, axis 2 must be anchored
2966         to the second body.
2967  * @ingroup joints
2968  */
2969 ODE_API int dJointGetAMotorAxisRel (dJointID, int anum);
2970
2971 /**
2972  * @brief Get the current angle for axis.
2973  * @remarks
2974  * In dAMotorUser mode this is simply the value that was set with
2975  * dJointSetAMotorAngle().
2976  * In dAMotorEuler mode this is the corresponding euler angle.
2977  * @ingroup joints
2978  */
2979 ODE_API dReal dJointGetAMotorAngle (dJointID, int anum);
2980
2981 /**
2982  * @brief Get the current angle rate for axis anum.
2983  * @remarks
2984  * In dAMotorUser mode this is always zero, as not enough information is
2985  * available.
2986  * In dAMotorEuler mode this is the corresponding euler angle rate.
2987  * @ingroup joints
2988  */
2989 ODE_API dReal dJointGetAMotorAngleRate (dJointID, int anum);
2990
2991 /**
2992  * @brief get joint parameter
2993  * @ingroup joints
2994  */
2995 ODE_API dReal dJointGetAMotorParam (dJointID, int parameter);
2996
2997 /**
2998  * @brief Get the angular motor mode.
2999  * @param mode must be one of the following constants:
3000  * \li dAMotorUser The AMotor axes and joint angle settings are entirely
3001  * controlled by the user.  This is the default mode.
3002  * \li dAMotorEuler Euler angles are automatically computed.
3003  * The axis a1 is also automatically computed.
3004  * The AMotor axes must be set correctly when in this mode,
3005  * as described below.
3006  * When this mode is initially set the current relative orientations
3007  * of the bodies will correspond to all euler angles at zero.
3008  * @ingroup joints
3009  */
3010 ODE_API int dJointGetAMotorMode (dJointID);
3011
3012 /**
3013  * @brief Get nr of axes.
3014  * @ingroup joints
3015  */
3016 ODE_API int dJointGetLMotorNumAxes (dJointID);
3017
3018 /**
3019  * @brief Get axis.
3020  * @ingroup joints
3021  */
3022 ODE_API void dJointGetLMotorAxis (dJointID, int anum, dVector3 result);
3023
3024 /**
3025  * @brief get joint parameter
3026  * @ingroup joints
3027  */
3028 ODE_API dReal dJointGetLMotorParam (dJointID, int parameter);
3029
3030 /**
3031  * @brief get joint parameter
3032  * @ingroup joints
3033  */
3034 ODE_API dReal dJointGetFixedParam (dJointID, int parameter);
3035
3036
3037 /**
3038  * @brief get the contact point of the first wheel of the Transmission joint.
3039  * @ingroup joints
3040  */
3041 ODE_API void dJointGetTransmissionContactPoint1(dJointID, dVector3 result);
3042
3043 /**
3044  * @brief get contact point of the second wheel of the Transmission joint.
3045  * @ingroup joints
3046  */
3047 ODE_API void dJointGetTransmissionContactPoint2(dJointID, dVector3 result);
3048
3049 /**
3050  * @brief set the first axis for the Transmission joint
3051  * @remarks This is the axis around which the first body is allowed to
3052  * revolve and is attached to it.  It is given in global coordinates
3053  * and can only be set explicitly in intersecting-axes mode.  For the
3054  * parallel-axes and chain modes which share one common axis of
3055  * revolution for both gears dJointSetTransmissionAxis should be used.
3056  * @ingroup joints
3057  */
3058 ODE_API void dJointSetTransmissionAxis1(dJointID, dReal x, dReal y, dReal z);
3059
3060 /**
3061  * @brief get first axis for the Transmission joint
3062  * @remarks In parallel-axes and chain mode the common axis with
3063  * respect to the first body is returned.  If the joint constraint is
3064  * satisfied it should be the same as the axis return with
3065  * dJointGetTransmissionAxis2 or dJointGetTransmissionAxis.
3066  * @ingroup joints
3067  */
3068 ODE_API void dJointGetTransmissionAxis1(dJointID, dVector3 result);
3069
3070 /**
3071  * @brief set second axis for the Transmission joint
3072  * @remarks This is the axis around which the second body is allowed
3073  * to revolve and is attached to it.  It is given in global
3074  * coordinates and can only be set explicitly in intersecting-axes
3075  * mode.  For the parallel-axes and chain modes which share one common
3076  * axis of revolution for both gears dJointSetTransmissionAxis should
3077  * be used.
3078  * @ingroup joints
3079  */
3080 ODE_API void dJointSetTransmissionAxis2(dJointID, dReal x, dReal y, dReal z);
3081
3082 /**
3083  * @brief get second axis for the Transmission joint
3084  * @remarks In parallel-axes and chain mode the common axis with
3085  * respect to the second body is returned.  If the joint constraint is
3086  * satisfied it should be the same as the axis return with
3087  * dJointGetTransmissionAxis1 or dJointGetTransmissionAxis.
3088  * @ingroup joints
3089  */
3090 ODE_API void dJointGetTransmissionAxis2(dJointID, dVector3 result);
3091
3092 /**
3093  * @brief set the first anchor for the Transmission joint
3094  * @remarks This is the point of attachment of the wheel on the
3095  * first body.  It is given in global coordinates.
3096  * @ingroup joints
3097  */
3098 ODE_API void dJointSetTransmissionAnchor1(dJointID, dReal x, dReal y, dReal z);
3099
3100 /**
3101  * @brief get the first anchor of the Transmission joint
3102  * @ingroup joints
3103  */
3104 ODE_API void dJointGetTransmissionAnchor1(dJointID, dVector3 result);
3105
3106 /**
3107  * @brief set the second anchor for the Transmission joint
3108  * @remarks This is the point of attachment of the wheel on the
3109  * second body.  It is given in global coordinates.
3110  * @ingroup joints
3111  */
3112 ODE_API void dJointSetTransmissionAnchor2(dJointID, dReal x, dReal y, dReal z);
3113
3114 /**
3115  * @brief get the second anchor for the Transmission joint
3116  * @ingroup joints
3117  */
3118 ODE_API void dJointGetTransmissionAnchor2(dJointID, dVector3 result);
3119
3120 /**
3121  * @brief set a Transmission joint parameter
3122  * @ingroup joints
3123  */
3124 ODE_API void dJointSetTransmissionParam(dJointID, int parameter, dReal value);
3125
3126 /**
3127  * @brief get a Transmission joint parameter
3128  * @ingroup joints
3129  */
3130 ODE_API dReal dJointGetTransmissionParam(dJointID, int parameter);
3131
3132 /**
3133  * @brief set the Transmission joint mode
3134  * @remarks The mode can be one of dTransmissionParallelAxes,
3135  * dTransmissionIntersectingAxes and dTransmissionChainDrive simulating a
3136  * set of parallel-axes gears, intersecting-axes beveled gears or
3137  * chain and sprockets respectively.
3138  * @ingroup joints
3139  */
3140 ODE_API void dJointSetTransmissionMode( dJointID j, int mode );
3141
3142 /**
3143  * @brief get the Transmission joint mode
3144  * @ingroup joints
3145  */
3146 ODE_API int dJointGetTransmissionMode( dJointID j );
3147
3148 /**
3149  * @brief set the Transmission ratio
3150  * @remarks This is the ratio of the angular speed of the first gear
3151  * to that of the second gear.  It can only be set explicitly in
3152  * parallel-axes mode.  In intersecting-axes mode the ratio is defined
3153  * implicitly by the initial configuration of the wheels and in chain
3154  * mode it is defined implicitly be the wheel radii.
3155  * @ingroup joints
3156  */
3157 ODE_API void dJointSetTransmissionRatio( dJointID j, dReal ratio );
3158
3159 /**
3160  * @brief get the Transmission joint ratio
3161  * @ingroup joints
3162  */
3163 ODE_API dReal dJointGetTransmissionRatio( dJointID j );
3164
3165 /**
3166  * @brief set the common axis for both wheels of the Transmission joint
3167  * @remarks This sets the common axis of revolution for both wheels
3168  * and should only be used in parallel-axes or chain mode.  For
3169  * intersecting-axes mode where each wheel axis needs to be specified
3170  * individually dJointSetTransmissionAxis1 and
3171  * dJointSetTransmissionAxis2 should be used.  The axis is given in
3172  * global coordinates
3173  * @ingroup joints
3174  */
3175 ODE_API void dJointSetTransmissionAxis( dJointID j, dReal x, dReal y, dReal z );
3176
3177 /**
3178  * @brief get the common axis for both wheels of the Transmission joint
3179  * @ingroup joints
3180  */
3181 ODE_API void dJointGetTransmissionAxis( dJointID j, dVector3 result );
3182
3183 /**
3184  * @brief get the phase, that is the traversed angle for the first
3185  * wheel of the Transmission joint
3186  * @ingroup joints
3187  */
3188 ODE_API dReal dJointGetTransmissionAngle1( dJointID j );
3189
3190 /**
3191  * @brief get the phase, that is the traversed angle for the second
3192  * wheel of the Transmission joint
3193  * @ingroup joints
3194  */
3195 ODE_API dReal dJointGetTransmissionAngle2( dJointID j );
3196
3197 /**
3198  * @brief get the radius of the first wheel of the Transmission joint
3199  * @ingroup joints
3200  */
3201 ODE_API dReal dJointGetTransmissionRadius1( dJointID j );
3202
3203 /**
3204  * @brief get the radius of the second wheel of the Transmission joint
3205  * @ingroup joints
3206  */
3207 ODE_API dReal dJointGetTransmissionRadius2( dJointID j );
3208
3209 /**
3210  * @brief set the radius of the first wheel of the Transmission joint
3211  * @remarks The wheel radii can only be set explicitly in chain mode.
3212  * In the other modes they're defined implicitly by the initial
3213  * configuration and ratio of the wheels.
3214  * @ingroup joints
3215  */
3216 ODE_API void dJointSetTransmissionRadius1( dJointID j, dReal radius );
3217
3218 /**
3219  * @brief set the radius of the second wheel of the Transmission joint
3220  * @remarks The wheel radii can only be set explicitly in chain mode.
3221  * In the other modes they're defined implicitly by the initial
3222  * configuration and ratio of the wheels.
3223  * @ingroup joints
3224  */
3225 ODE_API void dJointSetTransmissionRadius2( dJointID j, dReal radius );
3226
3227 /**
3228  * @brief get the backlash of the Transmission joint
3229  * @ingroup joints
3230  */
3231 ODE_API dReal dJointGetTransmissionBacklash( dJointID j );
3232
3233 /**
3234  * @brief set the backlash of the Transmission joint
3235  * @remarks Backlash is the clearance in the mesh of the wheels of the
3236  * transmission and is defined as the maximum distance that the
3237  * geometric contact point can travel without any actual contact or
3238  * transfer of power between the wheels.  This can be converted in
3239  * degrees of revolution for each wheel by dividing by the wheel's
3240  * radius.  To further illustrate this consider the situation where a
3241  * wheel of radius r_1 is driving another wheel of radius r_2 and
3242  * there is an amount of backlash equal to b in their mesh.  If the
3243  * driving wheel were to instantaneously stop there would be no
3244  * contact and hence the driven wheel would continue to turn for
3245  * another b / r_2 radians until all the backlash in the mesh was take
3246  * up and contact restored with the relationship of driving and driven
3247  * wheel reversed.  The backlash is therefore given in untis of
3248  * length.
3249   * @ingroup joints
3250  */
3251 ODE_API void dJointSetTransmissionBacklash( dJointID j, dReal backlash );
3252
3253 /**
3254  * @brief set anchor1 for double ball joint
3255  * @ingroup joints
3256  */
3257 ODE_API void dJointSetDBallAnchor1(dJointID, dReal x, dReal y, dReal z);
3258
3259 /**
3260  * @brief set anchor2 for double ball joint
3261  * @ingroup joints
3262  */
3263 ODE_API void dJointSetDBallAnchor2(dJointID, dReal x, dReal y, dReal z);
3264
3265 /**
3266  * @brief get anchor1 from double ball joint
3267  * @ingroup joints
3268  */
3269 ODE_API void dJointGetDBallAnchor1(dJointID, dVector3 result);
3270
3271 /**
3272  * @brief get anchor2 from double ball joint
3273  * @ingroup joints
3274  */
3275 ODE_API void dJointGetDBallAnchor2(dJointID, dVector3 result);
3276
3277 /**
3278  * @brief get the target distance from double ball joint
3279  * @ingroup joints
3280  */
3281 ODE_API dReal dJointGetDBallDistance(dJointID);
3282
3283 /**
3284  * @brief set the target distance for the double ball joint
3285  * @ingroup joints
3286  */
3287 ODE_API void dJointSetDBallDistance(dJointID, dReal dist);
3288
3289 /**
3290  * @brief set double ball joint parameter
3291  * @ingroup joints
3292  */
3293 ODE_API void dJointSetDBallParam(dJointID, int parameter, dReal value);
3294
3295 /**
3296  * @brief get double ball joint parameter
3297  * @ingroup joints
3298  */
3299 ODE_API dReal dJointGetDBallParam(dJointID, int parameter);
3300
3301 /**
3302  * @brief set axis for double hinge joint
3303  * @ingroup joints
3304  */
3305 ODE_API void dJointSetDHingeAxis(dJointID, dReal x, dReal y, dReal z);
3306
3307 /**
3308  * @brief get axis for double hinge joint
3309  * @ingroup joints
3310  */
3311 ODE_API void dJointGetDHingeAxis(dJointID, dVector3 result);
3312
3313 /**
3314  * @brief set anchor1 for double hinge joint
3315  * @ingroup joints
3316  */
3317 ODE_API void dJointSetDHingeAnchor1(dJointID, dReal x, dReal y, dReal z);
3318
3319 /**
3320  * @brief set anchor2 for double hinge joint
3321  * @ingroup joints
3322  */
3323 ODE_API void dJointSetDHingeAnchor2(dJointID, dReal x, dReal y, dReal z);
3324
3325 /**
3326  * @brief get anchor1 from double hinge joint
3327  * @ingroup joints
3328  */
3329 ODE_API void dJointGetDHingeAnchor1(dJointID, dVector3 result);
3330
3331 /**
3332  * @brief get anchor2 from double hinge joint
3333  * @ingroup joints
3334  */
3335 ODE_API void dJointGetDHingeAnchor2(dJointID, dVector3 result);
3336
3337 /**
3338  * @brief get the set distance from double hinge joint
3339  * @ingroup joints
3340  */
3341 ODE_API dReal dJointGetDHingeDistance(dJointID);
3342
3343 /**
3344  * @brief set double hinge joint parameter
3345  * @ingroup joints
3346  */
3347 ODE_API void dJointSetDHingeParam(dJointID, int parameter, dReal value);
3348
3349 /**
3350  * @brief get double hinge joint parameter
3351  * @ingroup joints
3352  */
3353 ODE_API dReal dJointGetDHingeParam(dJointID, int parameter);
3354
3355
3356
3357
3358 /**
3359  * @ingroup joints
3360  */
3361 ODE_API dJointID dConnectingJoint (dBodyID, dBodyID);
3362
3363 /**
3364  * @ingroup joints
3365  */
3366 ODE_API int dConnectingJointList (dBodyID, dBodyID, dJointID*);
3367
3368 /**
3369  * @brief Utility function
3370  * @return 1 if the two bodies are connected together by
3371  * a joint, otherwise return 0.
3372  * @ingroup joints
3373  */
3374 ODE_API int dAreConnected (dBodyID, dBodyID);
3375
3376 /**
3377  * @brief Utility function
3378  * @return 1 if the two bodies are connected together by
3379  * a joint that does not have type @arg{joint_type}, otherwise return 0.
3380  * @param body1 A body to check.
3381  * @param body2 A body to check.
3382  * @param joint_type is a dJointTypeXXX constant.
3383  * This is useful for deciding whether to add contact joints between two bodies:
3384  * if they are already connected by non-contact joints then it may not be
3385  * appropriate to add contacts, however it is okay to add more contact between-
3386  * bodies that already have contacts.
3387  * @ingroup joints
3388  */
3389 ODE_API int dAreConnectedExcluding (dBodyID body1, dBodyID body2, int joint_type);
3390
3391
3392 #ifdef __cplusplus
3393 }
3394 #endif
3395
3396 #endif