esp::physics::PhysicsManager class

Kinematic and dynamic scene and object manager.

Responsible for tracking, updating, and synchronizing the state of the physical world and all non-static geometry in the scene as well as interfacing with specific physical simulation implementations.

The physical world in this case consists of any objects which can be manipulated (kinematically or dynamically) or simulated and anything such objects must be aware of (e.g. static scene collision geometry).

Will later manager multiple physical scenes, but currently assumes only one unique physical world can exist.

Derived classes

class BulletPhysicsManager
Dynamic scene and object manager interfacing with Bullet physics engine: https://github.com/bulletphysics/bullet3.

Public types

enum PhysicsSimulationLibrary { NONE, BULLET }
==== physics engines ====
using DrawableGroup = gfx::DrawableGroup
Stores references to a set of drawable elements.

Constructors, destructors, conversion operators

PhysicsManager(assets::ResourceManager& _resourceManager, const assets::PhysicsManagerAttributes::cptr _physicsManagerAttributes) explicit
Construct a ref PhysicsManager with access to specific resource assets.
~PhysicsManager() virtual
Destructor.

Public functions

auto initPhysics(scene::SceneNode* node) -> bool
Initialization: load physical properties and setup the world.
void reset() virtual
Reset the simulation and physical world. Sets the worldTime_ to 0.0, does not change physical state.
auto addScene(const std::string& handle, const std::vector<assets::CollisionMeshData>& meshGroup) -> bool
Initialize static scene collision geometry from loaded mesh data. Only one 'scene' may be initialized per simulated world, but this scene may contain several components (e.g. GLB heirarchy).
auto addObject(const std::string& configFile, DrawableGroup* drawables, scene::SceneNode* attachmentNode = nullptr, const Magnum::ResourceKey& lightSetup = Magnum::ResourceKey{ assets::ResourceManager::DEFAULT_LIGHTING_KEY}) -> int
Instance a physical object from an object properties template in the esp::assets::ResourceManager::physicsObjectLibrary_.
auto addObject(const int objectLibIndex, DrawableGroup* drawables, scene::SceneNode* attachmentNode = nullptr, const Magnum::ResourceKey& lightSetup = Magnum::ResourceKey{ assets::ResourceManager::DEFAULT_LIGHTING_KEY}) -> int
Instance a physical object from an object properties template in the esp::assets::ResourceManager::physicsObjectLibrary_ by object library index.
void removeObject(const int physObjectID, bool deleteObjectNode = true, bool deleteVisualNode = true) virtual
Remove an object instance from the pysical scene by ID, destroying its scene graph node and removing it from PhysicsManager::existingObjects_.
auto getNumRigidObjects() const -> int
Get the number of objects mapped in PhysicsManager::existingObjects_.
auto getExistingObjectIDs() const -> std::vector<int>
Get a list of existing object IDs (i.e., existing keys in PhysicsManager::existingObjects_.)
auto setObjectMotionType(const int physObjectID, MotionType mt) -> bool
Set the MotionType of an object, allowing or disallowing its manipulation by dynamic processes or kinematic control.
auto getObjectMotionType(const int physObjectID) const -> MotionType
Get the MotionType of an object.
void stepPhysics(double dt = 0.0) virtual
Step the physical world forward in time. Time may only advance in increments of fixedTimeStep_.
void setTimestep(double dt) virtual
Set the fixedTimeStep_ of the physical world. See stepPhysics.
void setGravity(const Magnum::Vector3& gravity) virtual
Set the gravity of the physical world if the world is dyanmic and therefore has a notion of force. By default does nothing since the world is kinematic. Exact implementations of gravity will depend on the specific dynamics of the derived physical simulator class.
auto getTimestep() const -> double virtual
Get the fixedTimeStep_ of the physical world. See stepPhysics.
auto getWorldTime() const -> double virtual
Get the current worldTime_ of the physical world. See stepPhysics.
auto getGravity() const -> Magnum::Vector3 virtual
Get the current gravity in the physical world. By default returns [0,0,0] since their is no notion of force in a kinematic world.
auto getSceneFrictionCoefficient() const -> double virtual
Get the current friction coefficient of the scene collision geometry. See staticSceneObject_.
void setSceneFrictionCoefficient(CORRADE_UNUSED const double frictionCoefficient) virtual
Set the friction coefficient of the scene collision geometry. See staticSceneObject_.
auto getSceneRestitutionCoefficient() const -> double virtual
Get the current coefficient of restitution for the scene collision geometry. This determines the ratio of initial to final relative velocity between the scene and collidiing object. See staticSceneObject_. By default this will always return 0, since kinametic scenes have no dynamics.
void setSceneRestitutionCoefficient(CORRADE_UNUSED const double restitutionCoefficient) virtual
Set the coefficient of restitution for the scene collision geometry. See staticSceneObject_. By default does nothing since kinametic scenes have no dynamics.
void setTransformation(const int physObjectID, const Magnum::Matrix4& trans)
Set the 4x4 transformation matrix of an object kinematically. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.
void setRigidState(const int physObjectID, const esp::core::RigidState& rigidState)
Set the esp::core::RigidState of an object kinematically. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.
void setTranslation(const int physObjectID, const Magnum::Vector3& vector)
Set the 3D position of an object kinematically. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.
void setRotation(const int physObjectID, const Magnum::Quaternion& quaternion)
Set the orientation of an object kinematically. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.
void resetTransformation(const int physObjectID)
Reset the transformation of the object. !!NOT IMPLEMENTED!!
void translate(const int physObjectID, const Magnum::Vector3& vector)
Modify the 3D position of an object kinematically by translation. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.
void translateLocal(const int physObjectID, const Magnum::Vector3& vector)
Modify the 3D position of an object kinematically by translation with a vector defined in the object's local coordinate system. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.
void rotate(const int physObjectID, const Magnum::Rad angleInRad, const Magnum::Vector3& normalizedAxis)
Modify the orientation of an object kinematically by applying an axis-angle rotation to it. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.
void rotateLocal(const int physObjectID, const Magnum::Rad angleInRad, const Magnum::Vector3& normalizedAxis)
Modify the orientation of an object kinematically by applying an axis-angle rotation to it in the local coordinate system. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.
void rotateX(const int physObjectID, const Magnum::Rad angleInRad)
Modify the orientation of an object kinematically by applying a rotation to it about the global X axis. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.
void rotateY(const int physObjectID, const Magnum::Rad angleInRad)
Modify the orientation of an object kinematically by applying a rotation to it about the global Y axis. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.
void rotateZ(const int physObjectID, const Magnum::Rad angleInRad)
Modify the orientation of an object kinematically by applying a rotation to it about the global Z axis. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.
void rotateXLocal(const int physObjectID, const Magnum::Rad angleInRad)
Modify the orientation of an object kinematically by applying a rotation to it about the local X axis. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.
void rotateYLocal(const int physObjectID, const Magnum::Rad angleInRad)
Modify the orientation of an object kinematically by applying a rotation to it about the local Y axis. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.
void rotateZLocal(const int physObjectID, const Magnum::Rad angleInRad)
Modify the orientation of an object kinematically by applying a rotation to it about the local Z axis. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.
auto getTransformation(const int physObjectID) const -> Magnum::Matrix4
Get the current 4x4 transformation matrix of an object.
auto getRigidState(const int objectID) const -> esp::core::RigidState
Get the current esp::core::RigidState of an object.
auto getTranslation(const int physObjectID) const -> Magnum::Vector3
Get the current 3D position of an object.
auto getRotation(const int physObjectID) const -> Magnum::Quaternion
Get the current orientation of an object.
void setMass(const int physObjectID, const double mass)
Set the mass of an object. See RigidObject::setMass.
void setCOM(const int physObjectID, const Magnum::Vector3& COM)
Set the center of mass (COM) of an object. Warning: some physics implementations require that object origins coincide with thier COM. See BulletRigidObject. Therefore, be careful modifying this value. See RigidObject::setCOM.
void setInertiaVector(const int physObjectID, const Magnum::Vector3& inertia)
Set the diagonal of the inertia matrix for an object. If an object is aligned with its principle axii of inertia, the 3x3 inertia matrix can be reduced to a diagonal. See RigidObject::setInertiaVector.
void setFrictionCoefficient(const int physObjectID, const double frictionCoefficient)
Set the scalar friction coefficient for an object. See RigidObject::setFrictionCoefficient.
void setRestitutionCoefficient(const int physObjectID, const double restitutionCoefficient)
Set the scalar coefficient of restitution for an object. See RigidObject::setRestitutionCoefficient.
void setLinearDamping(const int physObjectID, const double linDamping)
Set the scalar linear damping coefficient for an object. See RigidObject::setLinearDamping.
void setAngularDamping(const int physObjectID, const double angDamping)
Set the scalar angular damping coefficient for an object. See RigidObject::setAngularDamping.
auto getMass(const int physObjectID) const -> double
Get the mass of an object. See RigidObject::getMass.
auto getCOM(const int physObjectID) const -> Magnum::Vector3
Get the center of mass (COM) of an object. See RigidObject::getCOM.
auto getInertiaVector(const int physObjectID) const -> Magnum::Vector3
Get the diagnoal vector of the inertia matrix of an object. See RigidObject::getInertiaVector.
auto getInertiaMatrix(const int physObjectID) const -> Magnum::Matrix3
Get the 3x3 inertia matrix of an object. See RigidObject::getInertiaMatrix.
auto getScale(const int physObjectID) const -> Magnum::Vector3
Get the scale of an object set during initialization. See RigidObject::getScale.
auto getFrictionCoefficient(const int physObjectID) const -> double
Get the scalar coefficient of friction of an object. See RigidObject::getFrictionCoefficient.
auto getRestitutionCoefficient(const int physObjectID) const -> double
Get the scalar coefficient of restitution of an object. See RigidObject::getRestitutionCoefficient.
auto getLinearDamping(const int physObjectID) const -> double
Get the scalar linear damping coefficient of an object. See RigidObject::getLinearDamping.
auto getAngularDamping(const int physObjectID) const -> double
Get the scalar angular damping coefficient of an object. See RigidObject::getAngularDamping.
auto getMargin(CORRADE_UNUSED const int physObjectID) const -> double virtual
Get the scalar collision margin of an object. See BulletRigidObject::getMargin.
void setMargin(CORRADE_UNUSED const int physObjectID, CORRADE_UNUSED const double margin) virtual
Set the scalar collision margin of an object. See BulletRigidObject::setMargin. Nothing is set if no implementation using a collision margin is in use.
auto checkActiveObjects() -> int
Get the number of objects in PhysicsManager::existingObjects_ considered active by the physics simulator currently in use. See RigidObject::isActive.
auto isActive(const int physObjectID) const -> bool
True if the object is considered active by the simulator physics simulator currently in use. See RigidObject::isActive.
void applyForce(const int physObjectID, const Magnum::Vector3& force, const Magnum::Vector3& relPos)
Apply a linear 3D force defined in global coordinates to an object. See RigidObject::applyForce.
void applyImpulse(const int physObjectID, const Magnum::Vector3& impulse, const Magnum::Vector3& relPos)
Apply a linear 3D impulse defined in global coordinates to an object. See RigidObject::applyImpulse. Impulse is applied instantly to modify object velocity (i.e., not integrated through dynamic equations).
void applyTorque(const int physObjectID, const Magnum::Vector3& torque)
Apply an internal angular 3D torque to an object. See RigidObject::applyTorque.
void applyImpulseTorque(const int physObjectID, const Magnum::Vector3& impulse)
Apply an internal angular 3D impulse torque to an object. See RigidObject::applyImpulseTorque.
void setLinearVelocity(const int physObjectID, const Magnum::Vector3& linVel)
Set linear velocity for an object with MotionType::DYNAMIC.
void setAngularVelocity(const int physObjectID, const Magnum::Vector3& angVel)
Set angular velocity for an object with MotionType::DYNAMIC.
auto getLinearVelocity(const int physObjectID) const -> Magnum::Vector3
Get linear velocity of an object with MotionType::DYNAMIC.
auto getAngularVelocity(const int physObjectID) const -> Magnum::Vector3
Get angular velocity of an object with MotionType::DYNAMIC.
auto getVelocityControl(const int physObjectID) -> VelocityControl::ptr
Retrieves a shared pointer to the VelocityControl struct for this object.
void setObjectBBDraw(int physObjectID, DrawableGroup* drawables, bool drawBB)
Set bounding box rendering for the object true or false.
auto getObjectSceneNode(int physObjectID) const -> const scene::SceneNode&
Get a const reference to the specified object's SceneNode for info query purposes.
auto getObjectSceneNode(int physObjectID) -> scene::SceneNode&
auto getObjectVisualSceneNode(int physObjectID) const -> const scene::SceneNode&
Get a const reference to the specified object's visual SceneNode for info query purposes.
auto getObjectVisualSceneNodes(const int objectID) const -> std::vector<scene::SceneNode*>
Get pointers to an object's visual SceneNodes.
void debugDraw(CORRADE_UNUSED const Magnum::Matrix4& projTrans) const virtual
Render any debugging visualizations provided by the underlying physics simulator implementation. By default does nothing. See BulletPhysicsManager::debugDraw.
auto contactTest(CORRADE_UNUSED const int physObjectID) -> bool virtual
Check whether an object is in contact with any other objects or the scene.
auto getPhysicsSimulationLibrary() const -> const PhysicsSimulationLibrary&
Return the library implementation type for the simulator currently in use. Use to check for a particular implementation.
void setSemanticId(int physObjectID, uint32_t semanticId)
Set the esp::scene:SceneNode::semanticId_ for all visual nodes belonging to an object.
auto getObjectInitAttributes(const int physObjectID) const -> assets::PhysicsObjectAttributes::ptr
Get a copy of the template used to initialize an object.
auto getInitializationAttributes() const -> assets::PhysicsManagerAttributes::ptr
Get a copy of the template used to initialize this physics manager.
auto castRay(const esp::geo::Ray& ray, CORRADE_UNUSED double maxDistance = 100.0) -> RaycastResults virtual
Cast a ray into the collision world and return a RaycastResults with hit information.

