Definition of an independent and simulatable "world". More...

#include <World.hpp>

Public Types
using	Bodies = std::vector< Body * >
	Bodies container type. More...

using	Contacts = std::vector< KeyedContactPtr >
	Contacts container type. More...

using	Joints = std::vector< Joint * >
	Joints container type. More...

using	Fixtures = std::vector< Fixture * >
	Fixtures container type. More...

Public Member Functions
	World (const WorldConf &def=GetDefaultWorldConf())
	Constructs a world object. More...

	World (const World &other)
	Copy constructor. More...

World &	operator= (const World &other)
	Assignment operator. More...

	~World () noexcept
	Destructor. More...

void	Clear ()
	Clears this world. More...

void	SetDestructionListener (DestructionListener *listener) noexcept
	Register a destruction listener. More...

void	SetContactListener (ContactListener *listener) noexcept
	Register a contact event listener. More...

Body *	CreateBody (const BodyConf &def=GetDefaultBodyConf())
	Creates a rigid body with the given configuration. More...

Joint *	CreateJoint (const JointConf &def)
	Creates a joint to constrain one or more bodies. More...

void	Destroy (Body *body)
	Destroys the given body. More...

void	Destroy (Joint *joint)
	Destroys a joint. More...

StepStats	Step (const StepConf &conf)
	Steps the world simulation according to the given configuration. More...

SizedRange< Bodies::iterator >	GetBodies () noexcept
	Gets the world body range for this world. More...

SizedRange< Bodies::const_iterator >	GetBodies () const noexcept
	Gets the world body range for this constant world. More...

SizedRange< Bodies::const_iterator >	GetBodiesForProxies () const noexcept
	Gets the bodies-for-proxies range for this world. More...

SizedRange< Fixtures::const_iterator >	GetFixturesForProxies () const noexcept
	Gets the fixtures-for-proxies range for this world. More...

SizedRange< Joints::const_iterator >	GetJoints () const noexcept
	Gets the world joint range. More...

SizedRange< Joints::iterator >	GetJoints () noexcept
	Gets the world joint range. More...

SizedRange< Contacts::const_iterator >	GetContacts () const noexcept
	Gets the world contact range. More...

bool	IsStepComplete () const noexcept
	Whether or not "step" is complete. More...

bool	GetSubStepping () const noexcept
	Gets whether or not sub-stepping is enabled. More...

void	SetSubStepping (bool flag) noexcept
	Enables/disables single stepped continuous physics. More...

const DynamicTree &	GetTree () const noexcept
	Gets access to the broad-phase dynamic tree information. More...

bool	IsLocked () const noexcept
	Is the world locked (in the middle of a time step). More...

void	ShiftOrigin (Length2 newOrigin)
	Shifts the world origin. More...

Length	GetMinVertexRadius () const noexcept
	Gets the minimum vertex radius that shapes in this world can be. More...

Length	GetMaxVertexRadius () const noexcept
	Gets the maximum vertex radius that shapes in this world can be. More...

Frequency	GetInvDeltaTime () const noexcept
	Gets the inverse delta time. More...

Friends
class	WorldAtty

Related Functions
(Note that these are not member functions.)
BodyCounter	GetBodyCount (const World &world) noexcept
	Gets the body count in the given world. More...

JointCounter	GetJointCount (const World &world) noexcept

ContactCounter	GetContactCount (const World &world) noexcept
	Gets the count of contacts in the given world. More...

ContactCounter	GetTouchingCount (const World &world) noexcept
	Gets the touching count for the given world. More...

StepStats	Step (World &world, Time delta, TimestepIters velocityIterations=8, TimestepIters positionIterations=3)
	Steps the world ahead by a given time amount. More...

std::size_t	GetFixtureCount (const World &world) noexcept
	Gets the count of fixtures in the given world. More...

std::size_t	GetShapeCount (const World &world) noexcept
	Gets the count of unique shapes in the given world. More...

BodyCounter	GetAwakeCount (const World &world) noexcept
	Gets the count of awake bodies in the given world. More...

BodyCounter	Awaken (World &world) noexcept
	Awakens all of the bodies in the given world. More...

template<class F >
void	SetAccelerations (World &world, F fn) noexcept
	Sets the accelerations of all the world's bodies. More...

