Commits

Michael Ludwig  committed 6557fdb

Document the tasks in the physics module.

  • Participants
  • Parent commits c0b3d9b

Comments (0)

Files changed (7)

File ferox-physics/src/main/java/com/ferox/physics/task/CollisionTask.java

 import java.util.Collections;
 import java.util.Set;
 
+/**
+ * CollisionTask is an abstract task used to perform the collision detection necessary for a physics
+ * simulation. It manages a {@link ContactManifoldPool} to accumulate collisions and reports the contact and
+ * friction constraints with a {@link ConstraintResult}.
+ * <p/>
+ * Subclasses must implement the broadphase portion of the collision detection algorithm. They can then invoke
+ * {@link #notifyPotentialContact(com.ferox.physics.collision.CollisionBody,
+ * com.ferox.physics.collision.CollisionBody)} to perform the narrowphase and update the collision manifold as
+ * necessary.
+ *
+ * @author Michael Ludwig
+ */
 public abstract class CollisionTask implements Task {
     private final CollisionAlgorithmProvider algorithms;
 
 
     protected double dt;
 
+    /**
+     * Create a new CollisionTask that uses the given algorithm provider.
+     *
+     * @param algorithms The algorithm provider to use
+     *
+     * @throws NullPointerException if algorithms is null
+     */
     public CollisionTask(CollisionAlgorithmProvider algorithms) {
         if (algorithms == null) {
             throw new NullPointerException("Algorithm provider cannot be null");
         this.dt = dt.getTimeDelta();
     }
 
+    /**
+     * Subclasses must call this at the end in order to enable warmstart impulses. This will never return a
+     * null Task.
+     *
+     * @param system The entity system
+     * @param job    The current job
+     *
+     * @return A task that updates the manifold with warmstart impulses from the just completed frame
+     */
     @Override
     public Task process(EntitySystem system, Job job) {
         return new WarmstartTask();
         frictionGroup.clear();
     }
 
+    /**
+     * Compute and report the contact and friction constraints as two different {@link ConstraintResult}
+     * instances. This should be called at the end of the task before the value is returned.
+     *
+     * @param job The current job
+     */
     protected void reportConstraints(Job job) {
         manifolds.generateConstraints(dt, contactGroup, frictionGroup);
         job.report(new ConstraintResult(contactGroup));
         job.report(new ConstraintResult(frictionGroup));
     }
 
+    /**
+     * Compute a narrowphase collision check between the two bodies and update the collision manifold if
+     * necessary. The order of the arguments is not important. The two components should not be flyweight
+     * instances.
+     *
+     * @param bodyA The first body
+     * @param bodyB The second body
+     */
     @SuppressWarnings({ "rawtypes", "unchecked" })
     protected void notifyPotentialContact(CollisionBody bodyA, CollisionBody bodyB) {
         // collisions must have at least one rigid body to act on

File ferox-physics/src/main/java/com/ferox/physics/task/ConstraintResult.java

 import com.ferox.physics.dynamics.LinearConstraintPool;
 import com.lhkbob.entreri.task.Result;
 
+/**
+ * ConstraintResult is a result that can be used to deliver {@link LinearConstraintPool constraints} to a task
+ * that can then solve them when appropriate. Currently this is the aptly named {@link
+ * ConstraintSolvingTask}.
+ *
+ * @author Michael Ludwig
+ */
 public class ConstraintResult extends Result {
     private final LinearConstraintPool group;
 
+    /**
+     * Create a new result that wraps the given constraint pool
+     *
+     * @param group The pool to use
+     *
+     * @throws NullPointerException if group is null
+     */
     public ConstraintResult(LinearConstraintPool group) {
         if (group == null) {
             throw new NullPointerException("LinearConstraintPool cannot be null");
         this.group = group;
     }
 
+    /**
+     * @return The constraint pool in the result
+     */
     public LinearConstraintPool getConstraints() {
         return group;
     }

File ferox-physics/src/main/java/com/ferox/physics/task/ConstraintSolvingTask.java

 import java.util.List;
 import java.util.Set;
 
+/**
+ * ConstraintSolvingTask is a task implementation that collects all reported {@link ConstraintResult
+ * ConstraintResults} and computes a solution using a {@link LinearConstraintSolver}. It also manages the
+ * decorated properties expected by the solver to accumulate delta impulses and properly adds those impulses
+ * to the rigid bodies' velocities.
+ *
+ * @author Michael Ludwig
+ */
 public class ConstraintSolvingTask implements Task, ParallelAware {
     private final LinearConstraintSolver solver;
 

File ferox-physics/src/main/java/com/ferox/physics/task/IntegrationTask.java

 import java.util.Set;
 
 /**
+ * IntegerationTask is a task to run at the start of the physics job that integrates the linear and angular
+ * velocities into the new position and orientation. It then updates all CollisionBodies' world bounds, and
+ * all RigidBodies' inertia tensor matrices. After that it applies a configured gravity acceleration. The
+ * world bounds of the simulation are reported using a {@link BoundsResult} instance.
  *
+ * @author Michael Ludwig
  */
 public class IntegrationTask implements Task, ParallelAware {
     private static final Set<Class<? extends Component>> COMPONENTS;
     private final Vector3 force = new Vector3();
     private final Matrix3 rotation = new Matrix3();
 
+    /**
+     * Create a new IntegrationTask that uses the default gravity vector along the y-axis with acceleration
+     * equal to Earth's. An explicit Euler integrator is used.
+     */
     public IntegrationTask() {
         this(new Vector3(0, -9.8, 0));
     }
 
+    /**
+     * Create a new IntegrationTask that uses the given default gravity acceleration vector and an explicit
+     * Euler integrator.
+     *
+     * @param gravity The default gravity (it will be cloned so changes to it do not affect the task)
+     *
+     * @throws NullPointerException if gravity is null
+     */
     public IntegrationTask(@Const Vector3 gravity) {
         this(gravity, new ExplicitEulerIntegrator());
     }
 
+    /**
+     * Create a new IntegrationTask that uses the given default gravity and integrator.
+     *
+     * @param gravity    The default gravity (it will be cloned so changes to it do not affect the task)
+     * @param integrator The integrator to use
+     *
+     * @throws NullPointerException if gravity or integrator are null
+     */
     public IntegrationTask(@Const Vector3 gravity, Integrator integrator) {
         if (integrator == null) {
             throw new NullPointerException("Integrator cannot be null");

File ferox-physics/src/main/java/com/ferox/physics/task/SingleAxisSAPCollisionTask.java

 import com.ferox.math.Functions;
 import com.ferox.physics.collision.CollisionAlgorithmProvider;
 import com.ferox.physics.collision.CollisionBody;
+import com.ferox.physics.collision.DefaultCollisionAlgorithmProvider;
 import com.ferox.physics.dynamics.RigidBody;
 import com.ferox.util.Bag;
 import com.ferox.util.profile.Profiler;
 import java.util.HashSet;
 import java.util.Set;
 
+/**
+ * SingleAxisSAPCollisionTask is a collision task that implements the broadphase using the single axis sweep
+ * and prune technique. The current implementation uses the x axis as the sweeping axis.
+ *
+ * @author Michael Ludwig
+ */
 public class SingleAxisSAPCollisionTask extends CollisionTask implements ParallelAware {
     private static final Set<Class<? extends Component>> COMPONENTS;
 
     private CollisionBody body;
     private ComponentIterator iterator;
 
+    /**
+     * Create a new SingleAxisSAPCollisionTask that uses a default collision algorithm provider.
+     */
+    public SingleAxisSAPCollisionTask() {
+        this(new DefaultCollisionAlgorithmProvider());
+    }
+
+    /**
+     * Create a new SingleAxisSAPCollisionTask that uses the given algorithm provider.
+     *
+     * @param algorithms The algorithm provider
+     *
+     * @throws NullPointerException if algorithms is null
+     */
     public SingleAxisSAPCollisionTask(CollisionAlgorithmProvider algorithms) {
         super(algorithms);
         bodies = new Bag<>();

File ferox-physics/src/main/java/com/ferox/physics/task/SpatialIndexCollisionTask.java

 
 import com.ferox.math.AxisAlignedBox;
 import com.ferox.math.bounds.IntersectionCallback;
+import com.ferox.math.bounds.QuadTree;
 import com.ferox.math.bounds.SpatialIndex;
 import com.ferox.math.entreri.BoundsResult;
 import com.ferox.physics.collision.CollisionAlgorithmProvider;
 import com.ferox.physics.collision.CollisionBody;
+import com.ferox.physics.collision.DefaultCollisionAlgorithmProvider;
 import com.ferox.physics.dynamics.RigidBody;
 import com.ferox.util.profile.Profiler;
 import com.lhkbob.entreri.Component;
 import java.util.HashSet;
 import java.util.Set;
 
+/**
+ * SpatialIndexCollisionTask is a collision task that implements the broadphase by relying on the {@link
+ * SpatialIndex#query(com.ferox.math.bounds.IntersectionCallback)} method. Thus, the performance of this
+ * broadphase is dependent on the type of spatial index provided.
+ *
+ * @author Michael Ludwig
+ */
 public class SpatialIndexCollisionTask extends CollisionTask implements ParallelAware {
     private static final Set<Class<? extends Component>> COMPONENTS;
 
     private CollisionBody body;
     private ComponentIterator iterator;
 
+    /**
+     * Create a new SpatialIndexCollisionTask that uses a default collision algorithm provider and a quadtree
+     * with 3 levels.
+     */
+    public SpatialIndexCollisionTask() {
+        this(new QuadTree<Entity>(new AxisAlignedBox(), 3), new DefaultCollisionAlgorithmProvider());
+    }
+
+    /**
+     * Create a new SpatialIndexCollisionTask that uses the given algorithm provider and spatial index
+     *
+     * @param index      The spatial index that is used
+     * @param algorithms The algorithm provider
+     *
+     * @throws NullPointerException if index or algorithms are null
+     */
     public SpatialIndexCollisionTask(SpatialIndex<Entity> index, CollisionAlgorithmProvider algorithms) {
         super(algorithms);
         if (index == null) {

File ferox-physics/src/main/java/com/ferox/physics/task/TemporalSAPCollisionTask.java

 import com.ferox.physics.collision.CollisionAlgorithmProvider;
 import com.ferox.physics.collision.CollisionBody;
 import com.ferox.physics.collision.CollisionPair;
+import com.ferox.physics.collision.DefaultCollisionAlgorithmProvider;
 import com.ferox.util.profile.Profiler;
 import com.lhkbob.entreri.ComponentIterator;
 import com.lhkbob.entreri.EntitySystem;
 import java.util.HashSet;
 import java.util.Set;
 
+/**
+ * TemporalSAPCollisionTask is a collision task that implements the broadphase using a temporal, 3-axis sweep
+ * and prune technique. It maintains edge lists for the X, Y, and Z axis across frames of the simulation and
+ * updates them as necessary. Collisions are reported as the sortedness of the lists are ensured.
+ *
+ * @author Michael Ludwig
+ */
 public class TemporalSAPCollisionTask extends CollisionTask {
     private final EdgeStore[] edges;
     private final Set<CollisionPair> overlappingPairCache;
     private CollisionBody body;
     private ComponentIterator bodyIterator; // iterates bodyA
 
+    /**
+     * Create a new TemporalSAPCollisionTask that uses a default collision algorithm provider.
+     */
+    public TemporalSAPCollisionTask() {
+        this(new DefaultCollisionAlgorithmProvider());
+    }
+
+    /**
+     * Create a new TemporalSAPCollisionTask that uses the given algorithm provider.
+     *
+     * @param algorithms The algorithm provider
+     *
+     * @throws NullPointerException if algorithms is null
+     */
     public TemporalSAPCollisionTask(CollisionAlgorithmProvider algorithms) {
         super(algorithms);