Protected functions

void assertIDValidity(const int physObjectID) const virtual
Check that a given object ID is valid (i.e. it refers to an existing object). Terminate the program and report an error if not. This function is intended to unify object ID checking for PhysicsManager functions.
auto isMeshPrimitiveValid(const assets::CollisionMeshData& meshData) -> bool virtual
Check if a particular mesh can be used as a collision mesh for a particular physics implemenation. Always True for base PhysicsManager class, since the mesh has already been successfully loaded by esp::assets::ResourceManager.
auto allocateObjectID() -> int
Acquire a new ObjectID by recycling the ID of an object removed with removeObject or by incrementing nextObjectID_. See addObject.
auto deallocateObjectID(int physObjectID) -> int
Recycle the ID of an object removed with removeObject by adding it to the list of available IDs: recycledObjectIDs_.
auto initPhysicsFinalize() -> bool virtual
Finalize physics initialization. Setup staticSceneObject_ and initialize any other physics-related values for physics-based scenes. Overidden by instancing class if physics is supported.
auto addSceneFinalize(const std::string& handle) -> bool virtual
Finalize scene initialization for kinematic scenes. Overidden by instancing class if physics is supported.
auto makeAndAddRigidObject(int newObjectID, const std::string& handle, scene::SceneNode* objectNode) -> bool virtual
Create and initialize a RigidObject, assign it an ID and add it to existingObjects_ map keyed with newObjectID.

