A Tale of Three Modules
Box2D has three modules, the Common Module, which contains some low-
level code and data structures, the Collision Module, which contains code
and data structures for collision detection and response, and the Dynamics
Module, which contains code and data structures for the Physics World.
The body of this chapter is divided into three sections, one per module.
Section 6.1 will delve fairly deeply into the Common Module, since (in
addition to its use throughout Box2D) it is a useful toolkit that can save
you lots of programming time reinventing the wheel. Section 6.3 contains
an introduction to the Collision Module at a deep enough level for you to
get started writing a game. More details are available later in Chapter 8 if
you need them. Section 6.5 introduces the Dynamics Module.
The Box2D source-code folder contains, among other things, three fold-
ers corresponding to the three modules, conveniently named Common, Colli
sion,andDynamics. After poking about for a while, you will ﬁnd that the
overall structure of the ﬁles and folders in Box2D is as shown in Figure 6.1.
Fortunately, there is more structure here than meets the eye. Each mod-
ule is made up of various components, as illustrated in Figure 6.2. This
chapter and the next one will focus on the light gray components.
• 6.1 The Common Module
The Common Module contains code for some low-level things such as mem-
ory allocation and a math library. My ﬁrst thought when I saw this was
“Oh no! Not another math library!” but there is a good reason for this
one. Box2D is designed to be cross-platform, spanning devices that are
132 6 • A Tale of Three Modules
The Box2D ﬁle structure. The boxes represent folders.
blindingly fast and provide a lot of hardware support (such as gamer PCs)
to others that are less so, but are small and portable (cell phones). Writing
your code to use the structures and functions that Box2D provides will
enable your application to be cross-platform too.
Code and header ﬁles for the Common Module are found in folder Com-
mon. Table 6.1 lists them in three groups. The ﬁrst group consists of ﬁles
that are likely of no interest to you.
6.1 • The Common Module 133
The three Box2D modules with their dependencies and components.
The darker components are the ones you probably don’t need to know much about
in order to make a game.
b2Draw.h, cpp Drawing tools for demos
b2BlockAllocator.h, cpp For internal use
b2GrowableStack.h, cpp For internal use
b2StackAllocator.h, cpp For internal use
b2Settings.h, cpp Constant deﬁnitions
b2Timer.h, cpp Timer
b2Math.h, cpp Math library
Common Module ﬁles.
134 6 • A Tale of Three Modules
Box2D Type Typedeffed To
int8 signed char
int16 signed short
int32 signed int
uint8 unsigned char
uint16 unsigned short
uint32 unsigned int
Box2D scalar types.
• 6.1.1 Files Best Left Undisturbed
Files b2Draw.h and b2Draw.cpp contain the line-drawing tools that are
used in the testbed code demos that come with Box2D. They are great
for proof-of-concept, but you will likely want to use your own rendering
tools, as I have done in this book. The remaining ﬁles in this group are for
internal use by Box2D.
The second group consists of ﬁles that will be of some interest to you.
• 6.1.2 Files of Limited Interest
Files b2Settings.h and b2Settings.cpp largely consist of settings of all
kinds. Most of them are best left alone, but some of them are relevant
during tuning to make sure that your simulated physics looks and acts just
right. For the curious, b2Settings.h is where you’ll ﬁnd deﬁnitions for
the Box2D scalar types such as float32 and int32. These are listed in
Files b2Timer.h and b2Timer.cpp contain the Box2D timer class
b2Timer. This class diﬀers from the CTimer class in our codebase, used in
Chapter 3 in that it is less functional but cross-platform.
• 6.2 The Math Library
The third group of ﬁles in the Common Module should be of great interest
to you. Files b2Math.h and b2Math.cpp contain useful math structures
such as vectors and matrices and code for operations on them. All of
the functions are declared inline for speed. Table 6.3 lists some useful
uint32 b2NextPowerOfTwo(uint32); Rounds up to next power of 2
bool b2IsPowerOfTwo(uint32); true if a power of 2
float32 b2InvSqrt(float32); Approximate but fast 1/sqrt
Get Introduction to Game Physics with Box2D now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.