cpSpace

Classes
struct	cpCollisionHandler
	Struct that holds function callback pointers to configure custom collision handling. More...
struct	cpSpaceDebugColor
	Color type to use with the space debug drawing API. More...
struct	cpSpaceDebugDrawOptions
	Struct used with cpSpaceDebugDraw() containing drawing callbacks and other drawing settings. More...

Typedefs
typedef cpBool(*	cpCollisionBeginFunc )(cpArbiter *arb, cpSpace *space, cpDataPointer userData)
	Collision begin event function callback type. More...
typedef cpBool(*	cpCollisionPreSolveFunc )(cpArbiter *arb, cpSpace *space, cpDataPointer userData)
	Collision pre-solve event function callback type. More...
typedef void(*	cpCollisionPostSolveFunc )(cpArbiter *arb, cpSpace *space, cpDataPointer userData)
	Collision post-solve event function callback type.
typedef void(*	cpCollisionSeparateFunc )(cpArbiter *arb, cpSpace *space, cpDataPointer userData)
	Collision separate event function callback type.
typedef void(*	cpPostStepFunc )(cpSpace *space, void *key, void *data)
	Post Step callback function type.
typedef void(*	cpSpacePointQueryFunc )(cpShape *shape, cpVect point, cpFloat distance, cpVect gradient, void *data)
	Nearest point query callback function type.
typedef void(*	cpSpaceSegmentQueryFunc )(cpShape *shape, cpVect point, cpVect normal, cpFloat alpha, void *data)
	Segment query callback function type.
typedef void(*	cpSpaceBBQueryFunc )(cpShape *shape, void *data)
	Rectangle Query callback function type.
typedef void(*	cpSpaceShapeQueryFunc )(cpShape *shape, cpContactPointSet *points, void *data)
	Shape query callback function type.
typedef void(*	cpSpaceBodyIteratorFunc )(cpBody *body, void *data)
	Space/body iterator callback function type.
typedef void(*	cpSpaceShapeIteratorFunc )(cpShape *shape, void *data)
	Space/body iterator callback function type.
typedef void(*	cpSpaceConstraintIteratorFunc )(cpConstraint *constraint, void *data)
	Space/constraint iterator callback function type.
typedef struct cpSpaceDebugColor	cpSpaceDebugColor
	Color type to use with the space debug drawing API.
typedef void(*	cpSpaceDebugDrawCircleImpl )(cpVect pos, cpFloat angle, cpFloat radius, cpSpaceDebugColor outlineColor, cpSpaceDebugColor fillColor, cpDataPointer data)
	Callback type for a function that draws a filled, stroked circle.
typedef void(*	cpSpaceDebugDrawSegmentImpl )(cpVect a, cpVect b, cpSpaceDebugColor color, cpDataPointer data)
	Callback type for a function that draws a line segment.
typedef void(*	cpSpaceDebugDrawFatSegmentImpl )(cpVect a, cpVect b, cpFloat radius, cpSpaceDebugColor outlineColor, cpSpaceDebugColor fillColor, cpDataPointer data)
	Callback type for a function that draws a thick line segment.
typedef void(*	cpSpaceDebugDrawPolygonImpl )(int count, const cpVect *verts, cpFloat radius, cpSpaceDebugColor outlineColor, cpSpaceDebugColor fillColor, cpDataPointer data)
	Callback type for a function that draws a convex polygon.
typedef void(*	cpSpaceDebugDrawDotImpl )(cpFloat size, cpVect pos, cpSpaceDebugColor color, cpDataPointer data)
	Callback type for a function that draws a dot.
typedef cpSpaceDebugColor(*	cpSpaceDebugDrawColorForShapeImpl )(cpShape *shape, cpDataPointer data)
	Callback type for a function that returns a color for a given shape. This gives you an opportunity to color shapes based on how they are used in your engine.
typedef struct cpSpaceDebugDrawOptions	cpSpaceDebugDrawOptions
	Struct used with cpSpaceDebugDraw() containing drawing callbacks and other drawing settings.

