Connecting With Lua

Overview

Every shader that is marked as dynamic can be controlled through the Lua scripting system. Shaders can be disabled and enabled, and their uniforms can be controlled via scripts. For details, reference the API documentation here.

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.

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";
    version = "1.0";
    author = "Fargoth";
    passes = desaturate;
    dynamic = true;
}

Note

The dynamic flag here is very important, otherwise Lua will not be able to interact with this shader.

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.

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.

technique {
    description = "Desaturates scene";
    version = "1.0";
    author = "Fargoth";
    passes = desaturate;
    flags = hidden;
    dynamic = true;
}

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.

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.

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
    }
}