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.setBlendStateProperty(...) — controls how incoming fragment colours are blended with the render target
• graphicsDevice.setDepthStencilStateProperty(...) — controls depth testing, depth writing, and stencil operations
• graphicsDevice.setRasterizerStateProperty(...) — controls face culling, fill mode, and scissor/depth bias
• graphicsDevice.getSamplerStatesProperty()[n] — per-slot texture filtering and address modes (up to 16 slots)

CNA's C++ spelling of XNA's C# properties is a getXProperty() / setXProperty() pair; there is no graphicsDevice.BlendState = ... member assignment. Each getter has a reference-returning form and each setter takes the state object by const reference and binds it: the device’s field then shares the object’s state and the object is frozen (see Assigned states are frozen).

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.

Assigned states are frozen

Assigning a state object to the device, or to a sampler slot, binds it. From then on every property setter of that object throws System::InvalidOperationException ("Cannot modify a BlendState after it has been bound to a GraphicsDevice."), exactly as in Microsoft XNA. This applies through every alias of the object, including the reference returned by graphicsDevice.getBlendStateProperty(), because the device's field and the object you assigned share one state. The static presets are bound from the start.

So configure a state completely before assigning it, and change state by assigning a different object. To derive a variation of a preset or of the current state, copy-construct it: copy construction creates a new, unbound, mutable state, while copy assignment creates an alias.

BlendState additiveOnlyRgb = BlendState::Additive;   // copy construction: mutable
additiveOnlyRgb.setColorWriteChannelsProperty(
    ColorWriteChannels::Red | ColorWriteChannels::Green | ColorWriteChannels::Blue);
graphicsDevice.setBlendStateProperty(additiveOnlyRgb);  // binds it; no more setters from here

// graphicsDevice.getBlendStateProperty().setColorSourceBlendProperty(Blend::One); // throws

Assigning a disposed state throws ObjectDisposedException, except that re-assigning the state that is already active is a no-op, as in XNA. The complete rules, what each renderer receives and when, and the per-renderer differences are on State objects: identity, binding and what reaches the renderer.

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.setBlendStateProperty(BlendState::AlphaBlend);

// Draw transparent geometry...

// Reset to opaque for the next pass
graphicsDevice.setBlendStateProperty(BlendState::Opaque);

Custom BlendState

When the presets are not sufficient, create a BlendState and configure it through its accessor pairs (setColorBlendFunctionProperty() and so on). The built-in presets are shared static const objects — copy one if you want a variation:

// Custom multiply blend
BlendState multiply;
multiply.setColorBlendFunctionProperty(BlendFunction::Add);
multiply.setColorSourceBlendProperty(Blend::DestinationColor);
multiply.setColorDestinationBlendProperty(Blend::Zero);
multiply.setAlphaBlendFunctionProperty(BlendFunction::Add);
multiply.setAlphaSourceBlendProperty(Blend::DestinationAlpha);
multiply.setAlphaDestinationBlendProperty(Blend::Zero);

