@codexo/exojs 0.4.0 → 0.6.2

package/dist/esm/rendering/webgpu/WebGpuSpriteRenderer.js

@@ -1,137 +1,156 @@
 import { AbstractWebGpuRenderer } from './AbstractWebGpuRenderer.js';
 import { Texture } from '../texture/Texture.js';
 import { RenderTexture } from '../texture/RenderTexture.js';
+import { BlendModes } from '../types.js';
 import { getWebGpuBlendState } from './WebGpuBlendState.js';
 
 /// <reference types="@webgpu/types" />
-const spriteShaderSource = `
-struct ProjectionUniforms {
-    matrix: mat4x4<f32>,
-};
-
-@group(0) @binding(0)
-var<uniform> projection: ProjectionUniforms;
-
-@group(1) @binding(0)
-var spriteTexture0: texture_2d<f32>;
-@group(1) @binding(1)
-var spriteTexture1: texture_2d<f32>;
-@group(1) @binding(2)
-var spriteTexture2: texture_2d<f32>;
-@group(1) @binding(3)
-var spriteTexture3: texture_2d<f32>;
-@group(1) @binding(4)
-var spriteTexture4: texture_2d<f32>;
-@group(1) @binding(5)
-var spriteTexture5: texture_2d<f32>;
-@group(1) @binding(6)
-var spriteTexture6: texture_2d<f32>;
-@group(1) @binding(7)
-var spriteTexture7: texture_2d<f32>;
-
-@group(1) @binding(8)
-var spriteSampler0: sampler;
-@group(1) @binding(9)
-var spriteSampler1: sampler;
-@group(1) @binding(10)
-var spriteSampler2: sampler;
-@group(1) @binding(11)
-var spriteSampler3: sampler;
-@group(1) @binding(12)
-var spriteSampler4: sampler;
-@group(1) @binding(13)
-var spriteSampler5: sampler;
-@group(1) @binding(14)
-var spriteSampler6: sampler;
-@group(1) @binding(15)
-var spriteSampler7: sampler;
-
-struct VertexInput {
-    @location(0) position: vec2<f32>,
-    @location(1) texcoord: vec2<f32>,
-    @location(2) color: vec4<f32>,
-    @location(3) premultiplySample: u32,
-    @location(4) textureSlot: u32,
-};
-
-struct VertexOutput {
-    @builtin(position) position: vec4<f32>,
-    @location(0) texcoord: vec2<f32>,
-    @location(1) color: vec4<f32>,
-    @location(2) @interpolate(flat) premultiplySample: u32,
-    @location(3) @interpolate(flat) textureSlot: u32,
-};
-
-@vertex
-fn vertexMain(input: VertexInput) -> VertexOutput {
-    var output: VertexOutput;
-
-    output.position = projection.matrix * vec4<f32>(input.position, 0.0, 1.0);
-    output.texcoord = input.texcoord;
-    output.color = vec4(input.color.rgb * input.color.a, input.color.a);
-    output.premultiplySample = input.premultiplySample;
-    output.textureSlot = input.textureSlot;
-
-    return output;
-}
-
-fn sampleTexture(slot: u32, uv: vec2<f32>, ddx: vec2<f32>, ddy: vec2<f32>) -> vec4<f32> {
-    switch slot {
-        case 0u: {
-            return textureSampleGrad(spriteTexture0, spriteSampler0, uv, ddx, ddy);
-        }
-        case 1u: {
-            return textureSampleGrad(spriteTexture1, spriteSampler1, uv, ddx, ddy);
-        }
-        case 2u: {
-            return textureSampleGrad(spriteTexture2, spriteSampler2, uv, ddx, ddy);
-        }
-        case 3u: {
-            return textureSampleGrad(spriteTexture3, spriteSampler3, uv, ddx, ddy);
-        }
-        case 4u: {
-            return textureSampleGrad(spriteTexture4, spriteSampler4, uv, ddx, ddy);
-        }
-        case 5u: {
-            return textureSampleGrad(spriteTexture5, spriteSampler5, uv, ddx, ddy);
-        }
-        case 6u: {
-            return textureSampleGrad(spriteTexture6, spriteSampler6, uv, ddx, ddy);
-        }
-        default: {
-            return textureSampleGrad(spriteTexture7, spriteSampler7, uv, ddx, ddy);
-        }
-    }
-}
-
-@fragment
-fn fragmentMain(input: VertexOutput) -> @location(0) vec4<f32> {
-    // Compute screen-space derivatives in uniform control flow before the
-    // per-slot switch. WGSL requires textureSample (implicit LOD) to run in
-    // uniform control flow, which multi-texture batching breaks because the
-    // slot varies per fragment. textureSampleGrad takes explicit derivatives
-    // and is valid regardless of control-flow uniformity, while preserving
-    // mipmap-correct LOD when sprites use mipmapped textures.
-    let ddx = dpdx(input.texcoord);
-    let ddy = dpdy(input.texcoord);
-    let sample = sampleTexture(input.textureSlot, input.texcoord, ddx, ddy);
-    let resolvedSample = select(sample, vec4(sample.rgb * sample.a, sample.a), input.premultiplySample == 1u);
-
-    return resolvedSample * input.color;
-}
+const spriteShaderSource = `
+struct ProjectionUniforms {
+    matrix: mat4x4<f32>,
+};
+
+@group(0) @binding(0)
+var<uniform> projection: ProjectionUniforms;
+
+@group(1) @binding(0)
+var spriteTexture0: texture_2d<f32>;
+@group(1) @binding(1)
+var spriteTexture1: texture_2d<f32>;
+@group(1) @binding(2)
+var spriteTexture2: texture_2d<f32>;
+@group(1) @binding(3)
+var spriteTexture3: texture_2d<f32>;
+@group(1) @binding(4)
+var spriteTexture4: texture_2d<f32>;
+@group(1) @binding(5)
+var spriteTexture5: texture_2d<f32>;
+@group(1) @binding(6)
+var spriteTexture6: texture_2d<f32>;
+@group(1) @binding(7)
+var spriteTexture7: texture_2d<f32>;
+
+@group(1) @binding(8)
+var spriteSampler0: sampler;
+@group(1) @binding(9)
+var spriteSampler1: sampler;
+@group(1) @binding(10)
+var spriteSampler2: sampler;
+@group(1) @binding(11)
+var spriteSampler3: sampler;
+@group(1) @binding(12)
+var spriteSampler4: sampler;
+@group(1) @binding(13)
+var spriteSampler5: sampler;
+@group(1) @binding(14)
+var spriteSampler6: sampler;
+@group(1) @binding(15)
+var spriteSampler7: sampler;
+
+// Per-instance vertex layout (56 bytes per sprite). The four corners
+// of the quad are derived from @builtin(vertex_index) 0..3 inside the
+// vertex shader — there is no per-vertex stream.
+struct VertexInput {
+    @location(0) localBounds: vec4<f32>,        // left, top, right, bottom (local space)
+    @location(1) transformAB: vec3<f32>,        // first  row of 2D affine
+    @location(2) transformCD: vec3<f32>,        // second row of 2D affine
+    @location(3) uvBounds: vec4<f32>,           // uMin, vMin, uMax, vMax (CPU pre-swaps for flipY)
+    @location(4) color: vec4<f32>,              // RGBA tint
+    @location(5) packedSlotFlags: u32,          // bits 0..7 = slot, bit 8 = premultiply
+};
+
+struct VertexOutput {
+    @builtin(position) position: vec4<f32>,
+    @location(0) texcoord: vec2<f32>,
+    @location(1) color: vec4<f32>,
+    @location(2) @interpolate(flat) premultiplySample: u32,
+    @location(3) @interpolate(flat) textureSlot: u32,
+};
+
+@vertex
+fn vertexMain(input: VertexInput, @builtin(vertex_index) vid: u32) -> VertexOutput {
+    var output: VertexOutput;
+
+    // vid 0..3 → corners in TL, TR, BR, BL order (matches the static index
+    // buffer [0,1,2,0,2,3] used for indexed triangle-list drawing).
+    let cornerX = ((vid + 1u) >> 1u) & 1u;
+    let cornerY = vid >> 1u;
+
+    let localX = select(input.localBounds.x, input.localBounds.z, cornerX == 1u);
+    let localY = select(input.localBounds.y, input.localBounds.w, cornerY == 1u);
+
+    let worldX = input.transformAB.x * localX + input.transformAB.y * localY + input.transformAB.z;
+    let worldY = input.transformCD.x * localX + input.transformCD.y * localY + input.transformCD.z;
+
+    output.position = projection.matrix * vec4<f32>(worldX, worldY, 0.0, 1.0);
+
+    let u = select(input.uvBounds.x, input.uvBounds.z, cornerX == 1u);
+    let v = select(input.uvBounds.y, input.uvBounds.w, cornerY == 1u);
+    output.texcoord = vec2<f32>(u, v);
+
+    output.color = vec4(input.color.rgb * input.color.a, input.color.a);
+    output.textureSlot = input.packedSlotFlags & 0xFFu;
+    output.premultiplySample = (input.packedSlotFlags >> 8u) & 1u;
+
+    return output;
+}
+
+fn sampleTexture(slot: u32, uv: vec2<f32>, ddx: vec2<f32>, ddy: vec2<f32>) -> vec4<f32> {
+    switch slot {
+        case 0u: {
+            return textureSampleGrad(spriteTexture0, spriteSampler0, uv, ddx, ddy);
+        }
+        case 1u: {
+            return textureSampleGrad(spriteTexture1, spriteSampler1, uv, ddx, ddy);
+        }
+        case 2u: {
+            return textureSampleGrad(spriteTexture2, spriteSampler2, uv, ddx, ddy);
+        }
+        case 3u: {
+            return textureSampleGrad(spriteTexture3, spriteSampler3, uv, ddx, ddy);
+        }
+        case 4u: {
+            return textureSampleGrad(spriteTexture4, spriteSampler4, uv, ddx, ddy);
+        }
+        case 5u: {
+            return textureSampleGrad(spriteTexture5, spriteSampler5, uv, ddx, ddy);
+        }
+        case 6u: {
+            return textureSampleGrad(spriteTexture6, spriteSampler6, uv, ddx, ddy);
+        }
+        default: {
+            return textureSampleGrad(spriteTexture7, spriteSampler7, uv, ddx, ddy);
+        }
+    }
+}
+
+@fragment
+fn fragmentMain(input: VertexOutput) -> @location(0) vec4<f32> {
+    // Compute screen-space derivatives in uniform control flow before the
+    // per-slot switch. WGSL requires textureSample (implicit LOD) to run in
+    // uniform control flow, which multi-texture batching breaks because the
+    // slot varies per fragment. textureSampleGrad takes explicit derivatives
+    // and is valid regardless of control-flow uniformity, while preserving
+    // mipmap-correct LOD when sprites use mipmapped textures.
+    let ddx = dpdx(input.texcoord);
+    let ddy = dpdy(input.texcoord);
+    let sample = sampleTexture(input.textureSlot, input.texcoord, ddx, ddy);
+    let resolvedSample = select(sample, vec4(sample.rgb * sample.a, sample.a), input.premultiplySample == 1u);
+
+    return resolvedSample * input.color;
+}
 `;
-const vertexStrideBytes = 28;
-const spriteVertexCount = 4;
-const spriteIndexCount = 6;
+const instanceStrideBytes = 56;
+const wordsPerInstance = instanceStrideBytes / Uint32Array.BYTES_PER_ELEMENT;
 const projectionByteLength = 64;
 const initialBatchCapacity = 32;
-const wordsPerVertex = vertexStrideBytes / Uint32Array.BYTES_PER_ELEMENT;
 const maxBatchTextures = 8;
+const indicesPerSprite = 6;
+// Static index buffer: two triangles forming a quad, vertex IDs 0..3 in
+// TL/TR/BR/BL order so the WGSL `cornerX/cornerY` derivation matches.
+const quadIndices = new Uint16Array([0, 1, 2, 0, 2, 3]);
 class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
-    _drawCalls = [];
-    _drawCallCount = 0;
     _projectionData = new Float32Array(projectionByteLength / Float32Array.BYTES_PER_ELEMENT);
-    _renderManager = null;
     _device = null;
     _shaderModule = null;
     _uniformBindGroupLayout = null;
@@ -139,71 +158,81 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
     _pipelineLayout = null;
     _uniformBuffer = null;
     _uniformBindGroup = null;
-    _vertexBuffer = null;
     _indexBuffer = null;
-    _vertexCapacity = 0;
-    _vertexData = new ArrayBuffer(0);
-    _float32View = new Float32Array(this._vertexData);
-    _uint32View = new Uint32Array(this._vertexData);
+    _instanceBuffer = null;
+    _instanceCapacity = 0;
+    _instanceData = new ArrayBuffer(0);
+    _instanceFloat32 = new Float32Array(this._instanceData);
+    _instanceUint32 = new Uint32Array(this._instanceData);
     _pipelines = new Map();
-    onConnect(runtime) {
-        if (!this._renderManager) {
-            this._renderManager = runtime;
-            this._device = this._renderManager.device;
-            this._shaderModule = this._device.createShaderModule({ code: spriteShaderSource });
-            this._uniformBindGroupLayout = this._device.createBindGroupLayout({
-                entries: [{
-                        binding: 0,
-                        visibility: GPUShaderStage.VERTEX,
-                        buffer: {
-                            type: 'uniform',
-                        },
-                    }],
-            });
-            this._textureBindGroupLayout = this._device.createBindGroupLayout({
-                entries: [
-                    ...Array.from({ length: maxBatchTextures }, (_, index) => ({
-                        binding: index,
-                        visibility: GPUShaderStage.FRAGMENT,
-                        texture: {
-                            sampleType: 'float',
-                        },
-                    })),
-                    ...Array.from({ length: maxBatchTextures }, (_, index) => ({
-                        binding: maxBatchTextures + index,
-                        visibility: GPUShaderStage.FRAGMENT,
-                        sampler: {
-                            type: 'filtering',
-                        },
-                    })),
-                ],
-            });
-            this._pipelineLayout = this._device.createPipelineLayout({
-                bindGroupLayouts: [this._uniformBindGroupLayout, this._textureBindGroupLayout],
-            });
-            this._uniformBuffer = this._device.createBuffer({
-                size: projectionByteLength,
-                usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
-            });
-            this._uniformBindGroup = this._device.createBindGroup({
-                layout: this._uniformBindGroupLayout,
-                entries: [{
-                        binding: 0,
-                        resource: {
-                            buffer: this._uniformBuffer,
-                        },
-                    }],
-            });
-            this._ensureBatchCapacity(initialBatchCapacity);
+    _activeTextures = new Array(maxBatchTextures).fill(null);
+    _textureSlots = new Map();
+    _slotCount = 0;
+    _instanceCount = 0;
+    _currentBlendMode = null;
+    onConnect(backend) {
+        if (this._device) {
+            return;
         }
+        this._device = backend.device;
+        this._shaderModule = this._device.createShaderModule({ code: spriteShaderSource });
+        this._uniformBindGroupLayout = this._device.createBindGroupLayout({
+            entries: [{
+                    binding: 0,
+                    visibility: GPUShaderStage.VERTEX,
+                    buffer: {
+                        type: 'uniform',
+                    },
+                }],
+        });
+        this._textureBindGroupLayout = this._device.createBindGroupLayout({
+            entries: [
+                ...Array.from({ length: maxBatchTextures }, (_, index) => ({
+                    binding: index,
+                    visibility: GPUShaderStage.FRAGMENT,
+                    texture: {
+                        sampleType: 'float',
+                    },
+                })),
+                ...Array.from({ length: maxBatchTextures }, (_, index) => ({
+                    binding: maxBatchTextures + index,
+                    visibility: GPUShaderStage.FRAGMENT,
+                    sampler: {
+                        type: 'filtering',
+                    },
+                })),
+            ],
+        });
+        this._pipelineLayout = this._device.createPipelineLayout({
+            bindGroupLayouts: [this._uniformBindGroupLayout, this._textureBindGroupLayout],
+        });
+        this._uniformBuffer = this._device.createBuffer({
+            size: projectionByteLength,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        this._uniformBindGroup = this._device.createBindGroup({
+            layout: this._uniformBindGroupLayout,
+            entries: [{
+                    binding: 0,
+                    resource: {
+                        buffer: this._uniformBuffer,
+                    },
+                }],
+        });
+        // Static index buffer for the quad. Allocated once at connect; its
+        // contents never change.
+        this._indexBuffer = this._device.createBuffer({
+            size: quadIndices.byteLength,
+            usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
+        });
+        this._device.queue.writeBuffer(this._indexBuffer, 0, quadIndices.buffer, quadIndices.byteOffset, quadIndices.byteLength);
     }
     onDisconnect() {
-        this.flush();
-        this._vertexBuffer?.destroy();
+        this._instanceBuffer?.destroy();
         this._indexBuffer?.destroy();
         this._uniformBuffer?.destroy();
         this._pipelines.clear();
-        this._vertexBuffer = null;
+        this._instanceBuffer = null;
         this._indexBuffer = null;
         this._uniformBindGroup = null;
         this._uniformBuffer = null;
@@ -212,94 +241,64 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
         this._uniformBindGroupLayout = null;
         this._shaderModule = null;
         this._device = null;
-        this._renderManager = null;
-        this._vertexCapacity = 0;
-        this._vertexData = new ArrayBuffer(0);
-        this._float32View = new Float32Array(this._vertexData);
-        this._uint32View = new Uint32Array(this._vertexData);
-        this._drawCallCount = 0;
+        this._backend = null;
+        this._instanceCapacity = 0;
+        this._instanceData = new ArrayBuffer(0);
+        this._instanceFloat32 = new Float32Array(this._instanceData);
+        this._instanceUint32 = new Uint32Array(this._instanceData);
+        this._instanceCount = 0;
+        this._currentBlendMode = null;
+        this._resetSlots();
     }
     render(sprite) {
-        const renderManager = this._renderManager;
+        const backend = this._backend;
         const texture = sprite.texture;
-        if (renderManager === null
-            ||
-                (!(texture instanceof Texture) && !(texture instanceof RenderTexture))
+        // Same early-out conditions as the deferred renderer used to apply.
+        if (backend === null
+            || (!(texture instanceof Texture) && !(texture instanceof RenderTexture))
             || texture.width === 0
             || texture.height === 0
             || (texture instanceof Texture && texture.source === null)) {
             return;
         }
-        renderManager.setBlendMode(sprite.blendMode);
-        const drawCallIndex = this._drawCallCount++;
-        const drawCall = this._drawCalls[drawCallIndex];
-        if (drawCall) {
-            drawCall.sprite = sprite;
-            drawCall.texture = texture;
-            drawCall.color = sprite.tint.toRgba();
-            drawCall.blendMode = sprite.blendMode;
+        const blendMode = sprite.blendMode;
+        // Flush triggers: blend-mode change, instance buffer full at current
+        // capacity (we'll grow on next render), or texture-slot exhaustion.
+        const blendModeChanged = this._currentBlendMode !== null && blendMode !== this._currentBlendMode;
+        const slotExhausted = !this._textureSlots.has(texture) && this._slotCount >= maxBatchTextures;
+        if (blendModeChanged || slotExhausted) {
+            this.flush();
         }
-        else {
-            this._drawCalls.push({
-                sprite,
-                texture,
-                color: sprite.tint.toRgba(),
-                blendMode: sprite.blendMode,
-            });
+        this._currentBlendMode = blendMode;
+        backend.setBlendMode(blendMode);
+        // Resolve / assign texture slot.
+        let slot = this._textureSlots.get(texture);
+        if (slot === undefined) {
+            slot = this._slotCount++;
+            this._textureSlots.set(texture, slot);
+            this._activeTextures[slot] = texture;
         }
+        const premultiplySample = backend.shouldPremultiplyTextureSample(texture) ? 1 : 0;
+        const packedSlotFlags = slot | (premultiplySample << 8);
+        // Ensure capacity covers the new entry BEFORE packing — otherwise the
+        // typed-array writes in _packInstance silently fall off the end of a
+        // too-small buffer.
+        this._ensureInstanceCapacity(this._instanceCount + 1);
+        this._packInstance(sprite, texture, packedSlotFlags);
+        this._instanceCount++;
     }
     flush() {
-        const renderManager = this._renderManager;
+        const backend = this._backend;
         const device = this._device;
         const uniformBuffer = this._uniformBuffer;
         const uniformBindGroup = this._uniformBindGroup;
-        const vertexBuffer = this._vertexBuffer;
-        const indexBuffer = this._indexBuffer;
-        if (!renderManager || !device || !uniformBuffer || !uniformBindGroup || !vertexBuffer || !indexBuffer) {
+        if (!backend || !device || !uniformBuffer || !uniformBindGroup) {
             return;
         }
-        if (this._drawCallCount === 0 && !renderManager.clearRequested) {
+        if (this._instanceCount === 0 && !backend.clearRequested) {
             return;
         }
-        // Grow vertex/index buffers up front for the TOTAL sprite count. Two
-        // reasons this must happen before the render pass begins:
-        //   1. _ensureBatchCapacity destroys old buffers and creates new ones
-        //      when capacity grows, so running it after setVertexBuffer /
-        //      setIndexBuffer would leave the pass bound to destroyed buffers.
-        //   2. All batches are packed into the vertex buffer at distinct
-        //      sprite offsets, so the buffer must hold every sprite in the
-        //      flush, not just one batch worth.
-        if (this._drawCallCount > 0) {
-            this._ensureBatchCapacity(this._drawCallCount);
-        }
-        // Walk the batches once, packing each batch's vertex data into the
-        // CPU-side buffer at its own sprite-aligned offset. Each batch's
-        // metadata is recorded for the draw loop below.
-        //
-        // This replaces an earlier per-batch queue.writeBuffer(..., offset: 0)
-        // pattern where every writeBuffer targeted the same GPU offset. All
-        // writeBuffers in a frame execute before queue.submit(commandBuffer),
-        // so only the last batch's vertex data survived — which meant any
-        // flush containing more than one batch rendered every batch using
-        // the LAST batch's vertices (background vanished, sprites duplicated
-        // at wrong sizes, etc. whenever blend mode / texture slot / pipeline
-        // caused a split into multiple batches).
-        const batchPlan = [];
-        let packedSpriteCount = 0;
-        for (let start = 0; start < this._drawCallCount;) {
-            const batch = this._getBatchRange(start);
-            const spriteCount = batch.end - batch.start;
-            this._writeBatchVertexData(batch, packedSpriteCount);
-            batchPlan.push({
-                firstSprite: packedSpriteCount,
-                spriteCount,
-                blendMode: batch.blendMode,
-                textures: batch.textures,
-            });
-            packedSpriteCount += spriteCount;
-            start = batch.end;
-        }
-        const viewMatrix = renderManager.view.getTransform();
+        const viewMatrix = backend.view.getTransform();
         this._projectionData.set([
             viewMatrix.a, viewMatrix.c, 0, 0,
             viewMatrix.b, viewMatrix.d, 0, 0,
@@ -309,157 +308,175 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
         device.queue.writeBuffer(uniformBuffer, 0, this._projectionData.buffer, this._projectionData.byteOffset, this._projectionData.byteLength);
         const encoder = device.createCommandEncoder();
         const pass = encoder.beginRenderPass({
-            colorAttachments: [renderManager.createColorAttachment()],
+            colorAttachments: [backend.createColorAttachment()],
         });
-        renderManager.stats.renderPasses++;
-        const scissor = renderManager.getScissorRect();
+        backend.stats.renderPasses++;
+        const scissor = backend.getScissorRect();
         const maskClipsAll = scissor !== null && (scissor.width <= 0 || scissor.height <= 0);
         if (scissor !== null && !maskClipsAll) {
             pass.setScissorRect(scissor.x, scissor.y, scissor.width, scissor.height);
         }
-        if (this._drawCallCount > 0 && !maskClipsAll) {
-            // Single upload for the whole packed vertex buffer — every batch
-            // reads from its own sprite range via drawIndexed's firstIndex.
-            device.queue.writeBuffer(this._vertexBuffer, 0, this._vertexData, 0, packedSpriteCount * spriteVertexCount * vertexStrideBytes);
+        if (this._instanceCount > 0 && !maskClipsAll && this._instanceBuffer !== null && this._indexBuffer !== null && this._currentBlendMode !== null) {
+            device.queue.writeBuffer(this._instanceBuffer, 0, this._instanceData, 0, this._instanceCount * instanceStrideBytes);
+            const pipeline = this._getPipeline(this._currentBlendMode, backend.renderTargetFormat);
+            const textureBindGroup = this._createTextureBindGroup(device, backend);
+            pass.setPipeline(pipeline);
             pass.setBindGroup(0, uniformBindGroup);
-            pass.setVertexBuffer(0, this._vertexBuffer);
-            pass.setIndexBuffer(this._indexBuffer, 'uint32');
-            for (const plan of batchPlan) {
-                const pipeline = this._getPipeline(plan.blendMode, renderManager.renderTargetFormat);
-                const textureBindGroup = this._createTextureBindGroup(device, renderManager, plan.textures);
-                pass.setPipeline(pipeline);
-                pass.setBindGroup(1, textureBindGroup);
-                pass.drawIndexed(plan.spriteCount * spriteIndexCount, 1, plan.firstSprite * spriteIndexCount, 0, 0);
-                renderManager.stats.batches++;
-                renderManager.stats.drawCalls++;
-            }
+            pass.setBindGroup(1, textureBindGroup);
+            pass.setVertexBuffer(0, this._instanceBuffer);
+            pass.setIndexBuffer(this._indexBuffer, 'uint16');
+            pass.drawIndexed(indicesPerSprite, this._instanceCount, 0, 0, 0);
+            backend.stats.batches++;
+            backend.stats.drawCalls++;
         }
         pass.end();
-        renderManager.submit(encoder.finish());
-        this._drawCallCount = 0;
+        backend.submit(encoder.finish());
+        this._instanceCount = 0;
+        this._resetSlots();
+        this._currentBlendMode = null;
     }
     destroy() {
         this.disconnect();
     }
-    _ensureBatchCapacity(spriteCount) {
-        if (!this._device || spriteCount <= this._vertexCapacity) {
+    /**
+     * Pre-create render pipelines for every blend-mode × target-format
+     * combination this renderer can produce, asynchronously and in
+     * parallel. Called from the render manager's init path so by the time
+     * the first frame draws, all pipelines exist in cache.
+     *
+     * Without prewarm, the first draw of any new (blendMode, format)
+     * combination would fall back to the synchronous _getPipeline() path,
+     * which blocks while the WebGPU implementation compiles WGSL and
+     * sets up the pipeline state object — typically tens of milliseconds.
+     */
+    async prewarmPipelines(formats) {
+        const device = this._device;
+        if (!device || !this._shaderModule || !this._pipelineLayout) {
             return;
         }
-        let nextCapacity = Math.max(this._vertexCapacity, initialBatchCapacity);
-        while (nextCapacity < spriteCount) {
-            nextCapacity *= 2;
+        if (typeof device.createRenderPipelineAsync !== 'function') {
+            return;
         }
-        const vertexData = new ArrayBuffer(nextCapacity * spriteVertexCount * vertexStrideBytes);
-        const vertexBuffer = this._device.createBuffer({
-            size: vertexData.byteLength,
-            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
-        });
-        const indexData = new Uint32Array(nextCapacity * spriteIndexCount);
-        const indexBuffer = this._device.createBuffer({
-            size: indexData.byteLength,
-            usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
-        });
-        for (let spriteIndex = 0; spriteIndex < nextCapacity; spriteIndex++) {
-            const baseVertex = spriteIndex * spriteVertexCount;
-            const targetIndex = spriteIndex * spriteIndexCount;
-            indexData[targetIndex] = baseVertex;
-            indexData[targetIndex + 1] = baseVertex + 1;
-            indexData[targetIndex + 2] = baseVertex + 2;
-            indexData[targetIndex + 3] = baseVertex;
-            indexData[targetIndex + 4] = baseVertex + 2;
-            indexData[targetIndex + 5] = baseVertex + 3;
+        const blendModes = [
+            BlendModes.Normal,
+            BlendModes.Additive,
+            BlendModes.Subtract,
+            BlendModes.Multiply,
+            BlendModes.Screen,
+        ];
+        const promises = [];
+        for (const blendMode of blendModes) {
+            for (const format of formats) {
+                const pipelineKey = `${blendMode}:${format}`;
+                if (this._pipelines.has(pipelineKey)) {
+                    continue;
+                }
+                const promise = device
+                    .createRenderPipelineAsync(this._buildPipelineDescriptor(blendMode, format))
+                    .then((pipeline) => {
+                    this._pipelines.set(pipelineKey, pipeline);
+                });
+                promises.push(promise);
+            }
         }
-        this._device.queue.writeBuffer(indexBuffer, 0, indexData.buffer, indexData.byteOffset, indexData.byteLength);
-        this._vertexBuffer?.destroy();
-        this._indexBuffer?.destroy();
-        this._vertexCapacity = nextCapacity;
-        this._vertexData = vertexData;
-        this._float32View = new Float32Array(vertexData);
-        this._uint32View = new Uint32Array(vertexData);
-        this._vertexBuffer = vertexBuffer;
-        this._indexBuffer = indexBuffer;
+        await Promise.all(promises);
     }
-    _writeBatchVertexData(batch, firstSprite) {
-        const renderManager = this._renderManager;
-        if (!renderManager) {
+    _packInstance(sprite, texture, packedSlotFlags) {
+        const offset = this._instanceCount * wordsPerInstance;
+        const f32 = this._instanceFloat32;
+        const u32 = this._instanceUint32;
+        const bounds = sprite.getLocalBounds();
+        f32[offset + 0] = bounds.left;
+        f32[offset + 1] = bounds.top;
+        f32[offset + 2] = bounds.right;
+        f32[offset + 3] = bounds.bottom;
+        const transform = sprite.getGlobalTransform();
+        f32[offset + 4] = transform.a;
+        f32[offset + 5] = transform.b;
+        f32[offset + 6] = transform.x;
+        f32[offset + 7] = transform.c;
+        f32[offset + 8] = transform.d;
+        f32[offset + 9] = transform.y;
+        // uvBounds: u16x4 normalised, packed into two u32 slots. The CPU
+        // applies the flipY swap so the shader stays orientation-agnostic.
+        const frame = sprite.textureFrame;
+        const texWidth = texture.width;
+        const texHeight = texture.height;
+        const uMin = ((frame.left / texWidth) * 0xFFFF) & 0xFFFF;
+        const uMax = ((frame.right / texWidth) * 0xFFFF) & 0xFFFF;
+        const vMinRaw = ((frame.top / texHeight) * 0xFFFF) & 0xFFFF;
+        const vMaxRaw = ((frame.bottom / texHeight) * 0xFFFF) & 0xFFFF;
+        const flipY = texture instanceof Texture && texture.flipY;
+        const vMin = flipY ? vMaxRaw : vMinRaw;
+        const vMax = flipY ? vMinRaw : vMaxRaw;
+        u32[offset + 10] = uMin | (vMin << 16);
+        u32[offset + 11] = uMax | (vMax << 16);
+        u32[offset + 12] = sprite.tint.toRgba();
+        u32[offset + 13] = packedSlotFlags;
+    }
+    _ensureInstanceCapacity(instanceCount) {
+        if (!this._device || instanceCount <= this._instanceCapacity) {
             return;
         }
-        let vertexOffset = firstSprite * spriteVertexCount * wordsPerVertex;
-        for (let drawCallIndex = batch.start; drawCallIndex < batch.end; drawCallIndex++) {
-            const drawCall = this._drawCalls[drawCallIndex];
-            const textureSlot = batch.textureSlots.get(drawCall.texture) ?? 0;
-            const premultiplySample = renderManager.shouldPremultiplyTextureSample(drawCall.texture) ? 1 : 0;
-            const vertices = drawCall.sprite.vertices;
-            const texCoords = drawCall.sprite.texCoords;
-            for (let i = 0; i < spriteVertexCount; i++) {
-                const vertexIndex = i * 2;
-                const packedTexCoord = texCoords[i];
-                this._float32View[vertexOffset] = vertices[vertexIndex];
-                this._float32View[vertexOffset + 1] = vertices[vertexIndex + 1];
-                this._float32View[vertexOffset + 2] = (packedTexCoord & 0xFFFF) / 65535;
-                this._float32View[vertexOffset + 3] = ((packedTexCoord >>> 16) & 0xFFFF) / 65535;
-                this._uint32View[vertexOffset + 4] = drawCall.color;
-                this._uint32View[vertexOffset + 5] = premultiplySample;
-                this._uint32View[vertexOffset + 6] = textureSlot;
-                vertexOffset += wordsPerVertex;
-            }
+        let nextCapacity = Math.max(this._instanceCapacity, initialBatchCapacity);
+        while (nextCapacity < instanceCount) {
+            nextCapacity *= 2;
         }
+        const oldData = this._instanceData;
+        // Preserve any already-packed instances. _instanceCount is bounded by
+        // the previous capacity, but oldData may be the initial 0-byte buffer
+        // — clamp to its actual byteLength to avoid out-of-range typed-array
+        // construction.
+        const carryBytes = Math.min(this._instanceCount * instanceStrideBytes, oldData.byteLength);
+        const instanceData = new ArrayBuffer(nextCapacity * instanceStrideBytes);
+        if (carryBytes > 0) {
+            new Uint8Array(instanceData).set(new Uint8Array(oldData, 0, carryBytes));
+        }
+        const instanceBuffer = this._device.createBuffer({
+            size: instanceData.byteLength,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+        this._instanceBuffer?.destroy();
+        this._instanceCapacity = nextCapacity;
+        this._instanceData = instanceData;
+        this._instanceFloat32 = new Float32Array(instanceData);
+        this._instanceUint32 = new Uint32Array(instanceData);
+        this._instanceBuffer = instanceBuffer;
     }
-    _getBatchRange(start) {
-        const drawCall = this._drawCalls[start];
-        const textureSlots = new Map();
-        const textures = new Array();
-        let end = start + 1;
-        textureSlots.set(drawCall.texture, 0);
-        textures.push(drawCall.texture);
-        while (end < this._drawCallCount) {
-            const nextDrawCall = this._drawCalls[end];
-            if (nextDrawCall.blendMode !== drawCall.blendMode) {
-                break;
-            }
-            if (!textureSlots.has(nextDrawCall.texture)) {
-                if (textures.length >= maxBatchTextures) {
-                    break;
-                }
-                textureSlots.set(nextDrawCall.texture, textures.length);
-                textures.push(nextDrawCall.texture);
+    _resetSlots() {
+        if (this._slotCount > 0) {
+            for (let i = 0; i < this._slotCount; i++) {
+                this._activeTextures[i] = null;
             }
-            if (textureSlots.size > maxBatchTextures) {
-                break;
-            }
-            end++;
+            this._textureSlots.clear();
+            this._slotCount = 0;
         }
-        return {
-            start,
-            end,
-            spriteCount: end - start,
-            blendMode: drawCall.blendMode,
-            textures,
-            textureSlots,
-        };
     }
-    _createTextureBindGroup(device, renderManager, textures) {
-        const fallbackTexture = textures[0];
-        const fallbackBinding = renderManager.getTextureBinding(fallbackTexture);
-        const entries = [];
+    _createTextureBindGroup(device, backend) {
+        // Slots beyond the active count get the slot-0 texture as a filler so
+        // the bind-group layout always sees N valid texture views and samplers.
+        // The fragment shader's switch only ever dispatches to the active slot
+        // count, so unsampled fillers cost nothing visually.
+        const fallbackTexture = this._activeTextures[0] ?? Texture.empty;
+        const fallbackBinding = backend.getTextureBinding(fallbackTexture);
         const resolvedBindings = new Array(maxBatchTextures);
-        for (let index = 0; index < maxBatchTextures; index++) {
-            const texture = textures[index] ?? fallbackTexture;
-            const textureBinding = texture === fallbackTexture
+        for (let i = 0; i < maxBatchTextures; i++) {
+            const texture = this._activeTextures[i] ?? fallbackTexture;
+            resolvedBindings[i] = texture === fallbackTexture
                 ? fallbackBinding
-                : renderManager.getTextureBinding(texture);
-            resolvedBindings[index] = textureBinding;
+                : backend.getTextureBinding(texture);
         }
-        for (let index = 0; index < maxBatchTextures; index++) {
+        const entries = [];
+        for (let i = 0; i < maxBatchTextures; i++) {
             entries.push({
-                binding: index,
-                resource: resolvedBindings[index].view,
+                binding: i,
+                resource: resolvedBindings[i].view,
             });
         }
-        for (let index = 0; index < maxBatchTextures; index++) {
+        for (let i = 0; i < maxBatchTextures; i++) {
             entries.push({
-                binding: maxBatchTextures + index,
-                resource: resolvedBindings[index].sampler,
+                binding: maxBatchTextures + i,
+                resource: resolvedBindings[i].sampler,
             });
         }
         return device.createBindGroup({
@@ -473,35 +490,48 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
         if (existingPipeline) {
             return existingPipeline;
         }
-        if (!this._device || !this._shaderModule || !this._pipelineLayout || !this._renderManager) {
+        if (!this._device || !this._shaderModule || !this._pipelineLayout || !this._backend) {
             throw new Error('Renderer has to be connected first!');
         }
-        const pipeline = this._device.createRenderPipeline({
+        const pipeline = this._device.createRenderPipeline(this._buildPipelineDescriptor(blendMode, format));
+        this._pipelines.set(pipelineKey, pipeline);
+        return pipeline;
+    }
+    _buildPipelineDescriptor(blendMode, format) {
+        if (!this._shaderModule || !this._pipelineLayout) {
+            throw new Error('Renderer has to be connected first!');
+        }
+        return {
             layout: this._pipelineLayout,
             vertex: {
                 module: this._shaderModule,
                 entryPoint: 'vertexMain',
                 buffers: [{
-                        arrayStride: vertexStrideBytes,
+                        arrayStride: instanceStrideBytes,
+                        stepMode: 'instance',
                         attributes: [{
                                 shaderLocation: 0,
                                 offset: 0,
-                                format: 'float32x2',
+                                format: 'float32x4',
                             }, {
                                 shaderLocation: 1,
-                                offset: 8,
-                                format: 'float32x2',
+                                offset: 16,
+                                format: 'float32x3',
                             }, {
                                 shaderLocation: 2,
-                                offset: 16,
-                                format: 'unorm8x4',
+                                offset: 28,
+                                format: 'float32x3',
                             }, {
                                 shaderLocation: 3,
-                                offset: 20,
-                                format: 'uint32',
+                                offset: 40,
+                                format: 'unorm16x4',
                             }, {
                                 shaderLocation: 4,
-                                offset: 24,
+                                offset: 48,
+                                format: 'unorm8x4',
+                            }, {
+                                shaderLocation: 5,
+                                offset: 52,
                                 format: 'uint32',
                             }],
                     }],
@@ -518,9 +548,7 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
             primitive: {
                 topology: 'triangle-list',
             },
-        });
-        this._pipelines.set(pipelineKey, pipeline);
-        return pipeline;
+        };
     }
 }