From 6c35825453699f7490c19198cd8cc9e56b299d0c Mon Sep 17 00:00:00 2001
From: rubidium <rubidium@openttd.org>
Date: Mon, 20 Oct 2008 15:44:14 +0000
Subject: (svn r14502) -Codechange: add some inline comments and declare
 variable on use (Alberth)

---
 src/tile_map.cpp | 45 +++++++++++++++++++++++++--------------------
 1 file changed, 25 insertions(+), 20 deletions(-)

(limited to 'src')

diff --git a/src/tile_map.cpp b/src/tile_map.cpp
index 27b0a08a1..4f6ea17d6 100644
--- a/src/tile_map.cpp
+++ b/src/tile_map.cpp
@@ -14,13 +14,6 @@
  * @return Slope of the tile, except for the HALFTILE part */
 Slope GetTileSlope(TileIndex tile, uint *h)
 {
-	uint a;
-	uint b;
-	uint c;
-	uint d;
-	uint min;
-	uint r;
-
 	assert(tile < MapSize());
 
 	if (TileX(tile) == MapMaxX() || TileY(tile) == MapMaxY()) {
@@ -28,15 +21,27 @@ Slope GetTileSlope(TileIndex tile, uint *h)
 		return SLOPE_FLAT;
 	}
 
-	min = a = TileHeight(tile);
-	b = TileHeight(tile + TileDiffXY(1, 0));
+	uint a = TileHeight(tile); // Height of the N corner
+	uint min = a; // Minimal height of all corners examined so far
+	uint b = TileHeight(tile + TileDiffXY(1, 0)); // Height of the W corner
 	if (min > b) min = b;
-	c = TileHeight(tile + TileDiffXY(0, 1));
+	uint c = TileHeight(tile + TileDiffXY(0, 1)); // Height of the E corner
 	if (min > c) min = c;
-	d = TileHeight(tile + TileDiffXY(1, 1));
+	uint d = TileHeight(tile + TileDiffXY(1, 1)); // Height of the S corner
 	if (min > d) min = d;
 
-	r = SLOPE_FLAT;
+	/* Due to the fact that tiles must connect with each other without leaving gaps, the
+	 * biggest difference in height between any corner and 'min' is between 0, 1, or 2.
+	 *
+	 * Also, there is at most 1 corner with height difference of 2.
+	 */
+
+	uint r = SLOPE_FLAT; // Computed slope of the tile
+
+	/* For each corner if not equal to minimum height:
+	 *  - set the SLOPE_STEEP flag if the difference is 2
+	 *  - add the corresponding SLOPE_X constant to the computed slope
+	 */
 	if ((a -= min) != 0) r += (--a << 4) + SLOPE_N;
 	if ((c -= min) != 0) r += (--c << 4) + SLOPE_E;
 	if ((d -= min) != 0) r += (--d << 4) + SLOPE_S;
@@ -55,10 +60,10 @@ uint GetTileZ(TileIndex tile)
 {
 	if (TileX(tile) == MapMaxX() || TileY(tile) == MapMaxY()) return 0;
 
-	uint h = TileHeight(tile);
-	h = min(h, TileHeight(tile + TileDiffXY(1, 0)));
-	h = min(h, TileHeight(tile + TileDiffXY(0, 1)));
-	h = min(h, TileHeight(tile + TileDiffXY(1, 1)));
+	uint h = TileHeight(tile); // N corner
+	h = min(h, TileHeight(tile + TileDiffXY(1, 0))); // W corner
+	h = min(h, TileHeight(tile + TileDiffXY(0, 1))); // E corner
+	h = min(h, TileHeight(tile + TileDiffXY(1, 1))); // S corner
 
 	return h * TILE_HEIGHT;
 }
@@ -71,10 +76,10 @@ uint GetTileMaxZ(TileIndex t)
 {
 	if (TileX(t) == MapMaxX() || TileY(t) == MapMaxY()) return 0;
 
-	uint h = TileHeight(t);
-	h = max(h, TileHeight(t + TileDiffXY(1, 0)));
-	h = max(h, TileHeight(t + TileDiffXY(0, 1)));
-	h = max(h, TileHeight(t + TileDiffXY(1, 1)));
+	uint h = TileHeight(t); // N corner
+	h = max(h, TileHeight(t + TileDiffXY(1, 0))); // W corner
+	h = max(h, TileHeight(t + TileDiffXY(0, 1))); // E corner
+	h = max(h, TileHeight(t + TileDiffXY(1, 1))); // S corner
 
 	return h * TILE_HEIGHT;
 }
-- 
cgit v1.2.3-70-g09d2