Effects System

Microsoft::Xna::Framework::Graphics effects - stock effects, interfaces, custom shaders

Overview

CNA implements the XNA 4.0 effects model inside the Microsoft::Xna::Framework::Graphics namespace. An effect is a shader program combined with its parameter set and render state. You configure an effect through its typed properties (setWorldProperty(), setTextureProperty(), …), then apply a pass with effect->getCurrentTechniqueProperty()->getPassesProperty()[0]->Apply() (or the CNAEXT shortcut effect->Apply()) before drawing primitives. CNA's C++ spelling of XNA's C# properties is getXProperty() / setXProperty(); there is no CurrentTechnique member and no SetWorld()-style setter.

All stock effects implement one or more effect interfaces (IEffectMatrices, IEffectFog, IEffectLights) so that higher-level drawing code can treat effects polymorphically. Parameters can also be accessed directly through EffectParameter objects exposed on the effect.

CNA has distinct custom-effect paths, summarised in the table below. XNA/FNA Direct3D 9 Effect Framework binaries load through the XNA Effect bytecode constructor or XNB EffectReader on qualified renderers. CNAEXT ShaderEffect accepts renderer-oriented source such as GLSL, WGSL, HLSL or SPIR-V words. Support for one never implies support for the other: the first is gated by GraphicsCapability::CompiledEffects, the second by CustomEffects plus ExecutesShaderEffectSourceEXT().

Four effect paths at a glance

Which path you use decides which renderers can run your code and which capability you should query first.

Stock effects at a glance

Five XNA 4.0 stock effects, each implemented natively in C++ rather than translated from XNA's shipped shader bytecode, plus a public SpriteEffect that XNA keeps internal and that is inert at this snapshot. The set of these six is unchanged since alpha.1 and their public API changed only additively: CNAEXT shadow-receiver state on BasicEffect and SkinnedEffect, and on BasicEffect also XNA's own parameter collection (Texture, DiffuseColor, …), its technique name BasicEffect and getVertexColorEnabledProperty()/setVertexColorEnabledProperty() accessors; the five that draw geometry can also be loaded from XNB through built-in readers that need no compiled-effect capability.

BasicEffect

BasicEffect is the general-purpose 3D effect. It supports per-vertex and per-pixel lighting (setPreferPerPixelLightingProperty(true)) with up to three independent directional lights, a single diffuse texture, per-vertex color, and distance fog. Lighting is controlled via the IEffectLights interface — call EnableDefaultLighting() to activate XNA's standard three-light rig in a single call. Construction takes a GraphicsDevice&; the effect is a real 3D effect, so on a 2D-only renderer drawing with it throws.

// C++23 example
auto effect = std::make_shared<BasicEffect>(graphicsDevice);
effect->setWorldProperty(Matrix::getIdentityProperty());
effect->setViewProperty(view);
effect->setProjectionProperty(projection);
effect->EnableDefaultLighting();
effect->setTextureEnabledProperty(true);
effect->setTextureProperty(myTexture);          // Texture2D*

for (auto& pass : effect->getCurrentTechniqueProperty()->getPassesProperty()) {
    pass.Apply();
    graphicsDevice.DrawIndexedPrimitives(
        PrimitiveType::TriangleList,
        0,                 // baseVertex
        0,                 // minVertexIndex
        vertexCount,       // numVertices
        0,                 // startIndex
        indexCount / 3);   // primitiveCount
}

AlphaTestEffect

AlphaTestEffect renders a single textured surface and discards fragments whose alpha does not satisfy a configurable comparison against a reference value. Supported comparisons are Always, Never, Equal, NotEqual, Less, LessEqual, Greater, and GreaterEqual. The reference is an integer 0–255 that is normalised by 255 with a half-step threshold, as in XNA/FNA (Greater at reference 127 keeps alpha 128–255). This effect is useful for vegetation, fences, and other cut-out geometry where alpha blending would cause sorting problems.

auto effect = std::make_shared<AlphaTestEffect>(graphicsDevice);
effect->setWorldProperty(transform);
effect->setViewProperty(view);
effect->setProjectionProperty(projection);
effect->setTextureProperty(treeBarkTexture);
effect->setAlphaFunctionProperty(CompareFunction::Greater);
effect->setReferenceAlphaProperty(128);  // keep fragments with alpha above about 0.5
effect->getCurrentTechniqueProperty()->getPassesProperty()[0]->Apply();

DualTextureEffect

