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.

BackendArtifactProduced by
OpenGL 3.3, OpenGL|ES 3.0, WebGL 2.0VsSource / 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 headerprimary mode
Direct3D 11HlslVsSource / HlslFsSource — Shader Model 4/5 HLSL in the same headerprimary mode
VulkanVkVsSpirv / VkFsSpirv — SPIR-V compiled offline by glslangValidatorprimary 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::RuntimeProgram, 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 optionMeaning
-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
--checkReflection 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 essl100ESSL 100 (OpenGL|ES 2.0) transform of every variant. essl100 is the only --target value
--hlslHLSL (Shader Model 4/5) transform
--cgCg transform in the PS Vita's sceGxm dialect, see below
--vulkanVulkan GLSL ("#version 450") transform, needs no glslang
--mslMetal Shading Language transform
--generate-allRegenerates 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 fixed ShaderCompiler namespace, independent of -n, so headers with different data namespaces can be included together.
  • --emit-sw-generated and --emit-cg never 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-generated is the only path building with SOFTWARE_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-function treats 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

DirectiveMeaning
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

ElementMeaning
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 elseUniforms, 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 generated main() computes the built-ins as locals, splices the body, then runs the standard epilogue, so return; 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 with COLOR holding the instance colour.
Built-inVertex stageFragment stage
VERTEXsprite-local position in pixels, writable—
UVtexture coordinates, writablesubstituted with vTexCoords
COLORinstance colour, writableenters as the instance colour, and is the output
PALETTE_OFFSETpalette row of the instance, writablesubstituted with vPaletteOffset
TEXTURE—substituted with uTexture
  • TEXTURE without a uTexture declaration auto-declares "uniform sampler2D uTexture;" on unit 0.
  • NORMAL, SCREEN_UV, SCREEN_PIXEL_SIZE, TIME, POINT_COORD and VERTEX are errors in void 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:

MacroDefined forUse
VERTEX_STAGE / FRAGMENT_STAGEthe respective stage, at assembly timewhich 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 onlya cheaper CPU path that leaves every other backend unchanged ("TexturedBackground.shader")
NO_DYNAMIC_BRANCHING--emit-rsx onlygate 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 loweringa 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 nameseach variant's own sources, after the backend macrosthe 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 / #ifndef and #if / #elif expressions (#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 in fixed_function blocks, 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 in KEYED).
  • Around global-scope varying declarations, SOFTWARE_RENDERER / LOW_POWER_GPU give those emissions their own varyings. Such a conditional may hold only varying declarations, no nested directives — except that its LOW_POWER_GPU side may also hold a canvas_item shader's vertex() ("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:

  1. Stage conditionals are resolved.
  2. Unused functions are removed, to a fixpoint rooted at main().
  3. 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.
  4. 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.
  5. 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.
  6. 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 constexpr arrays (Uniform, BlockMember, UniformBlock, TextureBinding, Attribute), tied together by ProgramVariant and Program

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::ConsoleFixedFunction.

Block selection and what gets emitted

A block's parentheses hold its target list:

SpellingServes
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 reachable p.offset_color = ... exists (the PVR enables specular per program).
  • requirements — FixedFunctionRequirements bits 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 nameFixedFunctionIntrinsicStageDeclared by
tile_map_meshTileMapMesha 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_combineLightingCombineviewport compositor — the direct-tier CPU-lightmap lighting hookCombine.shader, CombineWithWater.shader, CombineWithWaterLow.shader
line_strip_meshLineStripMeshvertex-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 =.

