Geometry

Geometry types and algorithms. More...

Data Structures
struct	b2RayCastInput
	Low level ray cast input data. More...
struct	b2ShapeProxy
	A distance proxy is used by the GJK algorithm. More...
struct	b2ShapeCastInput
	Low level shape cast input in generic form. More...
struct	b2CastOutput
	Low level ray cast or shape-cast output data. More...
struct	b2MassData
	This holds the mass data computed for a shape. More...
struct	b2Circle
	A solid circle. More...
struct	b2Capsule
	A solid capsule can be viewed as two semicircles connected by a rectangle. More...
struct	b2Polygon
	A solid convex polygon. More...
struct	b2Segment
	A line segment with two-sided collision. More...
struct	b2ChainSegment
	A line segment with one-sided collision. More...
struct	b2Hull
	A convex hull. More...

Macros
#define	B2_MAX_POLYGON_VERTICES   8
	The maximum number of vertices on a convex polygon.

Functions
bool	b2IsValidRay (const b2RayCastInput *input)
	Validate ray cast input data (NaN, etc)
b2Polygon	b2MakePolygon (const b2Hull *hull, float radius)
	Make a convex polygon from a convex hull.
b2Polygon	b2MakeOffsetPolygon (const b2Hull *hull, b2Vec2 position, b2Rot rotation)
	Make an offset convex polygon from a convex hull.
b2Polygon	b2MakeOffsetRoundedPolygon (const b2Hull *hull, b2Vec2 position, b2Rot rotation, float radius)
	Make an offset convex polygon from a convex hull.
b2Polygon	b2MakeSquare (float halfWidth)
	Make a square polygon, bypassing the need for a convex hull.
b2Polygon	b2MakeBox (float halfWidth, float halfHeight)
	Make a box (rectangle) polygon, bypassing the need for a convex hull.
b2Polygon	b2MakeRoundedBox (float halfWidth, float halfHeight, float radius)
	Make a rounded box, bypassing the need for a convex hull.
b2Polygon	b2MakeOffsetBox (float halfWidth, float halfHeight, b2Vec2 center, b2Rot rotation)
	Make an offset box, bypassing the need for a convex hull.
b2Polygon	b2MakeOffsetRoundedBox (float halfWidth, float halfHeight, b2Vec2 center, b2Rot rotation, float radius)
	Make an offset rounded box, bypassing the need for a convex hull.
b2Polygon	b2TransformPolygon (b2Transform transform, const b2Polygon *polygon)
	Transform a polygon. This is useful for transferring a shape from one body to another.
b2MassData	b2ComputeCircleMass (const b2Circle *shape, float density)
	Compute mass properties of a circle.
b2MassData	b2ComputeCapsuleMass (const b2Capsule *shape, float density)
	Compute mass properties of a capsule.
b2MassData	b2ComputePolygonMass (const b2Polygon *shape, float density)
	Compute mass properties of a polygon.
b2AABB	b2ComputeCircleAABB (const b2Circle *shape, b2Transform transform)
	Compute the bounding box of a transformed circle.
b2AABB	b2ComputeCapsuleAABB (const b2Capsule *shape, b2Transform transform)
	Compute the bounding box of a transformed capsule.
b2AABB	b2ComputePolygonAABB (const b2Polygon *shape, b2Transform transform)
	Compute the bounding box of a transformed polygon.
b2AABB	b2ComputeSegmentAABB (const b2Segment *shape, b2Transform transform)
	Compute the bounding box of a transformed line segment.
bool	b2PointInCircle (b2Vec2 point, const b2Circle *shape)
	Test a point for overlap with a circle in local space.
bool	b2PointInCapsule (b2Vec2 point, const b2Capsule *shape)
	Test a point for overlap with a capsule in local space.
bool	b2PointInPolygon (b2Vec2 point, const b2Polygon *shape)
	Test a point for overlap with a convex polygon in local space.
b2CastOutput	b2RayCastCircle (const b2RayCastInput *input, const b2Circle *shape)
	Ray cast versus circle shape in local space. Initial overlap is treated as a miss.
b2CastOutput	b2RayCastCapsule (const b2RayCastInput *input, const b2Capsule *shape)
	Ray cast versus capsule shape in local space. Initial overlap is treated as a miss.
b2CastOutput	b2RayCastSegment (const b2RayCastInput *input, const b2Segment *shape, bool oneSided)
	Ray cast versus segment shape in local space.
b2CastOutput	b2RayCastPolygon (const b2RayCastInput *input, const b2Polygon *shape)
	Ray cast versus polygon shape in local space. Initial overlap is treated as a miss.
