Merge "Change ItemFactory destructor to be not pure virtual" into tizen
[platform/core/uifw/dali-toolkit.git] / docs / content / programming-guide / dynamics-bodies.h
1 /**
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
8  *
9  * \section create-body Creating a body
10  * <p>
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.
13  * \code
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 );
21  *
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() );
28  * \endcode
29  *
30  * \section create-body-advanced Specifying options
31  * <h4>Mass</h4>
32  * Use Dali::DynamicsBodyConfig::SetMass to specify the mass of the body [default: 1].
33  * <h4>Elasticity</h4>
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 &apos;bounciness&apos;.
36  * <h4>Damping</h4>
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
39  * <h4>Friction</h4>
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>
46  * <h4>Stiffness</h4>
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>
59  * \code
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 );
73  *
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 );
79  *
80  * // add to the simulation
81  * dynamicsRootActor.Add( actor );
82  * \endcode
83  * <h4>Create a soft body with advanced options</h4>
84  * \code
85  * // Create a unit mesh with 25 vertices
86  * Dali::Mesh mesh( Dali::Mesh::NewPlane(1.0f, 1.0f, 5, 5) );
87  *
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 );
97  *
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 );
103  *
104  * // add to the simulation
105  * dynamicsRootActor.Add( actor );
106  * \endcode
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
115  * away.
116  * \code
117  * ...
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 );
129  * animation.Play();
130  * \endcode
131  * <hr>
132  * <p>See also
133  * <ul>
134  *  <li>Dali::DynamicsBodyConfig</li>
135  *  <li>Dali::Actor::EnableDynamics</li>
136  *  <li>\link dynamics-initialization DynamicsWorld Initialization and Usage\endlink</li>
137  * </ul>
138  * </p>
139  */
140