Chapter 15 Stock Effects and Draw Parameters

Effect inherits GraphicsResource and is not copyable. The Effect(device) constructor creates the small stock-effect base graph. The byte-buffer constructor now accepts a bounded, structurally validated XNA/FNA Direct3D 9 Effect Framework binary — the .fxb-shaped payload normally stored by XNA’s general EffectReader. It rejects an empty or over-64-MiB buffer, malformed container graphs, and the distinct MonoGame MGFX container. It then requires GraphicsCapability::CompiledEffects; a renderer that did not opt in throws NotSupportedException before any draw.

FNA3D supports this route in its normal build. SDL_GPU, the EasyGL profiles, and Vulkan support it only when their respective CNA_*_COMPILED_EFFECTS option is enabled; those options are off by default because they add MojoShader. Other renderers report the capability false. This is compiled Effect Framework support, not a compiler for .fx or HLSL source, not DXBC or MGFX ingestion, and not the renderer-specific ShaderEffect API. Chapter 17 separates the formats and backends.

Clone() is virtual and, as a CNAEXT deviation from FNA’s garbage-collected reference semantics, returns an owning raw pointer rather than a managed reference — there is no GC in C++ to hand a shared reference back to. Apply() itself is CNAEXT — real FNA has no public Effect.Apply(), only EffectPass.Apply() — and the protected virtual FillGpuDrawParams(GpuDrawParams&) is the single mechanism every stock effect below uses to hand its own parameters down to whichever renderer is active; the base implementation is a no-op, and every stock effect overrides it.

EffectParameter carries a name, semantic, row/column counts, class/type enums, and a broad family of typed GetValue* / SetValue* accessors. In a compiled effect, those records are reflected from the binary and mutable values synchronize to the renderer runtime before a pass is applied. In a stock effect, the collection remains the narrower manual shadow described in §15.2. The parameter, pass, and technique collections all store elements behind unique_ptr rather than by value, so a reference obtained earlier — including a captured CurrentTechnique — survives a later Add() reallocation. EffectPass::Apply() throws InvalidOperationException if an owned pass does not belong to the effect’s currently selected technique, including when CurrentTechnique is null — matching FNA’s own “Applied a pass not in the current technique!” guard, mapped onto a defined C++ exception rather than the null-reference crash the equivalent null case produces in C#.

The XNA-looking Parameters property needs a mode-qualified reading. A compiled effect reflects parameters, techniques, passes, annotations, arrays and structures from its binary; current technique and mutable values are copied by Clone(), and pass application pushes the renderer’s blend, depth/stencil, rasterizer, sampler, texture and shader state changes through the device. A bare stock-mode Effect, by contrast, starts with one manually created Default technique containing one P0 pass and with zero parameters.

The five stock effects do not all even present the same structural approximation. BasicEffect adds no parameter records at all, even though real FNA’s compiled BasicEffect exposes its parsed parameter table:

AlphaTestEffect, DualTextureEffect, EnvironmentMapEffect, and SkinnedEffect each call a private CacheEffectParameters() helper instead. It manually creates a small set of internal shadows: respectively 6, 5, 12, and 12 records for the derived material, fog, matrix, and shader-index calculations. Those lists are neither a bytecode reflection result nor a full public description of the effect; for example, the manually cached AlphaTest and DualTexture lists contain no texture parameter despite each effect having a texture property.

The normal render flow is consequently one-way:

Writing a manually found EffectParameter therefore does not form a portable alternative to a stock effect’s named property and does not create an arbitrary renderer uniform. The device dispatches FillGpuDrawParams() directly, not the collection. A few properties deliberately use a shadow as their own storage — fog color is the important example in the four effects that cache it — but that is an implementation detail that a later property assignment or OnApply() calculation can overwrite. Use the public setDiffuseColorProperty, setTextureProperty, matrix, lighting, fog, and skinning APIs for stock material state; use the explicit ShaderEffect::SetUniform* surface, with Chapter 17’s renderer limits, for a custom uniform.