b2CastOutput	b2ShapeCastCircle (const b2ShapeCastInput *input, const b2Circle *shape)
	Shape cast versus a circle. Initial overlap is treated as a miss.
b2CastOutput	b2ShapeCastCapsule (const b2ShapeCastInput *input, const b2Capsule *shape)
	Shape cast versus a capsule. Initial overlap is treated as a miss.
b2CastOutput	b2ShapeCastSegment (const b2ShapeCastInput *input, const b2Segment *shape)
	Shape cast versus a line segment. Initial overlap is treated as a miss.
b2CastOutput	b2ShapeCastPolygon (const b2ShapeCastInput *input, const b2Polygon *shape)
	Shape cast versus a convex polygon. Initial overlap is treated as a miss.
b2Hull	b2ComputeHull (const b2Vec2 *points, int count)
	Compute the convex hull of a set of points.
bool	b2ValidateHull (const b2Hull *hull)
	This determines if a hull is valid.

Detailed Description

Geometry types and algorithms.

Definitions of circles, capsules, segments, and polygons. Various algorithms to compute hulls, mass properties, and so on.

---

Data Structure Documentation

b2RayCastInput

struct b2RayCastInput

Low level ray cast input data.

Collaboration diagram for b2RayCastInput:

Data Fields
float	maxFraction	The maximum fraction of the translation to consider, typically 1.
b2Vec2	origin	Start point of the ray cast.
b2Vec2	translation	Translation of the ray cast.

b2ShapeProxy

struct b2ShapeProxy

A distance proxy is used by the GJK algorithm.

It encapsulates any shape. You can provide between 1 and B2_MAX_POLYGON_VERTICES and a radius.

Collaboration diagram for b2ShapeProxy:

Data Fields
int	count	The number of points. Must be greater than 0.
b2Vec2	points[B2_MAX_POLYGON_VERTICES]	The point cloud.
float	radius	The external radius of the point cloud. May be zero.

b2ShapeCastInput

struct b2ShapeCastInput

Low level shape cast input in generic form.

This allows casting an arbitrary point cloud wrap with a radius. For example, a circle is a single point with a non-zero radius. A capsule is two points with a non-zero radius. A box is four points with a zero radius.

Collaboration diagram for b2ShapeCastInput:

Data Fields
bool	canEncroach	Allow shape cast to encroach when initially touching. This only works if the radius is greater than zero.
float	maxFraction	The maximum fraction of the translation to consider, typically 1.
b2ShapeProxy	proxy	A generic shape.
b2Vec2	translation	The translation of the shape cast.

b2CastOutput

struct b2CastOutput

Low level ray cast or shape-cast output data.

Collaboration diagram for b2CastOutput:

Data Fields
float	fraction	The fraction of the input translation at collision.
bool	hit	Did the cast hit?
int	iterations	The number of iterations used.
b2Vec2	normal	The surface normal at the hit point.
b2Vec2	point	The surface hit point.

b2MassData

struct b2MassData

This holds the mass data computed for a shape.

Collaboration diagram for b2MassData:

Data Fields
b2Vec2	center	The position of the shape's centroid relative to the shape's origin.
float	mass	The mass of the shape, usually in kilograms.
float	rotationalInertia	The rotational inertia of the shape about the local origin.

b2Circle

struct b2Circle

A solid circle.

Collaboration diagram for b2Circle:

Data Fields
b2Vec2	center	The local center.
float	radius	The radius.

b2Capsule

struct b2Capsule

A solid capsule can be viewed as two semicircles connected by a rectangle.

Collaboration diagram for b2Capsule:

Data Fields
b2Vec2	center1	Local center of the first semicircle.
b2Vec2	center2	Local center of the second semicircle.
float	radius	The radius of the semicircles.

b2Polygon

struct b2Polygon

A solid convex polygon.

It is assumed that the interior of the polygon is to the left of each edge. Polygons have a maximum number of vertices equal to B2_MAX_POLYGON_VERTICES. In most cases you should not need many vertices for a convex polygon.

Warning

DO NOT fill this out manually, instead use a helper function like b2MakePolygon or b2MakeBox.

Collaboration diagram for b2Polygon:

Data Fields
b2Vec2	centroid	The centroid of the polygon.
int	count	The number of polygon vertices.
b2Vec2	normals[B2_MAX_POLYGON_VERTICES]	The outward normal vectors of the polygon sides.
float	radius	The external radius for rounded polygons.
b2Vec2	vertices[B2_MAX_POLYGON_VERTICES]	The polygon vertices.

b2Segment

struct b2Segment

A line segment with two-sided collision.

Collaboration diagram for b2Segment:

