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

     2  *                                                                       *

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

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

     5  *                                                                       *

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

     7  * modify it under the terms of EITHER:                                  *

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

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

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

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

    12  *       file LICENSE.TXT.                                               *

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

    14  *       the file LICENSE-BSD.TXT.                                       *

    15  *                                                                       *

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

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

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

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

    20  *                                                                       *

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

    22 

    23 #ifndef _ODE_OBJECTS_H_

    24 #define _ODE_OBJECTS_H_

    25 

    26 #include <ode/common.h>

    27 #include <ode/mass.h>

    28 #include <ode/contact.h>

    29 

    30 #ifdef __cplusplus

    31 extern "C" {

    32 #endif

    33 

    34 /**

    35  * @defgroup world World

    36  *

    37  * The world object is a container for rigid bodies and joints. Objects in

    38  * different worlds can not interact, for example rigid bodies from two

    39  * different worlds can not collide.

    40  *

    41  * All the objects in a world exist at the same point in time, thus one

    42  * reason to use separate worlds is to simulate systems at different rates.

    43  * Most applications will only need one world.

    44  */

    45 

    46 

    47 /**

    48  * @brief Create a new, empty world and return its ID number.

    49  * @return an identifier

    50  * @ingroup world

    51  */

    52 ODE_API IMPORT_C dWorldID dWorldCreate(void);

    53 

    54 

    55 /**

    56  * @brief Destroy a world and everything in it.

    57  *

    58  * This includes all bodies, and all joints that are not part of a joint

    59  * group. Joints that are part of a joint group will be deactivated, and

    60  * can be destroyed by calling, for example, dJointGroupEmpty().

    61  * @ingroup world

    62  * @param world the identifier for the world the be destroyed.

    63  */

    64 ODE_API IMPORT_C void dWorldDestroy (dWorldID world);

    65 

    66 

    67 /**

    68  * @brief Set the world's global gravity vector.

    69  *

    70  * The units are m/s^2, so Earth's gravity vector would be (0,0,-9.81),

    71  * assuming that +z is up. The default is no gravity, i.e. (0,0,0).

    72  *

    73  * @ingroup world

    74  */

    75 ODE_API IMPORT_C void dWorldSetGravity (dWorldID, dReal x, dReal y, dReal z);

    76 

    77 

    78 /**

    79  * @brief Get the gravity vector for a given world.

    80  * @ingroup world

    81  */

    82 ODE_API IMPORT_C void dWorldGetGravity (dWorldID, dVector3 gravity);

    83 

    84 

    85 /**

    86  * @brief Set the global ERP value, that controls how much error

    87  * correction is performed in each time step.

    88  * @ingroup world

    89  * @param dWorldID the identifier of the world.

    90  * @param erp Typical values are in the range 0.1--0.8. The default is 0.2.

    91  */

    92 ODE_API IMPORT_C void dWorldSetERP (dWorldID, dReal erp);

    93 

    94 /**

    95  * @brief Get the error reduction parameter.

    96  * @ingroup world

    97  * @return ERP value

    98  */

    99 ODE_API IMPORT_C dReal dWorldGetERP (dWorldID);

   100 

   101 

   102 /**

   103  * @brief Set the global CFM (constraint force mixing) value.

   104  * @ingroup world

   105  * @param cfm Typical values are in the range @m{10^{-9}} -- 1.

   106  * The default is 10^-5 if single precision is being used, or 10^-10

   107  * if double precision is being used.

   108  */

   109 ODE_API IMPORT_C void dWorldSetCFM (dWorldID, dReal cfm);

   110 

   111 /**

   112  * @brief Get the constraint force mixing value.

   113  * @ingroup world

   114  * @return CFM value

   115  */

   116 ODE_API IMPORT_C dReal dWorldGetCFM (dWorldID);

   117 

   118 

   119 /**

   120  * @brief Step the world.

   121  *

   122  * This uses a "big matrix" method that takes time on the order of m^3

   123  * and memory on the order of m^2, where m is the total number of constraint

   124  * rows. For large systems this will use a lot of memory and can be very slow,

   125  * but this is currently the most accurate method.

   126  * @ingroup world

   127  * @param stepsize The number of seconds that the simulation has to advance.

   128  */

   129 ODE_API IMPORT_C void dWorldStep (dWorldID, dReal stepsize);

   130 

   131 

   132 /**

   133  * @brief Converts an impulse to a force.

   134  * @ingroup world

   135  * @remarks

   136  * If you want to apply a linear or angular impulse to a rigid body,

   137  * instead of a force or a torque, then you can use this function to convert

   138  * the desired impulse into a force/torque vector before calling the

   139  * BodyAdd... function.

   140  * The current algorithm simply scales the impulse by 1/stepsize,

   141  * where stepsize is the step size for the next step that will be taken.

   142  * This function is given a dWorldID because, in the future, the force

   143  * computation may depend on integrator parameters that are set as

   144  * properties of the world.

   145  */

   146 ODE_API IMPORT_C void dWorldImpulseToForce

   147 (

   148   dWorldID, dReal stepsize,

   149   dReal ix, dReal iy, dReal iz, dVector3 force

   150 );

   151 

   152 

   153 /**

   154  * @brief Step the world.

   155  * @ingroup world

   156  * @remarks

   157  * This uses an iterative method that takes time on the order of m*N

   158  * and memory on the order of m, where m is the total number of constraint

   159  * rows N is the number of iterations.

   160  * For large systems this is a lot faster than dWorldStep(),

   161  * but it is less accurate.

   162  * @remarks

   163  * QuickStep is great for stacks of objects especially when the

   164  * auto-disable feature is used as well.

   165  * However, it has poor accuracy for near-singular systems.

   166  * Near-singular systems can occur when using high-friction contacts, motors,

   167  * or certain articulated structures. For example, a robot with multiple legs

   168  * sitting on the ground may be near-singular.

   169  * @remarks

   170  * There are ways to help overcome QuickStep's inaccuracy problems:

   171  * \li Increase CFM.

   172  * \li Reduce the number of contacts in your system (e.g. use the minimum

   173  *     number of contacts for the feet of a robot or creature).

   174  * \li Don't use excessive friction in the contacts.

   175  * \li Use contact slip if appropriate

   176  * \li Avoid kinematic loops (however, kinematic loops are inevitable in

   177  *     legged creatures).

   178  * \li Don't use excessive motor strength.

   179  * \liUse force-based motors instead of velocity-based motors.

   180  *

   181  * Increasing the number of QuickStep iterations may help a little bit, but

   182  * it is not going to help much if your system is really near singular.

   183  */

   184 ODE_API IMPORT_C void dWorldQuickStep (dWorldID w, dReal stepsize);

   185 

   186 

   187 /**

   188  * @brief Set the number of iterations that the QuickStep method performs per

   189  *        step.

   190  * @ingroup world

   191  * @remarks

   192  * More iterations will give a more accurate solution, but will take

   193  * longer to compute.

   194  * @param num The default is 20 iterations.

   195  */

   196 ODE_API IMPORT_C void dWorldSetQuickStepNumIterations (dWorldID, int num);

   197 

   198 

   199 /**

   200  * @brief Get the number of iterations that the QuickStep method performs per

   201  *        step.

   202  * @ingroup world

   203  * @return nr of iterations

   204  */

   205 ODE_API IMPORT_C int dWorldGetQuickStepNumIterations (dWorldID);

   206 

   207 /**

   208  * @brief Set the SOR over-relaxation parameter

   209  * @ingroup world

   210  * @param over_relaxation value to use by SOR

   211  */

   212 ODE_API IMPORT_C void dWorldSetQuickStepW (dWorldID, dReal over_relaxation);

   213 

   214 /**

   215  * @brief Get the SOR over-relaxation parameter

   216  * @ingroup world

   217  * @returns the over-relaxation setting

   218  */

   219 ODE_API IMPORT_C dReal dWorldGetQuickStepW (dWorldID);

   220 

   221 /* World contact parameter functions */

   222 

   223 /**

   224  * @brief Set the maximum correcting velocity that contacts are allowed

   225  * to generate.

   226  * @ingroup world

   227  * @param vel The default value is infinity (i.e. no limit).

   228  * @remarks

   229  * Reducing this value can help prevent "popping" of deeply embedded objects.

   230  */

   231 ODE_API IMPORT_C void dWorldSetContactMaxCorrectingVel (dWorldID, dReal vel);

   232 

   233 /**

   234  * @brief Get the maximum correcting velocity that contacts are allowed

   235  * to generated.

   236  * @ingroup world

   237  */

   238 ODE_API IMPORT_C dReal dWorldGetContactMaxCorrectingVel (dWorldID);

   239 

   240 /**

   241  * @brief Set the depth of the surface layer around all geometry objects.

   242  * @ingroup world

   243  * @remarks

   244  * Contacts are allowed to sink into the surface layer up to the given

   245  * depth before coming to rest.

   246  * @param depth The default value is zero.

   247  * @remarks

   248  * Increasing this to some small value (e.g. 0.001) can help prevent

   249  * jittering problems due to contacts being repeatedly made and broken.

   250  */

   251 ODE_API IMPORT_C void dWorldSetContactSurfaceLayer (dWorldID, dReal depth);

   252 

   253 /**

   254  * @brief Get the depth of the surface layer around all geometry objects.

   255  * @ingroup world

   256  * @returns the depth

   257  */

   258 ODE_API IMPORT_C dReal dWorldGetContactSurfaceLayer (dWorldID);

   259 

   260 /* StepFast1 functions */

   261 

   262 /**

   263  * @brief Step the world using the StepFast1 algorithm.

   264  * @param stepsize the nr of seconds to advance the simulation.

   265  * @param maxiterations The number of iterations to perform.

   266  * @ingroup world

   267  */

   268 ODE_API IMPORT_C void dWorldStepFast1(dWorldID, dReal stepsize, int maxiterations);

   269 

   270 

   271 /**

   272  * @defgroup disable Automatic Enabling and Disabling

   273  *

   274  * Every body can be enabled or disabled. Enabled bodies participate in the

   275  * simulation, while disabled bodies are turned off and do not get updated

   276  * during a simulation step. New bodies are always created in the enabled state.

   277  *

   278  * A disabled body that is connected through a joint to an enabled body will be

   279  * automatically re-enabled at the next simulation step.

   280  *

   281  * Disabled bodies do not consume CPU time, therefore to speed up the simulation

   282  * bodies should be disabled when they come to rest. This can be done automatically

   283  * with the auto-disable feature.

   284  *

   285  * If a body has its auto-disable flag turned on, it will automatically disable

   286  * itself when

   287  *   @li It has been idle for a given number of simulation steps.

   288  *   @li It has also been idle for a given amount of simulation time.

   289  *

   290  * A body is considered to be idle when the magnitudes of both its

   291  * linear average velocity and angular average velocity are below given thresholds.

   292  * The sample size for the average defaults to one and can be disabled by setting

   293  * to zero with 

   294  *

   295  * Thus, every body has six auto-disable parameters: an enabled flag, a idle step

   296  * count, an idle time, linear/angular average velocity thresholds, and the

   297  * average samples count.

   298  *

   299  * Newly created bodies get these parameters from world.

   300  */

   301 

   302 /**

   303  * @brief Set the AutoEnableDepth parameter used by the StepFast1 algorithm.

   304  * @ingroup disable

   305  */

   306 ODE_API IMPORT_C void dWorldSetAutoEnableDepthSF1(dWorldID, int autoEnableDepth);

   307 

   308 /**

   309  * @brief Get the AutoEnableDepth parameter used by the StepFast1 algorithm.

   310  * @ingroup disable

   311  */

   312 ODE_API IMPORT_C int dWorldGetAutoEnableDepthSF1(dWorldID);

   313 

   314 /**

   315  * @brief Get auto disable linear threshold for newly created bodies.

   316  * @ingroup disable

   317  * @return the threshold

   318  */

   319 ODE_API IMPORT_C dReal dWorldGetAutoDisableLinearThreshold (dWorldID);

   320 

   321 /**

   322  * @brief Set auto disable linear threshold for newly created bodies.

   323  * @param linear_threshold default is 0.01

   324  * @ingroup disable

   325  */

   326 ODE_API IMPORT_C void  dWorldSetAutoDisableLinearThreshold (dWorldID, dReal linear_threshold);

   327 

   328 /**

   329  * @brief Get auto disable angular threshold for newly created bodies.

   330  * @ingroup disable

   331  * @return the threshold

   332  */

   333 ODE_API IMPORT_C dReal dWorldGetAutoDisableAngularThreshold (dWorldID);

   334 

   335 /**

   336  * @brief Set auto disable angular threshold for newly created bodies.

   337  * @param linear_threshold default is 0.01

   338  * @ingroup disable

   339  */

   340 ODE_API IMPORT_C void dWorldSetAutoDisableAngularThreshold (dWorldID, dReal angular_threshold);

   341 

   342 /**

   343  * @brief Get auto disable linear average threshold for newly created bodies.

   344  * @ingroup disable

   345  * @return the threshold

   346  */

   347 ODE_API dReal dWorldGetAutoDisableLinearAverageThreshold (dWorldID);

   348 

   349 /**

   350  * @brief Set auto disable linear average threshold for newly created bodies.

   351  * @param linear_average_threshold default is 0.01

   352  * @ingroup disable

   353  */

   354 ODE_API void  dWorldSetAutoDisableLinearAverageThreshold (dWorldID, dReal linear_average_threshold);

   355 

   356 /**

   357  * @brief Get auto disable angular average threshold for newly created bodies.

   358  * @ingroup disable

   359  * @return the threshold

   360  */

   361 ODE_API dReal dWorldGetAutoDisableAngularAverageThreshold (dWorldID);

   362 

   363 /**

   364  * @brief Set auto disable angular average threshold for newly created bodies.

   365  * @param linear_average_threshold default is 0.01

   366  * @ingroup disable

   367  */

   368 ODE_API void dWorldSetAutoDisableAngularAverageThreshold (dWorldID, dReal angular_average_threshold);

   369 

   370 /**

   371  * @brief Get auto disable sample count for newly created bodies.

   372  * @ingroup disable

   373  * @return number of samples used

   374  */

   375 ODE_API IMPORT_C int dWorldGetAutoDisableAverageSamplesCount (dWorldID);

   376 

   377 /**

   378  * @brief Set auto disable average sample count for newly created bodies.

   379  * @ingroup disable

   380  * @param average_samples_count Default is 1, meaning only instantaneous velocity is used.

   381  * Set to zero to disable sampling and thus prevent any body from auto-disabling.

   382  */

   383 ODE_API IMPORT_C void dWorldSetAutoDisableAverageSamplesCount (dWorldID, unsigned int average_samples_count );

   384 

   385 /**

   386  * @brief Get auto disable steps for newly created bodies.

   387  * @ingroup disable

   388  * @return nr of steps

   389  */

   390 ODE_API IMPORT_C int dWorldGetAutoDisableSteps (dWorldID);

   391 

   392 /**

   393  * @brief Set auto disable steps for newly created bodies.

   394  * @ingroup disable

   395  * @param steps default is 10

   396  */

   397 ODE_API IMPORT_C void dWorldSetAutoDisableSteps (dWorldID, int steps);

   398 

   399 /**

   400  * @brief Get auto disable time for newly created bodies.

   401  * @ingroup disable

   402  * @return nr of seconds

   403  */

   404 ODE_API IMPORT_C dReal dWorldGetAutoDisableTime (dWorldID);

   405 

   406 /**

   407  * @brief Set auto disable time for newly created bodies.

   408  * @ingroup disable

   409  * @param time default is 0 seconds

   410  */

   411 ODE_API IMPORT_C void dWorldSetAutoDisableTime (dWorldID, dReal time);

   412 

   413 /**

   414  * @brief Get auto disable flag for newly created bodies.

   415  * @ingroup disable

   416  * @return 0 or 1

   417  */

   418 ODE_API IMPORT_C int dWorldGetAutoDisableFlag (dWorldID);

   419 

   420 /**

   421  * @brief Set auto disable flag for newly created bodies.

   422  * @ingroup disable

   423  * @param do_auto_disable default is false.

   424  */

   425 ODE_API IMPORT_C void dWorldSetAutoDisableFlag (dWorldID, int do_auto_disable);

   426 

   427 

   428 

   429 /**

   430  * @defgroup bodies Rigid Bodies

   431  *

   432  * A rigid body has various properties from the point of view of the

   433  * simulation. Some properties change over time:

   434  *

   435  *  @li Position vector (x,y,z) of the body's point of reference.

   436  *      Currently the point of reference must correspond to the body's center of mass.

   437  *  @li Linear velocity of the point of reference, a vector (vx,vy,vz).

   438  *  @li Orientation of a body, represented by a quaternion (qs,qx,qy,qz) or

   439  *      a 3x3 rotation matrix.

   440  *  @li Angular velocity vector (wx,wy,wz) which describes how the orientation

   441  *      changes over time.

   442  *

   443  * Other body properties are usually constant over time:

   444  *

   445  *  @li Mass of the body.

   446  *  @li Position of the center of mass with respect to the point of reference.

   447  *      In the current implementation the center of mass and the point of

   448  *      reference must coincide.

   449  *  @li Inertia matrix. This is a 3x3 matrix that describes how the body's mass

   450  *      is distributed around the center of mass. Conceptually each body has an

   451  *      x-y-z coordinate frame embedded in it that moves and rotates with the body.

   452  *

   453  * The origin of this coordinate frame is the body's point of reference. Some values

   454  * in ODE (vectors, matrices etc) are relative to the body coordinate frame, and others

   455  * are relative to the global coordinate frame.

   456  *

   457  * Note that the shape of a rigid body is not a dynamical property (except insofar as

   458  * it influences the various mass properties). It is only collision detection that cares

   459  * about the detailed shape of the body.

   460  */

   461 

   462 

   463 /**

   464  * @brief Get auto disable linear average threshold.

   465  * @ingroup bodies

   466  * @return the threshold

   467  */

   468 ODE_API IMPORT_C dReal dBodyGetAutoDisableLinearThreshold (dBodyID);

   469 

   470 /**

   471  * @brief Set auto disable linear average threshold.

   472  * @ingroup bodies

   473  * @return the threshold

   474  */

   475 ODE_API IMPORT_C void  dBodySetAutoDisableLinearThreshold (dBodyID, dReal linear_average_threshold);

   476 

   477 /**

   478  * @brief Get auto disable angular average threshold.

   479  * @ingroup bodies

   480  * @return the threshold

   481  */

   482 ODE_API IMPORT_C dReal dBodyGetAutoDisableAngularThreshold (dBodyID);

   483 

   484 /**

   485  * @brief Set auto disable angular average threshold.

   486  * @ingroup bodies

   487  * @return the threshold

   488  */

   489 ODE_API IMPORT_C void  dBodySetAutoDisableAngularThreshold (dBodyID, dReal angular_average_threshold);

   490 

   491 /**

   492  * @brief Get auto disable average size (samples count).

   493  * @ingroup bodies

   494  * @return the nr of steps/size.

   495  */

   496 ODE_API IMPORT_C int dBodyGetAutoDisableAverageSamplesCount (dBodyID);

   497 

   498 /**

   499  * @brief Set auto disable average buffer size (average steps).

   500  * @ingroup bodies

   501  * @param average_samples_count the nr of samples to review.

   502  */

   503 ODE_API IMPORT_C void dBodySetAutoDisableAverageSamplesCount (dBodyID, unsigned int average_samples_count);

   504 

   505 

   506 /**

   507  * @brief Get auto steps a body must be thought of as idle to disable

   508  * @ingroup bodies

   509  * @return the nr of steps

   510  */

   511 ODE_API IMPORT_C int dBodyGetAutoDisableSteps (dBodyID);

   512 

   513 /**

   514  * @brief Set auto disable steps.

   515  * @ingroup bodies

   516  * @param steps the nr of steps.

   517  */

   518 ODE_API IMPORT_C void dBodySetAutoDisableSteps (dBodyID, int steps);

   519 

   520 /**

   521  * @brief Get auto disable time.

   522  * @ingroup bodies

   523  * @return nr of seconds

   524  */

   525 ODE_API IMPORT_C dReal dBodyGetAutoDisableTime (dBodyID);

   526 

   527 /**

   528  * @brief Set auto disable time.

   529  * @ingroup bodies

   530  * @param time nr of seconds.

   531  */

   532 ODE_API IMPORT_C void  dBodySetAutoDisableTime (dBodyID, dReal time);

   533 

   534 /**

   535  * @brief Get auto disable flag.

   536  * @ingroup bodies

   537  * @return 0 or 1

   538  */

   539 ODE_API IMPORT_C int dBodyGetAutoDisableFlag (dBodyID);

   540 

   541 /**

   542  * @brief Set auto disable flag.

   543  * @ingroup bodies

   544  * @param do_auto_disable 0 or 1

   545  */

   546 ODE_API IMPORT_C void dBodySetAutoDisableFlag (dBodyID, int do_auto_disable);

   547 

   548 /**

   549  * @brief Set auto disable defaults.

   550  * @remarks

   551  * Set the values for the body to those set as default for the world.

   552  * @ingroup bodies

   553  */

   554 ODE_API IMPORT_C void  dBodySetAutoDisableDefaults (dBodyID);

   555 

   556 

   557 /**

   558  * @brief Retrives the world attached to te given body.

   559  * @remarks

   560  * 

   561  * @ingroup bodies

   562  */

   563 ODE_API IMPORT_C dWorldID dBodyGetWorld (dBodyID);

   564 

   565 /**

   566  * @brief Create a body in given world.

   567  * @remarks

   568  * Default mass parameters are at position (0,0,0).

   569  * @ingroup bodies

   570  */

   571 ODE_API IMPORT_C dBodyID dBodyCreate (dWorldID);

   572 

   573 /**

   574  * @brief Destroy a body.

   575  * @remarks

   576  * All joints that are attached to this body will be put into limbo:

   577  * i.e. unattached and not affecting the simulation, but they will NOT be

   578  * deleted.

   579  * @ingroup bodies

   580  */

   581 ODE_API IMPORT_C void dBodyDestroy (dBodyID);

   582 

   583 /**

   584  * @brief Set the body's user-data pointer.

   585  * @ingroup bodies

   586  * @param data arbitraty pointer

   587  */

   588 ODE_API IMPORT_C void  dBodySetData (dBodyID, void *data);

   589 

   590 /**

   591  * @brief Get the body's user-data pointer.

   592  * @ingroup bodies

   593  * @return a pointer to the user's data.

   594  */

   595 ODE_API IMPORT_C void *dBodyGetData (dBodyID);

   596 

   597 /**

   598  * @brief Set position of a body.

   599  * @remarks

   600  * After setting, the outcome of the simulation is undefined

   601  * if the new configuration is inconsistent with the joints/constraints

   602  * that are present.

   603  * @ingroup bodies

   604  */

   605 ODE_API IMPORT_C void dBodySetPosition   (dBodyID, dReal x, dReal y, dReal z);

   606 

   607 /**

   608  * @brief Set the orientation of a body.

   609  * @ingroup bodies

   610  * @remarks

   611  * After setting, the outcome of the simulation is undefined

   612  * if the new configuration is inconsistent with the joints/constraints

   613  * that are present.

   614  */

   615 ODE_API IMPORT_C void dBodySetRotation   (dBodyID, const dMatrix3 R);

   616 

   617 /**

   618  * @brief Set the orientation of a body.

   619  * @ingroup bodies

   620  * @remarks

   621  * After setting, the outcome of the simulation is undefined

   622  * if the new configuration is inconsistent with the joints/constraints

   623  * that are present.

   624  */

   625 ODE_API IMPORT_C void dBodySetQuaternion (dBodyID, const dQuaternion q);

   626 

   627 /**

   628  * @brief Set the linear velocity of a body.

   629  * @ingroup bodies

   630  */

   631 ODE_API IMPORT_C void dBodySetLinearVel  (dBodyID, dReal x, dReal y, dReal z);

   632 

   633 /**

   634  * @brief Set the angular velocity of a body.

   635  * @ingroup bodies

   636  */

   637 ODE_API IMPORT_C void dBodySetAngularVel (dBodyID, dReal x, dReal y, dReal z);

   638 

   639 /**

   640  * @brief Get the position of a body.

   641  * @ingroup bodies

   642  * @remarks

   643  * When getting, the returned values are pointers to internal data structures,

   644  * so the vectors are valid until any changes are made to the rigid body

   645  * system structure.

   646  * @sa dBodyCopyPosition

   647  */

   648 ODE_API IMPORT_C const dReal * dBodyGetPosition   (dBodyID);

   649 

   650 

   651 /**

   652  * @brief Copy the position of a body into a vector.

   653  * @ingroup bodies

   654  * @param body  the body to query

   655  * @param pos   a copy of the body position

   656  * @sa dBodyGetPosition

   657  */

   658 ODE_API IMPORT_C void dBodyCopyPosition (dBodyID body, dVector3 pos);

   659 

   660 

   661 /**

   662  * @brief Get the rotation of a body.

   663  * @ingroup bodies

   664  * @return pointer to a 4x3 rotation matrix.

   665  */

   666 ODE_API IMPORT_C const dReal * dBodyGetRotation   (dBodyID);

   667 

   668 

   669 /**

   670  * @brief Copy the rotation of a body.

   671  * @ingroup bodies

   672  * @param body   the body to query

   673  * @param R      a copy of the rotation matrix

   674  * @sa dBodyGetRotation

   675  */

   676 ODE_API IMPORT_C void dBodyCopyRotation (dBodyID, dMatrix3 R);

   677 

   678 

   679 /**

   680  * @brief Get the rotation of a body.

   681  * @ingroup bodies

   682  * @return pointer to 4 scalars that represent the quaternion.

   683  */

   684 ODE_API IMPORT_C const dReal * dBodyGetQuaternion (dBodyID);

   685 

   686 

   687 /**

   688  * @brief Copy the orientation of a body into a quaternion.

   689  * @ingroup bodies

   690  * @param body  the body to query

   691  * @param quat  a copy of the orientation quaternion

   692  * @sa dBodyGetQuaternion

   693  */

   694 ODE_API IMPORT_C void dBodyCopyQuaternion(dBodyID body, dQuaternion quat);

   695 

   696 

   697 /**

   698  * @brief Get the linear velocity of a body.

   699  * @ingroup bodies

   700  */

   701 ODE_API IMPORT_C const dReal * dBodyGetLinearVel  (dBodyID);

   702 

   703 /**

   704  * @brief Get the angular velocity of a body.

   705  * @ingroup bodies

   706  */

   707 ODE_API IMPORT_C const dReal * dBodyGetAngularVel (dBodyID);

   708 

   709 /**

   710  * @brief Set the mass of a body.

   711  * @ingroup bodies

   712  */

   713 ODE_API IMPORT_C void dBodySetMass (dBodyID, const dMass *mass);

   714 

   715 /**

   716  * @brief Get the mass of a body.

   717  * @ingroup bodies

   718  */

   719 ODE_API IMPORT_C void dBodyGetMass (dBodyID, dMass *mass);

   720 

   721 /**

   722  * @brief Add force at centre of mass of body in absolute coordinates.

   723  * @ingroup bodies

   724  */

   725 ODE_API IMPORT_C void dBodyAddForce            (dBodyID, dReal fx, dReal fy, dReal fz);

   726 

   727 /**

   728  * @brief Add torque at centre of mass of body in absolute coordinates.

   729  * @ingroup bodies

   730  */

   731 ODE_API IMPORT_C void dBodyAddTorque           (dBodyID, dReal fx, dReal fy, dReal fz);

   732 

   733 /**

   734  * @brief Add force at centre of mass of body in coordinates relative to body.

   735  * @ingroup bodies

   736  */

   737 ODE_API IMPORT_C void dBodyAddRelForce         (dBodyID, dReal fx, dReal fy, dReal fz);

   738 

   739 /**

   740  * @brief Add torque at centre of mass of body in coordinates relative to body.

   741  * @ingroup bodies

   742  */

   743 ODE_API IMPORT_C void dBodyAddRelTorque        (dBodyID, dReal fx, dReal fy, dReal fz);

   744 

   745 /**

   746  * @brief Add force at specified point in body in global coordinates.

   747  * @ingroup bodies

   748  */

   749 ODE_API IMPORT_C void dBodyAddForceAtPos       (dBodyID, dReal fx, dReal fy, dReal fz,

   750 			                dReal px, dReal py, dReal pz);

   751 /**

   752  * @brief Add force at specified point in body in local coordinates.

   753  * @ingroup bodies

   754  */

   755 ODE_API IMPORT_C void dBodyAddForceAtRelPos    (dBodyID, dReal fx, dReal fy, dReal fz,

   756 			                dReal px, dReal py, dReal pz);

   757 /**

   758  * @brief Add force at specified point in body in global coordinates.

   759  * @ingroup bodies

   760  */

   761 ODE_API IMPORT_C void dBodyAddRelForceAtPos    (dBodyID, dReal fx, dReal fy, dReal fz,

   762 			                dReal px, dReal py, dReal pz);

   763 /**

   764  * @brief Add force at specified point in body in local coordinates.

   765  * @ingroup bodies

   766  */

   767 ODE_API IMPORT_C void dBodyAddRelForceAtRelPos (dBodyID, dReal fx, dReal fy, dReal fz,

   768 			                dReal px, dReal py, dReal pz);

   769 

   770 /**

   771  * @brief Return the current accumulated force vector.

   772  * @return points to an array of 3 reals.

   773  * @remarks

   774  * The returned values are pointers to internal data structures, so

   775  * the vectors are only valid until any changes are made to the rigid

   776  * body system.

   777  * @ingroup bodies

   778  */

   779 ODE_API IMPORT_C const dReal * dBodyGetForce   (dBodyID);

   780 

   781 /**

   782  * @brief Return the current accumulated torque vector.

   783  * @return points to an array of 3 reals.

   784  * @remarks

   785  * The returned values are pointers to internal data structures, so

   786  * the vectors are only valid until any changes are made to the rigid

   787  * body system.

   788  * @ingroup bodies

   789  */

   790 ODE_API IMPORT_C const dReal * dBodyGetTorque  (dBodyID);

   791 

   792 /**

   793  * @brief Set the body force accumulation vector.

   794  * @remarks

   795  * This is mostly useful to zero the force and torque for deactivated bodies

   796  * before they are reactivated, in the case where the force-adding functions

   797  * were called on them while they were deactivated.

   798  * @ingroup bodies

   799  */

   800 ODE_API IMPORT_C void dBodySetForce  (dBodyID b, dReal x, dReal y, dReal z);

   801 

   802 /**

   803  * @brief Set the body torque accumulation vector.

   804  * @remarks

   805  * This is mostly useful to zero the force and torque for deactivated bodies

   806  * before they are reactivated, in the case where the force-adding functions

   807  * were called on them while they were deactivated.

   808  * @ingroup bodies

   809  */

   810 ODE_API IMPORT_C void dBodySetTorque (dBodyID b, dReal x, dReal y, dReal z);

   811 

   812 /**

   813  * @brief Get world position of a relative point on body.

   814  * @ingroup bodies

   815  * @param result will contain the result.

   816  */

   817 ODE_API IMPORT_C void dBodyGetRelPointPos

   818 (

   819   dBodyID, dReal px, dReal py, dReal pz,

   820   dVector3 result

   821 );

   822 

   823 /**

   824  * @brief Get velocity vector in global coords of a relative point on body.

   825  * @ingroup bodies

   826  * @param result will contain the result.

   827  */

   828 ODE_API IMPORT_C void dBodyGetRelPointVel

   829 (

   830   dBodyID, dReal px, dReal py, dReal pz,

   831   dVector3 result

   832 );

   833 

   834 /**

   835  * @brief Get velocity vector in global coords of a globally

   836  * specified point on a body.

   837  * @ingroup bodies

   838  * @param result will contain the result.

   839  */

   840 ODE_API IMPORT_C void dBodyGetPointVel

   841 (

   842   dBodyID, dReal px, dReal py, dReal pz,

   843   dVector3 result

   844 );

   845 

   846 /**

   847  * @brief takes a point in global coordinates and returns

   848  * the point's position in body-relative coordinates.

   849  * @remarks

   850  * This is the inverse of dBodyGetRelPointPos()

   851  * @ingroup bodies

   852  * @param result will contain the result.

   853  */

   854 ODE_API IMPORT_C void dBodyGetPosRelPoint

   855 (

   856   dBodyID, dReal px, dReal py, dReal pz,

   857   dVector3 result

   858 );

   859 

   860 /**

   861  * @brief Convert from local to world coordinates.

   862  * @ingroup bodies

   863  * @param result will contain the result.

   864  */

   865 ODE_API IMPORT_C void dBodyVectorToWorld

   866 (

   867   dBodyID, dReal px, dReal py, dReal pz,

   868   dVector3 result

   869 );

   870 

   871 /**

   872  * @brief Convert from world to local coordinates.

   873  * @ingroup bodies

   874  * @param result will contain the result.

   875  */

   876 ODE_API IMPORT_C void dBodyVectorFromWorld

   877 (

   878   dBodyID, dReal px, dReal py, dReal pz,

   879   dVector3 result

   880 );

   881 

   882 /**

   883  * @brief controls the way a body's orientation is updated at each timestep.

   884  * @ingroup bodies

   885  * @param mode can be 0 or 1:

   886  * \li 0: An ``infinitesimal'' orientation update is used.

   887  * This is fast to compute, but it can occasionally cause inaccuracies

   888  * for bodies that are rotating at high speed, especially when those

   889  * bodies are joined to other bodies.

   890  * This is the default for every new body that is created.

   891  * \li 1: A ``finite'' orientation update is used.

   892  * This is more costly to compute, but will be more accurate for high

   893  * speed rotations.

   894  * @remarks

   895  * Note however that high speed rotations can result in many types of

   896  * error in a simulation, and the finite mode will only fix one of those

   897  * sources of error.

   898  */

   899 ODE_API IMPORT_C void dBodySetFiniteRotationMode (dBodyID, int mode);

   900 

   901 /**

   902  * @brief sets the finite rotation axis for a body.

   903  * @ingroup bodies

   904  * @remarks

   905  * This is axis only has meaning when the finite rotation mode is set

   906  * If this axis is zero (0,0,0), full finite rotations are performed on

   907  * the body.

   908  * If this axis is nonzero, the body is rotated by performing a partial finite

   909  * rotation along the axis direction followed by an infinitesimal rotation

   910  * along an orthogonal direction.

   911  * @remarks

   912  * This can be useful to alleviate certain sources of error caused by quickly

   913  * spinning bodies. For example, if a car wheel is rotating at high speed

   914  * you can call this function with the wheel's hinge axis as the argument to

   915  * try and improve its behavior.

   916  */

   917 ODE_API IMPORT_C void dBodySetFiniteRotationAxis (dBodyID, dReal x, dReal y, dReal z);

   918 

   919 /**

   920  * @brief Get the way a body's orientation is updated each timestep.

   921  * @ingroup bodies

   922  * @return the mode 0 (infitesimal) or 1 (finite).

   923  */

   924 ODE_API IMPORT_C int dBodyGetFiniteRotationMode (dBodyID);

   925 

   926 /**

   927  * @brief Get the finite rotation axis.

   928  * @param result will contain the axis.

   929  * @ingroup bodies

   930  */

   931 ODE_API IMPORT_C void dBodyGetFiniteRotationAxis (dBodyID, dVector3 result);

   932 

   933 /**

   934  * @brief Get the number of joints that are attached to this body.

   935  * @ingroup bodies

   936  * @return nr of joints

   937  */

   938 ODE_API IMPORT_C int dBodyGetNumJoints (dBodyID b);

   939 

   940 /**

   941  * @brief Return a joint attached to this body, given by index.

   942  * @ingroup bodies

   943  * @param index valid range is  0 to n-1 where n is the value returned by

   944  * dBodyGetNumJoints().

   945  */

   946 ODE_API IMPORT_C dJointID dBodyGetJoint (dBodyID, int index);

   947 

   948 /**

   949  * @brief Manually enable a body.

   950  * @param dBodyID identification of body.

   951  * @ingroup bodies

   952  */

   953 ODE_API IMPORT_C void dBodyEnable (dBodyID);

   954 

   955 /**

   956  * @brief Manually disable a body.

   957  * @ingroup bodies

   958  * @remarks

   959  * A disabled body that is connected through a joint to an enabled body will

   960  * be automatically re-enabled at the next simulation step.

   961  */

   962 ODE_API IMPORT_C void dBodyDisable (dBodyID);

   963 

   964 /**

   965  * @brief Check wether a body is enabled.

   966  * @ingroup bodies

   967  * @return 1 if a body is currently enabled or 0 if it is disabled.

   968  */

   969 ODE_API IMPORT_C int dBodyIsEnabled (dBodyID);

   970 

   971 /**

   972  * @brief Set whether the body is influenced by the world's gravity or not.

   973  * @ingroup bodies

   974  * @param mode when nonzero gravity affects this body.

   975  * @remarks

   976  * Newly created bodies are always influenced by the world's gravity.

   977  */

   978 ODE_API IMPORT_C void dBodySetGravityMode (dBodyID b, int mode);

   979 

   980 /**

   981  * @brief Get whether the body is influenced by the world's gravity or not.

   982  * @ingroup bodies

   983  * @return nonzero means gravity affects this body.

   984  */

   985 ODE_API IMPORT_C int dBodyGetGravityMode (dBodyID b);

   986 

   987 

   988 

   989 /**

   990  * @defgroup joints Joints

   991  *

   992  * In real life a joint is something like a hinge, that is used to connect two

   993  * objects.

   994  * In ODE a joint is very similar: It is a relationship that is enforced between

   995  * two bodies so that they can only have certain positions and orientations

   996  * relative to each other.

   997  * This relationship is called a constraint -- the words joint and

   998  * constraint are often used interchangeably.

   999  *

  1000  * A joint has a set of parameters that can be set. These include:

  1001  *

  1002  *

  1003  * \li  dParamLoStop Low stop angle or position. Setting this to

  1004  *	-dInfinity (the default value) turns off the low stop.

  1005  *	For rotational joints, this stop must be greater than -pi to be

  1006  *	effective.

  1007  * \li  dParamHiStop High stop angle or position. Setting this to

  1008  *	dInfinity (the default value) turns off the high stop.

  1009  *	For rotational joints, this stop must be less than pi to be

  1010  *	effective.

  1011  *	If the high stop is less than the low stop then both stops will

  1012  *	be ineffective.

  1013  * \li  dParamVel Desired motor velocity (this will be an angular or

  1014  *	linear velocity).

  1015  * \li  dParamFMax The maximum force or torque that the motor will use to

  1016  *	achieve the desired velocity.

  1017  *	This must always be greater than or equal to zero.

  1018  *	Setting this to zero (the default value) turns off the motor.

  1019  * \li  dParamFudgeFactor The current joint stop/motor implementation has

  1020  *	a small problem:

  1021  *	when the joint is at one stop and the motor is set to move it away

  1022  *	from the stop, too much force may be applied for one time step,

  1023  *	causing a ``jumping'' motion.

  1024  *	This fudge factor is used to scale this excess force.

  1025  *	It should have a value between zero and one (the default value).

  1026  *	If the jumping motion is too visible in a joint, the value can be

  1027  *	reduced.

  1028  *	Making this value too small can prevent the motor from being able to

  1029  *	move the joint away from a stop.

  1030  * \li  dParamBounce The bouncyness of the stops.

  1031  *	This is a restitution parameter in the range 0..1.

  1032  *	0 means the stops are not bouncy at all, 1 means maximum bouncyness.

  1033  * \li  dParamCFM The constraint force mixing (CFM) value used when not

  1034  *	at a stop.

  1035  * \li  dParamStopERP The error reduction parameter (ERP) used by the

  1036  *	stops.

  1037  * \li  dParamStopCFM The constraint force mixing (CFM) value used by the

  1038  *	stops. Together with the ERP value this can be used to get spongy or

  1039  *	soft stops.

  1040  *	Note that this is intended for unpowered joints, it does not really

  1041  *	work as expected when a powered joint reaches its limit.

  1042  * \li  dParamSuspensionERP Suspension error reduction parameter (ERP).

  1043  *	Currently this is only implemented on the hinge-2 joint.

  1044  * \li  dParamSuspensionCFM Suspension constraint force mixing (CFM) value.

  1045  *	Currently this is only implemented on the hinge-2 joint.

  1046  *

  1047  * If a particular parameter is not implemented by a given joint, setting it

  1048  * will have no effect.

  1049  * These parameter names can be optionally followed by a digit (2 or 3)

  1050  * to indicate the second or third set of parameters, e.g. for the second axis

  1051  * in a hinge-2 joint, or the third axis in an AMotor joint.

  1052  */

  1053 

  1054 

  1055 /**

  1056  * @brief Create a new joint of the ball type.

  1057  * @ingroup joints

  1058  * @remarks

  1059  * The joint is initially in "limbo" (i.e. it has no effect on the simulation)

  1060  * because it does not connect to any bodies.

  1061  * @param dJointGroupID set to 0 to allocate the joint normally.

  1062  * If it is nonzero the joint is allocated in the given joint group.

  1063  */

  1064 ODE_API IMPORT_C dJointID dJointCreateBall (dWorldID, dJointGroupID);

  1065 

  1066 /**

  1067  * @brief Create a new joint of the hinge type.

  1068  * @ingroup joints

  1069  * @param dJointGroupID set to 0 to allocate the joint normally.

  1070  * If it is nonzero the joint is allocated in the given joint group.

  1071  */

  1072 ODE_API IMPORT_C dJointID dJointCreateHinge (dWorldID, dJointGroupID);

  1073 

  1074 /**

  1075  * @brief Create a new joint of the slider type.

  1076  * @ingroup joints

  1077  * @param dJointGroupID set to 0 to allocate the joint normally.

  1078  * If it is nonzero the joint is allocated in the given joint group.

  1079  */

  1080 ODE_API IMPORT_C dJointID dJointCreateSlider (dWorldID, dJointGroupID);

  1081 

  1082 /**

  1083  * @brief Create a new joint of the contact type.

  1084  * @ingroup joints

  1085  * @param dJointGroupID set to 0 to allocate the joint normally.

  1086  * If it is nonzero the joint is allocated in the given joint group.

  1087  */

  1088 ODE_API IMPORT_C dJointID dJointCreateContact (dWorldID, dJointGroupID, const dContact *);

  1089 

  1090 /**

  1091  * @brief Create a new joint of the hinge2 type.

  1092  * @ingroup joints

  1093  * @param dJointGroupID set to 0 to allocate the joint normally.

  1094  * If it is nonzero the joint is allocated in the given joint group.

  1095  */

  1096 ODE_API IMPORT_C dJointID dJointCreateHinge2 (dWorldID, dJointGroupID);

  1097 

  1098 /**

  1099  * @brief Create a new joint of the universal type.

  1100  * @ingroup joints

  1101  * @param dJointGroupID set to 0 to allocate the joint normally.

  1102  * If it is nonzero the joint is allocated in the given joint group.

  1103  */

  1104 ODE_API IMPORT_C dJointID dJointCreateUniversal (dWorldID, dJointGroupID);

  1105 

  1106 /**

  1107  * @brief Create a new joint of the PR (Prismatic and Rotoide) type.

  1108  * @ingroup joints

  1109  * @param dJointGroupID set to 0 to allocate the joint normally.

  1110  * If it is nonzero the joint is allocated in the given joint group.

  1111  */

  1112 ODE_API IMPORT_C dJointID dJointCreatePR (dWorldID, dJointGroupID);

  1113 

  1114 /**

  1115  * @brief Create a new joint of the fixed type.

  1116  * @ingroup joints

  1117  * @param dJointGroupID set to 0 to allocate the joint normally.

  1118  * If it is nonzero the joint is allocated in the given joint group.

  1119  */

  1120 ODE_API IMPORT_C dJointID dJointCreateFixed (dWorldID, dJointGroupID);

  1121 

  1122 ODE_API IMPORT_C dJointID dJointCreateNull (dWorldID, dJointGroupID);

  1123 

  1124 /**

  1125  * @brief Create a new joint of the A-motor type.

  1126  * @ingroup joints

  1127  * @param dJointGroupID set to 0 to allocate the joint normally.

  1128  * If it is nonzero the joint is allocated in the given joint group.

  1129  */

  1130 ODE_API IMPORT_C dJointID dJointCreateAMotor (dWorldID, dJointGroupID);

  1131 

  1132 /**

  1133  * @brief Create a new joint of the L-motor type.

  1134  * @ingroup joints

  1135  * @param dJointGroupID set to 0 to allocate the joint normally.