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
24struct b2Vec2;
25struct b2Transform;
26class b2Fixture;
27class b2Body;
28class b2Joint;
29class b2Contact;
30struct b2ContactResult;
31struct 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.
36class b2DestructionListener
37{
38public:
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.
52class b2ContactFilter
53{
54public:
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.
65struct 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.
81class b2ContactListener
82{
83public:
84 virtual ~b2ContactListener() {}
85
86 /// Called when two fixtures begin to touch.
87 virtual void BeginContact(b2Contact* contact) { B2_NOT_USED(contact); }
88
89 /// Called when two fixtures cease to touch.
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.
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.
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
123class b2QueryCallback
124{
125public:
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
135class b2RayCastCallback
136{
137public:
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