Update documentation

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

@@ -22,12 +22,23 @@ number of shadow maps
 
 :Type:		integer
 :Range:		1 to 8, but higher values may conflict with other texture effects
-:Default:	1
+:Default:	3
 
 Control how many shadow maps to use - more of these means each shadow map texel covers less area, producing better-looking shadows, but may decrease performance.
 Using too many shadow maps will lead to them overriding texture slots used for other effects, producing unpleasant artefacts.
 A value of three is recommended in most cases, but other values may produce better results or performance.
 
+allow shadow map overlap
+------------------------
+
+:Type:		boolean
+:Range:		True/False
+:Default:	True
+
+If true, allow shadow maps to overlap.
+Counter-intuitively, will produce much better results when the light is behind the camera.
+When enabled, OpenMW uses Cascaded Shadow Maps and when disabled, it uses Parallel Split Shadow Maps.
+
 enable debug hud
 ----------------
 
@@ -97,8 +108,9 @@ Note: Right now, there is no setting allowing toggling of shadows for statics
 Expert settings
 ***************
 
-You probably shouldn't be changing these if you haven't read `this paper on Parallel Split Shadow Maps <https://pdfs.semanticscholar.org/15a9/f2a7cf6b1494f45799617c017bd42659d753.pdf>`_ and understood how they interact with the transformation used with Light Space Perspective Shadow Maps.
+You probably shouldn't be changing these yourself if you haven't read `this paper on Parallel Split Shadow Maps <https://pdfs.semanticscholar.org/15a9/f2a7cf6b1494f45799617c017bd42659d753.pdf>`_ and understood how they interact with the transformation used with Light Space Perspective Shadow Maps.
 If you have, then you may get better results tuning these for your specific view distance.
+Copying values from another user who's done careful tuning is the recommended way of arriving at an optimal value for these settings.
 
 split point uniform logarithmic ratio
 -------------------------------------
@@ -108,6 +120,8 @@ split point uniform logarithmic ratio
 :Default:	0.5
 
 Controls the ratio of :math:`C_i^{log}` versus :math:`C_i^{uniform}` used to form the Practical Split Scheme as described in the linked paper.
+When using a larger-than-default viewing distance and distant terrain, and you have `allow shadow map overlap`_ enabled, larger values will prevent nearby shadows losing quality.
+It is therefore recommended that this isn't left at the default when the viewing distance is changed.
 
 split point bias
 ----------------

files/settings-default.cfg

@@ -514,7 +514,7 @@ enable shadows = false
 number of shadow maps = 3
 # If true, allow shadow maps to overlap. Counter-intuitively, will produce better results when the light is behind the camera. When enabled, OpenMW uses Cascaded Shadow Maps and when disabled, it uses Parallel Split Shadow Maps.
 allow shadow map overlap = true
-# Indirectly controls where to split the shadow map(s). Values closer to 1.0 bring more detail closer to the camera (potentially excessively so), and values closer to 0.0 spread it more evenly across the whole viewing distance. 0.5 is recommended for most viewing distances by the original Parallel Split Shadow Maps paper, but this does not take into account use of a Light Space Perspective transformation, so other values may be preferable. If some of the terms used here go over your head, you probably don't want to change this, especially not without reading the associated papers first.
+# Indirectly controls where to split the shadow map(s). Values closer to 1.0 bring more detail closer to the camera (potentially excessively so), and values closer to 0.0 spread it more evenly across the whole viewing distance. 0.5 is recommended for most viewing distances by the original Parallel Split Shadow Maps paper, but this does not take into account use of a Light Space Perspective transformation, so other values may be preferable. If some of the terms used here go over your head, you might not want to change this, especially not without reading the associated papers first. When "allow shadow map overlap" is combined with a higher-than-default viewing distance, values closer to 1.0 will prevent nearby shadows losing a lot of quality.
 split point uniform logarithmic ratio = 0.5
 # Indirectly controls where to split the shadow map(s). Positive values move split points away from the camera and negative values move them towards the camera. Intended to be used in conjunction with changes to 'split point uniform logarithmic ratio' to counteract side effects, but may cause additional, more serious side effects. Read the Parallel Split Shadow Maps paper by F Zhang et al before changing.
 split point bias = 0.0