updates to omwfx documentation

docs/source/reference/postprocessing/index.rst

@@ -8,4 +8,5 @@ OpenMW Post Processing
     :maxdepth: 2
 
     overview
-    omwfx
+    omwfx
+    lua

docs/source/reference/postprocessing/lua.rst

@@ -0,0 +1,137 @@
+####################
+Connecting With Lua
+####################
+
+Overview
+########
+
+Every shader can be controlled through the Lua scripting system. While shaders can be disabled and enabled,
+shader uniforms can also be controlled. For details reference the API documentation, found :doc:`here<../lua-scripting/openmw_postprocessing>`.
+
+Toggling Shaders With a Keybind
+###############################
+
+In this example, we use the desaturation shader created in the previous section and bind the ``x`` key to toggle it on and off.
+It is assumed the shader has the filename ``desaturate.omwfx`` in this example.
+
+.. code-block:: none
+
+    uniform_float uDesaturationFactor {
+        default = 0.5;
+        min = 0.0;
+        max = 1.0;
+        step = 0.05;
+        description = "Desaturation factor. A value of 1.0 is full grayscale.";
+    }
+
+    fragment desaturate {
+        omw_In vec2 omw_TexCoord;
+
+        void main()
+        {
+            // fetch scene texture from last shader
+            vec4 scene = omw_GetLastShader(omw_TexCoord);
+
+            // desaturate RGB component
+            const vec3 luminance = vec3(0.299, 0.587, 0.144);
+            float gray = dot(luminance, scene.rgb);
+
+            omw_FragColor = vec4(mix(scene.rgb, vec3(gray), uDesaturationFactor), scene.a);
+        }
+    }
+
+    technique {
+        description = "Desaturates scene";
+        passes = desaturate;
+        version = "1.0";
+        author = "Fargoth";
+        passes = desaturate;
+    }
+
+
+Next, a script that is attached to the player is needed. The shader is loaded first, then toggled on and off in response to key presses.
+Below is a working example to illustrate this.
+
+.. code-block:: Lua
+
+    local input = require('openmw.input')
+    local postprocessing = require('openmw.postprocessing')
+
+    local shader = postprocessing.load('desaturate')
+
+    return {
+        engineHandlers = {
+            onKeyPress = function(key)
+                if key.code == input.KEY.X then
+                    if shader:isEnabled() then
+                        shader:disable()
+                    else
+                        shader:enable()
+                    end
+                end
+            end
+        }
+    }
+
+Hiding Shader From the HUD
+##########################
+
+If the HUD is opened (default with ``F2``) you will notice it lists all available shaders. If you want your shader to be completely
+hidden in this HUD, this can done by adding the ``hidden`` flag to the main technique block.
+
+.. code-block:: none
+
+    technique {
+        description = "Desaturates scene";
+        passes = desaturate;
+        version = "1.0";
+        author = "Fargoth";
+        passes = desaturate;
+        flags = hidden;
+    }
+
+This flag is usually used when the shader is associated with something special, like special weather, spell, or alcohol effects.
+
+Controlling Uniforms
+####################
+
+By default, any uniform you defined will not be exposed to Lua, you must set the ``static`` flag to ``false`` in every uniform block for which you want exposed.
+For example, to set the ``uDesaturationFactor`` uniform from a Lua script, we must define it as follows.
+
+.. code-block:: none
+
+    uniform_float uDesaturationFactor {
+        default = 0.5;
+        min = 0.0;
+        max = 1.0;
+        step = 0.05;
+        description = "Desaturation factor. A value of 1.0 is full grayscale.";
+        static = false;
+    }
+
+In some player Lua script, this uniform can then be freely set. When a uniform is set to ``static`` it will no longer show up in the HUD.
+Here, instead of disabling and enabling the shader we set the factor to ``0`` or ``1``, respectively.
+
+.. code-block:: Lua
+
+    local input = require('openmw.input')
+    local postprocessing = require('openmw.postprocessing')
+
+    local shader = postprocessing.load('desaturate')
+    local factor = 0
+
+    return {
+        engineHandlers = {
+            onKeyPress = function(key)
+                if key.code == input.KEY.X then
+                    if factor == 0 then
+                        factor = 1
+                    else
+                        factor = 0
+                    end
+
+                    shader:setFloat('uDesaturationFactor', factor)
+                end
+            end
+        }
+    }

docs/source/reference/postprocessing/omwfx.rst

@@ -350,6 +350,10 @@ OpenMW currently supports ``1D``, ``2D``, and ``3D`` texture samplers, cubemaps
 | sampler_3d  |
 +-------------+
 
+.. warning::
+    OpenMW vertically flips all DDS textures when loading them, with the exception of ``3D`` textures.
+
+
 The properites for a ``sampler_*`` block are as following.
 The only required property for a texture is its ``source``.