gfx/box2d_renderer.h

Against YOUR Box2D, never a copy of ours

The reference bundles the physics engine itself, which is how a framework ends up shipping a second Box2D into a project that already has one -- two copies of every b2 symbol, and whichever the linker meets first wins. This header vendors nothing. It compiles against the Box2D the plugin already builds, and when there is none it declares nothing at all: including it is free, and SONORE_BOX2D_API says which API, if any, it found.

Which Box2D

Found with __has_include, in this order, unless SONORE_BOX2D_API is defined first (3, 24, 23, or 0 to switch it off):

<box2d/id.h>       Box2D 3.1 and later: the C API of b2WorldId handles.
                   Drawn through b2World_Draw with a b2DebugDraw whose
                   callbacks are this class. 3.0 is NOT supported: its
                   b2DebugDraw has no b2DefaultDebugDraw() and a
                   different string callback.
<box2d/b2_world.h> Box2D 2.4: the C++ API. Walked by hand -- bodies,
                   fixtures, joints -- rather than through b2Draw,
                   because b2Draw is installed ON the world with
                   SetDebugDraw, and a renderer that replaced the
                   plugin's own debug draw to paint one frame would be
                   a renderer with a side effect.
<Box2D/Box2D.h>    Box2D 2.3, the same walk (IsActive for IsEnabled).

Colours, by body

By body type and state, from a Palette the caller can replace: static, kinematic, awake dynamic, sleeping, disabled, sensor, and joints. For 2.x the walk decides; for 3.x Box2D decides, and passes a named colour -- paleGreen for a static body, pink for an awake one, gray for one asleep -- which is mapped back to the palette entry it stands for. Shapes and joints are drawn in two separate passes so the mapping can tell a gray revolute joint from a gray sleeping body.

The transform

render() maps a rectangle of the WORLD -- its left, top, right and bottom edges, in metres -- onto a rectangle of the component. Box2D's y axis points up, so a world viewed the right way up passes top > bottom, and the mapping flips it; nothing assumes either. Points are taken to component space here and drawn there, so a line is lineThickness() PIXELS wide whatever the zoom: strokes in world units would be a hairline at one zoom and a slab at another.