From 8ed8963c638b19ff814dc7bd0d0a68c01e38d5b5 Mon Sep 17 00:00:00 2001
From: hikerstk <hikerstk@178a84e3-b1eb-0310-8ba1-8eac791a3b58>
Date: Thu, 15 Aug 2013 06:20:31 +0000
Subject: [PATCH] Documented the main loop of STK.

git-svn-id: svn+ssh://svn.code.sf.net/p/supertuxkart/code/main/branches/rewind@13483 178a84e3-b1eb-0310-8ba1-8eac791a3b58
---
 src/main_loop.cpp | 66 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/src/main_loop.cpp b/src/main_loop.cpp
index 8524dbed0..754c6eaaf 100644
--- a/src/main_loop.cpp
+++ b/src/main_loop.cpp
@@ -114,6 +114,72 @@ void MainLoop::updateRace(float dt)
 
 //-----------------------------------------------------------------------------
 /** Run the actual main loop.
+ *  The sequnce in which various parts of STK are updated is:
+ *  - Determine next time step size (`getLimitedDt`). This takes maximum fps
+ *    into account (i.e. sleep if the fps would be too high), and will actually
+ *    slow down the in-game clock if the fps are too low (if more than 3/60 of
+ *    a second have passed, more than 3 physics time steps would be needed, 
+ *    and physics do at most 3 time steps).
+ *  - if a race is taking place (i.e. not only a menu being shown), call
+ *    `updateRace()`, which is a thin wrapper around a call to
+ *    `World::updateWorld()`:
+ *    - Update history manager (which will either set the kart position and/or
+ *      controls when replaying, or store the current info for a replay).
+ *      This is mostly for debugging only (though available even in release
+ *      mode).
+ *    - Updates Replays - either storing data when not replaying, or
+ *      updating kart positions/control when replaying).
+ *    - Calls `WorldStatus::update()`, which updates the race state (e.g.
+ *      go from 'ready' to 'set' etc), and clock.
+ *    - Updates the physics (`Physics::update()`). This will simulate all
+ *      physical objects for the specified time with bullet.
+ *    - Updates all karts (`Kart::update()`). Obviously the update function
+ *      does a lot more than what is described here, this is only supposed to
+ *      be a _very_ high level overview:
+ *      - Updates its rewinder (to store potentially changed controls
+ *        as events) in `KartRewinder::update()`.
+ *      - Calls `Moveable::update()`, which takes the new position from
+ *        the physics and saves it (and computes dependent values, like
+ *        heading, local velocity).
+ *      - Updates its controller. This is either:
+ *        - an AI using `SkiddingController::update()` (which then will
+ *          compute the new controls), or 
+ *        - a player controller using `PlayerController::update()`, which will
+ *          handle smooth steering (in case of digital input devices steering
+ *          is adjusted a bit over time to avoid an instant change from all
+ *          left to all right). Input events will be handled when updating
+ *          the irrlicht driver later at the end of the main loop.
+ *      - Updates kart animation (like rescue, ...) if one is shown atm.
+ *      - Update attachments.
+ *      - update physics, i.e. taking the current steering and updating
+ *        the bullet raycast vehicle with that data. The settings are actually
+ *        only used in the next frame when the physics are updated.
+ *    - Updates all cameras via `Camera::update()`. The camera position and
+ *      rotation is adjusted according to the position etc of the kart (and
+ *      special circumstances like rescue, falling).
+ *    - Updates all projectiles using the projectile manager. Some of the
+ *      projectiles are mostly handled by the physics (e.g. a cake will mainly
+ *      check if it's out of bounds), others (like basket ball) do all 
+ *      their aiming and movement here.
+ *    - Updates the rewind manager to store rewind states.
+ *  - Updates the music manager.
+ *  - Updates the input manager (which only updates internal time, actual
+ *    input handling follows late)
+ *  - Updates the wiimote manager. This will read the data of all wiimotes
+ *    and feed the corresponding events to the irrlicht event system.
+ *  - Updates the STK internal gui engine. This updates all widgets, and
+ *    e.g. takes care of the rotation of the karts in the KartSelection
+ *    screen using the ModelViewWidget.
+ *  - Updates STK's irrlicht driver `IrrDriver::update()`:
+ *    - Calls Irrlicht's `beginScene()` .
+ *    - Renders the scene (several times with different viewport if
+ *      split screen is being used)
+ *    - Calls `GUIEngine::render()`, which renders all widgets with the
+ *      help of Irrlicht's GUIEnvironment (`drawAll()`). This will also
+ *      handle all events, i.e. all input is now handled (e.g. steering,
+ *      firing etc are all set in the corresponding karts depending on
+ *      user input).
+ *    - Calls Irrlicht's `endScene()`
  */
 void MainLoop::run()
 {