Write a post-processing shader
A post-processing shader changes the picture after the game’s sprites have been drawn. This page gives the starter game a warm tint, with one HLSL function and a few C++ lines to choose it. HLSL describes a pixel’s colour; the game’s rules, input and states stay in C++.
Before you start, build the project from Get Started. For the browser steps, also complete Build for the browser. The shader is compiled when you build the game, so editing it means rebuilding and restarting the game or refreshing its page. There is no shader hot reload.
Run the commands below in the x64 Native Tools Command Prompt, from your project’s folder:
cd /d C:\dev\mygameWrite and select the material
Section titled “Write and select the material”A material is the shader function together with the values your C++ code gives it.
-
Make a shader file.
Terminal window mkdir game\shadersnotepad game\shaders\warm_tint.hlslPaste this, save and close Notepad:
game\shaders\warm_tint.hlsl float4 material(MaterialInput input){const float4 picture = scene_point(input.uv);const float3 tint = material_value(0).rgb;return float4(picture.rgb * tint, picture.a);}The engine supplies
MaterialInput,scene_pointandmaterial_value; do not include the engine’s shader files yourself.input.uvruns from(0, 0)at the picture’s top-left corner to(1, 1)at its bottom-right.scene_pointreads the scene there, without smoothing. The function multiplies the picture’s red, green and blue by three numbers from your C++ code, leaving its alpha unchanged. -
Add the material to both builds. Open
game\CMakeLists.txt. In theif(EMSCRIPTEN)block, put this immediately before itsreturn():game\CMakeLists.txt, inside if(EMSCRIPTEN) labrador_add_material(MyGame warm_tintSOURCE shaders/warm_tint.hlsl)Add the same two lines at the end of the file for the Windows build. The browser returns before reaching that second copy, so each build adds the material once.
MyGameis the executable’s target name; use your game’s name if you renamed it.warm_tintis the material’s C++ name and the generated header’s file name. The build createsmaterials/warm_tint.hunder its own generated folder and adds that folder to the target’s include paths. You do not copy the header into your project. -
Register and select it. In
game\states\hello_state.cpp, add this include beside the other includes:#include "materials/warm_tint.h"At the start of
HelloState::init(), before its existing statements, add:renderer->add_material(labrador::warm_tint);renderer->set_post_material(tint_material);tint_values.values[0] = 1.0f;tint_values.values[1] = 0.75f;tint_values.values[2] = 0.5f;renderer->set_post_values(tint_material, tint_values);HelloState::init()runs after the application creates its renderer, before the first frame. Register and choose materials outside a frame, rather than indraw().add_materialcopies the source and returns a handle belonging to this renderer. Keep that handle if you want to change its values later. Register a material once; registration keeps it until the renderer is destroyed. This starter creates its greeting state once. A game that recreates a screen registers shared materials during application setup and hands their handles to the screens. Device or context restoration rebuilds the registered material automatically and does not call this state’sinit()again.The three numbers keep red as it is, keep three quarters of green and half of blue.
(1, 1, 1)leaves the colours unchanged. The greeting and its hint both receive the tint, because this shader processes the whole scene. -
Build, test and play on Windows. The normal Direct3D 11 preset uses the Windows SDK’s
fxc, already required for the starter’s own shaders:Terminal window cmake --preset x64-debugcmake --build --preset x64-debugctest --preset x64-debugstart "" out\build\x64-debug\game\MyGame.exeThe tint should be visible on the greeting. A shader syntax error stops the build and names the
.hlslfile and its line; fix that file and build again. The compiled shader is embedded in the executable, so there is no shader file to copy into a release folder.
Build the same shader for a browser
Section titled “Build the same shader for a browser”The HLSL file stays the same. For desktop GL and browser WebGL2, the build uses two host
tools: DirectX Shader Compiler (dxc) produces SPIR-V, and spirv-cross turns that into
GLSL for the selected renderer. They run on the computer doing the build; the player’s
browser runs neither tool.
Your game’s top-level vcpkg.json owns its dependencies. Add these two objects to its
dependencies array, leaving the existing entries and baseline in place:
{ "name": "directx-dxc", "host": true },{ "name": "spirv-cross", "host": true }Then run the browser commands from the prompt where emsdk_env.bat has run:
cmake --preset wasm-releasecmake --build --preset wasm-releasectest --preset wasm-releaseServe and open out\build\wasm-release\game\MyGame.html as
Build for the browser describes. dxc and spirv-cross are
build-time tools; adding them does not add a runtime library to your game. A starter that
writes no materials needs neither tool.
When building the engine repository’s own material tests instead of a consumer project,
enable its optional vcpkg feature with -DVCPKG_MANIFEST_FEATURES=materials at configure.
If you already have both tools, you can use them instead of adding the vcpkg dependencies.
The build checks the host tools vcpkg installed, then the Vulkan SDK’s Bin folder and
PATH. To choose exact executables, pass -DLABRADOR_MATERIAL_DXC=C:/path/to/dxc.exe and
-DLABRADOR_SPIRV_CROSS=C:/path/to/spirv-cross.exe to the configure command. The selected
dxc must support -spirv; the Windows SDK’s compiler with the same name may not.
The values and the picture
Section titled “The values and the picture”PostValues::values holds 32 floats: eight groups of four. The shader reads the first four
with material_value(0), the next four with material_value(1), through
material_value(7). Values start at zero. The renderer refuses a NaN or infinite value.
Change the selected material’s values with set_post_values(handle, values) from the
thread that owns the frame; you do not recompile a shader to change its tint. An unselected,
unresolved or foreign handle is refused. To animate a look, pass elapsed time in one of
your parameter groups; the frame’s reserved timing fields do not supply a clock.
The frame also supplies:
| Name | Meaning |
|---|---|
input.uv |
Normalised top-down output position. |
input.output_pixel |
Output position in pixels, with the top-left at (0, 0). |
output_size.xy, output_size.zw |
Output width and height, and their reciprocals. |
scene_size.xy, scene_size.zw |
Input width and height, and their reciprocals. |
scene_point(uv) |
Read the scene with point sampling. |
scene_linear(uv) |
Read the scene with linear smoothing. |
Sample through the helpers and leave register declarations, vertex functions, entry points and texture orientation to the engine. The return value replaces the processed pixel; there is no extra sprite blend at this stage. Scene colours have premultiplied alpha, so keep the result premultiplied when changing alpha. This page’s factors stay between zero and one and preserve the original alpha.
If a shader includes a file you own, name that dependency in the build so editing it also rebuilds the material:
labrador_add_material(MyGame warm_tint SOURCE shaders/warm_tint.hlsl DEPENDS shaders/common.hlsli)Switch it off or draw a flat overlay
Section titled “Switch it off or draw a flat overlay”Use renderer->set_post_effects({}); outside a frame to return to the ordinary scene.
Calling set_post_effects with a built-in effect also replaces the custom material. Its
handle remains valid and its values remain available if you select it again.
For a HUD that stays unchanged, call begin_overlay() inside the frame before declaring
and drawing the HUD’s view. That view and the views after it draw over the processed scene.
Allow room for the additional view in ApplicationOptions::view_capacity; the starter’s
default code sets that capacity to one. The
renderer contract describes view and
frame ordering.
One custom material is one full-screen pass. It is for the scene’s presentation; it does not change the shader of an individual sprite. Game render targets, a custom multi-pass chain and bloom are separate work from this authoring path.
Documentation for Labrador v0.4.0. Built from Labrador f525bc6 of 2026-11-17.