Functions to create, destroy, and access shapes. 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	b2SurfaceMaterial
	The surface material groups together parameters related to the shape surface, which is the 2D boundary. More...
struct	b2ShapeDef
	Used to create a shape. More...

Macros
#define	B2_DEFAULT_CATEGORY_BITS 1
	Default filter category bits.
#define	B2_DEFAULT_MASK_BITS UINT64_MAX
	Default filter mask bits.

Enumerations
enum	b2ShapeType
	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	b2CreateChainSegmentShape (b2BodyId bodyId, const b2ShapeDef def, const b2ChainSegment chainSegment)
	Create a chain 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, bool updateBodyMass)
	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.
b2WorldId	b2Shape_GetWorld (b2ShapeId shapeId)
	Get the world that owns this shape.
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. This is useful when you get a shape id from an event or query.
void	b2Shape_SetDensity (b2ShapeId shapeId, float density, bool updateBodyMass)
	Set the mass density of a shape, usually in kg/m^2.
float	b2Shape_GetDensity (b2ShapeId shapeId)
	Get the density of a shape, usually 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.
void	b2Shape_SetUserMaterial (b2ShapeId shapeId, uint64_t material)
	Set the user material identifier.
uint64_t	b2Shape_GetUserMaterial (b2ShapeId shapeId)
	Get the user material identifier.
void	b2Shape_SetSurfaceMaterial (b2ShapeId shapeId, const b2SurfaceMaterial *surfaceMaterial)
	Set the shape surface material.
b2SurfaceMaterial	b2Shape_GetSurfaceMaterial (b2ShapeId shapeId)
	Get the shape surface material.
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, b2Pos point)
	Test a world point for overlap with a shape.
b2WorldCastOutput	b2Shape_CastRay (b2ShapeId shapeId, b2Pos origin, b2Vec2 translation)
	Ray cast a single shape.
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.
void	b2Shape_SetChainSegment (b2ShapeId shapeId, const b2ChainSegment *chainSegment)
	Allows you to change a shape to be a loose chain segment or update the current chain segment.
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.
int	b2Shape_GetSensorCapacity (b2ShapeId shapeId)
	Get the maximum capacity required for retrieving all the overlapped shapes on a sensor shape.
int	b2Shape_GetSensorData (b2ShapeId shapeId, b2ShapeId *visitorIds, int capacity)
	Get the overlap data for a sensor shape computed during the previous world step.
b2AABB	b2Shape_GetBounds (b2ShapeId shapeId)
	Get the current world AABB.
b2MassData	b2Shape_ComputeMassData (b2ShapeId shapeId)
	Compute the mass data for a shape.
b2Pos	b2Shape_GetClosestPoint (b2ShapeId shapeId, b2Pos target)
	Get the closest point on a shape to a target point. Target and result are world positions.
void	b2Shape_ApplyWind (b2ShapeId shapeId, b2Vec2 wind, float drag, float lift, bool wake)
	Apply a wind force to the body for this shape using the density of air.
b2Filter	b2DefaultFilter (void)
	Use this to initialize your filter.
b2QueryFilter	b2DefaultQueryFilter (void)
	Use this to initialize your query filter.
b2SurfaceMaterial	b2DefaultSurfaceMaterial (void)
	Use this to initialize your surface material.
b2ShapeDef	b2DefaultShapeDef (void)
	Use this to initialize your shape definition.

Detailed Description

Functions to create, destroy, and access shapes.

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 };
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; b2Filter::maskBits uint64_t maskBits The collision mask bits. Definition types.h:343

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

◆ b2SurfaceMaterial

struct b2SurfaceMaterial

The surface material groups together parameters related to the shape surface, which is the 2D boundary.

Surface materials allow chain shapes to have per segment properties.

Data Fields
uint32_t	customColor	Custom debug draw color.
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].
float	tangentSpeed	The tangent speed for conveyor belts.
uint64_t	userMaterialId	User material identifier. This is passed with query results and to friction and restitution combining functions. It is not used internally.

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

Data Fields
float	density	The density, usually in kg/m^2. This is not part of the surface material because this is for the interior, which may have other considerations, such as being hollow. For example a wood barrel may be hollow or full of water.
bool	enableContactEvents	Enable contact events for this shape. Only applies to kinematic and dynamic bodies. Only one shape involved needs this flag set to true. Ignored for sensors. False by default.
bool	enableCustomFiltering	Enable custom filtering. Only one of the two shapes needs to enable custom filtering. See b2World_SetCustomFilterCallback.
bool	enableHitEvents	Enable hit events for this shape. Only applies to kinematic and dynamic bodies. Only one shape involved needs this flag set to true. 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. Both shapes involved must have this flag set to true. False by default, even for sensors.
b2Filter	filter	Collision 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 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. Fast moving sensors may miss overlaps. 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
b2SurfaceMaterial	material	The surface material for this shape.
bool	updateBodyMass	Should the body update the mass properties when this shape is created. Default is true. Warning: if this is false, you MUST call b2Body_UpdateMassFromShapes or b2Body_SetMassData before simulating the world.
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