void	SetAccelerations (World &world, Acceleration acceleration) noexcept
	Sets the accelerations of all the world's bodies to the given value. More...

void	SetAccelerations (World &world, LinearAcceleration2 acceleration) noexcept
	Sets the accelerations of all the world's bodies to the given value. More...

void	ClearForces (World &world) noexcept
	Clears forces. More...

Body *	FindClosestBody (const World &world, Length2 location) noexcept
	Finds body in given world that's closest to the given location. More...

Detailed Description

Definition of an independent and simulatable "world".

The world class manages physics entities, dynamic simulation, and queries. In a physical sense, perhaps this is more like a universe in that entities in a world have no interaction with entities in other worlds. In any case, there's precedence, from a physics-engine standpoint, for this being called a world.

Note: World instances do not themselves have any force or acceleration properties. They simply utilize the acceleration property of the bodies they manage. This is different than some other engines (like Box2D which provides a world gravity property).; World instances are composed of — i.e. contain and own — Body, Joint, and Contact instances.; This data structure is 232-bytes large (with 4-byte Real on at least one 64-bit platform).

Attention: For example, the following could be used to create a dynamic body having a one meter radius disk shape:
auto world = World{};

const auto body = world.CreateBody(BodyConf{}.UseType(BodyType::Dynamic));

const auto fixture = body->CreateFixture(Shape{DiskShapeConf{1_m}});

See also: Body, Joint, Contact, Physical Entity Classes

Examples: Body.cpp, Contact.cpp, HelloWorld.cpp, and World.cpp.

Definition at line 115 of file World.hpp.

Member Typedef Documentation

◆ Bodies

using playrho::d2::World::Bodies = std::vector<Body*>

Bodies container type.

Definition at line 119 of file World.hpp.

◆ Contacts

using playrho::d2::World::Contacts = std::vector<KeyedContactPtr>

Contacts container type.

Definition at line 122 of file World.hpp.

◆ Joints

using playrho::d2::World::Joints = std::vector<Joint*>

Joints container type.

Note: Cannot be container of Joint instances since joints are polymorphic types.

Definition at line 126 of file World.hpp.

◆ Fixtures

using playrho::d2::World::Fixtures = std::vector<Fixture*>

Fixtures container type.

Definition at line 129 of file World.hpp.

Constructor & Destructor Documentation

◆ World() [1/2]

playrho::d2::World::World ( const WorldConf & def = GetDefaultWorldConf() )

explicit

Constructs a world object.

Parameters

def	A customized world configuration or its default value.

Note: A lot more configurability can be had via the StepConf data that's given to the world's Step method.

Exceptions

InvalidArgument if the given max vertex radius is less than the min.

See also: Step

Definition at line 420 of file World.cpp.

◆ World() [2/2]

playrho::d2::World::World ( const World & other )

Copy constructor.

Copy constructs this world with a deep copy of the given world.

Postcondition: The state of this world is like that of the given world except this world now has deep copies of the given world with pointers having the new addresses of the new memory required for those copies.

Definition at line 433 of file World.cpp.

◆ ~World()

playrho::d2::World::~World ( )

noexcept

Destructor.

All physics entities are destroyed and all dynamically allocated memory is released.

Definition at line 470 of file World.cpp.

Member Function Documentation

◆ operator=()

World & playrho::d2::World::operator= ( const World & other )

Assignment operator.

Copy assigns this world with a deep copy of the given world.

Postcondition: The state of this world is like that of the given world except this world now has deep copies of the given world with pointers having the new addresses of the new memory required for those copies.

Warning: This method should not be called while the world is locked!

Exceptions

WrongState if this method is called while the world is locked.

Definition at line 449 of file World.cpp.

◆ Clear()

void playrho::d2::World::Clear ( )

Clears this world.

Postcondition: The contents of this world have all been destroyed and this world's internal state reset as though it had just been constructed.

Exceptions

WrongState if this method is called while the world is locked.

Examples: World.cpp.

Definition at line 475 of file World.cpp.

◆ SetDestructionListener()

void playrho::d2::World::SetDestructionListener ( DestructionListener * listener )

inlinenoexcept

Register a destruction listener.

Note: The listener is owned by you and must remain in scope.

