openttd-ottdgrfs: comparison src/tgp.cpp

equal deleted inserted replaced

-:6db1c5112e97
+:3a53e7dcff4c
 	uint     dim_x;      //< height map size_x MapSizeX() + 1
 	uint     total_size; //< height map total size
 	uint     size_x;     //< MapSizeX()
 	uint     size_y;     //< MapSizeY()
+	/**
+	 * Height map accessor
+	 * @param x X position
+	 * @param y Y position
+	 * @return height as fixed point number
+	 */
 	inline height_t &height(uint x, uint y) {
 		return h[x + y * dim_x];
 	}
 };
 {
 	return ((int)x) >= 0 && x < _height_map.size_x && ((int)y) >= 0 && y < _height_map.size_y;
 }
-/** Allocate array of (MapSizeX()+1)*(MapSizeY()+1) heights and init the _height_map structure members */
+/**
+* Allocate array of (MapSizeX()+1)*(MapSizeY()+1) heights and init the _height_map structure members
+* @return true on success
+*/
 static inline bool AllocHeightMap()
 {
 	height_t *h;
 	_height_map.size_x = MapSizeX();
 	if (_height_map.h == NULL) return;
 	free(_height_map.h);
 	_height_map.h = NULL;
 }
-/** RandomHeight() generator */
+/**
+* Generates new random height in given amplitude (generated numbers will range from - amplitude to + amplitude)
+* @param rMax Limit of result
+* @return generated height
+*/
 static inline height_t RandomHeight(amplitude_t rMax)
 {
 	amplitude_t ra = (Random() << 16) | (Random() & 0x0000FFFF);
 	height_t rh;
 	/* Spread height into range -rMax..+rMax */
 	rh = A2H(ra % (2 * rMax + 1) - rMax);
 	return rh;
 }
-/** One interpolation and noise round */
+/**
+* One interpolation and noise round
+*
+* The heights on the map are generated in an iterative process.
+* We start off with a frequency of 1 (log_frequency == 0), and generate heights only for corners on the most coarsly mesh
+* (i.e. only for x/y coordinates which are multiples of the minimum edge length).
+*
+* After this initial step the frequency is doubled (log_frequency incremented) each iteration to generate corners on the next finer mesh.
+* The heights of the newly added corners are first set by interpolating the heights from the previous iteration.
+* Finally noise with the given amplitude is applied to all corners of the new mesh.
+*
+* Generation terminates, when the frequency has reached the map size. I.e. the mesh is as fine as the map, and every corner height
+* has been set.
+*
+* @param log_frequency frequency (logarithmic) to apply noise for
+* @param amplitude Amplitude for the noise
+* @return false if we are finished (reached the minimal step size / highest frequency)
+*/
 static bool ApplyNoise(uint log_frequency, amplitude_t amplitude)
 {
 	uint size_min = min(_height_map.size_x, _height_map.size_y);
 	uint step = size_min >> log_frequency;
 	uint x, y;
+	/* Trying to apply noise to uninitialized height map */
 	assert(_height_map.h != NULL);
 	/* Are we finished? */
 	if (step == 0) return false;
 			height_t h10 = (h00 + h20) / 2;
 			_height_map.height(x, y + 1 * step) = h10;
 		}
 	}
+	/* Add noise for next higher frequency (smaller steps) */
 	for (y = 0; y <= _height_map.size_y; y += step) {
 		for (x = 0; x <= _height_map.size_x; x += step) {
 			_height_map.height(x, y) += RandomHeight(amplitude);
 		}
 	}
 	return (step > 1);
 }
 /** Base Perlin noise generator - fills height map with raw Perlin noise */
 static void HeightMapGenerate()
 	/* Find first power of two that fits */
 	for (log_size_min = 6; (1U << log_size_min) < size_min; log_size_min++) { }
 	log_frequency_min = log_size_min - 6;
+	/* Keep increasing the frequency until we reach the step size equal to one tile */
 	do {
 		log_frequency = iteration_round - log_frequency_min;
 		if (log_frequency >= 0) {
+			/* Apply noise for the next frequency */
 			amplitude = _amplitudes_by_smoothness_and_frequency[_settings_game.game_creation.tgen_smoothness][log_frequency];
 		} else {
+			/* Amplitude for the low frequencies on big maps is 0, i.e. initialise with zero height */
 			amplitude = 0;
 		}
 		continue_iteration = ApplyNoise(iteration_round, amplitude);
 		iteration_round++;
-	} while(continue_iteration);
+	} while (continue_iteration);
 }
 /** Returns min, max and average height from height map */
 static void HeightMapGetMinMaxAvg(height_t *min_ptr, height_t *max_ptr, height_t *avg_ptr)
 {
 static int *HeightMapMakeHistogram(height_t h_min, height_t h_max, int *hist_buf)
 {
 	int *hist = hist_buf - h_min;
 	height_t *h;
-	/* Fill histogram */
+	/* Count the heights and fill the histogram */
 	FOR_ALL_TILES_IN_HEIGHT(h) {
 		assert(*h >= h_min);
 		assert(*h <= h_max);
 		hist[*h]++;
 	}
 	return total;
 }
-/** A small helper function */
+/** A small helper function to initialize the terrain */
 static void TgenSetTileHeight(TileIndex tile, int height)
 {
 	SetTileHeight(tile, height);
 	MakeClear(tile, CLEAR_GRASS, 3);
 }

changeset 11109	3a53e7dcff4c
parent 11091	6b5352725f43
child 11113	3cb24f59d83e