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