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 b2ComputeShapeDistance. More...
struct	b2DistanceOutput
	Output for b2ComputeShapeDistance. More...
struct	b2SimplexVertex
	Simplex vertex for debugging the GJK algorithm. More...
struct	b2Simplex
	Simplex from the GJK algorithm. More...
struct	b2ShapeCastPairInput
	Input parameters for b2CastShape. More...
struct	b2Sweep
	This describes the motion of a body/shape for TOI computation. More...
struct	b2TOIInput
	Time of impact input. More...
struct	b2TOIOutput
	Time of impact output. More...

Enumerations
enum	b2TOIState
	Describes the TOI output.

Functions
b2SegmentDistanceResult	b2ComputeSegmentDistance (b2Vec2 p1, b2Vec2 q1, b2Vec2 p2, b2Vec2 q2)
	Compute the distance between two line segments, clamping at the end points if needed.
b2DistanceOutput	b2ComputeShapeDistance (const b2DistanceInput *input, b2SimplexCache *cache, b2Simplex *simplexes, int simplexCapacity)
	Compute the closest points between two shapes represented as point clouds.
b2CastOutput	b2CastShape (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.
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	b2ComputeTimeOfImpact (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.

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 b2ComputeShapeDistance multiple times with nearby transforms this might improve performance. The distance cache must be initialized to zero on the first 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 b2ComputeShapeDistance.

Data Fields
b2ShapeProxy	proxyA	The proxy for shape A.
b2ShapeProxy	proxyB	The proxy for shape B.
b2Transform	transform	Transform of shape B in shape A's frame, the relative pose B in A (b2InvMulTransforms( worldA, worldB )). The query is origin independent and runs in frame A.
bool	useRadii	Should the proxy radius be considered?

b2DistanceOutput

struct b2DistanceOutput

Output for b2ComputeShapeDistance.

Data Fields
float	distance	The final distance, zero if overlapped.
int	iterations	Number of GJK iterations used.
b2Vec2	normal	A to B normal in shape A's frame. Invalid if distance is zero.
b2Vec2	pointA	Closest point on shapeA, in shape A's frame.
b2Vec2	pointB	Closest point on shapeB, in shape A's frame.
int	simplexCount	The number of simplexes stored in the simplex array.

b2SimplexVertex

struct b2SimplexVertex

Simplex vertex for debugging the GJK algorithm.

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.

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

b2ShapeCastPairInput

struct b2ShapeCastPairInput

Input parameters for b2CastShape.

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	transform	Transform of shape B in shape A's frame, the relative pose B in A.
b2Vec2	translationB	The translation of shape B, in A's frame.

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.

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

Time of impact input.

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

Time of impact output.

Data Fields
float	fraction	The sweep time of the collision.
b2Vec2	normal	The hit normal.
b2Vec2	point	The hit point.
b2TOIState	state	The type of result.

Function Documentation

b2CastShape()

b2CastOutput b2CastShape

(

const b2ShapeCastPairInput *

input

)

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

Determines the hit point, normal, and translation fraction. The query runs in frame A, so the hit point and normal are returned in frame A. Initially touching shapes return a zero fraction in the output.

b2ComputeShapeDistance()

b2DistanceOutput b2ComputeShapeDistance	(	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.

b2ComputeTimeOfImpact()

b2TOIOutput b2ComputeTimeOfImpact

(

const b2TOIInput *

input

)

Compute the upper bound on time before two shapes penetrate.

Time is represented as a fraction between [0,maxFraction]. 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.

b2MakeProxy()

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.