Expand description
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:
RigidBodyVec
, a vector of rigid bodies.Solver
, a generic constraint-based solver.ContactConstraint
, a constraint modeling the collision of two objects.
After contact points are accumulated, they are pruned via a ContactPruner
and put
through a constraint solver.
use mgf::cgmath::prelude::*;
use mgf::cgmath::*;
use mgf::*;
const TIMESTEP: f32 = 1.0;
const RESTITUTION: f32 = 0.3;
const FRICTION: f32 = 0.5;
const MASS: f32 = 1.0;
const SOLVER_ITERS: usize = 20;
let gravity = Vector3::new(0.0, -9.8, 0.0);
let mut rigid_bodies = RigidBodyVec::new();
let mut sphere = Component::from(Sphere{ c: Point3::new(0.0, 0.0, 0.0), r: 1.0 });
sphere.set_pos(Point3::new(-5.0, 0.0, 0.0));
let body_a = rigid_bodies.add_body(sphere, MASS, RESTITUTION, FRICTION, gravity);
sphere.set_pos(Point3::new(5.0, 0.0, 0.0));
let body_b = rigid_bodies.add_body(sphere, MASS, RESTITUTION, FRICTION, gravity);
// Set the velocity for the objects.
rigid_bodies.set(body_a, Velocity{ linear: Vector3::new(0.0, 4.0, 0.0), angular: Vector3::zero() });
rigid_bodies.set(body_b, Velocity{ linear: Vector3::new(0.0, -4.0, 0.0), angular: Vector3::zero() });
// Integrate the objects, creating colliders for each.
rigid_bodies.integrate(TIMESTEP);
// Collide the objects:
let mut pruner: ContactPruner = ContactPruner::new();
let body_ai: usize = body_a.into();
let body_bi: usize = body_b.into();
rigid_bodies.collider[body_ai].local_contacts(
&rigid_bodies.collider[body_bi],
| lc | {
pruner.push(lc);
}
);
// Create the constraint solver:
let mut solver = Solver::<ContactConstraint<_>>::new();
// Create a manifold to pass to the contact solver as a constraint:
// Obviously two spheres will only produce one contact. To avoid using a
// pruner in this case a Manifold may be constructed from a single LocalContact:
// let manifold = Manifold::from(local_contact);
let manifold = Manifold::from(pruner);
solver.add_constraint(
ContactConstraint::new(
&rigid_bodies,
body_a, body_b,
manifold,
TIMESTEP
)
);
// Solve the collision:
solver.solve(&mut rigid_bodies, SOLVER_ITERS);
Re-exports§
pub extern crate cgmath;
Modules§
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.
- Contact
- A point of contact between two objects occurring during a timestep.
- Contact
Constraint - A non-penetration constraint between two rigid bodies.
- Contact
Pruner - Structure for pruning unnecessary contact points.
- Convex
Mesh - A closed convex mesh. Represented by a point soup.
- Default
Contact Constraint Params - The suggested set of parameters to use when resolving collisions.
- Default
Pruning Params - Default parameters supplied for pruning
- Intersection
- A collision between a non-volumetric object and a volumetric object.
- Local
Contact - 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.
- Minkowski
Diff - Moving
- A geometry swept accross a given path of motion.
- OBB
- An arbitrarily oriented bounding box.
- Penetration
- A discrete point of contact between two objects.
- 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.
- Rigid
Body Info - A description of the physical state of an object minus linear and angular velocity.
- Rigid
Body Vec - A vector of rigid bodies.
- Segment
- A point and a direction with a finite distance.
- Simplex
- Solver
- A generic constraint solver.
- Sphere
- A point and a distance.
- Support
Point - A point that stores the local support points as well as the Minkowski difference.
- Tetrahedron
- Four points in space forming a 3D geometry with four faces.
- Triangle
- Three points in space.
- Velocity
- A description of the positional derivative of an object.
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.
- Component
Constructor - A description of a Component minus rotation and position.
- Pool
Entry - Internal storage type used by Pool.
- Rigid
Body Ref - A reference to an element of a RigidBodyVec.
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.
- Bounded
By - A type that can be decomposed into a bound.
- Constrained
Set - A type that can be indexed and return some information. Constrained is information that can be returned and set, while Inspected is information that can only be returned.
- Constraint
- A type that represents a constraint between some objects.
- Contact
Constraint Params - 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.
- Convex
- A type that represents a convex volume.
- Delta
- An object with a positional derivative over a time step.
- Inertia
- Any 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.
- Local
Contacts - A type that can produce a point of contact with another and convert it to local coordinates.
- Overlaps
- A type that can overlap another.
- Particle
- A type that is linear in nature.
- Penetrates
- A type that can penetrate another.
- Polygon
- A type that is composed of vertices, edges and has a face.
- Pruning
Params - 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§
- closest_
pts_ seg - 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/