Functions
CP_EXPORT cpSpace *	cpSpaceAlloc (void)
	Allocate a cpSpace.
CP_EXPORT cpSpace *	cpSpaceInit (cpSpace *space)
	Initialize a cpSpace.
CP_EXPORT cpSpace *	cpSpaceNew (void)
	Allocate and initialize a cpSpace.
CP_EXPORT void	cpSpaceDestroy (cpSpace *space)
	Destroy a cpSpace.
CP_EXPORT void	cpSpaceFree (cpSpace *space)
	Destroy and free a cpSpace.
CP_EXPORT int	cpSpaceGetIterations (const cpSpace *space)
	Number of iterations to use in the impulse solver to solve contacts and other constraints.
CP_EXPORT cpVect	cpSpaceGetGravity (const cpSpace *space)
	Gravity to pass to rigid bodies when integrating velocity.
CP_EXPORT cpFloat	cpSpaceGetDamping (const cpSpace *space)
	Damping rate expressed as the fraction of velocity bodies retain each second. More...
CP_EXPORT cpFloat	cpSpaceGetIdleSpeedThreshold (const cpSpace *space)
	Speed threshold for a body to be considered idle. More...
CP_EXPORT cpFloat	cpSpaceGetSleepTimeThreshold (const cpSpace *space)
	Time a group of bodies must remain idle in order to fall asleep. More...
CP_EXPORT cpFloat	cpSpaceGetCollisionSlop (const cpSpace *space)
	Amount of encouraged penetration between colliding shapes. More...
CP_EXPORT cpFloat	cpSpaceGetCollisionBias (const cpSpace *space)
	Determines how fast overlapping shapes are pushed apart. More...
CP_EXPORT cpTimestamp	cpSpaceGetCollisionPersistence (const cpSpace *space)
	Number of frames that contact information should persist. More...
CP_EXPORT cpDataPointer	cpSpaceGetUserData (const cpSpace *space)
	User definable data pointer. More...
CP_EXPORT cpBody *	cpSpaceGetStaticBody (const cpSpace *space)
	The Space provided static body for a given cpSpace. More...
CP_EXPORT cpFloat	cpSpaceGetCurrentTimeStep (const cpSpace *space)
	Returns the current (or most recent) time step used with the given space. More...
CP_EXPORT cpBool	cpSpaceIsLocked (cpSpace *space)
	returns true from inside a callback when objects cannot be added/removed.
CP_EXPORT cpCollisionHandler *	cpSpaceAddDefaultCollisionHandler (cpSpace *space)
	Create or return the existing collision handler that is called for all collisions that are not handled by a more specific collision handler.
CP_EXPORT cpCollisionHandler *	cpSpaceAddCollisionHandler (cpSpace *space, cpCollisionType a, cpCollisionType b)
	Create or return the existing collision handler for the specified pair of collision types. More...
CP_EXPORT cpCollisionHandler *	cpSpaceAddWildcardHandler (cpSpace *space, cpCollisionType type)
	Create or return the existing wildcard collision handler for the specified type.
CP_EXPORT cpShape *	cpSpaceAddShape (cpSpace *space, cpShape *shape)
	Add a collision shape to the simulation. More...
CP_EXPORT cpBody *	cpSpaceAddBody (cpSpace *space, cpBody *body)
	Add a rigid body to the simulation.
CP_EXPORT cpConstraint *	cpSpaceAddConstraint (cpSpace *space, cpConstraint *constraint)
	Add a constraint to the simulation.
CP_EXPORT void	cpSpaceRemoveShape (cpSpace *space, cpShape *shape)
	Remove a collision shape from the simulation.
CP_EXPORT void	cpSpaceRemoveBody (cpSpace *space, cpBody *body)
	Remove a rigid body from the simulation.
CP_EXPORT void	cpSpaceRemoveConstraint (cpSpace *space, cpConstraint *constraint)
	Remove a constraint from the simulation.
