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.
15 * <h3>A code example creating two actors connected by a joint</h3>
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() );
28 * Vector3 relativeOffset( 25, 0, 0 );
29 * actor1.AddDynamicsJoint( actor2, relativeOffset );
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.
39 * actor1.AddDynamicsJoint( actor2, Vector3(0, 0, 0) );
40 * DynamicsJoint joint( actor1.GetDynamicsJoint(actor2) );
42 * // Allow translation from the joint's origin along the X axis of +/- 50 units
43 * joint.SetLinearLimit( Dali::DynamicsJoint::LINEAR_X, -50, 50);
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.
50 * actor1.AddDynamicsJoint( actor2, Vector3(0, 0, 0) );
51 * DynamicsJoint joint( actor1.GetDynamicsJoint(actor2) );
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) );
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.
63 * actor1.AddDynamicsJoint( actor2, Vector3(0, 0, 0) );
64 * DynamicsJoint joint( actor1.GetDynamicsJoint(actor2) );
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);
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.
85 * actor1.AddDynamicsJoint( actor2, Vector3(0, 0, 0) );
86 * DynamicsJoint joint( actor1.GetDynamicsJoint(actor2) );
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);
102 * <li>Dali::DynamicsJoint</li>
103 * <li>Dali::Actor::AddDynamicsJoint</li>
104 * <li>Dali::Actor::GetDynamicsJoint</li>