Data Fields
b2Vec2	point1	The first point.
b2Vec2	point2	The second point.

b2ChainSegment

struct b2ChainSegment

A line segment with one-sided collision.

Only collides on the right side. Several of these are generated for a chain shape. ghost1 -> point1 -> point2 -> ghost2

Collaboration diagram for b2ChainSegment:

Data Fields
int	chainId	The owning chain shape index (internal usage only)
b2Vec2	ghost1	The tail ghost vertex.
b2Vec2	ghost2	The head ghost vertex.
b2Segment	segment	The line segment.

b2Hull

struct b2Hull

A convex hull.

Used to create convex polygons.

Warning

Do not modify these values directly, instead use b2ComputeHull()

Collaboration diagram for b2Hull:

Data Fields
int	count	The number of points.
b2Vec2	points[B2_MAX_POLYGON_VERTICES]	The final points of the hull.

Macro Definition Documentation

B2_MAX_POLYGON_VERTICES

#define B2_MAX_POLYGON_VERTICES   8

The maximum number of vertices on a convex polygon.

Changing this affects performance even if you don't use more vertices.

Function Documentation

b2ComputeHull()

b2Hull b2ComputeHull	(	const b2Vec2 *	points,
		int	count )

Compute the convex hull of a set of points.

Returns an empty hull if it fails. Some failure cases:

• all points very close together
• all points on a line
• less than 3 points
• more than B2_MAX_POLYGON_VERTICES points This welds close points and removes collinear points.

  Warning

  Do not modify a hull once it has been computed

b2MakeBox()

b2Polygon b2MakeBox	(	float	halfWidth,
		float	halfHeight )

Make a box (rectangle) polygon, bypassing the need for a convex hull.

Parameters

halfWidth	the half-width (x-axis)
halfHeight	the half-height (y-axis)

b2MakeOffsetBox()

b2Polygon b2MakeOffsetBox	(	float	halfWidth,
		float	halfHeight,
		b2Vec2	center,
		b2Rot	rotation )

Make an offset box, bypassing the need for a convex hull.

Parameters

halfWidth	the half-width (x-axis)
halfHeight	the half-height (y-axis)
center	the local center of the box
rotation	the local rotation of the box

b2MakeOffsetPolygon()

b2Polygon b2MakeOffsetPolygon	(	const b2Hull *	hull,
		b2Vec2	position,
		b2Rot	rotation )

Make an offset convex polygon from a convex hull.

This will assert if the hull is not valid.

Warning

Do not manually fill in the hull data, it must come directly from b2ComputeHull

b2MakeOffsetRoundedBox()

b2Polygon b2MakeOffsetRoundedBox	(	float	halfWidth,
		float	halfHeight,
		b2Vec2	center,
		b2Rot	rotation,
		float	radius )

Make an offset rounded box, bypassing the need for a convex hull.

Parameters

halfWidth	the half-width (x-axis)
halfHeight	the half-height (y-axis)
center	the local center of the box
rotation	the local rotation of the box
radius	the radius of the rounded extension

b2MakeOffsetRoundedPolygon()

b2Polygon b2MakeOffsetRoundedPolygon	(	const b2Hull *	hull,
		b2Vec2	position,
		b2Rot	rotation,
		float	radius )

Make an offset convex polygon from a convex hull.

This will assert if the hull is not valid.

Warning

Do not manually fill in the hull data, it must come directly from b2ComputeHull

b2MakePolygon()

b2Polygon b2MakePolygon	(	const b2Hull *	hull,
		float	radius )

Make a convex polygon from a convex hull.

This will assert if the hull is not valid.

Warning

Do not manually fill in the hull data, it must come directly from b2ComputeHull

b2MakeRoundedBox()

b2Polygon b2MakeRoundedBox	(	float	halfWidth,
		float	halfHeight,
		float	radius )

Make a rounded box, bypassing the need for a convex hull.

Parameters

halfWidth	the half-width (x-axis)
halfHeight	the half-height (y-axis)
radius	the radius of the rounded extension

b2MakeSquare()

b2Polygon b2MakeSquare

(

float

halfWidth

)

Make a square polygon, bypassing the need for a convex hull.

Parameters

halfWidth

the half-width

b2RayCastSegment()

b2CastOutput b2RayCastSegment	(	const b2RayCastInput *	input,
		const b2Segment *	shape,
		bool	oneSided )

Ray cast versus segment shape in local space.

Optionally treat the segment as one-sided with hits from the left side being treated as a miss.

b2ValidateHull()

bool b2ValidateHull

(

const b2Hull *

hull

)

This determines if a hull is valid.

Checks for:

• convexity
• collinear points This is expensive and should not be called at runtime.