Update doc

1 files changed, 14 insertions, 8 deletions

diff --git a/simloop/include/simloop.h b/simloop/include/simloop.h
index b08dcac..c5a0372 100644
--- a/simloop/include/simloop.h
+++ b/simloop/include/simloop.h
@@ -4,9 +4,16 @@
  * control flow. The client steps the loop and then checks whether the
  * simulation must be updated and/or the result rendered.
  *
- * If the simulation's update cannot keep up with the desired frame rate, then
- * the loop degrades to match the simulation's rate by requesting a single
- * update.
+ * The simulation is updated at a fixed time step given a desired frame rate.
+ * Rendering frame rate can likewise be capped or be unlimited. In any case, the
+ * loop guarantees that the same frame is not rendered twice.
+ *
+ * Generally, the simulation's update logic should be able to keep up with the
+ * requested frame rate; it is the application's responsibility to ensure this.
+ * Should the update logic not be able to keep up, then the loop requests a
+ * single update per iteration, effectively "degrading" to match the update
+ * logic frame rate, and giving the update logic a chance to catch up with
+ * subsequent loop iterations.
  *
  * Under a variable time delta, the loop could simply update the simulation
  * with a large delta that puts the simulation back into the current clock
@@ -14,14 +21,13 @@
  * choices instead:
  *
  *   a) Queue as many updates as necessary to bring the simulation back to the
- *      current clock time (time_diff / fixed_delta).
+ *      current clock time (time_difference / fixed_delta).
  *
  *   b) Queue a single update.
  *
- * The issue with (a) is that the number of requested updates diverges and
- * eventually the simulation appears to freeze. At every loop, the number of
- * queued updates increases with respect to the last iteration as the
- * simulation fails to keep up with the desired frame rate. Example:
+ * The issue with (a) is that, if the simulation is never able to catch up, then
+ * the number of requested updates at every loop iteration diverges and
+ * eventually the simulation appears to freeze. Example:
  *
  *   desired delta = 10ms (100 fps)
  *   actual  delta = 20ms ( 50 fps)