Protected variables

assets::ResourceManager& resourceManager_
A reference to a esp::assets::ResourceManager which holds assets that can be accessed by this PhysicsManager.
const assets::PhysicsManagerAttributes::cptr physicsManagerAttributes_
A pointer to the assets::PhysicsManagerAttributes describing this physics manager.
PhysicsSimulationLibrary activePhysSimLib_
The current physics library implementation used by this PhysicsManager. Can be used to correctly cast the PhysicsManager to its derived type if necessary.
scene::SceneNode* physicsNode_
The scene::SceneNode which is the parent of all members of the scene graph which exist in the physical world. Used to keep track of all SceneNode's that have physical properties.
physics::RigidScene::uptr staticSceneObject_
The scene::SceneNode which represents the static collision geometry of the physical world. Only one staticSceneObject_ may exist in a physical world. This RigidScene can only have MotionType::STATIC as it is loaded as static geometry with simulation efficiency in mind. See addScene.
std::map<int, physics::RigidObject::uptr> existingObjects_
==== Rigid object memory management ====
int nextObjectID_
A counter of unique object ID's allocated thus far. Used to allocate new IDs when recycledObjectIDs_ is empty without needing to check existingObjects_ explicitly.
std::vector<int> recycledObjectIDs_
A list of available object IDs tracked by deallocateObjectID which were previously used by objects since removed from the world with removeObject. These IDs will be re-allocated with allocateObjectID before new IDs are acquired with nextObjectID_.
bool initialized_
Utilities.
double fixedTimeStep_
The fixed amount of time over which to integrate the simulation in discrete steps within stepPhysics. Lower values result in better stability at the cost of worse efficiency and vice versa.
double worldTime_
The current simulation time. Tracks the total amount of time simulated with stepPhysics up to this point.

