material batching

docs/user/gpu-driven.md

@@ -22,6 +22,20 @@ each frame — it never iterates the entities to issue draws.
 
 You do not need to do anything special to get this: `render_scene` is GPU-driven by default.
 
+## Batching by material
+
+The main render pass batches the draws by material: all entities sharing the same material are
+drawn back to back, so the GPU pipeline and the material's texture bind group are switched **once
+per distinct material**, not once per entity (the per-draw work — matrix offset, vertex/index
+buffers, the indirect draw itself — is unchanged). The grouping is internal: it does not change
+the rendered image and there is nothing to configure.
+
+> **Constraint:** the batching reorders the draws, which is safe here because every pipeline in
+> the engine is **opaque** (`BlendState::REPLACE`, no alpha blending) — the depth buffer resolves
+> the draw order. If transparent materials are ever added, the transparent draws must be isolated
+> (sorted back-to-front at the end of the pass) and must not interleave with the grouped opaque
+> draws.
+
 ## Frustum culling (opt-in)
 
 Culling is **off by default**. The culling pass still runs, but with culling disabled it marks
@@ -108,7 +122,7 @@ objects were off-screen anyway — so the proof is in the counts, not the image)
 This readback is the reference truth when a shader bug is suspected: it shows both the computed
 counts and the raw inputs of the cull pass, independently of what ends up on screen. (It is how
 the 2026-09-22 « black window » bug — an inverted WGSL `select` argument order — was diagnosed
-and verified fixed, see the DRAFT D14 in `docs/DRAFT.md`.)
+and verified fixed, see the D14 note in `docs/tech/ARCHI_CPU_GPU.md`.)
 
 ## Limitations