Distance

Functions for computing the distance between shapes. More...

Data Structures
struct	b2SegmentDistanceResult
	Result of computing the distance between two line segments. More...
struct	b2SimplexCache
	Used to warm start the GJK simplex. More...
struct	b2DistanceInput
	Input for b2ShapeDistance. More...
struct	b2DistanceOutput
	Output for b2ShapeDistance. More...
struct	b2SimplexVertex
	Simplex vertex for debugging the GJK algorithm. More...
struct	b2Simplex
	Simplex from the GJK algorithm. More...
struct	b2ShapeCastPairInput
	Input parameters for b2ShapeCast. More...
struct	b2Sweep
	This describes the motion of a body/shape for TOI computation. More...
struct	b2TOIInput
	Input parameters for b2TimeOfImpact. More...
struct	b2TOIOutput
	Output parameters for b2TimeOfImpact. More...

Enumerations
enum	b2TOIState {   b2_toiStateUnknown , b2_toiStateFailed , b2_toiStateOverlapped , b2_toiStateHit ,   b2_toiStateSeparated }
	Describes the TOI output.

Functions
b2SegmentDistanceResult	b2SegmentDistance (b2Vec2 p1, b2Vec2 q1, b2Vec2 p2, b2Vec2 q2)
	Compute the distance between two line segments, clamping at the end points if needed.
b2DistanceOutput	b2ShapeDistance (const b2DistanceInput *input, b2SimplexCache *cache, b2Simplex *simplexes, int simplexCapacity)
	Compute the closest points between two shapes represented as point clouds.
b2CastOutput	b2ShapeCast (const b2ShapeCastPairInput *input)
	Perform a linear shape cast of shape B moving and shape A fixed.
b2ShapeProxy	b2MakeProxy (const b2Vec2 *points, int count, float radius)
	Make a proxy for use in overlap, shape cast, and related functions. This is a deep copy of the points.
b2ShapeProxy	b2MakeOffsetProxy (const b2Vec2 *points, int count, float radius, b2Vec2 position, b2Rot rotation)
	Make a proxy with a transform. This is a deep copy of the points.
b2Transform	b2GetSweepTransform (const b2Sweep *sweep, float time)
	Evaluate the transform sweep at a specific time.
b2TOIOutput	b2TimeOfImpact (const b2TOIInput *input)
	Compute the upper bound on time before two shapes penetrate.

Detailed Description

Functions for computing the distance between shapes.

These are advanced functions you can use to perform distance calculations. There are functions for computing the closest points between shapes, doing linear shape casts, and doing rotational shape casts. The latter is called time of impact (TOI).

---

Data Structure Documentation

b2SegmentDistanceResult

struct b2SegmentDistanceResult

Result of computing the distance between two line segments.

Collaboration diagram for b2SegmentDistanceResult:

Data Fields
b2Vec2	closest1	The closest point on the first segment.
b2Vec2	closest2	The closest point on the second segment.
float	distanceSquared	The squared distance between the closest points.
float	fraction1	The barycentric coordinate on the first segment.
float	fraction2	The barycentric coordinate on the second segment.

b2SimplexCache

struct b2SimplexCache

Used to warm start the GJK simplex.

If you call this function multiple times with nearby transforms this might improve performance. Otherwise you can zero initialize this. The distance cache must be initialized to zero on the first call. Users should generally just zero initialize this structure for each call.

Data Fields
uint16_t	count	The number of stored simplex points.
uint8_t	indexA[3]	The cached simplex indices on shape A.
uint8_t	indexB[3]	The cached simplex indices on shape B.

b2DistanceInput

struct b2DistanceInput

Input for b2ShapeDistance.

Collaboration diagram for b2DistanceInput:

Data Fields
b2ShapeProxy	proxyA	The proxy for shape A.
b2ShapeProxy	proxyB	The proxy for shape B.
b2Transform	transformA	The world transform for shape A.
b2Transform	transformB	The world transform for shape B.
bool	useRadii	Should the proxy radius be considered?

b2DistanceOutput