Every stock effect’s FillGpuDrawParams override populates the same struct, defined once in the renderer contract layer (Chapter 19) and forwarded from Effect::FillGpuDrawParams() to whichever renderer is currently active. It carries two ordinary texture slots plus a dedicated environment-map cube slot, diffuse/ambient/emissive/specular colors, three directional lights (each with direction, diffuse, and specular), the world matrix, alpha-test parameters, Fresnel/environment-map parameters, a 72-bone skinning palette with a weights-per-vertex count, fog parameters, a set of mode flags (textureEnabled, vertexColorEnabled, lightingEnabled, dualTexture, envMapping, skinned, pbr), instancing fields, a pointer for a custom ShaderEffect-compiled program, and six PBR-specific metallic-roughness fields. Two flags are worth flagging directly: preferPerPixelLighting and specularEnabled. Earlier project documentation called both flags “ignored by every renderer except D3D9.” That statement is historical; the current scoped result appears after SkinnedEffect below.

BasicEffect is the largest of the five: public World / View/Projection fields, VertexColorEnabled, the full material color set (DiffuseColor, EmissiveColor, SpecularColor, SpecularPower, Alpha, AmbientLightColor), LightingEnabled/PreferPerPixelLighting, TextureEnabled / Texture, full DirectionalLight0/1/2, and EnableDefaultLighting(). Its 22-property audit found and fixed several early default-value bugs (VertexColorEnabled, DirectionalLight0.Enabled, and DirectionalLight.Direction’s default value were all initially wrong), then a sequence of real, per-renderer rendering bugs: the no-texture VertexColorEnabled toggle was ignored by all three of EasyGL, Vulkan, and BGFX (three separate bugs, one per renderer); the textured-plus-vertex-color-plus-diffuse case dropped DiffuseColor entirely on EasyGL and BGFX (Vulkan was already correct); and a shared bug across all three renderers never checked DirectionalLight0.Enabled at all, so a disabled light kept lighting the surface regardless. BGFX carried one additional, much wider bug: its vertex-layout builder never declared Normal / TexCoord0 attributes for any stride except the skinned 52-byte layout — silently breaking lit-normal and UV interpolation for every other stride, invisible until then because every prior test happened to use a UV-insensitive $1\times 1$ texture. EmissiveColor was dropped entirely in the no-lighting path on all three renderers; ambient/emissive/specular forwarding and specular highlights were corrected afterward. The focused composition fixture then produced byte-identical output on EasyGL, Vulkan, and BGFX at the pinned revisions; this result does not generalize to untested effect combinations or renderer families.

AlphaTestEffect implements IEffectMatrices and IEffectFog only — no lighting. AlphaFunction (a CompareFunction, defaulting to Greater) and ReferenceAlpha (an unclamped 0–255 int) implement the actual alpha test; VertexColorEnabled, DiffuseColor / Alpha, and Texture round out the surface. Its audit found zero property-default bugs (the first test coverage for this effect written from scratch), and a full 8-value CompareFunction sweep passed 24 of 24 cases on the three campaign renderers. The campaign initially found that VertexColorEnabled had no effect on Vulkan or BGFX because their alpha-test pipeline declared no color attribute. The correction added stride-24 sibling vertex shaders and discriminating pixel tests on both products; EasyGL was already correct. Fog forwarding was a real, fixed bug on EasyGL specifically for this effect — and, in the course of fixing it, revealed a much larger finding: fog was a total no-op on both Vulkan and BGFX for every 3D effect, because no shader file on either renderer mentioned fog at all. That project-wide gap was closed in one pass, adding real fog uniforms, varyings, and blend formula to every 3D shader on both renderers at once — the same “one shared fix closes it everywhere” pattern already seen for SpriteBatch’s flip bug in Chapter 13. A separate, unrelated BGFX-only bug — seven texture-binding call sites with no fallback-to-white-texture else-branch — was found and fixed at the same time, affecting every effect that binds a possibly-null texture, not just this one.

