Code review cleanup, add setting documentation

apps/openmw/engine.cpp

@@ -31,7 +31,6 @@
 #include <components/compiler/extensions0.hpp>
 
 #include <components/sceneutil/workqueue.hpp>
-#include <components/sceneutil/lightmanager.hpp>
 
 #include <components/files/configurationmanager.hpp>
 

components/sceneutil/lightmanager.cpp

@@ -136,33 +136,35 @@ namespace SceneUtil
         switch (method)
         {
         case LightingMethod::FFP:
-            break;
+            {
+                break;
+            }
         case LightingMethod::PerObjectUniform:
-        {
-            stateset->addUniform(new osg::Uniform("LightBuffer[0].diffuse", light->getDiffuse()), mode);
-            stateset->addUniform(new osg::Uniform("LightBuffer[0].ambient", light->getAmbient()), mode);
-            stateset->addUniform(new osg::Uniform("LightBuffer[0].specular", light->getSpecular()), mode);
-            stateset->addUniform(new osg::Uniform("LightBuffer[0].position", light->getPosition()), mode);
+            {
+                stateset->addUniform(new osg::Uniform("LightBuffer[0].diffuse", light->getDiffuse()), mode);
+                stateset->addUniform(new osg::Uniform("LightBuffer[0].ambient", light->getAmbient()), mode);
+                stateset->addUniform(new osg::Uniform("LightBuffer[0].specular", light->getSpecular()), mode);
+                stateset->addUniform(new osg::Uniform("LightBuffer[0].position", light->getPosition()), mode);
 
-            break;
-        }
+                break;
+            }
         case LightingMethod::SingleUBO:
-        {
-            osg::ref_ptr<LightBuffer> buffer = new LightBuffer(1);
+            {
+                osg::ref_ptr<LightBuffer> buffer = new LightBuffer(1);
 
-            buffer->setDiffuse(0, light->getDiffuse());
-            buffer->setAmbient(0, light->getAmbient());
-            buffer->setSpecular(0, light->getSpecular());
-            buffer->setPosition(0, light->getPosition());
+                buffer->setDiffuse(0, light->getDiffuse());
+                buffer->setAmbient(0, light->getAmbient());
+                buffer->setSpecular(0, light->getSpecular());
+                buffer->setPosition(0, light->getPosition());
 
-            osg::ref_ptr<osg::UniformBufferObject> ubo = new osg::UniformBufferObject;
-            buffer->mData->setBufferObject(ubo);
-            osg::ref_ptr<osg::UniformBufferBinding> ubb = new osg::UniformBufferBinding(static_cast<int>(Shader::UBOBinding::LightBuffer), buffer->mData.get(), 0, buffer->mData->getTotalDataSize());
+                osg::ref_ptr<osg::UniformBufferObject> ubo = new osg::UniformBufferObject;
+                buffer->mData->setBufferObject(ubo);
+                osg::ref_ptr<osg::UniformBufferBinding> ubb = new osg::UniformBufferBinding(static_cast<int>(Shader::UBOBinding::LightBuffer), buffer->mData.get(), 0, buffer->mData->getTotalDataSize());
 
-            stateset->setAttributeAndModes(ubb, mode);
+                stateset->setAttributeAndModes(ubb, mode);
 
-            break;
-        }
+                break;
+            }
         }
     }
 
