Graphics State

Microsoft::Xna::Framework::Graphics state objects — BlendState, DepthStencilState, RasterizerState, SamplerState

Overview

All render state in CNA follows the XNA 4.0 immutable state-object pattern. Rather than toggling individual render states through a stateful device API, you create a state object (either a built-in preset or a custom instance), then assign it to the appropriate property on GraphicsDevice before issuing draw calls.

The four state-object types and where they live on GraphicsDevice:

• graphicsDevice.BlendState — controls how incoming fragment colours are blended with the render target
• graphicsDevice.DepthStencilState — controls depth testing, depth writing, and stencil operations
• graphicsDevice.RasterizerState — controls face culling, fill mode, and scissor/depth bias
• graphicsDevice.SamplerStates[n] — per-slot texture filtering and address modes (up to 16 slots)

State assigned to GraphicsDevice applies to every draw call that follows until you change it again. A common mistake is forgetting to reset state between rendering passes — for example, leaving BlendState::Additive active when starting the opaque geometry pass. Always set state explicitly at the beginning of each logical pass.

BlendState

BlendState describes how the output of a pixel shader (the source) is combined with the existing colour already in the render target (the destination). CNA provides four built-in presets that cover the most common use cases.

Built-in presets

Setting BlendState

// Use a built-in preset
graphicsDevice.BlendState = BlendState::AlphaBlend;

// Draw transparent geometry...

// Reset to opaque for the next pass
graphicsDevice.BlendState = BlendState::Opaque;

Custom BlendState

When the presets are not sufficient, create a BlendState and configure its fields directly:

// Custom multiply blend
BlendState multiply;
multiply.ColorBlendFunction      = BlendFunction::Add;
multiply.ColorSourceBlend        = Blend::DestinationColor;
multiply.ColorDestinationBlend   = Blend::Zero;
multiply.AlphaBlendFunction      = BlendFunction::Add;
multiply.AlphaSourceBlend        = Blend::One;
multiply.AlphaDestinationBlend   = Blend::Zero;

graphicsDevice.BlendState = multiply;

DepthStencilState

DepthStencilState controls whether incoming fragments are tested against the depth buffer and whether they write their depth value back. It also governs stencil operations for masking and outlining effects.

Built-in presets

Setting DepthStencilState

// Standard 3D opaque pass
graphicsDevice.DepthStencilState = DepthStencilState::Default;

// Transparent 3D pass (test but do not write depth)
graphicsDevice.DepthStencilState = DepthStencilState::DepthRead;

// 2D HUD / SpriteBatch pass
graphicsDevice.DepthStencilState = DepthStencilState::None;

Custom DepthStencilState

RasterizerState

RasterizerState controls how triangles are converted to fragments. The most commonly adjusted settings are face culling and fill mode.

Built-in presets

What each cull mode does to one triangle

The three frames below come from CNA's XNA oracle corpus (tools/xna-oracle/) — they are the real Microsoft XNA 4.0 runtime's own output, which CNA's DIRECTX9 renderer is diffed against at --tolerance 0. A single clockwise-wound triangle is drawn under each CullMode. See the oracle corpus for details.

CullMode::None — both faces rasterise, so the triangle is visible. Real XNA 4.0 output; CNA matches it pixel-for-pixel.

CullClockwiseFace — the triangle's winding marks it as back-facing, so it disappears entirely. Real XNA 4.0 output; CNA matches it pixel-for-pixel.

CullCounterClockwiseFace — the default; this triangle is front-facing and survives. Real XNA 4.0 output; CNA matches it pixel-for-pixel.

Setting RasterizerState

// Default for 3D (already the default on GraphicsDevice)
graphicsDevice.RasterizerState = RasterizerState::CullCounterClockwise;

// Double-sided geometry
graphicsDevice.RasterizerState = RasterizerState::CullNone;

Custom RasterizerState

SamplerState

SamplerState describes how textures are sampled — the filtering algorithm applied when a texture is magnified or minified, and how texture coordinates outside the [0, 1] range are handled. Up to 16 independent sampler slots are available, addressed via graphicsDevice.SamplerStates[n].

Built-in presets

Setting SamplerState

// Set slot 0 for the primary texture
graphicsDevice.SamplerStates[0] = SamplerState::LinearClamp;

