File indexing completed on 2025-08-03 03:50:02

 /*
 * Copyright (c) 2006-2009 Erin Catto http://www.gphysics.com
 *
 * This software is provided 'as-is', without any express or implied
 * warranty.  In no event will the authors be held liable for any damages
 * arising from the use of this software.
 * Permission is granted to anyone to use this software for any purpose,
 * including commercial applications, and to alter it and redistribute it
 * freely, subject to the following restrictions:
 * 1. The origin of this software must not be misrepresented; you must not
 * claim that you wrote the original software. If you use this software
 * in a product, an acknowledgment in the product documentation would be
 * appreciated but is not required.
 * 2. Altered source versions must be plainly marked as such, and must not be
 * misrepresented as being the original software.
 * 3. This notice may not be removed or altered from any source distribution.
 */
 
 #ifndef B2_WORLD_CALLBACKS_H
 #define B2_WORLD_CALLBACKS_H
 
 #include <Box2D/Common/b2Settings.h>
 
 struct b2Vec2;
 struct b2Transform;
 class b2Fixture;
 class b2Joint;
 class b2Contact;
 struct b2ContactResult;
 struct b2Manifold;
 
 /// Joints and fixtures are destroyed when their associated
 /// body is destroyed. Implement this listener so that you
 /// may nullify references to these joints and shapes.
 class b2DestructionListener
 {
 public:
     virtual ~b2DestructionListener() {}
 
     /// Called when any joint is about to be destroyed due
     /// to the destruction of one of its attached bodies.
     virtual void SayGoodbye(b2Joint* joint) = 0;
 
     /// Called when any fixture is about to be destroyed due
     /// to the destruction of its parent body.
     virtual void SayGoodbye(b2Fixture* fixture) = 0;
 };
 
 /// Implement this class to provide collision filtering. In other words, you can implement
 /// this class if you want finer control over contact creation.
 class b2ContactFilter
 {
 public:
     virtual ~b2ContactFilter() {}
 
     /// Return true if contact calculations should be performed between these two shapes.
     /// @warning for performance reasons this is only called when the AABBs begin to overlap.
     virtual bool ShouldCollide(b2Fixture* fixtureA, b2Fixture* fixtureB);
 };
 
 /// Contact impulses for reporting. Impulses are used instead of forces because
 /// sub-step forces may approach infinity for rigid body collisions. These
 /// match up one-to-one with the contact points in b2Manifold.
 struct b2ContactImpulse
 {
     qreal normalImpulses[b2_maxManifoldPoints];
     qreal tangentImpulses[b2_maxManifoldPoints];
 };
 
 /// Implement this class to get contact information. You can use these results for
 /// things like sounds and game logic. You can also get contact results by
 /// traversing the contact lists after the time step. However, you might miss
 /// some contacts because continuous physics leads to sub-stepping.
 /// Additionally you may receive multiple callbacks for the same contact in a
 /// single time step.
 /// You should strive to make your callbacks efficient because there may be
 /// many callbacks per time step.
 /// @warning You cannot create/destroy Box2D entities inside these callbacks.
 class b2ContactListener
 {
 public:
     virtual ~b2ContactListener() {}
 
     /// Called when two fixtures begin to touch.
     virtual void BeginContact(b2Contact* contact) { B2_NOT_USED(contact); }
 
     /// Called when two fixtures cease to touch.
     virtual void EndContact(b2Contact* contact) { B2_NOT_USED(contact); }
 
     /// This is called after a contact is updated. This allows you to inspect a
     /// contact before it goes to the solver. If you are careful, you can modify the
     /// contact manifold (e.g. disable contact).
     /// A copy of the old manifold is provided so that you can detect changes.
     /// Note: this is called only for awake bodies.
     /// Note: this is called even when the number of contact points is zero.
     /// Note: this is not called for sensors.
     /// Note: if you set the number of contact points to zero, you will not
     /// get an EndContact callback. However, you may get a BeginContact callback
     /// the next step.
     virtual void PreSolve(b2Contact* contact, const b2Manifold* oldManifold)
     {
         B2_NOT_USED(contact);
         B2_NOT_USED(oldManifold);
     }
 
     /// This lets you inspect a contact after the solver is finished. This is useful
     /// for inspecting impulses.
     /// Note: the contact manifold does not include time of impact impulses, which can be
     /// arbitrarily large if the sub-step is small. Hence the impulse is provided explicitly
     /// in a separate data structure.
     /// Note: this is only called for contacts that are touching, solid, and awake.
     virtual void PostSolve(b2Contact* contact, const b2ContactImpulse* impulse)
     {
         B2_NOT_USED(contact);
         B2_NOT_USED(impulse);
     }
 };
 
 /// Callback class for AABB queries.
 /// See b2World::Query
 class b2QueryCallback
 {
 public:
     virtual ~b2QueryCallback() {}
 
     /// Called for each fixture found in the query AABB.
     /// @return false to terminate the query.
     virtual bool ReportFixture(b2Fixture* fixture) = 0;
 };
 
 /// Callback class for ray casts.
 /// See b2World::RayCast
 class b2RayCastCallback
 {
 public:
     virtual ~b2RayCastCallback() {}
 
     /// Called for each fixture found in the query. You control how the ray cast
     /// proceeds by returning a float:
     /// return -1: ignore this fixture and continue
     /// return 0: terminate the ray cast
     /// return fraction: clip the ray to this point
     /// return 1: don't clip the ray and continue
     /// @param fixture the fixture hit by the ray
     /// @param point the point of initial intersection
     /// @param normal the normal vector at the point of intersection
     /// @return -1 to filter, 0 to terminate, fraction to clip the ray for
     /// closest hit, 1 to continue
     virtual qreal ReportFixture(    b2Fixture* fixture, const b2Vec2& point,
                                     const b2Vec2& normal, qreal fraction) = 0;
 };
 
 /// Color for debug drawing. Each value has the range [0,1].
 struct b2Color
 {
     b2Color() {}
     b2Color(qreal r, qreal g, qreal b) : r(r), g(g), b(b) {}
     void Set(qreal ri, qreal gi, qreal bi) { r = ri; g = gi; b = bi; }
     qreal r, g, b;
 };
 
 /// Implement and register this class with a b2World to provide debug drawing of physics
 /// entities in your game.
 class b2DebugDraw
 {
 public:
     b2DebugDraw();
 
     virtual ~b2DebugDraw() {}
 
     enum
     {
         e_shapeBit              = 0x0001, ///< draw shapes
         e_jointBit              = 0x0002, ///< draw joint connections
         e_aabbBit               = 0x0004, ///< draw axis aligned bounding boxes
         e_pairBit               = 0x0008, ///< draw broad-phase pairs
         e_centerOfMassBit       = 0x0010  ///< draw center of mass frame
     };
 
     /// Set the drawing flags.
     void SetFlags(uint32 flags);
 
     /// Get the drawing flags.
     uint32 GetFlags() const;
     
     /// Append flags to the current flags.
     void AppendFlags(uint32 flags);
 
     /// Clear flags from the current flags.
     void ClearFlags(uint32 flags);
 
     /// Draw a closed polygon provided in CCW order.
     virtual void DrawPolygon(const b2Vec2* vertices, int32 vertexCount, const b2Color& color) = 0;
 
     /// Draw a solid closed polygon provided in CCW order.
     virtual void DrawSolidPolygon(const b2Vec2* vertices, int32 vertexCount, const b2Color& color) = 0;
 
     /// Draw a circle.
     virtual void DrawCircle(const b2Vec2& center, qreal radius, const b2Color& color) = 0;
     
     /// Draw a solid circle.
     virtual void DrawSolidCircle(const b2Vec2& center, qreal radius, const b2Vec2& axis, const b2Color& color) = 0;
     
     /// Draw a line segment.
     virtual void DrawSegment(const b2Vec2& p1, const b2Vec2& p2, const b2Color& color) = 0;
 
     /// Draw a transform. Choose your own length scale.
     /// @param xf a transform.
     virtual void DrawTransform(const b2Transform& xf) = 0;
 
 protected:
     uint32 m_drawFlags;
 };
 
 #endif