CP_EXPORT cpBool	cpSpaceContainsShape (cpSpace *space, cpShape *shape)
	Test if a collision shape has been added to the space.
CP_EXPORT cpBool	cpSpaceContainsBody (cpSpace *space, cpBody *body)
	Test if a rigid body has been added to the space.
CP_EXPORT cpBool	cpSpaceContainsConstraint (cpSpace *space, cpConstraint *constraint)
	Test if a constraint has been added to the space.
CP_EXPORT cpBool	cpSpaceAddPostStepCallback (cpSpace *space, cpPostStepFunc func, void *key, void *data)
	Schedule a post-step callback to be called when cpSpaceStep() finishes. More...
CP_EXPORT void	cpSpacePointQuery (cpSpace *space, cpVect point, cpFloat maxDistance, cpShapeFilter filter, cpSpacePointQueryFunc func, void *data)
	Query the space at a point and call func for each shape found.
CP_EXPORT cpShape *	cpSpacePointQueryNearest (cpSpace *space, cpVect point, cpFloat maxDistance, cpShapeFilter filter, cpPointQueryInfo *out)
	Query the space at a point and return the nearest shape found. Returns NULL if no shapes were found.
CP_EXPORT void	cpSpaceSegmentQuery (cpSpace *space, cpVect start, cpVect end, cpFloat radius, cpShapeFilter filter, cpSpaceSegmentQueryFunc func, void *data)
	Perform a directed line segment query (like a raycast) against the space calling func for each shape intersected.
CP_EXPORT cpShape *	cpSpaceSegmentQueryFirst (cpSpace *space, cpVect start, cpVect end, cpFloat radius, cpShapeFilter filter, cpSegmentQueryInfo *out)
	Perform a directed line segment query (like a raycast) against the space and return the first shape hit. Returns NULL if no shapes were hit.
CP_EXPORT void	cpSpaceBBQuery (cpSpace *space, cpBB bb, cpShapeFilter filter, cpSpaceBBQueryFunc func, void *data)
	Perform a fast rectangle query on the space calling func for each shape found. More...
CP_EXPORT cpBool	cpSpaceShapeQuery (cpSpace *space, cpShape *shape, cpSpaceShapeQueryFunc func, void *data)
	Query a space for any shapes overlapping the given shape and call func for each shape found.
CP_EXPORT void	cpSpaceEachBody (cpSpace *space, cpSpaceBodyIteratorFunc func, void *data)
	Call func for each body in the space.
CP_EXPORT void	cpSpaceEachShape (cpSpace *space, cpSpaceShapeIteratorFunc func, void *data)
	Call func for each shape in the space.
CP_EXPORT void	cpSpaceEachConstraint (cpSpace *space, cpSpaceConstraintIteratorFunc func, void *data)
	Call func for each shape in the space.
CP_EXPORT void	cpSpaceReindexStatic (cpSpace *space)
	Update the collision detection info for the static shapes in the space.
CP_EXPORT void	cpSpaceReindexShape (cpSpace *space, cpShape *shape)
	Update the collision detection data for a specific shape in the space.
CP_EXPORT void	cpSpaceReindexShapesForBody (cpSpace *space, cpBody *body)
	Update the collision detection data for all shapes attached to a body.
CP_EXPORT void	cpSpaceUseSpatialHash (cpSpace *space, cpFloat dim, int count)
	Switch the space to use a spatial has as it's spatial index.
CP_EXPORT void	cpSpaceStep (cpSpace *space, cpFloat dt)
	Step the space forward in time by dt.
CP_EXPORT void	cpSpaceDebugDraw (cpSpace *space, cpSpaceDebugDrawOptions *options)
	Debug draw the current state of the space using the supplied drawing options.

Detailed Description

Typedef Documentation

typedef cpBool(* cpCollisionBeginFunc)(cpArbiter *arb, cpSpace *space, cpDataPointer userData)

Collision begin event function callback type.

Returning false from a begin callback causes the collision to be ignored until the the separate callback is called when the objects stop colliding.

