Add some comments

game.h

@@ -147,8 +147,6 @@ uint8_t LCR_gameGetNextAudioSample(void);
 
 //------------------------------------------------------------------------------
 
-#include "settings.h"
-
 #define LCR_LOG0(s) ;
 #define LCR_LOG1(s) ;
 #define LCR_LOG2(s) ;
@@ -180,6 +178,30 @@ uint8_t LCR_gameGetNextAudioSample(void);
 #define LCR_GAME_STATE_LOADING_MAP  0x04
 #define LCR_GAME_STATE_END          0xff
 
+// forward decls of pixel drawing functions for the renderer
+
+/**
+  Internal pixel drawing function that draws pixel at specified screen coords
+  without checking for safety (it's faster but can only be done if we know for
+  sure we're not drawing outside the screen).
+*/
+void LCR_drawPixelXYUnsafe(unsigned int x, unsigned int y, uint16_t color);
+
+/**
+  Internal pixel drawing function that checks for out-of-screen coordinates. Use
+  this if the pixel can potentially lie of screen (however if you know it won't,
+  use the normal unsafe function in sake of performance).
+*/
+static inline void LCR_drawPixelXYSafe(unsigned int x, unsigned int y,
+  uint_fast16_t color);
+
+#include "constants.h"
+#include "racing.h"
+#include "settings.h"
+#include "audio.h"
+#include "assets.h"
+#include "renderer.h"
+
 struct
 {
   uint8_t state;
@@ -225,22 +247,6 @@ uint8_t LCR_gameMusicOn(void)
 #endif
 }
 
-void LCR_drawPixelXYUnsafe(unsigned int x, unsigned int y,
-  uint16_t color);
-
-/**
-  Internal pixel drawing function that checks for out-of-screen coordinates. Use
-  this if the pixel can potentially lie of screen (however if you know it won't,
-  use the normal unsafe function in sake of performance).
-*/
-static inline void LCR_drawPixelXYSafe(unsigned int x, unsigned int y,
-  uint_fast16_t color);
-
-#include "racing.h"
-#include "assets.h"
-#include "renderer.h"
-#include "audio.h"
-
 void LCR_drawPixelXYUnsafe(unsigned int x, unsigned int y,
   uint16_t color)
 {
@@ -287,6 +293,9 @@ void LCR_gameResetRun(void)
   LCR_game.runTimeMS = 0;
 }
 
