docs/content/programming-guide/dynamics-joints.h

   1 /**
   2  * \page dynamics-joints Joints
   3  * A Dali::DynamicsJoint represents a connection (or link) between a Dali::DynamicsBody pair.
   4  * A Joint can optionally allow \ref linear "linear motion" and/or \ref angular "angular rotation" around its origin on one or more axis, and
   5  * can have a \ref motors "motor" or \ref springs "spring" enabled on those axis.
   6  * \image html dynamics/dynamics-joint2.png
   7  * \section create-joint Creating a joint
   8  * <p>Each Dali::DynamicsJoint is created by a Dali::Actor through its Dali::Actor::AddDynamicsJoint method.\n
   9  * This method takes two parameters\n
  10  * 1. The other Dali::Actor in the joint relationship.\n
  11  * 2. A Dali::Vector3 relative offset from the owning Dali::Actor's current position.\n
  12  * A joint is active in the simulation when both of the actors are connected to the Stage via the Dali::Actor
  13  * set with Dali::DynamicsWorld::SetRootActorDynamics.
  14  * </p>
  15  * <h3>A code example creating two actors connected by a joint</h3>
  16  * \code
  17  * // create an actor to represent a rigid body
  18  * Dali::Actor actor1( Dali::Actor::New() );
  19  * // Enable dynamics for the actor, creating a rigid body with default configuration
  20  * actor1.EnableDynamics( Dali::DynamicsBodyConfig::New() );
  21  * actor1.SetPosition( Vector3( 0, 0, 0 ) );
  22  * // create an actor to represent a second rigid body
  23  * Dali::Actor actor2( Dali::Actor::New() );
  24  * actor1.SetPosition( Vector3( 100, 0, 0 ) );
  25  * // Enable dynamics for the actor, creating a rigid body with default configuration
  26  * actor2.EnableDynamics( Dali::DynamicsBodyConfig::New() );
  27  * // create the joint
  28  * Vector3 relativeOffset( 25, 0, 0 );
  29  * actor1.AddDynamicsJoint( actor2, relativeOffset );
  30  * \endcode
  31  * The joint is 25 units to the right of actor1 and 75 units to the left of actor2. If
  32  * either actor is moved the joint will follow pulling the other actor with it.
  33  * \section linear Linear Limits
  34  * \image html dynamics/dynamics-joint.png "A joint allowing linear motion on the Y Axis"
  35  * Limits control how much translation is allowed relative to the joints origin point, use Dali::DynamicsJoint::SetLinearLimit
  36  * to set linear limits.
  37  * \code
  38  * ...
  39  * actor1.AddDynamicsJoint( actor2, Vector3(0, 0, 0) );
  40  * DynamicsJoint joint( actor1.GetDynamicsJoint(actor2) );
  41  *
  42  * // Allow translation from the joint's origin along the X axis of +/- 50 units
  43  * joint.SetLinearLimit( Dali::DynamicsJoint::LINEAR_X, -50, 50);
  44  * \endcode
  45  * \section angular Angular Limits
  46  * Limits control how much rotation is allowed around the joint's origin point, use Dali::DynamicsJoint::SetAngularLimit
  47  * to set angular limits.
  48  * \code
  49  * ...
  50  * actor1.AddDynamicsJoint( actor2, Vector3(0, 0, 0) );
  51  * DynamicsJoint joint( actor1.GetDynamicsJoint(actor2) );
  52  *
  53  * // Allow rotation around the joint's origin on the Z axis of - 45 degrees and +90 degrees
  54  * joint.SetAngularLimit( Dali::DynamicsJoint::ANGULAR_Z, -Dali::Degree(45), Dali::Degree(90) );
  55  * \endcode
  56  * \section motors Motors
  57  * Motors apply a force along a given axis towards the lower or upper limit set on that axis.\n
  58  * Use Dali::DynamicsJoint::EnableMotor to enable/disable a motor.\n
  59  * The torque of the motor can be set with Dali::DynamicsJoint::SetMotorForce and the velocity
  60  * with Dali::DynamicsJoint::SetMotorVelocity.
  61  * \code
  62  * ...
  63  * actor1.AddDynamicsJoint( actor2, Vector3(0, 0, 0) );
  64  * DynamicsJoint joint( actor1.GetDynamicsJoint(actor2) );
  65  *
  66  * // allow angular rotation on the Z axis
  67  * joint.SetAngularLimit(Dali::DynamicsJoint::ANGULAR_Z, -Dali::Degree(90), Dali::Degree(90));
  68  * // enable the Z axis angular motor
  69  * joint.EnableMotor(Dali::DynamicsJoint::ANGULAR_Z, true);
  70  * // set the motor torque
  71  * joint.SetMotorForce(Dali::DynamicsJoint::ANGULAR_Z, 0.5f);
  72  * // set the motor velocity (acts towards lower limit)
  73  * joint.SetMotorVelocity(Dali::DynamicsJoint::ANGULAR_Z, -10.0f);
  74  * \endcode
  75  * \section springs Springs
  76  * Springs apply a force to keep the Dali::DynamicsJoint origin at the spring's center point.
  77  * A spring can be enabled for a given axis using Dali::DynamicsJoint::EnableSpring.\n
  78  * The center point is set as a ratio between the lower and upper limits on the given axis using
  79  * Dali::DynamicsJoint::SetSpringCenterPoint.\n
  80  * The magnitude of the spring's centering force can be set with Dali::DynamicsJoint::SetSpringStiffness.\n
  81  * Dali::DynamicsJoint::SetSpringDamping can be used to limit the amount of overshoot and oscillations
  82  * of the spring as it settles at its center point.
  83  * \code
  84  * ...
  85  * actor1.AddDynamicsJoint( actor2, Vector3(0, 0, 0) );
  86  * DynamicsJoint joint( actor1.GetDynamicsJoint(actor2) );
  87  *
  88  * // allow linear motion on Y axis
  89  * joint.SetLinearLimit(Dali::DynamicsJoint::LINEAR_Y, -50, 50);
  90  * // enable the Y axis linear spring
  91  * joint.EnableSpring(Dali::DynamicsJoint::LINEAR_Y, true);
  92  * // set the center point of the spring at -40 ( 10% of the limits set )
  93  * joint.SetSpringCenterPoint(Dali::DynamicsJoint::LINEAR_Y, 0.1f);
  94  * // set the springs stiffness or centering force
  95  * joint.SetSpringStiffness(Dali::DynamicsJoint::LINEAR_Y, 40.0f);
  96  * // allow more oscillations before the spring comes to reset
  97  * joint.SetSpringDamping(Dali::DynamicsJoint::LINEAR_Y, 0.1f);
  98  * \endcode
  99  * <hr>
 100  * <p>See also
 101  * <ul>
 102  *  <li>Dali::DynamicsJoint</li>
 103  *  <li>Dali::Actor::AddDynamicsJoint</li>
 104  *  <li>Dali::Actor::GetDynamicsJoint</li>
 105  * </ul>
 106  * </p>
 107  */
 108