Examples: World.cpp.

Definition at line 970 of file World.hpp.

◆ SetContactListener()

void playrho::d2::World::SetContactListener ( ContactListener * listener )

inlinenoexcept

Register a contact event listener.

Note: The listener is owned by you and must remain in scope.

Examples: World.cpp.

Definition at line 975 of file World.hpp.

◆ CreateBody()

Body * playrho::d2::World::CreateBody ( const BodyConf & def = GetDefaultBodyConf() )

Creates a rigid body with the given configuration.

Warning: This function should not be used while the world is locked — as it is during callbacks. If it is, it will throw an exception or abort your program.

Note: No references to the configuration are retained. Its value is copied.

Postcondition: The created body will be present in the range returned from the GetBodies() method.

Parameters

def	A customized body configuration or its default value.

Returns: Pointer to newly created body which can later be destroyed by calling the Destroy(Body*) method.

Exceptions

WrongState	if this method is called while the world is locked.
LengthError	if this operation would create more than `MaxBodies`.

See also: Destroy(Body*), GetBodies; Physical Entity Classes

Examples: Body.cpp, Contact.cpp, HelloWorld.cpp, and World.cpp.

Definition at line 717 of file World.cpp.

◆ CreateJoint()

Joint * playrho::d2::World::CreateJoint ( const JointConf & def )

Creates a joint to constrain one or more bodies.

Warning: This function is locked during callbacks.

Note: No references to the configuration are retained. Its value is copied.

Postcondition: The created joint will be present in the range returned from the GetJoints() method.

Returns: Pointer to newly created joint which can later be destroyed by calling the Destroy(Joint*) method.

Exceptions

WrongState	if this method is called while the world is locked.
LengthError	if this operation would create more than `MaxJoints`.
InvalidArgument	if the given definition is not allowed.

See also: Physical Entity Classes; Destroy(Joint*), GetJoints

Examples: World.cpp.

Definition at line 796 of file World.cpp.

◆ Destroy() [1/2]

void playrho::d2::World::Destroy ( Body * body )

Destroys the given body.

Destroys a given body that had previously been created by a call to this world's CreateBody(const BodyConf&) method.

Warning: This automatically deletes all associated shapes and joints.; This function is locked during callbacks.; Behavior is undefined if given a null body.; Behavior is undefined if the passed body was not created by this world.

Note: This function is locked during callbacks.

Postcondition: The destroyed body will no longer be present in the range returned from the GetBodies() method.; None of the body's fixtures will be present in the fixtures-for-proxies collection.

Parameters

body	Body to destroy that had been created by this world.

Exceptions

WrongState if this method is called while the world is locked.

See also: CreateBody(const BodyConf&), GetBodies, GetFixturesForProxies; Physical Entity Classes

Examples: World.cpp.

Definition at line 757 of file World.cpp.

◆ Destroy() [2/2]

void playrho::d2::World::Destroy ( Joint * joint )

Destroys a joint.

Destroys a given joint that had previously been created by a call to this world's CreateJoint(const JointConf&) method.

Warning: This function is locked during callbacks.; Behavior is undefined if the passed joint was not created by this world.

Note: This may cause the connected bodies to begin colliding.

Postcondition: The destroyed joint will no longer be present in the range returned from the GetJoints() method.

Parameters

joint Joint to destroy that had been created by this world.

Exceptions

WrongState if this method is called while the world is locked.

See also: CreateJoint(const JointConf&), GetJoints; Physical Entity Classes

Definition at line 844 of file World.cpp.

◆ Step()

StepStats playrho::d2::World::Step ( const StepConf & conf )

Steps the world simulation according to the given configuration.

Performs position and velocity updating, sleeping of non-moving bodies, updating of the contacts, and notifying the contact listener of begin-contact, end-contact, pre-solve, and post-solve events.

Warning: Behavior is undefined if given a negative step time delta.; Varying the step time delta may lead to non-physical behaviors.

Note: Calling this with a zero step time delta results only in fixtures and bodies registered for proxy handling being processed. No physics is performed.; If the given velocity and position iterations are zero, this method doesn't do velocity or position resolutions respectively of the contacting bodies.; While body velocities are updated accordingly (per the sum of forces acting on them), body positions (barring any collisions) are updated as if they had moved the entire time step at those resulting velocities. In other words, a body initially at position 0 (p0) going velocity 0 (v0) fast with a sum acceleration of a, after time t and barring any collisions, will have a new velocity (v1) of v0 + (a * t) and a new position (p1) of p0 + v1 * t.

