PlayRho  2.0.0
An interactive physics engine & library.
playrho::d2::detail::WorldConcept Struct Referenceabstract

World-concept internal pure virtual base interface class. More...

#include <playrho/d2/detail/WorldConcept.hpp>

Inheritance diagram for playrho::d2::detail::WorldConcept:
[legend]

Public Member Functions

virtual ~WorldConcept ()=default
 Destructor.
 
virtual void Clear_ () noexcept=0
 Clears the world. More...
 
virtual std::unique_ptr< WorldConceptClone_ () const =0
 Clones the instance - making a deep copy.
 
virtual BodyID CreateBody_ (const Body &body)=0
 Creates a rigid body that's a copy of the given one. More...
 
virtual JointID CreateJoint_ (const Joint &def)=0
 Creates a joint to constrain one or more bodies. More...
 
virtual ShapeID CreateShape_ (const Shape &def)=0
 Creates an identifiable copy of the given shape within this world. More...
 
virtual void Destroy_ (BodyID id)=0
 Destroys the identified body. More...
 
virtual void Destroy_ (JointID id)=0
 Destroys the identified joint. More...
 
virtual void Destroy_ (ShapeID id)=0
 Destroys the identified shape. More...
 
virtual std::vector< BodyIDGetBodies_ () const =0
 Gets the world body range for this constant world. More...
 
virtual std::vector< BodyIDGetBodiesForProxies_ () const =0
 Gets the bodies-for-proxies range for this world. More...
 
virtual Body GetBody_ (BodyID id) const =0
 Gets the state of the identified body. More...
 
virtual BodyCounter GetBodyRange_ () const noexcept=0
 Gets the extent of the currently valid body range. More...
 
virtual Contact GetContact_ (ContactID id) const =0
 Gets the identified contact. More...
 
virtual ContactCounter GetContactRange_ () const noexcept=0
 Gets the extent of the currently valid contact range. More...
 
virtual std::vector< KeyedContactIDGetContacts_ () const =0
 Gets the world contact range. More...
 
virtual std::vector< std::tuple< ContactKey, ContactID > > GetContacts_ (BodyID id) const =0
 Gets the container of contacts attached to the identified body. More...
 
virtual const void * GetData_ () const noexcept=0
 Gets the data for the underlying configuration.
 
virtual void * GetData_ () noexcept=0
 Gets the data for the underlying configuration.
 
virtual Frequency GetInvDeltaTime_ () const noexcept=0
 Gets the inverse delta time. More...
 
virtual Joint GetJoint_ (JointID id) const =0
 Gets the value of the identified joint. More...
 
virtual JointCounter GetJointRange_ () const noexcept=0
 Gets the extent of the currently valid joint range. More...
 
virtual std::vector< JointIDGetJoints_ () const =0
 Gets the world joint range. More...
 
virtual std::vector< std::pair< BodyID, JointID > > GetJoints_ (BodyID id) const =0
 Gets the range of joints attached to the identified body. More...
 
virtual Manifold GetManifold_ (ContactID id) const =0
 Gets the collision manifold for the identified contact. More...
 
virtual std::optional< pmr::StatsResource::StatsGetResourceStats_ () const noexcept=0
 Gets the polymorphic memory resource statistics. More...
 
virtual Shape GetShape_ (ShapeID id) const =0
 
virtual ShapeCounter GetShapeRange_ () const noexcept=0
 Gets the extent of the currently valid shape range. More...
 
virtual std::vector< ShapeIDGetShapes_ (BodyID id) const =0
 Gets the identities of the shapes associated with the identified body. More...
 
virtual bool GetSubStepping_ () const noexcept=0
 Gets whether or not sub-stepping is enabled. More...
 
virtual const DynamicTreeGetTree_ () const noexcept=0
 Gets access to the broad-phase dynamic tree information. More...
 
virtual TypeID GetType_ () const noexcept=0
 Gets the use type information. More...
 
virtual Interval< Positive< Length > > GetVertexRadiusInterval_ () const noexcept=0
 Gets the vertex radius range that shapes in this world can be within.
 
