@codexo/exojs 0.9.0 → 0.11.0

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

@@ -1,8 +1,10 @@
+import { spriteVertexWgsl } from '../sprite/spriteMaterialSources.js';
 import { RenderTexture } from '../texture/RenderTexture.js';
 import { Texture } from '../texture/Texture.js';
 import { BlendModes } from '../types.js';
 import { AbstractWebGpuRenderer } from './AbstractWebGpuRenderer.js';
 import { getWebGpuBlendState } from './WebGpuBlendState.js';
+import { stencilContentDepthStencilState } from './WebGpuStencilState.js';
 
 /// <reference types="@webgpu/types" />
 const spriteShaderSource = `
@@ -10,8 +12,16 @@ struct ProjectionUniforms {
     matrix: mat4x4<f32>,
 };
 
+struct TransformSlot {
+    m0: vec4<f32>,
+    m1: vec4<f32>,
+    m2: vec4<f32>,
+};
+
 @group(0) @binding(0)
 var<uniform> projection: ProjectionUniforms;
+@group(0) @binding(1)
+var<storage, read> transforms: array<TransformSlot>;
 
 @group(1) @binding(0)
 var spriteTexture0: texture_2d<f32>;
@@ -47,16 +57,17 @@ var spriteSampler6: sampler;
 @group(1) @binding(15)
 var spriteSampler7: sampler;
 
-// Per-instance vertex layout (56 bytes per sprite). The four corners
+// Per-instance vertex layout (36 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.
+// vertex shader — there is no per-vertex stream. The world transform is
+// fetched from the shared transform storage buffer keyed by nodeIndex
+// instead of being packed inline.
 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
+    @location(6) nodeIndex: u32,                // row into the shared transform storage buffer
 };
 
 struct VertexOutput {
@@ -79,8 +90,12 @@ fn vertexMain(input: VertexInput, @builtin(vertex_index) vid: u32) -> VertexOutp
     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;
+    // Fetch this instance's world transform from the shared storage buffer,
+    // keyed by nodeIndex: m0 = (a, b, c, d), m1 = (tx, ty, 0, 0). (m2 carries the
+    // node tint, unused here — the sprite keeps its own per-instance color.)
+    let slot = transforms[input.nodeIndex];
+    let worldX = slot.m0.x * localX + slot.m0.y * localY + slot.m1.x;
+    let worldY = slot.m0.z * localX + slot.m0.w * localY + slot.m1.y;
 
     output.position = projection.matrix * vec4<f32>(worldX, worldY, 0.0, 1.0);
 
@@ -140,11 +155,12 @@ fn fragmentMain(input: VertexOutput) -> @location(0) vec4<f32> {
     return resolvedSample * input.color;
 }
 `;
-const instanceStrideBytes = 56;
+const instanceStrideBytes = 36;
 const wordsPerInstance = instanceStrideBytes / Uint32Array.BYTES_PER_ELEMENT;
 const projectionByteLength = 64;
 const initialBatchCapacity = 32;
 const maxBatchTextures = 8;
+const maxCustomTextureSlots = 7; // user texture uniforms; group(2) binding 1..N
 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.
@@ -157,7 +173,10 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
     _textureBindGroupLayout = null;
     _pipelineLayout = null;
     _uniformBuffer = null;
-    _uniformBindGroup = null;
+    // group(0) bind group = projection UBO + shared transform storage buffer.
+    // Recreated whenever the storage buffer identity changes (capacity growth).
+    _transformBindGroup = null;
+    _transformStorageBuffer = null;
     _indexBuffer = null;
     _instanceBuffer = null;
     _instanceCapacity = 0;
@@ -169,7 +188,16 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
     _textureSlots = new Map();
     _slotCount = 0;
     _instanceCount = 0;
+    // Highest transform-storage row referenced by the pending batch; drives the
+    // minimum row count uploaded for the storage buffer at flush time.
+    _maxNodeIndex = 0;
     _currentBlendMode = null;