typedef cpBool(* cpCollisionPreSolveFunc)(cpArbiter *arb, cpSpace *space, cpDataPointer userData)

Collision pre-solve event function callback type.

Returning false from a pre-step callback causes the collision to be ignored until the next step.

Function Documentation

CP_EXPORT cpCollisionHandler* cpSpaceAddCollisionHandler	(	cpSpace *	space,
		cpCollisionType	a,
		cpCollisionType	b
	)

Create or return the existing collision handler for the specified pair of collision types.

If wildcard handlers are used with either of the collision types, it's the responibility of the custom handler to invoke the wildcard handlers.

CP_EXPORT cpBool cpSpaceAddPostStepCallback	(	cpSpace *	space,
		cpPostStepFunc	func,
		void *	key,
		void *	data
	)

Schedule a post-step callback to be called when cpSpaceStep() finishes.

You can only register one callback per unique value for key. Returns true only if key has never been scheduled before. It's possible to pass NULL for func if you only want to mark key as being used.

CP_EXPORT cpShape* cpSpaceAddShape	(	cpSpace *	space,
		cpShape *	shape
	)

Add a collision shape to the simulation.

If the shape is attached to a static body, it will be added as a static shape.

CP_EXPORT void cpSpaceBBQuery	(	cpSpace *	space,
		cpBB	bb,
		cpShapeFilter	filter,
		cpSpaceBBQueryFunc	func,
		void *	data
	)

Perform a fast rectangle query on the space calling func for each shape found.

Only the shape's bounding boxes are checked for overlap, not their full shape.

CP_EXPORT cpFloat cpSpaceGetCollisionBias

(

const cpSpace *

space

)

Determines how fast overlapping shapes are pushed apart.

Expressed as a fraction of the error remaining after each second. Defaults to pow(1.0 - 0.1, 60.0) meaning that Chipmunk fixes 10% of overlap each frame at 60Hz.

CP_EXPORT cpTimestamp cpSpaceGetCollisionPersistence

(

const cpSpace *

space

)

Number of frames that contact information should persist.

Defaults to 3. There is probably never a reason to change this value.

CP_EXPORT cpFloat cpSpaceGetCollisionSlop

(

const cpSpace *

space

)

Amount of encouraged penetration between colliding shapes.

Used to reduce oscillating contacts and keep the collision cache warm. Defaults to 0.1. If you have poor simulation quality, increase this number as much as possible without allowing visible amounts of overlap.

CP_EXPORT cpFloat cpSpaceGetCurrentTimeStep

(

const cpSpace *

space

)

Returns the current (or most recent) time step used with the given space.

Useful from callbacks if your time step is not a compile-time global.

CP_EXPORT cpFloat cpSpaceGetDamping

(

const cpSpace *

space

)

Damping rate expressed as the fraction of velocity bodies retain each second.

A value of 0.9 would mean that each body's velocity will drop 10% per second. The default value is 1.0, meaning no damping is applied.

Note

This damping value is different than those of cpDampedSpring and cpDampedRotarySpring.

CP_EXPORT cpFloat cpSpaceGetIdleSpeedThreshold

(

const cpSpace *

space

)

Speed threshold for a body to be considered idle.

The default value of 0 means to let the space guess a good threshold based on gravity.

CP_EXPORT cpFloat cpSpaceGetSleepTimeThreshold

(

const cpSpace *

space

)

Time a group of bodies must remain idle in order to fall asleep.

Enabling sleeping also implicitly enables the the contact graph. The default value of INFINITY disables the sleeping algorithm.

CP_EXPORT cpBody* cpSpaceGetStaticBody

(

const cpSpace *

space

)

The Space provided static body for a given cpSpace.

This is merely provided for convenience and you are not required to use it.

CP_EXPORT cpDataPointer cpSpaceGetUserData

(

const cpSpace *

space

)

User definable data pointer.

Generally this points to your game's controller or game state class so you can access it when given a cpSpace reference in a callback.