/*************************************************************************

 *                                                                       *

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

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

 *                                                                       *

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

 * modify it under the terms of EITHER:                                  *

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

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

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

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

 *       file LICENSE.TXT.                                               *

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

 *       the file LICENSE-BSD.TXT.                                       *

 *                                                                       *

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

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

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

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

 *                                                                       *

 *************************************************************************/

#ifndef _ODE_OBJECTS_H_

#define _ODE_OBJECTS_H_

#include <ode/common.h>

#include <ode/mass.h>

#include <ode/contact.h>

#ifdef __cplusplus

extern "C" {

#endif

/**

 * @defgroup world World

 *

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

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

 * different worlds can not collide.

 *

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

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

 * Most applications will only need one world.

 */

/**

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

 * @return an identifier

 * @ingroup world

 */

ODE_API IMPORT_C dWorldID dWorldCreate(void);

/**

 * @brief Destroy a world and everything in it.

 *

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

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

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

 * @ingroup world

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

 */

ODE_API IMPORT_C void dWorldDestroy (dWorldID world);

/**

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

 *

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

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

 *

 * @ingroup world

 */

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

/**

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

 * @ingroup world

 */

ODE_API IMPORT_C void dWorldGetGravity (dWorldID, dVector3 gravity);

/**

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

 * correction is performed in each time step.

 * @ingroup world

 * @param dWorldID the identifier of the world.

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

 */

ODE_API IMPORT_C void dWorldSetERP (dWorldID, dReal erp);

/**

 * @brief Get the error reduction parameter.

 * @ingroup world

 * @return ERP value

 */

ODE_API IMPORT_C dReal dWorldGetERP (dWorldID);

/**

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

 * @ingroup world

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

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

 * if double precision is being used.

 */

ODE_API IMPORT_C void dWorldSetCFM (dWorldID, dReal cfm);

/**

 * @brief Get the constraint force mixing value.

 * @ingroup world

 * @return CFM value

 */

ODE_API IMPORT_C dReal dWorldGetCFM (dWorldID);

/**

 * @brief Step the world.

 *

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

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

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

 * but this is currently the most accurate method.

 * @ingroup world

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

 */

ODE_API IMPORT_C void dWorldStep (dWorldID, dReal stepsize);

/**

 * @brief Converts an impulse to a force.

 * @ingroup world

 * @remarks

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

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

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

 * BodyAdd... function.

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

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

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

 * computation may depend on integrator parameters that are set as

 * properties of the world.

 */

ODE_API IMPORT_C void dWorldImpulseToForce

(

  dWorldID, dReal stepsize,

  dReal ix, dReal iy, dReal iz, dVector3 force

);

/**

 * @brief Step the world.

 * @ingroup world

 * @remarks

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

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

 * rows N is the number of iterations.

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

 * but it is less accurate.

 * @remarks

 * QuickStep is great for stacks of objects especially when the

 * auto-disable feature is used as well.

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

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

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

 * sitting on the ground may be near-singular.

 * @remarks

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

 * \li Increase CFM.

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

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

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

 * \li Use contact slip if appropriate

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

 *     legged creatures).

 * \li Don't use excessive motor strength.

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

 *

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

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

 */

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

/**

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

 *        step.

 * @ingroup world

 * @remarks

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

 * longer to compute.

 * @param num The default is 20 iterations.

 */

ODE_API IMPORT_C void dWorldSetQuickStepNumIterations (dWorldID, int num);

/**

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

 *        step.

 * @ingroup world

 * @return nr of iterations

 */

ODE_API IMPORT_C int dWorldGetQuickStepNumIterations (dWorldID);

/**

 * @brief Set the SOR over-relaxation parameter

 * @ingroup world

 * @param over_relaxation value to use by SOR

 */

ODE_API IMPORT_C void dWorldSetQuickStepW (dWorldID, dReal over_relaxation);

/**

 * @brief Get the SOR over-relaxation parameter

 * @ingroup world

 * @returns the over-relaxation setting

 */

ODE_API IMPORT_C dReal dWorldGetQuickStepW (dWorldID);

/* World contact parameter functions */

/**

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

 * to generate.

 * @ingroup world

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

 * @remarks

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

 */

ODE_API IMPORT_C void dWorldSetContactMaxCorrectingVel (dWorldID, dReal vel);

/**

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

 * to generated.

 * @ingroup world

 */

ODE_API IMPORT_C dReal dWorldGetContactMaxCorrectingVel (dWorldID);

/**

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

 * @ingroup world

 * @remarks

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

 * depth before coming to rest.

 * @param depth The default value is zero.

 * @remarks

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

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

 */

ODE_API IMPORT_C void dWorldSetContactSurfaceLayer (dWorldID, dReal depth);

/**

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

 * @ingroup world

 * @returns the depth

 */

ODE_API IMPORT_C dReal dWorldGetContactSurfaceLayer (dWorldID);

/* StepFast1 functions */

/**

 * @brief Step the world using the StepFast1 algorithm.

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

 * @param maxiterations The number of iterations to perform.

 * @ingroup world

 */

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

/**

 * @defgroup disable Automatic Enabling and Disabling

 *

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

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

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

 *

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

 * automatically re-enabled at the next simulation step.

 *

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

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

 * with the auto-disable feature.

 *

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

 * itself when

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

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

 *

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

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

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

 * to zero with 

 *

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

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

 * average samples count.

 *

 * Newly created bodies get these parameters from world.

 */

/**

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

 * @ingroup disable

 */

ODE_API IMPORT_C void dWorldSetAutoEnableDepthSF1(dWorldID, int autoEnableDepth);

/**

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

 * @ingroup disable

 */

ODE_API IMPORT_C int dWorldGetAutoEnableDepthSF1(dWorldID);

/**

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

 * @ingroup disable

 * @return the threshold

 */

ODE_API IMPORT_C dReal dWorldGetAutoDisableLinearThreshold (dWorldID);

/**

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

 * @param linear_threshold default is 0.01

 * @ingroup disable

 */

ODE_API IMPORT_C void  dWorldSetAutoDisableLinearThreshold (dWorldID, dReal linear_threshold);

/**

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

 * @ingroup disable

 * @return the threshold

 */

ODE_API IMPORT_C dReal dWorldGetAutoDisableAngularThreshold (dWorldID);

/**

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

 * @param linear_threshold default is 0.01

 * @ingroup disable

 */

ODE_API IMPORT_C void dWorldSetAutoDisableAngularThreshold (dWorldID, dReal angular_threshold);

/**

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

 * @ingroup disable

 * @return the threshold

 */

ODE_API dReal dWorldGetAutoDisableLinearAverageThreshold (dWorldID);

/**

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

 * @param linear_average_threshold default is 0.01

 * @ingroup disable

 */

ODE_API void  dWorldSetAutoDisableLinearAverageThreshold (dWorldID, dReal linear_average_threshold);

/**

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

 * @ingroup disable

 * @return the threshold

 */

ODE_API dReal dWorldGetAutoDisableAngularAverageThreshold (dWorldID);

/**

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

 * @param linear_average_threshold default is 0.01

 * @ingroup disable

 */

ODE_API void dWorldSetAutoDisableAngularAverageThreshold (dWorldID, dReal angular_average_threshold);

/**

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

 * @ingroup disable

 * @return number of samples used

 */

ODE_API IMPORT_C int dWorldGetAutoDisableAverageSamplesCount (dWorldID);

/**

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

 * @ingroup disable

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

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

 */

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

/**

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

 * @ingroup disable

 * @return nr of steps

 */

ODE_API IMPORT_C int dWorldGetAutoDisableSteps (dWorldID);

/**

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

 * @ingroup disable

 * @param steps default is 10

 */

ODE_API IMPORT_C void dWorldSetAutoDisableSteps (dWorldID, int steps);

/**

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

 * @ingroup disable

 * @return nr of seconds

 */

ODE_API IMPORT_C dReal dWorldGetAutoDisableTime (dWorldID);

/**

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

 * @ingroup disable

 * @param time default is 0 seconds

 */

ODE_API IMPORT_C void dWorldSetAutoDisableTime (dWorldID, dReal time);

/**

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

 * @ingroup disable

 * @return 0 or 1

 */

ODE_API IMPORT_C int dWorldGetAutoDisableFlag (dWorldID);

/**

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

 * @ingroup disable

 * @param do_auto_disable default is false.

 */

ODE_API IMPORT_C void dWorldSetAutoDisableFlag (dWorldID, int do_auto_disable);

/**

 * @defgroup bodies Rigid Bodies

 *

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

 * simulation. Some properties change over time:

 *

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

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

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

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

 *      a 3x3 rotation matrix.

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

 *      changes over time.

 *

 * Other body properties are usually constant over time:

 *

 *  @li Mass of the body.

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

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

 *      reference must coincide.

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

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

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

 *

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

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

 * are relative to the global coordinate frame.

 *

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

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

 * about the detailed shape of the body.

 */

/**

 * @brief Get auto disable linear average threshold.

 * @ingroup bodies

 * @return the threshold

 */

ODE_API IMPORT_C dReal dBodyGetAutoDisableLinearThreshold (dBodyID);

/**

 * @brief Set auto disable linear average threshold.

 * @ingroup bodies

 * @return the threshold

 */

ODE_API IMPORT_C void  dBodySetAutoDisableLinearThreshold (dBodyID, dReal linear_average_threshold);

/**

 * @brief Get auto disable angular average threshold.

 * @ingroup bodies

 * @return the threshold

 */

ODE_API IMPORT_C dReal dBodyGetAutoDisableAngularThreshold (dBodyID);

/**

 * @brief Set auto disable angular average threshold.

 * @ingroup bodies

 * @return the threshold

 */

ODE_API IMPORT_C void  dBodySetAutoDisableAngularThreshold (dBodyID, dReal angular_average_threshold);

/**

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

 * @ingroup bodies

 * @return the nr of steps/size.

 */

ODE_API IMPORT_C int dBodyGetAutoDisableAverageSamplesCount (dBodyID);

/**

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

 * @ingroup bodies

 * @param average_samples_count the nr of samples to review.

 */

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

/**

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

 * @ingroup bodies

 * @return the nr of steps

 */

ODE_API IMPORT_C int dBodyGetAutoDisableSteps (dBodyID);

/**

 * @brief Set auto disable steps.

 * @ingroup bodies

 * @param steps the nr of steps.

 */

ODE_API IMPORT_C void dBodySetAutoDisableSteps (dBodyID, int steps);

/**

 * @brief Get auto disable time.

 * @ingroup bodies

 * @return nr of seconds

 */

ODE_API IMPORT_C dReal dBodyGetAutoDisableTime (dBodyID);

/**

 * @brief Set auto disable time.

 * @ingroup bodies