DualTextureEffect samples two textures in the same draw call and multiplies them together. A common use case is lightmap baking: the first texture holds the base colour and the second holds a pre-baked lightmap. Like XNA's effect it reads two UV sets — TEXCOORD0 for the first texture and TEXCOORD1 for the second — so the vertex format needs both (XNA refuses a single-UV draw; CNA does not check, and the second texture reads (0, 0) on most renderers but the first set’s coordinates on VULKAN — see CNA-GAP-033). It also doubles the first texture's RGB, exactly as XNA does, so an all-grey (0.5) lightmap is the identity. An unbound texture samples opaque black.

auto effect = std::make_shared<DualTextureEffect>(graphicsDevice);
effect->setWorldProperty(Matrix::getIdentityProperty());
effect->setViewProperty(view);
effect->setProjectionProperty(projection);
effect->setTextureProperty(diffuseTexture);
effect->setTexture2Property(lightmapTexture);
effect->getCurrentTechniqueProperty()->getPassesProperty()[0]->Apply();

EnvironmentMapEffect

EnvironmentMapEffect adds a cube-map environment reflection on top of a diffuse texture. The amount of reflection versus base colour is controlled by the environment map amount (default 1.0) and an optional Fresnel factor — an exponent (default 1.0, and 0 disables Fresnel) that makes reflections stronger at glancing angles; the Fresnel weight is computed per vertex and clamped, as in D3D9. The effect implements the full IEffectLights interface: up to three directional lights contribute Lambert terms, and the specular contribution is EnvironmentMapSpecular multiplied by the cube map's alpha channel (default zero), not a Phong highlight. Fog is also supported.

auto effect = std::make_shared<EnvironmentMapEffect>(graphicsDevice);
effect->setWorldProperty(sphereTransform);
effect->setViewProperty(view);
effect->setProjectionProperty(projection);
effect->setTextureProperty(diffuseTexture);
effect->setEnvironmentMapProperty(skyboxCube);   // TextureCube*
effect->setEnvironmentMapAmountProperty(0.8f);
effect->setFresnelFactorProperty(1.0f);
effect->getCurrentTechniqueProperty()->getPassesProperty()[0]->Apply();

SkinnedEffect

SkinnedEffect is the standard effect for skeletal (skinned) mesh animation. Bone matrices are uploaded to the GPU as a bone palette of at most SkinnedEffect::MaxBones (72) matrices. Each vertex can reference 1, 2, or 4 bones through the weights-per-vertex property; any other value throws ArgumentOutOfRangeException. The effect also supports the full lighting model (three directional lights) and fog.

auto effect = std::make_shared<SkinnedEffect>(graphicsDevice);
effect->setWorldProperty(Matrix::getIdentityProperty());
effect->setViewProperty(view);
effect->setProjectionProperty(projection);
effect->EnableDefaultLighting();
effect->setWeightsPerVertexProperty(4);
effect->SetBoneTransforms(boneMatrices);   // const std::vector<Matrix>&, 1..72 entries
effect->getCurrentTechniqueProperty()->getPassesProperty()[0]->Apply();

SpriteEffect

