Crate mgf [−] [src]
A low-level 3D collision and physics library intended for use in 3D video game development.
Collision detection overview
An object implements collision detection routines through the various traits provided by MGF. Each trait provides a disparate form of collision detection:
Overlaps
: Specifies a collision where the only information required is whether or not two objects overlap.Contains
: Specifies a collision where one object completely contains another. For bounding volumes.Intersection
: For linear geometries, describes a collision at some time during the motion of a particle (represented with a Ray or Segment) with only one point of contact.Contacts
: For moving volumetric geometries, describes a collision with possibly multiple contacts occuring at some time during the motion of the geometries.LocalContacts
: Similar toContacts
, but returns contacts with local contact points as well as globals.
In addition to these traits, MGF supports broad-phase colision detection
through a bounding volume hierarch (BVH
)
Physics Overview
Physics is implemented through the following objects:
SimpleDynamicBody
, a dynamic rigid body with a single geometry as a volume.CompoundDynamicBody
, a dynamic rigid body with aCompound
geometry.StaticBody
, a static body with infinite mass (i.e. terrain) that can be any shape.
After contact points are accumulated, they are pruned via a ContactPruner
and put
through a constraint solver (called ContactSolver
). The constraint solver is a
slightly unsafe interface that requires passing a mutable pointer for each object in
a contact. It will operate fine if you unsafely pass the same mutable pointer multiple
times for different contacts. In fact, that's very typical. In the future this interface
may be made safer but for now, be safe. Here is an example of a typical use case:
use mgf::cgmath::prelude::*; use mgf::cgmath::*; use mgf::{ContactSolver, ContactPruner, LocalContacts, Manifold, PhysicsObject, SimpleDynamicBody, Shape, Sphere, Velocity}; const TIMESTEP: f32 = 1.0; const RESTITUTION: f32 = 0.3; const FRICTION: f32 = 0.5; let gravity = Vector3::new(0.0, -9.8, 0.0); let mass = 1.0; let mut body_a = SimpleDynamicBody::new( RESTITUTION, FRICTION, gravity, Sphere { c: Point3::new(0.0, 0.0, 0.0), r: 1.0, }, mass ); // It is generally faster to clone a physics object than it is to construct // a new one. let mut body_b = body_a.clone(); body_a.set_pos(Point3::new(-5.0, 0.0, 0.0)); body_b.set_pos(Point3::new( 5.0, 0.0, 0.0)); // Set the linear velocity of each of the objects. body_a.set_dx(Velocity{ linear: Vector3::new(0.0, 4.0, 0.0), angular: Vector3::zero() }); body_b.set_dx(Velocity{ linear: Vector3::new(0.0, -4.0, 0.0), angular: Vector3::zero() }); // ball_a and ball_b are set to collide at the end of one unit of time. // Integrate them to set their motion and hitboxes. body_a.integrate(TIMESTEP); body_b.integrate(TIMESTEP); // Collide the objects: let mut pruner: ContactPruner = ContactPruner::new(); body_a.local_contacts(&body_b, |contact|{ pruner.push(contact); }); // Put the contacts in the constraint solver. // This is where the interface gets hairy, as adding a constraint to the // solver requires two mutable references. Often times physics objects will // be stored in a Vec or a Pool, so obtaining mutable references for two // objects is difficult. Unsafe is often necessary. const SOLVER_ITERS: usize = 20; let mut solver: ContactSolver = ContactSolver::new(); solver.add_constraint(&mut body_a, &mut body_b, Manifold::from(pruner), TIMESTEP); solver.solve(SOLVER_ITERS);
Reexports
pub extern crate cgmath; |
Modules
bitset |
Structs
AABB |
An Axis Aligned Bounding Box. |
BVH |
A Bounding Volume Hierarchy. |
Capsule |
A sphere swept along a line. |
Compound |
An aggregate structure of Spheres and Capsules. Has a position and rotation. |
CompoundDynamicBody |
A generic physical body that has a mass, a volume, and experiences linear and rotational movement. |
Contact |
A point of contact between two objects occuring during a timestep. |
ContactConstraint |
A constraint created by two objects coming in contact. |
ContactPruner |
Structure for pruning unnecessary contact points. |
ContactSolver |
A PGE based constraint solver for contacts. |
DefaultContactSolverParams |
The suggested set of parameters to use when resolving collisions. |
DefaultPruningParams |
Default parameters supplied for pruning |
Intersection |
A collision between a non-volumetric object and a volumetric object. |
LocalContact |
A point of contact between two objects that includes the contact points for each object in terms of the object's center. |
Manifold |
A set of contacts between two objects. |
Mesh |
A triangle mesh is a set of triangles that forms some sort of mesh. There are no requirements on the convexivity of the mesh. |
Moving |
A geometry swept accross a given path of motion. |
Plane |
A normal vector and a distance. |
Pool |
Growable array type that allows items to be removed and inserted without changing the indices of other entries. |
Ray |
A point and a direction with infinite distance. |
Rectangle |
A center point, two directions, and two half widths. |
Segment |
A point and a direction with a finite distance. |
SimpleDynamicBody |
A dynamic body based on a single component. |
Sphere |
A point and a distance. |
StaticBody |
A physical object that cannot move. |
Triangle |
Three points in space. |
Velocity |
A description of the positional derivative of an object. |
Vertex |
A point and a normal |
Enums
Component |
A component is a generic volume that can either be a Sphere or Capsule at runtime. Anything that can collide with a Sphere and a Capsule can collide with a component. |
PoolEntry |
Internal storage type used by Pool. |
Constants
COLLISION_EPSILON |
Maximum tolerence for error, i.e. what we consider the x86 floating point epsilon. |
Traits
Bound |
A type that can overlap, contain, and be combined with one another. |
BoundedBy |
A type that can be decomposed into a bound. |
ContactSolverParams |
A type that describes parameters used when solving contact constraints. |
Contacts |
A type that can produce a point of contact with another. |
Contains |
A type that can completely subsume another. |
Delta |
An object with a positional derivative over a timestep |
Inertia |
An type that has a moment of inertia tensor. |
Intersects |
A type that can collide with a volumetric object and produce a single point of contact. |
LocalContacts |
A type that can produce a point of contact with another and convert it to local coordinates. |
MinDistance |
Finds the result corresponding to the minimum distance between two objects. |
Overlaps |
A type that can overlap another. |
Particle |
A type that is linear in nature. |
PhysicsObject |
A type that exhibits physical properties. |
Polygon |
A type that is composed of vertices, edges and has a face. |
PruningParams |
A type that supplies constants to a ContactPruner. |
Shape |
A type that describes a set of points in space. |
Volumetric |
A type that has volume. |
Functions
compute_basis |
Computes an orthonormal basis from a given vector. This is usually used to produce tangent vectors for friction contacts. Code taken from http://box2d.org/2014/02/computing-a-basis/ |
Type Definitions
Rect |