# 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;` |

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

## Type Definitions

Rect |