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 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.
Member Typedef Documentation
◆ Bodies
using playrho::d2::World::Bodies = std::vector<Body*> |
◆ Contacts
using playrho::d2::World::Contacts = std::vector<KeyedContactPtr> |
◆ Joints
using playrho::d2::World::Joints = std::vector<Joint*> |
◆ Fixtures
using playrho::d2::World::Fixtures = std::vector<Fixture*> |
Constructor & Destructor Documentation
◆ World() [1/2]
|
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'sStep
method.
- Exceptions
-
InvalidArgument if the given max vertex radius is less than the min.
- See also
- Step
◆ 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.
◆ ~World()
|
noexcept |
Member Function Documentation
◆ operator=()
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.
◆ 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.
◆ SetDestructionListener()
|
inlinenoexcept |
◆ SetContactListener()
|
inlinenoexcept |
◆ 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
.
- Examples
- Body.cpp, Contact.cpp, HelloWorld.cpp, and World.cpp.
◆ CreateJoint()
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.
- Examples
- 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.
- Examples
- 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.
◆ Step()
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 ofa
, after timet
and barring any collisions, will have a new velocity (v1
) ofv0 + (a * t)
and a new position (p1
) ofp0 + 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.
◆ GetBodies() [1/2]
|
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.
◆ GetBodies() [2/2]
|
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()
|
inlinenoexcept |
◆ GetFixturesForProxies()
|
inlinenoexcept |
◆ GetJoints() [1/2]
|
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.
◆ GetJoints() [2/2]
|
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()
|
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.
◆ IsStepComplete()
|
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.
◆ GetSubStepping()
|
inlinenoexcept |
◆ SetSubStepping()
|
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.
◆ GetTree()
|
inlinenoexcept |
◆ IsLocked()
|
inlinenoexcept |
◆ 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.
◆ GetMinVertexRadius()
|
inlinenoexcept |
◆ GetMaxVertexRadius()
|
inlinenoexcept |
◆ GetInvDeltaTime()
|
inlinenoexcept |
Friends And Related Function Documentation
◆ WorldAtty
◆ GetBodyCount()
|
related |
◆ GetJointCount()
|
related |
◆ GetContactCount()
|
related |
◆ GetTouchingCount()
|
related |
◆ Step()
|
related |
Steps the world ahead by a given time amount.
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
goingv0
fast with a sum acceleration ofa
, after timet
and barring any collisions, will have a new velocity (v1
) ofv0 + (a * t)
and a new position (p1
) ofp0 + 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.
◆ GetFixtureCount()
|
related |
◆ GetShapeCount()
|
related |
◆ GetAwakeCount()
|
related |
◆ Awaken()
|
related |
Awakens all of the bodies in the given 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.
◆ SetAccelerations() [1/3]
|
related |
◆ SetAccelerations() [2/3]
|
related |
◆ SetAccelerations() [3/3]
|
related |
◆ ClearForces()
|
related |
◆ FindClosestBody()
The documentation for this class was generated from the following files: