viktorljung
94 lines
3.2 KiB
Markdown
94 lines
3.2 KiB
Markdown
# Common
|
|
[About](#about)<br/>
|
|
[Settings](#settings)<br/>
|
|
[Memory Management](#mm)<br/>
|
|
[Math](#math)
|
|
|
|
<a name="about">
|
|
## About
|
|
|
|
The Common module contains settings, memory management, and vector math.
|
|
|
|
<a name="settings">
|
|
## 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.
|
|
|
|
<a name="mm">
|
|
## 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.
|
|
|
|
<a name="math">
|
|
## 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](http://creativecommons.org/licenses/by/4.0/legalcode).
|
|
For details and restrictions, please see the
|
|
[Content License](md__content_license.html).*
|