// Set slot 1 for a secondary (e.g. lightmap) texture
graphicsDevice.SamplerStates[1] = SamplerState::LinearWrap;

Custom SamplerState

Wrap versus Mirror addressing

The difference between the two repeating address modes is easiest to see on a two-colour texture sampled past U = 1. Both frames are genuine Microsoft XNA 4.0 runtime output from CNA's oracle corpus (tools/xna-oracle/), diffed against CNA's DIRECTX9 renderer at --tolerance 0.

TextureAddressMode::Wrap — the texture restarts at every integer U, so the red-then-green pattern simply repeats. Real XNA 4.0 output; CNA matches it pixel-for-pixel.

TextureAddressMode::Mirror — every other repeat is flipped, so the two green halves meet and form one continuous block. Real XNA 4.0 output; CNA matches it pixel-for-pixel.

Viewport and ScissorRectangle

Two additional device properties control which region of the render target receives output.

Viewport

graphicsDevice.Viewport is a Viewport struct that defines the sub-rectangle of the render target used for rendering and the depth range:

// Full-screen viewport with default depth range
graphicsDevice.Viewport = Viewport(0, 0, screenWidth, screenHeight, 0.0f, 1.0f);

// Split-screen: render to the left half
graphicsDevice.Viewport = Viewport(0, 0, screenWidth / 2, screenHeight, 0.0f, 1.0f);

The constructor parameters are (x, y, width, height, minDepth, maxDepth). minDepth and maxDepth default to 0.0f and 1.0f and should rarely need to change.

ScissorRectangle

graphicsDevice.ScissorRectangle is a Rectangle that clips rasterisation to a sub-region. It only takes effect when RasterizerState.ScissorTestEnable is true:

// Enable scissor test in the rasterizer state
RasterizerState scissorRS;
scissorRS.CullMode          = CullMode::CullCounterClockwiseFace;
scissorRS.ScissorTestEnable = true;
graphicsDevice.RasterizerState = scissorRS;

// Define the scissor region
graphicsDevice.ScissorRectangle = Rectangle(100, 100, 400, 300);

// Only pixels inside (100,100)-(500,400) are written
graphicsDevice.DrawPrimitives(PrimitiveType::TriangleList, 0, triangleCount);

// Disable scissor test afterwards
graphicsDevice.RasterizerState = RasterizerState::CullCounterClockwise;

Common patterns

Pattern 1: 3D scene with 2D HUD

The most common pattern in any game: render the 3D world, then overlay a 2D HUD using SpriteBatch. State must be switched explicitly between the two passes.

// --- 3D world pass ---
graphicsDevice.BlendState        = BlendState::Opaque;
graphicsDevice.DepthStencilState = DepthStencilState::Default;
graphicsDevice.RasterizerState   = RasterizerState::CullCounterClockwise;
graphicsDevice.SamplerStates[0]  = SamplerState::LinearWrap;

DrawScene(graphicsDevice);

// --- 2D HUD pass ---
// SpriteBatch sets its own blend and depth state internally,
// but setting them explicitly before Begin() is good practice.
graphicsDevice.BlendState        = BlendState::AlphaBlend;
graphicsDevice.DepthStencilState = DepthStencilState::None;
graphicsDevice.RasterizerState   = RasterizerState::CullNone;
graphicsDevice.SamplerStates[0]  = SamplerState::LinearClamp;

spriteBatch.Begin();
DrawHUD(spriteBatch);
spriteBatch.End();

Pattern 2: Opaque then transparent 3D objects

Opaque objects should always be drawn before transparent objects. After the opaque pass, switch to DepthRead and sort transparent objects back-to-front before drawing.

// --- Opaque pass ---
graphicsDevice.BlendState        = BlendState::Opaque;
graphicsDevice.DepthStencilState = DepthStencilState::Default;

for (auto& mesh : opaqueMeshes)
    mesh.Draw(graphicsDevice, effect);

// --- Transparent pass ---
// Sort transparent objects back-to-front from the camera
std::sort(transparentMeshes.begin(), transparentMeshes.end(),
    [&](const auto& a, const auto& b) {
        return a.DistanceTo(camera) > b.DistanceTo(camera);
    });

graphicsDevice.BlendState        = BlendState::AlphaBlend;
graphicsDevice.DepthStencilState = DepthStencilState::DepthRead;

for (auto& mesh : transparentMeshes)
    mesh.Draw(graphicsDevice, effect);

