From 0b41533763bc9f104a2da2e4191f4654b8d8dab4 Mon Sep 17 00:00:00 2001
From: sfan5 <sfan5@live.de>
Date: Mon, 20 Jun 2022 21:24:28 +0200
Subject: [PATCH] Annotate light spread functions with comments

---
 src/mapgen/mapgen.cpp |  8 ++------
 src/mapgen/mapgen.h   | 42 ++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 42 insertions(+), 8 deletions(-)

diff --git a/src/mapgen/mapgen.cpp b/src/mapgen/mapgen.cpp
index 1f2ac491e..cca036b7b 100644
--- a/src/mapgen/mapgen.cpp
+++ b/src/mapgen/mapgen.cpp
@@ -453,9 +453,8 @@ void Mapgen::lightSpread(VoxelArea &a, std::queue<std::pair<v3s16, u8>> &queue,
 			!ndef->get(n).light_propagates)
 		return;
 
-	// Since this recursive function only terminates when there is no light from
-	// either bank left, we need to take the max of both banks into account for
-	// the case where spreading has stopped for one light bank but not the other.
+	// MYMAX still needed here because we only exit early if both banks have
+	// nothing to propagate anymore.
 	light = MYMAX(light_day, n.param1 & 0x0F) |
 			MYMAX(light_night, n.param1 & 0xF0);
 
@@ -470,12 +469,9 @@ void Mapgen::calcLighting(v3s16 nmin, v3s16 nmax, v3s16 full_nmin, v3s16 full_nm
 	bool propagate_shadow)
 {
 	ScopeProfiler sp(g_profiler, "EmergeThread: update lighting", SPT_AVG);
-	//TimeTaker t("updateLighting");
 
 	propagateSunlight(nmin, nmax, propagate_shadow);
 	spreadLight(full_nmin, full_nmax);
-
-	//printf("updateLighting: %dms\n", t.stop());
 }
 
 
diff --git a/src/mapgen/mapgen.h b/src/mapgen/mapgen.h
index 61db4f3b9..ef5de6029 100644
--- a/src/mapgen/mapgen.h
+++ b/src/mapgen/mapgen.h
@@ -190,12 +190,38 @@ public:
 
 	void updateLiquid(UniqueQueue<v3s16> *trans_liquid, v3s16 nmin, v3s16 nmax);
 
+	/**
+	 * Set light in entire area to fixed value.
+	 * @param light Light value (contains both banks)
+	 * @param nmin Area to operate on
+	 * @param nmax ^
+	 */
 	void setLighting(u8 light, v3s16 nmin, v3s16 nmax);
-	void lightSpread(VoxelArea &a, std::queue<std::pair<v3s16, u8>> &queue,
-		const v3s16 &p, u8 light);
+	/**
+	 * Run all lighting calculations.
+	 * @param nmin Area to spread sunlight in
+	 * @param nmax ^
+	 * @param full_nmin Area to recalculate light in
+	 * @param full_nmax ^
+	 * @param propagate_shadow see propagateSunlight()
+	 */
 	void calcLighting(v3s16 nmin, v3s16 nmax, v3s16 full_nmin, v3s16 full_nmax,
 		bool propagate_shadow = true);
+	/**
+	 * Spread sunlight from the area above downwards.
+	 * Note that affected nodes have their night bank cleared so you want to
+	 * run a light spread afterwards.
+	 * @param nmin Area to operate on
+	 * @param nmax ^
+	 * @param propagate_shadow Ignore obstructions above and spread sun anyway
+	 */
 	void propagateSunlight(v3s16 nmin, v3s16 nmax, bool propagate_shadow);
+	/**
+	 * Spread light in the given area.
+	 * Artificial light is taken from nodedef, sunlight must already be set.
+	 * @param nmin Area to operate on
+	 * @param nmax ^
+	 */
 	void spreadLight(const v3s16 &nmin, const v3s16 &nmax);
 
 	virtual void makeChunk(BlockMakeData *data) {}
@@ -218,6 +244,18 @@ public:
 	static void setDefaultSettings(Settings *settings);
 
 private:
+	/**
+	 * Spread light to the node at the given position, add to queue if changed.
+	 * The given light value is diminished once.
+	 * @param a VoxelArea being operated on
+	 * @param queue Queue for later lightSpread() calls
+	 * @param p Node position
+	 * @param light Light value (contains both banks)
+	 *
+	 */
+	void lightSpread(VoxelArea &a, std::queue<std::pair<v3s16, u8>> &queue,
+		const v3s16 &p, u8 light);
+
 	// isLiquidHorizontallyFlowable() is a helper function for updateLiquid()
 	// that checks whether there are floodable nodes without liquid beneath
 	// the node at index vi.