Add more tilemap documentation

include/map.h

@@ -4,20 +4,33 @@
 #include "screen.h"
 
 /**
- * @page TileMap TileMap
+ * @page TileMap Tile Map
  * @brief The map consists of tiles to create the world.
  *
- * 16x16 tiles
- * 8x8 subTiles
+ * GBA graphics are made out of tiles with a size of 8px by 8px. We call those tiles *subTiles*.
+ * Four of those subTiles are combined together to form a bigger 16px by 16px tile (usually called metaTile). We call these *tiles*.
  *
- * tileIndex index into the tile set
- *  0 to 0x800, special tiles at 0x4000 to 0x4096
- * tilePos index into the current map
- * tileType
- * collisionData
- * 
+ * Each map can be up to 64 * 64 tiles big. The map consists of two layers of tiles gMapTop and gMapBottom.
+ * To access the map array the tilePos index can be used which goes from 0 to 64 * 64 = 4096.
+ * Each value in the MapLayer.mapData is a tileIndex which defined which tile of the tileSet should be used.
+ * The tileSet contains tiles from 0 to 2048. Special tileIndex from 0x4000 to 0x4096 can be used to denote special tiles.
+ *
+ * A tile is created from four subTiles. The subTiles for each tile in the tileSet are stored in MapLayer.subTiles. This is loaded for the current area from gAreaTileSets_*.
+ * The subTiles can also be flipped or the palette changed. This is stored in bits 0xa to 0xf, see https://www.coranac.com/tonc/text/regbg.htm#sec-map.
+ *
+ * Each tile in the tileSet also has a tileType defined. This is stored in MapLayer.tileTypes and loaded from gAreaTileSetTypes_*.
+ * The inverse dictionary from tileType to tileIndex is stored in MapLayer.tileIndices.
+ *
+ * The map also stores the collision for each tile in the tileMap layer in MapLayer.collisionData. By default this is filled from gMapTileTypeToCollisionData based on the tileType of the tiles.
+ * But it can also be loaded from gRoomCollisionMap_*.
+ * In MapLayer.actTiles some additional type for each tile is stored which is filled from gMapTileTypeToActTile based on the tileType of the tiles.
  */
 
+// Maximum width or height of a map in tiles.
+#define MAX_MAP_SIZE 64
+// Maximum amount of tiles in a tileSet.
+#define TILESET_SIZE 2048
+
 /**
  * @brief Layer of the TileMap.
  * @ingroup TileMap
@@ -27,62 +40,80 @@ typedef struct {
     /**
      * tileIndex for each tile on the current layer.
      */
-    /*0x0004*/ u16 mapData[0x40 * 0x40];
+    /*0x0004*/ u16 mapData[MAX_MAP_SIZE * MAX_MAP_SIZE];
     /**
      * Collision data for each tile on the current layer.
      * @see CollisionData
      */
-    /*0x2004*/ u8 collisionData[0x40 * 0x40];
+    /*0x2004*/ u8 collisionData[MAX_MAP_SIZE * MAX_MAP_SIZE];
     /**
      * Copy of the map data.
      * @see mapData
      */
-    /*0x3004*/ u16 mapDataOriginal[0x40 * 0x40];
+    /*0x3004*/ u16 mapDataOriginal[MAX_MAP_SIZE * MAX_MAP_SIZE];
     /**
      * Maps from the tileIndex to the tileType.
      * @see TileType
      */
-    /*0x5004*/ u16 tileTypes[0x800];
+    /*0x5004*/ u16 tileTypes[TILESET_SIZE];
     /**
      * Maps from a tileType to a tileIndex. Inverse of @see tileTypes.
      * @see TileType
      */
-    /*0x6004*/ u16 tileIndices[0x800];
+    /*0x6004*/ u16 tileIndices[TILESET_SIZE];
     /**
      * Maps from a tile index to the four sub tiles (with attributes) it consists of.
      * @see https://www.coranac.com/tonc/text/regbg.htm#sec-map
      */
-    /*0x7004*/ u16 subTiles[0x800 * 4];
+    /*0x7004*/ u16 subTiles[TILESET_SIZE * 4];
     /**
      * Some sort of special behavior for tiles? Falling into holes or jumping off walls does not work when this is all zero.
      * @see ActTile
      */
-    /*0xb004*/ u8 actTiles[0x40*0x40];
+    /*0xb004*/ u8 actTiles[MAX_MAP_SIZE * MAX_MAP_SIZE];
 } MapLayer;
 
 extern MapLayer gMapTop;
 extern MapLayer gMapBottom;
 
-extern MapLayer* GetLayerByIndex(u32 layer);
-
-/*
-Definition where some map data is found and where it should be copied to.
-Defined using the map_data asm macro, e.g. in map_headers.s
-*/
-typedef struct {
-    u32 src;
-    void* dest;
-    u32 size;
-} MapDataDefinition;
-
-// There is another map data definition following.
-#define MAP_MULTIPLE 0x80000000
-// The src is compressed.
-#define MAP_COMPRESSED 0x80000000
-
 typedef enum {
     LAYER_BOTTOM = 1,
     LAYER_TOP = 2,
 } LayerIndex;
 
+/**
+ * Returns the MapLayer for a layer of the map.
+ *
+ * @param layer @see LayerIndex
+ */
+extern MapLayer* GetLayerByIndex(u32 layer);
+
+// There is another map data definition following.
+#define MAP_MULTIPLE 0x80000000
+// The src is compressed.
+#define MAP_COMPRESSED 0x80000000
+
+/**
+ * Definition where some map data is found and where it should be copied to.
+ * Defined using the map_data asm macro, e.g. in map_headers.s
+ */
+typedef struct {
+    /**
+     * @brief Source offset from gMapData.
+     *
+     * MAP_MULTIPLE bit is set if there is another MapDataDefinition following.
+     */
+    u32 src;
+    /**
+     * Target pointer where to load or decompress the map data to.
+     */
+    void* dest;
+    /**
+     * @brief Size of the map data in bytes.
+     *
+     * MAP_COMPRESSED bit is set if the map data is compressed.
+     */
+    u32 size;
+} MapDataDefinition;
+
 #endif // MAP_H