Box2D 3.1.0
A 2D physics engine for games
Loading...
Searching...
No Matches
Shape

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

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