Query

Query types and functions. More...

Data Structures
struct	b3QueryFilter
	The query filter is used to filter collisions between queries and shapes. More...
struct	b3RayCastInput
	Low level ray cast input data. More...
struct	b3RayResult
	Result from b3World_RayCastClosest. More...
struct	b3ShapeProxy
	A shape proxy is used by the GJK algorithm. It can represent a convex shape. More...
struct	b3ShapeCastInput
	Low level shape cast input in generic form. More...
struct	b3BoxCastInput
	Input for sweeping an AABB through a dynamic tree. More...
struct	b3CastOutput
	Low level ray cast or shape-cast output data. More...
struct	b3BodyCastResult
	Body cast result for ray and shape casts. More...
struct	b3SimplexCache
	Used to warm start the GJK simplex. More...
struct	b3ShapeCastPairInput
	Input parameters for b3ShapeCast. More...
struct	b3DistanceInput
	Input for b3ShapeDistance. More...
struct	b3DistanceOutput
	Output for b3ShapeDistance. More...
struct	b3SimplexVertex
	Simplex vertex for debugging the GJK algorithm. More...
struct	b3Simplex
	Simplex from the GJK algorithm. More...
struct	b3Sweep
	This describes the motion of a body/shape for TOI computation. More...
struct	b3TOIInput
	Time of impact input. More...
struct	b3TOIOutput
	Time of impact output. More...

Typedefs
typedef bool	b3MeshQueryFcn(b3Vec3 a, b3Vec3 b, b3Vec3 c, int triangleIndex, void *context)
	Query callback.
typedef b3CastOutput	b3WorldCastOutput
	Same type in single precision.

Enumerations
enum	b3TOIState {   b3_toiStateUnknown , b3_toiStateFailed , b3_toiStateOverlapped , b3_toiStateHit ,   b3_toiStateSeparated }
	Describes the TOI output.

Functions
bool	b3IsValidRay (const b3RayCastInput *input)
	Use this to ensure your ray cast input is valid and avoid internal assertions.
bool	b3OverlapCapsule (const b3Capsule *shape, b3Transform shapeTransform, const b3ShapeProxy *proxy)
	Overlap shape versus capsule.
bool	b3OverlapCompound (const b3CompoundData *shape, b3Transform shapeTransform, const b3ShapeProxy *proxy)
	Overlap shape versus compound.
bool	b3OverlapHeightField (const b3HeightFieldData *shape, b3Transform shapeTransform, const b3ShapeProxy *proxy)
	Overlap shape versus height field.
bool	b3OverlapHull (const b3HullData *shape, b3Transform shapeTransform, const b3ShapeProxy *proxy)
	Overlap shape versus hull.
bool	b3OverlapMesh (const b3Mesh *shape, b3Transform shapeTransform, const b3ShapeProxy *proxy)
	Overlap shape versus mesh.
bool	b3OverlapSphere (const b3Sphere *shape, b3Transform shapeTransform, const b3ShapeProxy *proxy)
	Overlap shape versus sphere.
b3CastOutput	b3RayCastSphere (const b3Sphere *shape, const b3RayCastInput *input)
	Ray cast versus sphere in local space.
b3CastOutput	b3RayCastHollowSphere (const b3Sphere *shape, const b3RayCastInput *input)
	Ray cast versus a hollow sphere shell in local space.
b3CastOutput	b3RayCastCapsule (const b3Capsule *shape, const b3RayCastInput *input)
	Ray cast versus capsule in local space.
b3CastOutput	b3RayCastCompound (const b3CompoundData *shape, const b3RayCastInput *input)
	Ray cast versus compound in local space.
b3CastOutput	b3RayCastHull (const b3HullData *shape, const b3RayCastInput *input)
	Ray cast versus hull shape in local space.
b3CastOutput	b3RayCastMesh (const b3Mesh *shape, const b3RayCastInput *input)
	Ray cast versus mesh in local space. A thin surface with no interior, so there is no overlap case.
b3CastOutput	b3RayCastHeightField (const b3HeightFieldData *shape, const b3RayCastInput *input)
	Ray cast versus height field in local space. A thin surface with no interior, so there is no overlap case.