Postcondition: Static bodies are unmoved.; Kinetic bodies are moved based on their previous velocities.; Dynamic bodies are moved based on their previous velocities, gravity, applied forces, applied impulses, masses, damping, and the restitution and friction values of their fixtures when they experience collisions.; The bodies for proxies queue will be empty.; The fixtures for proxies queue will be empty.

Parameters

conf	Configuration for the simulation step.

Returns: Statistics for the step.

Exceptions

WrongState if this method is called while the world is locked.

See also: GetBodiesForProxies, GetFixturesForProxies

Examples: World.cpp.

Definition at line 1804 of file World.cpp.

◆ GetBodies() [1/2]

SizedRange< World::Bodies::const_iterator > playrho::d2::World::GetBodies ( )

inlinenoexcept

Gets the world body range for this world.

Gets a range enumerating the bodies currently existing within this world. These are the bodies that had been created from previous calls to the CreateBody(const BodyConf&) method that haven't yet been destroyed.

Returns: Body range that can be iterated over using its begin and end methods or using ranged-based for-loops.

See also: CreateBody(const BodyConf&)

Examples: World.cpp.

Definition at line 861 of file World.hpp.

◆ GetBodies() [2/2]

SizedRange<Bodies::const_iterator> playrho::d2::World::GetBodies ( ) const

noexcept

Gets the world body range for this constant world.

Gets a range enumerating the bodies currently existing within this world. These are the bodies that had been created from previous calls to the CreateBody(const BodyConf&) method that haven't yet been destroyed.

Returns: Body range that can be iterated over using its begin and end methods or using ranged-based for-loops.

See also: CreateBody(const BodyConf&)

◆ GetBodiesForProxies()

SizedRange< World::Bodies::const_iterator > playrho::d2::World::GetBodiesForProxies ( ) const

inlinenoexcept

Gets the bodies-for-proxies range for this world.

Provides insight on what bodies have been queued for proxy processing during the next call to the world step method.

See also: Step

Examples: World.cpp.

Definition at line 871 of file World.hpp.

◆ GetFixturesForProxies()

SizedRange< World::Fixtures::const_iterator > playrho::d2::World::GetFixturesForProxies ( ) const

inlinenoexcept

Gets the fixtures-for-proxies range for this world.

Provides insight on what fixtures have been queued for proxy processing during the next call to the world step method.

See also: Step

Examples: World.cpp.

Definition at line 876 of file World.hpp.

◆ GetJoints() [1/2]

SizedRange< World::Joints::iterator > playrho::d2::World::GetJoints ( ) const

inlinenoexcept

Gets the world joint range.

Gets a range enumerating the joints currently existing within this world. These are the joints that had been created from previous calls to the CreateJoint(const JointConf&) method that haven't yet been destroyed.

Returns: World joints sized-range.

See also: CreateJoint(const JointConf&)

Examples: World.cpp.

Definition at line 881 of file World.hpp.

◆ GetJoints() [2/2]

SizedRange<Joints::iterator> playrho::d2::World::GetJoints ( )

noexcept

Gets the world joint range.

Gets a range enumerating the joints currently existing within this world. These are the joints that had been created from previous calls to the CreateJoint(const JointConf&) method that haven't yet been destroyed.

Returns: World joints sized-range.

See also: CreateJoint(const JointConf&)

◆ GetContacts()

SizedRange< World::Contacts::const_iterator > playrho::d2::World::GetContacts ( ) const

inlinenoexcept

Gets the world contact range.

Warning: contacts are created and destroyed in the middle of a time step. Use ContactListener to avoid missing contacts.

Returns: World contacts sized-range.

Examples: World.cpp.

Definition at line 891 of file World.hpp.

◆ IsStepComplete()

bool playrho::d2::World::IsStepComplete ( ) const

inlinenoexcept

Whether or not "step" is complete.

The "step" is completed when there are no more TOI events for the current time step.

Returns: true unless sub-stepping is enabled and the step method returned without finishing all of its sub-steps.