+    // Custom-material state. Per-material pipelines/bind groups are cached; the
+    // current batch's material/base-texture decide when to flush.
+    _customMaterials = new Map();
+    _customBaseTextureLayout = null;
+    _currentMaterial = null;
+    _currentBaseTexture = null;
     onConnect(backend) {
         if (this._device) {
             return;
@@ -185,6 +213,13 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
                         type: 'uniform',
                     },
                 },
+                {
+                    binding: 1,
+                    visibility: GPUShaderStage.VERTEX,
+                    buffer: {
+                        type: 'read-only-storage',
+                    },
+                },
             ],
         });
         this._textureBindGroupLayout = this._device.createBindGroupLayout({
@@ -208,21 +243,20 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
         this._pipelineLayout = this._device.createPipelineLayout({
             bindGroupLayouts: [this._uniformBindGroupLayout, this._textureBindGroupLayout],
         });
+        // Single base-texture layout for the custom-material path (group 1).
+        this._customBaseTextureLayout = this._device.createBindGroupLayout({
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: 'float' } },
+                { binding: 1, visibility: GPUShaderStage.FRAGMENT, sampler: { type: 'filtering' } },
+            ],
+        });
         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,
-                    },
-                },
-            ],
-        });
+        // The group(0) bind group also binds the shared transform storage buffer,
+        // whose identity changes when its capacity grows — so it is built lazily in
+        // flush() once the active storage buffer is known.
         // Static index buffer for the quad. Allocated once at connect; its
         // contents never change.
         this._indexBuffer = this._device.createBuffer({
@@ -235,12 +269,21 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
         this._instanceBuffer?.destroy();
         this._indexBuffer?.destroy();
         this._uniformBuffer?.destroy();
+        // Custom materials are owned by user code (one SpriteMaterial can be shared
+        // across many sprites); their resources are released when the user calls
+        // material.destroy(). On disconnect we eagerly release to avoid GPU leaks.
+        for (const resources of this._customMaterials.values()) {
+            this._releaseCustomResources(resources);
+        }
+        this._customMaterials.clear();
         this._pipelines.clear();
         this._instanceBuffer = null;
         this._indexBuffer = null;
-        this._uniformBindGroup = null;
+        this._transformBindGroup = null;
+        this._transformStorageBuffer = null;
         this._uniformBuffer = null;
         this._pipelineLayout = null;
+        this._customBaseTextureLayout = null;
         this._textureBindGroupLayout = null;
         this._uniformBindGroupLayout = null;
         this._shaderModule = null;
@@ -251,7 +294,10 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
         this._instanceFloat32 = new Float32Array(this._instanceData);
         this._instanceUint32 = new Uint32Array(this._instanceData);
         this._instanceCount = 0;
+        this._maxNodeIndex = 0;
         this._currentBlendMode = null;
+        this._currentMaterial = null;
+        this._currentBaseTexture = null;
         this._resetSlots();
     }
     render(sprite) {
@@ -265,15 +311,33 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
             (texture instanceof Texture && texture.source === null)) {
             return;
         }
+        const material = sprite.material;
+        // The transform lives in the shared storage buffer, keyed by the draw
+        // command's stable nodeIndex (already packed at the draw-command boundary).
+        // A direct, non-plan `backend.draw(sprite)` has no command — push the
+        // sprite's transform into the buffer and use the freshly-allocated slot.
+        const command = backend.activeDrawCommand;
+        const nodeIndex = command !== null ? command.nodeIndex : backend._pushTransform(sprite);
+        if (material === null) {
+            this._renderDefault(sprite, texture, backend, nodeIndex);
+        }
+        else {
+            this._renderCustom(sprite, texture, material, backend, nodeIndex);
+        }
+    }
+    /** Default multi-texture path: rotate the base texture through 8 slots. */
+    _renderDefault(sprite, texture, backend, nodeIndex) {
         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.
+        // Flush triggers: blend-mode change, texture-slot exhaustion, or a custom
+        // batch still in flight that must drain first.
         const blendModeChanged = this._currentBlendMode !== null && blendMode !== this._currentBlendMode;
         const slotExhausted = !this._textureSlots.has(texture) && this._slotCount >= maxBatchTextures;
-        if (blendModeChanged || slotExhausted) {
+        const materialSwitch = this._currentMaterial !== null && this._instanceCount > 0;
+        if (blendModeChanged || slotExhausted || materialSwitch) {
             this.flush();
         }
         this._currentBlendMode = blendMode;
+        this._currentMaterial = null;
         backend.setBlendMode(blendMode);
         // Resolve / assign texture slot.
         let slot = this._textureSlots.get(texture);
@@ -288,15 +352,38 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
         // 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._packInstance(sprite, texture, packedSlotFlags, nodeIndex);
+        this._instanceCount++;
+    }
+    /** Custom-material path: single base texture on group(1), instanced. */
+    _renderCustom(sprite, texture, material, backend, nodeIndex) {
+        if (material.shader.wgsl === null) {
+            throw new Error('SpriteMaterial shader has no `wgsl` source; cannot render through the WebGPU backend.');
+        }
+        // The material owns its blend mode; the sprite's own blendMode overrides it
+        // when set away from the default (Normal).
+        const blendMode = sprite.blendMode === BlendModes.Normal ? material.blendMode : sprite.blendMode;
+        const blendModeChanged = this._currentBlendMode !== null && blendMode !== this._currentBlendMode;
+        const materialChanged = this._currentMaterial !== null && material !== this._currentMaterial;
+        const textureChanged = this._currentBaseTexture !== null && texture !== this._currentBaseTexture;
+        const modeSwitch = this._currentMaterial === null && this._instanceCount > 0;
+        if (blendModeChanged || materialChanged || textureChanged || modeSwitch) {
+            this.flush();
+        }
+        this._currentBlendMode = blendMode;
+        this._currentMaterial = material;
+        this._currentBaseTexture = texture;
+        backend.setBlendMode(blendMode);
+        // textureSlot word is unused by custom fragments (base binds to group(1)).
+        this._ensureInstanceCapacity(this._instanceCount + 1);
+        this._packInstance(sprite, texture, 0, nodeIndex);
         this._instanceCount++;
     }
     flush() {
         const backend = this._backend;
         const device = this._device;
         const uniformBuffer = this._uniformBuffer;
-        const uniformBindGroup = this._uniformBindGroup;
-        if (!backend || !device || !uniformBuffer || !uniformBindGroup) {
+        if (!backend || !device || !uniformBuffer) {
             return;
         }
         if (this._instanceCount === 0 && !backend.clearRequested) {
@@ -305,34 +392,66 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
         const viewMatrix = backend.view.getTransform();
         this._projectionData.set([viewMatrix.a, viewMatrix.c, 0, 0, viewMatrix.b, viewMatrix.d, 0, 0, 0, 0, 1, 0, viewMatrix.x, viewMatrix.y, 0, viewMatrix.z]);
         device.queue.writeBuffer(uniformBuffer, 0, this._projectionData.buffer, this._projectionData.byteOffset, this._projectionData.byteLength);
-        const encoder = device.createCommandEncoder();
-        const pass = encoder.beginRenderPass({
-            colorAttachments: [backend.createColorAttachment()],
-        });
-        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);
-        }
+        // The coordinator owns the GPU pass: it opens the encoder + render pass
+        // (load/clear resolution, pass count and scissor are applied there) and
+        // ends + submits it below.
+        const pass = backend._passCoordinator.acquirePass().pass;
         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.setBindGroup(1, textureBindGroup);
-            pass.setVertexBuffer(0, this._instanceBuffer);
-            pass.setIndexBuffer(this._indexBuffer, 'uint16');
-            pass.drawIndexed(indicesPerSprite, this._instanceCount, 0, 0, 0);
+            // Resolve the shared transform storage buffer (rows uploaded up to the
+            // max nodeIndex referenced by this batch) and bind it alongside the
+            // projection UBO on group(0). Both the default and custom programs fetch
+            // the world transform from it via nodeIndex.
+            const storage = backend.getTransformStorageBuffer(this._maxNodeIndex + 1);
+            const transformBindGroup = this._getOrCreateTransformBindGroup(device, uniformBuffer, storage.buffer);
+            const material = this._currentMaterial;
+            const stencil = backend._passCoordinator.stencilActive;
+            if (material === null) {
+                const pipeline = this._getPipeline(this._currentBlendMode, backend.renderTargetFormat, stencil);
+                const textureBindGroup = this._createTextureBindGroup(device, backend);
+                pass.setPipeline(pipeline);
+                pass.setBindGroup(0, transformBindGroup);
+                pass.setBindGroup(1, textureBindGroup);
+                pass.setVertexBuffer(0, this._instanceBuffer);
+                pass.setIndexBuffer(this._indexBuffer, 'uint16');
+                pass.drawIndexed(indicesPerSprite, this._instanceCount, 0, 0, 0);
+            }
+            else {
+                pass.pushDebugGroup('SpriteMaterial (custom)');
+                this._drawCustomBatch(pass, device, backend, material, transformBindGroup, stencil);
+                pass.popDebugGroup();
+            }
             backend.stats.batches++;
             backend.stats.drawCalls++;
         }
-        pass.end();
-        backend.submit(encoder.finish());
+        backend._passCoordinator.endPass();
         this._instanceCount = 0;
+        this._maxNodeIndex = 0;
         this._resetSlots();
         this._currentBlendMode = null;
+        this._currentMaterial = null;
+        this._currentBaseTexture = null;
+    }
+    /**
+     * Build (or reuse) the group(0) bind group pairing the fixed projection UBO
+     * with the shared transform storage buffer. Cached against the storage buffer
+     * identity, which changes only when its capacity grows.
+     */
+    _getOrCreateTransformBindGroup(device, uniformBuffer, storageBuffer) {
+        if (this._transformBindGroup !== null && this._transformStorageBuffer === storageBuffer) {
+            return this._transformBindGroup;
+        }
+        this._transformStorageBuffer = storageBuffer;
+        this._transformBindGroup = device.createBindGroup({
+            layout: this._uniformBindGroupLayout,
+            entries: [
+                { binding: 0, resource: { buffer: uniformBuffer } },
+                { binding: 1, resource: { buffer: storageBuffer } },
+            ],
+        });
+        return this._transformBindGroup;
     }
     destroy() {
         this.disconnect();
@@ -380,24 +499,18 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
         }
         await Promise.all(promises);
     }