Enum documentation

enum esp::physics::PhysicsManager::PhysicsSimulationLibrary

==== physics engines ====

The specific physics implementation used by the current PhysicsManager. Each entry suggests a derived class of PhysicsManager and RigidObject implementing the specific interface to a simulation library.

Enumerators
NONE

The default implemenation of kineamtics through the base PhysicsManager class. Supports MotionType::STATIC and MotionType::KINEMATIC objects of base class RigidObject. If the derived PhysicsManager class for a desired PhysicsSimulationLibrary fails to initialize, it will default to PhysicsSimulationLibrary::NONE.

BULLET

An implemenation of dynamics through the Bullet Physics library. Supports MotionType::STATIC, MotionType::KINEMATIC, and MotionType::DYNAMIC objects of RigidObject derived class BulletRigidObject. Suggests the use of PhysicsManager derived class BulletPhysicsManager

Function documentation

esp::physics::PhysicsManager::PhysicsManager(assets::ResourceManager& _resourceManager, const assets::PhysicsManagerAttributes::cptr _physicsManagerAttributes) explicit

Construct a ref PhysicsManager with access to specific resource assets.

Parameters
_resourceManager The esp::assets::ResourceManager which tracks the assets this PhysicsManager will have access to.
_physicsManagerAttributes

bool esp::physics::PhysicsManager::initPhysics(scene::SceneNode* node)

Initialization: load physical properties and setup the world.

Parameters
node The scene graph node which will act as the parent of all physical scene and object nodes.

bool esp::physics::PhysicsManager::addScene(const std::string& handle, const std::vector<assets::CollisionMeshData>& meshGroup)

Initialize static scene collision geometry from loaded mesh data. Only one 'scene' may be initialized per simulated world, but this scene may contain several components (e.g. GLB heirarchy).

Parameters
handle The handle to the attributes structure defining physical properties of the scene.
meshGroup collision meshs for the scene.
Returns true if successful and false otherwise

int esp::physics::PhysicsManager::addObject(const std::string& configFile, DrawableGroup* drawables, scene::SceneNode* attachmentNode = nullptr, const Magnum::ResourceKey& lightSetup = Magnum::ResourceKey{ assets::ResourceManager::DEFAULT_LIGHTING_KEY})

Instance a physical object from an object properties template in the esp::assets::ResourceManager::physicsObjectLibrary_.

Parameters
configFile The filename of the object's physical properties file used as the key to query esp::assets::ResourceManager::physicsObjectLibrary_
drawables Reference to the scene graph drawables group to enable rendering of the newly initialized object.
attachmentNode If supplied, attach the new physical object to an existing SceneNode.
lightSetup
Returns the instanced object's ID, mapping to it in PhysicsManager::existingObjects_ if successful, or esp::ID_UNDEFINED.

int esp::physics::PhysicsManager::addObject(const int objectLibIndex, DrawableGroup* drawables, scene::SceneNode* attachmentNode = nullptr, const Magnum::ResourceKey& lightSetup = Magnum::ResourceKey{ assets::ResourceManager::DEFAULT_LIGHTING_KEY})

Instance a physical object from an object properties template in the esp::assets::ResourceManager::physicsObjectLibrary_ by object library index.

Parameters
objectLibIndex The index of the object's template in esp::assets::ResourceManager::physicsObjectLibrary_
drawables Reference to the scene graph drawables group to enable rendering of the newly initialized object.
attachmentNode If supplied, attach the new physical object to an existing SceneNode.
lightSetup
Returns the instanced object's ID, mapping to it in PhysicsManager::existingObjects_ if successful, or esp::ID_UNDEFINED.

void esp::physics::PhysicsManager::removeObject(const int physObjectID, bool deleteObjectNode = true, bool deleteVisualNode = true) virtual

