2 * \page dynamics-initialization Initializing the Simulation
3 * \section dynamics-prerequisites Dynamics prerequisites
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
10 * Dynamics support: yes
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.
15 * \section initializing-world Initializing the World
17 * The simulation is encapsulated and controlled by a instance of a Dali::DynamicsWorld object.\n
19 * // DynamicsWorld initialisation code
20 * Dali::DynamicsWorldConfig worldConfig( Dali::DynamicsWorldConfig::New() );
21 * Dali::Stage::GetCurrent().InitializeDynamics( worldConfig );
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.
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 );
38 * \section initializing-world-advanced Advanced Initialization
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.
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);
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>
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);
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>
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 );
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>
87 * // Set gravity to apply a force on the negative Y axis
88 * dynamicsWorld.SetGravity( Vector3( 0.0f, -10.0f, 0.0f ) );
94 * <li>Dali::DynamicsWorldConfig</li>
95 * <li>Dali::DynamicsWorld</li>
96 * <li>Dali::Stage::InitializeDynamics</li>