@downdraft/engine 0.1.1 → 0.2.0

package/dist/core/src/render/bindless/material-manager.js

@@ -0,0 +1,182 @@
+// ============================================================================
+// BindlessMaterialManager — owns the material SSBO for bindless rendering
+//
+// Materials are flat structs in a read-only storage buffer. Each draw carries
+// a `materialIndex` (instance/vertex attribute) that indexes this buffer. The
+// struct holds scalar material params (baseColor, roughness, metallic, ...)
+// plus packed texture handles (arrayIndex << 16 | layerIndex) for each texture
+// slot the material uses.
+//
+// The SSBO grows in pages; the bind group is rebuilt only when it grows (rare).
+// Freed material slots are returned to a free list and reused.
+// ============================================================================
+import { createLogger } from "../../util/logger.js";
+import { BINDLESS_MATERIAL_FLOATS, BINDLESS_MATERIAL_SIZE, BindlessMaterialStruct } from "./bindless-struct.js";
+const log = createLogger();
+const STORAGE_USAGE = 0x80 | 0x08; // GPUBufferUsage.STORAGE | COPY_DST
+/**
+ * Byte size of one BindlessMaterial struct (80). Re-exported from
+ * bindless-struct.ts for back-compat — the layout is now the single source of
+ * truth in `BindlessMaterialStruct`.
+ */
+export const MATERIAL_STRUCT_SIZE = BINDLESS_MATERIAL_SIZE;
+const DEFAULT_INITIAL_CAPACITY = 256;
+const DEFAULT_GROWTH_FACTOR = 2;
+const DEFAULT_MAX_CAPACITY = 1 << 16; // 65536 materials
+export class BindlessMaterialManager {
+    device;
+    buffer;
+    capacity;
+    growthFactor;
+    maxCapacity;
+    /** Float32 view over the SSBO backing store (size = capacity * floatsPerMaterial). */
+    backing;
+    /** Uint32 view over the same ArrayBuffer as `backing` — kept for the flush
+     *  path and any direct u32 reads. Field writes go through StructView which
+     *  lazily creates its own Uint32Array view over the same buffer. */
+    backingU32;
+    /** Next free slot index, or -1 if none (then append). */
+    freeList = [];
+    nextSlot = 0;
+    /** Bumped whenever the SSBO is reallocated — invalidates bind groups. */
+    bufferVersion = 0;
+    constructor(device, options = {}) {
+        this.device = device;
+        this.capacity = options.initialCapacity ?? DEFAULT_INITIAL_CAPACITY;
+        this.growthFactor = options.growthFactor ?? DEFAULT_GROWTH_FACTOR;
+        this.maxCapacity = options.maxCapacity ?? DEFAULT_MAX_CAPACITY;
+        this.backing = new Float32Array(this.capacity * BINDLESS_MATERIAL_FLOATS);
+        this.backingU32 = new Uint32Array(this.backing.buffer);
+        this.buffer = device.createBuffer({
+            size: this.capacity * MATERIAL_STRUCT_SIZE,
+            usage: STORAGE_USAGE,
+            label: "bindless_material_ssbo",
+        });
+    }
+    getBuffer() {
+        return this.buffer;
+    }
+    getBufferVersion() {
+        return this.bufferVersion;
+    }
+    getCapacity() {
+        return this.capacity;
+    }
+    getCount() {
+        return this.nextSlot - this.freeList.length;
+    }
+    /**
+     * Register a material. Returns a stable materialIndex. If the SSBO is full
+     * and below maxCapacity, it is reallocated (bufferVersion bumps) and existing
+     * data is copied — indices stay stable.
+     */
+    registerMaterial(params) {
+        let index;
+        if (this.freeList.length > 0) {
+            index = this.freeList.pop();
+        }
+        else {
+            if (this.nextSlot >= this.capacity) {
+                this.grow();
+            }
+            index = this.nextSlot++;
+        }
+        this.writeMaterial(index, params);
+        return index;
+    }
+    /** Update an existing material's params in place (no reallocation). */
+    updateMaterial(index, params) {
+        if (index < 0 || index >= this.nextSlot) {
+            log.warn("bindless", `updateMaterial: index ${index} out of range (nextSlot=${this.nextSlot})`);
+            return;
+        }
+        this.writeMaterial(index, params);
+    }
+    /** Free a material slot; its index may be reused by a later registration. */
+    unregisterMaterial(index) {
+        if (index < 0 || index >= this.nextSlot)
+            return;
+        // Zero the slot so stale data isn't sampled.
+        this.backing.fill(0, index * BINDLESS_MATERIAL_FLOATS, (index + 1) * BINDLESS_MATERIAL_FLOATS);
+        this.flushRange(index, 1);
+        this.freeList.push(index);
+    }
+    /** Flush all pending writes to the GPU (call once per frame before draw). */
+    flush() {
+        if (this.nextSlot === 0)
+            return;
+        this.device.queue.writeBuffer(this.buffer, 0, this.backing.buffer, 0, this.nextSlot * BINDLESS_MATERIAL_FLOATS * 4);
+    }
+    destroy() {
+        this.buffer.destroy();
+    }
+    // ── internal ──────────────────────────────────────────────────────────
+    writeMaterial(index, p) {
+        const o = index * BINDLESS_MATERIAL_FLOATS;
+        // Zero-copy subarray view over this slot's region of the backing store.
+        // StructView writes field values at computed offsets; u32 handle fields
+        // write through a shared Uint32Array view so the shader reads correct u32
+        // bit patterns (not float reinterpretations).
+        const view = BindlessMaterialStruct.view(this.backing.subarray(o, o + BINDLESS_MATERIAL_FLOATS));
+        view.set("baseColor", p.baseColor);
+        view.set("roughness", p.roughness);
+        view.set("metallic", p.metallic);
+        view.set("emissiveIntensity", p.emissiveIntensity);
+        view.set("hasTexTransform", p.textureTransform ? 1.0 : 0.0);
+        view.setU32("albedoTex", p.albedoTexHandle >>> 0);
+        view.setU32("normalTex", p.normalTexHandle >>> 0);
+        view.setU32("metallicRoughnessTex", p.metallicRoughnessTexHandle >>> 0);
+        // Pack ao (low 16) + emissive (high 16) into one u32.
+        view.setU32("aoEmissiveTex", ((p.aoTexHandle & 0xffff) | ((p.emissiveTexHandle & 0xffff) << 16)) >>> 0);
+        // Texture transform (KHR_texture_transform)
+        if (p.textureTransform) {
+            view.set("texOffset", p.textureTransform.offset);
+            view.set("texScale", p.textureTransform.scale);
+            view.set("texRotation", p.textureTransform.rotation);
+        }
+        else {
+            view.set("texOffset", [0, 0]);
+            view.set("texScale", [1, 1]);
+            view.set("texRotation", 0);
+        }
+        view.set("_pad0", 0);
+        view.set("_pad1", 0);
+        view.set("_pad2", 0);
+        this.flushRange(index, 1);
+    }
+    flushRange(index, count) {
+        const byteOffset = index * MATERIAL_STRUCT_SIZE;
+        const byteLength = count * MATERIAL_STRUCT_SIZE;
+        this.device.queue.writeBuffer(this.buffer, byteOffset, this.backing.buffer, byteOffset, byteLength);
+    }
+    grow() {
+        if (this.capacity >= this.maxCapacity) {
+            throw new Error(`BindlessMaterialManager: maxCapacity ${this.maxCapacity} reached`);
+        }
+        const newCapacity = Math.min(Math.floor(this.capacity * this.growthFactor), this.maxCapacity);
+        const newBacking = new Float32Array(newCapacity * BINDLESS_MATERIAL_FLOATS);
+        newBacking.set(this.backing);
+        const newBuffer = this.device.createBuffer({
+            size: newCapacity * MATERIAL_STRUCT_SIZE,
+            usage: STORAGE_USAGE,
+            label: "bindless_material_ssbo",
+        });
+        // Copy old data into the new buffer.
+        this.device.queue.writeBuffer(newBuffer, 0, newBacking.buffer, 0, this.nextSlot * BINDLESS_MATERIAL_FLOATS * 4);
+        this.buffer.destroy();
+        this.buffer = newBuffer;
+        this.backing = newBacking;
+        this.backingU32 = new Uint32Array(newBacking.buffer);
+        this.capacity = newCapacity;
+        this.bufferVersion++;
+        log.debug("bindless", `material SSBO grew to capacity ${newCapacity}`);
+    }
+}
+/**
+ * Pack a texture handle's low 16 bits (layerIndex only — assumes a single
+ * array page, common case) into a u16 slot. Used when a material struct has
+ * more texture slots than 32-bit fields.
+ */
+export function packHandle16(handle) {
+    return handle & 0xffff;
+}