Remove an object instance from the pysical scene by ID, destroying its scene graph node and removing it from PhysicsManager::existingObjects_.

Parameters
physObjectID The ID (key) of the object instance in PhysicsManager::existingObjects_.
deleteObjectNode If true, deletes the object's scene node. Otherwise detaches the object from simulation.
deleteVisualNode If true, deletes the object's visual node. Otherwise detaches the object from simulation. Is not considered if deleteObjectNode==true.

int esp::physics::PhysicsManager::getNumRigidObjects() const

Get the number of objects mapped in PhysicsManager::existingObjects_.

Returns The size of PhysicsManager::existingObjects_.

std::vector<int> esp::physics::PhysicsManager::getExistingObjectIDs() const

Get a list of existing object IDs (i.e., existing keys in PhysicsManager::existingObjects_.)

Returns List of object ID keys from PhysicsManager::existingObjects_.

bool esp::physics::PhysicsManager::setObjectMotionType(const int physObjectID, MotionType mt)

Set the MotionType of an object, allowing or disallowing its manipulation by dynamic processes or kinematic control.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
mt The desired MotionType of the object to set.
Returns True if set was successful and False otherwise.

MotionType esp::physics::PhysicsManager::getObjectMotionType(const int physObjectID) const

Get the MotionType of an object.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
Returns The object's MotionType

void esp::physics::PhysicsManager::stepPhysics(double dt = 0.0) virtual

Step the physical world forward in time. Time may only advance in increments of fixedTimeStep_.

Parameters
dt The desired amount of time to advance the physical world.

void esp::physics::PhysicsManager::setTimestep(double dt) virtual

Set the fixedTimeStep_ of the physical world. See stepPhysics.

Parameters
dt The increment of time by which the physical world will advance.

void esp::physics::PhysicsManager::setGravity(const Magnum::Vector3& gravity) virtual

Set the gravity of the physical world if the world is dyanmic and therefore has a notion of force. By default does nothing since the world is kinematic. Exact implementations of gravity will depend on the specific dynamics of the derived physical simulator class.

Parameters
gravity The desired gravity force of the physical world.

double esp::physics::PhysicsManager::getTimestep() const virtual

Get the fixedTimeStep_ of the physical world. See stepPhysics.

Returns The increment of time, fixedTimeStep_, by which the physical world will advance.

double esp::physics::PhysicsManager::getWorldTime() const virtual

Get the current worldTime_ of the physical world. See stepPhysics.

Returns The amount of time, worldTime_, by which the physical world has advanced.

Magnum::Vector3 esp::physics::PhysicsManager::getGravity() const virtual

Get the current gravity in the physical world. By default returns [0,0,0] since their is no notion of force in a kinematic world.

Returns The current gravity vector in the physical world.

double esp::physics::PhysicsManager::getSceneFrictionCoefficient() const virtual

Get the current friction coefficient of the scene collision geometry. See staticSceneObject_.

Returns The scalar friction coefficient of the scene geometry.

void esp::physics::PhysicsManager::setSceneFrictionCoefficient(CORRADE_UNUSED const double frictionCoefficient) virtual

Set the friction coefficient of the scene collision geometry. See staticSceneObject_.

Parameters
frictionCoefficient The scalar friction coefficient of the scene geometry.

double esp::physics::PhysicsManager::getSceneRestitutionCoefficient() const virtual

Get the current coefficient of restitution for the scene collision geometry. This determines the ratio of initial to final relative velocity between the scene and collidiing object. See staticSceneObject_. By default this will always return 0, since kinametic scenes have no dynamics.

Returns The scalar coefficient of restitution for the scene geometry.

void esp::physics::PhysicsManager::setSceneRestitutionCoefficient(CORRADE_UNUSED const double restitutionCoefficient) virtual

Set the coefficient of restitution for the scene collision geometry. See staticSceneObject_. By default does nothing since kinametic scenes have no dynamics.

Parameters
restitutionCoefficient The scalar coefficient of restitution to set.

void esp::physics::PhysicsManager::setTransformation(const int physObjectID, const Magnum::Matrix4& trans)

Set the 4x4 transformation matrix of an object kinematically. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
trans The desired 4x4 transform of the object.

void esp::physics::PhysicsManager::setRigidState(const int physObjectID, const esp::core::RigidState& rigidState)

Set the esp::core::RigidState of an object kinematically. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
rigidState

void esp::physics::PhysicsManager::setTranslation(const int physObjectID, const Magnum::Vector3& vector)

Set the 3D position of an object kinematically. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
vector The desired 3D position of the object.

void esp::physics::PhysicsManager::setRotation(const int physObjectID, const Magnum::Quaternion& quaternion)

Set the orientation of an object kinematically. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
quaternion The desired orientation of the object.

void esp::physics::PhysicsManager::resetTransformation(const int physObjectID)

Reset the transformation of the object. !!NOT IMPLEMENTED!!

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.

void esp::physics::PhysicsManager::translate(const int physObjectID, const Magnum::Vector3& vector)

Modify the 3D position of an object kinematically by translation. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
vector The desired 3D vector by which to translate the object.

void esp::physics::PhysicsManager::translateLocal(const int physObjectID, const Magnum::Vector3& vector)

Modify the 3D position of an object kinematically by translation with a vector defined in the object's local coordinate system. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
vector The desired 3D vector in the object's ocal coordiante system by which to translate the object.