See also: SetStepComplete.

Examples: World.cpp.

Definition at line 901 of file World.hpp.

◆ GetSubStepping()

bool playrho::d2::World::GetSubStepping ( ) const

inlinenoexcept

Gets whether or not sub-stepping is enabled.

Examples: World.cpp.

Definition at line 918 of file World.hpp.

◆ SetSubStepping()

void playrho::d2::World::SetSubStepping ( bool flag )

inlinenoexcept

Enables/disables single stepped continuous physics.

Note: This is for testing.

Postcondition: The GetSubStepping method will return the value this method was called with.

See also: IsStepComplete, GetSubStepping.

Examples: World.cpp.

Definition at line 923 of file World.hpp.

◆ GetTree()

const DynamicTree & playrho::d2::World::GetTree ( ) const

inlinenoexcept

Gets access to the broad-phase dynamic tree information.

Examples: World.cpp.

Definition at line 965 of file World.hpp.

◆ IsLocked()

bool playrho::d2::World::IsLocked ( ) const

inlinenoexcept

Is the world locked (in the middle of a time step).

Examples: World.cpp.

Definition at line 896 of file World.hpp.

◆ ShiftOrigin()

void playrho::d2::World::ShiftOrigin ( Length2 newOrigin )

Shifts the world origin.

Note: Useful for large worlds.; The body shift formula is: position -= newOrigin.

Postcondition: The "origin" of this world's bodies, joints, and the board-phase dynamic tree have been translated per the shift amount and direction.

Parameters

newOrigin the new origin with respect to the old origin

Exceptions

WrongState if this method is called while the world is locked.

Examples: World.cpp.

Definition at line 1864 of file World.cpp.

◆ GetMinVertexRadius()

Length playrho::d2::World::GetMinVertexRadius ( ) const

inlinenoexcept

Gets the minimum vertex radius that shapes in this world can be.

Examples: World.cpp.

Definition at line 950 of file World.hpp.

◆ GetMaxVertexRadius()

Length playrho::d2::World::GetMaxVertexRadius ( ) const

inlinenoexcept

Gets the maximum vertex radius that shapes in this world can be.

Examples: World.cpp.

Definition at line 955 of file World.hpp.

◆ GetInvDeltaTime()

Frequency playrho::d2::World::GetInvDeltaTime ( ) const

inlinenoexcept

Gets the inverse delta time.

Gets the inverse delta time that was set on construction or assignment, and updated on every call to the Step() method having a non-zero delta-time.

See also: Step

Definition at line 960 of file World.hpp.

Friends And Related Function Documentation

◆ WorldAtty

friend class WorldAtty

friend

Definition at line 372 of file World.hpp.

◆ GetBodyCount()

BodyCounter GetBodyCount ( const World & world )

Returns: 0 or higher.

Examples: World.cpp.

Definition at line 1036 of file World.hpp.

◆ GetJointCount()

JointCounter GetJointCount ( const World & world )

Returns: 0 or higher.

Examples: World.cpp.

Definition at line 1044 of file World.hpp.

◆ GetContactCount()

ContactCounter GetContactCount ( const World & world )

Note: Not all contacts are for shapes that are actually touching. Some contacts are for shapes which merely have overlapping AABBs.

Returns: 0 or higher.

Definition at line 1054 of file World.hpp.

◆ GetTouchingCount()

ContactCounter GetTouchingCount ( const World & world )

Examples: World.cpp.

Definition at line 2605 of file World.cpp.

◆ Step()

StepStats Step	(	World &	world,
		Time	delta,
		TimestepIters	velocityIterations = `8`,
		TimestepIters	positionIterations = `3`
	)

Performs position and velocity updating, sleeping of non-moving bodies, updating of the contacts, and notifying the contact listener of begin-contact, end-contact, pre-solve, and post-solve events. If the given velocity and position iterations are more than zero, this method also respectively performs velocity and position resolution of the contacting bodies.

Note: While body velocities are updated accordingly (per the sum of forces acting on them), body positions (barring any collisions) are updated as if they had moved the entire time step at those resulting velocities. In other words, a body initially at p0 going v0 fast with a sum acceleration of a, after time t and barring any collisions, will have a new velocity (v1) of v0 + (a * t) and a new position (p1) of p0 + v1 * t.

