Functions to create, destroy, and access. More...

Data Structures
struct	b3Filter
	This is used to filter collision on shapes. More...
struct	b3SurfaceMaterial
	Material properties supported per triangle on meshes and height fields. More...
struct	b3ShapeDef
	Used to create a shape. More...

Enumerations
enum	b3ShapeType { b3_capsuleShape , b3_compoundShape , b3_heightShape , b3_hullShape , b3_meshShape , b3_sphereShape , b3_shapeTypeCount }
	Shape type. More...

Functions
b3ShapeId	b3CreateSphereShape (b3BodyId bodyId, const b3ShapeDef def, const b3Sphere sphere)
	Create a circle shape and attach it to a body.
b3ShapeId	b3CreateCapsuleShape (b3BodyId bodyId, const b3ShapeDef def, const b3Capsule capsule)
	Create a capsule shape and attach it to a body.
b3ShapeId	b3CreateHullShape (b3BodyId bodyId, const b3ShapeDef def, const b3HullData hull)
	Create a convex hull shape and attach it to a body.
b3ShapeId	b3CreateTransformedHullShape (b3BodyId bodyId, const b3ShapeDef def, const b3HullData hull, b3Transform transform, b3Vec3 scale)
	Create a convex hull shape and attach it to a body.
b3ShapeId	b3CreateMeshShape (b3BodyId bodyId, const b3ShapeDef def, const b3MeshData mesh, b3Vec3 scale)
	Create a mesh hull shape and attach it to a body.
b3ShapeId	b3CreateHeightFieldShape (b3BodyId bodyId, const b3ShapeDef def, const b3HeightFieldData heightField)
	Create a height-field shape and attach it to a body.
b3ShapeId	b3CreateCompoundShape (b3BodyId bodyId, b3ShapeDef def, const b3CompoundData compound)
	Compound shapes are only allowed on static bodies.
void	b3DestroyShape (b3ShapeId shapeId, bool updateBodyMass)
	Destroy a shape.
bool	b3Shape_IsValid (b3ShapeId id)
	Shape identifier validation. Provides validation for up to 64K allocations.
b3ShapeType	b3Shape_GetType (b3ShapeId shapeId)
	Get the type of a shape.
b3BodyId	b3Shape_GetBody (b3ShapeId shapeId)
	Get the id of the body that a shape is attached to.
b3WorldId	b3Shape_GetWorld (b3ShapeId shapeId)
	Get the world that owns this shape.
bool	b3Shape_IsSensor (b3ShapeId shapeId)
	Returns true if the shape is a sensor.
void	b3Shape_SetUserData (b3ShapeId shapeId, void *userData)
	Set the user data for a shape.
void *	b3Shape_GetUserData (b3ShapeId shapeId)
	Get the user data for a shape.
void	b3Shape_SetDensity (b3ShapeId shapeId, float density, bool updateBodyMass)
	Set the mass density of a shape, usually in kg/m^3.
float	b3Shape_GetDensity (b3ShapeId shapeId)
	Get the density of a shape, usually in kg/m^3.
void	b3Shape_SetFriction (b3ShapeId shapeId, float friction)
	Set the friction on a shape.
float	b3Shape_GetFriction (b3ShapeId shapeId)
	Get the friction of a shape.
void	b3Shape_SetRestitution (b3ShapeId shapeId, float restitution)
	Set the shape restitution (bounciness).
float	b3Shape_GetRestitution (b3ShapeId shapeId)
	Get the shape restitution.
void	b3Shape_SetSurfaceMaterial (b3ShapeId shapeId, b3SurfaceMaterial surfaceMaterial)
	Set the shape base surface material. Does not change per triangle materials.
b3SurfaceMaterial	b3Shape_GetSurfaceMaterial (b3ShapeId shapeId)
	Get the base shape surface material.
int	b3Shape_GetMeshMaterialCount (b3ShapeId shapeId)
	Get the number of mesh surface materials.
void	b3Shape_SetMeshMaterial (b3ShapeId shapeId, b3SurfaceMaterial surfaceMaterial, int index)
	Set a surface material for a mesh shape.
b3SurfaceMaterial	b3Shape_GetMeshSurfaceMaterial (b3ShapeId shapeId, int index)
	Get a surface material for a mesh shape.
b3Filter	b3Shape_GetFilter (b3ShapeId shapeId)
	Get the shape filter.
void	b3Shape_SetFilter (b3ShapeId shapeId, b3Filter filter, bool invokeContacts)
	Set the current filter.
void	b3Shape_EnableSensorEvents (b3ShapeId shapeId, bool flag)
	Enable sensor events for this shape.