graphicsDevice.setBlendStateProperty(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.setDepthStencilStateProperty(DepthStencilState::Default);

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

// 2D HUD / SpriteBatch pass
graphicsDevice.setDepthStencilStateProperty(DepthStencilState::None);

Custom DepthStencilState

Each field is a getXProperty() / setXProperty() pair on DepthStencilState (for example setDepthBufferEnableProperty(true), setStencilPassProperty(StencilOperation::Replace)). Two-sided stencil (setTwoSidedStencilModeProperty() and the CounterClockwiseStencil* members) is also available.

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’s DIRECTX9 renderer 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’s DIRECTX9 renderer matches it pixel-for-pixel.

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

Setting RasterizerState

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

// Double-sided geometry
graphicsDevice.setRasterizerStateProperty(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.getSamplerStatesProperty()[n], which returns a SamplerState& you assign to.

Built-in presets

Setting SamplerState

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

// Set slot 1 for a secondary (e.g. lightmap) texture
graphicsDevice.getSamplerStatesProperty()[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’s DIRECTX9 renderer 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’s DIRECTX9 renderer matches it pixel-for-pixel.

Viewport and ScissorRectangle

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

Viewport

graphicsDevice.getViewportProperty() / setViewportProperty() read and write a Viewport value that defines the sub-rectangle of the render target used for rendering and the depth range:

// Full-screen viewport with default depth range
graphicsDevice.setViewportProperty(Viewport(0, 0, screenWidth, screenHeight));

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

// A custom depth range is set through properties, not the constructor
Viewport vp(0, 0, screenWidth, screenHeight);
vp.setMinDepthProperty(0.0f);
vp.setMaxDepthProperty(1.0f);
graphicsDevice.setViewportProperty(vp);

The constructor parameters are (x, y, width, height); MinDepth and MaxDepth default to 0.0f and 1.0f and should rarely need to change. Binding a render target resets the viewport and scissor rectangle to that target's size.

ScissorRectangle

graphicsDevice.setScissorRectangleProperty(...) takes a Rectangle that clips rasterisation to a sub-region. It only takes effect when the active RasterizerState has ScissorTestEnable set to true:

// Enable scissor test in the rasterizer state
RasterizerState scissorRS;
scissorRS.setCullModeProperty(CullMode::CullCounterClockwiseFace);
scissorRS.setScissorTestEnableProperty(true);
graphicsDevice.setRasterizerStateProperty(scissorRS);

// Define the scissor region
graphicsDevice.setScissorRectangleProperty(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.setRasterizerStateProperty(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.setBlendStateProperty(BlendState::Opaque);
graphicsDevice.setDepthStencilStateProperty(DepthStencilState::Default);
graphicsDevice.setRasterizerStateProperty(RasterizerState::CullCounterClockwise);
graphicsDevice.getSamplerStatesProperty()[0] = SamplerState::LinearWrap;

DrawScene();

// --- 2D HUD pass ---
// SpriteBatch::Begin() applies its own blend, sampler, depth-stencil and
// rasterizer states to the device from its arguments (defaults: AlphaBlend,
// LinearClamp, None, CullCounterClockwise) and End() does NOT restore them --
// so pass the ones you want to Begin(), and reset the device afterwards.
spriteBatch.Begin(SpriteSortMode::Deferred, BlendState::AlphaBlend,
                  &SamplerState::LinearClamp, &DepthStencilState::None,
                  &RasterizerState::CullNone);
DrawHUD();
spriteBatch.End();

// --- the next frame's 3D pass must set its own state again (see above) ---

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.setBlendStateProperty(BlendState::Opaque);
graphicsDevice.setDepthStencilStateProperty(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.setBlendStateProperty(BlendState::AlphaBlend);
graphicsDevice.setDepthStencilStateProperty(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.setBlendStateProperty(BlendState::Additive);
graphicsDevice.setDepthStencilStateProperty(DepthStencilState::DepthRead);
graphicsDevice.setRasterizerStateProperty(RasterizerState::CullNone);
graphicsDevice.getSamplerStatesProperty()[0] = SamplerState::LinearClamp;

particleSystem.Draw(graphicsDevice, view, projection);

// Reset state for subsequent passes
graphicsDevice.setBlendStateProperty(BlendState::Opaque);
graphicsDevice.setDepthStencilStateProperty(DepthStencilState::Default);

Code examples

Example 1: Setting BlendState for HUD sprites

// Non-premultiplied PNG loaded from disk (straight alpha).
// Begin() applies the blend state to the device for the duration of the batch.
spriteBatch.Begin(SpriteSortMode::Deferred,
                  BlendState::NonPremultiplied);
spriteBatch.Draw(*hudTexture, Vector2(10.0f, 10.0f), Color::White);
spriteBatch.End();

// SpriteBatch does not restore the device state: set what the next pass needs.
graphicsDevice.setBlendStateProperty(BlendState::AlphaBlend);

Example 2: 3D opaque and transparent pass setup

void MyGame::Draw(const GameTime& gameTime)
{
    auto& graphicsDevice = getGraphicsDeviceProperty();
    graphicsDevice.Clear(Color::CornflowerBlue);

    // Opaque geometry
    graphicsDevice.setBlendStateProperty(BlendState::Opaque);
    graphicsDevice.setDepthStencilStateProperty(DepthStencilState::Default);
    graphicsDevice.setRasterizerStateProperty(RasterizerState::CullCounterClockwise);
    DrawOpaqueMeshes();

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

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

    // No Present() here: Game presents in EndDraw() after Draw() returns.
}

Example 3: Additive particle blending

// Particle system update + draw
void ParticleSystem::Draw(GraphicsDevice& gd, const Matrix& view, const Matrix& projection)
{
    gd.setBlendStateProperty(BlendState::Additive);
    gd.setDepthStencilStateProperty(DepthStencilState::DepthRead);
    gd.setRasterizerStateProperty(RasterizerState::CullNone);
    gd.getSamplerStatesProperty()[0] = SamplerState::LinearClamp;

    particleEffect->setViewProperty(view);
    particleEffect->setProjectionProperty(projection);

    for (auto& batch : particleBatches) {
        particleEffect->setWorldProperty(batch.Transform);
        particleEffect->setTextureProperty(batch.Texture);   // Texture2D*
        particleEffect->getCurrentTechniqueProperty()->getPassesProperty()[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.setCullModeProperty(CullMode::None);
wireframeState.setFillModeProperty(FillMode::WireFrame);
wireframeState.setMultiSampleAntiAliasProperty(false);

graphicsDevice.setRasterizerStateProperty(wireframeState);
DrawSceneWireframe();
graphicsDevice.setRasterizerStateProperty(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.getSamplerStatesProperty()[0] = SamplerState::LinearWrap;
graphicsDevice.getSamplerStatesProperty()[1] = SamplerState::LinearClamp;

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();

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