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

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