/** \file documentation.h \mainpage Main Page 
 * 
 * This is the documentation of Engine -- a game engine without a name.
 *
 * \section General Information
 *
 * To get an overview over the most important functions and classes have a
 * look at Engine. For the structure of the Engine look at Engine::Engine. In
 * \ref usecases you find documentation on how things are supposed to work and
 * what the ideas behind certain designs is.
 *
 * \section Physics
 *
 * So far we only use a very simple physics system which is mostly defined by
 * the Engine::Physics class. It uses the coll2d collision library. Collision
 * response so far only tries to prevent interpenetration.
 *
 * \section Networking
 *
 * For easier networking it is assumed that everything runs over a network.
 * The game itself is rather a smart client to a simple synchronization
 * protocol. What is being synchronized is the game state and the client
 * simply displays the current state it knows. The client is "smart" as it
 * tries to guess what the next state will be.
 *
 * For networking we want to use Enet http://enet.bespin.org/.
 *
 * Notes for networking: At
 * http://www.gamedev.net/community/forums/topic.asp?topic_id=550962 is an
 * interesting thread about modeling the updates. Especially the answer of
 * Antheus at http://www.gamedev.net/community/forums/viewreply.asp?ID=3546077
 * describes two fundamental models:
 *
 * Level Triggering (GoF Observer Pattern): Entity A sends its changes to the
 * Observer pattern and all objects that are interested in the state of Entity
 * A get notfied by the observer.
 *
 * Edge Triggering: For each Entity A the Observer B is interested, it stores
 * a flag for a value it is interested in (e.g. one for position, one for
 * velocity, etc.). When Entity A modifies one of the values it notifies the
 * observer that its current state has changed and the Observer sets the flag
 * to "dirty". Anyone interested in events polls at the Observer and decides
 * what to do with it. When the value is queried, the Observer reads the value
 * from the Entity and clears the flag.
 *
 * For networking a combination can be used: During the simulation loop only
 * Edge Triggering is performed and at the end of it, all dirty States get
 * sent over the network.
 *
 * When notifying events such as "Add new Entity X" the user tomv describes at
 * http://www.gamedev.net/community/forums/viewreply.asp?ID=3545586 a method
 * to circumvent these messages. Instead, the server simply sends out updates
 * about the Entities around a player where close Entities are updated more
 * frequently than ones that are further away. It simply sends "Entity X
 * changed by D". If a client does not know what the Entity X is, it queries
 * the type and current state of the Entity X and therefore reconstructs the
 * surroundings step-by-step. It is also robust against dropped messages of
 * the form "Add new Entity X".
 *
 * At tomvas model there are some problems: How are events "Delete Entity X"
 * handled? How to handle malicious clients that request the state of all
 * Entities? (Solution for the last question: Request Queues).
 *
 * Kylotan cals tomvas model as a unreliable system for generic state
 * [synchronization?] (http://www.gamedev.net/community/forums/viewreply.asp?ID=3548662).
 * Additionally he mentions that it can increase occurences of short term
 * unsynchronous states and reccomends using some reliable message passing.
 *
 * \section ToDos
 *
 * This is a loose list of items that are to be implemented. For a list of all
 * todos within the code have a look at the \ref todo.
 *
 * \todo [high] Create a simple racing or asteroids game
 * \todo [high] fix collisions that go over boundaries
 * \todo [med] disallow or fix resize of the game window
 *
 * These are the (for now) postponed todos:
 *
 * \todo [med] Use shared_ptr instead of raw pointers for the Entities
 * \todo [med] Clear all references of EntityVisualState and EntityGameState
 * \todo [med] Clarify functionalities of CreateEntity, KillEntity, RegisterEntity, UnregisterEntity (which frees memory, which does only change the state of the Model?)
 * \todo [med] Add basic networking
 * \todo [med] Add serialization
 * \todo [med] Add cal3d support
 * \todo [med] Smooth Physics at convex collisions (somehow there is jitter)
 * \todo [med] Create better collsion response
 * \todo [med] In rare cases two Actors can penetrate each other (probably at slow velocities)
 * \todo [low] Add a timer object to keep track of what is sucking performance.
 * \todo [low] Add a inspector widget that shows information about a selected Entity
 * \todo [low] Use a std::map<string, string> as initialization parameters for
 * Engine::Module::Init()
 *
 * Done:
 * \todo [med] (30-01-2011) add Engine::GUI::CheckKeyPressed that checks for completed key presses
 * \todo [med] (30-01-2011) fix LineEdit input which generates blanks when entering backspace for an empty edit
 * \todo [high] (30-01-2011) fix random crashes for certain characters (has to do with boundary box computation in OGLFT) fix: disabled debug assertion for proper boundary box merging.
 * \todo [high] (28-11-2010) Enable saving of music and effects volume
 * \todo [high] (28-11-2010) Allow transitions when player dies
 * \todo [high] (11-09-2010) Since introduction of the IMGUI pressing 'space' in the menu crashes the game
 * - [high] In Physics remove dependancy on the Model to pass on collision
 *   events
 * - [high] Fix Physics bug when two actors collide actively (i.e. velocity
 *   towards each other)
 * - [med]  Better Game Input so that each Entity has its own ControllerState
 *   that can be modified
 * - [med] (31-01-2009) Add support for loading levels (and saving!)
 */