b3CastOutput	b3ShapeCastSphere (const b3Sphere *shape, const b3ShapeCastInput *input)
	Shape cast versus a sphere. Initial overlap is treated as a miss.
b3CastOutput	b3ShapeCastCapsule (const b3Capsule *shape, const b3ShapeCastInput *input)
	Shape cast versus a capsule. Initial overlap is treated as a miss.
b3CastOutput	b3ShapeCastCompound (const b3CompoundData *shape, const b3ShapeCastInput *input)
	Shape cast versus compound. Initial overlap is treated as a miss.
b3CastOutput	b3ShapeCastHull (const b3HullData *shape, const b3ShapeCastInput *input)
	Shape cast versus a hull. Initial overlap is treated as a miss.
b3CastOutput	b3ShapeCastMesh (const b3Mesh *shape, const b3ShapeCastInput *input)
	Shape cast versus a mesh. Initial overlap is treated as a miss.
b3CastOutput	b3ShapeCastHeightField (const b3HeightFieldData *shape, const b3ShapeCastInput *input)
	Shape cast versus a height field. Initial overlap is treated as a miss.
void	b3QueryMesh (const b3Mesh *mesh, const b3AABB bounds, b3MeshQueryFcn *fcn, void *context)
	Query a mesh for triangles overlapping a bounding box in local space.
void	b3QueryHeightField (const b3HeightFieldData *heightField, b3AABB bounds, b3MeshQueryFcn *fcn, void *context)
	Query a height field for triangles overlapping a bounding box in local space.
b3DistanceOutput	b3ShapeDistance (const b3DistanceInput *input, b3SimplexCache *cache, b3Simplex *simplexes, int simplexCapacity)
	Compute the closest points between two shapes represented as point clouds.
b3CastOutput	b3ShapeCast (const b3ShapeCastPairInput *input)
	Perform a linear shape cast of shape B moving and shape A fixed.
b3Transform	b3GetSweepTransform (const b3Sweep *sweep, float time)
	Evaluate the transform sweep at a specific time.
b3TOIOutput	b3TimeOfImpact (const b3TOIInput *input)
	Compute the upper bound on time before two shapes penetrate.
b3QueryFilter	b3DefaultQueryFilter (void)
	Use this to initialize your query filter.

Detailed Description

Query types and functions.

Queries include ray casts, shapes casts, overlap, distance, and time of impact.

---

Data Structure Documentation

b3QueryFilter

struct b3QueryFilter

The query filter is used to filter collisions between queries and shapes.

For example, you may want a ray-cast representing a projectile to hit players and the static environment but not debris.

Data Fields
uint64_t	categoryBits	The collision category bits of this query. Normally you would just set one bit.
uint64_t	id	Optional id combined with name to identify this query in a recording, e.g. an entity id. Need not be unique on its own. 0 with a null name means untagged. Ignored when not recording.
uint64_t	maskBits	The collision mask bits. This states the shape categories that this query would accept for collision.
const char *	name	Optional label combined with Ids to identify this query, e.g. "bullet". Need not be unique on its own. The recorder hashes (id, name) into one stable key the viewer tracks the query by, so the same id and name pair identifies the same query across frames. NULL means none. Ignored when not recording.

b3RayCastInput

struct b3RayCastInput

Low level ray cast input data.

Collaboration diagram for b3RayCastInput:

Data Fields
float	maxFraction	The maximum fraction of the translation to consider, typically 1.
b3Vec3	origin	Start point of the ray cast.
b3Vec3	translation	Translation of the ray cast. end = start + translation.

b3RayResult

struct b3RayResult

Result from b3World_RayCastClosest.

Collaboration diagram for b3RayResult:

Data Fields
int	childIndex	The child index if the shape is a compound.
float	fraction	The fraction of the input ray.
bool	hit	Did the ray hit? If false, all other data is invalid.
int	leafVisits	The number of BVH leaves visited. Diagnostic.
int	nodeVisits	The number of BVH nodes visited. Diagnostic.
b3Vec3	normal	The world normal of the shape surface at the hit point.
b3Pos	point	The world point of the hit.
b3ShapeId	shapeId	The shape hit.
int	triangleIndex	The triangle index if the shape is a mesh, height-field, or compound with child mesh.
uint64_t	userMaterialId	The user material id at the hit point. This can be per triangle if the shape is a mesh, height-field, or compound with child mesh.

