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.

Typedefs
typedef b2CastOutput	b2WorldCastOutput
	This is an alias in single precision.

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 with a radius.
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, b2WorldTransform transform)
	Compute the bounding box of a transformed circle.
b2AABB	b2ComputeCapsuleAABB (const b2Capsule *shape, b2WorldTransform transform)
	Compute the bounding box of a transformed capsule.
b2AABB	b2ComputePolygonAABB (const b2Polygon *shape, b2WorldTransform transform)
	Compute the bounding box of a transformed polygon.
b2AABB	b2ComputeSegmentAABB (const b2Segment *shape, b2WorldTransform transform)
	Compute the bounding box of a transformed line segment.
bool	b2PointInCircle (const b2Circle *shape, b2Vec2 point)
	Test a point for overlap with a circle in local space.
bool	b2PointInCapsule (const b2Capsule *shape, b2Vec2 point)
	Test a point for overlap with a capsule in local space.
bool	b2PointInPolygon (const b2Polygon *shape, b2Vec2 point)
	Test a point for overlap with a convex polygon in local space.
b2CastOutput	b2CastRayCircle (const b2Circle *shape, const b2RayCastInput *input)
	Ray cast versus circle shape in local space.
b2CastOutput	b2CastRayCapsule (const b2Capsule *shape, const b2RayCastInput *input)
	Ray cast versus capsule shape in local space.
b2CastOutput	b2CastRaySegment (const b2Segment *shape, const b2RayCastInput *input, bool oneSided)
	Ray cast versus segment shape in local space.
b2CastOutput	b2CastRayPolygon (const b2Polygon *shape, const b2RayCastInput *input)
	Ray cast versus polygon shape in local space.
b2CastOutput	b2CastShapeCircle (const b2Circle *shape, const b2ShapeCastInput *input)
	Shape cast versus a circle.
b2CastOutput	b2CastShapeCapsule (const b2Capsule *shape, const b2ShapeCastInput *input)
	Shape cast versus a capsule.
b2CastOutput	b2CastShapeSegment (const b2Segment *shape, const b2ShapeCastInput *input)
	Shape cast versus a line segment.
b2CastOutput	b2CastShapePolygon (const b2Polygon *shape, const b2ShapeCastInput *input)
	Shape cast versus a convex polygon.
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. Functions should take the shape as the first argument to assist editor auto-complete.

---

Data Structure Documentation

b2RayCastInput

struct b2RayCastInput

Low level ray cast input data.

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 points and a radius.

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

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.

The hit point is in the local or relative frame of the input. Returns a zero fraction and normal in the case of initial overlap.

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.

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 shape center.

b2Circle

struct b2Circle

A solid circle.

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.

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.

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.

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

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()

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

b2CastRaySegment()

b2CastOutput b2CastRaySegment	(	const b2Segment *	shape,
		const b2RayCastInput *	input,
		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.

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 with a radius.

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

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.