---
name: sprite_batch
kind: function
lang: cpp
domain: gfx
version: "0.1.0"
purity: impure
signature: "sprite_batch_create(int cap=4096) -> SpriteBatch; sprite_batch_begin/draw/end"
description: "Batched textured quad renderer sobre sokol_gfx. Begin/draw/end con auto-flush por atlas change o capacity full. Vertex layout pos+uv+color, alpha blending estandar, GLSL 330 / GLES 300. Issue 0072b runtime gamedev — base de plataformeros, top-down, UI sprites."
tags: [gamedev, gfx, sokol, sprite, batch, 2d]
uses_functions:
  - sokol_setup_cpp_gfx
uses_types:
  - Rect_cpp_core
  - Color_cpp_core
returns: []
returns_optional: false
error_type: "error_go_core"
imports: []
example: |
  fn::gfx::SpriteBatch b = fn::gfx::sprite_batch_create(4096);
  // por frame, dentro de un sg_pass:
  fn::gfx::sprite_batch_begin(b, view_proj);
  fn::gfx::sprite_batch_draw(b, atlas_img, 1024, 1024,
    {0,0,32,32}, {100,100,32,32}, fn::math2d::Color::white());
  fn::gfx::sprite_batch_draw(b, atlas_img, 1024, 1024,
    {32,0,32,32}, {200,100,32,32}, fn::math2d::Color::rgba(255,0,0));
  fn::gfx::sprite_batch_end(b);
tested: false
tests: []
test_file_path: ""
file_path: "cpp/functions/gfx/sprite_batch.cpp"
params:
  - name: cap
    desc: "Capacidad de quads por flush (CPU buffer). Default 4096 (~96 KB)."
  - name: img
    desc: "sg_image atlas. Cambio de img = auto-flush."
  - name: src
    desc: "Rect en pixeles dentro del atlas (UV se calculan dividiendo por img_w/img_h)."
  - name: dst
    desc: "Rect destino en coordenadas world (la matriz view-proj traduce a clip space)."
  - name: tint
    desc: "Color multiplicativo. Default Color::white()."
output: "Quads renderizados via sg_draw cuando flush. Una sola draw call por atlas binding."
---

# sprite_batch

Renderer batched de sprites 2D sobre sokol_gfx. Patron clasico:

1. `sprite_batch_create` una vez (despues de `sg_setup`).
2. Por frame, dentro de un sg_pass:
   - `sprite_batch_begin(b, view_proj)` — pasa la matriz view-projection del camera_2d.
   - `sprite_batch_draw(...)` por sprite. Auto-flush cuando cambia atlas o se llena.
   - `sprite_batch_end(b)` — flush final.

**Alpha blending** activado por defecto (premultiplicado o no — usar el atlas que tengas; el shader hace `texture(u_tex, v_uv) * tint`).

**Sampler** linear filter + clamp-to-edge. Para pixel art, crear sampler propio con `SG_FILTER_NEAREST` y bindearlo manualmente (override no soportado por ahora — sub-issue futuro si hace falta).

**Performance**: 1 draw call por atlas. 10K sprites @ 60 FPS sobre WebGL2 modesto. Cap por defecto 4096 quads/flush; subir si tu juego dibuja >4K sprites del mismo atlas.