package/dist/core/src/render/bindless/texture-registry.js

@@ -0,0 +1,498 @@
+// ============================================================================
+// BindlessTextureRegistry — owns texture_2d_array "buckets" for bindless sampling
+//
+// WebGPU's native bindless mechanism is `texture_2d_array<T>`: one bind group
+// entry is a single GPUTexture with many 2D array layers, sampled with a
+// per-sample array index. All layers in a texture_2d_array must share format +
+// width + height + mip count + sample count, and the layer count is bounded by
+// `maxTextureArrayLayers` (default 256).
+//
+// Textures are bucketed by (format, width, height, mipCount, sampleCount). Each
+// bucket holds up to MAX_PAGES texture_2d_array textures ("pages"), each with
+// up to `layersPerPage` layers. When a page fills, a new page is appended and
+// the material bind group is rebuilt (rare — not per frame).
+//
+// A registered texture returns a stable TextureHandle packing (pageIndex << 16)
+// | layerIndex. Shaders index `texture_2d_array` bindings by pageIndex and
+// sample layerIndex.
+// ============================================================================
+import { createLogger } from "../../util/logger.js";
+const log = createLogger();
+// GPUTextureUsage flags — numeric literals for environments without WebGPU globals (Bun test)
+const TEXTURE_BINDING_USAGE = 0x04; // GPUTextureUsage.TEXTURE_BINDING
+const COPY_DST_USAGE = 0x02; // GPUTextureUsage.COPY_DST
+const COPY_SRC_USAGE = 0x01; // GPUTextureUsage.COPY_SRC
+const RENDER_ATTACHMENT_USAGE = 0x10; // GPUTextureUsage.RENDER_ATTACHMENT
+const DEFAULT_MAX_PAGES = 8;
+const DEFAULT_LAYERS_PER_PAGE = 256;
+const DEFAULT_MAX_ARRAY_BINDINGS = 8;
+function bucketKey(k) {
+    return `${k.format}|${k.width}x${k.height}|mip${k.mipCount}|ms${k.sampleCount}`;
+}
+export class BindlessTextureRegistry {
+    device;
+    buckets = new Map();
+    maxPagesPerBucket;
+    layersPerPage;
+    maxArrayBindingsPerFormat;
+    /** Next global binding index for a new page (monotonic, never reused). */
+    nextGlobalArrayIndex = 0;
+    /** Bumped whenever any bucket adds a page — used to invalidate bind groups. */
+    layoutVersion = 0;
+    /** Default white 1x1 rgba8unorm handle (always layer 0 of the default bucket). */
+    defaultWhiteHandle = 0;
+    /** Default black 1x1 rgba8unorm handle. */
+    defaultBlackHandle = 0;
+    /** Default flat-normal 1x1 rgba8unorm handle (128,128,255 = no perturbation). */
+    defaultNormalHandle = 0;
+    // ── Mipmap generation (in-place blit into bucket page mip levels) ──
+    mipPipelines = new Map();
+    mipBindGroupLayout = null;
+    mipSampler = null;
+    constructor(device, options = {}) {
+        this.device = device;
+        this.maxPagesPerBucket = options.maxPagesPerBucket ?? DEFAULT_MAX_PAGES;
+        const devLayers = (device.limits?.maxTextureArrayLayers) ?? DEFAULT_LAYERS_PER_PAGE;
+        this.layersPerPage = Math.min(options.layersPerPage ?? DEFAULT_LAYERS_PER_PAGE, devLayers);
+        this.maxArrayBindingsPerFormat = options.maxArrayBindingsPerFormat ?? DEFAULT_MAX_ARRAY_BINDINGS;
+        this.createDefaultTextures();
+    }
+    getLayoutVersion() {
+        return this.layoutVersion;
+    }
+    getMaxArrayBindingsPerFormat() {
+        return this.maxArrayBindingsPerFormat;
+    }
+    /**
+     * Register a texture by copying an external GPUTexture into a bucket layer.
+     * Returns a stable handle. If the same `sourceId` was registered before,
+     * returns the existing handle (idempotent).
+     */
+    registerFromTexture(sourceId, src, key) {
+        const b = this.getOrCreateBucket(key);
+        const existing = b.sources.get(sourceId);
+        if (existing)
+            return existing;
+        const slot = this.allocSlot(b);
+        this.copyTextureIntoLayer(src, b, slot.page, slot.layer, key);
+        const reg = {
+            handle: (slot.globalArrayIndex << 16) | slot.layer,
+            bucketKey: b.keyStr,
+            arrayIndex: slot.globalArrayIndex,
+            pageIndex: slot.page,
+            layerIndex: slot.layer,
+        };
+        b.sources.set(sourceId, reg);
+        return reg;
+    }
+    /**
+     * Register a texture by copying an ImageBitmap into a bucket layer.
+     * The bucket is created with the bitmap's dimensions and rgba8unorm format
+     * (or the provided key). Returns a stable handle.
+     */
+    registerFromImageBitmap(sourceId, bitmap, format = "rgba8unorm", mipCount = 1, generateMips = false) {
+        // If generateMips is requested and mipCount wasn't explicitly set,
+        // compute the full mip chain.
+        const effectiveMipCount = generateMips && mipCount === 1
+            ? Math.floor(Math.log2(Math.max(bitmap.width, bitmap.height))) + 1
+            : mipCount;
+        const key = {
+            format,
+            width: bitmap.width,
+            height: bitmap.height,
+            mipCount: effectiveMipCount,
+            sampleCount: 1,
+        };
+        const b = this.getOrCreateBucket(key);
+        const existing = b.sources.get(sourceId);
+        if (existing)
+            return existing;
+        const slot = this.allocSlot(b);
+        this.copyImageBitmapIntoLayer(bitmap, b, slot.page, slot.layer, key);
+        const reg = {
+            handle: (slot.globalArrayIndex << 16) | slot.layer,
+            bucketKey: b.keyStr,
+            arrayIndex: slot.globalArrayIndex,
+            pageIndex: slot.page,
+            layerIndex: slot.layer,
+        };
+        b.sources.set(sourceId, reg);
+        // Generate mip levels 1..N in-place.
+        if (generateMips && effectiveMipCount > 1) {
+            this.generateMipmapsForSlot(b, slot.page, slot.layer);
+        }
+        return reg;
+    }
+    /** Update an existing registration's pixel data (e.g. async load completion). */
+    updateFromImageBitmap(sourceId, bitmap) {
+        for (const b of this.buckets.values()) {
+            const reg = b.sources.get(sourceId);
+            if (!reg)
+                continue;
+            if (b.key.width !== bitmap.width || b.key.height !== bitmap.height) {
+                log.warn("bindless", `updateFromImageBitmap dimension mismatch for ${String(sourceId)}: bucket ${b.key.width}x${b.key.height} vs bitmap ${bitmap.width}x${bitmap.height}`);
+                return false;
+            }
+            this.copyImageBitmapIntoLayer(bitmap, b, reg.pageIndex, reg.layerIndex, b.key);
+            // Regenerate mips if the bucket has more than 1 mip level.
+            if (b.key.mipCount > 1)
+                this.generateMipmapsForSlot(b, reg.pageIndex, reg.layerIndex);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Generate mip levels 1..N for a registered texture by successively
+     * downsampling mip N-1 → mip N with a 2×2 box filter. The bucket page must
+     * have been created with mipLevelCount > 1 (i.e. the bucket key's mipCount).
+     * Only rgba8unorm is supported (the common case for albedo/normal textures).
+     */
+    generateMipmaps(sourceId) {
+        for (const b of this.buckets.values()) {
+            const reg = b.sources.get(sourceId);
+            if (!reg)
+                continue;
+            if (b.key.mipCount <= 1)
+                return false; // nothing to do
+            this.generateMipmapsForSlot(b, reg.pageIndex, reg.layerIndex);
+            return true;
+        }
+        return false;
+    }
+    generateMipmapsForSlot(b, page, layer) {
+        const format = b.key.format;
+        const pipeline = this.getMipPipeline(format);
+        if (!pipeline)
+            return;
+        const tex = b.pages[page];
+        const mipCount = b.key.mipCount;
+        const sampler = this.getMipSampler();
+        const layout = this.mipBindGroupLayout;
+        const encoder = this.device.createCommandEncoder();
+        for (let mip = 1; mip < mipCount; mip++) {
+            const srcView = tex.createView({
+                dimension: "2d-array",
+                baseMipLevel: mip - 1,
+                mipLevelCount: 1,
+                baseArrayLayer: layer,
+                arrayLayerCount: 1,
+            });
+            const dstView = tex.createView({
+                dimension: "2d-array",
+                baseMipLevel: mip,
+                mipLevelCount: 1,
+                baseArrayLayer: layer,
+                arrayLayerCount: 1,
+            });
+            const bg = this.device.createBindGroup({
+                layout,
+                entries: [
+                    { binding: 0, resource: srcView },
+                    { binding: 1, resource: sampler },
+                ],
+            });
+            const mw = Math.max(1, b.key.width >> mip);
+            const mh = Math.max(1, b.key.height >> mip);
+            const pass = encoder.beginRenderPass({
+                colorAttachments: [{
+                        view: dstView,
+                        clearValue: { r: 0, g: 0, b: 0, a: 1 },
+                        loadOp: "clear",
+                        storeOp: "store",
+                    }],
+            });
+            pass.setPipeline(pipeline);
+            pass.setBindGroup(0, bg);
+            pass.setViewport(0, 0, mw, mh, 0, 1);
+            pass.draw(3);
+            pass.end();
+        }
+        this.device.queue.submit([encoder.finish()]);
+    }
+    getMipSampler() {
+        if (this.mipSampler)
+            return this.mipSampler;
+        this.mipSampler = this.device.createSampler({
+            magFilter: "linear",
+            minFilter: "linear",
+            addressModeU: "clamp-to-edge",
+            addressModeV: "clamp-to-edge",
+        });
+        return this.mipSampler;
+    }
+    getMipPipeline(format) {
+        const existing = this.mipPipelines.get(format);
+        if (existing)
+            return existing;
+        // Only support color formats for mip generation.
+        if (format === "depth32float" || format.startsWith("depth"))
+            return null;
+        if (!this.mipBindGroupLayout) {
+            this.mipBindGroupLayout = this.device.createBindGroupLayout({
+                entries: [
+                    { binding: 0, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float", viewDimension: "2d-array" } },
+                    { binding: 1, visibility: GPUShaderStage.FRAGMENT, sampler: { type: "filtering" } },
+                ],
+            });
+        }
+        const shader = this.device.createShaderModule({
+            label: "bindless-mip-blit",
+            code: /* wgsl */ `
+@vertex
+fn vs(@builtin(vertex_index) vi: u32) -> @builtin(position) vec4f {
+  var pos = array<vec2f, 3>(vec2f(-1.0,-1.0), vec2f(3.0,-1.0), vec2f(-1.0,3.0));
+  return vec4f(pos[vi], 0.0, 1.0);
+}
+@group(0) @binding(0) var srcTex: texture_2d_array<f32>;
+@group(0) @binding(1) var srcSampler: sampler;
+@fragment
+fn fs(@builtin(position) pos: vec4f) -> @location(0) vec4f {
+  let dim = vec2f(textureDimensions(srcTex, 0).xy);
+  let uv = (pos.xy + 0.5) / dim;
+  // 2x2 box filter — sample 4 taps to downsample mip N-1 → mip N.
+  let texel = 1.0 / dim;
+  let c00 = textureSample(srcTex, srcSampler, uv + vec2f(-0.5, -0.5) * texel, 0u);
+  let c10 = textureSample(srcTex, srcSampler, uv + vec2f( 0.5, -0.5) * texel, 0u);
+  let c01 = textureSample(srcTex, srcSampler, uv + vec2f(-0.5,  0.5) * texel, 0u);
+  let c11 = textureSample(srcTex, srcSampler, uv + vec2f( 0.5,  0.5) * texel, 0u);
+  return (c00 + c10 + c01 + c11) * 0.25;
+}
+`,
+        });
+        const pipeline = this.device.createRenderPipeline({
+            label: `bindless-mip-${format}`,
+            layout: this.device.createPipelineLayout({ bindGroupLayouts: [this.mipBindGroupLayout] }),
+            vertex: { module: shader, entryPoint: "vs" },
+            fragment: { module: shader, entryPoint: "fs", targets: [{ format }] },
+            primitive: { topology: "triangle-list" },
+        });
+        this.mipPipelines.set(format, pipeline);
+        return pipeline;
+    }
+    /** Update an existing registration from an external GPUTexture. */
+    updateFromTexture(sourceId, src) {
+        for (const b of this.buckets.values()) {
+            const reg = b.sources.get(sourceId);
+            if (!reg)
+                continue;
+            this.copyTextureIntoLayer(src, b, reg.pageIndex, reg.layerIndex, b.key);
+            return true;
+        }
+        return false;
+    }
+    /** Look up an existing registration by sourceId (returns undefined if absent). */
+    getRegistration(sourceId) {
+        for (const b of this.buckets.values()) {
+            const reg = b.sources.get(sourceId);
+            if (reg)
+                return reg;
+        }
+        return undefined;
+    }
+    /** Convenience: return the packed handle for a sourceId, or undefined. */
+    getHandle(sourceId) {
+        return this.getRegistration(sourceId)?.handle;
+    }
+    /** Unregister a texture by sourceId; returns its slot to the bucket free list. */
+    unregister(sourceId) {
+        for (const b of this.buckets.values()) {
+            const reg = b.sources.get(sourceId);
+            if (!reg)
+                continue;
+            b.sources.delete(sourceId);
+            b.freeList.push({ page: reg.pageIndex, layer: reg.layerIndex });
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Get the array texture views for a bucket key, for bind-group construction.
+     * Returns one GPUTextureView (dimension "2d-array") per page, padded with
+     * null entries up to maxArrayBindingsPerFormat.
+     */
+    getArrayViews(key) {
+        const b = this.buckets.get(bucketKey(key));
+        const out = new Array(this.maxArrayBindingsPerFormat).fill(null);
+        if (!b)
+            return out;
+        for (let i = 0; i < b.pages.length && i < this.maxArrayBindingsPerFormat; i++) {
+            out[i] = b.pages[i].createView({ dimension: "2d-array" });
+        }
+        return out;
+    }
+    /** All bucket keys currently allocated (for bind-group construction). */
+    getBucketKeys() {
+        return Array.from(this.buckets.values()).map((b) => b.key);
+    }
+    /**
+     * Returns a flat list of all page views across ALL buckets, in bucket-then-page
+     * order. Each view is dimension "2d-array". Padded with nulls up to
+     * maxArrayBindingsPerFormat total entries. This is what the bind group binds:
+     * binding 1 = flat[0], binding 2 = flat[1], etc.
+     *
+     * The handle's `arrayIndex` field is the global flat index (see allocSlot).
+     */
+    getAllArrayViewsFlat() {
+        const out = new Array(this.maxArrayBindingsPerFormat).fill(null);
+        for (const b of this.buckets.values()) {
+            for (let i = 0; i < b.pages.length; i++) {
+                const gidx = b.globalArrayIndices[i];
+                if (gidx < this.maxArrayBindingsPerFormat) {
+                    out[gidx] = b.pages[i].createView({ dimension: "2d-array" });
+                }
+            }
+        }
+        return out;
+    }
+    /** Total layers in use across all buckets (telemetry / debugging). */
+    getTotalLayersInUse() {
+        let total = 0;
+        for (const b of this.buckets.values()) {
+            b.layerCursor.forEach((c) => { total += c; ; });
+            total -= b.freeList.length;
+        }
+        return total;
+    }
+    destroy() {
+        for (const b of this.buckets.values()) {
+            b.pages.forEach((t) => { t.destroy(); ; });
+        }
+        this.buckets.clear();
+    }
+    // ── internal ──────────────────────────────────────────────────────────
+    createDefaultTextures() {
+        // Default white 1x1 rgba8unorm — layer 0 of the default bucket.
+        const key = {
+            format: "rgba8unorm",
+            width: 1,
+            height: 1,
+            mipCount: 1,
+            sampleCount: 1,
+        };
+        const b = this.getOrCreateBucket(key);
+        const whiteSlot = this.allocSlot(b);
+        const whiteData = new Uint8Array([255, 255, 255, 255]);
+        this.device.queue.writeTexture({ texture: b.pages[whiteSlot.page], origin: [0, 0, whiteSlot.layer], mipLevel: 0 }, whiteData, { bytesPerRow: 4 }, { width: 1, height: 1 });
+        this.defaultWhiteHandle = (whiteSlot.globalArrayIndex << 16) | whiteSlot.layer;
+        b.sources.set("__default_white__", {
+            handle: this.defaultWhiteHandle,
+            bucketKey: b.keyStr,
+            arrayIndex: whiteSlot.globalArrayIndex,
+            pageIndex: whiteSlot.page,
+            layerIndex: whiteSlot.layer,
+        });
+        // Default black 1x1 rgba8unorm.
+        const blackSlot = this.allocSlot(b);
+        const blackData = new Uint8Array([0, 0, 0, 255]);
+        this.device.queue.writeTexture({ texture: b.pages[blackSlot.page], origin: [0, 0, blackSlot.layer], mipLevel: 0 }, blackData, { bytesPerRow: 4 }, { width: 1, height: 1 });
+        this.defaultBlackHandle = (blackSlot.globalArrayIndex << 16) | blackSlot.layer;
+        b.sources.set("__default_black__", {
+            handle: this.defaultBlackHandle,
+            bucketKey: b.keyStr,
+            arrayIndex: blackSlot.globalArrayIndex,
+            pageIndex: blackSlot.page,
+            layerIndex: blackSlot.layer,
+        });
+        // Default flat-normal 1x1 rgba8unorm — (128,128,255) unpacks to (0,0,1) = no perturbation.
+        const normalSlot = this.allocSlot(b);
+        const normalData = new Uint8Array([128, 128, 255, 255]);
+        this.device.queue.writeTexture({ texture: b.pages[normalSlot.page], origin: [0, 0, normalSlot.layer], mipLevel: 0 }, normalData, { bytesPerRow: 4 }, { width: 1, height: 1 });
+        this.defaultNormalHandle = (normalSlot.globalArrayIndex << 16) | normalSlot.layer;
+        b.sources.set("__default_normal__", {
+            handle: this.defaultNormalHandle,
+            bucketKey: b.keyStr,
+            arrayIndex: normalSlot.globalArrayIndex,
+            pageIndex: normalSlot.page,
+            layerIndex: normalSlot.layer,
+        });
+    }
+    getOrCreateBucket(key) {
+        const keyStr = bucketKey(key);
+        let b = this.buckets.get(keyStr);
+        if (!b) {
+            b = {
+                key,
+                keyStr,
+                pages: [],
+                globalArrayIndices: [],
+                layerCursor: [],
+                freeList: [],
+                sources: new Map(),
+            };
+            this.buckets.set(keyStr, b);
+            this.appendPage(b);
+        }
+        return b;
+    }
+    appendPage(b) {
+        if (b.pages.length >= this.maxPagesPerBucket) {
+            log.error("bindless", `bucket ${b.keyStr} exhausted maxPages=${this.maxPagesPerBucket}; texture registration failed`);
+            throw new Error(`BindlessTextureRegistry: bucket ${b.keyStr} full (maxPages=${this.maxPagesPerBucket})`);
+        }
+        const tex = this.device.createTexture({
+            size: [b.key.width, b.key.height, this.layersPerPage],
+            format: b.key.format,
+            usage: TEXTURE_BINDING_USAGE | COPY_DST_USAGE | COPY_SRC_USAGE | RENDER_ATTACHMENT_USAGE,
+            mipLevelCount: b.key.mipCount,
+            sampleCount: b.key.sampleCount,
+            label: `bindless_${b.keyStr}_page${b.pages.length}`,
+        });
+        b.pages.push(tex);
+        b.layerCursor.push(0);
+        b.globalArrayIndices.push(this.nextGlobalArrayIndex++);
+        this.layoutVersion++;
+    }
+    allocSlot(b) {
+        let slot;
+        if (b.freeList.length > 0) {
+            const free = b.freeList.pop();
+            slot = { ...free, globalArrayIndex: b.globalArrayIndices[free.page] };
+        }
+        else {
+            // Find a page with a free layer.
+            let allocated = false;
+            for (let p = 0; p < b.layerCursor.length; p++) {
+                if (b.layerCursor[p] < this.layersPerPage) {
+                    const layer = b.layerCursor[p];
+                    b.layerCursor[p] = layer + 1;
+                    slot = { page: p, layer, globalArrayIndex: b.globalArrayIndices[p] };
+                    allocated = true;
+                    break;
+                }
+            }
+            if (!allocated) {
+                // All pages full — append a new one and allocate from it.
+                this.appendPage(b);
+                const page = b.layerCursor.length - 1;
+                b.layerCursor[page] = 1;
+                slot = { page, layer: 0, globalArrayIndex: b.globalArrayIndices[page] };
+            }
+        }
+        // Validate that layer and globalArrayIndex fit in the 16-bit handle fields.
+        // The handle packs (globalArrayIndex << 16) | layer; overflow corrupts sampling.
+        const { layer, globalArrayIndex } = slot;
+        if (layer < 0 || layer > 0xFFFF) {
+            throw new Error(`BindlessTextureRegistry: layer index ${layer} exceeds 16-bit handle field (max 65535) for bucket ${b.keyStr}`);
+        }
+        if (globalArrayIndex < 0 || globalArrayIndex > 0xFFFF) {
+            throw new Error(`BindlessTextureRegistry: global array index ${globalArrayIndex} exceeds 16-bit handle field (max 65535) for bucket ${b.keyStr}`);
+        }
+        return slot;
+    }
+    copyTextureIntoLayer(src, b, page, layer, key) {
+        const dst = b.pages[page];
+        const encoder = this.device.createCommandEncoder();
+        for (let mip = 0; mip < key.mipCount; mip++) {
+            encoder.copyTextureToTexture({ texture: src, mipLevel: mip, origin: [0, 0, 0] }, { texture: dst, mipLevel: mip, origin: [0, 0, layer] }, { width: key.width >> mip, height: key.height >> mip, depthOrArrayLayers: 1 });
+        }
+        this.device.queue.submit([encoder.finish()]);
+    }
+    copyImageBitmapIntoLayer(bitmap, b, page, layer, key) {
+        const dst = b.pages[page];
+        this.device.queue.copyExternalImageToTexture({ source: bitmap }, { texture: dst, origin: [0, 0, layer], mipLevel: 0 }, { width: key.width, height: key.height });
+        // NOTE: only mip 0 is uploaded from the bitmap; mip generation is the
+        // caller's responsibility (most material textures are mip-less or
+        // pre-mipped and copied via registerFromTexture).
+    }
+}
+export { bucketKey as computeBucketKey };