Shader Effects¶
Shader effects change how a mesh draws without forking its shaders. A vertex offset moves its vertices, a coverage function removes part of its surface, and shader parameters feed both with values that belong to the mesh, the scene or a camera. The engine runs them in the color, depth and G-buffer passes alike, so shadows, SSAO and screen-space reflections agree with what is drawn. Shader parameters also work in forks of every shader type, as Custom Shaders explains.
The engine's wind and see-through are built this way, and so are three small examples it ships: a dissolve, a height cut, and grass pushed aside by a character.
How it fits together¶
| Piece | What it is | Set on |
|---|---|---|
| Vertex offset | One .glsl with vec3 getVertexOffset(vec3 localPosition, vec3 worldPosition) |
Mesh vertexOffsetShader |
| Coverage | One .glsl with float getCoverage(CoverageContext context) |
Mesh coverageShader |
| Object parameters | Values of one component, declared with #pragma param |
The component's shader uniforms |
| Scene parameters | Collection.name values the whole scene shares, declared with #pragma scene |
Scene properties, Scene::setShaderParameter |
| View parameters | Collection.name values of one camera, declared with #pragma view |
Camera properties, Camera::setShaderParameter |
A mesh takes one vertex offset and one coverage function. To combine several effects of the same kind, write one function that calls the helpers of each (see Writing your own). The vertex offset runs after skinning, morph targets and instancing and before the instance distance fade. The coverage runs at the start of the fragment stage, before any texture is sampled and before the material's alpha test.
Declaring parameters¶
Parameters are declared with #pragma lines. The GLSL compiler skips a pragma it does not
know, so an effect file stays plain GLSL:
#pragma param float strength = 0.5 [0, 2] "How far the top moves, in world units"
#pragma param vec4 tint = 1, 0.8, 0.6, 1 color
#pragma scene vec3 Wind.velocity "Air velocity in m/s"
#pragma view float SeeThrough.radius = 0 [0, 20]
The type is float, vec2, vec3, vec4, int, ivec2, ivec3 or ivec4. The
numbers after = are the default, and a single number fills a whole vector. Integer types
travel as floats and are exact up to 16777216. [min, max] is the range of the inspector field,
color shows a color picker, runtime marks a value that a script or the engine writes
(the inspector shows it read-only), and the quoted text is the tooltip.
The code reads each parameter by the name it was declared with:
| Declared as | Read in GLSL as |
|---|---|
#pragma param float strength |
params.strength |
#pragma scene vec3 Wind.velocity |
Wind.velocity |
#pragma view float SeeThrough.radius |
SeeThrough.radius |
The collection keeps unrelated values apart: Wind.speed and Water.speed are two
parameters. A collection is either a scene or a view one. The build stops with an error that
names the file and line when two declarations give a parameter different types, or use a
collection in both scopes, even when one is in the vertex file and the other in the
fragment file. The shader's Parameters section shows the same error before any build.
Collection and parameter names take letters, digits and underscores, and params and
Engine are not collection names.
Declarations are read from the shader file and every file it includes, whatever #if
surrounds them. A comment may follow one on its line. The shader builder packs the
declarations of each stage into one uniform block, u_vs_params or u_fs_params, with the
engine values the code reads. The mesh color pass appends them to its material block
instead, so effects and collections take no extra uniform block slots there. Changing a
value rewrites that block at the next draw. It never rebuilds a shader or reloads a
component.
Engine values¶
Two values need no declaration. A shader that reads them gets them:
| Value | Contents |
|---|---|
Engine.time |
Seconds since the scene started. The clock holds while the editor scene is stopped or paused, and while the game pauses, and starts over when Play mode stops, so each Play session begins like the exported game. For gameplay-driven time, set a parameter of your own from a script. |
Engine.resolution |
xy = width and height of the target the shader draws into (the camera's framebuffer, the fixed-resolution target, a shadow slot, a reflection probe face, or a post-process target), zw = 1 / width and 1 / height. |
Where values come from¶
An object parameter reads the component's shader uniform of the same name, then the value of the scene default shader when the component inherits it, then the declared default. A post-process pass keeps its own values.
A scene parameter reads the runtime value a script set, then the value saved with the scene, then the declared default.
A view parameter reads, for the camera a pass is drawn for:
- the runtime value of that camera, from
Camera::setShaderParameter; - the runtime value of the main view, from
Scene::setMainViewShaderParameter, while that camera renders the scene; - the value saved on its Camera component;
- the declared default.
Runtime values are never saved: stopping Play mode or loading the scene again brings back
the saved ones, and Wind.travel and the effect clock start over. Each scene keeps its own
values, and so does each copy of it that Play mode runs. Shadow maps are fitted to the
camera that renders the scene, so an effect sees that camera there. A reflection probe
capture has no camera and reads the declared defaults of view parameters.
Vertex offsets¶
It returns how far the vertex moves, in world units. localPosition is the vertex in the
mesh's own space after skinning, morph targets and instancing, and worldPosition is where
it lands before the move. Engine.time is the seconds since the scene started (see
Engine values).
The mesh's Max Offset (vertexOffsetMax) is the longest offset. Longer ones are clamped
to it, and culling widens the mesh bounds and each instance's sphere by it, so moved
geometry is not cut at the screen edge or out of a shadow cascade. At 0 nothing is clamped
and the bounds stay those of the mesh data. Lighting keeps the normals of the unmoved
surface, and terrain ignores vertex offsets.
Coverage¶
It returns how much of the fragment stays: 1 keeps it and 0 removes it. In between, opaque and alpha-tested surfaces keep a steady 4×4 dithered share of their pixels, and blended surfaces multiply their alpha instead. The coverage and the material's alpha test are separate tests that both have to pass.
CoverageContext field |
Meaning |
|---|---|
vec3 worldPosition |
The fragment in world space. |
vec2 uv |
The mesh's first UV set as stored, before sprite or instance texture rects; 0 when it has none. Every pass interpolates it for a mesh with coverage. |
vec3 eye |
Position of the camera the pass draws for. |
vec3 forward |
Its view direction, normalized. |
bool perspective |
False for an orthographic camera. |
vec2 pixel |
The fragment pixel counted from the corner of the view, the same in every pass, so the depth passes drop the pixels the color pass drops on any viewport offset or flipped target. |
The depth pre-pass and the SSR G-buffer cut what the color pass cuts, so SSAO, reflections
and depth based post-processing match it. Shadow maps keep the whole silhouette unless the
mesh's Cut Shadows (coverageShadows) is on: a see-through wall should still cast its
shadow, but a dissolving one should not. A skipped coverage still applies the material's
alpha mask to the shadow.
Coverage functions can use the shapes in includes/coverage_helpers.glsl, which every
coverage file sees:
| Helper | Returns |
|---|---|
coverageBelowHeight(worldPosition, height, softness) |
1 below the height, 0 above, with a dithered band of the given width. |
coverageNoise(position) |
A smooth value noise in [0, 1]. |
coverageViewOpening(worldPosition, eye, forward, perspective, target, radius, opacity, margin) |
The see-through opening: a cone from a perspective eye, a cylinder along an orthographic view. |
A file can suggest the shadow policy with #pragma coverage_shadows apply or keep. The
editor sets Cut Shadows from it when the file is picked.
The engine's effects¶
| File | Parameters | What it does |
|---|---|---|
offsets/wind.glsl |
windSway (0.3), windSwayHeight (0); scene Wind.velocity, Wind.travel |
Sways the mesh in the wind, with gusts that roll downwind. |
offsets/interaction.glsl |
pushStrength (0.5), pushHeight (1); scene Interaction.position, Interaction.radius (0) |
Bends the mesh away from a point. |
coverage/see_through.glsl |
view SeeThrough.target, radius (0), opacity (0.3), margin (0.5) |
Opens a view to a target behind the mesh. |
coverage/height_clip.glsl |
scene Clip.height (1000), Clip.softness (0) |
Cuts away everything above a height. |
coverage/dissolve.glsl |
dissolve (0), dissolveScale (4), dissolveEdge (0.05) |
Dissolves the mesh into world-space noise. |
Wind¶
windSway is the bend in 10 m/s of wind, in world units. With windSwayHeight above 0 the
bend grows as the square of the model height up to that value, so a plant modelled with its
origin at its base keeps its foot still. The engine adds the meters of air blown past to
Wind.travel each update, which moves the gusts at the wind's speed without a jump when it
changes. Set the mesh's Max Offset to about windSway × 2.5 for winds up to 15 m/s, or
windSway × 4 up to 20 m/s.
Terrain foliage layers keep their Wind Sway control: it runs this offset on the layer's instances, bending them up to their tips.
scene->setShaderParameter("Wind", "velocity", Vector3(5.0f, 0.0f, -2.0f));
grass.setVertexOffsetShader("offsets/wind.glsl");
grass.setShaderUniform("windSway", 0.3f);
grass.setShaderUniform("windSwayHeight", 0.5f);
grass.setVertexOffsetMax(0.8f);
scene:setShaderParameter("Wind", "velocity", Vector3(12, 0, 0)) -- a gale, until cleared
scene:clearShaderParameter("Wind", "velocity") -- back to the saved wind
See-through¶
The opening is a cone from the camera to a sphere of radius around the target, so it keeps
one size on screen, and a cylinder along the view for an orthographic camera. It is full in
its inner half and fades out in the outer half. opacity is what stays at the center. Only
what lies in front of the target opens, starting margin before it and full at twice that,
so the ground under a character stays whole. A radius of 0 turns it off.
The engine does not track the target: a script writes it each frame. The main view values go to whichever camera renders the scene, so a camera switch keeps the opening:
// in a C++ script deriving from Object, attached to the player
void PlayerReveal::onUpdate(){
Vector3 chest = getWorldPosition() + Vector3(0.0f, 0.9f, 0.0f);
scene->setMainViewShaderParameter("SeeThrough", "target", chest);
scene->setMainViewShaderParameter("SeeThrough", "radius", 2.5f);
scene->setMainViewShaderParameter("SeeThrough", "margin", 0.3f);
}
-- the same each frame from Lua, with player an Object handle
scene:setMainViewShaderParameter("SeeThrough", "target", player:getWorldPosition() + Vector3(0, 0.9, 0))
scene:setMainViewShaderParameter("SeeThrough", "radius", 2.5)
With two players on split cameras, give each camera its own target:
leftCamera:setShaderParameter("SeeThrough", "target", playerOne:getWorldPosition())
rightCamera:setShaderParameter("SeeThrough", "target", playerTwo:getWorldPosition())
Radius, opacity and margin can also be saved on the camera in the editor, under its Shader Parameters, leaving only the target to the script.
Dissolve, height cut and push¶
-- fade a defeated enemy out over a second, shadow included
enemy.coverageShader = "coverage/dissolve.glsl"
enemy.coverageShadows = true
enemy:setShaderUniform("dissolve", math.min(elapsed, 1.0))
-- hide the floors above the player in every building of the scene
scene:setShaderParameter("Clip", "height", player:getWorldPosition().y + 2.5)
-- grass bends away from the player
scene:setShaderParameter("Interaction", "position", player:getWorldPosition())
scene:setShaderParameter("Interaction", "radius", 1.5)
Writing your own¶
An effect file is a plain .glsl in the project. It finds its includes like a fork: first
in its own folder, then the project root, then the engine library. This one bobs a boat on
the water and sways its sail, reading a scene parameter of its own and the engine's wind:
// Bobs the mesh on the water, with the wind on top
#pragma param float bob = 0.05 [0, 1] "Height of the bobbing, in world units"
#pragma scene float Water.level "World height of the water surface"
#include "includes/wind.glsl"
vec3 getVertexOffset(vec3 localPosition, vec3 worldPosition){
float wave = sin(worldPosition.x * 3.0 + Engine.time * 2.0) * params.bob;
float nearWater = step(worldPosition.y, Water.level + 0.5);
return vec3(0.0, wave * nearWater, 0.0) + getWindSway(localPosition, worldPosition, 0.2, 1.0);
}
A coverage function the same way:
// Keeps only what is above the water
#pragma param float edge = 0.1 [0, 1] "Height of the dithered edge"
#pragma scene float Water.level
#pragma coverage_shadows apply
float getCoverage(CoverageContext context){
return smoothstep(Water.level - params.edge, Water.level, context.worldPosition.y);
}
To change an engine effect, copy it into the project (see below) and edit the copy.
In forks¶
A color or depth fork runs effect functions when it keeps the lines of the built-in shader
that include includes/vertex_offset.glsl and includes/coverage.glsl, the
loadShaderParameters() call at the top of main(), and in the color fork the
SHADER_PARAMS_FS_MEMBERS line of its material block. The build warns when a mesh has an
effect function its fork cannot run.
A fork can declare and read parameters in its own code too, after that call, and so can a fork of any other shader type:
#pragma scene float Weather.wetness = 0 [0, 1] "How wet surfaces look"
#pragma param vec4 wetTint = 0.6, 0.65, 0.7, 1 color
...
color.rgb = mix(color.rgb, color.rgb * params.wetTint.rgb, Weather.wetness);
Every fork that declares Weather.wetness reads the same scene value, so one script call
can wet the meshes, the water and a post-process pass together.
In the editor¶
The Shaders section of a Mesh component has a Vertex Offset row and a Coverage
row. Each row can create a file from a template, use one of the engine's effects (shown as
built-in), pick a project file, copy the built-in effect into the project to change it,
open the file, or remove it. A .glsl can also be dropped on the row. Max Offset shows
under a vertex offset and Cut Shadows under a coverage function.
Below the table, each fork and effect file of the component has its own Parameters
section with the fields its #pragma param lines declare, with their ranges, colors and tooltips. A
field nobody set shows the value inherited from the scene's default shader, else the declared
default, and the arrow next to a set field drops it. The section also lists the scene and view
parameters the file reads. Saving the file updates the fields. A forked default shader shows
its fields in the scene's Default Shaders, where the components using it inherit them, and
a post-process pass shows them under its header.
The scene properties list every scene parameter the scene's shaders declare under Shader Parameters, the wind among them once something sways, and save the values set there. A camera's properties list the view parameters the same way. Values nothing declares any more stay listed until their arrow removes them. Every edit is undoable.
Export¶
The effect functions are part of the shader name, written fork#vertexOffset#coverage,
so each combination compiles to its own variant and each pass gets the variant it needs.
Saving a scene records the variants its meshes use, and an export builds and ships those,
with any project effect files and the files they include. A composition that only appears at
runtime, such as a script giving a mesh a coverage function, goes in the export overrides
like any other variant:
mesh:Uv1,Puc,Nor@##coverage/dissolve.glsl
depth:Uv1@##coverage/dissolve.glsl
mesh:Uv1,Puc,Nor@shaders/myMesh#shaders/sway.glsl#coverage/see_through.glsl
The same specs work with doriax-editor export --shader. A mesh with a coverage function
and a UV set uses the Uv1 variants of the depth and G-buffer passes.