# 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 to`Contacts`

, 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

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. |

Contact |
A point of contact between two objects occurring during a timestep. |

ContactConstraint |
A non-penetration constraint between two rigid bodies. |

ContactPruner |
Structure for pruning unnecessary contact points. |

ConvexMesh |
A closed convex mesh. Represented by a point soup. |

DefaultContactConstraintParams |
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. |

MinkowskiDiff | |

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. |

RigidBodyInfo |
A description of the physical state of an object minus linear and angular velocity. |

RigidBodyVec |
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. |

SupportPoint |
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. |

ComponentConstructor |
A description of a Component minus rotation and position. |

PoolEntry |
Internal storage type used by Pool. |

RigidBodyRef |
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. |

BoundedBy |
A type that can be decomposed into a bound. |

ConstrainedSet |
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. |

ContactConstraintParams |
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. |

LocalContacts |
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. |

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

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/ |

## Type Definitions

Rect |