@codexo/exojs-tilemap 0.15.3 → 0.16.0

package/dist/esm/webgpu/WebGpuTileChunkRenderer.js

@@ -1,390 +1,503 @@
-import { AbstractWebGpuRenderer, Texture, getWebGpuBlendState, stencilContentDepthStencilState } from '@codexo/exojs/renderer-sdk';
+import { TILE_DIAGONAL_BIT, TILE_ROW_MASK } from "../tileWord.js";
+import tile_chunk_default from "./shaders/tile-chunk.wgsl.js";
+import { AbstractWebGpuRenderer, DataTexture, Texture, fillShaderSource, getWebGpuBlendState, packAffineMat4, packSnapViewport, packedGroupChanged, retainedGroupUniformBytes, stencilContentDepthStencilState } from "@codexo/exojs/renderer-sdk";
+import { Matrix } from "@codexo/exojs";
 
-/// <reference types="@webgpu/types" />
+//#region src/webgpu/WebGpuTileChunkRenderer.ts
 const instanceStrideBytes = 32;
-const wordsPerInstance = instanceStrideBytes / Uint32Array.BYTES_PER_ELEMENT; // = 8
-const projectionByteLength = 64;
+const wordsPerInstance = instanceStrideBytes / Uint32Array.BYTES_PER_ELEMENT;
+const projectionByteLength = 144;
 const initialBatchCapacity = 256;
 const indicesPerInstance = 6;
