Batch Renderer
A sprite batcher that sorts pending sprites and submits one indexed draw per frame, plus the shelf-packing texture atlas that feeds it.
Overview#
The batch renderer collects sprites, radix-sorts them by a 32-bit key and emits a single
drawIndexed for the frame. Today it is a standalone component: only the tests exercise it,
and the 3D scene renderer does not submit through it.
- Batching — all pending sprites become one quad buffer
- Radix sort — orders sprites by layer → texture → depth before building the buffer
- Texture atlas — one texture bind for every sprite that uses the packed atlas
API#
namespace Caffeine::Render {
struct SpriteVertex { // 24 bytes
Vec3 position;
Vec2 texcoord;
u32 tint; // RGBA8 packed
};
class BatchRenderer {
public:
static constexpr u32 MAX_SPRITES_PER_BATCH = 32768;
explicit BatchRenderer(RHI::RenderDevice* device);
void beginFrame(); // clears pending sprites + stats
void setCamera(const Camera2D& camera);
void setAtlas(const TextureAtlas* atlas);
void submitSprite(const Mat4& worldTransform, const ECS::Sprite& sprite);
void endFrame(RHI::CommandBuffer* cmd); // sort → build → upload → draw
struct FrameStats {
u32 totalSprites = 0;
u32 totalBatches = 0;
u32 drawCalls = 0;
u32 verticesUploaded = 0;
};
FrameStats lastFrameStats() const;
};
class TextureAtlas {
public:
explicit TextureAtlas(u32 width, u32 height);
bool add(const char* name, Rect2D sourceRegion); // only width/height are used
void pack(); // shelf packing, tallest first
bool isPacked() const;
Vec4 getUV(const char* name) const; // Vec4(u0, v0, u1, v1)
struct PixelData { const u8* pixels; u32 width; u32 height; u32 byteSize; };
PixelData exportImage() const;
u32 count() const;
u32 usedArea() const;
u32 totalArea() const;
f32 utilization() const;
};
} // namespace Caffeine::Render
Buffers#
There is no persistent mapped buffer. endFrame builds CPU vertex and index vectors, creates
a BufferUsage::Vertex and a BufferUsage::Index buffer, binds them, draws, and destroys
both buffers before returning. Sprites that share a draw therefore avoid per-sprite draws,
but the upload still happens every frame.
Sort key#
sortKey = ((layer + 128) & 0xFF) << 24
| (textureId & 0xFFF) << 12
| (depth * 0xFFF)
The field split exists so layer dominates, then texture, then depth. submitSprite currently
passes layer 0 and texture 0 and takes depth from worldTransform(2, 3), so in practice
the sort orders sprites by depth only. The key is consumed by a 4-pass LSD radix sort.
Usage#
// ── Setup ──────────────────────────────────────────────────────
Caffeine::Render::BatchRenderer renderer(&device);
Caffeine::Render::TextureAtlas atlas(2048, 2048);
atlas.add("hero_idle", { {0, 0}, {64, 64} });
atlas.add("hero_walk_0", { {64, 0}, {64, 64} });
atlas.add("tile_grass", { {128, 0}, {16, 16} });
atlas.pack();
// ── Per frame ─────────────────────────────────────────────────
renderer.beginFrame();
renderer.setAtlas(&atlas);
renderer.setCamera(camera2D);
ECS::ComponentQuery spriteQuery;
spriteQuery.with<ECS::Sprite>();
world.forEach<ECS::Sprite>(spriteQuery, [&](ECS::Entity, ECS::Sprite& sprite) {
renderer.submitSprite(Mat4::translation(0, 0, 0), sprite);
});
auto* cmd = device.beginFrame();
renderer.endFrame(cmd);
device.endFrame(cmd);
// ── Stats ─────────────────────────────────────────────────────
auto stats = renderer.lastFrameStats();
// stats.drawCalls == 1 when at least one sprite was submitted
A sprite is a unit quad centred on the origin, transformed by worldTransform. Its UVs come
from the atlas when one is set and packed, otherwise they cover the whole texture.
Design decisions#
| Decision | Rationale |
|---|---|
| One quad buffer per frame | A single indexed draw instead of one per sprite |
| Radix sort | O(n) for the per-frame sprite order |
| Texture atlas | One bind for every sprite in the batch |
SpriteVertex 24 bytes |
Packed RGBA8 tint, no padding |
Current limits#
- The batch is not split by texture or layer: everything goes into one draw, so a sprite atlas is required to see more than one image.
- No persistent mapping and no double buffering; buffers are created and destroyed each frame.
tintis fixed to white insubmitSprite.- Not integrated with the 3D scene renderer or the ECS sprite system yet.