void esp::physics::PhysicsManager::rotate(const int physObjectID, const Magnum::Rad angleInRad, const Magnum::Vector3& normalizedAxis)

Modify the orientation of an object kinematically by applying an axis-angle rotation to it. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
angleInRad The angle of rotation in radians.
normalizedAxis The desired unit vector axis of rotation.

void esp::physics::PhysicsManager::rotateLocal(const int physObjectID, const Magnum::Rad angleInRad, const Magnum::Vector3& normalizedAxis)

Modify the orientation of an object kinematically by applying an axis-angle rotation to it in the local coordinate system. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
angleInRad The angle of rotation in radians.
normalizedAxis The desired unit vector axis of rotation in the local coordinate system.

void esp::physics::PhysicsManager::rotateX(const int physObjectID, const Magnum::Rad angleInRad)

Modify the orientation of an object kinematically by applying a rotation to it about the global X axis. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
angleInRad The angle of rotation in radians.

void esp::physics::PhysicsManager::rotateY(const int physObjectID, const Magnum::Rad angleInRad)

Modify the orientation of an object kinematically by applying a rotation to it about the global Y axis. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
angleInRad The angle of rotation in radians.

void esp::physics::PhysicsManager::rotateZ(const int physObjectID, const Magnum::Rad angleInRad)

Modify the orientation of an object kinematically by applying a rotation to it about the global Z axis. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
angleInRad The angle of rotation in radians.

void esp::physics::PhysicsManager::rotateXLocal(const int physObjectID, const Magnum::Rad angleInRad)

Modify the orientation of an object kinematically by applying a rotation to it about the local X axis. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
angleInRad The angle of rotation in radians.

void esp::physics::PhysicsManager::rotateYLocal(const int physObjectID, const Magnum::Rad angleInRad)

Modify the orientation of an object kinematically by applying a rotation to it about the local Y axis. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
angleInRad The angle of rotation in radians.

void esp::physics::PhysicsManager::rotateZLocal(const int physObjectID, const Magnum::Rad angleInRad)

Modify the orientation of an object kinematically by applying a rotation to it about the local Z axis. Calling this during simulation of a MotionType::DYNAMIC object is not recommended.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
angleInRad The angle of rotation in radians.

Magnum::Matrix4 esp::physics::PhysicsManager::getTransformation(const int physObjectID) const

Get the current 4x4 transformation matrix of an object.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
Returns The 4x4 transform of the object.

esp::core::RigidState esp::physics::PhysicsManager::getRigidState(const int objectID) const

Get the current esp::core::RigidState of an object.

Returns The esp::core::RigidState of the object.

Magnum::Vector3 esp::physics::PhysicsManager::getTranslation(const int physObjectID) const

Get the current 3D position of an object.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
Returns The 3D position of the object.

Magnum::Quaternion esp::physics::PhysicsManager::getRotation(const int physObjectID) const

Get the current orientation of an object.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
Returns A quaternion representation of the object's orientation.

void esp::physics::PhysicsManager::setMass(const int physObjectID, const double mass)

Set the mass of an object. See RigidObject::setMass.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
mass The new mass of the object.

void esp::physics::PhysicsManager::setCOM(const int physObjectID, const Magnum::Vector3& COM)

Set the center of mass (COM) of an object. Warning: some physics implementations require that object origins coincide with thier COM. See BulletRigidObject. Therefore, be careful modifying this value. See RigidObject::setCOM.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
COM The new 3D center of mass for the object in the local coordinate system.

void esp::physics::PhysicsManager::setInertiaVector(const int physObjectID, const Magnum::Vector3& inertia)

Set the diagonal of the inertia matrix for an object. If an object is aligned with its principle axii of inertia, the 3x3 inertia matrix can be reduced to a diagonal. See RigidObject::setInertiaVector.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
inertia The new diagonal for the object's inertia matrix.

void esp::physics::PhysicsManager::setFrictionCoefficient(const int physObjectID, const double frictionCoefficient)

Set the scalar friction coefficient for an object. See RigidObject::setFrictionCoefficient.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
frictionCoefficient The new scalar coefficient of friction for the object.

void esp::physics::PhysicsManager::setRestitutionCoefficient(const int physObjectID, const double restitutionCoefficient)

Set the scalar coefficient of restitution for an object. See RigidObject::setRestitutionCoefficient.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
restitutionCoefficient The new scalar coefficient of restitution for the object.

void esp::physics::PhysicsManager::setLinearDamping(const int physObjectID, const double linDamping)

Set the scalar linear damping coefficient for an object. See RigidObject::setLinearDamping.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
linDamping The new scalar linear damping coefficient for the object.

void esp::physics::PhysicsManager::setAngularDamping(const int physObjectID, const double angDamping)

Set the scalar angular damping coefficient for an object. See RigidObject::setAngularDamping.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
angDamping The new scalar angular damping coefficient for the object.

double esp::physics::PhysicsManager::getMass(const int physObjectID) const

Get the mass of an object. See RigidObject::getMass.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
Returns Object mass or esp::PHYSICS_ATTR_UNDEFINED if failed.

Magnum::Vector3 esp::physics::PhysicsManager::getCOM(const int physObjectID) const

Get the center of mass (COM) of an object. See RigidObject::getCOM.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
Returns Object 3D center of mass in the local coordinate system.

