SpriteBatch

Microsoft::Xna::Framework::Graphics — 2D sprite batching, text rendering, and blend control

Overview

SpriteBatch is the primary 2D drawing class in the Microsoft::Xna::Framework::Graphics namespace. It collects 2D draw calls issued between a Begin()/End() pair and submits them to the GPU as a single batched draw, dramatically reducing API overhead compared to drawing each sprite individually.

The fundamental usage pattern is:

1. Call Begin() once to configure blend state, sort mode, and any optional transform.
2. Call Draw() or DrawString() any number of times to queue sprites and text.
3. Call End() to flush the batch and issue the GPU draw calls.

SpriteBatch is backend-agnostic. On SDL_RENDERER it maps draw calls directly to SDL3 renderer commands. On EASYGL, BGFX, and VULKAN it generates textured quads fed through the internal SpriteEffect with an orthographic projection covering the back-buffer dimensions.

Begin() overloads

All overloads open a batch. Parameters not supplied take their XNA 4.0 defaults. A second call to Begin() without a preceding End() is an error.

SpriteSortMode

Controls the order in which batched sprites are drawn relative to each other. Choose a mode that balances visual correctness against throughput for your use case.

Draw() overloads

All Draw() overloads accept a Texture2D as the first argument. Omitted optional parameters take XNA 4.0 defaults (rotation = 0, origin = Vector2::Zero, scale = 1, effects = SpriteEffects::None, layerDepth = 0).

DrawString() overloads

DrawString() renders text using a SpriteFont loaded through the ContentManager. In CNA the text parameter accepts either a standard std::string or the String type alias provided by the sharp-runtime layer.

SpriteEffects

The SpriteEffects enum controls axis-aligned flipping of a sprite around its origin. Values can be combined with the bitwise OR operator.

BlendState presets

CNA ships the same four BlendState static presets as XNA 4.0. Pass one to Begin() to control how each sprite's colour is composited over existing framebuffer contents.

Code examples

1. Basic 2D sprite draw

The minimal Begin / Draw / End cycle. spriteBatch is typically stored as a member of your Game subclass and created once in LoadContent().

// In LoadContent():
spriteBatch = std::make_shared<SpriteBatch>(GraphicsDevice);
playerTexture = Content.Load<Texture2D>("player");

// In Draw():
spriteBatch->Begin();
spriteBatch->Draw(playerTexture, Vector2(100.0f, 200.0f), Color::White);
spriteBatch->End();

2. Draw with rotation and scale

Use the full Vector2-position overload to rotate a sprite around its centre and scale it uniformly.

float rotation = MathHelper::ToRadians(45.0f);   // 45 degrees
Vector2 origin(playerTexture->Width() / 2.0f,
               playerTexture->Height() / 2.0f);  // centre pivot
float scale = 2.0f;

spriteBatch->Begin();
spriteBatch->Draw(
    playerTexture,
    Vector2(400.0f, 300.0f),    // screen position
    std::nullopt,               // sourceRect: full texture
    Color::White,               // tint
    rotation,                   // rotation in radians
    origin,                     // pivot point
    scale,                      // uniform scale
    SpriteEffects::None,
    0.0f);                      // layerDepth
spriteBatch->End();

3. DrawString example

Load a SpriteFont via ContentManager, then call DrawString() to render text.

// In LoadContent():
auto font = Content.Load<SpriteFont>("fonts/Arial20");

// In Draw():
spriteBatch->Begin();
spriteBatch->DrawString(
    font,
    "Score: " + std::to_string(score),
    Vector2(16.0f, 16.0f),
    Color::Yellow);
spriteBatch->End();

4. Additive blending for particles

Switch to BlendState::Additive so particle sprites brighten the scene rather than covering it.

spriteBatch->Begin(SpriteSortMode::Deferred, BlendState::Additive);

for (auto& particle : particles) {
    spriteBatch->Draw(
        sparkTexture,
        particle.Position,
        std::nullopt,
        Color(255, 200, 100, particle.Alpha),
        particle.Rotation,
        sparkOrigin,
        particle.Scale,
        SpriteEffects::None,
        0.0f);
}

spriteBatch->End();

5. Transform matrix camera (2D scrolling)

Pass a Matrix to Begin() to apply a global transform to every sprite in the batch. This is the standard XNA pattern for 2D camera scroll and zoom.

// Build a camera matrix: translate by -cameraPosition, scale by zoom
Matrix cameraTransform =
    Matrix::CreateTranslation(-cameraPosition.X, -cameraPosition.Y, 0.0f) *
    Matrix::CreateScale(zoom, zoom, 1.0f) *
    Matrix::CreateTranslation(
        GraphicsDevice->Viewport().Width  / 2.0f,
        GraphicsDevice->Viewport().Height / 2.0f,
        0.0f);

spriteBatch->Begin(
    SpriteSortMode::Deferred,
    BlendState::AlphaBlend,
    nullptr,            // SamplerState  (default)
    nullptr,            // DepthStencilState (default)
    nullptr,            // RasterizerState (default)
    nullptr,            // Effect (built-in SpriteEffect)
    cameraTransform);   // <-- camera matrix applied to all draws

// Draw world tiles, characters, etc. in world-space coordinates
for (auto& tile : world.VisibleTiles(cameraPosition)) {
    spriteBatch->Draw(tileSheet, tile.WorldPosition, tile.SourceRect, Color::White);
}

spriteBatch->End();