Refactor TextureCache and Batcher base class for renderer-agnostic abstraction

[obiot]

Summary

Prepare the texture cache and batcher systems for a future WebGPU backend by extracting renderer-agnostic parts from the current WebGL-specific implementations.

Completed

Buffer extraction (PR #1414)

• VertexArrayBuffer: moved from video/webgl/buffer/ to video/buffer/ — zero GL dependency, pure typed array management
• IndexBuffer: split into renderer-agnostic IndexBuffer base class (data accumulation, quad index patterns) and WebGLIndexBuffer subclass (GL buffer bind/upload)

Deferred — TextureCache unit management

Moving units/usedUnits/allocateTextureUnit/etc. from TextureCache to MaterialBatcher was attempted but causes rendering regressions.

Root causes identified

1. boundTextures is per-batcher, but GL texture units are global. When unit management lives on the batcher, each batcher (QuadBatcher, MeshBatcher, PrimitiveBatcher) independently allocates units. MeshBatcher assigns a texture to unit 0, then QuadBatcher also assigns a different texture to unit 0 — they conflict because GL units are shared.

2. blitTexture and beginPostEffect bypass unbindTexture2D. They do raw delete this.boundTextures[0] which desyncs the source→unit map from the unit→GLTexture map. Fixed by routing through unbindTexture2D, but the global vs per-batcher issue (point 1) remains.

3. The cache's units Map must be shared across all batchers. This is by design — cache.units maps texture sources to GL units at the renderer level, while batcher.boundTextures tracks which GL texture object is bound to each unit within that batcher. These are different levels of abstraction that cannot be merged.

Correct approach (future)

The source→unit mapping should stay on a shared object (renderer or cache). Options:

• Rename cache.units/usedUnits to something clearer (e.g. textureBindings) and keep on cache
• Create a dedicated TextureUnitAllocator on the renderer that both the cache and batchers access
• Keep the current architecture but document the intentional coupling between cache and batcher

Not planned (wait for WebGPU)

• GLShader / ShaderEffect — GLSL vs WGSL is too fundamental to abstract without the actual WebGPU implementation
• WebGLRenderer itself — 2000+ lines of direct GL, would be a parallel WebGPURenderer
• Specific batchers (QuadBatcher, PrimitiveBatcher, MeshBatcher) — depend on the batcher base

Already done (prior PRs)

• RenderTarget abstract base class with WebGLRenderTarget / CanvasRenderTarget (Add multi-pass post-effect chaining with renderer-agnostic RenderTarget architecture #1408)
• RenderTargetPool with factory pattern (Add multi-pass post-effect chaining with renderer-agnostic RenderTarget architecture #1408)
• Renderer-agnostic state methods on base Renderer (Add multi-pass post-effect chaining with renderer-agnostic RenderTarget architecture #1408)
• RenderState — already renderer-agnostic
• TextureAtlas — already renderer-agnostic

[obiot]

Investigation Results

Buffer extraction (PR #1414) — DONE

VertexArrayBuffer moved to video/buffer/, IndexBuffer split into base + WebGLIndexBuffer. No issues.

TextureCache unit management → Batcher — BLOCKED

Moving units/usedUnits/allocateTextureUnit/etc. from TextureCache to MaterialBatcher causes rendering regressions. Root causes identified:

1. boundTextures is per-batcher, but GL texture units are global. When unit management lives on the batcher, each batcher (QuadBatcher, MeshBatcher, PrimitiveBatcher) independently allocates units. MeshBatcher assigns a texture to unit 0, then QuadBatcher also assigns a different texture to unit 0 — they conflict because GL units are shared.

2. blitTexture and beginPostEffect bypass unbindTexture2D. They do raw delete this.boundTextures[0] which desyncs the source→unit map from the unit→GLTexture map. Fixed by routing through unbindTexture2D, but the global vs per-batcher issue (point 1) remains.

3. The cache's units Map must be shared across all batchers. This is by design — cache.units maps texture sources to GL units at the renderer level, while batcher.boundTextures tracks which GL texture object is bound to each unit within that batcher. These are different levels of abstraction.

Correct approach (future)

The source→unit mapping should stay on a shared object (renderer or cache). The per-batcher boundTextures tracks the GL texture handles. These are complementary, not redundant. A cleaner refactoring would:

• Rename cache.units/usedUnits to something clearer (e.g. textureBindings)
• Keep the circular dependency but document it clearly
• Or create a dedicated TextureUnitAllocator on the renderer that both the cache and batchers access

[obiot]

Recommended Architecture: Centralized TextureSystem

Based on investigation, the correct approach is a single shared TextureSystem on the renderer — not per-batcher, not on the cache.

Renderer
  ├─ TextureSystem (single, shared)
  │   ├─ boundTextures[]   ← canonical GL state (which GL texture is on each unit)
  │   ├─ textureBindings    ← source → unit mapping
  │   ├─ currentUnit        ← active unit tracker
  │   ├─ bind(texture, unit)
  │   ├─ unbind(unit)
  │   └─ allocateUnit()
  ├─ TextureCache           ← atlas metadata only (get/set/has/delete/tint)
  ├─ QuadBatcher            ← calls TextureSystem for unit assignment
  ├─ MeshBatcher            ← calls same TextureSystem
  └─ PrimitiveBatcher       ← no textures, doesn't use TextureSystem

This eliminates both problems:

• No per-batcher state conflicts — all batchers share one boundTextures and one textureBindings
• No circular dependency — cache doesn't reach into batcher, batcher doesn't reach into cache. Both go through TextureSystem.