virtual bool IsEqual_ (const WorldConcept &other) const noexcept=0
 Equality checking function.
 
virtual bool IsLocked_ () const noexcept=0
 Is the world locked (in the middle of a time step).
 
virtual bool IsStepComplete_ () const noexcept=0
 Whether or not "step" is complete. More...
 
virtual void SetBeginContactListener_ (ContactFunction listener) noexcept=0
 Sets a begin contact event listener.
 
virtual void SetBody_ (BodyID id, const Body &value)=0
 Sets the state of the identified body. More...
 
virtual void SetContact_ (ContactID id, const Contact &value)=0
 Sets the identified contact's state. More...
 
virtual void SetDetachListener_ (BodyShapeFunction listener) noexcept=0
 Sets the detach listener for shapes detaching from bodies.
 
virtual void SetEndContactListener_ (ContactFunction listener) noexcept=0
 Sets an end contact event listener.
 
virtual void SetJoint_ (JointID id, const Joint &def)=0
 Sets the identified joint to the given value. More...
 
virtual void SetJointDestructionListener_ (JointFunction listener) noexcept=0
 Sets a destruction listener for joints. More...
 
virtual void SetManifold_ (ContactID id, const Manifold &value)=0
 Sets the collision manifold for the identified contact. More...
 
virtual void SetPostSolveContactListener_ (ContactImpulsesFunction listener) noexcept=0
 Sets a post-solve contact event listener.
 
virtual void SetPreSolveContactListener_ (ContactManifoldFunction listener) noexcept=0
 Sets a pre-solve contact event listener.
 
virtual void SetShape_ (ShapeID id, const Shape &def)=0
 Sets the identified shape to the new value. More...
 
virtual void SetShapeDestructionListener_ (ShapeFunction listener) noexcept=0
 Sets the destruction listener for shapes. More...
 
virtual void SetSubStepping_ (bool flag) noexcept=0
 Enables/disables single stepped continuous physics. More...
 
virtual void ShiftOrigin_ (const Length2 &newOrigin)=0
 Shifts the world origin. More...
 
virtual StepStats Step_ (const StepConf &conf)=0
 Steps the world simulation according to the given configuration. More...
 

Detailed Description

World-concept internal pure virtual base interface class.

Note
This class itself has no invariants. Some of its member functions however do impose some invariant like relationships with others.

Member Function Documentation

◆ Clear_()

virtual void playrho::d2::detail::WorldConcept::Clear_ ( )
pure virtualnoexcept

Clears the world.