bool	b3Shape_AreSensorEventsEnabled (b3ShapeId shapeId)
	Returns true if sensor events are enabled.
void	b3Shape_EnableContactEvents (b3ShapeId shapeId, bool flag)
	Enable contact events for this shape.
bool	b3Shape_AreContactEventsEnabled (b3ShapeId shapeId)
	Returns true if contact events are enabled.
void	b3Shape_EnablePreSolveEvents (b3ShapeId shapeId, bool flag)
	Enable pre-solve contact events for this shape.
bool	b3Shape_ArePreSolveEventsEnabled (b3ShapeId shapeId)
	Returns true if pre-solve events are enabled.
void	b3Shape_EnableHitEvents (b3ShapeId shapeId, bool flag)
	Enable contact hit events for this shape.
bool	b3Shape_AreHitEventsEnabled (b3ShapeId shapeId)
	Returns true if hit events are enabled.
b3WorldCastOutput	b3Shape_RayCast (b3ShapeId shapeId, b3Pos origin, b3Vec3 translation)
	Ray cast a shape directly.
b3Sphere	b3Shape_GetSphere (b3ShapeId shapeId)
	Get a copy of the shape's sphere. Asserts the type is correct.
b3Capsule	b3Shape_GetCapsule (b3ShapeId shapeId)
	Get a copy of the shape's capsule. Asserts the type is correct.
const b3HullData *	b3Shape_GetHull (b3ShapeId shapeId)
	Get the shape's convex hull. Asserts the type is correct.
b3Mesh	b3Shape_GetMesh (b3ShapeId shapeId)
	Get the shape's mesh. Asserts the type is correct.
const b3HeightFieldData *	b3Shape_GetHeightField (b3ShapeId shapeId)
	Get the shape's height field. Asserts the type is correct.
void	b3Shape_SetSphere (b3ShapeId shapeId, const b3Sphere *sphere)
	Allows you to change a shape to be a sphere or update the current sphere.
void	b3Shape_SetCapsule (b3ShapeId shapeId, const b3Capsule *capsule)
	Allows you to change a shape to be a capsule or update the current capsule.
void	b3Shape_SetHull (b3ShapeId shapeId, const b3HullData *hull)
	Allows you to change a shape to be a hull or update the current hull.
void	b3Shape_SetMesh (b3ShapeId shapeId, const b3MeshData *meshData, b3Vec3 scale)
	Allows you to change a shape to be a mesh or update the current mesh.
int	b3Shape_GetContactCapacity (b3ShapeId shapeId)
	Get the maximum capacity required for retrieving all the touching contacts on a shape.
int	b3Shape_GetContactData (b3ShapeId shapeId, b3ContactData *contactData, int capacity)
	Get the touching contact data for a shape.
int	b3Shape_GetSensorCapacity (b3ShapeId shapeId)
	Get the maximum capacity required for retrieving all the overlapped shapes on a sensor shape.
int	b3Shape_GetSensorData (b3ShapeId shapeId, b3ShapeId *visitorIds, int capacity)
	Get the overlap data for a sensor shape.
b3AABB	b3Shape_GetAABB (b3ShapeId shapeId)
	Get the current world AABB.
b3MassData	b3Shape_ComputeMassData (b3ShapeId shapeId)
	Compute the mass data for a shape.
b3Vec3	b3Shape_GetClosestPoint (b3ShapeId shapeId, b3Vec3 target)
	Get the closest point on a shape to a target point. Target and result are in world space.
void	b3Shape_ApplyWind (b3ShapeId shapeId, b3Vec3 wind, float drag, float lift, float maxSpeed, bool wake)
	Apply a wind force to the body for this shape using the density of air.
b3Filter	b3DefaultFilter (void)
	Use this to initialize your filter.
b3SurfaceMaterial	b3DefaultSurfaceMaterial (void)
	Use this to initialize your surface material.
b3ShapeDef	b3DefaultShapeDef (void)
	Use this to initialize your shape definition.

Detailed Description

Functions to create, destroy, and access.

Shapes bind raw geometry to bodies and hold material properties including friction and restitution.

Data Structure Documentation

◆ b3Filter

struct b3Filter

This is used to filter collision on shapes.

It affects shape-vs-shape collision and shape-versus-query collision (such as b3World_CastRay).

