Introduction to Game Physics with Box2D

6

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 find that the

overall structure of the files 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 first 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

131

132 6 • A Tale of Three Modules

Figure 6.1

•

The Box2D file 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 files for the Common Module are found in folder Com-

mon. Table 6.1 lists them in three groups. The first group consists of files

that are likely of no interest to you.

6.1 • The Common Module 133

Math Functions

Figure 6.2

•

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.

File Description

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 definitions

b2Timer.h, cpp Timer

b2Math.h, cpp Math library

Table 6.1

•

Common Module files.

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

float32 float

float64 double

Table 6.2

•

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 files in this group are for

internal use by Box2D.

The second group consists of files 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 find definitions for

the Box2D scalar types such as float32 and int32. These are listed in

Table 6.2.

Files b2Timer.h and b2Timer.cpp contain the Box2D timer class

b2Timer. This class differs 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 files 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

Function Description

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

Table 6.3

•

Scalar functions.