Shader uniform type mismatch handling in Love2D

Question

Shader uniform type mismatch handling in Love2D
The goal is to diagnose intermittent rendering artifacts that appear when a uniform is bound with a Lua value of an incompatible type. For example, setting a GLSL float uniform with a Lua string or passing a table with fewer elements than required for a vector uniform.
Constraints include the fact that Love2D’s love.graphics.setShader API does not document explicit type checking. On some desktop OpenGL drivers the binding silently succeeds, producing no console output, while on WebGL or mobile GL ES the same call may generate a warning, an error, or no observable effect. Additionally, if the uniform is not referenced in the shader, the engine logs a warning only at compile time, further obscuring the issue.
Unresolved behavior: does Love2D guarantee consistent error reporting across platforms when a uniform type mismatch occurs? How can a developer reliably detect and handle such mismatches to avoid silent failures?
Specific questions:

What is the documented behavior of love.graphics.setShader when the Lua value type does not match the declared GLSL uniform type?
Under what circumstances does Love2D emit warnings or errors for these mismatches on desktop, WebGL, and mobile builds?
What best‑practice patterns can be employed to enforce type safety for shader uniforms across all supported platforms?

Tasadduq Burney · Answer

Shader uniform type mismatch handling in Love2D
Love2D’s shader:send (used internally by love.graphics.setShader) does not perform runtime type checking against the GLSL uniform declaration. It only does implicit conversion: Lua numbers become floats, Lua tables become vectors or matrices by element count. If the Lua value’s type or size does not match the uniform, the call is forwarded to the underlying OpenGL/WebGL/GLES driver, which may:

silently accept the data (producing undefined values such as zero or garbage),
generate a GL error that Love2D does not surface as a Lua error, or
emit a console warning in WebGL/GLES validation layers.

Because error reporting is driver‑ and backend‑dependent, there is no guaranteed warning or error on desktop OpenGL, while WebGL (via love.js) and mobile GLES builds are more likely to show a warning in the browser/device console.
Confirmed facts (from Love2D source and documentation):

shader:getUniform(name) returns the declared GLSL type ("float", "vec3", "mat4", etc.) and component count.
Unused uniforms trigger a compile‑time warning only when the shader is first created (love.graphics.newShader); this warning is not repeated on later send calls.
Love2D does not add stricter validation in versions 11.x or 12.x.

Recommended steps for cross‑platform type safety:

After creating the shader, query the uniform’s expected signature:
local uType, uSize = shader:getUniform('myUniform')
-- uType is a string like "float", "vec3", "mat4"
-- uSize is the number of components (1 for float/mat1, 3 for vec3, 16 for mat4)

Coerce the Lua value to match that signature. A small helper can do the conversion and assert on mismatch:
local function safeSend(shader, name, value)
    local typ, size = shader:getUniform(name)
    if typ == nil then
        error('Uniform not found: ' .. name)
    end
    if typ == 'float' then
        if type(value) ~= 'number' then
            error(string.format('Uniform %s expects a number, got %s', name, type(value)))
        end
        shader:send(name, value)
    elseif typ:match('^vec%d+$') then
        local n = tonumber(typ:match('vec(%d+)'))
        if type(value) ~= 'table' or #value ~= n then
            error(string.format('Uniform %s expects %d numbers, got %s', name, n, table.concat(value, ', ')))
        end
        shader:send(name, unpack(value))
    elseif typ == 'mat4' then
        if type(value) ~= 'table' or #value ~= 16 then
            error(string.format('Uniform %s expects 16 numbers (column‑major), got %s', name, table.concat(value, ', ')))
        end
        shader:send(name, unpack(value))
    else
        error('Unsupported uniform type: ' .. typ)
    end
end

Use safeSend wherever you would call shader:send. This runs the same validation on desktop, WebGL, and mobile because the check is performed in Lua before the GL call.

If you need to know whether a particular platform is emitting GL errors, you can check love.graphics.getRendererInfo() to distinguish OpenGL, OpenGL ES, or WebGL backends, but the helper above eliminates reliance on such diagnostics.

Shader uniform type mismatch handling in Love2D

Shader uniform type mismatch handling in Love2D

1 answer

Shader uniform type mismatch handling in Love2D

Your perspective belongs here.

0 question comments