About

The Common module contains settings, memory management, and vector math.

Settings

The header b2Settings.h contains:

Types such as int32 and float32
Constants
Allocation wrappers
The version number

Types

LiquidFun defines various types such as float32, int8, etc. to make it easy to determine the size of structures.

Constants

LiquidFun defines several constants. These are all documented in b2Settings.h. Normally you do not need to adjust these constants.

LiquidFun uses floating point math for collision and simulation. Due to round-off error some numerical tolerances are defined. Some tolerances are absolute and some are relative. Absolute tolerances use MKS units.

Allocation wrappers

The settings file defines b2Alloc and b2Free for large allocations. You may forward these calls to your own memory management system.

Version

The b2Version structure holds the current version so you can query this at run-time.

Memory Management

A large number of the decisions about the design of LiquidFun were based on the need for quick and efficient use of memory. In this section I will discuss how and why LiquidFun allocates memory.

LiquidFun tends to allocate a large number of small objects (around 50-300 bytes). Using the system heap through malloc or new for small objects is inefficient and can cause fragmentation. Many of these small objects may have a short life span, such as contacts, but can persist for several time steps. So we need an allocator that can efficiently provide heap memory for these objects.

LiquidFun's solution is to use a small object allocator (SOA) called b2BlockAllocator. The SOA keeps a number of growable pools of varying sizes. When a request is made for memory, the SOA returns a block of memory that best fits the requested size. When a block is freed, it is returned to the pool. Both of these operations are fast and cause little heap traffic.

Since LiquidFun uses a SOA, you should never new or malloc a body, fixture, or joint. However, you do have to allocate a b2World on your own. The b2World class provides factories for you to create bodies, fixtures, and joints. This allows LiquidFun to use the SOA and hide the gory details from you. Never, call delete or free on a body, fixture, or joint.

While executing a time step, LiquidFun needs some temporary workspace memory. For this, it uses a stack allocator called b2StackAllocator to avoid per-step heap allocations. You don't need to interact with the stack allocator, but it's good to know it's there.

Math

LiquidFun includes a simple small vector and matrix module. This has been designed to suit the internal needs of LiquidFun and the API. All the members are exposed, so you may use them freely in your application.

The math library is kept simple to make LiquidFun easy to port and maintain.

This content is licensed under Creative Commons Attribution 4.0. For details and restrictions, please see the Content License.