diff options
Diffstat (limited to 'Client/ThirdParty/Box2D/docs/overview.md')
| -rw-r--r-- | Client/ThirdParty/Box2D/docs/overview.md | 216 |
1 files changed, 216 insertions, 0 deletions
diff --git a/Client/ThirdParty/Box2D/docs/overview.md b/Client/ThirdParty/Box2D/docs/overview.md new file mode 100644 index 0000000..99142f3 --- /dev/null +++ b/Client/ThirdParty/Box2D/docs/overview.md @@ -0,0 +1,216 @@ +# Overview +Box2D is a 2D rigid body simulation library for games. Programmers can +use it in their games to make objects move in realistic ways and make +the game world more interactive. From the game engine's point of view, +a physics engine is just a system for procedural animation. + +Box2D is written in portable C++. Most of the types defined in the +engine begin with the b2 prefix. Hopefully this is sufficient to avoid +name clashing with your game engine. + +## Prerequisites +In this manual I'll assume you are familiar with basic physics +concepts, such as mass, force, torque, and impulses. If not, please +first consult Google search and Wikipedia. + +Box2D was created as part of a physics tutorial at the Game Developer +Conference. You can get these tutorials from the download section of +box2d.org. + +Since Box2D is written in C++, you are expected to be experienced in C++ +programming. Box2D should not be your first C++ programming project! You +should be comfortable with compiling, linking, and debugging. + +> **Caution**: +> Box2D should not be your first C++ project. Please learn C++ +> programming, compiling, linking, and debugging before working with +> Box2D. There are many resources for this on the net. + +## Scope +This manual covers the majority of the Box2D API. However, not every +aspect is covered. Please look at the testbed included +with Box2D to learn more. + +This manual is only updated with new releases. The latest version of +Box2D may be out of sync with this manual. + +## Feedback and Bugs +Please file bugs and feature requests here: +[Box2D Issues](https://github.com/erincatto/box2d/issues) + +You can help to ensure your issue gets fixed if you provide sufficient +detail. A testbed example that reproduces the problem is ideal. You can +read about the testbed later in this document. + +There is also a [Discord server](https://discord.gg/NKYgCBP) and a +[subreddit](https://reddit.com/r/box2d) for Box2D. + +## Core Concepts +Box2D works with several fundamental concepts and objects. We briefly +define these objects here and more details are given later in this +document. + +#### shape +A shape is 2D geometrical object, such as a circle or polygon. + +#### rigid body +A chunk of matter that is so strong that the distance between any two +bits of matter on the chunk is constant. They are hard like a diamond. +In the following discussion we use body interchangeably with rigid body. + +#### fixture +A fixture binds a shape to a body and adds material properties such as +density, friction, and restitution. A fixture puts a shape into the +collision system (broad-phase) so that it can collide with other shapes. + +#### constraint +A constraint is a physical connection that removes degrees of freedom +from bodies. A 2D body has 3 degrees of freedom (two translation +coordinates and one rotation coordinate). If we take a body and pin it +to the wall (like a pendulum) we have constrained the body to the wall. +At this point the body can only rotate about the pin, so the constraint +has removed 2 degrees of freedom. + +#### contact constraint +A special constraint designed to prevent penetration of rigid bodies and +to simulate friction and restitution. You do not create contact +constraints; they are created automatically by Box2D. + +#### joint +This is a constraint used to hold two or more bodies together. Box2D +supports several joint types: revolute, prismatic, distance, and more. +Some joints may have limits and motors. + +#### joint limit +A joint limit restricts the range of motion of a joint. For example, the +human elbow only allows a certain range of angles. + +#### joint motor +A joint motor drives the motion of the connected bodies according to the +joint's degrees of freedom. For example, you can use a motor to drive +the rotation of an elbow. + +#### world +A physics world is a collection of bodies, fixtures, and constraints +that interact together. Box2D supports the creation of multiple worlds, +but this is usually not necessary or desirable. + +#### solver +The physics world has a solver that is used to advance time and to +resolve contact and joint constraints. The Box2D solver is a high +performance iterative solver that operates in order N time, where N is +the number of constraints. + +#### continuous collision +The solver advances bodies in time using discrete time steps. Without +intervention this can lead to tunneling. + + +Box2D contains specialized algorithms to deal with tunneling. First, the +collision algorithms can interpolate the motion of two bodies to find +the first time of impact (TOI). Second, there is a sub-stepping solver +that moves bodies to their first time of impact and then resolves the +collision. + +## Modules +Box2D is composed of three modules: Common, Collision, and Dynamics. The +Common module has code for allocation, math, and settings. The Collision +module defines shapes, a broad-phase, and collision functions/queries. +Finally the Dynamics module provides the simulation world, bodies, +fixtures, and joints. + + +## Units +Box2D works with floating point numbers and tolerances have to be used +to make Box2D perform well. These tolerances have been tuned to work +well with meters-kilogram-second (MKS) units. In particular, Box2D has +been tuned to work well with moving shapes between 0.1 and 10 meters. So +this means objects between soup cans and buses in size should work well. +Static shapes may be up to 50 meters long without trouble. + +Being a 2D physics engine, it is tempting to use pixels as your units. +Unfortunately this will lead to a poor simulation and possibly weird +behavior. An object of length 200 pixels would be seen by Box2D as the +size of a 45 story building. + +> **Caution**: +> Box2D is tuned for MKS units. Keep the size of moving objects roughly +> between 0.1 and 10 meters. You'll need to use some scaling system when +> you render your environment and actors. The Box2D testbed does this by +> using an OpenGL viewport transform. DO NOT USE PIXELS. + +It is best to think of Box2D bodies as moving billboards upon which you +attach your artwork. The billboard may move in a unit system of meters, +but you can convert that to pixel coordinates with a simple scaling +factor. You can then use those pixel coordinates to place your sprites, +etc. You can also account for flipped coordinate axes. + +Another limitation to consider is overall world size. If your world units +become larger than 2 kilometers or so, then the lost precision can affect +stability. + +> **Caution**: +> Box2D works best with world sizes less than 2 kilometers. Use +> b2World::ShiftOrigin to support larger worlds. + +If you need to have a larger game world, consider using +b2World::ShiftOrigin to keep the world origin close to your player. I recommend +to use grid lines along with some hysteresis for triggering calls to ShiftOrigin. +This call should be made infrequently because it is has CPU cost. You may +need to store a physics offset when translating between game units and Box2D units. + +Box2D uses radians for angles. The body rotation is stored in radians +and may grow unbounded. Consider normalizing the angle of your bodies if +the magnitude of the angle becomes too large (use `b2Body::SetTransform`). + +> **Caution**: +> Box2D uses radians, not degrees. + +## Changing the length units +Advanced users may change the length unit modifying `b2_lengthUnitsPerMeter`. +You can avoid merge conflicts by defining `B2_USER_SETTINGS` and providing +`b2_user_settings.h`. See the file `b2_settings.h` for details. + +## Factories and Definitions +Fast memory management plays a central role in the design of the Box2D +API. So when you create a b2Body or a b2Joint, you need to call the +factory functions on b2World. You should never try to allocate these +types in another manner. + +There are creation functions: + +```cpp +b2Body* b2World::CreateBody(const b2BodyDef* def) +b2Joint* b2World::CreateJoint(const b2JointDef* def) +``` + +And there are corresponding destruction functions: + +```cpp +void b2World::DestroyBody(b2Body* body) +void b2World::DestroyJoint(b2Joint* joint) +``` + +When you create a body or joint, you need to provide a definition. These +definitions contain all the information needed to build the body or +joint. By using this approach we can prevent construction errors, keep +the number of function parameters small, provide sensible defaults, and +reduce the number of accessors. + +Since fixtures (shapes) must be parented to a body, they are created and +destroyed using a factory method on b2Body: + +```cpp +b2Fixture* b2Body::CreateFixture(const b2FixtureDef* def) +void b2Body::DestroyFixture(b2Fixture* fixture) +``` + +There is also shortcut to create a fixture directly from the shape and +density. + +```cpp +b2Fixture* b2Body::CreateFixture(const b2Shape* shape, float density) +``` + +Factories do not retain references to the definitions. So you can create +definitions on the stack and keep them in temporary resources. |