/** \mainpage Game example code.
 
  \section overview Overview
 
  The example application shows you how to:
   <ul>
   <li>Start threads, see class CGameFramework </li>
   <li>Talk direct to the window server, see class CGameFramework </li>
   <li>Access screen memory directly, see class RScreenUtils </li>
   <li>Integrate arm assembler into c++, see class TSprite32x24 and files sprite.s and Game.mmp
   <li>Integrate active objects with other requests, see class CGameFramework </li>
   </ul>

  Note this application will not build for the emulator as it uses
  arm assembler to implement some of the game routines.
 
  The application breaks down into two sections.

  \section uicode The ui code

  The ui code implements a simple non-file based application. It has
  a simple menu, one dialog and a simple main view. This is implemented
  in classes:
        <ul>
        <li> CGameAppUi, the ui, this handles menu selections etc.</li>
        <li> CGameAppView, the main view, this draws the main window.</li>
        <li> CGameDocument, the game document, this owns the state of the app</li>
        <li> CGameState, this stores the current state and owns the highscores.</li>
        <li> CGameApplication, main class that creates the document.</li>
        <li> CScoreDialog, a dialog class that handles entering names for high scores.</li>
        <li> CHighScores, container for the high score table.</li>
        </ul>

  The CGameAppUi owns a CGameFramework class that handles running the real
  game.

  \section gamecode The game code

  This breaks down into two main areas:
        <ul>
        <li>The CGameFramework class which handles loading a level and getting key events.</li>
        <li>The CGame and the objects it owns. This is started in its own thread and just loops running the game.</li>
        </ul>

   \subsection framework The framework

   The CGameFramework class provides an api for the UI to load and run
   game levels. When the CGameFramework class is asked to
   start a level it creates
   a window server session to allow it to create a window and get events.
   It then uses the session to create an RBlankWindow in front of the
   rest of the ui.

   This window is never drawn to as the game itself does
   all its drawing driect to screen memory, however it is useful as it
   gets key events and informs us when it loses the focus. This allows
   the framework to inform the game thread when a key is pressed, it
   does this via the TGameData::iKeys bit mask, and also to suspend the
   game thread when the user pages away to another application which
   stops the direct screen access writing over other applications.

   The framework also watches for signals indicating that the thread
   has terminated which means that the player has either completed the
   level, died or quit.

   \subsection cgame The CGame class

   The CGame class and its owned objects can be implemented as a simple
   while loop (see CGame::Play()) that runs
   while the TGameData::iKeys bit mask doesn't have the quit key bit
   set. It doesn't have to deal with window server events it can just
   test the bit mask for the keys it is interested in. In fact there
   are only three system calls made from the game thread, these are
   UserSvr::ScreenInfo() to find out the base address of the screen (see
   RScreenUtils::Open()), User::TickCount() for timing (see CGame::Play())
   and finaly User::Panic() to catch programming errors (see TGamePanics::Panic()).
  

  \section other Other Pages

  There are a few notes on integrating arm assembler and c++, see page \ref asm_note "assembler notes".

  There is a description of the format of the level files used by the game \ref file_format "here".


 */