Magnum::Vector3 esp::physics::PhysicsManager::getInertiaVector(const int physObjectID) const

Get the diagnoal vector of the inertia matrix of an object. See RigidObject::getInertiaVector.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
Returns The diagnoal vector of the inertia matrix of the object.

Magnum::Matrix3 esp::physics::PhysicsManager::getInertiaMatrix(const int physObjectID) const

Get the 3x3 inertia matrix of an object. See RigidObject::getInertiaMatrix.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
Returns The 3x3 inertia matrix of the object.

Magnum::Vector3 esp::physics::PhysicsManager::getScale(const int physObjectID) const

Get the scale of an object set during initialization. See RigidObject::getScale.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
Returns The scaling of the object relative to its initialy loaded meshes.

double esp::physics::PhysicsManager::getFrictionCoefficient(const int physObjectID) const

Get the scalar coefficient of friction of an object. See RigidObject::getFrictionCoefficient.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
Returns The scalar coefficient of friction of the object.

double esp::physics::PhysicsManager::getRestitutionCoefficient(const int physObjectID) const

Get the scalar coefficient of restitution of an object. See RigidObject::getRestitutionCoefficient.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
Returns The scalar coefficient of restitution of the object.

double esp::physics::PhysicsManager::getLinearDamping(const int physObjectID) const

Get the scalar linear damping coefficient of an object. See RigidObject::getLinearDamping.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
Returns The scalar linear damping coefficient of the object.

double esp::physics::PhysicsManager::getAngularDamping(const int physObjectID) const

Get the scalar angular damping coefficient of an object. See RigidObject::getAngularDamping.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
Returns The scalar angular damping coefficient of the object

double esp::physics::PhysicsManager::getMargin(CORRADE_UNUSED const int physObjectID) const virtual

Get the scalar collision margin of an object. See BulletRigidObject::getMargin.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
Returns The scalar collision margin of the object.

void esp::physics::PhysicsManager::setMargin(CORRADE_UNUSED const int physObjectID, CORRADE_UNUSED const double margin) virtual

Set the scalar collision margin of an object. See BulletRigidObject::setMargin. Nothing is set if no implementation using a collision margin is in use.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
margin The desired collision margin for the object.

int esp::physics::PhysicsManager::checkActiveObjects()

Get the number of objects in PhysicsManager::existingObjects_ considered active by the physics simulator currently in use. See RigidObject::isActive.

Returns The number of active RigidObject instances.

bool esp::physics::PhysicsManager::isActive(const int physObjectID) const

True if the object is considered active by the simulator physics simulator currently in use. See RigidObject::isActive.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
Returns Whether or not the object is active.

void esp::physics::PhysicsManager::applyForce(const int physObjectID, const Magnum::Vector3& force, const Magnum::Vector3& relPos)

Apply a linear 3D force defined in global coordinates to an object. See RigidObject::applyForce.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
force The linear 3D force to apply to the object.
relPos The global 3D location relative to the object COM at which to apply the force.

void esp::physics::PhysicsManager::applyImpulse(const int physObjectID, const Magnum::Vector3& impulse, const Magnum::Vector3& relPos)

Apply a linear 3D impulse defined in global coordinates to an object. See RigidObject::applyImpulse. Impulse is applied instantly to modify object velocity (i.e., not integrated through dynamic equations).

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
impulse The linear 3D impulse to apply to the object.
relPos The global 3D location relative to the object COM at which to apply the impulse.

void esp::physics::PhysicsManager::applyTorque(const int physObjectID, const Magnum::Vector3& torque)

Apply an internal angular 3D torque to an object. See RigidObject::applyTorque.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
torque The angular torque to apply to the object.

void esp::physics::PhysicsManager::applyImpulseTorque(const int physObjectID, const Magnum::Vector3& impulse)

Apply an internal angular 3D impulse torque to an object. See RigidObject::applyImpulseTorque.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
impulse The angular impulse torque to apply to the object.

void esp::physics::PhysicsManager::setLinearVelocity(const int physObjectID, const Magnum::Vector3& linVel)

Set linear velocity for an object with MotionType::DYNAMIC.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
linVel Linear velocity to set.

Does nothing for MotionType::KINEMATIC or MotionType::STATIC objects.

void esp::physics::PhysicsManager::setAngularVelocity(const int physObjectID, const Magnum::Vector3& angVel)

Set angular velocity for an object with MotionType::DYNAMIC.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
angVel Angular velocity vector corresponding to world unit axis angles.

Does nothing for MotionType::KINEMATIC or MotionType::STATIC objects.

Magnum::Vector3 esp::physics::PhysicsManager::getLinearVelocity(const int physObjectID) const

Get linear velocity of an object with MotionType::DYNAMIC.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
Returns Linear velocity of the object.

Always zero for MotionType::KINEMATIC or MotionType::STATIC objects.

Magnum::Vector3 esp::physics::PhysicsManager::getAngularVelocity(const int physObjectID) const

Get angular velocity of an object with MotionType::DYNAMIC.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
Returns Angular velocity vector corresponding to world unit axis angles.

Always zero for MotionType::KINEMATIC or MotionType::STATIC objects.

void esp::physics::PhysicsManager::setObjectBBDraw(int physObjectID, DrawableGroup* drawables, bool drawBB)

