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

   1 /**
   2  * \page dynamics-collisions Collisions
   3  * \section collision-detection Collision Detection
   4  * <p>
   5  * Collision detection is automatic and occurs between all Dali::DynamicsBody objects in the simulation.@n
   6  * To respond to a detected collisions, the application developer can connect to a signal provided by
   7  * a Dali::DynamicsWorld object.
   8  * \code
   9  * ...
  10  *
  11  * // DynamicsWorld initialization code
  12  *
  13  * ...
  14  *
  15  * // Connect a signal handler to the signal
  16  * Dali::DynamicsWorld theWorld( Stage::GetCurrent().GetDynamicsWorld() );
  17  * theWorld.SignalCollision().Connect( this, &myClass::OnDynamicsCollision );
  18  *
  19  * ...
  20  *
  21  * // Implement a signal handler
  22  * void myClass::OnDynamicsCollision( Dali::DynamicsWorld world, Dali::DynamicsCollision collisionData )
  23  * {
  24  *   std::cout << "Collision between "
  25  *             << collisionData.GetActorA().GetName() << " and "
  26  *             << collisionData.GetActorB().GetName() << " ";
  27  *
  28  *   if( collisionData.GetImpactForce() != 0.0f )
  29  *   {
  30  *     std::cout << "detected (impact force: " << collisionData.GetImpactForce() << " )";
  31  *   }
  32  *   else
  33  *   {
  34  *     std::cout << "ended";
  35  *   }
  36  *   std::cout << std::endl;
  37  * }
  38  * \endcode
  39  *
  40  * <hr>
  41  * \section collision-filtering Collision Filtering
  42  *
  43  * <p>
  44  * When a large number of Dali::DynamicsBody objects are added to the simulation, collision detection can become a
  45  * significant performance drain, where every possible pairing of objects needs to be checked for collisions.</p>
  46  * <p>You can significantly reduce the number of pairs considered for collision detection by using a collision filter.</p>
  47  * <p>Each Dali::DynamicsBody can belong to a user defined collision filter group and have a user defined collision filter mask.<p>
  48  * <p>A Dali::DynamicsBody pair are considered for collision detection if one or more bits in the filter group from each Dali::DynamicsBody
  49  * matches one or more bits in the filter mask of the other Dali::DynamicsBody.
  50  * </p>
  51  * <center><table border="1">
  52  * <caption>Truth table</caption>
  53  * <tr align="center">
  54  * <th>&nbsp;P&nbsp;</th>
  55  * <th>&nbsp;Q&nbsp;</th>
  56  * <th>tested for collision?</th>
  57  * </tr>
  58  * <tr align="center">
  59  * <td>0</th>
  60  * <td>0</th>
  61  * <td>no</th>
  62  * </tr>
  63  * <tr align="center">
  64  * <td>0</th>
  65  * <td>1</th>
  66  * <td>no</th>
  67  * </tr>
  68  * <tr align="center">
  69  * <td>1</th>
  70  * <td>0</th>
  71  * <td>no</th>
  72  * </tr>
  73  * <tr align="center">
  74  * <td>1</th>
  75  * <td>1</th>
  76  * <td>yes</th>
  77  * </tr>
  78  * </table></center>
  79  * <p>
  80  * where <b>P</b> = bitwise AND of the collision group from the first Dali::DynamicsBody and the collision mask from the second Dali::DynamicsBody\n
  81  * and   <b>Q</b> = bitwise AND of the collision group from the second Dali::DynamicsBody and the collision mask from the first Dali::DynamicsBody.
  82  * </p><br>
  83  * <p>
  84  * <b>Pseudo code for the filter check.</b>
  85  * \code
  86  * const bool canCollide( (  firstBody->GetCollisionGroup() & secondBody->GetCollisionMask() &&
  87  *                        ( secondBody->GetCollisionGroup() &  firstBody->GetCollisionMask() );
  88  * \endcode
  89  * </p>
  90  * <h3 class="pg">Code example - Illustrating how to create multiple filter groups and masks.</h3>
  91  * \code
  92  * // Define some collision groups
  93  * const short int group0( 1 << 1 );
  94  * const short int group1( 1 << 2 );
  95  * const short int group2( 1 << 3 );
  96  *
  97  * // Create some Dali::DynamicsBodyConfig objects
  98  * Dali::DynamicsBodyConfig bodyConfig0( Dali::DynamicsBodyConfig::New() );
  99  * Dali::DynamicsBodyConfig bodyConfig1( Dali::DynamicsBodyConfig::New() );
 100  * Dali::DynamicsBodyConfig bodyConfig2( Dali::DynamicsBodyConfig::New() );
 101  *
 102  * // Assign the collision filters to the configurations
 103  * bodyConfig0->SetCollisionGroup(group0);
 104  * bodyConfig0->SetCollisionMask( group1 | group2 );
 105  * bodyConfig1->SetCollisionGroup(group1);
 106  * bodyConfig1->SetCollisionMask(group0);
 107  * bodyConfig2->SetCollisionGroup(group2);
 108  * bodyConfig2->SetCollisionMask(group0 | group2);
 109  * \endcode
 110  * <p>
 111  * Collision detection is \b enabled between Dali::DynamicsBody pairs of...
 112  * <ul>
 113  *  <li>group0 and group1 objects.</li>
 114  *  <li>group0 and group2 objects.</li>
 115  *  <li>group2 objects.</li>
 116  * </ul>
 117  * Collision detection is \b disabled between Dali::DynamicsBody pairs of...
 118  * <ul>
 119  *  <li>group0 objects.</li>
 120  *  <li>group1 objects.</li>
 121  *  <li>group1 and group2 objects.</li>
 122  * </ul>
 123  * </p>
 124  *
 125  * See
 126  * <ul>
 127  *  <li>Dali::DynamicsWorld::SignalCollision</li>
 128  *  <li>Dali::DynamicsCollision</li>
 129  *  <li>\ref Dali::DynamicsBodyConfig::SetCollisionGroup - to set the collision group</li>
 130  *  <li>\ref Dali::DynamicsBodyConfig::SetCollisionMask - to set the collision mask</li>
 131  * </ul>
 132  */
 133