Note
This calls the joint and shape destruction listeners (if they're set), for all defined joints and shapes, before clearing anything. Any exceptions thrown from these listeners are ignored.
Postcondition
The contents of this world have all been destroyed and this world's internal state is reset as though it had just been constructed.
See also
SetJointDestructionListener_, SetShapeDestructionListener_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ CreateBody_()

virtual BodyID playrho::d2::detail::WorldConcept::CreateBody_ ( const Body body)
pure virtual

Creates a rigid body that's a copy of the given one.

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_() function.
Parameters
bodyA customized body or its default value.
Returns
Identifier of the newly created body which can later be destroyed by calling the Destroy_(BodyID) function.
Exceptions
WrongStateif this function is called while the world is locked.
LengthErrorif this operation would create more than MaxBodies.
std::out_of_rangeif the given body references any invalid shape identifiers.
See also
Destroy_(BodyID), GetBodies_.
Physical Entities.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ CreateJoint_()

virtual JointID playrho::d2::detail::WorldConcept::CreateJoint_ ( const Joint def)
pure virtual

Creates a joint to constrain one or more bodies.

Warning
This function is locked during callbacks.
Postcondition
The created joint will be present in the range returned from the GetJoints_() function.
Returns
Identifier of newly created joint which can later be destroyed by calling the Destroy_(JointID) function.
Exceptions
WrongStateif this function is called while the world is locked.
LengthErrorif this operation would create more than MaxJoints.
See also
Physical Entities.
Destroy_(JointID), GetJoints_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ CreateShape_()

virtual ShapeID playrho::d2::detail::WorldConcept::CreateShape_ ( const Shape def)
pure virtual

Creates an identifiable copy of the given shape within this world.

Exceptions
InvalidArgumentif called for a shape with a vertex radius that's either: less than the minimum vertex radius, or greater than the maximum vertex radius.
WrongStateif this function is called while the world is locked.
LengthErrorif this operation would create more than MaxShapes.
See also
Destroy_(ShapeID), GetShape_, SetShape_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ Destroy_() [1/3]

virtual void playrho::d2::detail::WorldConcept::Destroy_ ( BodyID  id)
pure virtual

Destroys the identified body.

Destroys the identified body that had previously been created by a call to this world's CreateBody_(const Body&) function.

Warning
This automatically deletes all associated shapes and joints.
This function is locked during callbacks.
Behavior is not specified if identified body wasn't 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_() function.
Parameters
idIdentifier of body to destroy that had been created by this world.
Exceptions
WrongStateif this function is called while the world is locked.
std::out_of_rangeIf given an invalid body identifier.
See also
CreateBody_, GetBodies_, GetBodyRange_.
Physical Entities.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ Destroy_() [2/3]

virtual void playrho::d2::detail::WorldConcept::Destroy_ ( JointID  id)
pure virtual

Destroys the identified joint.

Destroys the identified joint that had previously been created by a call to this world's CreateJoint_(const Joint&) function.

Warning
This function is locked during callbacks.
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_() function.
Parameters
idIdentifier of joint to destroy that had been created by this world.
Exceptions
WrongStateif this function is called while the world is locked.
std::out_of_rangeIf given an invalid joint identifier.
See also
CreateJoint_(const Joint&), GetJoints_, GetJointRange_.
Physical Entities.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ Destroy_() [3/3]

virtual void playrho::d2::detail::WorldConcept::Destroy_ ( ShapeID  id)
pure virtual

Destroys the identified shape.

Exceptions
std::out_of_rangeIf given an invalid shape identifier.
See also
CreateShape_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ GetBodies_()

virtual std::vector<BodyID> playrho::d2::detail::WorldConcept::GetBodies_ ( ) const
pure virtual

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 Body&) function that haven't yet been destroyed.

Returns
An iterable of body identifiers.
See also
CreateBody_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ GetBodiesForProxies_()

virtual std::vector<BodyID> playrho::d2::detail::WorldConcept::GetBodiesForProxies_ ( ) const
pure virtual

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

See also
Step_.
Todo:
Remove this function from this class - access from implementation instead.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ GetBody_()

virtual Body playrho::d2::detail::WorldConcept::GetBody_ ( BodyID  id) const
pure virtual

Gets the state of the identified body.

Exceptions
std::out_of_rangeIf given an invalid body identifier.
See also
SetBody_, GetBodyRange_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ GetBodyRange_()

virtual BodyCounter playrho::d2::detail::WorldConcept::GetBodyRange_ ( ) const
pure virtualnoexcept

Gets the extent of the currently valid body range.

Note
This is one higher than the maxium BodyID that is in range for body related functions.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ GetContact_()

virtual Contact playrho::d2::detail::WorldConcept::GetContact_ ( ContactID  id) const
pure virtual

Gets the identified contact.

Exceptions
std::out_of_rangeIf given an invalid contact identifier.
See also
SetContact_, GetContactRange_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ GetContactRange_()

virtual ContactCounter playrho::d2::detail::WorldConcept::GetContactRange_ ( ) const
pure virtualnoexcept

Gets the extent of the currently valid contact range.

Note
This is one higher than the maxium ContactID that is in range for contact related functions.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ GetContacts_() [1/2]

virtual std::vector<KeyedContactID> playrho::d2::detail::WorldConcept::GetContacts_ ( ) const
pure virtual

Gets the world contact range.

Warning
contacts are created and destroyed in the middle of a time step. Use ContactFunction to avoid missing contacts.
Returns
World contacts sized-range.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ GetContacts_() [2/2]