Two independent texture slots (Texture, Texture2), plus VertexColorEnabled, DiffuseColor / Alpha, and fog — no lighting. The audit’s headline finding was a shared formula bug across all three campaign renderers: FNA’s real shader doubles the first texture’s RGB value (color.rgb *= 2) before multiplying it against the overlay texture, and none of the three shaders initially implemented that factor — invisible to every prior test, because a test built from 0-or-1-saturated color values cannot distinguish “multiplied by one” from “multiplied by two and then saturated.” The factor is present in all three pinned shader paths now. Texture2’s null-texture fallback had its own, BGFX-specific bug (again, no else-branch), fixed alongside the project-wide fallback fix above. Fog needed its own separate EasyGL fix here, because this effect uses its own dedicated shader with no fog infrastructure at all, unlike AlphaTestEffect’s shared shader path; Vulkan and BGFX were already covered by the project-wide fog fix. VertexColorEnabled was another closed defect: the correction added a stride-24 colored variant on EasyGL, Vulkan, and BGFX and verified enabled and disabled cases independently.

EnvironmentMapEffect combines IEffectMatrices, IEffectLights, and IEffectFog. It accepts a diffuse Texture, a cube EnvironmentMap, EnvironmentMapAmount, EnvironmentMapSpecular, FresnelFactor, EmissiveColor, and lighting state. As in FNA, LightingEnabled is always true and its setter throws when passed false. The 14-property API audit found no property-contract defects.

A capstone fixture composes these corrections and produces byte-identical output on EasyGL, Vulkan, and BGFX. That result is scoped to the fixture and those renderer routes.

SkinnedEffect accepts at most MaxBones = 72. Its WeightsPerVertex property accepts only 1, 2, or 4 and throws for other values. SetBoneTransforms / GetBoneTransforms(count), specular lighting, fog, and three directional lights follow the stock-effect route. CNA adds VertexColorEnabled for imported glTF meshes with a COLOR_0 attribute; XNA’s SkinnedEffect has no corresponding property.

Identity, single-bone, and two-bone weighted skinning are pixel-verified on the three campaign renderers. Historical defects affected surrounding state: Clone() dropped SpecularColor and SpecularPower; lights 1 and 2 were not forwarded; the specular fields had no GPU implementation; and WeightsPerVertex did not gate the four-weight sum. The pinned implementation preserves the cloned fields, forwards all enabled lights, evaluates a Blinn–Phong half-vector specular term, and gates the sum for the selected weight count.

Earlier shared dispatch omitted both PreferPerPixelLighting and EnvironmentMapEffect’s specularEnabled. The affected GPU paths therefore used fragment lighting regardless of the public setting. D3D9 already contained Microsoft’s per-vertex and per-pixel shader families; the other covered renderers added per-vertex variants using FNA’s lighting formula in the vertex stage. AlphaTestEffect and DualTextureEffect have no lighting path and were unchanged.

The new discriminating fixtures exposed four secondary issues:

Lit-scene baselines changed when the XNA-compatible default became effective: low-poly surfaces can appear more faceted and highlights can soften under vertex interpolation. Those changes are expected for the default path; the D3D12 fixture above explicitly selects the alternate path.

The audits found three recurring failure modes:

• •

  a missing shader term, such as doubled dual-texture RGB, Fresnel weighting, or specular;

• •

  a public flag that never reached GPU state, such as the former VertexColorEnabled and WeightsPerVertex gaps; and

• •

  a shared dispatch defect affecting several renderers, including the former light-enable, fog-forwarding, and clone-state omissions.

The tested core interpolation and lighting formulas were not broadly defective; the observed failures were specific omissions. This distinction keeps the evidence scoped to the paths and fixtures that exposed them.