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

   1 /**
   2  * \page dynamics-initialization Initializing the Simulation
   3  * \section dynamics-prerequisites Dynamics prerequisites
   4  * <p>
   5  * In order to reduce binary size on devices, by default Dali core is built without Dynamics support. \n
   6  * This can be enabled by adding the --enable-debug option to configure. The configure command should output this: \n
   7  * \code
   8  * Configuration
   9  * -------------
  10  *  Dynamics support:                 yes
  11  * \endcode
  12  * <p>In addition to rebuilding Dali, a physics plugin (e.g. bullet, havok) should be installed on the target device.
  13  * Dali adaptor provides the bullet plugin e.g. install dali-adaptor-dali-bullet-plugin-X.armv7l.rpm.
  14  *
  15  * \section initializing-world Initializing the World
  16  * <p>
  17  * The simulation is encapsulated and controlled by a instance of a Dali::DynamicsWorld object.\n
  18  * \code
  19  * // DynamicsWorld initialisation code
  20  * Dali::DynamicsWorldConfig worldConfig( Dali::DynamicsWorldConfig::New() );
  21  * Dali::Stage::GetCurrent().InitializeDynamics( worldConfig );
  22  * \endcode
  23  * <p>If the DynamicsWorld handle empty, then a prerequisite is missing (see above).
  24  * Use a Dali::DynamicsWorldConfig object to specify options for the type of simulation required.\n
  25  * Dali::DynamicsWorldConfig::RIGID supports rigid body dynamics only, while Dali::DynamicsWorldConfig::SOFT supports
  26  * both rigid and soft body dynamics. Rigid body dynamics uses less CPU than soft body dynamics and is simpler to set up.
  27  * \code
  28  * // DynamicsWorld initialisation code
  29  * Dali::DynamicsWorldConfig worldConfig( Dali::DynamicsWorldConfig::New() );
  30  * // Choose a rigid body capable simulation
  31  * worldConfig.SetType( Dali::DynamicsWorldConfig::RIGID );
  32  * // or a soft and rigid body simulation
  33  * worldConfig.SetType( Dali::DynamicsWorldConfig::SOFT );
  34  * // Request Dali::Stage to create an instance of the DynamicsWorld
  35  * Dali::Stage::GetCurrent().InitializeDynamics( worldConfig );
  36  * \endcode
  37  *
  38  * \section initializing-world-advanced Advanced Initialization
  39  * <h3>Units</h3>
  40  * <p>All distance units in the simulation are based on meters, so positioning an actor at (0, -500, -1000)
  41  * will position it 0.5km in the air and 1km away from the camera.\n So if the actor was to fall under
  42  * the control of gravity it will seem to fall in slow motion. To counteract this the simulation units can
  43  * be modified using Dali::DynamicsWorldConfig::SetUnit. The default value is set to 0.01 to change the
  44  * simulation units to centimeters.
  45  * </p>
  46  * \code
  47  * // change simulation back to meters
  48  * worldConfig.SetUnit(1.0f);
  49  * // or change simulation unit to millimeters
  50  * worldConfig.SetUnit(1.0f/1000.0f);
  51  * \endcode
  52  *
  53  * <h3>Simulation update ticks</h3>
  54  * <p>The application developer can set the number of simulation time steps / DALi update tick using
  55  * Dali::DynamicsWorldConfig::SetSimulationSubSteps.\n
  56  * Use this to advance the simulation in smaller time steps, thus gaining a more accurate
  57  * simulation for collision detection.\n
  58  * Using this API may adversely affect performance, as the dynamics simulation is performing many more
  59  * calculations each DAli tick than normal.</p>
  60  * \code
  61  * // Assume DAli is updating at 60Hz (16.667ms / update)
  62  * //Setting subSteps to 1 will update the simulation once per DALi update.
  63  * worldConfig.SetSimulationSubSteps(1);
  64  * //Setting subSteps to 4 will perform 4 simulation updates per DALi update each with a time step of Approx 4.2ms.
  65  * worldConfig.SetSimulationSubSteps(1);
  66  * \endcode
  67  * \section manipulating-world Using the World
  68  * <h3>The Dynamics Simulation Root Actor</h3>
  69  * <p>To manipulate the world within the scene-graph it must be connected to a Dali::Actor.\n
  70  * All Rigid or Soft bodies that will be simulated must each be connected to a Dali::Actor which is a
  71  * direct child of the dynamics root actor.</p>
  72  * \code
  73  * // Create an actor to represent our view of the simulation
  74  * Dali::Actor dynamicsRootActor( Dali::Actor::New() );
  75  * // retrieve a handle to the DynamicsWorld object initialized previously
  76  * Dali::DynamicsWorld dynamicsWorld( Dali::Stage::GetCurrent().GetDynamicsWorld() );
  77  * // Connect the Dali::DynamicsWorld and the Dali::Actor
  78  * dynamicsWorld.SetRootActor( dynamicsRootActor );
  79  * // Add root actor to Dali::Stage
  80  * Dali::Stage::GetCurrent().Add( dynamicsRootActor );
  81  * \endcode
  82  * <h3>Gravity</h3>
  83  * <p>The gravity applicable to the entire simulation can be set through Dali::DynamicsWorld::SetGravity.\n
  84  * The gravity will apply a constant force on all Dali::DynamicsBody objects added to the world which have a
  85  * non zero mass and are not flagged as kinematic.</p>
  86  * \code
  87  * // Set gravity to apply a force on the negative Y axis
  88  * dynamicsWorld.SetGravity( Vector3( 0.0f, -10.0f, 0.0f ) );
  89  * \endcode
  90  * <hr>
  91  * <p>See also
  92 * <p>See
  93  * <ul>
  94  *  <li>Dali::DynamicsWorldConfig</li>
  95  *  <li>Dali::DynamicsWorld</li>
  96  *  <li>Dali::Stage::InitializeDynamics</li>
  97  * </ul>
  98  * </p>
  99  *
 100  */
 101