-const quadIndices = new Uint16Array([0, 1, 2, 0, 2, 3]);
-const TILE_ROW_MASK = 0x1fffffff;
-const TILE_DIAGONAL_BIT = 0x20000000;
-const tileShaderSource = `
-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 tileTexture: texture_2d<f32>;
-@group(1) @binding(1)
-var tileSampler: sampler;
-
-struct VertexInput {
-    @location(0) quadBounds: vec4<f32>,   // x0, y0, x1, y1
-    @location(1) uvBounds: vec4<f32>,     // uMin, vMin, uMax, vMax (flipX/Y + texture flipY baked)
-    @location(2) color: vec4<f32>,        // RGBA tint (layer opacity in alpha)
-    @location(3) tileWord: u32,           // transform row (bits 0..28) | diagonal (bit 29)
-};
-
-struct VertexOutput {
-    @builtin(position) position: vec4<f32>,
-    @location(0) texcoord: vec2<f32>,
-    @location(1) color: vec4<f32>,
-};
-
-@vertex
-fn vertexMain(input: VertexInput, @builtin(vertex_index) vid: u32) -> VertexOutput {
-    var output: VertexOutput;
-
-    // vid 0..3 → TL, TR, BR, BL (matches static index buffer [0,1,2,0,2,3])
-    let cornerX = ((vid + 1u) >> 1u) & 1u;
-    let cornerY = vid >> 1u;
-
-    let localX = select(input.quadBounds.x, input.quadBounds.z, cornerX == 1u);
-    let localY = select(input.quadBounds.y, input.quadBounds.w, cornerY == 1u);
-
-    let row = input.tileWord & ${TILE_ROW_MASK}u;
-    let diagonal = (input.tileWord & ${TILE_DIAGONAL_BIT}u) != 0u;
-
-    let slot = transforms[row];
-    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);
-
-    // Tile orientation: diagonal transposes the corner-coordinate axes; flipX/Y
-    // are baked into the UV corner ordering by the CPU writer.
-    var su = cornerX;
-    var sv = cornerY;
-    if (diagonal) {
-        let t = su;
-        su = sv;
-        sv = t;
-    }
-
-    let u = select(input.uvBounds.x, input.uvBounds.z, su == 1u);
-    let v = select(input.uvBounds.y, input.uvBounds.w, sv == 1u);
-    output.texcoord = vec2<f32>(u, v);
-
-    output.color = vec4(input.color.rgb * input.color.a, input.color.a);
-
-    return output;
-}
-
-@fragment
-fn fragmentMain(input: VertexOutput) -> @location(0) vec4<f32> {
-    let sample = textureSample(tileTexture, tileSampler, input.texcoord);
-    return sample * input.color;
-}
-`;
+const quadIndices = new Uint16Array([
+	0,
+	1,
+	2,
+	0,
+	2,
+	3
+]);
+const tileShaderSource = fillShaderSource(tile_chunk_default, {
+	tileRowMask: TILE_ROW_MASK,
+	tileDiagonalBit: TILE_DIAGONAL_BIT
+});
 /**
- * Instanced WebGPU renderer for {@link TileChunkNode}, the parity counterpart of
- * the WebGL2 renderer. Same instance layout and orientation handling; per-chunk
- * transforms ride on the backend's shared transform storage buffer, and the
- * instance buffer grows on demand rather than flushing in fixed runs.
- * @internal
- */
-class WebGpuTileChunkRenderer extends AbstractWebGpuRenderer {
-    _projectionData = new Float32Array(projectionByteLength / Float32Array.BYTES_PER_ELEMENT);
-    _device = null;
-    _shaderModule = null;
-    _uniformBindGroupLayout = null;
-    _textureBindGroupLayout = null;
-    _pipelineLayout = null;
-    _uniformBuffer = null;
-    _transformBindGroup = null;
-    _transformStorageBuffer = null;
-    _indexBuffer = null;
-    _instanceBuffer = null;
-    _instanceCapacity = 0;
-    _instanceData = new ArrayBuffer(0);
-    _instanceFloat32 = new Float32Array(this._instanceData);
-    _instanceUint32 = new Uint32Array(this._instanceData);
-    _pipelines = new Map();
-    _quadIndex = 0;
-    _maxNodeIndex = 0;
-    _currentBlendMode = null;
-    _currentTexture = null;
-    onConnect(backend) {
-        if (this._device) {
-            return;
-        }
-        this._device = backend.device;
-        this._shaderModule = this._device.createShaderModule({ code: tileShaderSource });
-        this._uniformBindGroupLayout = this._device.createBindGroupLayout({
-            entries: [
-                { binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: 'uniform' } },
-                { binding: 1, visibility: GPUShaderStage.VERTEX, buffer: { type: 'read-only-storage' } },
-            ],
-        });
-        this._textureBindGroupLayout = this._device.createBindGroupLayout({
-            entries: [
-                { binding: 0, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: 'float' } },
-                { binding: 1, 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._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._instanceBuffer?.destroy();
-        this._indexBuffer?.destroy();
-        this._uniformBuffer?.destroy();
-        this._pipelines.clear();
-        this._instanceBuffer = null;
-        this._indexBuffer = null;
-        this._transformBindGroup = null;
-        this._transformStorageBuffer = null;
-        this._uniformBuffer = null;
-        this._pipelineLayout = null;
-        this._textureBindGroupLayout = null;
-        this._uniformBindGroupLayout = null;
-        this._shaderModule = null;
-        this._device = null;
-        this._backend = null;
-        this._instanceCapacity = 0;
-        this._instanceData = new ArrayBuffer(0);
-        this._instanceFloat32 = new Float32Array(this._instanceData);
-        this._instanceUint32 = new Uint32Array(this._instanceData);
-        this._quadIndex = 0;
-        this._maxNodeIndex = 0;
-        this._currentBlendMode = null;
-        this._currentTexture = null;
-    }
-    render(node) {
-        const backend = this._backend;
-        if (backend === null) {
-            return;
-        }
-        const pages = node.pages;
-        if (pages.length === 0) {
-            return;
-        }
-        const blendMode = node.blendMode;
-        const tintRgba = node.tint.toRgba();
-        const command = backend.activeDrawCommand;
-        const nodeIndex = command !== null ? command.nodeIndex : backend._pushTransform(node);
-        for (const page of pages) {
-            this._renderPage(backend, page.texture, page.quads, blendMode, tintRgba, nodeIndex);
-        }
-    }
-    _renderPage(backend, texture, quads, blendMode, tintRgba, nodeIndex) {
-        if (quads.length === 0) {
-            return;
-        }
-        if (texture.width === 0 || texture.height === 0) {
-            return;
-        }
-        if (texture instanceof Texture && texture.source === null) {
-            return;
-        }
-        const blendModeChanged = this._currentBlendMode !== null && blendMode !== this._currentBlendMode;
-        const textureChanged = this._currentTexture !== null && texture !== this._currentTexture;
-        const willExceed = this._quadIndex + quads.length > this._instanceCapacity && this._instanceCapacity > 0;
-        if ((blendModeChanged || textureChanged || willExceed) && this._quadIndex > 0) {
-            this.flush();
-        }
-        this._currentBlendMode = blendMode;
-        this._currentTexture = texture;
-        backend.setBlendMode(blendMode);
-        this._ensureInstanceCapacity(this._quadIndex + quads.length);
-        const f32 = this._instanceFloat32;
-        const u32 = this._instanceUint32;
-        const flipYTexture = texture.flipY;
-        const baseWord = nodeIndex & TILE_ROW_MASK;
-        for (const q of quads) {
-            const idx = this._quadIndex * wordsPerInstance;
-            f32[idx + 0] = q.x0;
-            f32[idx + 1] = q.y0;
-            f32[idx + 2] = q.x1;
-            f32[idx + 3] = q.y1;
-            const flipX = (q.orient & 1) !== 0;
-            const tileFlipY = (q.orient & 2) !== 0;
-            const diagonal = (q.orient & 4) !== 0;
-            const uA = flipX ? q.u1 : q.u0;
-            const uB = flipX ? q.u0 : q.u1;
-            let vA = tileFlipY ? q.v1 : q.v0;
-            let vB = tileFlipY ? q.v0 : q.v1;
-            if (flipYTexture) {
-                const swap = vA;
-                vA = vB;
-                vB = swap;
-            }
-            const uMin = (uA * 0xffff) & 0xffff;
-            const vMin = (vA * 0xffff) & 0xffff;
-            const uMax = (uB * 0xffff) & 0xffff;
-            const vMax = (vB * 0xffff) & 0xffff;
-            u32[idx + 4] = uMin | (vMin << 16);
-            u32[idx + 5] = uMax | (vMax << 16);
-            u32[idx + 6] = tintRgba;
-            u32[idx + 7] = (diagonal ? baseWord | TILE_DIAGONAL_BIT : baseWord) >>> 0;
-            this._quadIndex++;
-        }
-        if (nodeIndex > this._maxNodeIndex) {
-            this._maxNodeIndex = nodeIndex;
-        }
-    }
-    flush() {
-        const backend = this._backend;
-        const device = this._device;
-        const uniformBuffer = this._uniformBuffer;
-        if (!backend || !device || !uniformBuffer) {
-            return;
-        }
-        if (this._quadIndex === 0 && !backend.clearRequested) {
-            return;
-        }
-        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 scissor = backend.getScissorRect();
-        const maskClipsAll = scissor !== null && (scissor.width <= 0 || scissor.height <= 0);
-        const pass = backend._passCoordinator.acquirePass().pass;
-        if (this._quadIndex > 0 && !maskClipsAll && this._instanceBuffer !== null && this._indexBuffer !== null && this._currentBlendMode !== null && this._currentTexture !== null) {
-            device.queue.writeBuffer(this._instanceBuffer, 0, this._instanceData, 0, this._quadIndex * instanceStrideBytes);
-            const storage = backend.getTransformStorageBuffer(this._maxNodeIndex + 1);
-            const transformBindGroup = this._getOrCreateTransformBindGroup(device, uniformBuffer, storage.buffer);
-            const textureBindGroup = this._createTextureBindGroup(device, backend, this._currentTexture);
-            const stencil = backend._passCoordinator.stencilActive;
-            const pipeline = this._getPipeline(this._currentBlendMode, backend.renderTargetFormat, stencil);
-            pass.setPipeline(pipeline);
-            pass.setBindGroup(0, transformBindGroup);
-            pass.setBindGroup(1, textureBindGroup);
-            pass.setVertexBuffer(0, this._instanceBuffer);
-            pass.setIndexBuffer(this._indexBuffer, 'uint16');
-            pass.drawIndexed(indicesPerInstance, this._quadIndex, 0, 0, 0);
-            backend.stats.batches++;
-            backend.stats.drawCalls++;
-        }
-        backend._passCoordinator.endPass();
-        this._quadIndex = 0;
-        this._maxNodeIndex = 0;
-        this._currentBlendMode = null;
-        this._currentTexture = null;
-    }
-    destroy() {
-        this.disconnect();
-    }
-    _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;
-    }
-    _createTextureBindGroup(device, backend, texture) {
-        const binding = backend.getTextureBinding(texture);
-        return device.createBindGroup({
-            layout: this._textureBindGroupLayout,
-            entries: [
-                { binding: 0, resource: binding.view },
-                { binding: 1, resource: binding.sampler },
-            ],
-        });
-    }
-    _getPipeline(blendMode, format, stencil) {
-        const key = `${blendMode}:${format}:${stencil ? 's' : 'n'}`;
-        const existing = this._pipelines.get(key);
-        if (existing) {
-            return existing;
-        }
-        if (!this._device || !this._shaderModule || !this._pipelineLayout) {
-            throw new Error('WebGpuTileChunkRenderer: renderer must be connected first.');
-        }
-        const descriptor = {
-            layout: this._pipelineLayout,
-            vertex: {
-                module: this._shaderModule,
-                entryPoint: 'vertexMain',
-                buffers: [
-                    {
-                        arrayStride: instanceStrideBytes,
-                        stepMode: 'instance',
-                        attributes: [
-                            { shaderLocation: 0, offset: 0, format: 'float32x4' },
-                            { shaderLocation: 1, offset: 16, format: 'unorm16x4' },
-                            { shaderLocation: 2, offset: 24, format: 'unorm8x4' },
-                            { shaderLocation: 3, offset: 28, format: 'uint32' },
-                        ],
-                    },
-                ],
-            },
-            fragment: {
-                module: this._shaderModule,
-                entryPoint: 'fragmentMain',
-                targets: [
-                    {
-                        format,
-                        blend: getWebGpuBlendState(blendMode),
-                        writeMask: GPUColorWrite.ALL,
-                    },
-                ],
-            },
-            primitive: {
-                topology: 'triangle-list',
-            },
-        };
-        if (stencil) {
-            descriptor.depthStencil = stencilContentDepthStencilState();
-        }
-        const pipeline = this._device.createRenderPipeline(descriptor);
-        this._pipelines.set(key, pipeline);
-        return pipeline;
-    }
-    _ensureInstanceCapacity(instanceCount) {
-        if (!this._device || instanceCount <= this._instanceCapacity) {
-            return;
-        }
-        let nextCapacity = Math.max(this._instanceCapacity, initialBatchCapacity);
-        while (nextCapacity < instanceCount) {
-            nextCapacity *= 2;
-        }
-        const oldData = this._instanceData;
-        const carryBytes = Math.min(this._quadIndex * 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;
-    }
-}
+* Instanced WebGPU renderer for {@link TileChunkNode}, the parity counterpart of
+* the WebGL2 renderer. Same instance layout and orientation handling; per-chunk
+* transforms ride on the backend's shared transform storage buffer, and the
+* instance buffer grows on demand rather than flushing in fixed runs.
+* @internal
+*/
+var WebGpuTileChunkRenderer = class extends AbstractWebGpuRenderer {
+	/**
+	* Retained-batch capability opt-in: a tile chunk's per-flush
+	* instanced batches (fixed 32-byte layout, tile word at word 7) record and
+	* replay from group-owned resources. Pixel-snapped draws are excluded by
+	* the collect-time recordability predicate (and belt-and-braces poisoning
+	* in {@link render}); tile chunks have no custom-material path to exclude.
+	* @internal
+	*/
+	_supportsRetainedBatches = true;
+	_projectionData = new Float32Array(projectionByteLength / Float32Array.BYTES_PER_ELEMENT);
+	_writtenView = null;
+	_writtenViewUpdateId = -1;
+	_hasWrittenProjection = false;
+	_stagedGroupData = /* @__PURE__ */ new Float32Array(16);
+	_device = null;
+	_shaderModule = null;
+	_uniformBindGroupLayout = null;
+	_textureBindGroupLayout = null;
+	_pipelineLayout = null;
+	_uniformBuffer = null;
+	_transformBindGroup = null;
+	_transformStorageBuffer = null;
+	_indexBuffer = null;
+	_instanceBuffer = null;
+	_instanceBufferCapacity = 0;
+	_instanceStagingCapacity = 0;
+	_instanceData = /* @__PURE__ */ new ArrayBuffer(0);
+	_instanceFloat32 = new Float32Array(this._instanceData);
+	_instanceUint32 = new Uint32Array(this._instanceData);
+	_pipelines = /* @__PURE__ */ new Map();
+	_textureBindGroups = /* @__PURE__ */ new WeakMap();
+	_quadIndex = 0;
+	_maxNodeIndex = 0;
+	_batchNodeCount = 0;
+	_nodeBooked = false;
+	_currentBlendMode = null;
+	_currentTexture = null;
+	_passDraws = null;
+	_instancePassBytes = 0;
+	_stagedReplayGroupData = /* @__PURE__ */ new Float32Array(16);
+	_recordTextures = [null];
+	onConnect(backend) {
+		if (this._device) return;
+		this._device = backend.device;
+		this._shaderModule = this._device.createShaderModule({ code: tileShaderSource });
+		this._uniformBindGroupLayout = this._device.createBindGroupLayout({ entries: [{
+			binding: 0,
+			visibility: GPUShaderStage.VERTEX,
+			buffer: { type: "uniform" }
+		}, {
+			binding: 1,
+			visibility: GPUShaderStage.VERTEX,
+			buffer: { type: "read-only-storage" }
+		}] });
+		this._textureBindGroupLayout = this._device.createBindGroupLayout({ entries: [{
+			binding: 0,
+			visibility: GPUShaderStage.FRAGMENT,
+			texture: { sampleType: "float" }
+		}, {
+			binding: 1,
+			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._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() {
+		const coordinator = this._backend?._passCoordinator ?? null;
+		if (coordinator !== null && this._passDraws !== null && this._passDraws === coordinator.activePass) coordinator.endPass();
+		this._instanceBuffer?.destroy();
+		this._indexBuffer?.destroy();
+		this._uniformBuffer?.destroy();
+		this._pipelines.clear();
+		this._instanceBuffer = null;
+		this._indexBuffer = null;
+		this._transformBindGroup = null;
+		this._transformStorageBuffer = null;
+		this._textureBindGroups = /* @__PURE__ */ new WeakMap();
+		this._uniformBuffer = null;
+		this._pipelineLayout = null;
+		this._textureBindGroupLayout = null;
+		this._uniformBindGroupLayout = null;
+		this._shaderModule = null;
+		this._device = null;
+		this._backend = null;
+		this._instanceBufferCapacity = 0;
+		this._instanceStagingCapacity = 0;
+		this._instanceData = /* @__PURE__ */ new ArrayBuffer(0);
+		this._instanceFloat32 = new Float32Array(this._instanceData);
+		this._instanceUint32 = new Uint32Array(this._instanceData);
+		this._passDraws = null;
+		this._instancePassBytes = 0;
+		this._quadIndex = 0;
+		this._maxNodeIndex = 0;
+		this._batchNodeCount = 0;
+		this._nodeBooked = false;
+		this._currentBlendMode = null;
+		this._currentTexture = null;
+		this._writtenView = null;
+		this._writtenViewUpdateId = -1;
+		this._hasWrittenProjection = false;
+	}
+	render(node) {
+		const backend = this._backend;
+		if (backend === null) return;
+		const pages = node.pages;
+		this._nodeBooked = false;
+		if (pages.length === 0) return;
+		const blendMode = node.blendMode;
+		const tintRgba = node.tint.toRgba8();
+		const command = backend.activeDrawCommand;
+		const nodeIndex = command !== null ? command.nodeIndex : backend._pushTransform(node);
+		for (const page of pages) this._renderPage(backend, page.texture, page.quads, blendMode, tintRgba, nodeIndex);
+	}
+	_renderPage(backend, texture, quads, blendMode, tintRgba, nodeIndex) {
+		if (quads.length === 0) return;
+		if (texture.width === 0 || texture.height === 0) return;
+		if (texture instanceof Texture && !(texture instanceof DataTexture) && texture.source === null) return;
+		const blendModeChanged = this._currentBlendMode !== null && blendMode !== this._currentBlendMode;
+		const textureChanged = this._currentTexture !== null && texture !== this._currentTexture;
+		const willExceed = this._quadIndex + quads.length > this._instanceStagingCapacity && this._instanceStagingCapacity > 0;
+		if ((blendModeChanged || textureChanged || willExceed) && this._quadIndex > 0) this.flush();
+		this._currentBlendMode = blendMode;
+		this._currentTexture = texture;
+		backend.setBlendMode(blendMode);
+		this._ensureStagingCapacity(this._quadIndex + quads.length);
+		if (!this._nodeBooked) {
+			this._nodeBooked = true;
+			this._batchNodeCount++;
+		}
+		const f32 = this._instanceFloat32;
+		const u32 = this._instanceUint32;
+		const flipYTexture = texture.flipY;
+		const baseWord = nodeIndex & TILE_ROW_MASK;
+		for (const q of quads) {
+			const idx = this._quadIndex * wordsPerInstance;
+			f32[idx + 0] = q.x0;
+			f32[idx + 1] = q.y0;
+			f32[idx + 2] = q.x1;
+			f32[idx + 3] = q.y1;
+			const flipX = (q.orient & 1) !== 0;
+			const tileFlipY = (q.orient & 2) !== 0;
+			const diagonal = (q.orient & 4) !== 0;
+			const uA = flipX ? q.u1 : q.u0;
+			const uB = flipX ? q.u0 : q.u1;
+			let vA = tileFlipY ? q.v1 : q.v0;
+			let vB = tileFlipY ? q.v0 : q.v1;
+			if (flipYTexture) {
+				const swap = vA;
+				vA = vB;
+				vB = swap;
+			}
+			const uMin = uA * 65535 & 65535;
+			const vMin = vA * 65535 & 65535;
+			const uMax = uB * 65535 & 65535;
+			const vMax = vB * 65535 & 65535;
+			u32[idx + 4] = uMin | vMin << 16;
+			u32[idx + 5] = uMax | vMax << 16;
+			u32[idx + 6] = tintRgba;
+			u32[idx + 7] = (diagonal ? baseWord | TILE_DIAGONAL_BIT : baseWord) >>> 0;
+			this._quadIndex++;
+		}
+		if (nodeIndex > this._maxNodeIndex) this._maxNodeIndex = nodeIndex;
+	}
+	flush() {
+		const backend = this._backend;
+		const device = this._device;
+		const uniformBuffer = this._uniformBuffer;
+		if (!backend || !device || !uniformBuffer) return;
+		if (this._quadIndex === 0 && !backend.clearRequested) return;
+		const view = backend.view;
+		const viewportChanged = packSnapViewport(backend, this._projectionData, 32);
+		const projectionChanged = !this._hasWrittenProjection || this._writtenView !== view || this._writtenViewUpdateId !== view.updateId || viewportChanged || this._groupContentChanged(backend);
+		const scissor = backend.getScissorRect();
+		const maskClipsAll = scissor !== null && (scissor.width <= 0 || scissor.height <= 0);
+		const coordinator = backend._passCoordinator;
+		const texture = this._currentTexture;
+		const blendMode = this._currentBlendMode;
+		const indexBuffer = this._indexBuffer;
+		const willDraw = this._quadIndex > 0 && !maskClipsAll && texture !== null && blendMode !== null && indexBuffer !== null;
+		const flushBytes = this._quadIndex * instanceStrideBytes;
+		const targetInstanceBytes = this._instancePassBytes + flushBytes;
+		if (this._passDraws !== null && this._passDraws === coordinator.activePass && (projectionChanged || willDraw && targetInstanceBytes > this._instanceBufferCapacity) || willDraw && coordinator.passHasDraws && (backend._textureUploadWouldMutate(texture) || backend._transformStorageWouldGrow(this._maxNodeIndex + 1))) coordinator.endPass();
+		if (this._passDraws !== coordinator.activePass) {
+			this._passDraws = null;
+			this._instancePassBytes = 0;
+		}
+		if (projectionChanged) {
+			packAffineMat4(view.getTransform(), this._projectionData, 0);
+			packAffineMat4(backend.renderGroupTransform ?? Matrix.identity, this._projectionData, 16);
+			this._writtenView = view;
+			this._writtenViewUpdateId = view.updateId;
+			this._hasWrittenProjection = true;
+			device.queue.writeBuffer(uniformBuffer, 0, this._projectionData.buffer, this._projectionData.byteOffset, this._projectionData.byteLength);
+		}
+		if (willDraw || backend.clearRequested) {
+			const active = coordinator.acquirePass();
+			const pass = active.pass;
+			if (willDraw) {
+				const instanceBuffer = this._ensureInstanceBufferCapacity(device, targetInstanceBytes);
+				const instanceByteOffset = this._instancePassBytes;
+				device.queue.writeBuffer(instanceBuffer, instanceByteOffset, this._instanceData, 0, flushBytes);
+				const storage = backend.getTransformStorageBuffer(this._maxNodeIndex + 1);
+				const transformBindGroup = this._getOrCreateTransformBindGroup(device, uniformBuffer, storage.buffer);
+				const textureBindGroup = this._getOrCreateTextureBindGroup(device, backend, texture);
+				const stencil = coordinator.stencilActive;
+				const pipeline = this._getPipeline(blendMode, backend.renderTargetFormat, stencil);
+				pass.setPipeline(pipeline);
+				pass.setBindGroup(0, transformBindGroup);
+				pass.setBindGroup(1, textureBindGroup);
+				pass.setVertexBuffer(0, instanceBuffer, instanceByteOffset);
+				pass.setIndexBuffer(indexBuffer, "uint16");
+				pass.drawIndexed(indicesPerInstance, this._quadIndex, 0, 0, 0);
+				this._instancePassBytes = instanceByteOffset + flushBytes;
+				this._passDraws = active;
+				coordinator.markPassDraws();
+				backend.stats.batches++;
+				backend.stats.drawCalls++;
+			}
+		}
+		if (this._quadIndex > 0 && backend._retainedCaptureActive && blendMode !== null && texture !== null) {
+			this._recordTextures[0] = texture;
+			backend._recordRetainedBatch(this, this._instanceData, flushBytes, this._quadIndex, blendMode, this._recordTextures, 1, null, null, this._batchNodeCount);
+		}
+		this._quadIndex = 0;
+		this._maxNodeIndex = 0;
+		this._batchNodeCount = 0;
+		this._currentBlendMode = null;
+		this._currentTexture = null;
+	}
+	/**
+	* Whether the packed floats of the active group matrix differ from what the
+	* shared projection UBO currently holds at [16, 32). Stages the packed matrix
+	* into `_stagedGroupData` as a side effect (idempotent - safe to call more
+	* than once per flush).
+	*/
+	_groupContentChanged(backend) {
+		packAffineMat4(backend.renderGroupTransform ?? Matrix.identity, this._stagedGroupData, 0);
+		if (!this._hasWrittenProjection) return true;
+		return packedGroupChanged(this._stagedGroupData, this._projectionData, 16);
+	}
+	destroy() {
+		this.disconnect();
+	}
+	_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;
+	}
+	/**
+	* Build (or reuse) the group(1) texture bind group for `texture`. The
+	* binding is resolved BEFORE the cache lookup on purpose: resolving is what
+	* syncs a dirty/mutated texture's content to the GPU, so it must run every
+	* flush/replay even when the bind group itself is served from cache.
+	*/
+	_getOrCreateTextureBindGroup(device, backend, texture) {
+		const { view, sampler } = backend.getTextureBinding(texture);
+		const cached = this._textureBindGroups.get(texture);
+		if (cached?.view === view && cached.sampler === sampler) return cached.group;
+		const group = device.createBindGroup({
+			layout: this._textureBindGroupLayout,
+			entries: [{
+				binding: 0,
+				resource: view
+			}, {
+				binding: 1,
+				resource: sampler
+			}]
+		});
+		this._textureBindGroups.set(texture, {
+			group,
+			view,
+			sampler
+		});
+		return group;
+	}
+	/** @internal See {@link WebGpuRetainedBatchReplayer._scanRetainedNodeIndexRange}. */
+	_scanRetainedNodeIndexRange(bytes, range) {
+		const words = new Uint32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength / Uint32Array.BYTES_PER_ELEMENT);
+		for (let i = 7; i < words.length; i += 8) {
+			const row = words[i] & TILE_ROW_MASK;
+			if (row < range.min) range.min = row;
+			if (row > range.max) range.max = row;
+		}
+	}
+	/** @internal See {@link WebGpuRetainedBatchReplayer._rebaseRetainedNodeIndices} (group-local indices). */
+	_rebaseRetainedNodeIndices(bytes, base) {
+		const words = new Uint32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength / Uint32Array.BYTES_PER_ELEMENT);
+		for (let i = 7; i < words.length; i += 8) {
+			const word = words[i];
+			const diagonal = word & TILE_DIAGONAL_BIT;
+			const row = word & TILE_ROW_MASK;
+			words[i] = (diagonal | row - base & TILE_ROW_MASK) >>> 0;
+		}
+	}
+	/**
+	* Replay one recorded batch from its group-owned bundle into the OPEN pass.
+	* Reuses only recorded DATA (instance bytes, transform rows, texture, blend
+	* mode); every piece of STATE is resolved live - pipeline via the
+	* `_getPipeline` cache, the group(1) texture bind group via the live
+	* texture-set cache (resolving re-syncs dirty content), and the group's
+	* 128-byte UBO (projection from the live view + the live composed group
+	* matrix) written only when its content changed. The same-frame
+	* double-replay hazard (one group under two views while the open pass
+	* already holds this bundle's draws) ends the pass first.
+	* @internal
+	*/
+	_replayRetainedBatch(payload) {
+		const backend = this._backend;
+		const device = this._device;
+		const bundle = payload.bundle;
+		if (!backend || !device || this._indexBuffer === null || !bundle.isReady) return;
+		this.flush();
+		const scissor = backend.getScissorRect();
+		if (scissor !== null && (scissor.width <= 0 || scissor.height <= 0)) return;
+		const coordinator = backend._passCoordinator;
+		if (coordinator.passHasDraws) {
+			for (const texture of payload.textures) if (backend._textureUploadWouldMutate(texture)) {
+				coordinator.endPass();
+				break;
+			}
+		}
+		const textureBindGroup = this._getOrCreateTextureBindGroup(device, backend, payload.textures[0]);
+		const view = backend.view;
+		const scratch = this._stagedReplayGroupData;
+		packAffineMat4(backend.renderGroupTransform ?? Matrix.identity, scratch, 0);
+		const viewportChanged = packSnapViewport(backend, bundle.uboData, 32);
+		let uboDirty = !bundle.uboWritten || bundle.uboView !== view || bundle.uboViewUpdateId !== view.updateId || viewportChanged;
+		if (!uboDirty) {
+			for (let i = 0; i < 16; i++) if (scratch[i] !== bundle.uboData[16 + i]) {
+				uboDirty = true;
+				break;
+			}
+		}
+		if (uboDirty) {
+			const activePass = coordinator.activePass;
+			if (activePass !== null && bundle.drawsInPass === activePass) coordinator.endPass();
+			packAffineMat4(view.getTransform(), bundle.uboData, 0);
+			bundle.uboData.set(scratch, 16);
+			bundle.uboView = view;
+			bundle.uboViewUpdateId = view.updateId;
+			bundle.uboWritten = true;
+			device.queue.writeBuffer(bundle.uniformBuffer, 0, bundle.uboData.buffer, bundle.uboData.byteOffset, retainedGroupUniformBytes);
+		}
+		const active = coordinator.acquirePass();
+		const pass = active.pass;
+		pass.setPipeline(this._getPipeline(payload.blendMode, backend.renderTargetFormat, coordinator.stencilActive));
+		pass.setBindGroup(0, bundle.getBindGroup(device, this._uniformBindGroupLayout, false));
+		pass.setBindGroup(1, textureBindGroup);
+		pass.setVertexBuffer(0, bundle.instanceBuffer, payload.byteOffset);
+		pass.setIndexBuffer(this._indexBuffer, "uint16");
+		pass.drawIndexed(indicesPerInstance, payload.instanceCount, 0, 0, 0);
+		bundle.drawsInPass = active;
+		coordinator.markPassDraws();
+		backend.stats.batches++;
+		backend.stats.drawCalls++;
+	}
+	_getPipeline(blendMode, format, stencil) {
+		const key = `${blendMode}:${format}:${stencil ? "s" : "n"}`;
+		const existing = this._pipelines.get(key);
+		if (existing) return existing;
+		if (!this._device || !this._shaderModule || !this._pipelineLayout) throw new Error("WebGpuTileChunkRenderer: renderer must be connected first.");
+		const descriptor = {
+			layout: this._pipelineLayout,
+			vertex: {
+				module: this._shaderModule,
+				entryPoint: "vertexMain",
+				buffers: [{
+					arrayStride: instanceStrideBytes,
+					stepMode: "instance",
+					attributes: [
+						{
+							shaderLocation: 0,
+							offset: 0,
+							format: "float32x4"
+						},
+						{
+							shaderLocation: 1,
+							offset: 16,
+							format: "unorm16x4"
+						},
+						{
+							shaderLocation: 2,
+							offset: 24,
+							format: "unorm8x4"
+						},
+						{
+							shaderLocation: 3,
+							offset: 28,
+							format: "uint32"
+						}
+					]
+				}]
+			},
+			fragment: {
+				module: this._shaderModule,
+				entryPoint: "fragmentMain",
+				targets: [{
+					format,
+					blend: getWebGpuBlendState(blendMode),
+					writeMask: GPUColorWrite.ALL
+				}]
+			},
+			primitive: { topology: "triangle-list" }
+		};
+		if (stencil) descriptor.depthStencil = stencilContentDepthStencilState();
+		const pipeline = this._device.createRenderPipeline(descriptor);
+		this._pipelines.set(key, pipeline);
+		return pipeline;
+	}
+	/**
+	* Grow the CPU staging array to hold `instanceCount` instances, carrying the
+	* quads packed so far. Flush-local: the array only ever holds the pending
+	* batch, so it is sized independently of the pass-scoped GPU buffer.
+	*/
+	_ensureStagingCapacity(instanceCount) {
+		if (instanceCount <= this._instanceStagingCapacity) return;
+		let nextCapacity = Math.max(this._instanceStagingCapacity, initialBatchCapacity);
+		while (nextCapacity < instanceCount) nextCapacity *= 2;
+		const oldData = this._instanceData;
+		const carryBytes = Math.min(this._quadIndex * instanceStrideBytes, oldData.byteLength);
+		const instanceData = /* @__PURE__ */ new ArrayBuffer(nextCapacity * instanceStrideBytes);
+		if (carryBytes > 0) new Uint8Array(instanceData).set(new Uint8Array(oldData, 0, carryBytes));
+		this._instanceStagingCapacity = nextCapacity;
+		this._instanceData = instanceData;
+		this._instanceFloat32 = new Float32Array(instanceData);
+		this._instanceUint32 = new Uint32Array(instanceData);
+	}
+	/**
+	* Resolve the GPU instance buffer for `requiredBytes` - the total this pass
+	* would reach by appending, not this flush's own bytes. Reallocation frees the
+	* buffer earlier draws in the open pass read, so the caller must have ended
+	* that pass (and restarted the cursor) before a growing call. Capacity
+	* doubles, so the split a growth costs converges away within a frame or two.
+	*/
+	_ensureInstanceBufferCapacity(device, requiredBytes) {
+		const existing = this._instanceBuffer;
+		if (existing !== null && requiredBytes <= this._instanceBufferCapacity) return existing;
+		const nextCapacity = Math.max(this._instanceBufferCapacity * 2, requiredBytes, initialBatchCapacity * instanceStrideBytes);
+		const instanceBuffer = device.createBuffer({
+			label: "tile-chunk:instance-buffer",
+			size: nextCapacity,
+			usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST
+		});
+		existing?.destroy();
+		this._instanceBufferCapacity = nextCapacity;
+		this._instanceBuffer = instanceBuffer;
+		return instanceBuffer;
+	}
+};
 
+//#endregion
 export { WebGpuTileChunkRenderer };
-//# sourceMappingURL=WebGpuTileChunkRenderer.js.map
+//# sourceMappingURL=WebGpuTileChunkRenderer.js.map