FieldTypeMeaning
p.colorvec4per-vertex colour of the pass
p.offset_colorvec3post-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_offsetvec2displacement of the whole quad in its own coordinate space
p.luma_gainfloatLUMA_RAMP luminance amplification before saturation, ignored by other presets
p.texture_repeatbool literalfixed_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.blendenumblend override for this pass
p.tevenumcombiner preset — portable intent. The PVR always modulates, the GE knows only MODULATE and SILHOUETTE
p.blendBlendModeHardware
MATERIALMaterialwhatever the material configured (default)
ADDAdditiveadditive glow and split-multiplier passes. GX ONE + ONE, PVR SRCALPHA + ONE (scaled by pass alpha)
OPAQUEOpaqueONE + ZERO
ALPHAAlphaSRCALPHA + INVSRCALPHA, independent of the material
p.tevTevPresetMeaning and availability
MODULATEModulatetexture * vertex colour (default)
SILHOUETTESilhouettevertex colour where the texture has alpha (masks, shadows, glows)
MODULATE_X2ModulateX2modulate 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_X4ModulateX4modulate with x4 output scale. Rejected for gu, gs and rdp (would need a third combiner cycle)
TINT_MIXTintMixmix(texel, colour, alpha), opaque result. Needs a lerping combiner: only blocks whose targets are all among gx, pica, rdp, legacygl
LUMA_RAMPLumaRampsilhouette 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-inTypeMeaningCore?
COLORvec4instance colour of the draw, the shader's COLOR input. Read-only, cannot be redeclaredyes
texel_size()vec2one texel's displacement in the quad's coordinate space, converted per backendyes
has_texel_size()boolwhether that step is derivable (a zero texRect has none). Guard texel_size() with ityes
submit_quad(p)statementsubmits one pass over the current instance's quadyes
quad_origin()vec2pre-clip raster position of the sprite's (0,0) cornerno
quad_axis_x(), quad_axis_y()vec2pre-clip raster displacements of the sprite's local axes. Use these for synthesized geometry so clipping cannot distort itno
quad_tex_rect()vec4the instance's texRect (scale and bias of U, then of V) - which part of what the shader draws the quad showsno
has_uniform(uName)boolwhether the program resolved that uniform (unresolved ones load zeros)no
uniform_vec2(uName), uniform_vec4(uName)vec2, vec4resolved uniform by name via ResolveUniform. The argument is an identifier, not a stringno
strip_position(i, <vec2>)statementstrip vertex positionno
strip_uv(i, <vec2>)statementstrip vertex UV in the shader's texture spaceno
strip_color(i, <vec4>)statementstrip per-vertex colourno
strip_q(i, <float>)statementstrip 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 GEno
strip_clip(<vec4>)statementcuts 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 qno
submit_strip(p, count)statementsubmits the first count strip vertices textured, with the pass's flat colourno
submit_strip_shaded(p, count)statementsubmits 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.

RuleOn a target list
Extended vocabulary (strip builder, quad axes, uniforms)allowed. Only the generic block is held to the portable core
TINT_MIXonly when every target is among gx, pica, rdp, legacygl, so void fixed_function(gx, gu) is rejected
LUMA_RAMPonly in a block targeting gx alone (the RDP combiner has no dot product)
MODULATE_X2 / MODULATE_X4rejected 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 capacitythe 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), pass declarations, =, +=, -=, *=, /=, prefix/postfix ++ / -- on an int, if / else, C-style for with an int counter and a bool condition, 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), % on int only, < > <= >= on numeric scalars, == / != on numeric scalars or bools, && || ^^ on bools, unary - on numeric and ! on bool, and ternary ?: with a bool condition and same-typed branches.
  • Functions — min / max on (float, float), (int, int), (vecN, vecN) or (vecN, float). clamp and mix in the matching 3-argument shapes, ceil / floor on float or vector, abs / sqrt / sin / cos on float, float(x) / int(x), and vec2 / vec3 / vec4 constructors as a scalar splat or any mix whose components sum to the width.
  • Swizzles — single components in xyzw, rgba or stpq, plus .xy, .zw, .xyz, .yzw for 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

ShaderShows
"WhiteMask.shader"the minimal shape: one silhouette pass coloured by the offset colour
PartialWhiteMask.shadersplit 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.incshared (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_COLOR folds the horizon tint into each band via TINT_MIX. Without it the tint is a second alpha-blended pass after all bands.
  • WARP_TEXTURE_REPEAT draws each band as one strip with unwrapped coordinates on hardware that repeats the 256x256 render target (the PVR cannot). WARP_TEXTURE_REPEAT_IN_PASS also sets p.texture_repeat for 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:

  1. "ShaderCompilerTypes.h" — shared reflection types (--emit-types)
  2. One header per .shader file — Default*.shader into nCine::ShadersGen, everything else into Jazz2::ShadersGen
  3. "ShadersGen.h" — umbrella header plus the per-namespace AllPrograms[] arrays (a file with a batched twin contributes two entries)
  4. "SwGeneratedShaders.h" (--emit-sw-generated)
  5. "CgGeneratedShaders.h" (--emit-cg)
  6. "PvrGeneratedEffects.h", "GxGeneratedEffects.h", "GuGeneratedEffects.h", "GsGeneratedEffects.h", "RdpGeneratedEffects.h", "LegacyGlGeneratedEffects.h", "PicaGeneratedEffects.h" (--emit-fixed-function)
  7. "RsxGeneratedShaders.h" (--emit-rsx), only on a host with cgcomp
  8. "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.ps1

SPIR-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:

  1. The deathShader.compilerPath setting — absolute, or relative to the workspace folder.
  2. "Sources/Utilities/ShaderCompiler/<x64|ARM64EC|Win32>/<Release|Debug>/", then any CMake tree at the repository root named build* or cmake-build*, then "out/build/<preset>/".
  3. ShaderCompiler on PATH.

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 positionCompletion offers
Brace depth 0directives, entry points, #include, types, names declared in the file
After shader_type, render_mode or precisiononly that directive's values
After the : of a uniformonly the seven uniform hints
Inside void fixed_function(...) parenthesesonly pvr, gx, pica, gu, gs, rdp, legacygl
Inside a fixed_function bodythe 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:

  1. The compiler — ShaderCompiler <file> --check. All three stderr shapes from the command-line reference are parsed.
  2. Built-in checks needing no executable: missing or duplicate program, missing void fragment() (or void vertex() in custom mode), a directive before program, batched without shader_type canvas_item, #version, fragColor, an illegal stage-macro form, return; in a canvas vertex(), an unsupported canvas built-in. Set deathShader.validate.builtinChecks to false to 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

CommandRuns
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—
SettingDefaultMeaning
deathShader.compilerPath""explicit executable path, empty auto-detects
deathShader.validate.enabletruereport diagnostics at all
deathShader.validate.runonSaveonSave or onType
deathShader.validate.delay400onType debounce in milliseconds
deathShader.validate.builtinCheckstruethe 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::HlslEmitter with Dialect::Cg. Differences from HLSL:

  • Both entry points are named main, not VSMain / PSMain.
  • Semantics are POSITION (clip position), WPOS (fragment position) and COLOR (output), not SV_Position / SV_Target.
  • No cbuffer: std140 block members become top-level uniforms. Samplers are sampler2D / sampler3D with the GXM TEXUNIT<n> semantic, read with tex2D() / tex2Dlod().
  • No vertex-ID or instance-ID input: the ESSL 100 VertexIdRewrite turns gl_VertexID quad synthesis into reads of the aQuadCorner / aInstanceIndex attributes. A stage still using either built-in is rejected.
  • BATCH_SIZE is 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's SceShaccCg finds lerp(float3, float3, float) ambiguous for tex2D() 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:

  1. It compiles the plain view — NO_DYNAMIC_BRANCHING defined, LOW_POWER_GPU not. Low-power paths never reach the RSX, and editing only them leaves "RsxGeneratedShaders.h" unchanged.
  2. BATCH_SIZE is 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.
  3. Each stage is compiled by cgcomp (PSL1GHT) with the vp40 / fp40 profiles, found via --cgcomp, then $PS3DEV/bin, then PATH. "Unable to load Cg" means NVIDIA's libCg.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 or gl_VertexID, so the ESSL 100 lowering turns std140 blocks into loose uniforms or a uniform struct array and uses the aQuadCorner / aInstanceIndex attributes.
  • Direct3D 11 — VSMain / PSMain, std140 blocks as cbuffers, separate Texture2D + 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-function never reflects GLSL and --check never 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 a varying, attribute or render_mode is silently discarded.
  • Function-like macros are never expanded by the reflection preprocessor. Only one BATCH_SIZE array per block, as its last member. Struct-typed loose uniforms, sampler arrays, multi-dimensional arrays and array vertex attributes are rejected.