ShaderEffect

Microsoft::Xna::Framework::Graphics — user-supplied GLSL / GLSL ES / SPIR-V / WGSL / HLSL shaders from source text or a .cnj descriptor

Overview

ShaderEffect lives alongside the stock effects in the Microsoft::Xna::Framework::Graphics namespace, but it is a CNA addition rather than an XNA 4.0 type. It binds a shader program to the graphics pipeline and exposes its uniform inputs through a family of SetUniformXxx methods. There is no Parameters[...] collection on ShaderEffect — that is the main way it departs from the stock effects.

When the built-in stock effects do not cover your use case, you author your own vertex and fragment shaders and hand the source text to the constructor. It takes three arguments, and the two strings are the shader source itself, not paths:

// Microsoft/Xna/Framework/Graphics/ShaderEffect.hpp
CNAEXT ShaderEffect(GraphicsDevice& device,
                   const std::string& vertSrc,
                   const std::string& fragSrc);

You can keep that source in a raw string literal, read it from disk yourself with System::IO::File::ReadAllText, or let ContentManager read it via a .cnj Effect descriptor. The same effect->getCurrentTechniqueProperty()->getPassesProperty()[0]->Apply() pattern used by stock effects applies equally to custom ShaderEffect instances. The constructor does not throw when the shader fails to compile: check IsEffectValid(), and see Compile diagnostics for the reason.

Relationship to stock effects

CNA ships the five XNA stock effects — BasicEffect, AlphaTestEffect, DualTextureEffect, EnvironmentMapEffect and SkinnedEffect — and a public SpriteEffect (XNA keeps its sprite effect internal), implemented natively in C++ rather than translated from bytecode. Each bundles a built-in shader program with typed C++ properties for convenience. CNA additionally ships the CNAEXT effects PbrEffect, SkinnedPbrEffect and ColorMatrixEffect (the last runs on the SOFTWARE SpriteBatch only). A custom ShaderEffect follows the same runtime pattern — the difference is that the shader source is supplied by the application rather than built into the engine.

This means any code that works with Effect* pointers polymorphically will accept a custom ShaderEffect without modification.

The .cnj Effect descriptor

If you would rather not read the shader files yourself, ContentManager can do it. CNA's content pipeline has a real Effect reader that consumes a .cnj document — CNA's single JSON content format, the same one used for models and sprite fonts. It carries a cnjVersion and a type, and has exactly two shader fields.

{
  "cnjVersion": 1,
  "type": "Effect",
  "vertex": "myvert.vert",
  "fragment": "myfrag.frag"
}

Fields:

