From 482ab43af5af4b6d0c31e867bc6d169c3023fb97 Mon Sep 17 00:00:00 2001
From: Pavel Rojtberg <rojtberg@gmail.com>
Date: Thu, 25 Apr 2024 00:41:29 +0200
Subject: [PATCH] Docs: improve point_size_attenuation docs

---
 Docs/src/material-scripts.md | 20 +++++++++++++++-----
 OgreMain/include/OgrePass.h  |  9 +++++++--
 2 files changed, 22 insertions(+), 7 deletions(-)

diff --git a/Docs/src/material-scripts.md b/Docs/src/material-scripts.md
index 4f552b6f34b..ceddb088586 100644
--- a/Docs/src/material-scripts.md
+++ b/Docs/src/material-scripts.md
@@ -875,7 +875,9 @@ material Fur
 @copydetails Ogre::Pass::setPointSize
 
 @par
-Format: point\_size &lt;size&gt; Default: point\_size 1.0
+Format: point\_size &lt;size&gt;
+@par
+Default: point\_size 1.0
 
 @ffp_rtss_only
 
@@ -886,7 +888,9 @@ Format: point\_size &lt;size&gt; Default: point\_size 1.0
 @copydetails Ogre::Pass::setPointSpritesEnabled
 
 @par
-Format: point\_sprites &lt;on|off&gt; Default: point\_sprites off
+Format: point\_sprites &lt;on|off&gt;
+@par
+Default: point\_sprites off
 
 <a name="point_005fsize_005fattenuation"></a><a name="point_005fsize_005fattenuation-1"></a>
 
@@ -895,7 +899,9 @@ Format: point\_sprites &lt;on|off&gt; Default: point\_sprites off
 Defines whether point size is attenuated with view space distance, and in what fashion.
 
 @par
-Format: point\_size\_attenuation &lt;enabled&gt; \[constant linear quadratic\] Default: point\_size\_attenuation off
+Format: point\_size\_attenuation &lt;enabled&gt; \[constant linear quadratic\]
+@par
+Default: point\_size\_attenuation off
 
 @copydetails Ogre::Pass::setPointAttenuation
 
@@ -907,7 +913,9 @@ Format: point\_size\_attenuation &lt;enabled&gt; \[constant linear quadratic\] D
 
 Sets the minimum point size after attenuation ([point\_size\_attenuation](#point_005fsize_005fattenuation)). For details on the size metrics, See [point\_size](#point_005fsize).
 @par
-Format: point\_size\_min &lt;size&gt; Default: point\_size\_min 0
+Format: point\_size\_min &lt;size&gt;
+@par
+Default: point\_size\_min 0
 
 <a name="point_005fsize_005fmax"></a><a name="point_005fsize_005fmax-1"></a>
 
@@ -915,7 +923,9 @@ Format: point\_size\_min &lt;size&gt; Default: point\_size\_min 0
 
 Sets the maximum point size after attenuation ([point\_size\_attenuation](#point_005fsize_005fattenuation)). For details on the size metrics, See [point\_size](#point_005fsize). A value of 0 means the maximum is set to the same as the max size reported by the current card. 
 @par
-Format: point\_size\_max &lt;size&gt; Default: point\_size\_max 0
+Format: point\_size\_max &lt;size&gt;
+@par
+Default: point\_size\_max 0
 
 <a name="line_width"></a>
 ## line_width
diff --git a/OgreMain/include/OgrePass.h b/OgreMain/include/OgrePass.h
index d9a2d48aaf5..72ee6d37ab6 100644
--- a/OgreMain/include/OgrePass.h
+++ b/OgreMain/include/OgrePass.h
@@ -479,9 +479,14 @@ namespace Ogre {
 
             When performing point rendering or point sprite rendering,
             point size can be attenuated with distance. The equation for
-            doing this is 
+            doing this is:
             
-            $$attenuation = 1 / (constant + linear * dist + quadratic * d^2)$$
+            \f[ S_a = V_h \cdot S \cdot \frac{1}{\sqrt{constant + linear \cdot d + quadratic \cdot d^2}} \f]
+
+            Where
+            - \f$d\f$ is the distance from the camera to the point
+            - \f$S\f$ is the point size parameter
+            - \f$V_h\f$ is the viewport height in pixels
 
             For example, to disable distance attenuation (constant screensize)
             you would set constant to 1, and linear and quadratic to 0. A