Pattern 3: Additive particle system

Particle effects such as fire, sparks, and laser bolts accumulate light additively. Depth writing must be disabled so particles do not occlude each other based on draw order.

graphicsDevice.BlendState        = BlendState::Additive;
graphicsDevice.DepthStencilState = DepthStencilState::DepthRead;
graphicsDevice.RasterizerState   = RasterizerState::CullNone;
graphicsDevice.SamplerStates[0]  = SamplerState::LinearClamp;

particleSystem.Draw(graphicsDevice, camera);

// Reset state for subsequent passes
graphicsDevice.BlendState        = BlendState::Opaque;
graphicsDevice.DepthStencilState = DepthStencilState::Default;

Code examples

Example 1: Setting BlendState for HUD sprites

// Non-premultiplied PNG loaded from disk (straight alpha)
graphicsDevice.BlendState = BlendState::NonPremultiplied;

spriteBatch.Begin(SpriteSortMode::Deferred,
                  BlendState::NonPremultiplied);
spriteBatch.Draw(hudTexture, Vector2(10.0f, 10.0f), Color::White);
spriteBatch.End();

// Return to premultiplied alpha for the next SpriteBatch call
graphicsDevice.BlendState = BlendState::AlphaBlend;

Example 2: 3D opaque and transparent pass setup

void Game::Draw(GameTime gameTime)
{
    graphicsDevice.Clear(Color::CornflowerBlue);

    // Opaque geometry
    graphicsDevice.BlendState        = BlendState::Opaque;
    graphicsDevice.DepthStencilState = DepthStencilState::Default;
    graphicsDevice.RasterizerState   = RasterizerState::CullCounterClockwise;
    DrawOpaqueMeshes();

    // Transparent geometry (test depth, do not write)
    graphicsDevice.BlendState        = BlendState::AlphaBlend;
    graphicsDevice.DepthStencilState = DepthStencilState::DepthRead;
    DrawTransparentMeshes();

    // 2D overlay
    graphicsDevice.DepthStencilState = DepthStencilState::None;
    spriteBatch.Begin();
    DrawHUD();
    spriteBatch.End();
}

Example 3: Additive particle blending

// Particle system update + draw
void ParticleSystem::Draw(GraphicsDevice& gd, const Camera& cam)
{
    gd.BlendState        = BlendState::Additive;
    gd.DepthStencilState = DepthStencilState::DepthRead;
    gd.RasterizerState   = RasterizerState::CullNone;
    gd.SamplerStates[0]  = SamplerState::LinearClamp;

    particleEffect->SetView(cam.View());
    particleEffect->SetProjection(cam.Projection());

    for (auto& batch : particleBatches) {
        particleEffect->SetWorld(batch.Transform);
        particleEffect->SetTexture(batch.Texture);
        particleEffect->CurrentTechnique->Passes[0]->Apply();
        gd.DrawPrimitives(PrimitiveType::TriangleList,
                          batch.VertexOffset, batch.PrimitiveCount);
    }
}

Example 4: Custom RasterizerState (no culling + wireframe)

// Build a custom rasterizer state for debug wireframe rendering.
// WireFrame is not honoured by every renderer — verify it visually
// against the renderer this build was configured with.
RasterizerState wireframeState;
wireframeState.CullMode             = CullMode::None;
wireframeState.FillMode             = FillMode::WireFrame;
wireframeState.MultiSampleAntiAlias = false;

graphicsDevice.RasterizerState = wireframeState;
DrawSceneWireframe();
graphicsDevice.RasterizerState = RasterizerState::CullCounterClockwise;

Example 5: Per-slot sampler state for multi-texture

// DualTextureEffect uses two texture slots.
// Slot 0: diffuse texture with linear wrap (tiling surface)
// Slot 1: lightmap with linear clamp (unique per-object UV)
graphicsDevice.SamplerStates[0] = SamplerState::LinearWrap;
graphicsDevice.SamplerStates[1] = SamplerState::LinearClamp;

auto effect = std::make_shared<DualTextureEffect>(graphicsDevice);
effect->SetWorld(Matrix::Identity);
effect->SetView(camera.View());
effect->SetProjection(camera.Projection());
effect->SetTexture(diffuseTexture);
effect->SetTexture2(lightmapTexture);
effect->CurrentTechnique->Passes[0]->Apply();

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