SpriteEffect is the 2D sprite effect. XNA 4.0 has no public class of this name (its SpriteBatch keeps the equivalent effect internal); CNA exposes one. In CNA, SpriteBatch never creates or uses it (sprites go through each renderer's own sprite path). Its OnApply() is written to set up an orthographic projection over the viewport, but because the effect has no MatrixTransform parameter it returns at its first statement, so applying it currently sets nothing (see Known Issues). It derives from Effect directly and does not implement IEffectMatrices. Application code does not normally instantiate SpriteEffect directly; it is exposed in the public API for completeness.

Beyond XNA: PbrEffect, SkinnedPbrEffect, ShaderEffect and more

Four effect classes that are always compiled into the library have no XNA 4.0 counterpart. They are tagged CNAEXT in the headers, which means a compile-time purity check can be switched on to make using them an error — useful if your goal is a strictly XNA-compatible codebase.

PBR support is broad but not universal: DIRECTX9, DIRECTX11, the three EasyGL identities, SDL_GPU, VULKAN, WEBGPU and METAL (9 identities, seven implementation families) implement the full model, both KHR_materials_specular maps and vertex-colour PBR included; SOFTWARE draws a reduced CPU cross-check (base colour multiplied by diffuse); FNA3D refuses PBR draws by name. Shadow sampling and image-based lighting (IShadowReceiverEXT, setImageBasedLightEXT) are honoured only by the three EasyGL identities, VULKAN, SDL_GPU and WEBGPU; elsewhere the state is accepted and ignored (an unshadowed image, no error). The shadow map and the environment textures are rendered by the application; see Tutorial 114 and Tutorial 59.

CNAEXT effects (CNA_CNAEXT=ON)

The optional CNAEXT extensions (modules/graphics-ext, 11 public headers) add a few effect-shaped classes. They are off by default and built by no CI workflow; see CNAEXT extensions.

Compiled XNA effects

Effect(GraphicsDevice&, bytecode) accepts the XNA/FNA Direct3D 9 Effect Framework binary format (commonly stored as .fxb), including the wrapper emitted by the XNA 4 compiler. The real XNB EffectReader reads the same payload through ContentManager, preserves the asset name and wraps every failure — including the “this renderer cannot do it” case — in ContentLoadException. The direct and XNB routes produce the same reflected effect graph. This is a real implementation, not a stub: on a capable renderer the constructor builds and reflects the full graph.

The loader enforces a 64 MiB payload limit and validates structure before constructing renderer resources. It reflects techniques, passes, parameters, annotations, arrays and structures; parameter values and textures can be set, pass render/sampler state is applied, cloning preserves runtime state, and compiled effects can participate in SpriteBatch and 3D draws.

What throws, and when

Malformed input is judged before the renderer is consulted, so the same bytes give the same ArgumentException on every renderer; only a structurally valid binary on an incapable renderer reaches the capability check.

Renderer support is opt-in and queryable

Compiled-effect support is 11 of the 14 identities in 9 implementation families. FNA3D has it always; every other option defaults to OFF because it pulls the pinned FNA3D/MojoShader translation machinery into a renderer that does not otherwise need it. Enabling an option for one family is not a universal capability promise: each option lives in the renderer's own configure branch, and a default configure reports CompiledEffects true on FNA3D only (13 of 14 identities false).

if (!device.SupportsCapability(CNA::GraphicsCapability::CompiledEffects)) {
    // Choose a stock effect or another renderer/build configuration.
}

auto effect = getContentProperty().Load<std::shared_ptr<Effect>>("Effects/Bloom");
effect->getCurrentTechniqueProperty()->getPassesProperty()[0]->Apply();

The finer-grained query is RendererFeature::CompiledXnaEffects in the RendererCapabilityProfile returned by GraphicsDevice::GetRendererCapabilityProfileEXT().

Producing a compiled effect at build time

XNA samples ship .fx source; what CNA loads is the compiled container the XNA content build produced. CNA's cna-content tool (built with the library) covers both routes: a .fxb is imported as-is, and a .fx is compiled by an external, legacy fxc at profile fx_2_0 and written as an Effect .xnb. CNA does not vendor or embed a compiler. The .fx route needs --format xnb (a .cnb cannot carry an Effect), and it has not been checked against a genuine Microsoft fxc — CNA's own documentation says so. The full walkthrough is Tutorial 150.

cna-content build Content -o build/Content --format xnb \
    --fx-compiler /path/to/fxc.exe --fx-compiler-launcher wine

Renderer coverage

Effect support is a property of the active renderer and its build options. CNA exposes 14 renderer identities over 12 implementation families, and coverage differs sharply across them; in a multi-renderer build query the actual device rather than the compile-time default. See Renderers for the full inventory. The table lists which of the XNA stock effects, the CNAEXT PBR pair and a source ShaderEffect each renderer can draw. Shader-program and blob counts are deliberately not published: they change with every shader edit and depend on what is counted.

Effect interfaces

IEffectMatrices

Implemented by every stock 3D effect, by PbrEffect/SkinnedPbrEffect and by ShaderEffect. (SpriteEffect is a plain Effect and does not implement it.) Provides the three standard transformation matrices used to project geometry from object space to clip space. Each is a getXProperty() / setXProperty(const Matrix&) pair.

IEffectFog

Implemented by all stock effects that render geometry in world space. Fog is computed per vertex from view-space depth (matching XNA/FNA) and blended linearly between FogStart and FogEnd. Call setFogEnabledProperty(false) to disable the computation entirely.

A quad receding from the camera with fog enabled: the linear blend between FogStart and FogEnd is interpolated across the surface. This is genuine Microsoft XNA 4.0 runtime output from CNA's oracle corpus (tools/xna-oracle/), which CNA's DIRECTX9 renderer is diffed against at --tolerance 0 (captured under Wine + DXVK on Linux). See Verification.

IEffectLights

Implemented by BasicEffect, EnvironmentMapEffect, SkinnedEffect, PbrEffect and SkinnedPbrEffect. Exposes an ambient light and three independent directional lights. Call EnableDefaultLighting() to configure XNA's standard three-light rig in one call.

Each DirectionalLight exposes accessor pairs for:

• Direction (getDirectionProperty() / setDirectionProperty()) — Vector3, the direction the light travels (XNA's convention; the default key light points along (-0.53, -0.57, -0.63))
• DiffuseColor — Vector3 RGB diffuse contribution
• SpecularColor — Vector3 RGB specular contribution
• Enabled — bool enables or disables this light

EffectParameter

All effect parameters are accessible through the collection returned by effect->getParametersProperty() as EffectParameter objects. Look one up by name with getParametersProperty()["Name"], which returns an EffectParameter* (null when absent); the integer subscript also returns a pointer (null when out of range). There is no template GetValue<T>(): reads use typed getters and writes use the overloaded SetValue(), mirroring XNA 4.0.

Supported types for GetValueXxx / SetValue:

• bool, int, float, std::string — scalar values (on a compiled effect's parameter, SetValue(std::string) throws InvalidCastException unless the parameter is a string; on other parameters it simply stores the string)
• Vector2, Vector3, Vector4, Quaternion — float vectors
• Matrix — 4×4 matrix (GetValueMatrix(), SetValue(const Matrix&), plus the Transpose variants)
• std::vector<T> of each of the above — arrays (GetValueMatrixArray(count), used for example by a bone palette)
• Texture2D*, Texture3D*, TextureCube* — sampler bindings

// Look up a parameter by name and set it directly
EffectParameter* param = effect->getParametersProperty()["DiffuseColor"];
if (param != nullptr)
    param->SetValue(Vector4(1.0f, 0.5f, 0.0f, 1.0f));

// Read back a matrix
Matrix world = effect->getParametersProperty()["World"]->GetValueMatrix();

Custom ShaderEffect

When the stock effects do not meet your needs, ShaderEffect lets you supply your own shader source. Its constructor takes three arguments — the device and the two shader sources as source text, not paths. Note that ShaderEffect is a CNA extension, not part of XNA 4.0 — it is tagged CNAEXT. The constructor does not throw on a compile failure: check IsEffectValid(), and read GetCompileErrorEXT() or GetShaderDiagnosticsEXT() for the reason.

CNAEXT ShaderEffect(GraphicsDevice& device,
                   const std::string& vertSrc,
                   const std::string& fragSrc);

Alternatively, a .cnj Effect descriptor lets ContentManager read the sources for you. It has exactly two shader fields, vertex and fragment, each naming a shader source file relative to the content root (not to the descriptor's own folder); missing either raises a ContentLoadException. (The same reader also accepts BasicEffect, AlphaTestEffect, DualTextureEffect, EnvironmentMapEffect and SkinnedEffect descriptors.)

{
  "cnjVersion": 1,
  "type": "Effect",
  "vertex": "effects/my_effect.vert",
  "fragment": "effects/my_effect.frag"
}

Load it as Effect — that, not ShaderEffect, is the type the reader is registered for — then downcast. Uniforms are set by name through the SetUniformXxx family; there is no Parameters collection on ShaderEffect.

auto fxBase = getContentProperty().Load<std::shared_ptr<Effect>>("effects/my_effect");
auto* myEffect = dynamic_cast<ShaderEffect*>(fxBase.get());

// Applying first is the portable habit. (On the GL renderers each setter also
// makes its own program current, but do not rely on that on other renderers.)
myEffect->getCurrentTechniqueProperty()->getPassesProperty()[0]->Apply();

float wvpColumnMajor[16];
wvp.ToColumnMajor(wvpColumnMajor);
myEffect->SetUniformMat4("WorldViewProj", wvpColumnMajor);
myEffect->SetUniformVec4("Tint", 1.0f, 0.8f, 0.6f, 1.0f);

graphicsDevice.DrawPrimitives(PrimitiveType::TriangleList, 0, triangleCount);

For the Vulkan renderer, the source a source-string constructor takes is SPIR-V words rather than GLSL text (a .cnj descriptor names the pre-compiled .spv files). A ShaderEffect's scalar uniforms on Vulkan live in a fixed 128-byte push-constant block, and DeclareUniformBlockEXT() describes std140 uniform blocks.

See ShaderEffect and Tutorial 52: Writing Custom Shaders for the full treatment, and Tutorial 128 for the compiled-effect path.