2 * \page dynamics-bodies Dynamics - Bodies
3 * A Dali::DynamicsBody can be "Rigid" or "Soft". Rigid bodies require much less processing and should be used
4 * in preference to a soft body.\n
5 * All bodies are controlled by the simulation, the application developer can influence them by setting their
6 * linear or angular velocities, but direct control of their position is not possible until the Dali::DynamicsBody is flagged
7 * as a \ref kinematic-body "kinematic object".\n
9 * \section create-body Creating a body
11 * Each Dali::DynamicsBody is created by an Dali::Actor through its Dali::Actor::EnableDynamics method using a
12 * Dali::DynamicsBodyConfig object to specify options for the Dali::DynamicsBody.
14 * // Initialize and get a handle to the Dali::DynamicsWorld
15 * Dali::DynamicsWorldConfig worldConfig( Dali::DynamicsWorldConfig::New() );
16 * Dali::DynamicsWorld dynamicsWorld( Dali::Stage::GetCurrent().InitializeDynamics( worldConfig ) );
17 * // Create an actor to represent the world
18 * Dali::Actor dynamicsRootActor( Dali::Actor::New() );
19 * dynamicsWorld.SetRootActor( dynamicsRootActor );
20 * Dali::Stage::GetCurrent().Add( dynamicsRootActor );
22 * // create an actor to represent a rigid body
23 * Dali::Actor actor( Dali::Actor::New() );
24 * actor.SetParentOrigin( Dali::ParentOrigin::CENTER );
25 * dynamicsRootActor.Add( actor );
26 * // Enable dynamics for the actor, creating a rigid body with default configuration
27 * actor.EnableDynamics( Dali::DynamicsBodyConfig::New() );
30 * \section create-body-advanced Specifying options
32 * Use Dali::DynamicsBodyConfig::SetMass to specify the mass of the body [default: 1].
34 * Use Dali::DynamicsBodyConfig::SetElasticity to specify the elasticity of the body [default: 0.85].\n
35 * This may also be known as the co-efficient of restitution or 'bounciness'.
37 * Use Dali::DynamicsBodyConfig::SetLinearDamping to specify the linear damping coefficient [default: 0].\n
38 * and Dali::DynamicsBodyConfig::SetAngularDamping to specify the angular damping coefficient [default: 0].\n
40 * Use Dali::DynamicsBodyConfig::SetFriction to specify the friction of the body [default: 0.5].\n
41 * <h4>Collision Filtering</h4>
42 * See \link dynamics-collisions Collision Detection and Filtering \endlink\n\n
43 * Use Dali::DynamicsBodyConfig::SetCollisionGroup to specify the collision filter group.\n
44 * Use Dali::DynamicsBodyConfig::SetCollisionMask to specify the collision filter mask.\n
45 * <h3>Soft body specific options</h3>
47 * Use Dali::DynamicsBodyConfig::SetStiffness to specify the stiffness of the links between the mesh vertices used to
48 * define the soft body. Values clamped between 0 and 1 [default: 1].\n
49 * <h4>Anchor hardness</h4>
50 * Use Dali::DynamicsBodyConfig::SetAnchorHardness to specify the hardness or drift correction applied to anchors.
51 * Values clamped between 0 and 1 [default: 0.7]. Smaller values mean less drift correction.\n
52 * <h4>Conservation</h4>
53 * Use Dali::DynamicsBodyConfig::SetShapeConservation to specify the shape conservation coefficient,
54 * or the magnitude of the force which will attempt to maintain the soft bodies shape (see \ref Dali::DynamicsBody::ConserveShape).\n
55 * Use Dali::DynamicsBodyConfig::SetVolumeConservation to specify the volume conservation coefficient,
56 * or the magnitude of the force which will attempt to maintain the soft bodies volume (see \ref Dali::DynamicsBody::ConserveVolume).
57 * Smaller values mean less conservation.\n
58 * <h4>Create a rigid body with advanced options</h4>
60 * Dali::DynamicsBodyConfig bodyConfig( Dali::DynamicsBodyConfig::New() );
61 * // increase mass from the default
62 * bodyConfig.SetMass( 2.5f );
63 * // set elasticity so that the velocity of the object will be halved after a collision
64 * // (assuming the other body has a mass = 1 and a velocity 0f 0).
65 * bodyConfig.SetElasticity( 0.5f );
66 * // increase the rate at which a bodies linear velocity will decrease
67 * bodyConfig.SetLinearDamping( 0.5f );
68 * // reduce the friction to zero
69 * bodyConfig.SetFriction( 0.0f );
70 * // Ignore all collisions
71 * bodyConfig.SetCollisionGroup( 0 );
72 * bodyConfig.SetCollisionMask( 0 );
74 * // create an actor for the Dali::DynamicsBody
75 * Actor actor( Actor::New() );
76 * actor.SetParentOrigin( Dali::ParentOrigin::CENTER );
77 * // create the Dali::DynamicsBody
78 * actor.EnableDynamics( bodyConfig );
80 * // add to the simulation
81 * dynamicsRootActor.Add( actor );
83 * <h4>Create a soft body with advanced options</h4>
85 * // Create a unit mesh with 25 vertices
86 * Dali::Mesh mesh( Dali::Mesh::NewPlane(1.0f, 1.0f, 5, 5) );
88 * Dali::DynamicsBodyConfig bodyConfig( Dali::DynamicsBodyConfig::New() );
89 * // select a soft body
90 * bodyConfig.SetType( Dali::DynamicsBodyConfig::SOFT );
91 * // set the mesh as the soft body shape
92 * bodyConfig.SetShape( Dali::DynamicsShape::NewMesh( mesh ) );
93 * // decrease the stiffness of the links between the soft body vertices
94 * bodyConfig.SetStiffness( 0.25f );
95 * // Make anchors very loose/weak
96 * bodyConfig.SetAnchorHardness( 0.1f );
98 * // create an actor for the Dali::DynamicsBody
99 * Actor actor( MeshActor::New(mesh) );
100 * actor.SetParentOrigin( Dali::ParentOrigin::CENTER );
101 * // create the Dali::DynamicsBody
102 * actor.EnableDynamics( bodyConfig );
104 * // add to the simulation
105 * dynamicsRootActor.Add( actor );
107 * \image html dynamics/dynamics-soft.png "A soft body (with debug rendering enabled)"
108 * \section kinematic-body Kinematic bodies
109 * A kinematic body is not controlled by the simulation, there is a one-way interaction with other dynamic objects
110 * under control of the simulation, where other objects will be pushed away, but the kinematic object will be unaffected.\n
111 * Kinematic objects can be animated with DALi's \ref animation-example "animation system", each DALi update the simulation will
112 * get the current position of associated DALi actor.\n Use Dali::DynamicsBody::SetKinematic to make a kinematic object.
113 * <h3>Animating a kinematic object</h3>
114 * Other dynamics enabled actors that collide with the kinematic object during the animation will be pushed
118 * // create an actor to represent a rigid body
119 * Dali::Actor actor( Dali::Actor::New() );
120 * dynamicsRootActor.Add( actor );
121 * // Enable dynamics for the actor, creating a rigid body with default configuration
122 * actor.EnableDynamics( Dali::DynamicsBodyConfig::New() );
123 * // get the DynamicsBody handle
124 * DynamicsBody body( actor.GetDynamicsBody() );
125 * body.SetKinematic( true );
126 * // create a second animation to move the actor 100 units to the right
127 * Animation animation( Animation::New( 1 ) );
128 * animation.AnimateBy( Property( actor, Actor::Property::POSITION ), Vector3( 100, 0, 0 ), AlphaFunction::LINEAR );
134 * <li>Dali::DynamicsBodyConfig</li>
135 * <li>Dali::Actor::EnableDynamics</li>
136 * <li>\link dynamics-initialization DynamicsWorld Initialization and Usage\endlink</li>