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

Data Structures
struct	b2Filter
	This is used to filter collision on shapes. More...

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

struct	b2ShapeDef
	Used to create a shape. More...

struct	b2ChainDef
	Used to create a chain of line segments. More...

Enumerations
enum	b2ShapeType { b2_circleShape , b2_capsuleShape , b2_segmentShape , b2_polygonShape , b2_chainSegmentShape , b2_shapeTypeCount }
	Shape type. More...

Functions
b2ShapeId	b2CreateCircleShape (b2BodyId bodyId, const b2ShapeDef def, const b2Circle circle)
	Create a circle shape and attach it to a body.

b2ShapeId	b2CreateSegmentShape (b2BodyId bodyId, const b2ShapeDef def, const b2Segment segment)
	Create a line segment shape and attach it to a body.

b2ShapeId	b2CreateCapsuleShape (b2BodyId bodyId, const b2ShapeDef def, const b2Capsule capsule)
	Create a capsule shape and attach it to a body.

b2ShapeId	b2CreatePolygonShape (b2BodyId bodyId, const b2ShapeDef def, const b2Polygon polygon)
	Create a polygon shape and attach it to a body.

void	b2DestroyShape (b2ShapeId shapeId)
	Destroy a shape.

bool	b2Shape_IsValid (b2ShapeId id)
	Shape identifier validation. Provides validation for up to 64K allocations.

b2ShapeType	b2Shape_GetType (b2ShapeId shapeId)
	Get the type of a shape.

b2BodyId	b2Shape_GetBody (b2ShapeId shapeId)
	Get the id of the body that a shape is attached to.

bool	b2Shape_IsSensor (b2ShapeId shapeId)
	Returns true If the shape is a sensor.

void	b2Shape_SetUserData (b2ShapeId shapeId, void *userData)
	Set the user data for a shape.

void *	b2Shape_GetUserData (b2ShapeId shapeId)
	Get the user data for a shape.

void	b2Shape_SetDensity (b2ShapeId shapeId, float density)
	Set the mass density of a shape, typically in kg/m^2.

float	b2Shape_GetDensity (b2ShapeId shapeId)
	Get the density of a shape, typically in kg/m^2.

void	b2Shape_SetFriction (b2ShapeId shapeId, float friction)
	Set the friction on a shape.

float	b2Shape_GetFriction (b2ShapeId shapeId)
	Get the friction of a shape.

void	b2Shape_SetRestitution (b2ShapeId shapeId, float restitution)
	Set the shape restitution (bounciness)

float	b2Shape_GetRestitution (b2ShapeId shapeId)
	Get the shape restitution.

b2Filter	b2Shape_GetFilter (b2ShapeId shapeId)
	Get the shape filter.

void	b2Shape_SetFilter (b2ShapeId shapeId, b2Filter filter)
	Set the current filter.

void	b2Shape_EnableSensorEvents (b2ShapeId shapeId, bool flag)
	Enable sensor events for this shape.

bool	b2Shape_AreSensorEventsEnabled (b2ShapeId shapeId)
	Returns true if sensor events are enabled.

void	b2Shape_EnableContactEvents (b2ShapeId shapeId, bool flag)
	Enable contact events for this shape.

bool	b2Shape_AreContactEventsEnabled (b2ShapeId shapeId)
	Returns true if contact events are enabled.

void	b2Shape_EnablePreSolveEvents (b2ShapeId shapeId, bool flag)
	Enable pre-solve contact events for this shape.

bool	b2Shape_ArePreSolveEventsEnabled (b2ShapeId shapeId)
	Returns true if pre-solve events are enabled.

void	b2Shape_EnableHitEvents (b2ShapeId shapeId, bool flag)
	Enable contact hit events for this shape.

bool	b2Shape_AreHitEventsEnabled (b2ShapeId shapeId)
	Returns true if hit events are enabled.

bool	b2Shape_TestPoint (b2ShapeId shapeId, b2Vec2 point)
	Test a point for overlap with a shape.

b2CastOutput	b2Shape_RayCast (b2ShapeId shapeId, const b2RayCastInput *input)
	Ray cast a shape directly.

