Shader compilation
Offline shader preprocessing tool of Jazz² Resurrection.
ShaderCompiler ("Sources/Utilities/ShaderCompiler", dependency-free C++17) reads annotated .shader files from "Sources/Shaders", expands their variants, reflects the GLSL declarations offline and emits self-contained C++ headers with sources and reflection data, so the runtime needs no glGetActiveUniform introspection. It also performs every lowering the non-GL backends need: HLSL, Vulkan GLSL + SPIR-V, Metal, ESSL 100, Cg, GLSL-to-C++ for the software renderer, and a fixed-function transpiler for backends without fragment shaders (PVR, GX, PICA, GU, GS, RDP, LegacyGL).
A .shader file describes an effect on two tiers:
- Shader backends (software renderer included, via ShaderCompiler::
GlslToCpp) get the GLSL of void vertex()/void fragment(), lowered per variant and per backend. - Fixed-function backends get a
void fixed_function()block — hardware passes over the sprite quad, transpiled to C++. Design:"Docs/FixedFunctionShaderDesign.md". Runtime contract:"Sources/nCine/Graphics/RHI/FixedFunctionPass.h".
All outputs are committed under "Sources/Shaders/Generated". The game's build never runs the tool, so regenerate after every shader edit, see Regenerating the committed headers.
Which artifact serves which platform
One per-shader header serves GL, ES2, D3D11 and Vulkan. The other tiers get aggregate headers. The committed set must only be produced by `--generate-all`, which runs every mode below.
| Backend | Artifact | Produced by |
|---|---|---|
| OpenGL 3.3, OpenGL|ES 3.0, WebGL 2.0 | VsSource / FsSource of the per-shader header (#version and platform defines injected at runtime) | primary mode |
OpenGL|ES 2.0 profile (NCINE_RHI_GL_PROFILE=ES2) | VsSource100 / FsSource100 — ESSL 100 lowering in the same header | primary mode |
| Direct3D 11 | HlslVsSource / HlslFsSource — Shader Model 4/5 HLSL in the same header | primary mode |
| Vulkan | VkVsSpirv / VkFsSpirv — SPIR-V compiled offline by glslangValidator | primary mode + glslang |
| Metal (macOS) | MslVsSource / MslFsSource — compiled on the device at load time (no MSL compiler outside Xcode) | primary mode |
| Software renderer | "SwGeneratedShaders.h" — transpiled C++ fragment functions | --emit-sw-generated |
| Dreamcast (PVR) | "PvrGeneratedEffects.h" | --emit-fixed-function pvr |
| Wii / GameCube (GX) | "GxGeneratedEffects.h" | --emit-fixed-function gx |
| Nintendo 3DS (PICA) | "PicaGeneratedEffects.h" | --emit-fixed-function pica |
| PlayStation Portable (GU) | "GuGeneratedEffects.h" | --emit-fixed-function gu |
| PlayStation 2 (GS) | "GsGeneratedEffects.h" | --emit-fixed-function gs |
| Nintendo 64 (RDP) | "RdpGeneratedEffects.h" | --emit-fixed-function rdp |
| Legacy OpenGL 1.x (MorphOS' TinyGL) | "LegacyGlGeneratedEffects.h" | --emit-fixed-function legacygl |
| PlayStation Vita (GXM) | "CgGeneratedShaders.h" — Cg sources compiled on the console | --emit-cg |
| PlayStation 3 (RSX) | "RsxGeneratedShaders.h" — NV40 microcode compiled offline from the same Cg | --emit-rsx + cgcomp |
| Wii U (GX2) | "Gx2GeneratedShaders.h" — R700 shaders compiled offline from the OpenGL GLSL | --emit-gx2 + CafeGLSL |
The *GeneratedEffects.h headers hold transpiled fixed_function effects. Unavailable lowerings are null (a construct outside the HLSL/ESSL 100 subset, or no glslang for SPIR-V). A program without a fixed_function block is skipped on those backends with a one-time warning. A shader the software transpiler declines is absent from "SwGeneratedShaders.h".
Runtime-compiled .shader files (ShaderCompiler::CompileRuntimeProgram) get only GLSL, reflection and, under ES2, the ESSL 100 lowering — so they are unavailable on the fixed-function backends.
Building the tool
The desktop CMake build adds the tool as a utility target in the Utilities folder. It is skipped when cross-compiling (Emscripten, Nintendo Switch, Vita, UWP, Wii, GameCube, Wii U, Dreamcast), since it runs on the build machine. Standalone build:
cmake -S Sources/Utilities/ShaderCompiler -B build-shadercompiler cmake --build build-shadercompiler
Command-line reference
ShaderCompiler <input.shader> -o <output.h> [-n <namespace>] [--glslang <path>] ShaderCompiler <input.shader> --check | --essl100-check | --hlsl | --cg | --vulkan | --msl ShaderCompiler --generate-all [--shaders-dir <dir>] [--out-dir <dir>] [--check] [--no-dxbc] [--glslang <path>] ShaderCompiler --emit-types <output.h> ShaderCompiler --emit-sw-generated <output.h> <input.shader ...> ShaderCompiler --emit-cg <output.h> <input.shader ...> ShaderCompiler --emit-fixed-function <pvr|gx|pica|gu|gs|rdp|legacygl> <output.h> <input.shader ...> ShaderCompiler --hlsl-check <input.shader ...> ShaderCompiler --spirv-check [--glslang <path>] <input.shader ...>
The standalone modes (--generate-all, --emit-*, --hlsl-check, --spirv-check) are recognized only as the first argument. Elsewhere they are an unknown option. Everything else is the primary per-shader mode, which takes exactly one input file.
| Mode or option | Meaning |
|---|---|
-o <output.h> | Generated C++ header. Required unless a dump switch is given |
-n <namespace> | Namespace for the program data (default ShaderArtifacts), :: nesting allowed. Empty, a leading digit or a character outside [A-Za-z0-9_:] is an error |
--glslang <path> | glslangValidator for the embedded SPIR-V, otherwise found via VULKAN_SDK\Bin, VULKAN_SDK\Bin32 and PATH |
--check | Reflection dump of every program and variant (structs with std140 offsets, uniforms, blocks with BaseSize/InstanceStride, texture units, attribute locations). The test suite compares it against "tests/expected" |
--essl100-check, --target essl100 | ESSL 100 (OpenGL|ES 2.0) transform of every variant. essl100 is the only --target value |
--hlsl | HLSL (Shader Model 4/5) transform |
--cg | Cg transform in the PS Vita's sceGxm dialect, see below |
--vulkan | Vulkan GLSL ("#version 450") transform, needs no glslang |
--msl | Metal Shading Language transform |
--generate-all | Regenerates every committed artifact, see below. --shaders-dir / --out-dir override the auto-detected directories, --check compares instead of writing, --no-dxbc and --glslang are forwarded |
--emit-types <output.h> | Writes only the shared reflection-types header |
--emit-sw-generated <output.h> <in ...> | Software-renderer header: every variant's fragment stage as C++ |
--emit-cg <output.h> <in ...> | PS Vita header: every variant as Cg |
--emit-rsx <output.h> <in ...> | PlayStation 3 header: every variant as Cg compiled by cgcomp (path via --cgcomp). The only path building with NO_DYNAMIC_BRANCHING |
--emit-gx2 <output.h> <in ...> | Wii U header: every variant's OpenGL GLSL compiled in uniform-block mode by CafeGLSL's glslcompiler (path via --cafeglsl, else $CAFEGLSL/bin, else PATH). Works around what Cemu 2.6 cannot translate: vertex-index divisions become float, ceil() becomes -floor(-x), and burst parameter exports are split |
--emit-fixed-function <pvr\|gx\|pica\|gu\|gs\|rdp\|legacygl> <output.h> <in ...> | Per-backend effect header: the applicable fixed_function block of every variant |
--hlsl-check <in ...> | Compiles every variant's HLSL via D3DCompile (vs_5_0 / ps_5_0), printing a pass/fail table (Windows only, d3dcompiler_47.dll) |
--spirv-check [--glslang <path>] <in ...> | Compiles every variant's Vulkan GLSL to SPIR-V via glslangValidator, printing a pass/fail table |
--help, -h, /? | Prints usage to stderr and exits successfully |
The dump switches (--check, --essl100-check, --hlsl, --cg, --vulkan, --msl) print to stdout and write nothing. When several are combined, the first of --essl100-check, --hlsl, --cg, --vulkan, --msl, --check wins and the rest are silently ignored. --glslang is ignored by all of them.
Diagnostics go to stderr as "<file>:<line>: error: <message>" (parser, reflection, emitters), "<file>: error: <message>" (failed #include or unreadable input) or a bare "error: <message>" (command line and I/O). Exit code: 0 success, 1 input or emission failure, 2 usage error.
The aggregate modes
--emit-types: the types live in the fixedShaderCompilernamespace, independent of-n, so headers with different data namespaces can be included together.--emit-sw-generatedand--emit-cgnever fail on unsupported input: the shader or variant is declined, omitted and listed with its reason in the summary (the Vita backend then reports it unavailable at load time).--emit-sw-generatedis the only path building withSOFTWARE_RENDERER.- Cg is a separate header because the per-shader headers can only be rewritten on Windows (DXBC, SPIR-V). A Cg run touches nothing else.
--emit-fixed-functiontreats an invalid block as a hard error that fails the whole run.
The .shader input format
A .shader file is GLSL globals plus void vertex() / void fragment() entry points, annotated with keyword directives — top-level statements at brace depth 0, terminated by ;. Comments follow GLSL rules and never reach the emitted sources — they are stripped right after parsing, along with the lines only a comment was on, and diagnostics still point at the lines of the original file. Do not write #version — the engine injects the version header ("#version 330", "#version 300 es", "#version 100") and platform defines at runtime. The full in-tree specification, including std140 layout rules and the --check dump format, is "Sources/Utilities/ShaderCompiler/README.md".
Top-level directives
| Directive | Meaning |
|---|---|
program <Name>; | Required, exactly once, before shader_type, variant, batched, precision and the entry points — write it first. A C++/GLSL identifier naming the emitted Program (and keying the console tables) |
shader_type canvas_item; shader_type custom; | Optional, default custom. canvas_item opts into the sprite template |
variant <NAME>; | May repeat. Output holds the unnamed base variant (Variants[0]) plus one entry per declaration, compiled with <NAME> defined — its conditionals are resolved in the variant's emitted sources. No cross-products on their own: variant <A> + <B>; declares one, named A_B, with the defines of both (each part declared as a variant before it) |
render_mode <mode>[, <mode>]; | Any of blend_mix, blend_add, blend_sub, blend_mul, blend_premul_alpha, unshaded, OR-ed into RenderModes. May repeat |
precision mediump; precision highp; | Optional (default mediump), only these spellings: precision of the auto-emitted "#ifdef GL_ES" fragment prologue (precision highp float; is plain GLSL). highp is guarded by "GL_FRAGMENT_PRECISION_HIGH", falling back to mediump on ES 2.0 devices without it |
batched <Name>; | canvas_item only — also emits the batched twin (InstancesBlock + 6-vertex corner formula), sharing the fragment stage, variants and fixed_function blocks |
#include "relative/path" | Replaced textually before parsing, relative to the including file, up to depth 8. Diagnostic line numbers refer to the expanded stream |
void fixed_function([<target>[, <target>...]]) { ... } | Fixed-function implementation, see below. Never part of the GLSL stages |
Declarations shared by both modes
| Element | Meaning |
|---|---|
varying [flat] [precision] <type> <name>; | Becomes out in the vertex stage and in in the fragment stage, qualifiers preserved. May be wrapped in a global-scope SOFTWARE_RENDERER or LOW_POWER_GPU conditional, see below |
attribute [layout(location = N)] <declaration>; | Vertex attribute — an in global in the vertex stage only. A leading layout(...) is kept and honored by reflection |
uniform <type> <name> : <hint>[, <hint>]; | texture_unit(N) (0–31) is the only explicit texture-unit assignment. The name must match a sampler in some variant, and two hints for one uniform are an error. source_color, hint_range(...), filter_nearest, filter_linear, repeat_enable, repeat_disable are parsed and dropped. Anything else is an error |
| everything else | Uniforms, std140 blocks, consts, structs and helper functions are shared by both stages of every variant |
Custom mode (the default)
No template, no substitutions. Both entry points are required. The body of void vertex() becomes the vertex main() verbatim and writes gl_Position itself. In void fragment(), COLOR is the output variable itself ("out vec4 COLOR;"), undefined until written, so an early return; is safe. fragColor anywhere in a .shader file is a parse error — write COLOR.
Canvas mode (shader_type canvas_item)
Uses the engine's sprite template (InstanceBlock / InstancesBlock, the vTexCoords / vColor / vPaletteOffset varyings) and enables batched.
void vertex()is optional. The generatedmain()computes the built-ins as locals, splices the body, then runs the standard epilogue, soreturn;in it is a parse error. It can be given to the low-power emissions alone via a global-scope#if LOW_POWER_GPU, see Variants, conditionals and includes.void fragment()is required and enters withCOLORholding the instance colour.
| Built-in | Vertex stage | Fragment stage |
|---|---|---|
VERTEX | sprite-local position in pixels, writable | — |
UV | texture coordinates, writable | substituted with vTexCoords |
COLOR | instance colour, writable | enters as the instance colour, and is the output |
PALETTE_OFFSET | palette row of the instance, writable | substituted with vPaletteOffset |
TEXTURE | — | substituted with uTexture |
TEXTUREwithout auTexturedeclaration auto-declares"uniform sampler2D uTexture;"on unit 0.NORMAL,SCREEN_UV,SCREEN_PIXEL_SIZE,TIME,POINT_COORDandVERTEXare errors invoid fragment()and shared globals.- Built-ins are locals of the generated
main(), so redeclaring one is a GLSL error. - Without
void vertex()the vertex stage is the template alone, without shared globals.
Variants, conditionals and includes
Reflection runs per variant through a mini preprocessor implementing the object-like C subset (#define / #undef, #if / #ifdef / #ifndef / #elif / #else / #endif with integer constant expressions). It only feeds reflection: emitted sources keep the original text verbatim, with the stage, backend and variant conditionals resolved and "#line 1" at the top (after a #define <NAME> (1) only for a variant macro the text still names outside a conditional). GL_ES is never predefined (reflection uses the desktop GL view). BATCH_SIZE evaluates as 1 in #if but stays symbolic as an array size.
These macros are resolved by the tool and never survive into an emitted source:
| Macro | Defined for | Use |
|---|---|---|
VERTEX_STAGE / FRAGMENT_STAGE | the respective stage, at assembly time | which stage sees a shared global (optional "#else"). Rarely needed: attributes and varyings have keywords, unused functions are eliminated per stage |
SOFTWARE_RENDERER | --emit-sw-generated only | a cheaper CPU path that leaves every other backend unchanged ("TexturedBackground.shader") |
NO_DYNAMIC_BRANCHING | --emit-rsx only | gate every dynamically branching fragment block on it — NV40 IF/LOOP/BRK miscompiles (the branch body overwrites live registers) |
LOW_POWER_GPU | --emit-cg (PS Vita) and the ESSL 100 lowering | a cheaper approximation of an expensive path, not a capability limit. In a per-shader header only _Vs100/_Fs100 are built with it. The engine's RHI_LOW_POWER_GPU (RhiFwd.h) mirrors which view a binary compiled |
the variant names | each variant's own sources, after the backend macros | the code of one variant: in its GLSL an #if <NAME> block is plain code, in the others' it is gone, and so is a helper function only it calls. A combined variant defines all of its parts |
- They work in
#ifdef/#ifndefand#if/#elifexpressions (#if !SOFTWARE_RENDERER && !NO_DYNAMIC_BRANCHING): each family folds the top-level&&terms naming only its macros and leaves the rest. Defining or undefining them is an error. Variant names resolve per variant the same way, also infixed_functionblocks, and a term that names a flag no pass owns as well is decided whenever that flag can no longer change it ("#if KEYED || SLOPE"is plain code inKEYED). - Around global-scope
varyingdeclarations,SOFTWARE_RENDERER/LOW_POWER_GPUgive those emissions their own varyings. Such a conditional may hold onlyvaryingdeclarations, no nested directives — except that itsLOW_POWER_GPUside may also hold acanvas_itemshader'svertex()("Blur.shader"). See"tests/SwVarying.shader","tests/LowPowerVarying.shader","tests/LowPowerCanvasVertex.shader". - When a low-power vertex stage replaces derivatives with matrix data (
"TileMapMeshBlur.shader"), take only the magnitude: the projection's y sign differs between backends (GL flips it while a render target is bound).
Automatic cleanup passes
Run per stage, in this order:
- Stage conditionals are resolved.
- Unused functions are removed, to a fixpoint rooted at
main(). - A varying the fragment stage never reads is removed with its dead vertex-stage stores, or demoted to a plain global when a store has side effects.
- Unused uniforms, blocks, defines and structs are removed from a stage only when the same declaration survives in the other stage, so reflection stays byte-identical.
- The same rule applies per backend view: a loose uniform read only by branches that view drops (
SOFTWARE_RENDERER/NO_DYNAMIC_BRANCHING/LOW_POWER_GPU) leaves that stage. - Literal-only subexpressions inside function bodies are constant-folded with exact GLSL semantics. Global declarations are never touched.
Reflection and generated headers
Reflection runs per stage and variant over global declarations (structs, loose uniforms, "layout (std140)" blocks with computed offsets and strides, sampler2D / sampler3D / samplerCube bindings, vertex attributes) and the stages are merged GL-style. An array sized by BATCH_SIZE records its element stride as the block's InstanceStride with a sentinel count. The runtime computes the batch size as maxUniformBlockSize / InstanceStride (the batched sprite instance's 112-byte stride gives 585 = 65536 / 112).
Each header is self-contained (<cstdint> / <cstddef> plus the types header) and carries per variant:
- Stage sources as raw string literals —
<Program>_Vs/_Fs, or<Program>_<VARIANT>_Vs/_Fs— each starting with"#line 1", the variant's conditionals resolved - The ESSL 100 and HLSL lowerings (
_Vs100/_Fs100,_HlslVs/_HlslFs), and SPIR-V words when glslang was available - Reflection as
constexprarrays (Uniform,BlockMember,UniformBlock,TextureBinding,Attribute), tied together byProgramVariantandProgram
The types live in "Generated/ShaderCompilerTypes.h" in the fixed ShaderCompiler namespace, data in the -n namespace, so engine code can include the types header alone.
Fixed-function blocks
On backends without fragment shaders an effect is a list of passes over the sprite quad, stated by a fixed_function block next to the GLSL it approximates. The whole block of "WhiteMask.shader":
void fixed_function() { pass p; p.color = vec4(0.0, 0.0, 0.0, COLOR.a); p.offset_color = COLOR.rgb; submit_quad(p); }
Anything outside the grammar is a hard error with file and line that fails the whole --generate-all run. Design and per-console capabilities: "Docs/FixedFunctionShaderDesign.md". Emitter: ShaderCompiler::
Block selection and what gets emitted
A block's parentheses hold its target list:
| Spelling | Serves |
|---|---|
void fixed_function() | every backend without a more specific block, restricted to the portable core |
void fixed_function(pvr) | Dreamcast |
void fixed_function(gx) | Wii/GameCube |
void fixed_function(pica) | Nintendo 3DS |
void fixed_function(gu) | PlayStation Portable |
void fixed_function(gs) | PlayStation 2 |
void fixed_function(rdp) | Nintendo 64 |
void fixed_function(legacygl) | OpenGL 1.x (MorphOS' TinyGL, or desktop GL in a compatibility context) |
void fixed_function(pvr, gu, gs) | every listed target from one body (any subset, any order, whitespace free) |
- A block naming a backend (alone or in a list) wins over the generic block regardless of order.
- Each target belongs to exactly one block per file. Claiming it twice is an error.
- Use a list only when the code is literally identical. Capabilities are checked against the intersection of the listed targets.
- A program with no applicable block is skipped on that backend at runtime.
Each variant's applicable block becomes a "void <Program>[_<VARIANT>]_Effect(EffectContext&)" function, listed in a FixedFunctionGeneratedEffects[] table of
{ program, variant, usesOffsetColor, requirements, intrinsic, &function }
entries keyed by the (program, variant) identity from ShaderProgram::SetProgramIdentity(). An entry has a function or an intrinsic, never both. The including device file supplies EffectContext through a using alias before the include.
usesOffsetColor— whether a reachablep.offset_color = ...exists (the PVR enables specular per program).requirements—FixedFunctionRequirementsbits for the context facilities used:NeedsTexelStep(texel_size()/has_texel_size()),NeedsUniforms(has_uniform()/uniform_vec2/vec4()),NeedsStripBuilder(strip_*()/submit_strip[_shaded]()),NeedsQuadAxes(quad_origin()/quad_axis_x/y()).
Both are computed from the block selected for that backend. Byte-identical bodies are emitted once, with a from <file>:<block> line and a // Shared by: list.
Pipeline bindings
A block whose sole statement is pipeline <name>; binds the program to a backend pipeline stage consuming an engine data structure. The table entry carries a FixedFunctionIntrinsic instead of a function. Anything else in such a block is an error.
pipeline name | FixedFunctionIntrinsic | Stage | Declared by |
|---|---|---|---|
tile_map_mesh | TileMapMesh | a whole tile layer as one indexed triangle-list mesh (8-float TileMap::AppendTileQuad contract, corners addressed through RenderResources::GetQuadIndices(), resolved on the CPU, PVR scissor-clips) | TileMapMesh.shader, TileMapMeshPalette.shader |
lighting_combine | LightingCombine | viewport compositor — the direct-tier CPU-lightmap lighting hook | Combine.shader, CombineWithWater.shader, CombineWithWaterLow.shader |
line_strip_mesh | LineStripMesh | vertex-fed textured line strip of the weapon wheel (PVR expands to thin quads, GX/GU draw native lines) | DefaultMeshSprite.shader |
Geometry-synthesized effects (transition iris, warped background) are ordinary blocks on the strip builder, not intrinsics.
Passes and their fields
pass p; declares a FixedFunctionPass with engine defaults (plain modulated sprite, material blending). No initializer, one statement per pass. Fields are write-only and take only plain =.
| Field | Type | Meaning |
|---|---|---|
p.color | vec4 | per-vertex colour of the pass |
p.offset_color | vec3 | post-texture additive term. Writing it enables it and sets usesOffsetColor. GX uses a silhouette pass, while GU expands it into modulate + additive silhouette (same result, one draw when color.rgb is zero), so generic blocks using it work everywhere |
p.screen_offset | vec2 | displacement of the whole quad in its own coordinate space |
p.luma_gain | float | LUMA_RAMP luminance amplification before saturation, ignored by other presets |
p.texture_repeat | bool literal | fixed_function(rdp) blocks only: hardware wrap along S, so coordinates outside [0, 1] repeat instead of the strip being cut. Only adds wrapping. GE and PICA200 take wrap from the sampler state |
p.blend | enum | blend override for this pass |
p.tev | enum | combiner preset — portable intent. The PVR always modulates, the GE knows only MODULATE and SILHOUETTE |
p.blend | BlendMode | Hardware |
|---|---|---|
MATERIAL | Material | whatever the material configured (default) |
ADD | Additive | additive glow and split-multiplier passes. GX ONE + ONE, PVR SRCALPHA + ONE (scaled by pass alpha) |
OPAQUE | Opaque | ONE + ZERO |
ALPHA | Alpha | SRCALPHA + INVSRCALPHA, independent of the material |
p.tev | TevPreset | Meaning and availability |
|---|---|---|
MODULATE | Modulate | texture * vertex colour (default) |
SILHOUETTE | Silhouette | vertex colour where the texture has alpha (masks, shadows, glows) |
MODULATE_X2 | ModulateX2 | modulate with x2 output scale. Rejected in any block reaching gu or gs (no output scale). RDP via its second combiner cycle, LegacyGL via GL_RGB_SCALE |
MODULATE_X4 | ModulateX4 | modulate with x4 output scale. Rejected for gu, gs and rdp (would need a third combiner cycle) |
TINT_MIX | TintMix | mix(texel, colour, alpha), opaque result. Needs a lerping combiner: only blocks whose targets are all among gx, pica, rdp, legacygl |
LUMA_RAMP | LumaRamp | silhouette toned per texel: color.rgb at luminance 0, offset_color at 1, luma_gain amplifying the Rec.601 luminance. Coverage texel alpha * color.a. Only in a block targeting gx alone |
These checks reject the generic block too. The PVR silently ignores p.tev (an output scale has no effect there). Without a combiner, express a boost as extra additive passes (Colorized.shader).
Built-ins
The portable core is valid in every block. The extended vocabulary is only valid in blocks that name their targets (single or list), never in the generic block.
| Built-in | Type | Meaning | Core? |
|---|---|---|---|
COLOR | vec4 | instance colour of the draw, the shader's COLOR input. Read-only, cannot be redeclared | yes |
texel_size() | vec2 | one texel's displacement in the quad's coordinate space, converted per backend | yes |
has_texel_size() | bool | whether that step is derivable (a zero texRect has none). Guard texel_size() with it | yes |
submit_quad(p) | statement | submits one pass over the current instance's quad | yes |
quad_origin() | vec2 | pre-clip raster position of the sprite's (0,0) corner | no |
quad_axis_x(), quad_axis_y() | vec2 | pre-clip raster displacements of the sprite's local axes. Use these for synthesized geometry so clipping cannot distort it | no |
quad_tex_rect() | vec4 | the instance's texRect (scale and bias of U, then of V) - which part of what the shader draws the quad shows | no |
has_uniform(uName) | bool | whether the program resolved that uniform (unresolved ones load zeros) | no |
uniform_vec2(uName), uniform_vec4(uName) | vec2, vec4 | resolved uniform by name via ResolveUniform. The argument is an identifier, not a string | no |
strip_position(i, <vec2>) | statement | strip vertex position | no |
strip_uv(i, <vec2>) | statement | strip vertex UV in the shader's texture space | no |
strip_color(i, <vec4>) | statement | strip per-vertex colour | no |
strip_q(i, <float>) | statement | strip vertex q: the UVs of the strip are interpolated in perspective (u * q, v * q and q across the screen, divided per pixel), the UVs given stay the true ones. Only for the strip submitted next; ignored by the GE | no |
strip_clip(<vec4>) | statement | cuts every strip submitted after it to the rectangle (min x, min y, max x, max y in raster space), in the generated code - a rectangle stays one, the cut edges carry their attributes in perspective where the strip has a q | no |
submit_strip(p, count) | statement | submits the first count strip vertices textured, with the pass's flat colour | no |
submit_strip_shaded(p, count) | statement | submits them with per-vertex colours, untextured unless the preset consumes the texel (TINT_MIX) | no |
Submission and strip calls cannot appear in expressions. Strip capacity is 8 vertices on the PVR and 16 elsewhere. A literal index outside 0..capacity-1 or count outside 3..capacity is a hard error (at runtime it would be silently dropped or clamped). Computed values are unchecked. Prefer fewer, longer strips — on the GE each is a draw call.
Capability rules for a target list
A block naming several backends is validated against the intersection of their capabilities, whichever backend is being generated.
| Rule | On a target list |
|---|---|
| Extended vocabulary (strip builder, quad axes, uniforms) | allowed. Only the generic block is held to the portable core |
TINT_MIX | only when every target is among gx, pica, rdp, legacygl, so void fixed_function(gx, gu) is rejected |
LUMA_RAMP | only in a block targeting gx alone (the RDP combiner has no dot product) |
MODULATE_X2 / MODULATE_X4 | rejected as soon as gu or gs is listed, even while generating the PVR header. rdp rejects MODULATE_X4 only, and gx/legacygl/pica have both |
| Strip-builder capacity | the minimum of the targets: void fixed_function(pvr, gx) gets 8, so a literal index 8 is an error |
Each diagnostic names the target that rejects the feature. The fix is splitting the list into separate blocks.
Statements and expressions
Types: float, int, bool, vec2, vec3, vec4 and the opaque pass.
- Statements — local declarations (initializers, comma-separated declarators),
passdeclarations,=,+=,-=,*=,/=, prefix/postfix++/--on anint,if/else, C-styleforwith anintcounter and aboolcondition, braced blocks with their own scope, and the submission/strip calls. Nothing else stands alone as a statement. - Operators —
+ - * /on numeric operands (scalar broadcasts over a vector, mismatched widths rejected),%onintonly,< > <= >=on numeric scalars,==/!=on numeric scalars orbools,&& || ^^onbools, unary-on numeric and!onbool, and ternary?:with aboolcondition and same-typed branches. - Functions —
min/maxon(float, float),(int, int),(vecN, vecN)or(vecN, float).clampandmixin the matching 3-argument shapes,ceil/flooronfloator vector,abs/sqrt/sin/cosonfloat,float(x)/int(x), andvec2/vec3/vec4constructors as a scalar splat or any mix whose components sum to the width. - Swizzles — single components in
xyzw,rgbaorstpq, plus.xy,.zw,.xyz,.yzwfor reading. Only a single component can be assigned.
Rejected, each with its own error: while, do, switch, return, break, continue, discard, arrays and indexing, unary ~, %=, &=, |=, ^=, <<=, >>=, assignments inside expressions, initializing or assigning a pass as a value, redeclaring COLOR or ctx, and blend/tev preset names as variables.
Worked examples
| Shader | Shows |
|---|---|
"WhiteMask.shader" | the minimal shape: one silhouette pass coloured by the offset colour |
PartialWhiteMask.shader | split by capability: offset-colour lift in (pvr, gu, gs), x2 output scale on gx |
"Outline.shader" | a nested for over eight neighbours, each an offset silhouette guarded by has_texel_size() |
"Colorized.shader" | multiplier as up to three additive passes in (pvr, gu, gs), two in rdp, one MODULATE_X4 pass on gx |
"FrozenMask.shader" | constant ice tone where there is no per-texel arithmetic, but LUMA_RAMP with luma_gain = 2.6 on gx |
"Transition.shader" | iris fan from quad_origin() / quad_axis_x/y() and shaded strips. pvr gets its own block because the 10-vertex strip exceeds its 8 |
Include/CombineWaterFixedFunction.inc | shared (gx, pica, gu, gs, legacygl) block plus separate rdp (no light rays) and pvr (8-vertex strips) blocks |
"Include/TexturedBackgroundWarp.inc" shows the idiom for specializing a shared include: the including block defines macros before the #include.
WARP_TINT_IN_VERTEX_COLORfolds the horizon tint into each band viaTINT_MIX. Without it the tint is a second alpha-blended pass after all bands.WARP_TEXTURE_REPEATdraws each band as one strip with unwrapped coordinates on hardware that repeats the 256x256 render target (the PVR cannot).WARP_TEXTURE_REPEAT_IN_PASSalso setsp.texture_repeatfor the RDP.
The blocks: (pvr, gs) bare, gu repeat, rdp repeat in pass + tint, pica repeat + tint and (gx, legacygl) tint.
Regenerating the committed headers
--generate-all enumerates every *.shader in "Sources/Shaders" and writes into "Sources/Shaders/Generated", in this order:
"ShaderCompilerTypes.h"— shared reflection types (--emit-types)- One header per
.shaderfile —Default*.shaderintonCine::ShadersGen, everything else intoJazz2::ShadersGen "ShadersGen.h"— umbrella header plus the per-namespaceAllPrograms[]arrays (a file with abatchedtwin contributes two entries)"SwGeneratedShaders.h"(--emit-sw-generated)"CgGeneratedShaders.h"(--emit-cg)"PvrGeneratedEffects.h","GxGeneratedEffects.h","GuGeneratedEffects.h","GsGeneratedEffects.h","RdpGeneratedEffects.h","LegacyGlGeneratedEffects.h","PicaGeneratedEffects.h"(--emit-fixed-function)"RsxGeneratedShaders.h"(--emit-rsx), only on a host withcgcomp"Gx2GeneratedShaders.h"(--emit-gx2), only on a host with CafeGLSL
After editing a .shader file:
Sources\Utilities\ShaderCompiler\x64\Release\ShaderCompiler.exe --generate-all git add Sources\Shaders Sources\Shaders\Generated
The shader directory is found by walking up from the executable, then from the working directory, to a "Sources/Shaders". Output goes to its "Generated" subdirectory. Never regenerate artifacts piecemeal — it leaves the committed set inconsistent. GenerateAll.ps1 is a thin wrapper forwarding -Glslang, -NoDxbc and -Check:
cd Sources\Utilities\ShaderCompiler
powershell .\GenerateAll.ps1SPIR-V is embedded when glslangValidator is found: --glslang <path>, then VULKAN_SDK\Bin and VULKAN_SDK\Bin32, then PATH, then a Visual Studio-bundled copy, then a repo-local build-tree copy. Without it a warning is printed and the SPIR-V fields are null — the headers build, but the Vulkan backend does not.
--generate-all --check is the staleness guard: it generates into a temporary directory, byte-compares with the committed headers (missing and extra files count), reports stale files and exits non-zero without touching the tree. Without glslang or with --no-dxbc, every header with SPIR-V or DXBC reports stale. Run it after editing a shader or in CI — the build never detects stale headers.
Tests in "Sources/Utilities/ShaderCompiler/tests": --check dumps in "tests/expected", must-fail inputs in "tests/errors", ESSL 100 fixtures in "tests/essl100". tests/RunTests.ps1 runs them all.
Editor support (Visual Studio Code)
"Sources/Utilities/VSCodeExtension" is a plain-JavaScript extension (no build step) for .shader and .inc files. Its diagnostics come from ShaderCompiler <file> --check, so they match the compiler exactly. It also provides highlighting, context-aware completion, hovers, an outline, #include navigation, go-to-definition, snippets and transform previews.
Installing
Symlink the in-tree copy (so it tracks the repository), then restart Visual Studio Code (or Developer: Reload Window):
# Linux / macOS ln -sfn "$PWD/Sources/Utilities/VSCodeExtension" ~/.vscode/extensions/death-shader
rem Windows, from an elevated prompt (a directory junction needs no elevation on recent builds) mklink /D "%USERPROFILE%\.vscode\extensions\death-shader" "%CD%\Sources\Utilities\VSCodeExtension"
To develop it, open the folder and press F5 (".vscode/launch.json" opens the repository root). npx @vscode/vsce package builds a .vsix (only that needs Node).
How it finds the tool
First hit wins:
- The
deathShader.compilerPathsetting — absolute, or relative to the workspace folder. "Sources/Utilities/ShaderCompiler/<x64|ARM64EC|Win32>/<Release|Debug>/", then any CMake tree at the repository root namedbuild*orcmake-build*, then"out/build/<preset>/".ShaderCompileronPATH.
The status bar shows the executable in use or warns when none was found. Without one only the built-in checks work.
Highlighting and completion
Constructs the language rejects are highlighted as errors: fragColor, #version, unsupported canvas built-ins, unknown render modes or uniform hints, and stage macros in #if defined(...) / #elif / #define / #undef. Completion depends on the cursor:
| Cursor position | Completion offers |
|---|---|
| Brace depth 0 | directives, entry points, #include, types, names declared in the file |
After shader_type, render_mode or precision | only that directive's values |
After the : of a uniform | only the seven uniform hints |
Inside void fixed_function(...) parentheses | only pvr, gx, pica, gu, gs, rdp, legacygl |
Inside a fixed_function body | the DSL statements, calls, pass fields and values, facilities, maths subset |
Inside vertex() or fragment() | GLSL built-ins, mode-appropriate canvas built-ins, the file's declarations |
Inside #include "..." | sibling .inc / .shader files |
Diagnostics
Two layers, both on by default:
- The compiler —
ShaderCompiler <file> --check. All three stderr shapes from the command-line reference are parsed. - Built-in checks needing no executable: missing or duplicate
program, missingvoid fragment()(orvoid vertex()in custom mode), a directive beforeprogram,batchedwithoutshader_type canvas_item,#version,fragColor, an illegal stage-macro form,return;in a canvasvertex(), an unsupported canvas built-in. SetdeathShader.validate.builtinCheckstofalseto leave diagnostics to the compiler.
Structural checks stand down in files with #include (as in "LightingMesh.shader") and in .inc fragments. Since the compiler reports include-expanded line numbers, the extension notes the expanded line in such files. Validation runs on open and save, or while typing with onType. A dirty buffer is then written to a short-lived ".vscode-death-shader-tmp." copy, next to the original when it has #include lines, else in the OS temp directory.
Commands and settings
| Command | Runs |
|---|---|
| Death™ Shader: Show Reflection Dump | --check |
| Death™ Shader: Show HLSL Transform | --hlsl |
| Death™ Shader: Show Vulkan GLSL Transform | --vulkan |
| Death™ Shader: Show Cg Transform | --cg |
| Death™ Shader: Show ESSL 100 Transform | --essl100-check |
| Show Resolved ShaderCompiler Path, Validate Current File | — |
| Setting | Default | Meaning |
|---|---|---|
deathShader.compilerPath | "" | explicit executable path, empty auto-detects |
deathShader.validate.enable | true | report diagnostics at all |
deathShader.validate.run | onSave | onSave or onType |
deathShader.validate.delay | 400 | onType debounce in milliseconds |
deathShader.validate.builtinChecks | true | the executable-free checks |
The extension is disabled in untrusted workspaces, since it executes a binary from the workspace.
Keeping it in step with the tool
When this page gains a directive, render_mode, pass field or context facility, add it to src/language.js (and to "syntaxes/deathshader.tmLanguage.json" if it needs its own colour). The dependency-free tests assert the closed sets against the parser:
node test/run-tests.js && node test/run-provider-tests.js
The Cg dialect (PS Vita and PlayStation 3)
Both consoles get Cg from the same emitter, but from different views: the Vita's with LOW_POWER_GPU, the PS3's with NO_DYNAMIC_BRANCHING (see Variants, conditionals and includes).
- PS Vita — there is no offline GXP compiler (only the console's
libshacccg.suprx), so"CgGeneratedShaders.h"carries Cg source per program variant, compiled at load time through vitaShaRK. - PlayStation 3 — the console has no shader compiler, so the Cg is compiled to microcode offline, see below.
Cg comes from ShaderCompiler::
- Both entry points are named
main, notVSMain/PSMain. - Semantics are
POSITION(clip position),WPOS(fragment position) andCOLOR(output), notSV_Position/SV_Target. - No
cbuffer: std140 block members become top-level uniforms. Samplers aresampler2D/sampler3Dwith the GXMTEXUNIT<n>semantic, read withtex2D()/tex2Dlod(). - No vertex-ID or instance-ID input: the ESSL 100
VertexIdRewriteturnsgl_VertexIDquad synthesis into reads of theaQuadCorner/aInstanceIndexattributes. A stage still using either built-in is rejected. BATCH_SIZEis baked in as a plain#define, and the backend rewrites the number when the runtime picks a different batch size.- A
mix()of two vectors by a scalar casts the weight,lerp(a, b, ((float3)(t))), because the console'sSceShaccCgfindslerp(float3, float3, float)ambiguous fortex2D()results (Vita3K does not). HLSL keeps the plain call.
Compiling that Cg for the PlayStation 3
--emit-rsx emits Cg like --emit-cg and then compiles it:
- It compiles the plain view —
NO_DYNAMIC_BRANCHINGdefined,LOW_POWER_GPUnot. Low-power paths never reach the RSX, and editing only them leaves"RsxGeneratedShaders.h"unchanged. BATCH_SIZEis capped to the batch the backend's corner stream covers, since instance arrays live in vertex-program constant registers rather than a 64 KB uniform buffer as on the Vita.- Each stage is compiled by
cgcomp(PSL1GHT) with thevp40/fp40profiles, found via--cgcomp, then$PS3DEV/bin, thenPATH. "Unable to load Cg" means NVIDIA'slibCg.so(Cg Toolkit) is not on the library path.
The header is a byte-array table looked up by (program, variant), plus the built-in present shader written directly as Cg in "Sources/Shaders/Rsx/". A stage the profiles reject is reported and left out, and that program fails at load time. The console build never invokes cgcomp. See Shaders are compiled offline for the invocation.
Platform notes
- OpenGL|ES 2.0 (
NCINE_RHI_GL_PROFILE=ES2,"#version 100") has no UBOs orgl_VertexID, so the ESSL 100 lowering turns std140 blocks into loose uniforms or a uniform struct array and uses theaQuadCorner/aInstanceIndexattributes. - Direct3D 11 —
VSMain/PSMain, std140 blocks as cbuffers, separateTexture2D+SamplerState,mul()matrix algebra. - Vulkan — pipelines from the embedded SPIR-V, descriptor-set layout from the reflection.
- Fixed-function consoles include their effect header from the device file under
WITH_RHI_PVR/WITH_RHI_GX/WITH_RHI_GU/WITH_RHI_GS/WITH_RHI_RDP. - PS Vita (
WITH_RHI_GXM) compiles Cg source on the console, while PlayStation 3 (WITH_RHI_RSX) loads precompiled microcode, see above. - Wii U (
WITH_RHI_GX2) loads R700 shaders compiled offline from the OpenGL GLSL by CafeGLSL (--emit-gx2), so the console build needs no shader compiler, see Nintendo Wii U.
Console content is fully preprocessed (see AssetPacker), so runtime-compiled shaders are desktop-only. See Building for consoles for those backends.
Pitfalls
- Never edit
"Sources/Shaders/Generated"by hand (console headers included). The next regeneration overwrites it. - A layout change of
"ShaderCompilerTypes.h"invalidates every generated header — one regeneration commit, guarded by--check. - A missing console effect means a missing block, not a failure — read the generation summary.
--emit-fixed-functionnever reflects GLSL and--checknever validates blocks, so each can pass while the other fails.- Misspelled directives are not diagnosed: unknown top-level keywords pass into the GLSL (
render_modee blend_mix;fails in the GLSL compiler). Text after the;of avarying,attributeorrender_modeis silently discarded. - Function-like macros are never expanded by the reflection preprocessor. Only one
BATCH_SIZEarray per block, as its last member. Struct-typed loose uniforms, sampler arrays, multi-dimensional arrays and array vertex attributes are rejected.