1 /* 2 * Copyright (c) 2006-2009 Erin Catto http://www.box2d.org 3 * 4 * This software is provided 'as-is', without any express or implied 5 * warranty. In no event will the authors be held liable for any damages 6 * arising from the use of this software. 7 * Permission is granted to anyone to use this software for any purpose, 8 * including commercial applications, and to alter it and redistribute it 9 * freely, subject to the following restrictions: 10 * 1. The origin of this software must not be misrepresented; you must not 11 * claim that you wrote the original software. If you use this software 12 * in a product, an acknowledgment in the product documentation would be 13 * appreciated but is not required. 14 * 2. Altered source versions must be plainly marked as such, and must not be 15 * misrepresented as being the original software. 16 * 3. This notice may not be removed or altered from any source distribution. 17 */ 18 19 #ifndef B2_WORLD_CALLBACKS_H 20 #define B2_WORLD_CALLBACKS_H 21 22 #include <Box2D/Common/b2Settings.h> 23 24 struct b2Vec2; 25 struct b2Transform; 26 class b2Fixture; 27 class b2Body; 28 class b2Joint; 29 class b2Contact; 30 struct b2ContactResult; 31 struct b2Manifold; 32 33 /// Joints and fixtures are destroyed when their associated 34 /// body is destroyed. Implement this listener so that you 35 /// may nullify references to these joints and shapes. 36 class b2DestructionListener 37 { 38 public: ~b2DestructionListener()39 virtual ~b2DestructionListener() {} 40 41 /// Called when any joint is about to be destroyed due 42 /// to the destruction of one of its attached bodies. 43 virtual void SayGoodbye(b2Joint* joint) = 0; 44 45 /// Called when any fixture is about to be destroyed due 46 /// to the destruction of its parent body. 47 virtual void SayGoodbye(b2Fixture* fixture) = 0; 48 }; 49 50 /// Implement this class to provide collision filtering. In other words, you can implement 51 /// this class if you want finer control over contact creation. 52 class b2ContactFilter 53 { 54 public: ~b2ContactFilter()55 virtual ~b2ContactFilter() {} 56 57 /// Return true if contact calculations should be performed between these two shapes. 58 /// @warning for performance reasons this is only called when the AABBs begin to overlap. 59 virtual bool ShouldCollide(b2Fixture* fixtureA, b2Fixture* fixtureB); 60 }; 61 62 /// Contact impulses for reporting. Impulses are used instead of forces because 63 /// sub-step forces may approach infinity for rigid body collisions. These 64 /// match up one-to-one with the contact points in b2Manifold. 65 struct b2ContactImpulse 66 { 67 float32 normalImpulses[b2_maxManifoldPoints]; 68 float32 tangentImpulses[b2_maxManifoldPoints]; 69 int32 count; 70 }; 71 72 /// Implement this class to get contact information. You can use these results for 73 /// things like sounds and game logic. You can also get contact results by 74 /// traversing the contact lists after the time step. However, you might miss 75 /// some contacts because continuous physics leads to sub-stepping. 76 /// Additionally you may receive multiple callbacks for the same contact in a 77 /// single time step. 78 /// You should strive to make your callbacks efficient because there may be 79 /// many callbacks per time step. 80 /// @warning You cannot create/destroy Box2D entities inside these callbacks. 81 class b2ContactListener 82 { 83 public: ~b2ContactListener()84 virtual ~b2ContactListener() {} 85 86 /// Called when two fixtures begin to touch. BeginContact(b2Contact * contact)87 virtual void BeginContact(b2Contact* contact) { B2_NOT_USED(contact); } 88 89 /// Called when two fixtures cease to touch. EndContact(b2Contact * contact)90 virtual void EndContact(b2Contact* contact) { B2_NOT_USED(contact); } 91 92 /// This is called after a contact is updated. This allows you to inspect a 93 /// contact before it goes to the solver. If you are careful, you can modify the 94 /// contact manifold (e.g. disable contact). 95 /// A copy of the old manifold is provided so that you can detect changes. 96 /// Note: this is called only for awake bodies. 97 /// Note: this is called even when the number of contact points is zero. 98 /// Note: this is not called for sensors. 99 /// Note: if you set the number of contact points to zero, you will not 100 /// get an EndContact callback. However, you may get a BeginContact callback 101 /// the next step. PreSolve(b2Contact * contact,const b2Manifold * oldManifold)102 virtual void PreSolve(b2Contact* contact, const b2Manifold* oldManifold) 103 { 104 B2_NOT_USED(contact); 105 B2_NOT_USED(oldManifold); 106 } 107 108 /// This lets you inspect a contact after the solver is finished. This is useful 109 /// for inspecting impulses. 110 /// Note: the contact manifold does not include time of impact impulses, which can be 111 /// arbitrarily large if the sub-step is small. Hence the impulse is provided explicitly 112 /// in a separate data structure. 113 /// Note: this is only called for contacts that are touching, solid, and awake. PostSolve(b2Contact * contact,const b2ContactImpulse * impulse)114 virtual void PostSolve(b2Contact* contact, const b2ContactImpulse* impulse) 115 { 116 B2_NOT_USED(contact); 117 B2_NOT_USED(impulse); 118 } 119 }; 120 121 /// Callback class for AABB queries. 122 /// See b2World::Query 123 class b2QueryCallback 124 { 125 public: ~b2QueryCallback()126 virtual ~b2QueryCallback() {} 127 128 /// Called for each fixture found in the query AABB. 129 /// @return false to terminate the query. 130 virtual bool ReportFixture(b2Fixture* fixture) = 0; 131 }; 132 133 /// Callback class for ray casts. 134 /// See b2World::RayCast 135 class b2RayCastCallback 136 { 137 public: ~b2RayCastCallback()138 virtual ~b2RayCastCallback() {} 139 140 /// Called for each fixture found in the query. You control how the ray cast 141 /// proceeds by returning a float: 142 /// return -1: ignore this fixture and continue 143 /// return 0: terminate the ray cast 144 /// return fraction: clip the ray to this point 145 /// return 1: don't clip the ray and continue 146 /// @param fixture the fixture hit by the ray 147 /// @param point the point of initial intersection 148 /// @param normal the normal vector at the point of intersection 149 /// @return -1 to filter, 0 to terminate, fraction to clip the ray for 150 /// closest hit, 1 to continue 151 virtual float32 ReportFixture( b2Fixture* fixture, const b2Vec2& point, 152 const b2Vec2& normal, float32 fraction) = 0; 153 }; 154 155 #endif 156