b2Circle	b2Shape_GetCircle (b2ShapeId shapeId)
	Get a copy of the shape's circle. Asserts the type is correct.

b2Segment	b2Shape_GetSegment (b2ShapeId shapeId)
	Get a copy of the shape's line segment. Asserts the type is correct.

b2ChainSegment	b2Shape_GetChainSegment (b2ShapeId shapeId)
	Get a copy of the shape's chain segment.

b2Capsule	b2Shape_GetCapsule (b2ShapeId shapeId)
	Get a copy of the shape's capsule. Asserts the type is correct.

b2Polygon	b2Shape_GetPolygon (b2ShapeId shapeId)
	Get a copy of the shape's convex polygon. Asserts the type is correct.

void	b2Shape_SetCircle (b2ShapeId shapeId, const b2Circle *circle)
	Allows you to change a shape to be a circle or update the current circle.

void	b2Shape_SetCapsule (b2ShapeId shapeId, const b2Capsule *capsule)
	Allows you to change a shape to be a capsule or update the current capsule.

void	b2Shape_SetSegment (b2ShapeId shapeId, const b2Segment *segment)
	Allows you to change a shape to be a segment or update the current segment.

void	b2Shape_SetPolygon (b2ShapeId shapeId, const b2Polygon *polygon)
	Allows you to change a shape to be a polygon or update the current polygon.

b2ChainId	b2Shape_GetParentChain (b2ShapeId shapeId)
	Get the parent chain id if the shape type is a chain segment, otherwise returns b2_nullChainId.

int	b2Shape_GetContactCapacity (b2ShapeId shapeId)
	Get the maximum capacity required for retrieving all the touching contacts on a shape.

int	b2Shape_GetContactData (b2ShapeId shapeId, b2ContactData *contactData, int capacity)
	Get the touching contact data for a shape. The provided shapeId will be either shapeIdA or shapeIdB on the contact data.

b2AABB	b2Shape_GetAABB (b2ShapeId shapeId)
	Get the current world AABB.

b2Vec2	b2Shape_GetClosestPoint (b2ShapeId shapeId, b2Vec2 target)
	Get the closest point on a shape to a target point. Target and result are in world space.

b2ChainId	b2CreateChain (b2BodyId bodyId, const b2ChainDef *def)
	Chain Shape.

void	b2DestroyChain (b2ChainId chainId)
	Destroy a chain shape.

void	b2Chain_SetFriction (b2ChainId chainId, float friction)
	Set the chain friction.

void	b2Chain_SetRestitution (b2ChainId chainId, float restitution)
	Set the chain restitution (bounciness)

bool	b2Chain_IsValid (b2ChainId id)
	Chain identifier validation. Provides validation for up to 64K allocations.

b2Filter	b2DefaultFilter (void)
	Use this to initialize your filter.

b2QueryFilter	b2DefaultQueryFilter (void)
	Use this to initialize your query filter.

b2ShapeDef	b2DefaultShapeDef (void)
	Use this to initialize your shape definition.

b2ChainDef	b2DefaultChainDef (void)
	Use this to initialize your chain 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

◆ b2Filter

struct b2Filter

This is used to filter collision on shapes.

It affects shape-vs-shape collision and shape-versus-query collision (such as b2World_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 };
int32_t	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; b2Filter::maskBits uint64_t maskBits The collision mask bits. Definition types.h:246

◆ b2QueryFilter

struct b2QueryFilter

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	maskBits	The collision mask bits. This states the shape categories that this query would accept for collision.

◆ b2ShapeDef

struct b2ShapeDef

Used to create a shape.

This is a temporary object used to bundle shape creation parameters. You may use the same shape definition to create multiple shapes. Must be initialized using b2DefaultShapeDef().

Collaboration diagram for b2ShapeDef:

[legend]

