# 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 resolution overview

Types that satisfy the `PhysicsObject` trait can resolve collisions in accordance with the laws of classical mechanics. To do this it is recommended to generate a `Manifold` type and pass it to the resolution function. This method handles any geometry and number of contacts:

```use mgf::cgmath::{Vector3, Point3, Zero};
use mgf::{Sphere, RigidBody, LocalContacts, Manifold, PhysicsState,
DefaultPhysConfig, Component, PhysicsObject, Shape};

const RESTITUTION: f32 = 1.0;
const FRICTION: f32 = 0.0;

let gravity = Vector3::new(0.0, -9.8, 0.0);

let body_geom = vec![
Component::from(Sphere{ c: Point3::new(0.0, 0.0, 0.0), r: 1.0 })
];
let body_masses = vec![ 1.0 ];

let mut rigid_body_a = RigidBody::new(RESTITUTION, FRICTION, gravity,
body_geom, body_masses);
// Since constructing a rigid body calculates the center of mass and the
// inertia tensor for an object, it is more efficient to clone a rigid
// body into a new one that shares the same geometry.
let mut rigid_body_b = rigid_body_a.clone();

// Set the initial positions of the bodies
rigid_body_a.set_pos(Point3::new(0.0, -5.0, 0.0));
rigid_body_b.set_pos(Point3::new(0.0,  5.0, 0.0));

// Apply an impulse to the bodies to set them in motion.
rigid_body_a.apply_impulse(
Vector3::new(5.0, 0.0, 0.0),    // Linear impulse
Vector3::zero()                 // Angular impulse
);
rigid_body_b.apply_impulse(Vector3::new(-5.0, 0.0, 0.0), Vector3::zero());

// Integrate the bodies once per frame to produce the correct motion.
rigid_body_a.integrate(1.0);
rigid_body_b.integrate(1.0);

let mut manifold = Manifold::new();

rigid_body_a.local_contacts(&rigid_body_b, |c|{ manifold.push(c); });

PhysicsState::resolve_manifold::<DefaultPhysConfig, _, _>(
&mut rigid_body_a,
&mut rigid_body_b,
&manifold,
1.0     // The same timestep passed to integrate.
);```

`DefaultPhysConfig` is a struct that passes various constants to the resolver. It does not incur any runtime penalty.

## Reexports

 `pub extern crate cgmath;`

## 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 occuring during a timestep. DefaultPhysConfig The suggested set of parameters to use when resolving collisions. 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 Structure for pruning unnecessary contact points. 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. PhysicsState A description of the physical state of an object. 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. RigidBody A generic physical body that has a mass, a volume, and experiences linear and rotational movement. Segment A point and a direction with a finite distance. Sphere A point and a distance. StaticBody A physical object that cannot move. Triangle Three points in space. 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. PERSISTENT_THRESHOLD_SQ Minimum distance between two points required to not reject a point.

## Traits

 Bound A type that can overlap, contain, and be combined with one another. BoundedBy A type that can be decomposed into a bound. 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. 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. PhysicsConfig A set of constants necessary when performing collision resolution. PhysicsObject A type that exhibits physical properties. Polygon A type that is composed of vertices, edges and has a face. Shape A type that describes a set of points in space.