Warning: Varying the time step may lead to non-physical behaviors.

Postcondition: Static bodies are unmoved.; Kinetic bodies are moved based on their previous velocities.; Dynamic bodies are moved based on their previous velocities, gravity, applied forces, applied impulses, masses, damping, and the restitution and friction values of their fixtures when they experience collisions.

Parameters

world	World to step.
delta	Time to simulate as a delta from the current state. This should not vary.
velocityIterations	Number of iterations for the velocity constraint solver.
positionIterations	Number of iterations for the position constraint solver. The position constraint solver resolves the positions of bodies that overlap.

Examples: World.cpp.

Definition at line 2589 of file World.cpp.

◆ GetFixtureCount()

std::size_t GetFixtureCount ( const World & world )

Definition at line 2614 of file World.cpp.

◆ GetShapeCount()

std::size_t GetShapeCount ( const World & world )

Examples: World.cpp.

Definition at line 2625 of file World.cpp.

◆ GetAwakeCount()

BodyCounter GetAwakeCount ( const World & world )

Examples: World.cpp.

Definition at line 2638 of file World.cpp.

◆ Awaken()

BodyCounter Awaken ( World & world )

Calls all of the world's bodies' SetAwake method.

Returns: Sum total of calls to bodies' SetAwake method that returned true.

See also: Body::SetAwake.

Definition at line 2646 of file World.cpp.

◆ SetAccelerations() [1/3]

template<class F >

void SetAccelerations	(	World &	world,
		F	fn
	)

Parameters

world	World instance to set the acceleration of all contained bodies for.
fn	Function or functor with a signature like: `Acceleration (*fn)(const Body& body)`.

Examples: World.cpp.

Definition at line 1123 of file World.hpp.

◆ SetAccelerations() [2/3]

void SetAccelerations	(	World &	world,
		Acceleration	acceleration
	)

Definition at line 2660 of file World.cpp.

◆ SetAccelerations() [3/3]

void SetAccelerations	(	World &	world,
		LinearAcceleration2	acceleration
	)

Note: This will leave the angular acceleration alone.

Definition at line 2668 of file World.cpp.

◆ ClearForces()

void ClearForces ( World & world )

Manually clear the force buffer on all bodies.

Examples: World.cpp.

Definition at line 1143 of file World.hpp.

◆ FindClosestBody()

Body * FindClosestBody	(	const World &	world,
		Length2	location
	)

Examples: World.cpp.

Definition at line 2676 of file World.cpp.

The documentation for this class was generated from the following files:

Dynamics/World.hpp
Dynamics/World.cpp

Public Types

Public Member Functions

Friends

Related Functions

Detailed Description

Member Typedef Documentation

◆ Bodies

◆ Contacts

◆ Joints

◆ Fixtures

Constructor & Destructor Documentation

◆ World() [1/2]

◆ World() [2/2]

◆ ~World()

Member Function Documentation

◆ operator=()

◆ Clear()

◆ SetDestructionListener()

◆ SetContactListener()

◆ CreateBody()

◆ CreateJoint()

◆ Destroy() [1/2]

◆ Destroy() [2/2]

◆ Step()

◆ GetBodies() [1/2]

◆ GetBodies() [2/2]

◆ GetBodiesForProxies()

◆ GetFixturesForProxies()

◆ GetJoints() [1/2]

◆ GetJoints() [2/2]

◆ GetContacts()

◆ IsStepComplete()

◆ GetSubStepping()

◆ SetSubStepping()

◆ GetTree()

◆ IsLocked()

◆ ShiftOrigin()

◆ GetMinVertexRadius()

◆ GetMaxVertexRadius()

◆ GetInvDeltaTime()

Friends And Related Function Documentation

◆ WorldAtty

◆ GetBodyCount()

◆ GetJointCount()

◆ GetContactCount()

◆ GetTouchingCount()

◆ Step()

◆ GetFixtureCount()

◆ GetShapeCount()

◆ GetAwakeCount()

◆ Awaken()

◆ SetAccelerations() [1/3]

◆ SetAccelerations() [2/3]

◆ SetAccelerations() [3/3]

◆ ClearForces()

◆ FindClosestBody()