Add some comments

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_Model3D mapModel; ///< whole map model
-  S3L_Model3D *carModel;
-  S3L_Model3D *ghostModel;
+  S3L_Scene scene;          ///< Whole 3D scene.
+  S3L_Model3D mapModel;     ///< Whole map model.
+  S3L_Model3D *carModel;    ///< Shortcut pointer to the car model in scene.
+  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
-  towards which the camera is looking.
+  Loads the map models with 8 chunks that are nearest to a certain point towards
+  which the camera is looking.
 */
 void _LCR_rendererLoadMapChunks(void)
 {