+/**
+  Rewinds the global resource reading head to the beginning.
+*/
 void LCR_gameRewindResourceFile(void)
 {
   LCR_appendResourceStr("");
@@ -294,10 +303,10 @@ void LCR_gameRewindResourceFile(void)
 }
 
 /**
-  Reads the next resource file character while merging the internal resource
+  Reads the next global resource file character (merged internal resource file
-  file with the optional user file. First the internal file will be read,
+  with the optional user file). First the internal file will be read,
-  immediately followed by the user file, then zero char will return and
+  immediately followed by the user file, then zero char will be returned and
-  reading will start over.
+  then reading starts over.
 */
 char LCR_gameGetNextResourceFileChar(void)
 {
@@ -337,7 +346,7 @@ char LCR_gameGetNextResourceFileChar(void)
 
 /**
   Similar to LCR_gameGetNextResourceFileChar, but returns 0 instead of the
-  resource string separator character. This function is means to be used by
+  resource string separator character. This function is meant to be used by
   functions that load something from a string while expecting a zero terminated
   string.
 */
@@ -453,8 +462,7 @@ void LCR_gameInit(void)
 
 /**
   Loads up to LCR_RESOURCE_ITEM_CHUNK items of given type, starting at given
-  index (among items of the same type). This will also load the menu item
+  index (among items of the same type). This will also load the menu item names.
-  names.
 */
 void LCR_gameLoadResourceFileChunk(unsigned int startIndex, char magicNumber)
 {
@@ -499,8 +507,7 @@ void LCR_gameLoadResourceFileChunk(unsigned int startIndex, char magicNumber)
       }
       else if (i == 1 && state != 255)
       {
-        if (
+        if (c == LCR_RESOURCE_FILE_SEPARATOR ||
-          c == LCR_RESOURCE_FILE_SEPARATOR ||
           c == LCR_RESOURCE_FILE_SEPARATOR2 ||
           state >= 1 + LCR_MENU_STRING_SIZE - 1)
         {
@@ -622,6 +629,10 @@ void LCR_gameDraw3DView(void)
   }
 }
 
+/**
+  Helper subroutine, handles user input during main loop frame, EXCEPT for the
+  driving input (that is handled in the loop itself).
+*/
 void LCR_gameHandleInput(void)
 {
   int tabSwitchedTo = -1;
@@ -812,11 +823,10 @@ void LCR_gameHandleInput(void)
 uint8_t LCR_gameStep(uint32_t time)
 {
   uint32_t sleep = 0;
-  int paused =
+  int paused = LCR_game.state == LCR_GAME_STATE_MENU ||
-    LCR_game.state == LCR_GAME_STATE_MENU ||
     LCR_game.state == LCR_GAME_STATE_RUN_STARTING;
 
-  LCR_LOG2("game step start");
+  LCR_LOG2("game step (start)");
 
   LCR_game.time = time;
 
@@ -876,6 +886,7 @@ uint8_t LCR_gameStep(uint32_t time)
     }
 
     int engineIntensity = LCR_carSpeedKMH() * 2;
+
     LCR_audioSetEngineIntensity(paused ? 0 :
       (engineIntensity < 256 ? engineIntensity : 255));
 
@@ -890,7 +901,7 @@ uint8_t LCR_gameStep(uint32_t time)
   // handle rendering:
   if (time >= LCR_game.nextRenderFrameTime)
   {
-    LCR_LOG2("gonna render next frame");
+    LCR_LOG2("rendering next frame");
 
     while (time >= LCR_game.nextRenderFrameTime)
       LCR_game.nextRenderFrameTime += 1000 / LCR_SETTING_FPS;
@@ -935,7 +946,7 @@ uint8_t LCR_gameStep(uint32_t time)
   }
 
   LCR_game.frame++;
-  LCR_LOG2("game step end");
+  LCR_LOG2("game step (end)");
 
   return LCR_game.state != LCR_GAME_STATE_END;
 }

racing.h

@@ -730,7 +730,7 @@ void _LCR_drawPhysicsDebugPixel(uint16_t x, uint16_t y, uint8_t color)
 
     for (int j = -1; j <= 2; ++j)
       for (int i = -1; i <= 2; ++i)
-        LCR_drawPixelXYUnsafe(x + i,y + j,c);
+        LCR_drawPixelXYUnsafe(x + i,y + j,c); // TODO: should be separated, make this independent of game module
   }
 }
 
@@ -1209,6 +1209,9 @@ uint32_t LCR_racingStep(unsigned int input)
   return result;
 }
 