Set bounding box rendering for the object true or false.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
drawables The drawables group with which to render the bounding box.
drawBB Set rendering of the bounding box to true or false.

const scene::SceneNode& esp::physics::PhysicsManager::getObjectSceneNode(int physObjectID) const

Get a const reference to the specified object's SceneNode for info query purposes.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
Returns Const reference to the object scene node.

scene::SceneNode& esp::physics::PhysicsManager::getObjectSceneNode(int physObjectID)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

const scene::SceneNode& esp::physics::PhysicsManager::getObjectVisualSceneNode(int physObjectID) const

Get a const reference to the specified object's visual SceneNode for info query purposes.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
Returns Const reference to the object's visual scene node.

std::vector<scene::SceneNode*> esp::physics::PhysicsManager::getObjectVisualSceneNodes(const int objectID) const

Get pointers to an object's visual SceneNodes.

Returns pointers to the object's visual scene nodes.

void esp::physics::PhysicsManager::debugDraw(CORRADE_UNUSED const Magnum::Matrix4& projTrans) const virtual

Render any debugging visualizations provided by the underlying physics simulator implementation. By default does nothing. See BulletPhysicsManager::debugDraw.

Parameters
projTrans The composed projection and transformation matrix for the render camera.

bool esp::physics::PhysicsManager::contactTest(CORRADE_UNUSED const int physObjectID) virtual

Check whether an object is in contact with any other objects or the scene.

Parameters
physObjectID The object ID and key identifying the object in PhysicsManager::existingObjects_.
Returns Whether or not the object is in contact with any other collision enabled objects.

Not implemented for default PhysicsManager. See BulletPhysicsManager.

const PhysicsSimulationLibrary& esp::physics::PhysicsManager::getPhysicsSimulationLibrary() const

Return the library implementation type for the simulator currently in use. Use to check for a particular implementation.

Returns The implementation type of this simulator.

void esp::physics::PhysicsManager::setSemanticId(int physObjectID, uint32_t semanticId)

Set the esp::scene:SceneNode::semanticId_ for all visual nodes belonging to an object.

Parameters
physObjectID
semanticId The desired semantic id for the object.

assets::PhysicsObjectAttributes::ptr esp::physics::PhysicsManager::getObjectInitAttributes(const int physObjectID) const

Get a copy of the template used to initialize an object.

Returns The initialization settings of the specified object instance.

assets::PhysicsManagerAttributes::ptr esp::physics::PhysicsManager::getInitializationAttributes() const

Get a copy of the template used to initialize this physics manager.

Returns The initialization settings for this physics manager

RaycastResults esp::physics::PhysicsManager::castRay(const esp::geo::Ray& ray, CORRADE_UNUSED double maxDistance = 100.0) virtual

Cast a ray into the collision world and return a RaycastResults with hit information.

Parameters
ray The ray to cast. Need not be unit length, but returned hit distances will be in units of ray length.
maxDistance The maximum distance along the ray direction to search. In units of ray length.
Returns The raycast results sorted by distance.

Note: not implemented here in default PhysicsManager as there are no collision objects without a simulation implementation.

void esp::physics::PhysicsManager::assertIDValidity(const int physObjectID) const virtual protected

Check that a given object ID is valid (i.e. it refers to an existing object). Terminate the program and report an error if not. This function is intended to unify object ID checking for PhysicsManager functions.

Parameters
physObjectID The object ID to validate.

bool esp::physics::PhysicsManager::isMeshPrimitiveValid(const assets::CollisionMeshData& meshData) virtual protected

Check if a particular mesh can be used as a collision mesh for a particular physics implemenation. Always True for base PhysicsManager class, since the mesh has already been successfully loaded by esp::assets::ResourceManager.

Parameters
meshData The mesh to validate.
Returns true if valid, false otherwise.

int esp::physics::PhysicsManager::allocateObjectID() protected

Acquire a new ObjectID by recycling the ID of an object removed with removeObject or by incrementing nextObjectID_. See addObject.

Returns The newly allocated ObjectID.

int esp::physics::PhysicsManager::deallocateObjectID(int physObjectID) protected

Recycle the ID of an object removed with removeObject by adding it to the list of available IDs: recycledObjectIDs_.

Parameters
physObjectID The ID to recycle.
Returns The recycled object ID.

bool esp::physics::PhysicsManager::addSceneFinalize(const std::string& handle) virtual protected

Finalize scene initialization for kinematic scenes. Overidden by instancing class if physics is supported.

Parameters
handle the handle to the attributes structure defining physical properties of the scene.
Returns true if successful and false otherwise

bool esp::physics::PhysicsManager::makeAndAddRigidObject(int newObjectID, const std::string& handle, scene::SceneNode* objectNode) virtual protected

Create and initialize a RigidObject, assign it an ID and add it to existingObjects_ map keyed with newObjectID.

Parameters
newObjectID valid object ID for the new object
handle The handle to the physical object's template defining its physical parameters.
objectNode Valid, existing scene node
Returns whether the object has been successfully initialized and added to existingObjects_ map

Variable documentation

std::map<int, physics::RigidObject::uptr> esp::physics::PhysicsManager::existingObjects_ protected

==== Rigid object memory management ====

Maps object IDs to all existing physical object instances in the world.

bool esp::physics::PhysicsManager::initialized_ protected

Utilities.

Tracks whether or not this PhysicsManager has already been initialized with initPhysics.