@@ -201,9 +203,9 @@ namespace SceneUtil
         void apply(osg::State& state) const override
         {
             int lightNum = GL_LIGHT0 + mIndex;
-            glLightfv( lightNum, GL_AMBIENT,               mnullptr.ptr() );
-            glLightfv( lightNum, GL_DIFFUSE,               mnullptr.ptr() );
-            glLightfv( lightNum, GL_SPECULAR,              mnullptr.ptr() );
+            glLightfv(lightNum, GL_AMBIENT, mnullptr.ptr());
+            glLightfv(lightNum, GL_DIFFUSE, mnullptr.ptr());
+            glLightfv(lightNum, GL_SPECULAR, mnullptr.ptr());
 
             LightStateCache* cache = getLightStateCache(state.getContextID());
             cache->lastAppliedLight[mIndex] = nullptr;
@@ -595,7 +597,7 @@ namespace SceneUtil
         : mStartLight(0)
         , mLightingMask(~0u)
         , mSun(nullptr)
-        , mPointLightRadiusMultiplier(std::max(0.f, Settings::Manager::getFloat("light bounds multiplier", "Shaders")))
+        , mPointLightRadiusMultiplier(std::clamp(Settings::Manager::getFloat("light bounds multiplier", "Shaders"), 0.f, 10.f))
         , mPointLightFadeStart(0.f)
     {
         mPointLightFadeEnd = std::max(0.f, Settings::Manager::getFloat("maximum light distance", "Shaders"));

docs/source/reference/modding/settings/shaders.rst

@@ -148,6 +148,69 @@ By default, the fog becomes thicker proportionally to your distance from the cli
 This setting makes the fog use the actual eye point distance (or so called Euclidean distance) to calculate the fog, which makes the fog look less artificial, especially if you have a wide FOV.
 Note that the rendering will act as if you have 'force shaders' option enabled with this on, which means that shaders will be used to render all objects and the terrain.
 
+lighting method
+---------------
+
+:Type:		string
+:Range:		legacy|default|experimental
+:Default:	default
+
+Sets the internal handling of light sources. 
+
+'legacy' is restricted to a maximum of 8 lights per object and guarantees fixed function pipeline compatible lighting.
+
+'default' removes the light limit via :ref:`max lights` and follows a new attenuation formula which can drastically reduce light popping and seams.
+It is recommended to use this mode with older hardware, as the technique ensures a range of compatibility equal to that of 'legacy'.
+
+'experimental' carries all of the benefits that 'legacy' has, but uses a modern approach that allows for a higher 'max lights' count with little to no performance penalties on modern hardware.
+
+light bounds multiplier
+-----------------------
+
+:Type:		float
+:Range:		0.0-10.0
+:Default:	2.0
+
+Controls the bounding sphere radius of point lights, which is used to determine if an object should receive lighting from a particular light source.
+Note, this has no direct effect on the overall illumination of lights.
+Larger multipliers will allow for smoother transitions of light sources, but may require an increase in :ref:`max lights` and thus carries a performance penalty.
+This especially helps with abrupt light popping with handheld light sources such as torches and lanterns.
+
+It is recommended to keep this at 1.0 if :ref:`lighting method` is set to 'legacy', as the number of lights is fixed in that mode.
+
+maximum light distance
+----------------------
+
+:Type:		float
+:Range:		The whole range of 32-bit floating point
+:Default:	8192
+
+The maximum distance from the camera that lights will be illuminated, applies to both interiors and exteriors.
+A lower distance will improve performance.
+Set this to a non-positive value to disable fading.
+
+light fade start
+----------------
+
+:Type:		float
+:Range:		0.0-1.0
+:Default:	0.85
+
+The fraction of the maximum distance at which lights will begin to fade away.
+Tweaking it will make the transition proportionally more or less smooth.
+This setting has no effect if the maximum light distance is non-positive.
+
+max lights
+----------
+
+:Type:		integer
+:Range:		>=2
+:Default:	16
+
+Sets the maximum number of lights that each object can receive lighting from.
+Has no effect if :ref:`force shaders` option is off or :ref:`lighting method` is 'legacy'. In this case the maximum number of lights is fixed at 8.
+Increasing this too much can cause significant performance loss, especially if :ref:`lighting method` is not set to 'experimental' or :ref:`force per pixel lighting` is on. 
+
 antialias alpha test
 ---------------------------------------
 

files/shaders/objects_fragment.glsl

@@ -76,8 +76,8 @@ varying vec3 passNormal;
 
 #include "vertexcolors.glsl"
 #include "shadows_fragment.glsl"
-#include "parallax.glsl"
 #include "lighting.glsl"
+#include "parallax.glsl"
 #include "alpha.glsl"
 
 void main()

files/shaders/terrain_fragment.glsl

@@ -34,8 +34,8 @@ varying vec3 passNormal;
 
 #include "vertexcolors.glsl"
 #include "shadows_fragment.glsl"
-#include "parallax.glsl"
 #include "lighting.glsl"
+#include "parallax.glsl"
 
 void main()
 {