Chapter 13 SpriteBatch and 2D Rendering

SpriteBatch inherits GraphicsResource and offers five Begin() overloads of increasing specificity. The public contract defaults whatever the caller omits: Begin() alone defaults to SpriteSortMode::Deferred, BlendState::AlphaBlend, a LinearClamp sampler, no depth-stencil state, RasterizerState::CullCounterClockwise, and an identity transform; the fuller overloads let a caller override the sort mode and blend state, the three optional state objects (nullptr falls back to the same defaults), a custom Effect (nullptr falls back to an internal default SpriteEffect), and finally an explicit transform Matrix applied to every sprite in the batch before projection.

Draw itself has nine overloads: six are the canonical XNA forms — position-or-destination-rectangle, an optional source rectangle (represented as std::optional<Rectangle> rather than C#’s nullable Rectangle?), color, and progressively more control over rotation, origin, scale (as either a uniform float or a non-uniform Vector2), SpriteEffects, and layer depth — and three are CNAEXT raw texture-and-rectangle convenience forms layered on top. DrawString adds six more overloads (string or StringBuilder, each in a simple 4-argument form, a uniform-scale 9-argument form, and a non-uniform-scale (Vector2 scale) 9-argument form).

The nine Draw overloads split cleanly into two families by their second parameter — a Vector2 position (four overloads, increasingly parameterized) or a Rectangle destinationRectangle that scales the texture to fit (three overloads) — plus the two CNAEXT raw float x, float y convenience forms already noted. Every XNA-compatible overload takes an explicit Color tint — there is no overload that omits it, unlike the CNAEXT convenience forms. The table below abbreviates each overload’s parameter names for width (tex for texture, pos for position, and so on) — the full, exact parameter names for every overload are shown in the parameterized example below the table.

The parameterized overloads share origin, a point in texture space (not screen space) that both the rotation pivot and the drawn position are measured relative to. Rotating a $64\times 64$ sprite around its own center, rather than its top-left corner, means passing that texture’s own center as origin:

Passing Vector2::Zero for origin instead — the easy mistake, since it is also the type’s default-constructed value — rotates the sprite around its top-left corner, which reads as the sprite “orbiting” spritePosition in a circle rather than spinning in place; the visual symptom is easy to misdiagnose as a rotation-math bug when the actual cause is simply the wrong origin.

The Vector2-position overloads do not preserve sub-pixel destinations. Their shared queue record stores an integer Rectangle; CNA validates the position and scaled size, then converts each floating component with truncation toward zero. Thus (10.9f, 4.9f) and (10.1f, 4.1f) both enter every renderer as (10,4). This is a shared SpriteBatch fidelity difference from XNA, not a renderer-specific rasterization rule.

Text follows a subtly different policy. DrawString() computes each transformed glyph destination in floating point and rounds it to the nearest integer before storing the same rectangle shape. A sprite and a glyph submitted at the same fractional coordinate can therefore land on adjacent pixels. Both conversion helpers reject non-finite values and results outside the signed 32-bit range; the safety check prevents undefined conversion, but does not restore the lost fractional position. Code that depends on smooth sub-pixel camera motion must account for this quantization above the renderer layer.

XNA 4.0 ran exclusively on Direct3D 9, whose rasterizer places texel centers at integer pixel coordinates rather than pixel centers — the well-known “D3D9 half-pixel offset” problem, notorious enough that porting guides for other 2D APIs still warn about it decades later. SpriteBatch’s own shared, renderer-agnostic SpriteBatch.cpp carries no trace of this compensation at all, which is exactly correct behavior for every renderer built on a modern API (EasyGL, Vulkan, BGFX, D3D11, D3D12, WebGPU): none of them share Direct3D 9’s own texel-center convention, so there is nothing to compensate for, and adding an offset unconditionally would introduce an error on every renderer that does not need one. On D3D9, the compensation lives one level down, inside D3D9SpriteBatchRenderer::BuildMatrixTransformEXT specifically — baked directly into the projection matrix SpriteBatch constructs, the same technique the classic XNA 4.0 D3D9 fix itself used:

Verification against the XNA 4.0 oracle (Chapter 28) exposed a mutation-testing trap: two independently designed tests could not detect whether the offset was present. A $1\times 1$ test texture cannot detect it, because the half-pixel offset shifts which texel a given screen pixel samples, not where a sprite’s geometric edges land on screen — a texture with only one texel has nothing else to shift onto, so removing the offset entirely changes nothing a one-texel-texture test can observe. Separately, sampling only at a drawn rectangle’s own quadrant-center points misses it too, for the same underlying reason: those points are exactly where a coarse boundary check happens to line up regardless of the sub-pixel shift. Both traps were only caught by deliberately mutation-testing the passing test itself — commenting out the two M41 / M42 lines above and re-running the existing check suite, which still passed with the fix removed. The replacement samples a specific internal texel boundary a rotated/flipped sprite’s own blended edge produces — a pixel confirmed to shift from one exact, named RGB value to another under the same mutation, the first check in the suite that changed under the mutation. A regression test must fail when its protected behavior is removed; mutation testing establishes that property directly.

SpriteSortMode has five values: Deferred, Immediate, Texture, BackToFront, and FrontToBack. Only the latter two honor layerDepth; the other modes ignore it by design.

Texture mode applies a stable sort to raw texture pointers. The TextureGroupsDrawsByTextureAndPreservesGroupOrder test establishes two properties: sprites sharing a texture become adjacent, and their relative submission order is preserved. The order between different texture groups is unspecified because it depends on pointer order. Overlapping sprites must therefore not use Texture mode when the A-versus-B group order matters. A separate SDL Renderer pixel test checks that the reordered draw calls bind the intended textures; a mock renderer can establish grouping but cannot observe that renderer-side binding.

The BlendState passed to Begin()—or BlendState::AlphaBlend when omitted—remains assigned to GraphicsDevice.BlendState after End(). This matches FNA. A following 3D draw inherits that mode unless the game assigns another blend state:

SpriteFont is not a GraphicsResource. It owns a texture atlas, glyph bounds, cropping data, a character set, line spacing, character spacing, kerning data, and an optional default character. Its constructor is CNAEXT and public. Microsoft XNA’s SpriteFont constructor is internal, reachable only from the compiled .xnb content pipeline’s SpriteFontReader; CNA lacks that reader and exposes construction instead.

MeasureString exists for both string and StringBuilder. The latter forwards to the string implementation, a simplification available in C++ because there is no garbage-collection-pressure argument against sharing code here. A trailing "\n" adds a second empty line to the measured height: Y = 2 $\times$ LineSpacing. Both the newline handler and the loop’s final height addition run, matching Microsoft XNA’s result.

For text encoding, CNA’s String is UTF-8 (std::string), and SpriteFont / SpriteBatch decode each glyph via an internal DecodeUtf8CodePoint helper. Because charcs (the glyph-key type, per Chapter 3’s type-alias table) is 16 bits wide, only Basic Multilingual Plane code points can serve as glyph keys. An invalid or truncated UTF-8 sequence decodes to ’?’; the byte index still advances by at least one.

This example uses MeasureString to center HUD text before calling the simplest DrawString overload:

docs/spritefont-support.md verifies the property surface, MeasureString, single- and multi-glyph placement, newline handling, default-character fallback, single-axis flip, and rotation/scale as pixel-correct on both SDL_Renderer and EasyGL. Vulkan and BGFX reuse the shared layout logic, but that source relationship is not a renderer-engaged or pixel oracle. Their SpriteFont paths have not been independently re-verified, as also recorded in docs/graphics-renderer-feature-matrix.md. Combined-axis flip is not representable on any renderer at all, for the SpriteEffects reason above.

The class is named SpriteBatch, and SpriteSortMode::Deferred — the default — sounds like it defers submission to build one large GPU-side batch. Reading SpriteBatch.cpp’s own pushSprite / flushSingle / flushBatch shows a narrower design with performance implications for code accustomed to GPU-side draw-call coalescing:

Immediate sends every Draw() directly to flushSingle; it is the only mode in which renderer state changes between sprite submissions retain their exact position. The other modes queue and optionally sort, but flushBatch() still calls the renderer once per sprite. CNA’s batch therefore coalesces sort decisions, not GPU draw calls: roughly one thousand sprites produce roughly one thousand renderer submissions.

pushSprite also rejects a disposed texture with ObjectDisposedException. This is CNA-specific hardening. Without the guard, a disposed Texture2D would leave a null renderer pointer for GetRenderer() to dereference.

§13.8 above already named the raw ingredients — kerning_, a Vector3 per glyph packing (leftBearing, width, rightBearing) — but MeasureString and DrawString are two independent implementations of the identical walk, in two different files (SpriteFont.cpp and SpriteBatch.cpp respectively), and it is worth confirming directly, rather than assuming, that they agree. Reading SpriteBatch::DrawString shows the same three-line shape, glyph by glyph:

Only the first glyph applies std::abs() to its left bearing. This prevents a negative initial bearing from moving the whole string before position; later negative bearings can still tuck a glyph toward its predecessor. MeasureString (§13.8) applies the same rule, so measured and drawn placement agree.

The focused EasyGL fixture is easygl_spritefont_multiglyph_spacing_test.cpp. It exercises the non-first-glyph branch. Its two $8\times 8$ glyphs have zero-valued kerning (0, 8, 0) and spacing = 4.0f, making placement checkable in whole pixels:

Drawing "AB" at position = (2, 2) therefore places ’A’ at screen $x\in [2,10)$ and ’B’ at $x\in [14,22)$ — an exact 4-pixel gap at $x\in [10,14)$ that must stay background-colored for the test to pass. A sample inside the gap establishes that spacing was applied, while each glyph’s distinct fill color (white for ’A’, green for ’B’) at its expected position rules out an index mix-up between the two glyphs — a bug shape that a single-glyph test, no matter how many pixels it samples, structurally cannot detect at all, since there would be no second glyph to place at the wrong index.

Calling Begin() a second time without an intervening End() — or calling End() before any Begin() at all — is a real, commonly-hit misuse case (a forgotten End() inside an early-return branch, most often), and CNA does throw for it. Reading the real implementation shows exactly what it throws, though, and it is not the type a reader would reasonably expect from real XNA:

Real XNA’s own SpriteBatch.Begin() throws InvalidOperationException for the identical misuse, and System’s own InvalidOperationException type exists in this codebase, real and used elsewhere (Chapter 16 and others cite it directly) — but SpriteBatch itself throws a plain std::runtime_error here instead, confirmed by reading both guard sites directly rather than assumed from the message text alone. The two exception hierarchies do not meet until std::exception itself: InvalidOperationException derives from SystemException, which derives from System::Exception — a hierarchy entirely separate from std::runtime_error’s own std::exception lineage, confirmed by reading InvalidOperationException.hpp / SystemException.hpp directly.

This is a narrower, more precisely scoped gap than “wrong error message” or “doesn’t throw at all”: the throw itself is correct and reliable (a real, hittable misuse genuinely does terminate the batch and report a real diagnostic message), and any code written against a generic catch (const std::exception&) handler — the common, safe default in ordinary C++ — catches it exactly as expected, message text and all. The gap only bites a porting engineer who specifically wrote a typed InvalidOperationException catch clause around SpriteBatch usage, reasonably expecting the same exception hierarchy this book’s other chapters confirm many other CNA classes do use faithfully for the identical real-XNA exception type.

SpriteBatch has broad cross-renderer coverage because each renderer must expose it. The evidence is not uniform: shared queue logic, renderer engagement, targeted pixel tests, and XNA-oracle comparisons establish different claims. It is a practical portability baseline for 2D ports, but the implementation-family matrix and open limitations above still apply.