virtual std::vector<std::tuple<ContactKey, ContactID> > playrho::d2::detail::WorldConcept::GetContacts_ ( BodyID  id) const
pure virtual

Gets the container of contacts attached to the identified body.

Warning
This collection changes during the time step and you may miss some collisions if you don't use ContactFunction.
Exceptions
std::out_of_rangeIf given an invalid body identifier.
See also
GetBodyRange_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ GetInvDeltaTime_()

virtual Frequency playrho::d2::detail::WorldConcept::GetInvDeltaTime_ ( ) const
pure virtualnoexcept

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_ function having a non-zero delta-time.

See also
Step_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ GetJoint_()

virtual Joint playrho::d2::detail::WorldConcept::GetJoint_ ( JointID  id) const
pure virtual

Gets the value of the identified joint.

Exceptions
std::out_of_rangeIf given an invalid joint identifier.
See also
SetJoint_, GetJointRange_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ GetJointRange_()

virtual JointCounter playrho::d2::detail::WorldConcept::GetJointRange_ ( ) const
pure virtualnoexcept

Gets the extent of the currently valid joint range.

Note
This is one higher than the maxium JointID that is in range for joint related functions.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ GetJoints_() [1/2]

virtual std::vector<JointID> playrho::d2::detail::WorldConcept::GetJoints_ ( ) const
pure virtual

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_ function that haven't yet been destroyed.

Returns
World joints sized-range.
See also
CreateJoint_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ GetJoints_() [2/2]

virtual std::vector<std::pair<BodyID, JointID> > playrho::d2::detail::WorldConcept::GetJoints_ ( BodyID  id) const
pure virtual

Gets the range of joints attached to the identified body.

Exceptions
std::out_of_rangeIf given an invalid body identifier.
See also
CreateJoint_, GetBodyRange_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ GetManifold_()

virtual Manifold playrho::d2::detail::WorldConcept::GetManifold_ ( ContactID  id) const
pure virtual

Gets the collision manifold for the identified contact.

Exceptions
std::out_of_rangeIf given an invalid contact identifier.
See also
SetManifold_, GetContactRange_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ GetResourceStats_()

virtual std::optional<pmr::StatsResource::Stats> playrho::d2::detail::WorldConcept::GetResourceStats_ ( ) const
pure virtualnoexcept

Gets the polymorphic memory resource statistics.

Note
This will be the zero initialized value unless the world configuration the world was constructed with specified the collection of these statistics.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ GetShape_()

virtual Shape playrho::d2::detail::WorldConcept::GetShape_ ( ShapeID  id) const
pure virtual
Exceptions
std::out_of_rangeIf given an invalid shape identifier.
See also
CreateShape_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ GetShapeRange_()

virtual ShapeCounter playrho::d2::detail::WorldConcept::GetShapeRange_ ( ) const
pure virtualnoexcept

Gets the extent of the currently valid shape range.

Note
This is one higher than the maxium ShapeID that is in range for shape related functions.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ GetShapes_()

virtual std::vector<ShapeID> playrho::d2::detail::WorldConcept::GetShapes_ ( BodyID  id) const
pure virtual

Gets the identities of the shapes associated with the identified body.

Exceptions
std::out_of_rangeIf given an invalid body identifier.
See also
GetBodyRange_, CreateBody_, SetBody_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ GetSubStepping_()

virtual bool playrho::d2::detail::WorldConcept::GetSubStepping_ ( ) const
pure virtualnoexcept

Gets whether or not sub-stepping is enabled.

See also
SetSubStepping_, IsStepComplete_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ GetTree_()

virtual const DynamicTree& playrho::d2::detail::WorldConcept::GetTree_ ( ) const
pure virtualnoexcept

Gets access to the broad-phase dynamic tree information.

Todo:
Consider removing this function. This function exposes the implementation detail of the broad-phase contact detection system.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ GetType_()

virtual TypeID playrho::d2::detail::WorldConcept::GetType_ ( ) const
pure virtualnoexcept

Gets the use type information.

Returns
Type info of the underlying value's type.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ IsStepComplete_()

virtual bool playrho::d2::detail::WorldConcept::IsStepComplete_ ( ) const
pure virtualnoexcept