◆ 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, this will be b2_nullShapeId if the length is too small.

◆ b2CreateChainSegmentShape()

b2ShapeId b2CreateChainSegmentShape	(	b2BodyId	bodyId,
		const b2ShapeDef *	def,
		const b2ChainSegment *	chainSegment )

Create a chain segment shape and attach it to a body.

The shape definition and geometry are fully cloned. The segment is not owned by any chain shape (b2Shape_GetParentChain returns b2_nullChainId). Contacts are not created until the next time step. The chainId on the segment is ignored. This uses more memory than using a chain shape, so I don't recommend using this.

Returns: the shape id, or b2_nullShapeId if the segment is too short.

◆ 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 or b2_nullShapeId if the segment is too short.

◆ b2DestroyShape()

void b2DestroyShape	(	b2ShapeId	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: b2Body_UpdateMassFromShapes

◆ b2Shape_ApplyWind()

void b2Shape_ApplyWind	(	b2ShapeId	shapeId,
		b2Vec2	wind,
		float	drag,
		float	lift,
		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
wake	should this wake the body

◆ b2Shape_CastRay()

b2WorldCastOutput b2Shape_CastRay	(	b2ShapeId	shapeId,
		b2Pos	origin,
		b2Vec2	translation )

Ray cast a single shape.

The ray starts at the origin and extends by the translation. The output point is a world position.

◆ 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

Warning: changing this at run-time may lead to lost begin/end events

◆ 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: b2PreSolveCallbackFcn

◆ b2Shape_EnableSensorEvents()

void b2Shape_EnableSensorEvents	(	b2ShapeId	shapeId,
		bool	flag )

Enable sensor events for this shape.

See also: b2ShapeDef::enableSensorEvents

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

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.

Note: Box2D 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

◆ b2Shape_GetSensorCapacity()

int b2Shape_GetSensorCapacity ( b2ShapeId 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 b2Shape_GetSensorData

◆ b2Shape_GetSensorData()

int b2Shape_GetSensorData	(	b2ShapeId	shapeId,
		b2ShapeId *	visitorIds,
		int	capacity )

Get the overlap data for a sensor shape computed during the previous world step.

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 visitorIds

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 b2Shape_IsValid to confirm each overlap

◆ b2Shape_IsSensor()

bool b2Shape_IsSensor ( b2ShapeId shapeId )

Returns true if the shape is a sensor.

It is not possible to change a shape from sensor to solid dynamically because this breaks the contract for sensor events.

◆ 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_UpdateMassFromShapes

◆ b2Shape_SetChainSegment()

void b2Shape_SetChainSegment	(	b2ShapeId	shapeId,
		const b2ChainSegment *	chainSegment )

Allows you to change a shape to be a loose chain segment or update the current chain segment.

The resulting shape does not belong to a chain shape. Asserts if the shape is already a chain segment owned by a chain shape (chainId != B2_NULL_INDEX).

◆ 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_UpdateMassFromShapes

◆ b2Shape_SetDensity()

void b2Shape_SetDensity	(	b2ShapeId	shapeId,
		float	density,
		bool	updateBodyMass )

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

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

See also: b2ShapeDef::density, b2Body_UpdateMassFromShapes

◆ b2Shape_SetFilter()

void b2Shape_SetFilter	(	b2ShapeId	shapeId,
		b2Filter	filter )

Set the current filter.

This is almost as expensive as recreating the shape. This may cause contacts to be immediately destroyed. However contacts are not created until the next world step. Sensor overlap state is also not updated until the next world step.

See also: b2ShapeDef::filter

◆ 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_UpdateMassFromShapes

Data Structures

Macros

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ b2Filter

◆ b2QueryFilter

◆ b2SurfaceMaterial

◆ b2ShapeDef

Enumeration Type Documentation

◆ b2ShapeType

Function Documentation

◆ b2CreateCapsuleShape()

◆ b2CreateChainSegmentShape()

◆ b2CreateCircleShape()

◆ b2CreatePolygonShape()

◆ b2CreateSegmentShape()

◆ b2DestroyShape()

◆ b2Shape_ApplyWind()

◆ b2Shape_CastRay()

◆ b2Shape_EnableContactEvents()

◆ b2Shape_EnableHitEvents()

◆ b2Shape_EnablePreSolveEvents()

◆ b2Shape_EnableSensorEvents()

◆ b2Shape_GetChainSegment()

◆ b2Shape_GetContactData()

◆ b2Shape_GetSensorCapacity()

◆ b2Shape_GetSensorData()

◆ b2Shape_IsSensor()

◆ b2Shape_SetCapsule()

◆ b2Shape_SetChainSegment()

◆ b2Shape_SetCircle()

◆ b2Shape_SetDensity()

◆ b2Shape_SetFilter()

◆ b2Shape_SetPolygon()