+/**
+  Draws a simple 3D debug overlap of the physics world.
+*/
 void LCR_physicsDebugDraw(LCR_GameUnit camPos[3], LCR_GameUnit camRot[2],
   LCR_GameUnit camFov)
 {

renderer.h

@@ -1,5 +1,15 @@
 /**
-  3D renderer: implements 3D rendering.
+  Renderer: implements 3D and 2D rendering.
+
+  Some comments:
+
+  - The map 3D model is divided into 4x4x4 chunks, i.e. 64 in total, out of
+    which only 8 are loaded at any time, depending on where the camera is and
+    where it is looking. This is to save resources, we don't draw the far away
+    chunks or those behind the camera.
+  - Extremely simple LOD of far away chunks is implemented: we keep an 8x8x8
+    bit map of where there is empty space and where there is "something", then
+    for far away areas with "something" we just draw some 2D rectangles.
 */
 
 #ifndef _LCR_RENDERER_H
@@ -49,10 +59,10 @@
 
 struct
 {
-  S3L_Scene scene;
+  S3L_Scene scene;          ///< Whole 3D scene.
-  S3L_Model3D mapModel; ///< whole map model
+  S3L_Model3D mapModel;     ///< Whole map model.
-  S3L_Model3D *carModel;
+  S3L_Model3D *carModel;    ///< Shortcut pointer to the car model in scene.
-  S3L_Model3D *ghostModel;
+  S3L_Model3D *ghostModel;  ///< Shortcut pointer to the ghost model in scene.
 
   /**
     The scene model array.
@@ -199,6 +209,11 @@ void LCR_rendererDrawText(const char *text, int x, int y, uint16_t color,
   }
 }
 
+/**
+  Used as a fragment shader by small3dlib. This function will be called for
+  every rasterized 3D pixel, we use it write actual pixels to the screen with
+  shading, texturing etc.
+*/
 void _LCR_pixelFunc3D(S3L_PixelInfo *pixel)
 {
 #if LCR_SETTING_POTATO_GRAPHICS
@@ -726,6 +741,11 @@ void _LCR_cullHiddenMapTris(void)
   }
 }
 
+/**
+  Rearranges map triangles so that they're grouped by chunks. Order of triangles
+  doesn't matter much in rendering, so we exploit this to use order for
+  chunking.
+*/
 void _LCR_makeMapChunks(void)
 {
   LCR_LOG1("making map chunks");
@@ -928,6 +948,10 @@ uint8_t _LCR_buildMapModel(void)
   return 1;
 }
 
+/**
+  Computes the binary 3D grid of simple LODs (these just say whether in given
+  area is "something" or not) for currently loaded map.
+*/
 void _LCR_rendererComputeLOD(void)
 {
   LCR_LOG1("computing LOD");
@@ -993,6 +1017,10 @@ void LCR_rendererMarkTakenCP(int x, int y, int z)
     }
 }
 
+/**
+  Creates everything that's needed to start rendering the currently loaded map,
+  returns success (1 or 0).
+*/
 uint8_t LCR_rendererLoadMap(void)
 {
   LCR_LOG0("loading map");
@@ -1203,8 +1231,14 @@ void LCR_rendererDrawRect(int x, int y, unsigned int w, unsigned int h,
     }
 }
 
-void _LCR_rendererDrawLODBlock(int blockX, int blockY, int blockZ, unsigned int size,
+/**
-  uint16_t color, uint8_t variability)
+  Draws a very simple LOD block (just a few 2D rectangles) meant to represent
+  far away geometry. The size parameter says base size in pixels (will be
+  affected by perspective), variability is used to create slightly different
+  shapes of blocks.
+*/
+void _LCR_rendererDrawLODBlock(int blockX, int blockY, int blockZ,
+  unsigned int size, uint16_t color, uint8_t variability)
 {
   LCR_LOG2("drawing LOD block");
 
@@ -1381,6 +1415,11 @@ void LCR_rendererDrawSky(int sky, S3L_Unit offsetH, S3L_Unit offsetV)
 #endif
 }
 
+/**
+  Loads a map chunk at chunk coords into given scene model. The chunk param says
+  into which model to load the chunk (0 to 7), the x, y and z params are the
+  coordinates (may even be outside the map).
+*/
 void _LCR_rendererLoadMapChunk(uint8_t chunk, int8_t x, int8_t y, int8_t z)
 {
   LCR_renderer.models[chunk] = LCR_renderer.mapModel;
@@ -1443,8 +1482,8 @@ S3L_Unit _LCR_rendererSmoothRot(S3L_Unit angleOld, S3L_Unit angleNew,
 }
 
 /**
-  Loads the map models with 8 chunks that are nearest to a certain point
+  Loads the map models with 8 chunks that are nearest to a certain point towards
-  towards which the camera is looking.
+  which the camera is looking.
 */
 void _LCR_rendererLoadMapChunks(void)
 {