1
edit
Changes
→Functions
<sup></sup>{{GAM670/DPS905 Index | 20111}}
= Physics System Overview =
By 'northWind'
[[Team_Guardian|Back to Team Guardian's Page]]
== Downloads ==
[[Team_Guardian#Downloads | Download Here]]
== Major Classes ==
</pre>
== Integrating Framework Breakdown Into Existing Projects == There are three ways to integrate the framework into your game: # As a physics simulator and collision detector combination# As a physics simulator only# As a collision detector only === Which Download Package Should I Choose? === Choose one of the barebones packages. They are labelled to coincide with whichever route you want to take when integrating the framework into your project. A reference implementation is also provided that shows an example of how the physics simulation and collision detection code is implemented. For the least amount of headache and work, I suggest getting either the physics sim/collision detection package or the physics sim only package; the collision detection only package inherently requires more work as the iRigidBody interface must be implemented to suit your project ([[Team_Guardian_Physics#Collision_Detector_Only |See here]]). Please skip to the section relevant to your interests :) === Basic Integration Steps === The barebones packages assume that your working copy is based on sample 28 but should integrate well with all samples 16 (possibly 22) and above. For all packages, the basic steps are the same and are the following: # Copy all files unique to the chosen package into your working copy. Add the files to your solution as desired; I recommend that new project filters be created to keep the package code separate from everything else.# Overwrite all of Chris' files that you did not modify during development that are also present in the chosen barebones package.# Merge together files that you've modified from Chris' reference implementation and that are also present in the chosen barebones package. [mailto:hkamal-al-deen@learn.senecac.on.ca Let me know if any problems arise during this step :)] '''Note that some files don't necessarily need to be copied in (such as Camera.cpp). Use your discretion when deciding on what parts of the framework to filter out and hopefully nothing breaks??''' For the combined package and the physics-only package, this is all that you need to do to get going. To actually get stuff simulating, take a look at some of [[Team_Guardian_Physics#How_to_Use |this code]]. For the collision only package, read on... === Collision Detector Only === After copying/merging in the requisite files from the collision detection package and adding all new files to your solution, the project should now be compiling cleanly. To get any use out of the collision detection, you will want to create a collision space, assign it to be the global collision space and implement the iRigidBody interface for your custom object classes. Let's take a look at this one step at a time:<ol><li>Create a global collision space for all of your collision geometry. For the time being, the only collision space available is the simple one so let's do that:<pre>#include "iCollisionSpace.h"#include "iSimpleCollisionSpace.h" iCollisionSpace* collisionSpace = CreateSimpleCollisionSpace();</pre></li><li> Assign this collision space to be the global collision space for all collision geometries that will be created from this point on. This should be done during initialization and prior to collision geometry creation.<br/><br/> From a design perspective, it should be possible for multiple collision spaces to coexist in the world but at the moment this is not implemented correctly so you will have to live with a single global collision space, unfortunately.</li><li>Implement the <code>iRigidBody</code> interface in some of your custom classes. A collision geometry requires a RigidBody instance to be passed in on creation (it can also be attached to a RigidBody at a later time); let's take a look at why this is so.</li></ol> ==== CollisionGeometry and RigidBody ==== A collision geometry uses a RigidBody for location, rotation and velocity inforomation. When implementing the iRigidBody interface, it is crucial that <code>getRBDynamics()</code> return an up to date representation of the object's state in the world. At minimum, the following properties should be consistent with real-time attributes of the object:<pre>Vector position : Current position of COMVector com : Center of Mass offset.PhysicsType physicsType : Type of physics applied to body, defaults to Falling (BUGGY, use PHYS_Falling and PHYS_Floating for now)Matrix orientation : Matrix representing rotation in XYZ</pre> A couple of notes:; PhysicsType physicsType : Always return PHYS_Falling or PHYS_Floating. The collision space will filter out collisions between PHYS_FixedInSpace objects to avoid unnecessary collision checks.; Matrix orientation : Ensure that the rotation matrix has not been contaminated with any scale information, otherwise the collision tests may not return correct results. Oh, this might also be a good time to note that scaling is '''not supported''' by the physics simulator or the collision detector :) Having said that, this should be enough to get your objects up and colliding. To detect all collisions at a given time in the world, call <code>populateContactList()</code> on the collision space. Retrieve the list of collisions by calling <code>getContactList()</code>; to find the number of contacts in the world, call <code>getNumContacts()</code>. For more/misc information, see [[Team_Guardian_Physics#RigidBody |RigidBody Reference]] and the [[Team_Guardian_Physics#CollisionSpace |CollisionSpace Reference]]. == Framework Reference ==
The framework consists of a physics simulator (PhysicsScene) and a collision space (SimpleCollisionSpace). They are designed to work relatively independently using a set a of joint interfaces.
iPhysicsScene* CreatePhysicsScene(iContext* c);
</pre>
; virtual bool add(iRigidBody* o) : Adds a RigidBody to the internal RigidBody list.
; virtual void setNewGlobalCollisionSpace(iCollisionSpace* cs) : Sets the default CollisionSpace for all CollisionGeometries to the one passed in.
; virtual void update(int now) : Moves the simulation forward. Accepts an integer representing current world time.
; virtual void remove(const iRigidBody* o) : Removes a RigidBody from the internal RigidBody list. The removed RigidBody will nolonger be simulated/updated by the PhysicsScene instance.
; virtual void Delete() const : Deletes this PhysicsScene instance and also deletes all attached RigidBodies.
'''Typical Usage'''
The standard controller functions should be called in the usual places in Engine.cpp (Delete(), release(), suspend(), reset(), restore()), please refer to Engine.cpp in the reference implementation for more details.
; virtual RBDynamics& getDynamics() : Returns a reference to the RBDynamics struct. The public properties of the struct can be directly edited in this way. The physics simulator will update these properties every frame.
; virtual void Delete() const : Deletes this RigidBody and its RBDynamics instance. Does not delete the associated object or any associated collision listeners.
==== PhysicsFrame ====
A PhysicsFrame is a convenience class that internally holds an instance of a RigidBody. This can be useful in that it is manipulated just like any other Frame and direct interaction with RBDynamics struct is not strictly required. Let's examine the interface:
<pre>
/* Physics Frame Interface - Model Branch
*
* iPhysicsFrame.h
* March 22 2011
* distributed under TPL - see ../Licenses.txt
* Hasan Kamal-Al-Deen
*/
#include "Frame.h"
//--------------------------- iPhysicsFrame -----------------------------------
//
// iPhysicsFrame is the Interface to the PhysicsFrame object.
//
class iRigidBody;
struct RBDynamics;
class iPhysicsFrame : public Frame {
public:
virtual iRigidBody* getRB() const = 0;
virtual RBDynamics* getDynamics() const = 0;
virtual iPhysicsFrame* clone() const = 0;
// termination functions
virtual void suspend() const = 0;
virtual void release() const = 0;
virtual void Delete() const = 0;
};
extern "C"
iPhysicsFrame* CreatePhysicsFrame();
</pre>
The standard suite of iFrame functions is implemented to work as you would expect. Let's look at the new convenience functions:
<pre>
virtual iRigidBody* getRB() const = 0;
virtual RBDynamics* getDynamics() const = 0;
</pre>
; virtual iRigidBody* getRB() const : Returns the RigidBody instance associated with this PhysicsFrame.
; virtual RBDynamics* getDynamics() const : Returns the RBDynamics instance contained within the associated RigidBody.
It should be noted that while PhysicsScene tracks all RigidBodies and destroys them upon engine shutdown, it does not do this for PhysicsFrame instances. Therefore, the implementer is responsible (at least for the time being!) for destrying PhysicsFrame instances. Please refer to the example implementation for an example on how to do this.
=== Collision ===
==== CollisionSpace ====
<pre>#include "iCollisionSpace.h"</pre>
A CollisionSpace is not a coordinator and does not need to be updated every frame. A collision space is responsible for holding a list of collision geometries (CollisionGeometry) and for generating a list of all collisions between them. There are two ways to add collision geometries to a collision space:
# By manually adding each CollisionGeometry to to the space by calling <code>virtual bool add(iCollisionGeometry* o)</code> on the CollisionSpace instance.
# By setting a particular CollisionSpace instance to be the default collision space for all collision geometries. This is done by calling <code>CollisionGeometry::setGlobalCollisionSpace(iCollisionSpace* cs)</code>
Let's look at the interface:
<pre>
class iCollisionSpace {
public:
// execution functions
virtual bool add(iCollisionGeometry* o) = 0;
virtual void remove(iCollisionGeometry* o) = 0;
virtual const std::list<iCollisionGeometry*>& getAttachedGeometry() = 0;
virtual void populateContactList(float delta) = 0;
virtual const CollisionContact* getContactList() const = 0;
virtual size_t getNumContacts() const = 0;
// termination functions
virtual void suspend() const = 0;
virtual void release() const = 0;
virtual void Delete() const = 0;
};
</pre>
Of these functions, three are of particular importance:
<pre>
virtual void populateContactList(float delta) = 0;
virtual const CollisionContact* getContactList() const = 0;
virtual size_t getNumContacts() const = 0;
</pre>
; virtual void populateContactList(float delta) : Collides all attached collision geometries with each other, clears then builds the internal contact list. This function requires a delta time amount to be passed in that represents the last time <code>populateContactList()</code> was called. Valid values for <code>delta</code> are inclusively between 0.0f and FLOAT_INFINITE.
; virtual size_t getNumContacts() const : Returns the number of CollisionContacts in the contact list array.
; virtual const CollisionContact* getContactList() : Returns a pointer to the first element in the internal CollisionContact array.
Currently, only a simple collision space is implemented. It performs N^2 collision checks when populateContactList is called where N is the number of collision geometries attached to the space.
In the very near future, an octree collision space will be implemented. This space will be updated when this happens :)
==== SimpleCollisionSpace ====
<pre>#include "iSimpleCollisionSpace.h"</pre>
Creating a simple collision space is as easy as cake. Let's look at the interface:
<pre>
/* Simple Collision Space Interface - Physics Scene Component - Model Branch
*
* iSimpleCollisionSpace.h
* November 17 2010
*/
//--------------------------- iSimpleCollisionSpace ---------------------------
//
// A simple collision space. Performance is N^2 rigid bodies.
//
class iCollisionSpace;
extern "C"
iCollisionSpace* CreateSimpleCollisionSpace(size_t samplesPerSecond=60);
</pre>
Surprise! There is no interface! iSimpleCollisionSpace.h simply holds the header for the creation function. To create a simple collision space, simply call:
<pre>iCollisionSpace* CreateSimpleCollisionSpace()</pre>
; size_t samplesPerSecond=60 : The number of collision samples to perform per second; used in contact determination. At the moment, this feature is simply disabled as the implementation is borked.... HOWEVER! If the implementation were not borked, then under most circumstances the samplesPerSecond parameter should not have to be changed.
==== CollisionContact ====
<pre>#include "iCollisionSpace.h"</pre>
A CollisionContact represents a single collision at a point in world space between two collision geometries. Let's look at the definition:
<pre>
struct CollisionContact{
Vector pos; // contact position
Vector normal; // normal vector
float depth; // penetration depth
iCollisionGeometry *g1, *g2; // colliding geoms
};
</pre>
; Vector pos : The world space location of the point of collision.
; Vector normal : A world space unit vector perpendicular to the collision surface. This always points at g2.
; float depth : The depth of penetration between the geometries.
; iCollisionGeometry* g1 : The first geometry involved in this collision.
; iCollisionGeometry* g2 : The second geometry involved in this collision.
With this information, the computer can be programmed to respond appropriately to any number of collisions :)
==== CollisionGeometry ====
<pre>#include "iCollisionGeometry.h"</pre>
A CollisionGeometry is a mathematical representation of a body's shape in 3D. Currently, there are 2 collision geometries implemented:
# iCSphere : A collision sphere. Possesses a single radius. <pre>#include "iCSphere.h"</pre>
# iCOBB : A body oriented bounding box. Possesses 3 radius values, one for each dimension. This shape rotates with the RigidBody. <pre>#include "iCOBB.h"</pre>
The collision primitives can be created and associated with a RigidBody as follows, respectively:
* <code>iCollisionGeometry* CreateCSphere(iRigidBody* rb=NULL, float radius=10.0f)</code>
* <code>iCollisionGeometry* CreateCOBB(iRigidBody* rb=NULL, const Vector& radius=Vector(10, 10, 10))</code>
== Listening For Collisions ==
; Vector hitLocation : The location in world space of the point of collision.
== Integrating Framework Into Existing Projects RBDynamics Reference == There are three ways to integrate the framework into your game: # As a physics simulator and collision detector combination# As a physics simulator only# As a collision detector only Please skip to the section relevant to your interests :) === Combined Physics Simulator/Collision Detector === This is the framework in its default state. Properties == RBDynamics Properties Reference ==
; Vector position : Current position of COM
; Vector velocity : Current velocity of COM
; Vector temporalTorque : Torque force that will be applied at the next tick and then reset to 0; Total angular acceleration is equal to: angularAcceleration + ((torque + temporalTorque)/inertiaMoment)
== RBDynamics = Functions Reference ===; Vector getWorldCOM() const : '''REMOVED IN NEXT UPDATE''' Returns the world position of the COM with respect to this body.
; Vector getVelocityAtWorldPoint(const Vector& p) const : Given a point in worldspace, returns its speed taking into account velocity and angular velocity.
; Void setInverseInertiaTensor(const Matrix& i) : Sets the inverse inertia tensor of this body. Automatically sets the inertia tensor as well by inversing the incoming matrix. DOES NOT NEED TO BE CALLED AFTER CALLING setInertiaTensor()
; Matrix& getInverseInertiaTensor() : Returns the inertia tensor or inverse inertia tensor contained by this object.
; Void ApplyImpulse(const Vector& impulse, const Vector& pointOfApplication) : Applies a given impulse instantaneously onto this object at a given world point of application. Can be used to shoot or prod objects.
==== Functions Coming In Next Update ====
; void attachTo(RBDynamics* p) : Attaches this RBD to a given RBD. It is not required to call this function after calling PhysicsFrame's AttachTo(PhysicsFrame*) if the RBD resides within the RB of the PhysicsFrame.
; RBDynamics* attachedTo() const : Returns the RBD this RBD is attached to or NULL.
; RBDynamics* attachmentRoot() const : Returns the root of the attachment chain of this RBD.
; float getMass() const : Returns the mass of the RBD at the root of the attachment chain.
; Vector getWorldPosition() const : Returns the world-space position of this body's COM taking into account parent position/orientation.
; Matrix getWorldOrientation() const : Returns the world-space orientation of this body taking into account parent orientation.
== Other Topics Reference ==
