Annotate light spread functions with comments

diff --git a/src/mapgen/mapgen.cpp b/src/mapgen/mapgen.cpp
index 1f2ac491e952331e41aac3249760d5d18be5c3f7..cca036b7bd6ce8bd7369e78848bc9263dc13e730 100644 (file)
--- 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 61db4f3b97740e2a679d61c01c34006086e08f4a..ef5de60291e272bcd2d067ae523f56e7edeb8af3 100644 (file)
--- a/src/mapgen/mapgen.h
+++ b/src/mapgen/mapgen.h
@@ -190,12 +190,38 @@ class Mapgen {
 
        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 @@ class Mapgen {
        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.