Data Fields
uint64_t	categoryBits	The collision category bits. Normally you would just set one bit. The category bits should represent your application object types. For example: enum MyCategories { Static = 0x00000001, Dynamic = 0x00000002, Debris = 0x00000004, Player = 0x00000008, // etc };
int	groupIndex	Collision groups allow a certain group of objects to never collide (negative) or always collide (positive). A group index of zero has no effect. Non-zero group filtering always wins against the mask bits. For example, you may want ragdolls to collide with other ragdolls but you don't want ragdoll self-collision. In this case you would give each ragdoll a unique negative group index and apply that group index to all shapes on the ragdoll.
uint64_t	maskBits	The collision mask bits. This states the categories that this shape would accept for collision. For example, you may want your player to only collide with static objects and other players. maskBits = Static \| Player; b3Filter::maskBits uint64_t maskBits The collision mask bits. Definition types.h:381

◆ b3SurfaceMaterial

struct b3SurfaceMaterial

Material properties supported per triangle on meshes and height fields.

Collaboration diagram for b3SurfaceMaterial:

[legend]

Data Fields
uint32_t	customColor	Custom debug draw color. Ignored if 0. The low 24 bits are RGB. The high byte may carry a b3DebugMaterial preset, see b3MakeDebugColor. See also b3HexColor
float	friction	The Coulomb (dry) friction coefficient, usually in the range [0,1].
float	restitution	The coefficient of restitution (bounce) usually in the range [0,1]. https://en.wikipedia.org/wiki/Coefficient_of_restitution
float	rollingResistance	The rolling resistance usually in the range [0,1]. This is only used for spheres and capsules.
b3Vec3	tangentVelocity	The tangent velocity for conveyor belts. This is local to the shape and will be projected onto the contact surface.
uint64_t	userMaterialId	User material identifier. This is passed with query results and to friction and restitution combining functions. It is not used internally.

◆ b3ShapeDef

struct b3ShapeDef

Used to create a shape.

Collaboration diagram for b3ShapeDef:

[legend]

Data Fields
b3SurfaceMaterial	baseMaterial	The base surface material. Ignored for compound shapes.
float	density	The density, usually in kg/m^3.
bool	enableContactEvents	Enable contact events for this shape. Only applies to kinematic and dynamic bodies. Ignored for sensors. False by default.
bool	enableCustomFiltering	Enable custom filtering. Only one of the two shapes needs to enable custom filtering. See b3WorldDef.
bool	enableHitEvents	Enable hit events for this shape. Only applies to kinematic and dynamic bodies. Ignored for sensors. False by default.
bool	enablePreSolveEvents	Enable pre-solve contact events for this shape. Only applies to dynamic bodies. These are expensive and must be carefully handled due to multithreading. Ignored for sensors.
bool	enableSensorEvents	Enable sensor events for this shape. This applies to sensors and non-sensors. False by default, even for sensors.
float	explosionScale	Explosion scale for b3World_Explode. non-dimensional.
b3Filter	filter	Contact filtering data.
int	internalValue	Used internally to detect a valid definition. DO NOT SET.
bool	invokeContactCreation	When shapes are created they will scan the environment for collision the next time step. This can significantly slow down static body creation when there are many static shapes. This is flag is ignored for dynamic and kinematic shapes which always invoke contact creation.
bool	isSensor	A sensor shape generates overlap events but never generates a collision response. Sensors do not have continuous collision. Instead, use a ray or shape cast for those scenarios. Sensors still contribute to the body mass if they have non-zero density. Note Sensor events are disabled by default. See also enableSensorEvents
int	materialCount	Surface material count.
b3SurfaceMaterial *	materials	Surface material used on mesh shapes per triangle. Ignored for convex shapes. Ignored for compound shapes.
bool	updateBodyMass	Should the body update the mass properties when this shape is created. Default is true.
void *	userData	Use this to store application specific shape data.

Enumeration Type Documentation

◆ b3ShapeType

enum b3ShapeType

Shape type.

Enumerator
b3_capsuleShape	A capsule is an extruded sphere.
b3_compoundShape	A compound shape composed of up to 64K spheres, capsules, hulls, and meshes.
b3_heightShape	A height field useful for terrain.
b3_hullShape	A convex hull.
b3_meshShape	A triangle soup.
b3_sphereShape	A sphere with an offset.
b3_shapeTypeCount	The number of shape types.

Function Documentation

◆ b3CreateCapsuleShape()

b3ShapeId b3CreateCapsuleShape	(	b3BodyId	bodyId,
		const b3ShapeDef *	def,
		const b3Capsule *	capsule )

Create a capsule shape and attach it to a body.

The shape definition and geometry are fully cloned. Contacts are not created until the next time step.

Returns: the shape id for accessing the shape

◆ b3CreateHeightFieldShape()

b3ShapeId b3CreateHeightFieldShape	(	b3BodyId	bodyId,
		const b3ShapeDef *	def,
		const b3HeightFieldData *	heightField )

Create a height-field shape and attach it to a body.

The shape definition is fully cloned but the height field is not. Contacts are not created until the next time step. Height field is only allowed on static bodies.

Warning: this holds reference to the input height field which must remain valid for the lifetime of this shape

Returns: the shape id for accessing the shape

◆ b3CreateHullShape()

b3ShapeId b3CreateHullShape	(	b3BodyId	bodyId,
		const b3ShapeDef *	def,
		const b3HullData *	hull )

Create a convex hull shape and attach it to a body.

The shape definition is fully cloned. Contacts are not created until the next time step.

Returns: the shape id for accessing the shape

◆ b3CreateMeshShape()

b3ShapeId b3CreateMeshShape	(	b3BodyId	bodyId,
		const b3ShapeDef *	def,
		const b3MeshData *	mesh,
		b3Vec3	scale )

Create a mesh hull shape and attach it to a body.

The shape definition is fully cloned but the mesh is not. Contacts are not created until the next time step. Mesh collision only creates contacts on static bodies.

Warning: this holds reference to the input mesh data which must remain valid for the lifetime of this shape

Returns: the shape id for accessing the shape

◆ b3CreateSphereShape()

b3ShapeId b3CreateSphereShape	(	b3BodyId	bodyId,
		const b3ShapeDef *	def,
		const b3Sphere *	sphere )

Create a circle shape and attach it to a body.

The shape definition and geometry are fully cloned. Contacts are not created until the next time step.

Returns: the shape id for accessing the shape

◆ b3CreateTransformedHullShape()

b3ShapeId b3CreateTransformedHullShape	(	b3BodyId	bodyId,
		const b3ShapeDef *	def,
		const b3HullData *	hull,
		b3Transform	transform,
		b3Vec3	scale )

Create a convex hull shape and attach it to a body.

The hull is cloned then transformed with scale applied first. Use this for non-uniform or mirrored scale or a baked local transform. The baked result is shared through the world hull database. The shape definition and geometry are fully cloned. Contacts are not created until the next time step.

Returns: the shape id for accessing the shape

◆ b3DestroyShape()

void b3DestroyShape	(	b3ShapeId	shapeId,
		bool	updateBodyMass )

Destroy a shape.

You may defer the body mass update which can improve performance if several shapes on a body are destroyed at once.

See also: b3Body_ApplyMassFromShapes

◆ b3Shape_ApplyWind()

void b3Shape_ApplyWind	(	b3ShapeId	shapeId,
		b3Vec3	wind,
		float	drag,
		float	lift,
		float	maxSpeed,
		bool	wake )

Apply a wind force to the body for this shape using the density of air.

This considers the projected area of the shape in the wind direction. This also considers the relative velocity of the shape.

Parameters

shapeId	the shape id
wind	the wind velocity in world space
drag	the drag coefficient, the force that opposes the relative velocity
lift	the lift coefficient, the force that is perpendicular to the relative velocity
maxSpeed	the maximum relative speed. Speed cap is necessary for stability. Typically 10m/s or less.
wake	should this wake the body

◆ b3Shape_EnableContactEvents()

void b3Shape_EnableContactEvents	(	b3ShapeId	shapeId,
		bool	flag )

Enable contact events for this shape.

Only applies to kinematic and dynamic bodies. Ignored for sensors.

See also: b3ShapeDef::enableContactEvents

◆ b3Shape_EnableHitEvents()

void b3Shape_EnableHitEvents	(	b3ShapeId	shapeId,
		bool	flag )

Enable contact hit events for this shape.

Ignored for sensors.

See also: b3WorldDef.hitEventThreshold

◆ b3Shape_EnablePreSolveEvents()

void b3Shape_EnablePreSolveEvents	(	b3ShapeId	shapeId,
		bool	flag )

Enable pre-solve contact events for this shape.

Only applies to dynamic bodies. These are expensive and must be carefully handled due to multithreading. Ignored for sensors.

See also: b3PreSolveFcn

◆ b3Shape_EnableSensorEvents()

void b3Shape_EnableSensorEvents	(	b3ShapeId	shapeId,
		bool	flag )

Enable sensor events for this shape.

Only applies to kinematic and dynamic bodies. Ignored for sensors.

See also: b3ShapeDef::isSensor

◆ b3Shape_GetContactData()

int b3Shape_GetContactData	(	b3ShapeId	shapeId,
		b3ContactData *	contactData,
		int	capacity )

Get the touching contact data for a shape.

The provided shapeId will be either shapeIdA or shapeIdB on the contact data.

Note: Box3D uses speculative collision so some contact points may be separated.

Returns: the number of elements filled in the provided array

Warning: do not ignore the return value, it specifies the valid number of elements

◆ b3Shape_GetSensorCapacity()

int b3Shape_GetSensorCapacity ( b3ShapeId shapeId )

Get the maximum capacity required for retrieving all the overlapped shapes on a sensor shape.

This returns 0 if the provided shape is not a sensor.

Parameters

shapeId the id of a sensor shape

Returns: the required capacity to get all the overlaps in b3Shape_GetSensorOverlaps

◆ b3Shape_GetSensorData()

int b3Shape_GetSensorData	(	b3ShapeId	shapeId,
		b3ShapeId *	visitorIds,
		int	capacity )

Get the overlap data for a sensor shape.

Parameters

shapeId	the id of a sensor shape
visitorIds	a user allocated array that is filled with the overlapping shapes (visitors)
capacity	the capacity of overlappedShapes

Returns: the number of elements filled in the provided array

Warning: do not ignore the return value, it specifies the valid number of elements; overlaps may contain destroyed shapes so use b3Shape_IsValid to confirm each overlap

◆ b3Shape_GetUserData()

void * b3Shape_GetUserData ( b3ShapeId shapeId )

Get the user data for a shape.

This is useful when you get a shape id from an event or query.

◆ b3Shape_RayCast()

b3WorldCastOutput b3Shape_RayCast	(	b3ShapeId	shapeId,
		b3Pos	origin,
		b3Vec3	translation )

Ray cast a shape directly.

The ray runs from origin to origin + translation and the hit point comes back as a world position, so the cast stays precise far from the world origin.

◆ b3Shape_SetCapsule()

void b3Shape_SetCapsule	(	b3ShapeId	shapeId,
		const b3Capsule *	capsule )

Allows you to change a shape to be a capsule or update the current capsule.

This does not modify the mass properties.

See also: b3Body_ApplyMassFromShapes

◆ b3Shape_SetDensity()

void b3Shape_SetDensity	(	b3ShapeId	shapeId,
		float	density,
		bool	updateBodyMass )

Set the mass density of a shape, usually in kg/m^3.

This will optionally update the mass properties on the parent body.

See also: b3ShapeDef::density, b3Body_ApplyMassFromShapes

◆ b3Shape_SetFilter()

void b3Shape_SetFilter	(	b3ShapeId	shapeId,
		b3Filter	filter,
		bool	invokeContacts )

Set the current filter.

This is almost as expensive as recreating the shape.

See also: b3ShapeDef::filter

Parameters

shapeId	the shape
filter	the new filter
invokeContacts	if true then the shape will have all contacts recomputed the next time step (expensive)

◆ b3Shape_SetHull()

void b3Shape_SetHull	(	b3ShapeId	shapeId,
		const b3HullData *	hull )

Allows you to change a shape to be a hull or update the current hull.

This does not modify the mass properties.

See also: b3Body_ApplyMassFromShapes

◆ b3Shape_SetMesh()

void b3Shape_SetMesh	(	b3ShapeId	shapeId,
		const b3MeshData *	meshData,
		b3Vec3	scale )

Allows you to change a shape to be a mesh or update the current mesh.

This does not modify the mass properties.

See also: b3Body_ApplyMassFromShapes

◆ b3Shape_SetSphere()

void b3Shape_SetSphere	(	b3ShapeId	shapeId,
		const b3Sphere *	sphere )

Allows you to change a shape to be a sphere or update the current sphere.

This does not modify the mass properties.

See also: b3Body_ApplyMassFromShapes

Data Structures

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ b3Filter

◆ b3SurfaceMaterial

◆ b3ShapeDef

Enumeration Type Documentation

◆ b3ShapeType

Function Documentation

◆ b3CreateCapsuleShape()

◆ b3CreateHeightFieldShape()

◆ b3CreateHullShape()

◆ b3CreateMeshShape()

◆ b3CreateSphereShape()

◆ b3CreateTransformedHullShape()

◆ b3DestroyShape()

◆ b3Shape_ApplyWind()

◆ b3Shape_EnableContactEvents()

◆ b3Shape_EnableHitEvents()

◆ b3Shape_EnablePreSolveEvents()

◆ b3Shape_EnableSensorEvents()

◆ b3Shape_GetContactData()

◆ b3Shape_GetSensorCapacity()

◆ b3Shape_GetSensorData()

◆ b3Shape_GetUserData()

◆ b3Shape_RayCast()

◆ b3Shape_SetCapsule()

◆ b3Shape_SetDensity()

◆ b3Shape_SetFilter()

◆ b3Shape_SetHull()

◆ b3Shape_SetMesh()

◆ b3Shape_SetSphere()