# [−][src]Crate mgf

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 |