--- a/src/PhysicsObject.hh Mon Dec 08 22:28:51 2008 +0000
+++ b/src/PhysicsObject.hh Mon Dec 08 22:33:24 2008 +0000
@@ -15,58 +15,84 @@
// Type definitions
typedef Vector Force;
-
+
+/** Specifies possible object types. */
enum ObjectType { PLAYER, PROJECTILE, ROPE };
+/** Specifies possible facing directions for objects. */
enum FacingDirection {
FACING_LEFT,
FACING_RIGHT
};
/**
- * PhysicObject class.
- *
- * A basic PhysicsObject class.
+ * PhysicObject class. Represents an object in the physics simulation.
*/
class PhysicsObject {
public:
+ /** Reference to PhysicsWorld. */
PhysicsWorld &world;
protected:
+ /** Object position. */
Vector position;
+ /** Object position on previous physics tick. */
Vector previousPosition;
+ /** Object velocity */
Vector velocity;
+ /** Object mass. */
float mass;
- bool inAir; // Is the object "on the ground"
+ /** Tells if the object is "on the ground" */
+ bool inAir;
+ /** Object elasticity. */
float collision_elasticity;
// Attributes for players
- float aim; // Aim direction (half circle)
- FacingDirection facing; // Player facing
+ /** Aim angle in radians. */
+ float aim;
+ /** Player facing. */
+ FacingDirection facing;
+ /** Specifies if the player is alive (or dead). */
bool alive;
+ /** True if player object should be removed from the game. */
bool shouldDelete;
+ /** Type of the object */
ObjectType type;
+ /** Pivot object for this object. */
PhysicsObject *pivot;
+ /**
+ * Class constructor
+ *
+ * @param world Reference to PhysicsWorld
+ * @param mass Object mass
+ * @param position Object position
+ * @param velocity Object velocity
+ * @param type Object type
+ * @param collision_elasticity Object elasticity
+ * @param enabled Is the object currently part of the simulation
+ */
PhysicsObject (PhysicsWorld &world, float mass, Vector position, Vector velocity, ObjectType type,
float collision_elasticity, bool enabled = true);
virtual ~PhysicsObject (void);
/**
- * Add force to the force queue to be applied on next tick.
+ * Apply a force to the object. The force is applied to the object
+ * on the next physics tick.
*
* @param force Force vector
*/
void applyForce(Force force, TimeMS dt = PHYSICS_TICK_MS);
/**
- * Change player aim
+ * Change player aim. This function takes care that aim angle
+ * stays inside limits.
*
- * @param da Aim angle change
+ * @param da Aim angle change in radians
*/
void changeAim(float da);
@@ -79,12 +105,13 @@
/**
* Makes the player jump in the air.
+ *
* @param direction -1: jump left, 0: jump up, 1: jump right
*/
void jump (int direction);
/**
- * Handle ground-bounce
+ * Handle object bounce.
*
* @param normal Normal vector relative to which to bounce
*/
@@ -102,33 +129,40 @@
virtual void updatePhysics (Vector position, Vector velocity, bool inAir, FacingDirection facing, float aim);
/**
- * Put object to the objects list so that its movement will be calculated.
+ * Put the object in the physics simulation. When the object is in
+ * the physics simulation it's movements will be calculated.
*/
void enable (void);
/**
- * Remove object from the objects list but don't delete the object itself.
+ * Remove object from the objects physics simulation. When the
+ * object isn't in the physics simulation it won't be deleted but
+ * its movements will not be calculated.
*/
void disable (void);
private:
- // Shape of the object. Edge points of the shape polygon.
+ /** Objects shape. Edgepoints of the polygon */
std::vector<Vector> shape;
- // Force queue that is emptied on every tick
+ /** Object force queue. The queue is emptied on every physics
+ tick.*/
std::queue<std::pair<Force, TimeMS> > forceq;
/**
* Handle player movement and apply forces.
+ *
+ * @param dt Time intervall
*/
void updatePosition (TimeMS dt);
- // TODO: Should these be moved to PhysicsWorld?
/**
* Use RK4 to integrate the effects of force over a time interwall.
*
* @param force Force to integrate
* @param dt Time intervall
+ * @param posAfterTick Reference to object postition after integration.
+ * @param velAfterTick Reference to object velocity after integration.
*/
void integrate (Force force, TimeMS dt, Vector &posAfterTick, Vector &velAfterTick);
@@ -138,6 +172,7 @@
* @param force Force
* @param dt Time
* @param d Previous derivative
+ * @return Derivative
*/
Derivative evaluate (Force force, TimeMS dt, Derivative &d, const Vector &posAfterTick, const Vector &velAfterTick);
@@ -162,18 +197,23 @@
/**
* Define object behaviour on collisions.
*
- * XXX: make this pure-virtual
+ * @param collisionPoint Point of collision.
+ * @param other The other object we have collided with.
*/
virtual void onCollision (Vector collisionPoint, PhysicsObject *other = NULL);
/**
- * Return the type of the physics object (player, projectile...)
+ * Get object type.
+ *
+ * @return Object type
*/
ObjectType getType (void) const;
/**
* Checks if it is possible for the object to be in the given
* location.
+ *
+ * @param loc Location
*/
bool possibleLocation (Vector loc);
@@ -222,7 +262,7 @@
/**
* Set object shape.
*
- * @param shape Vector containing polygon poinst
+ * @param shape Vector containing polygon points
*/
void setShape(std::vector<Vector> shape);
@@ -241,7 +281,9 @@
float getAim() const;
/**
- * Returns facing+aim as a unit vector
+ * Get object direction.
+ *
+ * @return Unit vector to facing+aim
*/
Vector getDirection (void) const;
@@ -250,18 +292,24 @@
*/
void destroy (void);
- /*
- * Had the object been destroyed?
+ /**
+ * Check if the object is alive.
+ *
+ * @return Is the object alive?
*/
bool isAlive (void);
/**
- * Delete ourselves if we've been destroyed and return true, else return false
+ * Tells the state of the object.
+ *
+ * @return True if object has been destroyed.
*/
bool removeIfDestroyed (void);
/**
- * Sets this object's pivot to the given value, which will then exert a force on this object
+ * Set object pivot.
+ *
+ * @param pivot Pivot object
*/
void setPivot (PhysicsObject *pivot);
@@ -269,20 +317,27 @@
* Checks if object collides with other objects
*
* @param obj Other PhysicsObject
+ * @return Did we collide?
*/
bool collides (const PhysicsObject &obj);
/**
* Compute the force that this object (as a pivot) exerts on the given object
+ *
+ * @param bob Othe object
+ * @return Force
*/
virtual float getPivotForce (PhysicsObject *bob);
/**
* Update object in physics simulation.
+ *
+ * @param tick_length Length of the physics tick
*/
virtual void tick (TimeMS tick_length);
};
+/** Helper struct for the integration */
struct Derivative {
Vector dx; // Velocity
Vector dv; // Acceleration