Whether or not "step" is complete.

A "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 function returned without finishing all of its sub-steps.
See also
GetSubStepping_, SetSubStepping_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ SetBody_()

virtual void playrho::d2::detail::WorldConcept::SetBody_ ( BodyID  id,
const Body value 
)
pure virtual

Sets the state of the identified body.

Exceptions
std::out_of_rangeif given an invalid id of if the given body references any invalid shape identifiers.
InvalidArgumentif the specified ID was destroyed.
See also
GetBody_, GetBodyRange_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ SetContact_()

virtual void playrho::d2::detail::WorldConcept::SetContact_ ( ContactID  id,
const Contact value 
)
pure virtual

Sets the identified contact's state.

Parameters
idIdentifier of the contact whose state is to be set.
valueValue the contact is to be set to.
Exceptions
std::out_of_rangeIf given an invalid identifier.
InvalidArgumentif the identifier is to a freed contact or if the new state is not allowable.
See also
GetContact_, GetContactRange_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ SetJoint_()

virtual void playrho::d2::detail::WorldConcept::SetJoint_ ( JointID  id,
const Joint def 
)
pure virtual

Sets the identified joint to the given value.

Exceptions
WrongStateif this function is called while the world is locked.
std::out_of_rangeIf given an invalid joint identifier.
InvalidArgumentif the specified ID was destroyed.
See also
GetJoint_, GetJointRange_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ SetJointDestructionListener_()

virtual void playrho::d2::detail::WorldConcept::SetJointDestructionListener_ ( JointFunction  listener)
pure virtualnoexcept

Sets a destruction listener for joints.

Note
This listener is called on Clear_() for every joint. It's also called on Destroy_(BodyID) for every joint associated with the identified body.
See also
Clear_, Destroy_(BodyID).

Implemented in playrho::d2::detail::WorldModel< T >.

◆ SetManifold_()

virtual void playrho::d2::detail::WorldConcept::SetManifold_ ( ContactID  id,
const Manifold value 
)
pure virtual

Sets the collision manifold for the identified contact.

Exceptions
std::out_of_rangeIf given an invalid contact identifier.
See also
GetManifold_, GetContactRange_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ SetShape_()

virtual void playrho::d2::detail::WorldConcept::SetShape_ ( ShapeID  id,
const Shape def 
)
pure virtual

Sets the identified shape to the new value.

Exceptions
std::out_of_rangeIf given an invalid shape identifier.
InvalidArgumentif the specified ID was destroyed.
See also
CreateShape_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ SetShapeDestructionListener_()

virtual void playrho::d2::detail::WorldConcept::SetShapeDestructionListener_ ( ShapeFunction  listener)
pure virtualnoexcept

Sets the destruction listener for shapes.

Note
This listener is called on Clear_() for every shape.
See also
Clear_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ SetSubStepping_()

virtual void playrho::d2::detail::WorldConcept::SetSubStepping_ ( bool  flag)
pure virtualnoexcept

Enables/disables single stepped continuous physics.

Note
This is not normally used. Enabling sub-stepping is meant for testing.
Postcondition
The GetSubStepping_() function will return the value this function was called with.
See also
IsStepComplete_, GetSubStepping_.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ ShiftOrigin_()

virtual void playrho::d2::detail::WorldConcept::ShiftOrigin_ ( const Length2 newOrigin)
pure virtual

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
newOriginthe new origin with respect to the old origin
Exceptions
WrongStateif this function is called while the world is locked.

Implemented in playrho::d2::detail::WorldModel< T >.

◆ Step_()

virtual StepStats playrho::d2::detail::WorldConcept::Step_ ( const StepConf conf)
pure virtual

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 not specified 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 special handling being processed. No physics is performed.
If the given velocity and position iterations are zero, this function 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.
Parameters
confConfiguration for the simulation step.
Returns
Statistics for the step.
Exceptions
WrongStateif this function is called while the world is locked.

Implemented in playrho::d2::detail::WorldModel< T >.


The documentation for this struct was generated from the following file: