Chapter 17 Shaders: Four Answers to XNA’s .fx

The constructor takes its two source arguments by reference but immediately copies both into the effect. It is therefore safe to construct from temporary or subsequently modified strings; the program is compiled from the construction-time copies, not from caller-owned character storage. If the device has a renderer, construction asks it once for an IEffectRenderer. A returned but invalid renderer does not make the common constructor throw: it writes that renderer’s GetCompileError() text to standard error and leaves IsEffectValid() false. A null renderer and a failed compile are intentionally collapsed to the same public boolean, and there is no public ShaderEffect accessor for the diagnostic. Renderers may of course fail before returning from their own factory, so this is not a promise that every renderer-specific setup failure becomes a boolean.

Treat that validity result as a precondition, not a delayed exception. Effect::Apply() does reject an already disposed effect, but its common code calls OnApply() and then makes the effect current. ShaderEffect::OnApply() merely writes a debug message when its renderer is absent or invalid; it does not bind a fallback program. Calling Apply() on an invalid custom effect can therefore still replace the device’s current effect pointer. There is no automatic retry or source recompilation in this object; construct a new effect after correcting source or changing the renderer circumstances.

The uniform and texture calls are submission calls, not an XNA-style parameter collection. ShaderEffect keeps no uniform dictionary, no sampler table, and no texture ownership: each SetUniformXxx() forwards its name and scalar or caller buffer immediately to the renderer if one exists, while each SetTexture() immediately forwards the address of the texture’s renderer. It performs no common-layer check of a uniform name, sampler-unit range, array count, or matrix/array pointer. EasyGL uploads/binds at that call; some other renderers copy into a fixed staging block; inherited interface defaults can do nothing; and Headless records a raw texture-renderer pointer for tracing. Thus a successful call is not a portable guarantee of a binding, and it never gives the effect ownership of the texture. Keep every texture alive by its normal owner and set it again whenever the target renderer/path requires rebinding. The standalone setters also do not inspect IsDisposed; unlike Apply(), they continue to forward while the renderer object remains alive, so disposal must be treated as terminal by the caller.

Clone() is equally source-only. It returns an owning raw Effect pointer whose concrete object is constructed afresh as new ShaderEffect(*device_, vertSrc_, fragSrc_): it recompiles an independent renderer program and restores the three IEffectMatrices values to identity. It does not copy submitted uniforms, texture binds, name/tag metadata, or a compiled-program handle; its base effect begins with its own empty parameter collection and one Default/P0 technique. Use an owning smart pointer at the call site and reapply all desired state to the clone. The existing ShaderEffectTests test establishes distinct object identity, copied source strings, and equal validity on the default test device. It does not compile against a renderer or cover matrix/state transfer, texture lifetime, invalid-apply behavior, or a renderer reset.

Adapted from easygl_shadereffect_texturecube_test.cpp, a minimal cube-map-sampling fragment shader and its construction:

Check IsEffectValid() before drawing. Unlike a stock effect selected from CNA’s shipped programs or FNA3D’s retained stock bytecode, ShaderEffect compiles game-supplied source at runtime. A syntax error or unsupported GLSL feature therefore produces an invalid effect that must be reported before submission.

ShaderEffect’s constructor takes one pair of source strings for every renderer; there is no HLSL-specific overload. On a Direct3D renderer the same call shape compiles HLSL instead of GLSL. The following color-inversion example is adapted from the pinned D3D9 test and uses its SM2/SM3 Macros.fxh texture macros, which the vendored stock SpriteEffect.fx also uses:

vpSize is worth pausing on, because it is doing real work rather than being decorative: a custom vertex shader supplied this way has no other way to map SpriteBatch’s pixel-space Position input into normalized device coordinates, so this uniform (set automatically by the renderer, not by game code) is what makes the sprite land at the correct screen location at all — the same real test this example is adapted from separately verifies that sampling outside the sprite’s destination rectangle stays the clear color, proving this NDC math is genuinely correct rather than happening to paint something plausible-looking over the whole screen. One small, harmless documentation inaccuracy worth knowing if you go reading ShaderEffect’s own header next: its class-level doc comment describes it as a “GLSL-source-based effect.” That is accurate for EasyGL and SDL GPU, but this exact worked example proves the same class compiles HLSL on Direct3D, while Vulkan interprets the strings as raw SPIR-V bytes. The comment is stale cross-renderer documentation, not a constraint enforced by the public constructor.

Both worked examples so far apply a ShaderEffect through SpriteBatch. The wider path described in this subsection is specifically EasyGL support; no other renderer’s general 3D draw dispatch currently reads GpuDrawParams::customEffectRenderer. For a long stretch of this project’s history that was the only place a ShaderEffect could actually take effect: applying one before a raw GraphicsDevice::DrawIndexedPrimitives() call — the call shape ModelMesh::Draw() and a hand-rolled RawMesh both use — was silently ignored. Because ShaderEffect did not yet implement IEffectMatrices (Chapter 15) and its FillGpuDrawParams() override still ran the Effect base class’s no-op, GpuDrawParams stayed at its default, zero value on every 3D draw, and EasyGL’s DrawIndexedPrimitivesEx() fell back to selecting one of its own built-in, stride-keyed shaders regardless of whatever custom effect the caller had just applied — exactly the same silent-fallback failure shape Chapter 12’s ExtractMatrices() section already documents for stock effects, one layer further out.

This was closed by three coordinated changes, verified directly against ShaderEffect.hpp / .cpp and EasyGLRenderer.cpp: (1) GpuDrawParams gained a customEffectRenderer field; (2) ShaderEffect now implements IEffectMatrices — real World / View / Projection properties, extracted by the same GraphicsDevice::ExtractMatrices() every stock effect already goes through — and overrides FillGpuDrawParams() to populate customEffectRenderer; (3) EasyGL’s DrawPrimitivesEx() / DrawIndexedPrimitivesEx() check that field first and, when it is set, bind the custom compiled program and its World / View / Projection uniforms directly, bypassing the built-in stride-selected shaders entirely.

A worked example, adapted from easygl_shadereffect_3d_test.cpp, makes the wiring concrete. The shader is a minimal N-dot-L diffuse lighting pass over a single textured quad, using the same GLSL attribute-location convention (location = 0/1/2 for Position / Normal / TexCoord) as VertexPositionNormalTexture’s existing 32-byte stride:

The real test behind this example is deliberately built to rule out a false positive: it draws the same quad twice, once with World = Identity (facing the light, world normal (0,0,1), expected color close to the full (200,100,50) diffuse value) and once with World = CreateRotationY(180°). A $90$° rotation was deliberately not chosen for the second case — it would turn the quad edge-on to the camera, so “renders nothing” and “renders black” would look identical in a single-pixel readback. $180$° keeps the exact same on-screen footprint (the quad is X-symmetric, so mirroring X does not change its silhouette) while flipping the world-space normal to (0,0,-1), which the shader’s own max(dot(...), 0.0) clamps to a genuinely lit black. Only a World matrix that is actually reaching the vertex shader and actually affecting world-space lighting can produce that second, specific result rather than merely happening to draw something.

The first version of the 3D draw path above recognized only the five byte-strides EasyGL’s then-existing ApplyLayout() switch knew about (16/20/24/32/52). Later PBR and vertex-color work expanded the fixed family to 48/56/68 too, but a stride is still not a description of its internal fields. Arbitrary layouts were deliberately scoped out of the first task, since several real ported sample shaders (NormalMapping.fx’s Position+Normal+Binormal+Tangent+TexCoord layout, among others) need element arrangements that match none of those fixed interpretations. A truly custom VertexDeclaration — arbitrary element count, arbitrary per-element offset, any VertexElementFormat — reads back correctly through the same 3D ShaderEffect draw path via a second, separately-tracked fix: VertexBuffer::SetDataRaw() now pushes the buffer’s own VertexDeclaration down to the renderer through a new IVertexBufferRenderer::SetVertexDeclaration() call (default no-op, so Vulkan/BGFX/SDL_Renderer needed zero code changes for this to stay correct), and ApplyLayout() binds generically from that declaration when one is present — GLSL attribute location equals the element’s own index within the declaration — falling straight through to the original stride-keyed switch, unchanged, whenever no declaration was supplied. This is a purely additive capability, not a replacement of the fixed-stride path the first worked example already exercises.

The real test behind this (easygl_shadereffect_custom_vertex_layout_test.cpp) is worth citing for its own verification technique, not just its result: it declares a 5-element, 48-byte layout (Position / Normal / Tangent / TextureCoordinate / Color). CNA now also has a fixed 48-byte PBR layout, but that one contains a four-float tangent and no trailing color; sharing a total stride does not make the records equivalent. The test diagnostically encodes three of the four non-position attributes directly into the output pixel (FragColor = vec4(Normal.x, Tangent.y, TexCoord.x, Color.r)) and draws the same quad twice with two independently-chosen sets of attribute values. Distinct, correctly-offset readback values across both draws is what proves each attribute is being read from its own correct byte offset — not aliased to a neighbor, and not a value that happens to be correct by coincidence.