b3ShapeProxy

struct b3ShapeProxy

A shape proxy is used by the GJK algorithm. It can represent a convex shape.

Collaboration diagram for b3ShapeProxy:

Data Fields
int	count	The number of points. Do not exceed B3_MAX_SHAPE_CAST_POINTS.
const b3Vec3 *	points	The point cloud.
float	radius	The external radius of the point cloud.

b3ShapeCastInput

struct b3ShapeCastInput

Low level shape cast input in generic form.

This allows casting an arbitrary point cloud wrap with a radius. For example, a sphere 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 b3ShapeCastInput:

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.
b3ShapeProxy	proxy	A generic query shape.
b3Vec3	translation	The translation of the shape cast.

b3BoxCastInput

struct b3BoxCastInput

Input for sweeping an AABB through a dynamic tree.

The box is in the tree's world float frame. The caller folds the cast shape radius and any world origin into the box, so the tree traversal stays a conservative box sweep and the precise narrow phase happens per shape in the callback.

Collaboration diagram for b3BoxCastInput:

Data Fields
b3AABB	box	The AABB to cast, in the tree's frame.
float	maxFraction	The maximum fraction of the translation to consider, typically 1.
b3Vec3	translation	The sweep translation.

b3CastOutput

struct b3CastOutput

Low level ray cast or shape-cast output data.

Collaboration diagram for b3CastOutput:

Data Fields
int	childIndex	The index of the compound child shape.
float	fraction	The fraction of the input translation at collision.
bool	hit	Did the cast hit?
int	iterations	The number of iterations used.
int	materialIndex	The material index. May be -1 for null.
b3Vec3	normal	The surface normal at the hit point.
b3Vec3	point	The surface hit point.
int	triangleIndex	The index of the mesh or height field triangle hit.

b3BodyCastResult

struct b3BodyCastResult

Body cast result for ray and shape casts.

Collaboration diagram for b3BodyCastResult:

Data Fields
float	fraction	The fraction along the ray hit. hit point = origin + fraction * translation
bool	hit	Did the cast hit? If false, all other fields are invalid.
int	iterations	The number of iterations used. Diagnostic.
b3Vec3	normal	The world normal vector on the shape surface.
b3Pos	point	The world point on the shape surface.
b3ShapeId	shapeId	The shape hit.
int	triangleIndex	The triangle index if the shape is a mesh or height-field.
uint64_t	userMaterialId	The user material id at the hit point. This can be per triangle if the shape is a mesh, height-field, or compound with child mesh.

b3SimplexCache

struct b3SimplexCache

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[4]	The cached simplex indices on shape A.
uint8_t	indexB[4]	The cached simplex indices on shape B.
float	metric	Value use to compare length, area, volume of two simplexes.

b3ShapeCastPairInput

struct b3ShapeCastPairInput

Input parameters for b3ShapeCast.

Collaboration diagram for b3ShapeCastPairInput:

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.
b3ShapeProxy	proxyA	The proxy for shape A.
b3ShapeProxy	proxyB	The proxy for shape B.
b3Transform	transform	Transform of shape B in shape A's frame, the relative pose B in A.
b3Vec3	translationB	The translation of shape B, in A's frame.

b3DistanceInput

struct b3DistanceInput

Input for b3ShapeDistance.

Collaboration diagram for b3DistanceInput:

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

b3DistanceOutput

struct b3DistanceOutput

Output for b3ShapeDistance.

Collaboration diagram for b3DistanceOutput:

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

b3SimplexVertex

struct b3SimplexVertex

Simplex vertex for debugging the GJK algorithm.

Collaboration diagram for b3SimplexVertex:

Data Fields
float	a	barycentric coordinates
int	indexA	wA index
int	indexB	wB index
b3Vec3	w	wB - wA
b3Vec3	wA	support point in proxyA
b3Vec3	wB	support point in proxyB

b3Simplex

struct b3Simplex

Simplex from the GJK algorithm.

Collaboration diagram for b3Simplex:

Data Fields
int	count	number of valid vertices
b3SimplexVertex	vertices[4]	vertices

b3Sweep

struct b3Sweep

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 b3Sweep:

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

b3TOIInput

struct b3TOIInput

Time of impact input.

Collaboration diagram for b3TOIInput:

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

b3TOIOutput

struct b3TOIOutput

Time of impact output.

Collaboration diagram for b3TOIOutput:

Data Fields
float	distance	The final distance.
int	distanceIterations	Number of outer iterations.
float	fraction	The sweep time of the collision.
b3Vec3	normal	The hit normal.
b3Vec3	point	The hit point.
int	pushBackIterations	Total number of push back iterations.
int	rootIterations	Total number of root iterations.
b3TOIState	state	The type of result.
bool	usedFallback	Indicates that the time of impact detected initial overlap and used a fallback sphere as a last ditch effort to prevent tunneling.

Function Documentation

b3QueryHeightField()

void b3QueryHeightField	(	const b3HeightFieldData *	heightField,
		b3AABB	bounds,
		b3MeshQueryFcn *	fcn,
		void *	context )

Query a height field for triangles overlapping a bounding box in local space.

May have false positives. Useful for debug draw.

Parameters

heightField	the height field to query
bounds	the bounding box in local space
fcn	a user function to collect triangles
context	the context sent to the user function.

b3QueryMesh()

void b3QueryMesh	(	const b3Mesh *	mesh,
		const b3AABB	bounds,
		b3MeshQueryFcn *	fcn,
		void *	context )

Query a mesh for triangles overlapping a bounding box in local space.

May have false positives. Useful for debug draw.

Parameters

mesh	the mesh to query, includes scale
bounds	the bounding box in local space
fcn	a user function to collect triangles
context	the context sent to the user function.

b3RayCastCapsule()

b3CastOutput b3RayCastCapsule	(	const b3Capsule *	shape,
		const b3RayCastInput *	input )

Ray cast versus capsule in local space.

A zero length ray is a point query. Initial overlap reports a hit at the ray origin with zero fraction and zero normal.

b3RayCastCompound()

b3CastOutput b3RayCastCompound	(	const b3CompoundData *	shape,
		const b3RayCastInput *	input )

Ray cast versus compound in local space.

A zero length ray is a point query. Initial overlap with a child reports a hit at the ray origin with zero fraction and zero normal.

b3RayCastHollowSphere()

b3CastOutput b3RayCastHollowSphere	(	const b3Sphere *	shape,
		const b3RayCastInput *	input )

Ray cast versus a hollow sphere shell in local space.

Unlike the solid sphere a ray starting inside is not an overlap: it passes through and hits the far wall.

b3RayCastHull()

b3CastOutput b3RayCastHull	(	const b3HullData *	shape,
		const b3RayCastInput *	input )

Ray cast versus hull shape in local space.

A zero length ray is a point query. Initial overlap reports a hit at the ray origin with zero fraction and zero normal.

b3RayCastSphere()

b3CastOutput b3RayCastSphere	(	const b3Sphere *	shape,
		const b3RayCastInput *	input )

Ray cast versus sphere in local space.

A zero length ray is a point query. Initial overlap reports a hit at the ray origin with zero fraction and zero normal.

b3ShapeCast()

b3CastOutput b3ShapeCast

(

const b3ShapeCastPairInput *

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 are a miss.

b3ShapeDistance()

b3DistanceOutput b3ShapeDistance	(	const b3DistanceInput *	input,
		b3SimplexCache *	cache,
		b3Simplex *	simplexes,
		int	simplexCapacity )

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

b3SimplexCache cache is input/output. On the first call set b3SimplexCache.count to zero. The query runs in frame A, so the witness points and normal are returned in frame A. The underlying GJK algorithm may be debugged by passing in debug simplexes and capacity. You may pass in NULL and 0 for these.

b3TimeOfImpact()

b3TOIOutput b3TimeOfImpact

(

const b3TOIInput *

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.