• "cnjVersion" — must be 1.
• "type" — must be "Effect", or loading raises a ContentLoadException. (The same reader also accepts the five stock-effect types BasicEffect, AlphaTestEffect, DualTextureEffect, EnvironmentMapEffect and SkinnedEffect.)
• "vertex" — the vertex shader source file, named relative to the content root (not to the descriptor's own folder: for Content/shaders/custom.cnj write shaders/custom.vert).
• "fragment" — the fragment shader source file.

Missing either shader field raises a ContentLoadException. There is no uniform declaration list: uniforms are not pre-registered anywhere, they are simply set by name at draw time.

The file contents are handed to the renderer exactly as a string constructor argument would be, so they must be in the dialect the active renderer expects (see Renderer availability). For the Vulkan renderer the sources the descriptor names are pre-compiled SPIR-V (.spv) rather than GLSL. On Vulkan, scalar uniforms live in a fixed 128-byte push-constant block, and uniform buffer layout follows std140 rules (see DeclareUniformBlockEXT()).

Loading a custom shader

Load the descriptor as Effect — that, not ShaderEffect, is the type the reader is registered for — then downcast.

// In your Game::LoadContent():
auto fxBase = getContentProperty().Load<std::shared_ptr<Effect>>("shaders/custom");
auto* effect = dynamic_cast<ShaderEffect*>(fxBase.get());

The content manager resolves "shaders/custom" to Content/shaders/custom.cnj, reads the descriptor, reads the two named source files, compiles the shader program, and returns it as an Effect.

The equivalent without ContentManager is just as short — nothing in ShaderEffect requires content-manager involvement:

std::string vert = System::IO::File::ReadAllText("shaders/custom.vert");
std::string frag = System::IO::File::ReadAllText("shaders/custom.frag");
ShaderEffect effect(device, vert, frag);

Setting uniforms

There is no Parameters[...] collection on ShaderEffect. Uniforms are set by name through direct methods, each taking a const char* name.

// Bind this effect's program first.
effect->getCurrentTechniqueProperty()->getPassesProperty()[0]->Apply();

// Matrix uniforms — column-major float pointers. Matrix::ToColumnMajor fills 16 floats.
float world[16], viewM[16], projM[16];
worldMatrix.ToColumnMajor(world);
view.ToColumnMajor(viewM);
projection.ToColumnMajor(projM);
effect->SetUniformMat4("World", world);
effect->SetUniformMat4("View", viewM);
effect->SetUniformMat4("Projection", projM);

// Scalar and vector uniforms
effect->SetUniformFloat("Opacity", 0.75f);
effect->SetUniformVec4("Tint", 1.0f, 0.8f, 0.6f, 1.0f);

// Boolean flags are ints in GLSL
effect->SetUniformInt("UseNormalMap", 1);

World, View and Projection can also be set as properties: ShaderEffect implements IEffectMatrices (setWorldProperty(), setViewProperty(), setProjectionProperty()), and CNA forwards those to the renderer as column-major uniforms of exactly those names.

Passing a texture uniform

Bind a Texture2D to a texture unit with SetTexture (it takes a reference), then tell the sampler uniform which unit to read from.

// Load a texture through the content pipeline (Load returns the asset by value)
Texture2D diffuse = getContentProperty().Load<Texture2D>("textures/wall");

// Bind it to texture unit 0, and point the sampler at that unit
effect->SetTexture(0, diffuse);
effect->SetUniformInt("Texture0", 0);

The fragment shader declares the corresponding sampler as a standard uniform sampler2D Texture0;. No registration is needed beyond the two calls above. SetTexture also has TextureCube& and Texture3D& overloads for shaders that declare samplerCube or sampler3D uniforms.

Applying the effect and drawing

After all parameters are set, apply the effect's first (and typically only) pass before issuing draw calls. This uploads the current parameter values to the GPU and binds the shader program.

effect->getCurrentTechniqueProperty()->getPassesProperty()[0]->Apply();
graphicsDevice.DrawIndexedPrimitives(
    PrimitiveType::TriangleList,
    0,                // baseVertex
    0,                // minVertexIndex
    vertexCount,      // numVertices
    0,                // startIndex
    indexCount / 3);  // primitiveCount

If your effect defines multiple techniques or passes, iterate over effect->getTechniquesProperty() and each technique's getPassesProperty(), calling pass.Apply() inside the loop and re-issuing draw calls for each pass. Remember that operator[] on these collections returns a pointer; range-for yields references.

Full example: custom tinted mesh shader

The following example shows a complete .cnj Effect descriptor together with matching GLSL vertex and fragment shaders, and the C++ code that loads and drives the effect. The shaders below are desktop GLSL (#version 330 core), which is what OPENGL33 accept; the note after the C++ shows the GLSL ES 3.00 variant for OPENGLES3 and WEBGL2.

Content/shaders/tinted.cnj

{
  "cnjVersion": 1,
  "type": "Effect",
  "vertex": "tinted.vert.glsl",
  "fragment": "tinted.frag.glsl"
}

Content/shaders/tinted.vert.glsl

#version 330 core

uniform mat4 World;
uniform mat4 View;
uniform mat4 Projection;

layout(location = 0) in vec3 a_Position;
layout(location = 1) in vec2 a_TexCoord;

out vec2 v_TexCoord;

void main()
{
    mat4 wvp = Projection * View * World;
    gl_Position = wvp * vec4(a_Position, 1.0);
    v_TexCoord  = a_TexCoord;
}

Content/shaders/tinted.frag.glsl

#version 330 core

uniform sampler2D Texture0;
uniform vec4      Tint;

in  vec2 v_TexCoord;
out vec4 fragColor;

void main()
{
    vec4 texColor = texture(Texture0, v_TexCoord);
    fragColor = texColor * Tint;
}

C++ usage

// LoadContent
auto fxBase        = getContentProperty().Load<std::shared_ptr<Effect>>("shaders/tinted");
auto* tintedEffect = dynamic_cast<ShaderEffect*>(fxBase.get());
Texture2D wallTexture = getContentProperty().Load<Texture2D>("textures/wall");

// Draw (called each frame) — Apply() first, then the uniforms.
tintedEffect->getCurrentTechniqueProperty()->getPassesProperty()[0]->Apply();

float world[16], viewM[16], projM[16];
Matrix::getIdentityProperty().ToColumnMajor(world);
view.ToColumnMajor(viewM);
projection.ToColumnMajor(projM);
tintedEffect->SetUniformMat4("World", world);
tintedEffect->SetUniformMat4("View", viewM);
tintedEffect->SetUniformMat4("Projection", projM);
tintedEffect->SetUniformVec4("Tint", 1.0f, 0.5f, 0.5f, 1.0f);

tintedEffect->SetTexture(0, wallTexture);
tintedEffect->SetUniformInt("Texture0", 0);

graphicsDevice.DrawIndexedPrimitives(
    PrimitiveType::TriangleList, 0, 0, vertexCount, 0, indexCount / 3);

Vertex shader inputs and VertexDeclaration

The attribute layout declared in the vertex shader (layout(location = N) in ...) must match the VertexDeclaration of the vertex buffer bound at draw time. On EasyGL CNA maps each VertexElement to the attribute location equal to its element index in the declaration, per-vertex elements first and per-instance elements after them. A mismatch in type or location will produce incorrect geometry or a GPU error.

For the standard VertexPositionTexture layout used in the example above, position is always location 0 and texture coordinates are location 1. If you use a custom vertex struct, declare a matching VertexDeclaration (see Tutorial 51) and ensure the GLSL locations align. The GLSL attribute names are not a CNA contract — only the locations matter. The stock programs' own attribute names (aPos, aUV, …) are internal.

Uniform setter reference

The table below lists the uniform setters on ShaderEffect, together with the shader uniform type each one writes.

Note the difference between SetUniformFloatArray, SetUniformVec2Array and SetUniformVec3Array: the first counts scalars, the others count elements. There is no SetUniformMat3 and no vec4-array setter. See Tutorial 52: Writing Custom Shaders for worked examples.

Compile diagnostics

A failed compile is not an exception: on several renderers CustomEffects is true while GLSL text is never compiled at all (Vulkan takes SPIR-V and HEADLESS accepts and ignores the source; SOFTWARE also accepts it but reports CustomEffects false), and throwing would turn a documented capability boundary into a crash. Instead the effect is invalid, and it can say why:

ShaderEffect fx(device, vertSrc, fragSrc);
if (!fx.IsEffectValid()) {
    // Do not draw with it. Print why:
    std::fprintf(stderr, "ShaderEffect failed to compile:\n%s\n", fx.GetCompileErrorEXT().c_str());
}

Renderer availability

A single-renderer build fixes the shader source format with -DCNA_GRAPHICS_RENDERER=<NAME>. An opt-in multi-renderer build compiles several families and selects one before the graphics device is created, so an application that permits several runtime choices must package a compatible shader form for every active path. A source ShaderEffect needs the CustomEffects capability and a renderer that actually executes the text; the table lists what each of the 14 renderer identities accepts.

The practical consequence is that one shader source string is not portable across renderers. Shipping on more than one shading language means authoring a source variant per language and selecting it at build time with the CNA_RENDERER_<NAME> define CNA's configure emits (the three GL profiles share CNA_RENDERER_EASYGL, distinguished by CNA_GL_PROFILE_*) or, better, at run time from the live device (next section). A renderer name that is not one of the 14 is a configure-time error. See Renderers for the full comparison across all 14 identities.

Asking the live device

Rather than hard-coding a renderer table, ask the device. Three queries answer “can I use a source ShaderEffect here, and in which language?”:

GraphicsDevice& gd = getGraphicsDeviceProperty();

// 1. Does this renderer accept a custom effect at all?
bool custom = gd.SupportsCapability(CNA::GraphicsCapability::CustomEffects);

// 2. Does it actually run the source text you hand it? (false on VULKAN by design,
//    on DIRECTX9 by declaration, and on SOFTWARE/HEADLESS/FNA3D/METAL.)
bool runs = gd.ExecutesShaderEffectSourceEXT();

// 3. Which dialect does it want? (GlslDesktop, GlslEs, SpirV, Wgsl, Hlsl, ...)
auto dialect = gd.GetShaderDialectEXT();

For the typed constructors use gd.SupportsShaderLanguageEXT(language, stage). It is also the truthful query for Vulkan and SDL_GPU: their detailed RendererCapabilityProfile reports the six ShaderDialect* features as unsupported because SPIR-V has no feature entry there, even though both execute caller SPIR-V. GetRendererCapabilityProfileEXT() and GetRendererCapabilityReportEXT() give the full picture for logs (see Tutorial 133). Tutorial 151 turns these queries into a complete run-time choice with a fallback.

Typed shader code and packages

With CNA_CNAEXT=ON two more constructors exist. ShaderEffect(device, ShaderCodeEXT vertex, ShaderCodeEXT fragment) names the language and entry point of each stage explicitly, and ShaderEffect(device, ShaderPackageEXT) selects one vertex/fragment variant from a multi-language package per live device. They refuse with std::invalid_argument (bad stage, language or entry point) or CNA::ShaderCompilationExceptionEXT (no usable variant), and they live in the CNAEXT module, so they need it linked. The module’s own package ships GLSL desktop, GLSL ES, SPIR-V and WGSL payloads plus HLSL for two effects; no MSL or DXIL package ships, and no renderer answers true for Hlsl/Msl/Dxil in the typed route (so the Direct3D renderers use the string constructor). Offline, tools/shader_package/generate_shader_package.py turns GLSL into checked-in SPIR-V packages; the runtime never links shaderc or DXC. See Tutorial 151 for an end-to-end example.