Data Fields
uint32_t	customColor	Custom debug draw color.
float	density	The density, usually in kg/m^2.
bool	enableContactEvents	Enable contact events for this shape. Only applies to kinematic and dynamic bodies. Ignored for sensors.
bool	enableHitEvents	Enable hit events for this shape. Only applies to kinematic and dynamic bodies. Ignored for sensors.
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 threading. Ignored for sensors.
bool	enableSensorEvents	Enable sensor events for this shape. Only applies to kinematic and dynamic bodies. Ignored for sensors.
b2Filter	filter	Collision filtering data.
bool	forceContactCreation	Normally shapes on static bodies don't invoke contact creation when they are added to the world. This overrides that behavior and causes contact creation. This significantly slows down static body creation which can be important when there are many static shapes. This is implicitly always true for sensors.
float	friction	The Coulomb (dry) friction coefficient, usually in the range [0,1].
int32_t	internalValue	Used internally to detect a valid definition. DO NOT SET.
bool	isSensor	A sensor shape generates overlap events but never generates a collision response. Sensors do not collide with other sensors and do not have continuous collision. Instead use a ray or shape cast for those scenarios.
float	restitution	The restitution (bounce) usually in the range [0,1].
void *	userData	Use this to store application specific shape data.

◆ b2ChainDef

struct b2ChainDef

Used to create a chain of line segments.

This is designed to eliminate ghost collisions with some limitations.

chains are one-sided
chains have no mass and should be used on static bodies
chains have a counter-clockwise winding order
chains are either a loop or open
a chain must have at least 4 points
the distance between any two points must be greater than b2_linearSlop
a chain shape should not self intersect (this is not validated)
an open chain shape has NO COLLISION on the first and final edge
you may overlap two open chains on their first three and/or last three points to get smooth collision
a chain shape creates multiple line segment shapes on the body https://en.wikipedia.org/wiki/Polygonal_chain Must be initialized using b2DefaultChainDef().
Warning
Do not use chain shapes unless you understand the limitations. This is an advanced feature.

Collaboration diagram for b2ChainDef:

[legend]

Data Fields
int32_t	count	The point count, must be 4 or more.
b2Filter	filter	Contact filtering data.
float	friction	The friction coefficient, usually in the range [0,1].
int32_t	internalValue	Used internally to detect a valid definition. DO NOT SET.
bool	isLoop	Indicates a closed chain formed by connecting the first and last points.
const b2Vec2 *	points	An array of at least 4 points. These are cloned and may be temporary.
float	restitution	The restitution (elasticity) usually in the range [0,1].
void *	userData	Use this to store application specific shape data.

Enumeration Type Documentation

◆ b2ShapeType

enum b2ShapeType

Shape type.

Enumerator
b2_circleShape	A circle with an offset.
b2_capsuleShape	A capsule is an extruded circle.
b2_segmentShape	A line segment.
b2_polygonShape	A convex polygon.
b2_chainSegmentShape	A line segment owned by a chain shape.
b2_shapeTypeCount	The number of shape types.

Function Documentation

◆ b2Chain_SetFriction()

void b2Chain_SetFriction	(	b2ChainId	chainId,
		float	friction )

Set the chain friction.

See also: b2ChainDef::friction

◆ b2Chain_SetRestitution()

void b2Chain_SetRestitution	(	b2ChainId	chainId,
		float	restitution )

Set the chain restitution (bounciness)

See also: b2ChainDef::restitution

◆ b2CreateCapsuleShape()

b2ShapeId b2CreateCapsuleShape	(	b2BodyId	bodyId,
		const b2ShapeDef *	def,
		const b2Capsule *	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

◆ b2CreateChain()

b2ChainId b2CreateChain	(	b2BodyId	bodyId,
		const b2ChainDef *	def )

Chain Shape.

Create a chain shape

See also: b2ChainDef for details

◆ b2CreateCircleShape()

b2ShapeId b2CreateCircleShape	(	b2BodyId	bodyId,
		const b2ShapeDef *	def,
		const b2Circle *	circle )

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

◆ b2CreatePolygonShape()

b2ShapeId b2CreatePolygonShape	(	b2BodyId	bodyId,
		const b2ShapeDef *	def,
		const b2Polygon *	polygon )

Create a polygon 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

◆ b2CreateSegmentShape()

b2ShapeId b2CreateSegmentShape	(	b2BodyId	bodyId,
		const b2ShapeDef *	def,
		const b2Segment *	segment )

Create a line segment 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

◆ b2Shape_EnableContactEvents()

void b2Shape_EnableContactEvents	(	b2ShapeId	shapeId,
		bool	flag )

Enable contact events for this shape.

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

See also: b2ShapeDef::enableContactEvents

◆ b2Shape_EnableHitEvents()

void b2Shape_EnableHitEvents	(	b2ShapeId	shapeId,
		bool	flag )

Enable contact hit events for this shape.

Ignored for sensors.

See also: b2WorldDef.hitEventThreshold

◆ b2Shape_EnablePreSolveEvents()

void b2Shape_EnablePreSolveEvents	(	b2ShapeId	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: b2PreSolveFcn

◆ b2Shape_EnableSensorEvents()

void b2Shape_EnableSensorEvents	(	b2ShapeId	shapeId,
		bool	flag )

Enable sensor events for this shape.

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

See also: b2ShapeDef::isSensor

◆ b2Shape_GetChainSegment()

b2ChainSegment b2Shape_GetChainSegment ( b2ShapeId shapeId )

Get a copy of the shape's chain segment.

These come from chain shapes. Asserts the type is correct.

◆ b2Shape_GetUserData()

void * b2Shape_GetUserData ( b2ShapeId shapeId )

Get the user data for a shape.

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

◆ b2Shape_SetCapsule()

void b2Shape_SetCapsule	(	b2ShapeId	shapeId,
		const b2Capsule *	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: b2Body_ApplyMassFromShapes

◆ b2Shape_SetCircle()

void b2Shape_SetCircle	(	b2ShapeId	shapeId,
		const b2Circle *	circle )

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

This does not modify the mass properties.

See also: b2Body_ApplyMassFromShapes

◆ b2Shape_SetDensity()

void b2Shape_SetDensity	(	b2ShapeId	shapeId,
		float	density )

Set the mass density of a shape, typically in kg/m^2.

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

See also: b2ShapeDef::density, b2Body_ApplyMassFromShapes

◆ b2Shape_SetFilter()

void b2Shape_SetFilter	(	b2ShapeId	shapeId,
		b2Filter	filter )

Set the current filter.

This is almost as expensive as recreating the shape.

See also: b2ShapeDef::filter

◆ b2Shape_SetFriction()

void b2Shape_SetFriction	(	b2ShapeId	shapeId,
		float	friction )

Set the friction on a shape.

See also: b2ShapeDef::friction

◆ b2Shape_SetPolygon()

void b2Shape_SetPolygon	(	b2ShapeId	shapeId,
		const b2Polygon *	polygon )

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

This does not modify the mass properties.

See also: b2Body_ApplyMassFromShapes

◆ b2Shape_SetRestitution()

void b2Shape_SetRestitution	(	b2ShapeId	shapeId,
		float	restitution )

Set the shape restitution (bounciness)

See also: b2ShapeDef::restitution

Data Structures

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ b2Filter

◆ b2QueryFilter

◆ b2ShapeDef

◆ b2ChainDef

Enumeration Type Documentation

◆ b2ShapeType

Function Documentation

◆ b2Chain_SetFriction()

◆ b2Chain_SetRestitution()

◆ b2CreateCapsuleShape()

◆ b2CreateChain()

◆ b2CreateCircleShape()

◆ b2CreatePolygonShape()

◆ b2CreateSegmentShape()

◆ b2Shape_EnableContactEvents()

◆ b2Shape_EnableHitEvents()

◆ b2Shape_EnablePreSolveEvents()

◆ b2Shape_EnableSensorEvents()

◆ b2Shape_GetChainSegment()

◆ b2Shape_GetUserData()

◆ b2Shape_SetCapsule()

◆ b2Shape_SetCircle()

◆ b2Shape_SetDensity()

◆ b2Shape_SetFilter()

◆ b2Shape_SetFriction()

◆ b2Shape_SetPolygon()

◆ b2Shape_SetRestitution()