Batch Renderer
Um batcher de sprites que ordena os sprites pendentes e submete um único draw indexado por frame, mais o atlas de texturas com empacotamento em prateleiras que o alimenta.
Visão Geral#
O batch renderer acumula sprites, ordena-os por radix sort com uma chave de 32 bits e emite um
único drawIndexed por frame. Hoje é um componente isolado: só os testes o exercitam e o
renderer de cena 3D não submete através dele.
- Batching — todos os sprites pendentes viram um único buffer de quads
- Radix sort — ordena por layer → textura → profundidade antes de construir o buffer
- Texture atlas — um bind de textura para todos os sprites que usam o atlas
API#
namespace Caffeine::Render {
struct SpriteVertex { // 24 bytes
Vec3 position;
Vec2 texcoord;
u32 tint; // RGBA8 empacotado
};
class BatchRenderer {
public:
static constexpr u32 MAX_SPRITES_PER_BATCH = 32768;
explicit BatchRenderer(RHI::RenderDevice* device);
void beginFrame(); // limpa sprites pendentes + 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); // só width/height são usados
void pack(); // prateleiras, mais alto primeiro
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#
Não existe persistent mapped buffer. O endFrame constrói vectores de vértices e índices em
CPU, cria um buffer BufferUsage::Vertex e outro BufferUsage::Index, faz bind, desenha e
destrói ambos antes de retornar. Sprites que partilham o draw evitam um draw por sprite, mas o
upload continua a acontecer em cada frame.
Chave de ordenação#
sortKey = ((layer + 128) & 0xFF) << 24
| (textureId & 0xFFF) << 12
| (depth * 0xFFF)
A divisão de campos existe para o layer dominar, depois a textura e por fim a profundidade. O
submitSprite passa actualmente layer 0 e textura 0 e tira a profundidade de
worldTransform(2, 3), pelo que na prática a ordenação é apenas por profundidade. A chave é
consumida por um radix sort LSD de 4 passagens.
Utilização#
// ── 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();
// ── Por 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 quando há pelo menos um sprite submetido
Um sprite é um quad unitário centrado na origem, transformado por worldTransform. As UVs vêm
do atlas quando existe e está empacotado; caso contrário cobrem a textura inteira.
Decisões de design#
| Decisão | Justificação |
|---|---|
| Um buffer de quads por frame | Um único draw indexado em vez de um por sprite |
| Radix sort | O(n) para a ordem dos sprites do frame |
| Texture atlas | Um bind para todos os sprites do batch |
SpriteVertex de 24 bytes |
Tint RGBA8 empacotado, sem padding |
Limites actuais#
- O batch não é dividido por textura nem por layer: vai tudo num draw, pelo que é preciso um atlas para ver mais do que uma imagem.
- Sem persistent mapping nem double buffering; os buffers são criados e destruídos a cada frame.
- O
tintestá fixo a branco nosubmitSprite. - Ainda não está integrado com o renderer de cena 3D nem com o sistema ECS de sprites.