-    _packInstance(sprite, texture, packedSlotFlags) {
+    _packInstance(sprite, texture, packedSlotFlags, nodeIndex) {
         const offset = this._instanceCount * wordsPerInstance;
         const f32 = this._instanceFloat32;
         const u32 = this._instanceUint32;
+        // localBounds: left, top, right, bottom (words 0..3, offset 0)
         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.
+        // uvBounds: u16x4 normalised, packed into two u32 slots (words 4,5, offset
+        // 16). The CPU applies the flipY swap so the shader stays orientation-agnostic.
         const frame = sprite.textureFrame;
         const texWidth = texture.width;
         const texHeight = texture.height;
@@ -408,10 +521,18 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
         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;
+        u32[offset + 4] = uMin | (vMin << 16);
+        u32[offset + 5] = uMax | (vMax << 16);
+        // color (u8x4 packed) at word 6 (offset 24)
+        u32[offset + 6] = sprite.tint.toRgba();
+        // packedSlotFlags (u32) at word 7 (offset 28)
+        u32[offset + 7] = packedSlotFlags;
+        // nodeIndex (u32) at word 8 (offset 32) — row into the shared transform buffer.
+        const node = nodeIndex >>> 0;
+        u32[offset + 8] = node;
+        if (node > this._maxNodeIndex) {
+            this._maxNodeIndex = node;
+        }
     }
     _ensureInstanceCapacity(instanceCount) {
         if (!this._device || instanceCount <= this._instanceCapacity) {
@@ -481,8 +602,8 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
             entries,
         });
     }
