Add documentation of sun/moon orientation/scale differences (#12145)

doc/lua_api.txt

@@ -7208,6 +7208,8 @@ child will follow movement and rotation of that bone.
             (default: `true`)
         * `texture`: A regular texture for the sun. Setting to `""`
             will re-enable the mesh sun. (default: "sun.png", if it exists)
+            The texture appears non-rotated at sunrise and rotated 180 degrees
+            (upside down) at sunset.
         * `tonemap`: A 512x1 texture containing the tonemap for the sun
             (default: `"sun_tonemap.png"`)
         * `sunrise`: A regular texture for the sunrise texture.
@@ -7215,6 +7217,8 @@ child will follow movement and rotation of that bone.
         * `sunrise_visible`: Boolean for whether the sunrise texture is visible.
             (default: `true`)
         * `scale`: Float controlling the overall size of the sun. (default: `1`)
+            Note: For legacy reasons, the sun is bigger than the moon by a factor
+            of about `1.57` for equal `scale` values.
 * `get_sun()`: returns a table with the current sun parameters as in
     `set_sun`.
 * `set_moon(moon_parameters)`:
@@ -7224,11 +7228,15 @@ child will follow movement and rotation of that bone.
             (default: `true`)
         * `texture`: A regular texture for the moon. Setting to `""`
             will re-enable the mesh moon. (default: `"moon.png"`, if it exists)
-            Note: Relative to the sun, the moon texture is rotated by 180°.
+            The texture appears non-rotated at sunrise / moonset and rotated 180
+            degrees (upside down) at sunset / moonrise.
+            Note: Relative to the sun, the moon texture is hence rotated by 180°.
             You can use the `^[transformR180` texture modifier to achieve the same orientation.
         * `tonemap`: A 512x1 texture containing the tonemap for the moon
             (default: `"moon_tonemap.png"`)
         * `scale`: Float controlling the overall size of the moon (default: `1`)
+            Note: For legacy reasons, the sun is bigger than the moon by a factor
+            of about `1.57` for equal `scale` values.
 * `get_moon()`: returns a table with the current moon parameters as in
     `set_moon`.
 * `set_stars(star_parameters)`:

src/client/sky.cpp

@@ -142,7 +142,6 @@ void Sky::render()
 	driver->setTransform(video::ETS_WORLD, translate * scale);
 
 	if (m_sunlight_seen) {
-		float sunsize = 0.07;
 		video::SColorf suncolor_f(1, 1, 0, 1);
 		//suncolor_f.r = 1;
 		//suncolor_f.g = MYMAX(0.3, MYMIN(1.0, 0.7 + m_time_brightness * 0.5));
@@ -156,7 +155,6 @@ void Sky::render()
 		suncolor_f.g = MYMAX(0.3, MYMIN(1.0, 0.85 + m_time_brightness * 0.5));
 		suncolor_f.b = MYMAX(0.0, m_brightness);
 
-		float moonsize = 0.04;
 		video::SColorf mooncolor_f(0.50, 0.57, 0.65, 1);
 		video::SColorf mooncolor2_f(0.85, 0.875, 0.9, 1);
 
@@ -294,11 +292,11 @@ void Sky::render()
 
 		// Draw sun
 		if (m_sun_params.visible)
-			draw_sun(driver, sunsize, suncolor, suncolor2, wicked_time_of_day);
+			draw_sun(driver, suncolor, suncolor2, wicked_time_of_day);
 
 		// Draw moon
 		if (m_moon_params.visible)
-			draw_moon(driver, moonsize, mooncolor, mooncolor2, wicked_time_of_day);
+			draw_moon(driver, mooncolor, mooncolor2, wicked_time_of_day);
 
 		// Draw far cloudy fog thing below all horizons in front of sun, moon
 		// and stars.
@@ -573,16 +571,18 @@ v3f Sky::getMoonDirection()
 	return getSkyBodyPosition(270, getWickedTimeOfDay(m_time_of_day) * 360 - 90, m_sky_body_orbit_tilt);
 }
 
-void Sky::draw_sun(video::IVideoDriver *driver, float sunsize, const video::SColor &suncolor,
+void Sky::draw_sun(video::IVideoDriver *driver, const video::SColor &suncolor,
 	const video::SColor &suncolor2, float wicked_time_of_day)
 	/* Draw sun in the sky.
 	 * driver: Video driver object used to draw
-	 * sunsize: the default size of the sun
 	 * suncolor: main sun color
 	 * suncolor2: second sun color
 	 * wicked_time_of_day: current time of day, to know where should be the sun in the sky
 	 */
 {
+	// A magic number that contributes to the ratio 1.57 sun/moon size difference.
+	constexpr float sunsize = 0.07;
+
 	static const u16 indices[] = {0, 1, 2, 0, 2, 3};
 	std::array<video::S3DVertex, 4> vertices;
 	if (!m_sun_texture) {
@@ -605,6 +605,8 @@ void Sky::draw_sun(video::IVideoDriver *driver, float sunsize, const video::SCol
 		}
 	} else {
 		driver->setMaterial(m_materials[3]);
+		// Another magic number that contributes to the ratio 1.57 sun/moon size
+		// difference.
 		float d = (sunsize * 1.7) * m_sun_params.scale;
 		video::SColor c;
 		if (m_sun_tonemap)
@@ -618,18 +620,20 @@ void Sky::draw_sun(video::IVideoDriver *driver, float sunsize, const video::SCol
 }
 
 
-void Sky::draw_moon(video::IVideoDriver *driver, float moonsize, const video::SColor &mooncolor,
+void Sky::draw_moon(video::IVideoDriver *driver, const video::SColor &mooncolor,
 	const video::SColor &mooncolor2, float wicked_time_of_day)
 /*
 	* Draw moon in the sky.
 	* driver: Video driver object used to draw
-	* moonsize: the default size of the moon
 	* mooncolor: main moon color
 	* mooncolor2: second moon color
 	* wicked_time_of_day: current time of day, to know where should be the moon in
 	* the sky
 	*/
 {
+	// A magic number that contributes to the ratio 1.57 sun/moon size difference.
+	constexpr float moonsize = 0.04;
+
 	static const u16 indices[] = {0, 1, 2, 0, 2, 3};
 	std::array<video::S3DVertex, 4> vertices;
 	if (!m_moon_texture) {
@@ -658,6 +662,8 @@ void Sky::draw_moon(video::IVideoDriver *driver, float moonsize, const video::SC
 		}
 	} else {
 		driver->setMaterial(m_materials[4]);
+		// Another magic number that contributes to the ratio 1.57 sun/moon size
+		// difference.
 		float d = (moonsize * 1.9) * m_moon_params.scale;
 		video::SColor c;
 		if (m_moon_tonemap)

src/client/sky.h

@@ -200,9 +200,9 @@ private:
 
 	void updateStars();
 
-	void draw_sun(video::IVideoDriver *driver, float sunsize, const video::SColor &suncolor,
+	void draw_sun(video::IVideoDriver *driver, const video::SColor &suncolor,
 		const video::SColor &suncolor2, float wicked_time_of_day);
-	void draw_moon(video::IVideoDriver *driver, float moonsize, const video::SColor &mooncolor,
+	void draw_moon(video::IVideoDriver *driver, const video::SColor &mooncolor,
 		const video::SColor &mooncolor2, float wicked_time_of_day);
 	void draw_sky_body(std::array<video::S3DVertex, 4> &vertices,
 		float pos_1, float pos_2, const video::SColor &c);