struct b2DistanceOutput

Output for b2ShapeDistance.

Collaboration diagram for b2DistanceOutput:

Data Fields
float	distance	The final distance, zero if overlapped.
int	iterations	Number of GJK iterations used.
b2Vec2	normal	Normal vector that points from A to B.
b2Vec2	pointA	Closest point on shapeA.
b2Vec2	pointB	Closest point on shapeB.
int	simplexCount	The number of simplexes stored in the simplex array.

b2SimplexVertex

struct b2SimplexVertex

Simplex vertex for debugging the GJK algorithm.

Collaboration diagram for b2SimplexVertex:

Data Fields
float	a	barycentric coordinate for closest point
int	indexA	wA index
int	indexB	wB index
b2Vec2	w	wB - wA
b2Vec2	wA	support point in proxyA
b2Vec2	wB	support point in proxyB

b2Simplex

struct b2Simplex

Simplex from the GJK algorithm.

Collaboration diagram for b2Simplex:

Data Fields
int	count	number of valid vertices
b2SimplexVertex	v1
b2SimplexVertex	v2
b2SimplexVertex	v3	vertices

b2ShapeCastPairInput

struct b2ShapeCastPairInput

Input parameters for b2ShapeCast.

Collaboration diagram for b2ShapeCastPairInput:

Data Fields
bool	canEncroach	Allows shapes with a radius to move slightly closer if already touching.
float	maxFraction	The fraction of the translation to consider, typically 1.
b2ShapeProxy	proxyA	The proxy for shape A.
b2ShapeProxy	proxyB	The proxy for shape B.
b2Transform	transformA	The world transform for shape A.
b2Transform	transformB	The world transform for shape B.
b2Vec2	translationB	The translation of shape B.

b2Sweep

struct b2Sweep

This describes the motion of a body/shape for TOI computation.

Shapes are defined with respect to the body origin, which may not coincide with the center of mass. However, to support dynamics we must interpolate the center of mass position.

Collaboration diagram for b2Sweep:

Data Fields
b2Vec2	c1	Starting center of mass world position.
b2Vec2	c2	Ending center of mass world position.
b2Vec2	localCenter	Local center of mass position.
b2Rot	q1	Starting world rotation.
b2Rot	q2	Ending world rotation.

b2TOIInput

struct b2TOIInput

Input parameters for b2TimeOfImpact.

Collaboration diagram for b2TOIInput:

Data Fields
float	maxFraction	Defines the sweep interval [0, maxFraction].
b2ShapeProxy	proxyA	The proxy for shape A.
b2ShapeProxy	proxyB	The proxy for shape B.
b2Sweep	sweepA	The movement of shape A.
b2Sweep	sweepB	The movement of shape B.

b2TOIOutput

struct b2TOIOutput

Output parameters for b2TimeOfImpact.

Data Fields
float	fraction	The sweep time of the collision.
b2TOIState	state	The type of result.

Function Documentation

b2ShapeCast()

b2CastOutput b2ShapeCast

(

const b2ShapeCastPairInput *

input

)

Perform a linear shape cast of shape B moving and shape A fixed.

Determines the hit point, normal, and translation fraction. You may optionally supply an array to hold debug data.

b2ShapeDistance()

b2DistanceOutput b2ShapeDistance	(	const b2DistanceInput *	input,
		b2SimplexCache *	cache,
		b2Simplex *	simplexes,
		int	simplexCapacity )

Compute the closest points between two shapes represented as point clouds.

b2SimplexCache cache is input/output. On the first call set b2SimplexCache.count to zero. The underlying GJK algorithm may be debugged by passing in debug simplexes and capacity. You may pass in NULL and 0 for these.

b2TimeOfImpact()

b2TOIOutput b2TimeOfImpact

(

const b2TOIInput *

input

)

Compute the upper bound on time before two shapes penetrate.

Time is represented as a fraction between [0,tMax]. This uses a swept separating axis and may miss some intermediate, non-tunneling collisions. If you change the time interval, you should call this function again.