-    _getPipeline(blendMode, format) {
-        const pipelineKey = `${blendMode}:${format}`;
+    _getPipeline(blendMode, format, stencil) {
+        const pipelineKey = `${blendMode}:${format}:${stencil ? 's' : 'n'}`;
         const existingPipeline = this._pipelines.get(pipelineKey);
         if (existingPipeline) {
             return existingPipeline;
@@ -490,15 +611,15 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
         if (!this._device || !this._shaderModule || !this._pipelineLayout || !this._backend) {
             throw new Error('Renderer has to be connected first!');
         }
-        const pipeline = this._device.createRenderPipeline(this._buildPipelineDescriptor(blendMode, format));
+        const pipeline = this._device.createRenderPipeline(this._buildPipelineDescriptor(blendMode, format, stencil));
         this._pipelines.set(pipelineKey, pipeline);
         return pipeline;
     }
-    _buildPipelineDescriptor(blendMode, format) {
+    _buildPipelineDescriptor(blendMode, format, stencil = false) {
         if (!this._shaderModule || !this._pipelineLayout) {
             throw new Error('Renderer has to be connected first!');
         }
-        return {
+        const descriptor = {
             layout: this._pipelineLayout,
             vertex: {
                 module: this._shaderModule,
@@ -513,29 +634,24 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
                                 offset: 0,
                                 format: 'float32x4',
                             },
-                            {
-                                shaderLocation: 1,
-                                offset: 16,
-                                format: 'float32x3',
-                            },
-                            {
-                                shaderLocation: 2,
-                                offset: 28,
-                                format: 'float32x3',
-                            },
                             {
                                 shaderLocation: 3,
-                                offset: 40,
+                                offset: 16,
                                 format: 'unorm16x4',
                             },
                             {
                                 shaderLocation: 4,
-                                offset: 48,
+                                offset: 24,
                                 format: 'unorm8x4',
                             },
                             {
                                 shaderLocation: 5,
-                                offset: 52,
+                                offset: 28,
+                                format: 'uint32',
+                            },
+                            {
+                                shaderLocation: 6,
+                                offset: 32,
                                 format: 'uint32',
                             },
                         ],
@@ -557,7 +673,245 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
                 topology: 'triangle-list',
             },
         };
+        if (stencil) {
+            descriptor.depthStencil = stencilContentDepthStencilState();
+        }
+        return descriptor;
+    }
+    // ---------------------------------------------------------------------------
+    // Custom-material path
+    // ---------------------------------------------------------------------------
+    _drawCustomBatch(pass, device, backend, material, transformBindGroup, stencil) {
+        const resources = this._getOrCreateCustomResources(material, device);
+        const baseTexture = this._currentBaseTexture ?? Texture.empty;
+        // Re-built every frame so mutations to material.uniforms.X are picked up.
+        this._uploadUserUniforms(material, resources, device);
+        const pipeline = this._getOrCreateCustomPipeline(resources, this._currentBlendMode, backend.renderTargetFormat, stencil, device);
+        pass.setPipeline(pipeline);
+        pass.setBindGroup(0, transformBindGroup);
+        pass.setBindGroup(1, this._getCustomBaseTextureBindGroup(resources, backend, baseTexture, device));
+        pass.setBindGroup(2, this._buildUserBindGroup(material, resources, backend, device));
+        pass.setVertexBuffer(0, this._instanceBuffer);
+        pass.setIndexBuffer(this._indexBuffer, 'uint16');
+        pass.drawIndexed(indicesPerSprite, this._instanceCount, 0, 0, 0);
+    }
+    _getOrCreateCustomResources(material, device) {
+        const existing = this._customMaterials.get(material);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const wgsl = material.shader.wgsl;
+        if (wgsl === null) {
+            throw new Error('SpriteMaterial shader has no `wgsl` source; cannot render through the WebGPU backend.');
+        }
+        // The engine owns the vertex stage: prepend the canonical sprite vertex
+        // module (VertexInput/VertexOutput, group(0) projection + transform storage,
+        // group(1) base texture + sampler) to the material's fragment WGSL.
+        const shaderModule = device.createShaderModule({ code: `${spriteVertexWgsl}\n${wgsl}` });
+        const userLayout = this._buildUserBindGroupLayout(device, material);
+        const pipelineLayout = device.createPipelineLayout({
+            bindGroupLayouts: [this._uniformBindGroupLayout, this._customBaseTextureLayout, userLayout],
+        });
+        const resources = {
+            shaderModule,
+            userLayout,
+            pipelineLayout,
+            pipelines: new Map(),
+            userUniformBuffer: null,
+            userUniformBufferCapacity: 0,
+            baseTextureBindGroups: new WeakMap(),
+        };
+        this._customMaterials.set(material, resources);
+        material._onDispose(() => {
+            const stored = this._customMaterials.get(material);
+            if (stored !== undefined) {
+                this._releaseCustomResources(stored);
+                this._customMaterials.delete(material);
+            }
+        });
+        return resources;
+    }
+    _getOrCreateCustomPipeline(resources, blendMode, format, stencil, device) {
+        const cacheKey = `${blendMode}:${format}:${stencil ? 's' : 'n'}`;
+        const existing = resources.pipelines.get(cacheKey);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const descriptor = {
+            layout: resources.pipelineLayout,
+            vertex: {
+                module: resources.shaderModule,
+                entryPoint: 'vertexMain',
+                buffers: [
+                    {
+                        arrayStride: instanceStrideBytes,
+                        stepMode: 'instance',
+                        attributes: [
+                            { shaderLocation: 0, offset: 0, format: 'float32x4' },
+                            { shaderLocation: 3, offset: 16, format: 'unorm16x4' },
+                            { shaderLocation: 4, offset: 24, format: 'unorm8x4' },
+                            { shaderLocation: 5, offset: 28, format: 'uint32' },
+                            { shaderLocation: 6, offset: 32, format: 'uint32' },
+                        ],
+                    },
+                ],
+            },
+            fragment: {
+                module: resources.shaderModule,
+                entryPoint: 'fragmentMain',
+                targets: [
+                    {
+                        format,
+                        blend: getWebGpuBlendState(blendMode),
+                        writeMask: GPUColorWrite.ALL,
+                    },
+                ],
+            },
+            primitive: {
+                topology: 'triangle-list',
+            },
+        };
+        if (stencil) {
+            descriptor.depthStencil = stencilContentDepthStencilState();
+        }
+        const pipeline = device.createRenderPipeline(descriptor);
+        resources.pipelines.set(cacheKey, pipeline);
+        return pipeline;
+    }
+    _getCustomBaseTextureBindGroup(resources, backend, texture, device) {
+        const existing = resources.baseTextureBindGroups.get(texture);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const binding = backend.getTextureBinding(texture);
+        const group = device.createBindGroup({
+            layout: this._customBaseTextureLayout,
+            entries: [
+                { binding: 0, resource: binding.view },
+                { binding: 1, resource: binding.sampler },
+            ],
+        });
+        resources.baseTextureBindGroups.set(texture, group);
+        return group;
+    }
+    _buildUserBindGroupLayout(device, material) {
+        const entries = [];
+        // Binding 0 always reserved for the user UBO (even if empty), so the layout
+        // is stable across user-uniform mutations.
+        entries.push({
+            binding: 0,
+            visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
+            buffer: { type: 'uniform' },
+        });
+        const textureBindings = collectTextureBindings(material);
+        if (textureBindings.length > maxCustomTextureSlots) {
+            throw new Error(`SpriteMaterial requested more than ${maxCustomTextureSlots} user texture bindings.`);
+        }
+        let bindingIndex = 1;
+        for (let t = 0; t < textureBindings.length; t++) {
+            entries.push({ binding: bindingIndex, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: 'float' } });
+            bindingIndex++;
+            entries.push({ binding: bindingIndex, visibility: GPUShaderStage.FRAGMENT, sampler: { type: 'filtering' } });
+            bindingIndex++;
+        }
+        return device.createBindGroupLayout({ entries });
+    }
+    _uploadUserUniforms(material, resources, device) {
+        const scalarValues = collectScalarUniforms(material);
+        // Always create a UBO (even if empty) since binding 0 of the user layout is
+        // fixed. Min size 16 bytes to satisfy WebGPU's minimum buffer size.
+        const slotCount = Math.max(scalarValues.length, 1);
+        const bufferBytes = slotCount * 16;
+        if (resources.userUniformBuffer === null || resources.userUniformBufferCapacity < bufferBytes) {
+            resources.userUniformBuffer?.destroy();
+            resources.userUniformBufferCapacity = bufferBytes;
+            resources.userUniformBuffer = device.createBuffer({
+                size: bufferBytes,
+                usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+            });
+        }
+        const data = new Float32Array(bufferBytes / 4);
+        let slot = 0;
+        for (const value of scalarValues) {
+            const baseFloatIndex = slot * 4;
+            if (typeof value === 'number') {
+                data[baseFloatIndex] = value;
+            }
+            else if (value instanceof Float32Array) {
+                data.set(value, baseFloatIndex);
+            }
+            else if (value instanceof Int32Array) {
+                for (let i = 0; i < value.length; i++) {
+                    data[baseFloatIndex + i] = value[i];
+                }
+            }
+            else {
+                const arr = value;
+                for (let i = 0; i < arr.length; i++) {
+                    data[baseFloatIndex + i] = arr[i];
+                }
+            }
+            slot++;
+        }
+        device.queue.writeBuffer(resources.userUniformBuffer, 0, data);
+    }
+    _buildUserBindGroup(material, resources, backend, device) {
+        const entries = [];
+        entries.push({ binding: 0, resource: { buffer: resources.userUniformBuffer } });
+        let bindingIndex = 1;
+        for (const texture of collectTextureBindings(material)) {
+            const binding = backend.getTextureBinding(texture);
+            entries.push({ binding: bindingIndex, resource: binding.view });
+            bindingIndex++;
+            entries.push({ binding: bindingIndex, resource: binding.sampler });
+            bindingIndex++;
+        }
+        return device.createBindGroup({ layout: resources.userLayout, entries });
+    }
+    _releaseCustomResources(resources) {
+        resources.userUniformBuffer?.destroy();
+        resources.pipelines.clear();
+        resources.userUniformBuffer = null;
+        resources.userUniformBufferCapacity = 0;
+        resources.baseTextureBindGroups = new WeakMap();
+    }
+}
+function isTextureUniform(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'width' in value &&
+        'height' in value &&
+        !(value instanceof Float32Array) &&
+        !(value instanceof Int32Array) &&
+        !Array.isArray(value));
+}
+/** Scalar/vector/matrix uniforms (texture values excluded) in declaration order. */
+function collectScalarUniforms(material) {
+    const result = [];
+    for (const value of Object.values(material.uniforms)) {
+        if (!isTextureUniform(value)) {
+            result.push(value);
+        }
+    }
+    return result;
+}
+/**
+ * Texture bindings claimed by the material, in a stable order: texture-valued
+ * entries of `uniforms` first (declaration order), then the dedicated
+ * `textures` map. The WGSL source must declare its `@group(2)` texture/sampler
+ * pairs in this same order.
+ */
+function collectTextureBindings(material) {
+    const result = [];
+    for (const value of Object.values(material.uniforms)) {
+        if (isTextureUniform(value)) {
+            result.push(value);
+        }
+    }
+    for (const texture of Object.values(material.textures)) {
+        result.push(texture);
     }
+    return result;
 }
 
 export { WebGpuSpriteRenderer };