@meimu/mutracer 0.0.0-stage → 0.1.0

package/lib/renderer/WGPURayTracePass.js

@@ -0,0 +1,2323 @@
+import { constants } from './webgl.js';
+import { MATERIAL_FLOAT_COUNT } from './materialLayout.js';
+import { normalizeBounces } from './pathLimits.js';
+import { MATERIAL_TEXTURE_DEFINES, materialTextureFeatures } from './materialTextureSlots.js';
+import { updateMeshInstanceColors } from './prepareMeshBVH.js';
+import { updateTLASInstanceColors } from './bvhAccel.js';
+import { getMaterialHashKey } from '../scene/openPbrSchema.js';
+import { sameInstanceMembership } from './meshInstances.js';
+import InstancedMesh from '../scene/InstancedMesh.js';
+import { dirtyMeshInstanceIndices } from './prepareMeshBVH.js';
+import { cameraApertureRadius } from './cameraLens.js';
+import { getRectLightUOrV, getRectLightArea, getSphereLightArea, getSpotLightArea, getSpotLightRadiance, getLightDirection, getRigidLightFrame, validateSceneLights } from './lightsUtil.js';
+import { getGeometryBvh, setGeometryBvh } from './geometryBvh.js';
+import { SHADOW_CATCHER_ACCUMULATION_BYTES } from './wgsl/chunks/shadowCatcherAccumulation.wgsl.js';
+import { samplingPatternCode, zSobolLog2SPP } from './sampling.js';
+import { DEPTH_SAMPLE_COUNT, packDepthSampleArea, unpackDepthSamples } from './depthQuery.js';
+import { MeshMembershipCache } from './meshMembership.js';
+import { mergeRefitRanges } from './bvhAccel.js';
+import { updatePreparedGeometries, canUpdateGeometries, geometryTopologyChanged, packVertexAttributes } from './geometryUpdates.js';
+import { SceneEnvironmentCache, RectLightTextureTracker } from './sceneLightChanges.js';
+import { MaterialChangeTracker, materialIsEmissive } from './materialChanges.js';
+import { WGPUShaderCache, retainedShaderCapacity } from './WGPUShaderCache.js';
+import { WGPU_SCENE_FEATURE_BITS, wgpuSceneFeatureFlags } from './WGPUSceneFeatures.js';
+import { mat4 } from '../math.js';
+import MaterialTable, { DEFAULT_MAX_TEXTURE_ARRAY_BYTES, materialUsesMedium } from './MaterialTable.js';
+import { numberArraysEqual } from './util.js';
+import { generateBackgroundMapFromSceneBackground } from './envMapCreation.js';
+import rayTraceCompute, { WORKGROUP_SIZE } from './wgsl/rayTrace.compute.js';
+import { CONSTANT_DIRECTIONAL_LIGHT, CONSTANT_RECT_LIGHT, CONSTANT_SPHERE_LIGHT, CONSTANT_SPOT_LIGHT } from './lightsUtil.js';
+import { envMapDistribution, environmentMapSourcesMatch } from './envMapDistribution.js';
+import { updateMeshInstances, updateMeshInstanceTransforms } from './prepareMeshBVH.js';
+import { buildTLAS, concatBLASBuffers, getTraversalStackSizes, refitBLAS, refitTLAS } from './bvhAccel.js';
+import { isTextureDataSource } from '../scene/Texture.js';
+import { resolveMaterialAlphaMode } from '../scene/OpenPBRMaterial.js';
+import { DEFAULT_BEVEL_SAMPLES, DEFAULT_DIRECT_LIGHT_CANDIDATES, normalizeBevelSamples, normalizeDirectLightCandidates } from './RenderingPipeline.js';
+import { buildLightAliasTable, EmissiveTriangleCache, LightChoiceBuffer, estimateAnalyticLightPower, estimateEnvironmentPower, LIGHT_CHOICE_ANALYTIC, LIGHT_CHOICE_EMISSIVE_TRIANGLE, LIGHT_CHOICE_ENVIRONMENT, LIGHT_DOMAIN_ENVIRONMENT, LIGHT_DOMAIN_INFINITE, LIGHT_DOMAIN_LOCAL_AND_EMISSIVE, packEmissiveTriangles, packIESProfiles } from './lightSampling.js';
+import { getOpenPbrEnergyLutData, OPENPBR_ENERGY_LUT_HEIGHT, OPENPBR_ENERGY_LUT_WIDTH } from './openPbrEnergyLut.js';
+import { offlineAdaptiveCompute } from './wgsl/offlineAdaptive.compute.js';
+import { normalizeOfflineAdaptiveSamplingOptions } from './OfflineAdaptiveSampling.js';
+const F32 = Float32Array;
+const FIXED_LIGHT_COUNT = 64;
+const PIXELS_PER_LIGHT = 6;
+/**
+ * WebGPU errors are Web IDL objects and are not required to inherit from the
+ * JavaScript Error class. In particular, GPUValidationError exposes a useful
+ * `message` while String(error) may only return "[object GPUValidationError]".
+ */
+export function getWebGPUErrorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === 'string')
+        return error;
+    if (error && typeof error === 'object' && 'message' in error) {
+        const message = error.message;
+        if (typeof message === 'string' && message.length > 0)
+            return message;
+    }
+    return String(error);
+}
+function joinWebGPUErrors(...errors) {
+    return [
+        ...new Set(errors
+            .filter((error) => error != null)
+            .map(getWebGPUErrorMessage)
+            .filter(Boolean))
+    ].join('\n');
+}
+function shaderCompilationNow() {
+    return typeof performance === 'undefined' ? Date.now() : performance.now();
+}
+function shaderSourceLineCount(source) {
+    let lines = 1;
+    for (let offset = source.indexOf('\n'); offset >= 0; offset = source.indexOf('\n', offset + 1)) {
+        lines++;
+    }
+    return lines;
+}
+/** Fast diagnostic fingerprint; cache implementations use their own hashes. */
+export function shaderSourceFingerprint(source) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < source.length; index++) {
+        hash = Math.imul(hash ^ source.charCodeAt(index), 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
+export function isWebGPUPipelineSpecializationFailure(...errors) {
+    return errors.some((error) => /(?:compute )?library failed creation/i.test(getWebGPUErrorMessage(error)));
+}
+/** CPU-side views over the `RayTraceUniform` WGSL struct. */
+export function makeRayTraceUniform() {
+    // Created from https://webgpufundamentals.org/webgpu/lessons/resources/wgsl-offset-computer.html
+    const RayTraceUniformValues = new ArrayBuffer(176);
+    const RayTraceUniformViews = {
+        outputSize: new Float32Array(RayTraceUniformValues, 0, 2),
+        sampleCount: new Float32Array(RayTraceUniformValues, 8, 1),
+        scaleOffset: new Float32Array(RayTraceUniformValues, 16, 4),
+        lightsCount: new Int32Array(RayTraceUniformValues, 32, 1),
+        transmissiveOutputAlphaMin: new Float32Array(RayTraceUniformValues, 36, 1),
+        jitter: new Float32Array(RayTraceUniformValues, 40, 2),
+        backgroundColor: new Float32Array(RayTraceUniformValues, 48, 4),
+        groundedBackgroundParams: new Float32Array(RayTraceUniformValues, 64, 4),
+        groundedBackgroundCenter: new Float32Array(RayTraceUniformValues, 80, 2),
+        blasOffset: new Int32Array(RayTraceUniformValues, 88, 1),
+        isEmpty: new Int32Array(RayTraceUniformValues, 92, 1),
+        bevel: new Int32Array(RayTraceUniformValues, 96, 1),
+        dispersionWavelengths: new Int32Array(RayTraceUniformValues, 100, 1),
+        envLightPmf: new Float32Array(RayTraceUniformValues, 104, 1),
+        lightChoiceCount: new Int32Array(RayTraceUniformValues, 108, 1),
+        lightWeightTotal: new Float32Array(RayTraceUniformValues, 112, 1),
+        lightSamplingTextureWidth: new Int32Array(RayTraceUniformValues, 116, 1),
+        lightChoiceTexelOffset: new Int32Array(RayTraceUniformValues, 120, 1),
+        bounces: new Int32Array(RayTraceUniformValues, 124, 1),
+        varianceMoments: new Int32Array(RayTraceUniformValues, 128, 1),
+        adaptiveSampling: new Int32Array(RayTraceUniformValues, 132, 1),
+        clamping: new Float32Array(RayTraceUniformValues, 136, 1),
+        directLightCandidates: new Int32Array(RayTraceUniformValues, 140, 1),
+        backgroundFlags: new Int32Array(RayTraceUniformValues, 144, 1),
+        loopUnrollGuard: new Uint32Array(RayTraceUniformValues, 148, 1),
+        sceneFeatureFlags: new Uint32Array(RayTraceUniformValues, 152, 1),
+        sequenceSeed: new Uint32Array(RayTraceUniformValues, 156, 1),
+        zSobolLogSPP: new Uint32Array(RayTraceUniformValues, 160, 1),
+        sampleSequenceOffset: new Uint32Array(RayTraceUniformValues, 164, 1)
+    };
+    // Fixed runtime trip bounds discourage thin-film loop unrolling. Keep 4 for
+    // 2 polarizations/substrates and 3 channels, independent of BSDF budgets.
+    RayTraceUniformViews.loopUnrollGuard[0] = 4;
+    RayTraceUniformViews.bevel[0] = 1;
+    RayTraceUniformViews.dispersionWavelengths[0] = 3;
+    return {
+        buffer: RayTraceUniformValues,
+        views: RayTraceUniformViews
+    };
+}
+export function packAnalyticsLightsToBuffer(lights, texturesIndices, selectionPmfs, iesProfileTexelOffsets = []) {
+    validateSceneLights(lights);
+    const numLights = lights.length;
+    if (numLights > FIXED_LIGHT_COUNT) {
+        console.warn(`Too many lights, only the first ${FIXED_LIGHT_COUNT} lights will be used.`);
+    }
+    const data = new Float32Array(numLights * PIXELS_PER_LIGHT * 4);
+    function packVec3(idx, v) {
+        for (let i = 0; i < 3; i++) {
+            data[i + idx * 4] = v[i];
+        }
+    }
+    const lightTypeConstants = {
+        DirectionalLight: CONSTANT_DIRECTIONAL_LIGHT,
+        SphereLight: CONSTANT_SPHERE_LIGHT,
+        RectLight: CONSTANT_RECT_LIGHT,
+        SpotLight: CONSTANT_SPOT_LIGHT
+    };
+    for (let i = 0; i < numLights; i++) {
+        const light = lights[i];
+        const color = light.color;
+        const intensity = light.intensity;
+        const off = i * PIXELS_PER_LIGHT;
+        packVec3(off, light.position);
+        data[off * 4 + 3] = lightTypeConstants[light.type];
+        // emission
+        const emissionScale = light.type === 'SpotLight' ? getSpotLightRadiance(light) : intensity;
+        packVec3(off + 1, [
+            color[0] * emissionScale,
+            color[1] * emissionScale,
+            color[2] * emissionScale
+        ]);
+        if (light.type === 'RectLight') {
+            data[(off + 1) * 4 + 3] = getRectLightArea(light);
+            packVec3(off + 2, getRectLightUOrV(light, 0));
+            data[(off + 2) * 4 + 3] = light.spread;
+            packVec3(off + 3, getRectLightUOrV(light, 1));
+        }
+        else if (light.type === 'SphereLight') {
+            data[(off + 1) * 4 + 3] = getSphereLightArea(light);
+            data[(off + 2) * 4 + 3] = light.radius;
+        }
+        else if (light.type === 'SpotLight') {
+            data[(off + 1) * 4 + 3] = getSpotLightArea(light);
+            packVec3(off + 2, getLightDirection(light));
+            data[(off + 2) * 4 + 3] = light.radius;
+            packVec3(off + 3, [
+                Math.cos((light.outerAngle * Math.PI) / 180),
+                Math.min(1, Math.max(0, 1 - light.innerAngle / light.outerAngle)),
+                0
+            ]);
+        }
+        else if (light.type === 'DirectionalLight') {
+            packVec3(off + 2, getLightDirection(light));
+        }
+        data[(off + 3) * 4 + 3] = light.type === 'SpotLight'
+            ? iesProfileTexelOffsets[i] ?? -1
+            : texturesIndices[i];
+        data[(off + 4) * 4] = selectionPmfs[i] ?? 0;
+        packVec3(off + 5, getRigidLightFrame(light).x);
+    }
+    return data;
+}
+class WGPURayTracePass {
+    _device;
+    _rayTracePipeline;
+    _targetAspect = 1;
+    _width = 0;
+    _height = 0;
+    _meshes = [];
+    _sceneEnvironment = new SceneEnvironmentCache();
+    _rectLightTextures = new RectLightTextureTracker();
+    _analyticLights = [];
+    _iesProfileTexelOffsets = new Int32Array(0);
+    _materialChanges = new MaterialChangeTracker();
+    _pendingMaterialUpdate;
+    _materialData;
+    _maxTextureArrayBytes = DEFAULT_MAX_TEXTURE_ARRAY_BYTES;
+    _pendingGeometryUpdates = new Set();
+    _needsUpdateMeshData = true;
+    _needsUpdateMeshMembership = false;
+    _needsRefitTLAS = false;
+    _preparedMeshData;
+    _membershipCache = new MeshMembershipCache();
+    _pendingMembershipData;
+    _residentPreparedMeshData;
+    _tlas;
+    _meshSnapshot = [];
+    _snapshotByMesh = new WeakMap();
+    _residentSnapshotByMesh = new WeakMap();
+    _dirtyTransformMeshes = new Set();
+    _dirtyColorMeshes = new Set();
+    _geometriesNeedRefit = new Set();
+    _needsUpdateAnalyticLightsBuffer = true;
+    _activeTarget = {};
+    _targetOutputs = new Map();
+    releaseTarget(target) {
+        const output = this._targetOutputs.get(target);
+        if (!output)
+            return;
+        this._targetOutputs.delete(target);
+        for (const buffer of output.buffers)
+            buffer.destroy();
+        if (this._activeTarget === target) {
+            this._rayTraceBindGroups = undefined;
+            this._needsUpdateBindGroups = true;
+        }
+    }
+    getTargetMemoryBytes(target) {
+        return this._targetOutputs.get(target)?.buffers.reduce((sum, buffer) => sum + buffer.size, 0) ?? 0;
+    }
+    useTarget(target) {
+        this._activeTarget = target;
+        const output = this._targetOutputs.get(target);
+        [this._outColorBuffer, this._outNormalBuffer, this._outAlbedoBuffer, this._outShadowCatcherBuffer] = output?.buffers ?? [];
+        if (output?.bindGroup && output.pipeline === this._rayTracePipeline && this._rayTraceBindGroups) {
+            this._rayTraceBindGroups[3] = output.bindGroup;
+        }
+        else {
+            this._needsUpdateBindGroups = true;
+        }
+    }
+    _outColorBuffer;
+    _outNormalBuffer;
+    _outAlbedoBuffer;
+    _outShadowCatcherBuffer;
+    _uniforms;
+    _rtUniform = makeRayTraceUniform();
+    _mapInfoUniform;
+    _attributeData;
+    _attributeStride = 0;
+    _attributeOffsets = [];
+    _attrBuffers;
+    _materialsBuffer;
+    _lightSamplingTexture;
+    _lightSamplingTextureSize = [0, 0];
+    _lightDomainDiagnostics = {
+        environment: { count: 0, weight: 0, pmf: 0 },
+        infinite: { count: 0, weight: 0, pmf: 0 },
+        localAndEmissive: { count: 0, weight: 0, pmf: 0 }
+    };
+    _openPbrEnergyLut;
+    _bvhBuffer;
+    _instancesBuffer;
+    _emissiveCache = new EmissiveTriangleCache();
+    _lightChoices = new LightChoiceBuffer();
+    _lightSamplingData;
+    _lightSamplingScratch;
+    _lightSamplingTriangleCount = -1;
+    _emissiveTriangles = [];
+    _analyticLightSelectionPmfs = [];
+    _needsUpdateLightSamplingData = true;
+    _adaptiveSamplingTexture;
+    _adaptiveSamplingTextureSize = [1, 1];
+    _offlineAdaptivePipeline;
+    _offlineAdaptiveHistory;
+    _mapsSampler;
+    _maps;
+    _envImageSource;
+    _envTex;
+    _envDistributionTex;
+    _backgroundImageSource;
+    _backgroundTex;
+    _rayTracePipelineLayout;
+    _rayTraceBindGroups;
+    _blasLayoutMask = 1;
+    _compiledBlasLayoutMask = 0;
+    _compiledAnisotropyDirections = false;
+    _compiledCoatNormals = false;
+    _compiledHasAlpha = true;
+    _compiledSceneHasAlpha = true;
+    _alphaBlendStrategy = 'stochastic';
+    _constants = {
+        USE_BACKGROUND: false,
+        USE_BACKGROUND_MAP: false,
+        USE_GROUNDED_BACKGROUND: false,
+        SAMPLING_PATTERN: 0,
+        BEVEL_SAMPLES: DEFAULT_BEVEL_SAMPLES
+    };
+    _prevPipelineConstants = {};
+    _prevDefinesCode = '';
+    _hasTransmission = false;
+    _hasShadowCatcher = false;
+    _hasDisplacement = false;
+    // User set params
+    _bounces = -1;
+    _bevelSamples = DEFAULT_BEVEL_SAMPLES;
+    _directLightCandidates = DEFAULT_DIRECT_LIGHT_CANDIDATES;
+    _clamping;
+    _transmissiveAlphaMin = 1;
+    _viewProjInv = mat4.create();
+    _cameraWorld = mat4.create();
+    _apertureRadius = 0;
+    _focusDistance = 10;
+    _needsUpdateBindGroups = true;
+    _computeShaderModule;
+    _depthCompute;
+    _depthTracePipeline;
+    _depthPipeline;
+    _shaderCache;
+    _debugBVHBuffer;
+    _isCompilingShader = false;
+    _shaderCompilationDiagnostics;
+    _pipelineError;
+    // Fold scene invariants before backend inlining; runtime edits use uniforms.
+    _bakePipelineConstants = true;
+    _failedPipelineSignature;
+    constructor(device) {
+        this._device = device;
+        this._shaderCache = new WGPUShaderCache(device);
+        this._uniforms = {
+            cameraUniform: this._uniformBuffer(36 * 4),
+            rtUniform: this._uniformBuffer(this._rtUniform.buffer.byteLength),
+            analyticLights: this._uniformBuffer(FIXED_LIGHT_COUNT * PIXELS_PER_LIGHT * 4 * 4)
+        };
+        this._mapInfoUniform = this._uniformBuffer(4 * 4);
+        this._openPbrEnergyLut = device.createTexture({
+            format: 'r32float',
+            label: 'OpenPBR opaque dielectric energy compensation',
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+            size: {
+                width: OPENPBR_ENERGY_LUT_WIDTH,
+                height: OPENPBR_ENERGY_LUT_HEIGHT
+            }
+        });
+        device.queue.writeTexture({ texture: this._openPbrEnergyLut }, getOpenPbrEnergyLutData(), { bytesPerRow: OPENPBR_ENERGY_LUT_WIDTH * Float32Array.BYTES_PER_ELEMENT }, {
+            width: OPENPBR_ENERGY_LUT_WIDTH,
+            height: OPENPBR_ENERGY_LUT_HEIGHT
+        });
+        this._mapsSampler = device.createSampler({
+            minFilter: 'linear',
+            magFilter: 'linear',
+            addressModeU: 'clamp-to-edge',
+            addressModeV: 'clamp-to-edge'
+        });
+        this._setBackgroundMap(undefined);
+        this._adaptiveSamplingTexture = device.createTexture({
+            format: 'r32float',
+            label: 'Adaptive sample targets placeholder',
+            usage: GPUTextureUsage.TEXTURE_BINDING |
+                GPUTextureUsage.COPY_DST |
+                GPUTextureUsage.STORAGE_BINDING,
+            size: [1, 1]
+        });
+        device.queue.writeTexture({ texture: this._adaptiveSamplingTexture }, new Float32Array([Number.MAX_SAFE_INTEGER]), { bytesPerRow: 4 }, [1, 1]);
+    }
+    getOutputBuffer() {
+        return {
+            color: this._outColorBuffer,
+            normal: this._outNormalBuffer,
+            albedo: this._outAlbedoBuffer,
+            shadowCatcher: this._outShadowCatcherBuffer
+        };
+    }
+    _ensureAdaptiveSamplingTexture(width, height) {
+        if (this._adaptiveSamplingTextureSize[0] === width &&
+            this._adaptiveSamplingTextureSize[1] === height) {
+            return;
+        }
+        this._adaptiveSamplingTexture.destroy();
+        this._adaptiveSamplingTexture = this._device.createTexture({
+            format: 'r32float',
+            label: 'Adaptive sample targets',
+            usage: GPUTextureUsage.TEXTURE_BINDING |
+                GPUTextureUsage.COPY_DST |
+                GPUTextureUsage.STORAGE_BINDING,
+            size: [width, height]
+        });
+        this._adaptiveSamplingTextureSize = [width, height];
+        this._needsUpdateBindGroups = true;
+    }
+    /**
+     * Reduces pilot moments and expands final sample targets without transferring
+     * full-resolution buffers through JavaScript. Only compact per-tile history
+     * is read back for diagnostics and animation-frame reuse.
+     */
+    async prepareOfflineAdaptiveSampling(options) {
+        const width = this._width;
+        const height = this._height;
+        if (!width || !height || !this._outColorBuffer || !this._outNormalBuffer) {
+            return undefined;
+        }
+        const normalized = normalizeOfflineAdaptiveSamplingOptions(options, width, height);
+        const { maxSamples, minSamples, tileSize, columns, rows, absoluteError, relativeError, confidence, previous } = normalized;
+        const tileCount = columns * rows;
+        const tileByteLength = tileCount * Float32Array.BYTES_PER_ELEMENT;
+        const oldResidentHistory = this._offlineAdaptiveHistory;
+        let ownsPreviousBuffer = false;
+        let previousBuffer;
+        if (previous && oldResidentHistory?.history === previous) {
+            previousBuffer = oldResidentHistory.varianceBuffer;
+        }
+        else {
+            previousBuffer = this._device.createBuffer({
+                label: previous
+                    ? 'Offline previous tile variance upload'
+                    : 'Offline empty tile variance',
+                size: previous ? tileByteLength : Float32Array.BYTES_PER_ELEMENT,
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
+            });
+            this._device.queue.writeBuffer(previousBuffer, 0, previous?.variance ?? new Float32Array(1));
+            ownsPreviousBuffer = true;
+        }
+        const uniformBuffer = this._device.createBuffer({
+            label: 'Offline adaptive sampling parameters',
+            size: 48,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+        });
+        const uniformData = new ArrayBuffer(48);
+        new Uint32Array(uniformData, 0, 8).set([
+            width,
+            height,
+            tileSize,
+            columns,
+            rows,
+            maxSamples,
+            minSamples,
+            previous ? 1 : 0
+        ]);
+        new Float32Array(uniformData, 32, 4).set([
+            absoluteError,
+            relativeError,
+            confidence,
+            0
+        ]);
+        this._device.queue.writeBuffer(uniformBuffer, 0, uniformData);
+        const meanBuffer = this._device.createBuffer({
+            label: 'Offline tile mean luminance',
+            size: tileByteLength,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
+        });
+        const varianceBuffer = this._device.createBuffer({
+            label: 'Offline current tile variance',
+            size: tileByteLength,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
+        });
+        const targetBuffer = this._device.createBuffer({
+            label: 'Offline tile sample targets',
+            size: tileByteLength,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
+        });
+        const readbackBuffer = this._device.createBuffer({
+            label: 'Offline compact tile history readback',
+            size: tileByteLength * 3,
+            usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ
+        });
+        this._ensureAdaptiveSamplingTexture(width, height);
+        this._offlineAdaptivePipeline ??=
+            await this._device.createComputePipelineAsync({
+                label: 'Offline adaptive sampling planner',
+                layout: 'auto',
+                compute: {
+                    module: this._device.createShaderModule({
+                        label: 'Offline adaptive sampling planner',
+                        code: offlineAdaptiveCompute
+                    }),
+                    entryPoint: 'main'
+                }
+            });
+        const bindGroup = this._device.createBindGroup({
+            label: 'Offline adaptive sampling planner',
+            layout: this._offlineAdaptivePipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: { buffer: uniformBuffer } },
+                { binding: 1, resource: { buffer: this._outColorBuffer } },
+                { binding: 2, resource: { buffer: this._outNormalBuffer } },
+                { binding: 3, resource: { buffer: previousBuffer } },
+                { binding: 4, resource: { buffer: meanBuffer } },
+                { binding: 5, resource: { buffer: varianceBuffer } },
+                { binding: 6, resource: { buffer: targetBuffer } },
+                {
+                    binding: 7,
+                    resource: this._adaptiveSamplingTexture.createView()
+                }
+            ]
+        });
+        const encoder = this._device.createCommandEncoder({
+            label: 'Offline adaptive sampling planner'
+        });
+        const pass = encoder.beginComputePass({
+            label: 'Offline adaptive sampling planner'
+        });
+        pass.setPipeline(this._offlineAdaptivePipeline);
+        pass.setBindGroup(0, bindGroup);
+        pass.dispatchWorkgroups(Math.ceil(tileCount / 64));
+        pass.end();
+        encoder.copyBufferToBuffer(meanBuffer, 0, readbackBuffer, 0, tileByteLength);
+        encoder.copyBufferToBuffer(varianceBuffer, 0, readbackBuffer, tileByteLength, tileByteLength);
+        encoder.copyBufferToBuffer(targetBuffer, 0, readbackBuffer, tileByteLength * 2, tileByteLength);
+        this._device.queue.submit([encoder.finish()]);
+        let succeeded = false;
+        try {
+            await readbackBuffer.mapAsync(GPUMapMode.READ);
+            const mapped = readbackBuffer.getMappedRange();
+            const meanLuminance = new Float32Array(mapped, 0, tileCount).slice();
+            const variance = new Float32Array(mapped, tileByteLength, tileCount).slice();
+            const sampleTargets = new Uint32Array(mapped, tileByteLength * 2, tileCount).slice();
+            const history = {
+                width,
+                height,
+                tileSize,
+                columns,
+                rows,
+                meanLuminance,
+                variance,
+                sampleTargets
+            };
+            let maximumTarget = minSamples;
+            let totalTargetSamples = 0;
+            for (let tile = 0; tile < tileCount; tile++) {
+                const target = sampleTargets[tile];
+                maximumTarget = Math.max(maximumTarget, target);
+                const tileX = tile % columns;
+                const tileY = Math.floor(tile / columns);
+                const tileWidth = Math.min(tileSize, width - tileX * tileSize);
+                const tileHeight = Math.min(tileSize, height - tileY * tileSize);
+                totalTargetSamples += target * tileWidth * tileHeight;
+            }
+            this._offlineAdaptiveHistory = { history, varianceBuffer };
+            this._rtUniform.views.adaptiveSampling[0] = 1;
+            succeeded = true;
+            if (oldResidentHistory?.varianceBuffer !== varianceBuffer) {
+                oldResidentHistory?.varianceBuffer.destroy();
+            }
+            return {
+                maximumTarget,
+                averageTarget: totalTargetSamples / (width * height),
+                history
+            };
+        }
+        finally {
+            if (readbackBuffer.mapState === 'mapped')
+                readbackBuffer.unmap();
+            readbackBuffer.destroy();
+            meanBuffer.destroy();
+            targetBuffer.destroy();
+            uniformBuffer.destroy();
+            if (ownsPreviousBuffer)
+                previousBuffer.destroy();
+            if (!succeeded)
+                varianceBuffer.destroy();
+        }
+    }
+    _createPipelineLayout() {
+        //Bind group layouts
+        const commonBufferLayoutEntries = Array.from({ length: 4 }, (_, i) => ({
+            binding: i,
+            visibility: GPUShaderStage.COMPUTE,
+            buffer: {
+                type: 'read-only-storage'
+            }
+        }));
+        const buffersBindGroupLayout = this._shaderCache.createBindGroupLayout({
+            label: 'Buffers',
+            entries: commonBufferLayoutEntries
+        });
+        const textureLayoutEntries = [
+            {
+                binding: 0,
+                visibility: GPUShaderStage.COMPUTE,
+                sampler: {}
+            },
+            {
+                binding: 1,
+                visibility: GPUShaderStage.COMPUTE,
+                texture: {
+                    viewDimension: '2d-array'
+                }
+            },
+            // Map size
+            {
+                binding: 3,
+                visibility: GPUShaderStage.COMPUTE,
+                buffer: {
+                    type: 'uniform'
+                }
+            },
+            // Env map
+            {
+                binding: 4,
+                visibility: GPUShaderStage.COMPUTE,
+                texture: {
+                    viewDimension: '2d',
+                    sampleType: 'unfilterable-float'
+                }
+            },
+            // Env map distribution
+            {
+                binding: 5,
+                visibility: GPUShaderStage.COMPUTE,
+                texture: {
+                    viewDimension: '2d',
+                    sampleType: 'unfilterable-float'
+                }
+            },
+            // Background map
+            {
+                binding: 6,
+                visibility: GPUShaderStage.COMPUTE,
+                texture: {
+                    viewDimension: '2d',
+                    sampleType: 'unfilterable-float'
+                }
+            },
+            {
+                binding: 8,
+                visibility: GPUShaderStage.COMPUTE,
+                texture: {
+                    viewDimension: '2d',
+                    sampleType: 'unfilterable-float'
+                }
+            },
+            {
+                binding: 9,
+                visibility: GPUShaderStage.COMPUTE,
+                texture: {
+                    viewDimension: '2d',
+                    sampleType: 'unfilterable-float'
+                }
+            },
+            {
+                binding: 10,
+                visibility: GPUShaderStage.COMPUTE,
+                texture: {
+                    viewDimension: '2d',
+                    sampleType: 'unfilterable-float'
+                }
+            }
+        ];
+        const texturesBindGroupLayout = this._shaderCache.createBindGroupLayout({
+            label: 'Textures', entries: textureLayoutEntries
+        });
+        const uniformsBindGroupLayout = this._shaderCache.createBindGroupLayout({
+            label: 'Uniforms',
+            entries: [
+                ...Array.from({ length: Object.keys(this._uniforms).length }, (_, i) => ({
+                    binding: i,
+                    visibility: GPUShaderStage.COMPUTE,
+                    buffer: {
+                        type: 'uniform'
+                    }
+                })),
+                ...([])
+            ]
+        });
+        const rayTraceOutBuffersBindGroupLayout = this._shaderCache.createBindGroupLayout({
+            label: 'Ray Trace Out Buffers',
+            entries: [
+                ...Array.from({ length: 4 }, (_, i) => ({
+                    binding: i,
+                    visibility: GPUShaderStage.COMPUTE,
+                    buffer: { type: 'storage' }
+                })),
+                ...([])
+            ]
+        });
+        this._rayTracePipelineLayout = this._shaderCache.createPipelineLayout({
+            label: 'Ray Trace Pipeline Layout',
+            bindGroupLayouts: [
+                buffersBindGroupLayout,
+                texturesBindGroupLayout,
+                uniformsBindGroupLayout,
+                rayTraceOutBuffersBindGroupLayout
+            ]
+        });
+    }
+    _updateGPUBuffer(label, gpuBuffer, data, minSize = 200) {
+        const device = this._device;
+        const size = Math.max(data.byteLength, minSize);
+        if (gpuBuffer == null || gpuBuffer.size < size) {
+            this._needsUpdateBindGroups = true;
+            if (gpuBuffer) {
+                gpuBuffer.destroy();
+            }
+            gpuBuffer = device.createBuffer({
+                label,
+                size,
+                usage: GPUBufferUsage.STORAGE |
+                    GPUBufferUsage.COPY_DST |
+                    GPUBufferUsage.COPY_SRC
+            });
+        }
+        this._device.queue.writeBuffer(gpuBuffer, 0, data.buffer);
+        return gpuBuffer;
+    }
+    _uniformBuffer(size) {
+        this._needsUpdateBindGroups = true;
+        return this._device.createBuffer({
+            size,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+        });
+    }
+    async updatePipeline() {
+        if (this._isCompilingShader) {
+            return;
+        }
+        // Set this before any synchronous preparation. updatePipeline is called
+        // without awaiting it, so a preparation error must not let createPass run
+        // with an undefined pipeline in the same frame.
+        this._isCompilingShader = true;
+        let attemptedPipelineSignature;
+        let compilationStartedAt;
+        let pipelineCompilationStartedAt;
+        try {
+            if (this._needsUpdateMeshData) {
+                this._updateMeshData();
+            }
+            else if (this._needsUpdateMeshMembership) {
+                this._updateMeshMembership();
+            }
+            if (this._pendingGeometryUpdates.size)
+                this._updateGeometryData();
+            if (this._needsRefitTLAS)
+                this._refitMeshInstances();
+            if (this._dirtyColorMeshes.size)
+                this._updateMeshColors();
+            if (this._pendingMaterialUpdate)
+                this._updateMaterialData();
+            if (this._needsUpdateLightSamplingData) {
+                this._updateLightSamplingData();
+            }
+            const device = this._device;
+            const constants = this._constants;
+            this._rtUniform.views.sceneFeatureFlags[0] = wgpuSceneFeatureFlags(constants);
+            const hasAlpha = Boolean(constants.HAS_ALPHA_BLEND) &&
+                this._alphaBlendStrategy === 'deterministic-source-over';
+            const hasSceneAlpha = Boolean(constants.HAS_ALPHA);
+            const pipelineSignature = JSON.stringify({
+                constants: Object.keys(constants)
+                    .sort()
+                    .map((key) => [key, constants[key]]),
+                hasDisplacement: this._hasDisplacement,
+                hasAlpha,
+                hasSceneAlpha,
+                hasAnisotropyDirections: Boolean(constants.USE_ANISOTROPY_DIRECTIONS),
+                hasCoatNormals: Boolean(constants.USE_COAT_NORMAL_FRAMES),
+                blasLayoutMask: this._blasLayoutMask,
+                bakePipelineConstants: this._bakePipelineConstants
+            });
+            attemptedPipelineSignature = pipelineSignature;
+            if (pipelineSignature === this._failedPipelineSignature) {
+                return;
+            }
+            this._pipelineError = undefined;
+            // TODO hardcoded defines that will be replaced in the code.
+            const definesKeys = [
+                'NUM_MAPS',
+                'TLAS_STACK_SIZE',
+                'BLAS_STACK_SIZE',
+                'NUM_UNIFORM_LIGHTS'
+            ];
+            // Scene feature flags and background selection are runtime uniforms so
+            // interactive edits do not recompile the path tracer.
+            const constantsNotUsed = [
+                ...Object.keys(WGPU_SCENE_FEATURE_BITS),
+                'USE_BACKGROUND',
+                'USE_BACKGROUND_MAP',
+                'USE_GROUNDED_BACKGROUND',
+                ...MATERIAL_TEXTURE_DEFINES,
+                'USE_ANISOTROPY_DIRECTIONS',
+                'USE_COAT_NORMAL_FRAMES',
+                'COLOR_OFF',
+                'USE_VERTEX_COLOR',
+                'HAS_ALPHA_BLEND',
+                'HAS_ALPHA_MASK'
+            ];
+            const defines = definesKeys.reduce((obj, key) => {
+                obj[key] = constants[key];
+                return obj;
+            }, {});
+            const pipelineConstantsKeys = Object.keys(constants)
+                .sort()
+                .filter((key) => !definesKeys.includes(key) && !constantsNotUsed.includes(key));
+            const defineCode = definesKeys
+                .map((key) => `const ${key} = ${defines[key]};`)
+                .join('\n');
+            const previousPipelineConstantsKeys = Object.keys(this._prevPipelineConstants)
+                .filter((key) => !definesKeys.includes(key) && !constantsNotUsed.includes(key))
+                .sort();
+            const needsCreateShaderModule = !this._rayTracePipelineLayout ||
+                !this._computeShaderModule ||
+                pipelineConstantsKeys.join(',') !==
+                    previousPipelineConstantsKeys.join(',') ||
+                defineCode !== this._prevDefinesCode ||
+                hasAlpha !== this._compiledHasAlpha ||
+                hasSceneAlpha !== this._compiledSceneHasAlpha ||
+                Boolean(constants.USE_ANISOTROPY_DIRECTIONS) !== this._compiledAnisotropyDirections ||
+                Boolean(constants.USE_COAT_NORMAL_FRAMES) !== this._compiledCoatNormals ||
+                this._blasLayoutMask !== this._compiledBlasLayoutMask ||
+                (this._bakePipelineConstants &&
+                    pipelineConstantsKeys.some((key) => constants[key] !== this._prevPipelineConstants[key]));
+            const needsCreatePipeline = needsCreateShaderModule ||
+                pipelineConstantsKeys.some((key) => constants[key] !== this._prevPipelineConstants[key]);
+            compilationStartedAt = needsCreatePipeline
+                ? shaderCompilationNow()
+                : undefined;
+            let sourceGenerationTimeMs = 0;
+            let moduleCreationTimeMs = 0;
+            let sourceBytes = this._shaderCompilationDiagnostics?.sourceBytes ?? 0;
+            let sourceLines = this._shaderCompilationDiagnostics?.sourceLines ?? 0;
+            let sourceFingerprint = this._shaderCompilationDiagnostics?.modules[0]?.sourceFingerprint ?? '';
+            if (needsCreateShaderModule) {
+                const sourceGenerationStartedAt = shaderCompilationNow();
+                const constantsCode = pipelineConstantsKeys
+                    .map((key) => `${this._bakePipelineConstants ? 'const' : 'override'} ${key} = ${constants[key].toString()};`)
+                    .join('\n');
+                const rayTraceShaderCode = /* wgsl */ `
+${defineCode}
+${constantsCode}
+${rayTraceCompute({
+                    hasDisplacement: this._hasDisplacement,
+                    hasAlpha,
+                    hasSceneAlpha,
+                    hasAnisotropyDirections: Boolean(constants.USE_ANISOTROPY_DIRECTIONS),
+                    hasCoatNormals: Boolean(constants.USE_COAT_NORMAL_FRAMES),
+                    blasLayoutMask: this._blasLayoutMask
+                })}`;
+                sourceBytes = rayTraceShaderCode.length;
+                sourceLines = shaderSourceLineCount(rayTraceShaderCode);
+                sourceFingerprint = shaderSourceFingerprint(rayTraceShaderCode);
+                sourceGenerationTimeMs =
+                    shaderCompilationNow() - sourceGenerationStartedAt;
+                const moduleCreationStartedAt = shaderCompilationNow();
+                this._computeShaderModule = this._shaderCache.createShaderModule({
+                    label: 'Ray Trace',
+                    code: rayTraceShaderCode
+                });
+                moduleCreationTimeMs =
+                    shaderCompilationNow() - moduleCreationStartedAt;
+                this._compiledHasAlpha = hasAlpha;
+                this._compiledSceneHasAlpha = hasSceneAlpha;
+                this._compiledAnisotropyDirections = Boolean(constants.USE_ANISOTROPY_DIRECTIONS);
+                this._compiledCoatNormals = Boolean(constants.USE_COAT_NORMAL_FRAMES);
+                this._compiledBlasLayoutMask = this._blasLayoutMask;
+            }
+            if (needsCreatePipeline) {
+                if (!this._rayTracePipelineLayout) {
+                    device.pushErrorScope('validation');
+                    let layoutScopeOpen = true;
+                    try {
+                        this._createPipelineLayout();
+                        const layoutError = await device.popErrorScope();
+                        layoutScopeOpen = false;
+                        if (layoutError)
+                            throw layoutError;
+                    }
+                    catch (error) {
+                        const scopedError = layoutScopeOpen
+                            ? await device.popErrorScope().catch(() => null)
+                            : null;
+                        this._rayTracePipelineLayout = undefined;
+                        const detail = joinWebGPUErrors(error, scopedError);
+                        throw new Error(`Unable to create the ray tracing pipeline layout: ${detail}`);
+                    }
+                }
+                // NOTE must before creating pipeline.
+                // Because createComputePipelineAsync is async.
+                // The constants may be changed after the pipeline is created(in setMesh).
+                this._prevPipelineConstants = { ...this._constants };
+                this._prevDefinesCode = defineCode;
+                this._needsUpdateBindGroups = true;
+                device.pushErrorScope('validation');
+                let pipelineScopeOpen = true;
+                try {
+                    const pipelineConstants = !this._bakePipelineConstants
+                        ? pipelineConstantsKeys.reduce((obj, key) => {
+                            obj[key] = +this._constants[key];
+                            return obj;
+                        }, {})
+                        : undefined;
+                    const diagnostic = {
+                        label: 'Ray Trace',
+                        entryPoint: 'main',
+                        firstFrameRequired: true,
+                        status: 'compiling'
+                    };
+                    pipelineCompilationStartedAt = shaderCompilationNow();
+                    diagnostic.startedAtMs = 0;
+                    diagnostic.concurrentCompilationCount = 1;
+                    this._shaderCompilationDiagnostics = {
+                        status: 'compiling',
+                        sourceBytes,
+                        sourceLines,
+                        pipelineCount: 1,
+                        completedPipelineCount: 0,
+                        sourceGenerationTimeMs,
+                        moduleCreationTimeMs,
+                        modules: [
+                            {
+                                label: 'Ray Trace',
+                                sourceBytes,
+                                sourceLines,
+                                sourceFingerprint
+                            }
+                        ],
+                        pipelines: [{ ...diagnostic }],
+                        maximumConcurrentPipelineCount: 1,
+                        peakConcurrentPipelineCount: 1
+                    };
+                    let rayTracePipeline;
+                    try {
+                        rayTracePipeline = await this._shaderCache.createComputePipelineAsync({
+                            label: 'Ray Trace',
+                            layout: this._rayTracePipelineLayout,
+                            compute: {
+                                module: this._computeShaderModule,
+                                entryPoint: 'main',
+                                constants: pipelineConstants
+                            }
+                        });
+                        diagnostic.status = 'ready';
+                    }
+                    catch (error) {
+                        diagnostic.status = 'failed';
+                        diagnostic.error = getWebGPUErrorMessage(error);
+                        // Pipeline creation already reports WGSL failures. Pull the much
+                        // heavier module diagnostics only on that failure path so normal
+                        // startup does not schedule a second full-module inspection.
+                        const info = await this._computeShaderModule
+                            .getCompilationInfo()
+                            .catch(() => undefined);
+                        const shaderErrors = (info?.messages ?? [])
+                            .filter((message) => message.type === 'error');
+                        if (shaderErrors.length) {
+                            throw new Error(shaderErrors
+                                .map((message) => `Ray Trace WGSL ${message.lineNum}:${message.linePos} ${message.message}`)
+                                .join('\n'));
+                        }
+                        throw error;
+                    }
+                    finally {
+                        diagnostic.endedAtMs =
+                            shaderCompilationNow() - pipelineCompilationStartedAt;
+                        diagnostic.durationMs = diagnostic.endedAtMs;
+                    }
+                    this._rayTracePipeline = rayTracePipeline;
+                    this._depthCompute = { module: this._computeShaderModule, constants: pipelineConstants };
+                    const pipelineError = await device.popErrorScope();
+                    pipelineScopeOpen = false;
+                    if (pipelineError)
+                        throw pipelineError;
+                    const compilationCompletedAt = shaderCompilationNow();
+                    this._shaderCompilationDiagnostics = {
+                        ...this._shaderCompilationDiagnostics,
+                        status: 'ready',
+                        completedPipelineCount: 1,
+                        pipelines: [{ ...diagnostic }],
+                        pipelineCompilationTimeMs: compilationCompletedAt - pipelineCompilationStartedAt,
+                        totalTimeMs: compilationCompletedAt - compilationStartedAt
+                    };
+                }
+                catch (error) {
+                    const scopedError = pipelineScopeOpen
+                        ? await device.popErrorScope().catch(() => null)
+                        : null;
+                    const detail = joinWebGPUErrors(error, scopedError);
+                    if (!this._bakePipelineConstants &&
+                        isWebGPUPipelineSpecializationFailure(error, scopedError)) {
+                        const failedAt = shaderCompilationNow();
+                        if (this._shaderCompilationDiagnostics?.status === 'compiling') {
+                            this._shaderCompilationDiagnostics = {
+                                ...this._shaderCompilationDiagnostics,
+                                status: 'failed',
+                                pipelineCompilationTimeMs: pipelineCompilationStartedAt == null
+                                    ? undefined
+                                    : failedAt - pipelineCompilationStartedAt,
+                                totalTimeMs: compilationStartedAt == null
+                                    ? undefined
+                                    : failedAt - compilationStartedAt,
+                                error: detail
+                            };
+                        }
+                        // WebKit can accept a large WGSL module but fail while translating
+                        // its specialization-constant variant to Metal. Baking the values
+                        // into WGSL lets its front end eliminate disabled feature branches
+                        // before creating the Metal library.
+                        this._bakePipelineConstants = true;
+                        this._rayTracePipeline = undefined;
+                        this._rayTraceBindGroups = undefined;
+                        this._computeShaderModule = undefined;
+                        this._prevPipelineConstants = {};
+                        console.warn('WebGPU pipeline specialization failed; retrying with constants baked into WGSL.');
+                        return;
+                    }
+                    throw new Error(detail);
+                }
+            }
+            // TODO rebind when lights, materials, bvh changed.
+            if (this._needsUpdateBindGroups) {
+                this._needsUpdateBindGroups = false;
+                this._updateBindGroups();
+            }
+            this._failedPipelineSignature = undefined;
+        }
+        catch (error) {
+            this._pipelineError = error;
+            const failedAt = shaderCompilationNow();
+            if (this._shaderCompilationDiagnostics?.status === 'compiling') {
+                this._shaderCompilationDiagnostics = {
+                    ...this._shaderCompilationDiagnostics,
+                    status: 'failed',
+                    pipelineCompilationTimeMs: pipelineCompilationStartedAt == null
+                        ? undefined
+                        : failedAt - pipelineCompilationStartedAt,
+                    totalTimeMs: compilationStartedAt == null
+                        ? undefined
+                        : failedAt - compilationStartedAt,
+                    error: getWebGPUErrorMessage(error)
+                };
+            }
+            this._failedPipelineSignature = attemptedPipelineSignature;
+            // Do not allow the render loop to submit the previous/partial state.
+            // The failed signature prevents retrying the same shader every frame;
+            // changing a pipeline-affecting setting permits a new attempt.
+            this._rayTracePipeline = undefined;
+            this._rayTraceBindGroups = undefined;
+            this._prevPipelineConstants = {};
+            this._needsUpdateBindGroups = true;
+            console.error('Failed to update WebGPU ray tracing pipeline.', error);
+        }
+        finally {
+            this._isCompilingShader = false;
+        }
+    }
+    async readDepthSamples(area, aspect) {
+        const tracePipeline = this._rayTracePipeline;
+        const groups = this._rayTraceBindGroups;
+        if (!tracePipeline || !groups || !this._depthCompute || this._isCompilingShader)
+            return;
+        const packed = packDepthSampleArea(area, aspect ?? this._width / this._height);
+        if (this._depthTracePipeline !== tracePipeline || !this._depthPipeline) {
+            const outputLayout = this._shaderCache.createBindGroupLayout({
+                label: 'Depth query output',
+                entries: [
+                    { binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'storage' } },
+                    { binding: 4, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'uniform' } }
+                ]
+            });
+            const layout = this._shaderCache.createPipelineLayout({
+                label: 'Depth query layout',
+                bindGroupLayouts: [0, 1, 2].map(i => tracePipeline.getBindGroupLayout(i)).concat(outputLayout)
+            });
+            this._depthTracePipeline = tracePipeline;
+            this._depthPipeline = this._shaderCache.createComputePipelineAsync({
+                label: 'Depth query', layout,
+                compute: { ...this._depthCompute, entryPoint: 'depthQuery',
+                    constants: { ...this._depthCompute.constants, DEPTH_QUERY_MODE: 1 } }
+            });
+        }
+        const pipeline = await this._depthPipeline;
+        // Scene uploads can replace the buffers while the small query compiles.
+        if (tracePipeline !== this._rayTracePipeline || groups !== this._rayTraceBindGroups)
+            return;
+        const device = this._device;
+        const bytes = DEPTH_SAMPLE_COUNT * 16;
+        const output = device.createBuffer({ label: 'Depth samples', size: bytes,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC });
+        const readback = device.createBuffer({ label: 'Depth readback', size: bytes,
+            usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST });
+        const params = device.createBuffer({ label: 'Depth area', size: 16,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        try {
+            device.queue.writeBuffer(params, 0, packed);
+            const outputGroup = device.createBindGroup({ layout: pipeline.getBindGroupLayout(3), entries: [
+                    { binding: 0, resource: { buffer: output } },
+                    { binding: 4, resource: { buffer: params } }
+                ] });
+            const encoder = device.createCommandEncoder({ label: 'Depth query' });
+            const pass = encoder.beginComputePass();
+            pass.setPipeline(pipeline);
+            for (let i = 0; i < 3; i++)
+                pass.setBindGroup(i, groups[i]);
+            pass.setBindGroup(3, outputGroup);
+            pass.dispatchWorkgroups(1);
+            pass.end();
+            encoder.copyBufferToBuffer(output, 0, readback, 0, bytes);
+            device.queue.submit([encoder.finish()]);
+            await readback.mapAsync(GPUMapMode.READ);
+            return unpackDepthSamples(new Float32Array(readback.getMappedRange()));
+        }
+        finally {
+            if (readback.mapState === 'mapped')
+                readback.unmap();
+            readback.destroy();
+            output.destroy();
+            params.destroy();
+        }
+    }
+    isCompilingShader() {
+        return this._isCompilingShader;
+    }
+    isPipelineReady() {
+        return ((!!this._rayTracePipeline) &&
+            !!this._rayTraceBindGroups);
+    }
+    getPipelineError() {
+        return this._pipelineError;
+    }
+    _updateBindGroups() {
+        const { _device } = this;
+        const bindGroupPipeline = this._rayTracePipeline;
+        if (!bindGroupPipeline) {
+            throw new Error('WebGPU ray tracing bind-group pipeline is not ready.');
+        }
+        if (!this._bvhBuffer || !this._instancesBuffer) {
+            throw new Error('WebGPU BVH buffers are not ready.');
+        }
+        const bufferBindGroup = _device.createBindGroup({
+            layout: bindGroupPipeline.getBindGroupLayout(0),
+            entries: [
+                this._bvhBuffer,
+                this._instancesBuffer,
+                this._attrBuffers,
+                this._materialsBuffer
+            ].map((buffer, i) => ({
+                binding: i,
+                resource: {
+                    buffer: buffer
+                }
+            }))
+        });
+        const texturesBindGroup = _device.createBindGroup({
+            layout: bindGroupPipeline.getBindGroupLayout(1),
+            entries: [
+                {
+                    binding: 0,
+                    resource: this._mapsSampler
+                },
+                {
+                    binding: 1,
+                    resource: this._maps.createView()
+                },
+                {
+                    binding: 3,
+                    resource: {
+                        buffer: this._mapInfoUniform
+                    }
+                },
+                { binding: 4, resource: this._envTex.createView() },
+                { binding: 5, resource: this._envDistributionTex.createView() },
+                { binding: 6, resource: this._backgroundTex.createView() },
+                { binding: 8, resource: this._lightSamplingTexture.createView() },
+                { binding: 9, resource: this._openPbrEnergyLut.createView() },
+                {
+                    binding: 10,
+                    resource: this._adaptiveSamplingTexture.createView()
+                }
+            ]
+        });
+        const uniformBindGroup = _device.createBindGroup({
+            layout: bindGroupPipeline.getBindGroupLayout(2),
+            entries: Object.keys(this._uniforms).map((key, i) => ({
+                binding: i,
+                resource: {
+                    buffer: this._uniforms[key]
+                }
+            }))
+        });
+        const target = this._targetOutputs.get(this._activeTarget);
+        const outputBindGroup = target.pipeline === bindGroupPipeline && target.bindGroup || _device.createBindGroup({
+            layout: bindGroupPipeline.getBindGroupLayout(3),
+            entries: [
+                this._outColorBuffer,
+                this._outNormalBuffer,
+                this._outAlbedoBuffer,
+                this._outShadowCatcherBuffer
+            ].map((buffer, i) => ({
+                binding: i,
+                resource: { buffer }
+            }))
+        });
+        target.bindGroup = outputBindGroup;
+        target.pipeline = bindGroupPipeline;
+        this._rayTraceBindGroups = [
+            bufferBindGroup,
+            texturesBindGroup,
+            uniformBindGroup,
+            outputBindGroup
+        ];
+    }
+    createPass(encoder, clear, tiles, timing) {
+        // Update light buffer.
+        if (this._needsUpdateAnalyticLightsBuffer) {
+            const lightsBufferData = packAnalyticsLightsToBuffer(this._analyticLights, this._materialData.getLightTexturesIndices(), this._analyticLightSelectionPmfs, this._iesProfileTexelOffsets);
+            this._device.queue.writeBuffer(this._uniforms.analyticLights, 0, lightsBufferData.buffer, 0, lightsBufferData.buffer.byteLength);
+            this._needsUpdateAnalyticLightsBuffer = false;
+        }
+        const dispatchWidth = Math.ceil(this._width / tiles[0]);
+        const dispatchHeight = Math.ceil(this._height / tiles[1]);
+        // Update other uniforms
+        this._device.queue.writeBuffer(this._uniforms.rtUniform, 0, this._rtUniform.buffer);
+        if (clear) {
+            encoder.clearBuffer(this._outColorBuffer);
+            encoder.clearBuffer(this._outNormalBuffer);
+            encoder.clearBuffer(this._outAlbedoBuffer);
+            encoder.clearBuffer(this._outShadowCatcherBuffer);
+        }
+        const descriptor = {};
+        const querySet = timing?.querySet;
+        if (querySet) {
+            descriptor.timestampWrites = {
+                querySet,
+                beginningOfPassWriteIndex: 0,
+                endOfPassWriteIndex: 1
+            };
+        }
+        const pass = encoder.beginComputePass(descriptor);
+        if (!this._rayTracePipeline || !this._rayTraceBindGroups) {
+            throw new Error('WebGPU ray tracing pass was submitted before it was ready.');
+        }
+        pass.setPipeline(this._rayTracePipeline);
+        this._rayTraceBindGroups.forEach((bindGroup, idx) => {
+            pass.setBindGroup(idx, bindGroup);
+        });
+        pass.dispatchWorkgroups(Math.ceil(dispatchWidth / WORKGROUP_SIZE), Math.ceil(dispatchHeight / WORKGROUP_SIZE), 1);
+        pass.end();
+    }
+    async getDebugBVHData() {
+        if (!this._debugBVHBuffer) {
+            throw new Error(`software-bvh exposes no CPU-readable BVH debug buffer`);
+        }
+        return {
+            buffer: this._debugBVHBuffer
+        };
+    }
+    getDiagnostics() {
+        return {
+            textureAtlas: this._materialData?.textureAtlasStats,
+            shaderCompilation: this._shaderCompilationDiagnostics,
+            lightSampling: {
+                emissiveTriangles: this._emissiveTriangles.length,
+                activeChoices: this._rtUniform.views.lightChoiceCount[0],
+                totalWeight: this._rtUniform.views.lightWeightTotal[0],
+                domains: this._lightDomainDiagnostics
+            },
+            bvh: {
+                tlasTraversalStackSize: this._constants.TLAS_STACK_SIZE,
+                blasTraversalStackSize: this._constants.BLAS_STACK_SIZE
+            }
+        };
+    }
+    setAlphaBlendStrategy(strategy) {
+        const next = strategy === 'deterministic-source-over'
+            ? strategy
+            : 'stochastic';
+        if (next === this._alphaBlendStrategy)
+            return false;
+        this._alphaBlendStrategy = next;
+        if (this._constants.HAS_ALPHA_BLEND) {
+            this._computeShaderModule = undefined;
+            this._rayTracePipeline = undefined;
+            this._rayTracePipelineLayout = undefined;
+            this._rayTraceBindGroups = undefined;
+            this._prevPipelineConstants = {};
+            this._failedPipelineSignature = undefined;
+            this._needsUpdateBindGroups = true;
+        }
+        return true;
+    }
+    hasDepthOfField() {
+        return this._apertureRadius > 0;
+    }
+    setBounce(bounce) {
+        const next = normalizeBounces(bounce);
+        const changed = this._bounces !== next;
+        this._bounces = next;
+        this._rtUniform.views.bounces[0] = next;
+        return changed;
+    }
+    setDirectLightCandidates(candidates) {
+        const next = normalizeDirectLightCandidates(candidates);
+        const changed = this._directLightCandidates !== next;
+        this._directLightCandidates = next;
+        this._rtUniform.views.directLightCandidates[0] = next;
+        return changed;
+    }
+    setClamping(clamping) {
+        const changed = this._clamping !== clamping;
+        this._rtUniform.views.clamping[0] = clamping ?? 0;
+        this._clamping = clamping;
+        return changed;
+    }
+    setBevelSamples(samples) {
+        const next = normalizeBevelSamples(samples);
+        const changed = this._bevelSamples !== next;
+        if (changed) {
+            this._bevelSamples = next;
+            this._constants.BEVEL_SAMPLES = next;
+        }
+        return changed;
+    }
+    setSamplingPattern(pattern, maxSamples, sequenceSeed = 0) {
+        const code = samplingPatternCode(pattern);
+        const logSPP = zSobolLog2SPP(code === 1 ? maxSamples - 1 : maxSamples);
+        const views = this._rtUniform.views;
+        const changed = this._constants.SAMPLING_PATTERN !== code ||
+            views.sequenceSeed[0] !== (sequenceSeed >>> 0) ||
+            (code === 1 && views.zSobolLogSPP[0] !== logSPP);
+        this._constants.SAMPLING_PATTERN = code;
+        views.sequenceSeed[0] = sequenceSeed;
+        views.zSobolLogSPP[0] = logSPP;
+        return changed;
+    }
+    setSampleSequenceOffset(offset) {
+        this._rtUniform.views.sampleSequenceOffset[0] = offset;
+    }
+    setVarianceMoments(enabled) {
+        this._rtUniform.views.varianceMoments[0] = enabled ? 1 : 0;
+    }
+    setAdaptiveSamplingTargets(targets) {
+        this._rtUniform.views.adaptiveSampling[0] = targets ? 1 : 0;
+        if (!targets)
+            return;
+        const { width, height, data } = targets;
+        if (width <= 0 || height <= 0 || data.length !== width * height) {
+            throw new Error('Adaptive sample targets do not match their dimensions.');
+        }
+        this._ensureAdaptiveSamplingTexture(width, height);
+        this._device.queue.writeTexture({ texture: this._adaptiveSamplingTexture }, data, { bytesPerRow: width * Float32Array.BYTES_PER_ELEMENT }, [width, height]);
+    }
+    setQuality(options) {
+        this._rtUniform.views.bounces[0] = normalizeBounces(options.bounces);
+        this._rtUniform.views.bevel[0] = +options.bevel;
+        this._rtUniform.views.dispersionWavelengths[0] = options.dispersionWavelengths;
+        this._rtUniform.views.directLightCandidates[0] = normalizeDirectLightCandidates(options.directLightCandidates);
+    }
+    _setEnvMap(envImage) {
+        const device = this._device;
+        // Always create env tex
+        if (!environmentMapSourcesMatch(envImage, this._envImageSource) ||
+            !this._envTex) {
+            this._envImageSource = envImage;
+            this._envTex?.destroy();
+            this._envDistributionTex?.destroy();
+            const distribution = envImage && envMapDistribution(envImage);
+            const usage = GPUTextureUsage.TEXTURE_BINDING |
+                GPUTextureUsage.COPY_DST |
+                GPUTextureUsage.RENDER_ATTACHMENT;
+            this._envTex = device.createTexture({
+                format: 'rgba32float',
+                usage,
+                label: 'Env',
+                size: {
+                    width: envImage ? envImage.width : 1,
+                    height: envImage ? envImage.height : 1,
+                    depthOrArrayLayers: 1
+                }
+            });
+            this._envDistributionTex = device.createTexture({
+                format: 'rg32float',
+                usage,
+                label: 'Env Distribution',
+                size: {
+                    width: distribution ? distribution.width : 1,
+                    height: distribution ? distribution.height : 1,
+                    depthOrArrayLayers: 1
+                }
+            });
+            if (envImage && distribution) {
+                device.queue.writeTexture({
+                    texture: this._envTex
+                }, envImage.data.buffer, {
+                    bytesPerRow: envImage.width * 4 * 4
+                }, {
+                    width: envImage.width,
+                    height: envImage.height,
+                    depthOrArrayLayers: 1
+                });
+                device.queue.writeTexture({
+                    texture: this._envDistributionTex
+                }, distribution.data.buffer, {
+                    bytesPerRow: distribution.width * 4 * 2
+                }, {
+                    width: distribution.width,
+                    height: distribution.height,
+                    depthOrArrayLayers: 1
+                });
+            }
+            this._needsUpdateBindGroups = true;
+        }
+        this._constants.USE_ENVMAP = !!envImage;
+    }
+    setMeshes(meshes, update) {
+        for (const mesh of update?.colors ?? [])
+            this._dirtyColorMeshes.add(mesh);
+        if (update && this._preparedMeshData && this._materialData &&
+            !this._needsUpdateMeshData && !this._needsUpdateMeshMembership && meshes === this._meshes) {
+            const materialUpdate = this._materialChanges.classify(update.materials ?? []);
+            if (materialUpdate.level !== 'geometry' && canUpdateGeometries(this._preparedMeshData, update.geometries ?? [])) {
+                if (update.materials?.length) {
+                    const pending = this._pendingMaterialUpdate;
+                    this._pendingMaterialUpdate = {
+                        level: pending?.level === 'textures' ? 'textures' : materialUpdate.level,
+                        emission: !!pending?.emission || materialUpdate.emission,
+                        emissiveMap: !!pending?.emissiveMap || materialUpdate.emissiveMap,
+                        materials: new Set([...(pending?.materials ?? []), ...update.materials])
+                    };
+                    this._meshSnapshot.forEach(item => { item.materialKeys = item.materials.map(getMaterialHashKey); });
+                }
+                for (const geometry of update.geometries ?? [])
+                    this._pendingGeometryUpdates.add(geometry);
+                for (const item of this._meshSnapshot)
+                    if (this._pendingGeometryUpdates.has(item.geometry))
+                        item.geometryVersion = item.geometry.version;
+                for (const mesh of update.transforms ?? []) {
+                    const item = this._snapshotByMesh.get(mesh);
+                    if (!item)
+                        continue;
+                    item.matrix = Array.from(mesh.transform);
+                    this._dirtyTransformMeshes.add(mesh);
+                    this._needsRefitTLAS = true;
+                }
+                return !!update.materials?.length || !!update.transforms?.length || !!update.colors?.length || !!update.geometries?.length;
+            }
+        }
+        const transformOnlyMeshes = update?.materials?.length || update?.colors?.length ? undefined : update?.transforms;
+        const materialChange = !!update?.materials?.length;
+        if (transformOnlyMeshes && !transformOnlyMeshes.some(mesh => mesh instanceof InstancedMesh) &&
+            meshes === this._meshes &&
+            this._meshSnapshot.length === meshes.length &&
+            this._meshSnapshot.every((snapshot) => snapshot.geometryVersion === snapshot.geometry.version &&
+                snapshot.bvh === getGeometryBvh(snapshot.geometry))) {
+            let transformChange = false;
+            for (const mesh of transformOnlyMeshes) {
+                const snapshot = this._snapshotByMesh.get(mesh);
+                if (!snapshot)
+                    continue;
+                const matrix = mesh.transform;
+                if (snapshot.matrix.length === matrix.length &&
+                    snapshot.matrix.every((value, index) => value === matrix[index])) {
+                    continue;
+                }
+                snapshot.matrix = Array.from(matrix);
+                this._dirtyTransformMeshes.add(mesh);
+                transformChange = true;
+            }
+            if (transformChange) {
+                this._needsRefitTLAS = true;
+            }
+            return transformChange;
+        }
+        const previousSnapshot = this._meshSnapshot;
+        const nextSnapshot = meshes.map((mesh) => ({
+            mesh,
+            instanceCount: mesh instanceof InstancedMesh ? mesh.count : 1,
+            instanceVersion: mesh instanceof InstancedMesh ? mesh.transformsVersion : 0,
+            instanceTransforms: mesh instanceof InstancedMesh ? mesh.transforms : undefined,
+            instanceColors: mesh instanceof InstancedMesh ? mesh.colors : undefined,
+            colorVersion: mesh instanceof InstancedMesh ? mesh.colorsVersion : 0,
+            geometry: mesh.geometry,
+            bvh: getGeometryBvh(mesh.geometry),
+            materials: mesh.materials.slice(),
+            materialKeys: mesh.materials.map(getMaterialHashKey),
+            geometryVersion: mesh.geometry.version,
+            positionArray: mesh.geometry.position.array,
+            positionItemSize: mesh.geometry.position.itemSize,
+            indexArray: mesh.geometry.indices.array,
+            indexItemSize: mesh.geometry.indices.itemSize,
+            materialIndexArray: mesh.geometry.materialIndex?.array,
+            materialIndexItemSize: mesh.geometry.materialIndex?.itemSize,
+            matrix: Array.from(mesh.transform)
+        }));
+        const membershipChanged = nextSnapshot.length !== previousSnapshot.length ||
+            nextSnapshot.some((item, i) => item.mesh !== previousSnapshot[i]?.mesh || item.instanceCount !== previousSnapshot[i]?.instanceCount ||
+                item.materials.some((material, k) => material !== previousSnapshot[i]?.materials[k]));
+        const membership = !this._needsUpdateMeshData && membershipChanged && this._preparedMeshData
+            ? this._membershipCache.update(this._preparedMeshData, meshes) : undefined;
+        if (membership) {
+            const versions = new Map(previousSnapshot.flatMap(item => item.materials.map((m, i) => [m, item.materialKeys[i]])));
+            const materialsChanged = membership.materials.length !== this._preparedMeshData.materials.length ||
+                membership.materials.some((m, i) => m !== this._preparedMeshData.materials[i] ||
+                    versions.has(m) && getMaterialHashKey(m) !== versions.get(m));
+            this._pendingMembershipData = membership;
+            this._meshes = meshes;
+            this._meshSnapshot = nextSnapshot;
+            this._snapshotByMesh = new WeakMap();
+            nextSnapshot.forEach(item => this._snapshotByMesh.set(item.mesh, item));
+            this._needsUpdateMeshMembership = true;
+            this._needsRefitTLAS = false;
+            this._dirtyTransformMeshes.clear();
+            if (materialsChanged)
+                this._pendingMaterialUpdate = { level: 'textures', emission: true,
+                    emissiveMap: true, materials: new Set(membership.materials) };
+            return true;
+        }
+        const membershipOnlyChange = !!this._residentPreparedMeshData &&
+            (nextSnapshot.length !== previousSnapshot.length ||
+                nextSnapshot.some((next, index) => next.mesh !== previousSnapshot[index]?.mesh)) &&
+            nextSnapshot.every((next) => {
+                const resident = this._residentSnapshotByMesh.get(next.mesh);
+                return (!!resident &&
+                    next.colorVersion === resident.colorVersion && next.instanceColors === resident.instanceColors &&
+                    next.geometry === resident.geometry &&
+                    next.bvh === resident.bvh &&
+                    next.materials.length === resident.materials.length &&
+                    next.materials.every((material, index) => material === resident.materials[index]) &&
+                    next.materialKeys.every((hash, index) => hash === resident.materialKeys[index]) &&
+                    next.geometryVersion === resident.geometryVersion &&
+                    this._materialChanges.classify(next.materials).level === 'params' &&
+                    next.positionArray === resident.positionArray &&
+                    next.indexArray === resident.indexArray &&
+                    next.materialIndexArray === resident.materialIndexArray &&
+                    next.matrix.every((value, index) => value === resident.matrix[index]));
+            });
+        if (membershipOnlyChange) {
+            this._meshes = meshes;
+            this._meshSnapshot = nextSnapshot;
+            this._snapshotByMesh = new WeakMap();
+            nextSnapshot.forEach((snapshot) => {
+                this._snapshotByMesh.set(snapshot.mesh, snapshot);
+            });
+            this._needsUpdateMeshMembership = true;
+            this._needsRefitTLAS = false;
+            this._dirtyTransformMeshes.clear();
+            return true;
+        }
+        const topologyOrMaterialChange = nextSnapshot.length !== previousSnapshot.length ||
+            nextSnapshot.some((next, i) => {
+                const prev = previousSnapshot[i];
+                return (!prev ||
+                    next.mesh !== prev.mesh || next.instanceCount !== prev.instanceCount ||
+                    next.geometry !== prev.geometry ||
+                    next.bvh !== prev.bvh || next.colorVersion !== prev.colorVersion || next.instanceColors !== prev.instanceColors ||
+                    next.materials.length !== prev.materials.length ||
+                    next.materials.some((material, k) => material !== prev.materials[k]) ||
+                    next.materialKeys.some((hash, k) => hash !== prev.materialKeys[k]) ||
+                    next.positionArray !== prev.positionArray ||
+                    next.positionArray.length !== prev.positionArray.length ||
+                    next.positionItemSize !== prev.positionItemSize ||
+                    next.indexArray !== prev.indexArray ||
+                    next.indexArray.length !== prev.indexArray.length ||
+                    next.indexItemSize !== prev.indexItemSize ||
+                    next.materialIndexArray !== prev.materialIndexArray ||
+                    next.materialIndexArray?.length !== prev.materialIndexArray?.length ||
+                    next.materialIndexItemSize !== prev.materialIndexItemSize);
+            });
+        const geometryChange = !topologyOrMaterialChange &&
+            nextSnapshot.some((next, i) => next.geometryVersion !== previousSnapshot[i].geometryVersion);
+        const structuralChange = topologyOrMaterialChange || geometryChange;
+        const transformChange = !topologyOrMaterialChange &&
+            nextSnapshot.some((next, i) => next.instanceVersion !== previousSnapshot[i].instanceVersion || next.instanceTransforms !== previousSnapshot[i].instanceTransforms || next.matrix.some((value, k) => value !== previousSnapshot[i].matrix[k]));
+        this._meshes = meshes;
+        nextSnapshot.forEach((next, i) => {
+            const prev = previousSnapshot[i];
+            if (prev?.geometry === next.geometry && (prev.positionArray !== next.positionArray || prev.indexArray !== next.indexArray)) {
+                setGeometryBvh(next.geometry, undefined);
+                this._geometriesNeedRefit.add(next.geometry);
+            }
+            // A mesh can be animated before this renderer sees it for the first
+            // time. Its precomputed BLAS may then describe an older pose as well.
+            if (next.geometryVersion > 0 && (!prev || next.geometry !== prev.geometry ||
+                next.geometryVersion !== prev.geometryVersion)) {
+                this._geometriesNeedRefit.add(next.geometry);
+            }
+        });
+        this._meshSnapshot = nextSnapshot;
+        this._snapshotByMesh = new WeakMap();
+        nextSnapshot.forEach((snapshot) => {
+            this._snapshotByMesh.set(snapshot.mesh, snapshot);
+        });
+        if (structuralChange) {
+            this._needsUpdateMeshData = true;
+            this._needsUpdateMeshMembership = false;
+            this._needsRefitTLAS = false;
+            this._dirtyTransformMeshes.clear();
+        }
+        else if (transformChange) {
+            this._needsRefitTLAS = true;
+            nextSnapshot.forEach((next, index) => {
+                if (next.instanceVersion !== previousSnapshot[index].instanceVersion || next.instanceTransforms !== previousSnapshot[index].instanceTransforms || next.matrix.some((value, matrixIndex) => value !== previousSnapshot[index]?.matrix[matrixIndex])) {
+                    this._dirtyTransformMeshes.add(next.mesh);
+                }
+            });
+        }
+        if (materialChange || !update && !structuralChange && !transformChange) {
+            this._needsUpdateMeshData = true;
+        }
+        return structuralChange || transformChange || materialChange || !update;
+    }
+    setTextureAtlasBudget(maxBytes) {
+        const next = Number.isFinite(maxBytes)
+            ? Math.max(4, Math.floor(maxBytes))
+            : DEFAULT_MAX_TEXTURE_ARRAY_BYTES;
+        if (next === this._maxTextureArrayBytes)
+            return false;
+        this._maxTextureArrayBytes = next;
+        this._needsUpdateMeshData = true;
+        return true;
+    }
+    setBackground(background) {
+        this._constants.USE_BACKGROUND = !!background;
+        const backgroundImage = background && !Array.isArray(background)
+            ? generateBackgroundMapFromSceneBackground(background)
+            : undefined;
+        this._constants.USE_BACKGROUND_MAP = !!backgroundImage;
+        if (Array.isArray(background)) {
+            this._rtUniform.views.backgroundColor.set(new F32(background));
+        }
+        const grounded = background &&
+            !Array.isArray(background) &&
+            'type' in background &&
+            background.type === 'GroundedSkybox'
+            ? background
+            : undefined;
+        this._rtUniform.views.groundedBackgroundParams.set(grounded
+            ? [
+                Math.max(grounded.height, 0.0001),
+                Math.max(grounded.radius, 0.0001),
+                grounded.groundHeight ?? 0,
+                1
+            ]
+            : [0, 0, 0, 0]);
+        this._rtUniform.views.groundedBackgroundCenter.set(grounded?.center ?? [0, 0]);
+        this._constants.USE_GROUNDED_BACKGROUND = !!grounded;
+        this._rtUniform.views.backgroundFlags[0] =
+            ((background ? 1 : 0) | (backgroundImage ? 2 : 0) | (grounded ? 4 : 0)) |
+                (this._rtUniform.views.backgroundFlags[0] & 0x80000000);
+        this._setBackgroundMap(backgroundImage);
+    }
+    _setBackgroundMap(backgroundImage) {
+        if (backgroundImage === this._backgroundImageSource && this._backgroundTex) {
+            return;
+        }
+        this._backgroundImageSource = backgroundImage;
+        this._backgroundTex?.destroy();
+        const width = backgroundImage?.width ?? 1;
+        const height = backgroundImage?.height ?? 1;
+        this._backgroundTex = this._device.createTexture({
+            format: 'rgba32float',
+            usage: GPUTextureUsage.TEXTURE_BINDING |
+                GPUTextureUsage.COPY_DST |
+                GPUTextureUsage.RENDER_ATTACHMENT,
+            label: 'Background',
+            size: { width, height, depthOrArrayLayers: 1 }
+        });
+        if (backgroundImage) {
+            const source = backgroundImage.data;
+            const data = source instanceof Float32Array
+                ? source
+                : Float32Array.from(source, (value) => (source instanceof Uint8Array || source instanceof Uint8ClampedArray) ? value / 255 : value);
+            this._device.queue.writeTexture({ texture: this._backgroundTex }, data.buffer, { bytesPerRow: width * 4 * 4 }, { width, height, depthOrArrayLayers: 1 });
+        }
+        this._needsUpdateBindGroups = true;
+    }
+    _updateLightSamplingData() {
+        const choices = this._lightChoices;
+        choices.reserve(1 + this._analyticLights.length + this._emissiveTriangles.length);
+        choices.push(LIGHT_CHOICE_ENVIRONMENT, 0, estimateEnvironmentPower(this._envImageSource));
+        this._analyticLights.forEach((light, i) => choices.push(LIGHT_CHOICE_ANALYTIC, i, estimateAnalyticLightPower(light)));
+        this._emissiveTriangles.forEach((triangle, i) => choices.push(LIGHT_CHOICE_EMISSIVE_TRIANGLE, i, triangle.area * triangle.samplingLuminance));
+        const distribution = buildLightAliasTable(choices);
+        const domainDiagnostics = {
+            environment: { count: 0, weight: 0, pmf: 0 },
+            infinite: { count: 0, weight: 0, pmf: 0 },
+            localAndEmissive: { count: 0, weight: 0, pmf: 0 }
+        };
+        this._analyticLightSelectionPmfs = new Array(this._analyticLights.length).fill(0);
+        this._rtUniform.views.envLightPmf[0] = 0;
+        const domains = [domainDiagnostics.environment, domainDiagnostics.infinite, domainDiagnostics.localAndEmissive];
+        for (let i = 0; i < choices.count; i++) {
+            const type = choices.sourceTypes[i], source = choices.sourceIndices[i];
+            const pmf = distribution.pmfs[i];
+            const domainIndex = type === LIGHT_CHOICE_ENVIRONMENT ? LIGHT_DOMAIN_ENVIRONMENT :
+                type === LIGHT_CHOICE_ANALYTIC && this._analyticLights[source]?.type === 'DirectionalLight' ?
+                    LIGHT_DOMAIN_INFINITE : LIGHT_DOMAIN_LOCAL_AND_EMISSIVE;
+            const domain = domains[domainIndex];
+            domain.count++;
+            domain.weight += choices.weights[i];
+            domain.pmf += pmf;
+            if (type === LIGHT_CHOICE_ENVIRONMENT)
+                this._rtUniform.views.envLightPmf[0] = pmf;
+            else if (type === LIGHT_CHOICE_ANALYTIC)
+                this._analyticLightSelectionPmfs[source] = pmf;
+            else
+                this._emissiveTriangles[source].selectionPmf = pmf;
+        }
+        this._lightDomainDiagnostics = domainDiagnostics;
+        this._rtUniform.views.lightChoiceCount[0] = choices.count;
+        this._rtUniform.views.lightWeightTotal[0] = distribution.totalWeight;
+        const emissiveTexels = this._emissiveTriangles.length * 6;
+        const choiceTexels = Math.max(choices.count, 1);
+        const profileStartTexel = emissiveTexels + choiceTexels;
+        const packedIES = packIESProfiles(this._analyticLights, profileStartTexel);
+        this._iesProfileTexelOffsets = packedIES.offsets;
+        const totalTexels = Math.max(profileStartTexel + packedIES.texelCount, 1);
+        const maxDimension = this._device.limits.maxTextureDimension2D;
+        const width = Math.min(maxDimension, Math.max(16, Math.ceil(Math.sqrt(totalTexels) / 16) * 16));
+        const height = Math.ceil(totalTexels / width);
+        if (height > maxDimension) {
+            throw new Error('Too many emissive triangles for the light sampling texture.');
+        }
+        const resized = !this._lightSamplingTexture || width !== this._lightSamplingTextureSize[0] || height !== this._lightSamplingTextureSize[1];
+        if (!this._lightSamplingTexture ||
+            width !== this._lightSamplingTextureSize[0] ||
+            height !== this._lightSamplingTextureSize[1]) {
+            this._lightSamplingTexture?.destroy();
+            this._lightSamplingTexture = this._device.createTexture({
+                label: 'Light sampling data',
+                size: [width, height],
+                format: 'rgba32float',
+                usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST
+            });
+            this._lightSamplingTextureSize = [width, height];
+            this._needsUpdateBindGroups = true;
+        }
+        const textureData = this._lightSamplingScratch?.length === width * height * 4
+            ? this._lightSamplingScratch : new Float32Array(width * height * 4);
+        textureData.fill(0);
+        if (this._emissiveTriangles.length) {
+            packEmissiveTriangles(this._emissiveTriangles, textureData);
+        }
+        new Uint32Array(textureData.buffer).set(distribution.choices, emissiveTexels * 4);
+        textureData.set(packedIES.data, profileStartTexel * 4);
+        const previous = this._lightSamplingData;
+        const full = resized || !previous || this._lightSamplingTriangleCount !== this._emissiveTriangles.length;
+        const words = new Uint32Array(textureData.buffer);
+        const oldWords = previous && new Uint32Array(previous.buffer);
+        let startRow = -1;
+        for (let row = 0; row <= height; row++) {
+            let changed = row < height && full;
+            if (row < height && !full) {
+                for (let i = row * width * 4; i < (row + 1) * width * 4; i++) {
+                    if (words[i] !== oldWords[i]) {
+                        changed = true;
+                        break;
+                    }
+                }
+            }
+            if (changed && startRow < 0)
+                startRow = row;
+            if (!changed && startRow >= 0) {
+                this._device.queue.writeTexture({ texture: this._lightSamplingTexture, origin: [0, startRow] }, textureData.subarray(startRow * width * 4, row * width * 4), { bytesPerRow: width * 16 }, { width, height: row - startRow });
+                startRow = -1;
+            }
+        }
+        this._lightSamplingScratch = previous;
+        this._lightSamplingData = textureData;
+        this._lightSamplingTriangleCount = this._emissiveTriangles.length;
+        this._rtUniform.views.lightSamplingTextureWidth[0] = width;
+        this._rtUniform.views.lightChoiceTexelOffset[0] = emissiveTexels;
+        this._needsUpdateAnalyticLightsBuffer = true;
+        this._needsUpdateLightSamplingData = false;
+    }
+    /** Uploads the combined TLAS/BLAS buffer and the instance records. */
+    _uploadBVH(tlas, blases) {
+        const stacks = getTraversalStackSizes(tlas, blases);
+        this._constants.TLAS_STACK_SIZE = retainedShaderCapacity(stacks.tlas, Number(this._constants.TLAS_STACK_SIZE ?? 0));
+        this._constants.BLAS_STACK_SIZE = retainedShaderCapacity(stacks.blas, Number(this._constants.BLAS_STACK_SIZE ?? 0), 32);
+        const tlasBuffer = new Float32Array(tlas.buffer);
+        const blasBuffer = new Float32Array(concatBLASBuffers(blases));
+        const bvhData = new Float32Array(tlasBuffer.length + blasBuffer.length);
+        const blasOffset = tlasBuffer.length / 4;
+        bvhData.set(tlasBuffer);
+        bvhData.set(blasBuffer, blasOffset * 4);
+        const bvhBuffer = this._updateGPUBuffer('BVH', this._bvhBuffer, bvhData);
+        const instancesBuffer = this._updateGPUBuffer('Instances', this._instancesBuffer, new Float32Array(tlas.instancesBuffer));
+        if (bvhBuffer !== this._bvhBuffer || instancesBuffer !== this._instancesBuffer) {
+            this._needsUpdateBindGroups = true;
+        }
+        this._bvhBuffer = bvhBuffer;
+        this._instancesBuffer = instancesBuffer;
+        this._debugBVHBuffer = bvhData.buffer.slice(0);
+        this._rtUniform.views.blasOffset.set([blasOffset]);
+    }
+    _updateMeshData() {
+        this._pendingGeometryUpdates.clear();
+        this._emissiveCache = new EmissiveTriangleCache();
+        const meshes = this._meshes;
+        for (const geometry of this._geometriesNeedRefit) {
+            const usesDisplacement = meshes.some((mesh) => mesh.geometry === geometry &&
+                !!mesh.materials[0]?.displacementMap &&
+                Math.abs(mesh.materials[0].displacementScale) > 1e-6);
+            if (usesDisplacement || geometryTopologyChanged(this._preparedMeshData, geometry) || !getGeometryBvh(geometry) || !refitBLAS(getGeometryBvh(geometry), geometry)) {
+                setGeometryBvh(geometry, undefined);
+            }
+        }
+        this._geometriesNeedRefit.clear();
+        // TODO check bvh needs to change
+        const res = updateMeshInstances(meshes);
+        this._preparedMeshData = res;
+        this._membershipCache.capture(res);
+        this._pendingMembershipData = undefined;
+        this._needsUpdateMeshMembership = false;
+        const mergedGeometry = res.geometry;
+        const materials = res.materials;
+        const isEmpty = meshes.length === 0 || res.instances.length === 0;
+        const tlas = buildTLAS(res.instances, res.blases);
+        this._tlas = tlas;
+        this._uploadBVH(tlas, res.blases);
+        const materialData = (this._materialData = new MaterialTable(materials, this._analyticLights, {
+            maxTextureArrayBytes: this._maxTextureArrayBytes,
+            maxTextureArrayLayers: this._device.limits.maxTextureArrayLayers,
+            maxTextureDimension2D: this._device.limits.maxTextureDimension2D
+        }));
+        this._emissiveTriangles = this._emissiveCache.collect(res.emissiveBindings, materials);
+        this._needsUpdateLightSamplingData = true;
+        const attrNames = [
+            'position',
+            'normal',
+            'uv',
+            'uv1',
+            'color',
+            'tangent',
+            'materialIndex'
+        ];
+        const attributes = attrNames.map((a) => mergedGeometry[a]);
+        const fixedSize = 4;
+        let stride = 0;
+        const offsets = attrNames.map((attrName, idx) => {
+            const attr = attributes[idx];
+            const offset = stride;
+            if (attr) {
+                stride += fixedSize;
+            }
+            return offset;
+        });
+        const attrBufferData = new F32(mergedGeometry.vertexCount * stride);
+        packVertexAttributes(mergedGeometry, attrBufferData, stride, offsets, 0, mergedGeometry.vertexCount);
+        this._attributeData = attrBufferData;
+        this._attributeStride = stride;
+        this._attributeOffsets = offsets;
+        this._attrBuffers = this._updateGPUBuffer('Attributes', this._attrBuffers, attrBufferData);
+        this._materialsBuffer = this._updateGPUBuffer('Materials', this._materialsBuffer, materialData.getBufferArray(), 
+        // WGSL requires a runtime array binding to contain at least one
+        // MaterialBuffer element, including while a
+        // scene reload temporarily has no material payload.
+        MATERIAL_FLOAT_COUNT * 4);
+        const traversalStackSizes = getTraversalStackSizes(tlas, res.blases);
+        const blasLayoutBits = {
+            bvh2: 1,
+            bvh4: 2,
+            'bvh-gpu': 4,
+            cwbvh: 8
+        };
+        this._blasLayoutMask = res.blases.reduce((mask, blas) => mask | blasLayoutBits[blas.bvh.layout ?? 'bvh2'], 0);
+        Object.assign(this._constants, {
+            TLAS_STACK_SIZE: retainedShaderCapacity(traversalStackSizes.tlas, Number(this._constants.TLAS_STACK_SIZE ?? 0)),
+            BLAS_STACK_SIZE: retainedShaderCapacity(traversalStackSizes.blas, Number(this._constants.BLAS_STACK_SIZE ?? 0), 32),
+            USE_UV: mergedGeometry.uv != null,
+            USE_VERTEX_COLOR: mergedGeometry.color != null,
+            ATTR_STRIDE: stride / fixedSize,
+            ...offsets.reduce((obj, off, idx) => {
+                obj[attrNames[idx].toUpperCase() + '_OFF'] = off / fixedSize;
+                return obj;
+            }, {})
+        });
+        this._updateMaterialConstants(materials, materialData, mergedGeometry);
+        this._updateTextures(materialData);
+        this._needsUpdateBindGroups = true;
+        this._rtUniform.views.isEmpty[0] = +isEmpty;
+        this._meshSnapshot.forEach((snapshot) => {
+            snapshot.bvh = getGeometryBvh(snapshot.geometry);
+        });
+        this._residentPreparedMeshData = res;
+        this._residentSnapshotByMesh = new WeakMap();
+        this._meshSnapshot.forEach((snapshot) => {
+            this._residentSnapshotByMesh.set(snapshot.mesh, snapshot);
+        });
+        this._materialChanges.capture(materials);
+        this._pendingMaterialUpdate = undefined;
+        this._needsUpdateMeshData = false;
+        this._needsUpdateMeshMembership = false;
+        this._needsRefitTLAS = false;
+    }
+    _updateMaterialConstants(materials, materialData, mergedGeometry) {
+        const hasTransmission = materials.some((m) => m.transmissionWeight > 0);
+        if (hasTransmission !== this._hasTransmission) {
+            this._hasTransmission = hasTransmission;
+        }
+        this._hasShadowCatcher = materials.some((m) => m.shadowCatcher);
+        const hasDisplacement = materialData.getDisplacementMaps().length > 0;
+        if (hasDisplacement !== this._hasDisplacement) {
+            this._hasDisplacement = hasDisplacement;
+            // Needs to recreate pipeline layout
+            this._rayTracePipelineLayout = undefined;
+        }
+        const HAS_BEVEL = materials.some((m) => m.bevelSize > 0);
+        const SPECTRAL = materials.some((m) => m.transmissionDispersionScale > 0);
+        const HAS_MEDIUM = materials.some(materialUsesMedium);
+        // Retain the atlas uniform capacity when a stage/material is removed.
+        // Shrinking the array would rebuild every pipeline again on the next edit.
+        const NUM_MAPS = Math.max(Math.ceil(+materialData.defines.NUM_MAPS / 10) * 10, Number(this._constants.NUM_MAPS ?? 0), 20);
+        Object.assign(this._constants, {
+            // Match the atlas UV selector. Keep the second set when any texture
+            // needs it; material/texture edits already rebuild these constants.
+            USE_UV1: materialData.bufferData.mapUvChannel.some(channel => channel > 0.5),
+            // Isotropic OpenPBR constructs its own basis. Normal mapping uses
+            // triangle UV differentials rather than this vertex tangent.
+            USE_TANGENT: mergedGeometry.tangent != null &&
+                materials.some(material => material.specularAnisotropy > 0 || material.coatAnisotropy > 0 || (!!material.coatNormalMap && material.coatWeight > 0)),
+            USE_COAT_NORMAL_FRAMES: materials.some(m => !!m.coatNormalMap && m.coatWeight > 0),
+            USE_ANISOTROPY_DIRECTIONS: materials.some(m => (!!m.coatNormalMap && m.coatWeight > 0) ||
+                m.specularAnisotropy > 0 && (m.specularAnisotropyModel === 'gltf' || !!m.anisotropyMap || m.specularAnisotropyRotation !== 0) ||
+                m.coatAnisotropy > 0 && m.coatAnisotropyRotation !== 0),
+            HAS_MEDIUM,
+            HAS_SHADOW_CATCHER: this._hasShadowCatcher,
+            HAS_THIN_FILM: materials.some((material) => material.thinFilmWeight > 0),
+            HAS_COAT: materials.some((material) => material.coatWeight > 0),
+            HAS_FUZZ: materials.some((material) => material.fuzzWeight > 0),
+            HAS_SUBSURFACE: materials.some((material) => material.subsurfaceWeight > 0),
+            HAS_BEVEL,
+            HAS_ALPHA_MASK: materials.some((m) => resolveMaterialAlphaMode(m) === 'mask'),
+            HAS_ALPHA_BLEND: materials.some((m) => resolveMaterialAlphaMode(m) === 'blend'),
+            HAS_ALPHA: materials.some((m) => resolveMaterialAlphaMode(m) !== 'opaque'),
+            SPECTRAL,
+            BEVEL_SAMPLES: this._bevelSamples,
+            USE_RR: true,
+            // Match WebGL: defer roulette for multiple-scattering SSS paths.
+            RR_MAX: HAS_MEDIUM ? 12 : 2,
+            NUM_UNIFORM_LIGHTS: FIXED_LIGHT_COUNT,
+            ...materialData.defines,
+            NUM_MAPS,
+            ...materialTextureFeatures(materialData.defines),
+            USE_NORMAL_MAPS: +materialData.defines.NUM_NORMAL_MAPS > 0
+        });
+    }
+    _updateGeometryData() {
+        const res = this._preparedMeshData, tlas = this._tlas;
+        const update = updatePreparedGeometries(res, this._pendingGeometryUpdates);
+        for (const { first, count, topologyChanged, deformationOnly } of update.vertices) {
+            packVertexAttributes(res.geometry, this._attributeData, this._attributeStride, this._attributeOffsets, first, count, topologyChanged, deformationOnly);
+            const offset = first * this._attributeStride * 4, size = count * this._attributeStride * 4;
+            this._device.queue.writeBuffer(this._attrBuffers, offset, this._attributeData.buffer, offset, size);
+        }
+        for (const mesh of update.meshes)
+            this._dirtyTransformMeshes.add(mesh);
+        if (update.relocated)
+            for (const binding of res.instanceBindings)
+                this._dirtyTransformMeshes.add(binding.mesh);
+        // Instance BLAS offsets must be refreshed before uploading a resized BVH.
+        if (update.resized) {
+            res.instances = updateMeshInstanceTransforms(res.instanceBindings);
+            refitTLAS(tlas, res.instances, res.blases);
+            this._uploadBVH(tlas, res.blases);
+        }
+        else {
+            const bytes = new Uint8Array(this._debugBVHBuffer);
+            const ranges = [];
+            for (const { blas, offset } of update.blases) {
+                const target = tlas.buffer.byteLength + offset;
+                bytes.set(new Uint8Array(blas.buffer), target);
+                ranges.push({ offset: target, size: blas.buffer.byteLength });
+            }
+            for (const { offset, size } of mergeRefitRanges(ranges)) {
+                this._device.queue.writeBuffer(this._bvhBuffer, offset, this._debugBVHBuffer, offset, size);
+            }
+        }
+        const bits = { bvh2: 1, bvh4: 2, 'bvh-gpu': 4, cwbvh: 8 };
+        this._blasLayoutMask = res.blases.reduce((mask, b) => mask | bits[b.bvh.layout ?? 'bvh2'], 0);
+        const stacks = getTraversalStackSizes(tlas, res.blases);
+        this._constants.BLAS_STACK_SIZE = retainedShaderCapacity(stacks.blas, Number(this._constants.BLAS_STACK_SIZE ?? 0), 32);
+        this._meshSnapshot.forEach(item => { item.bvh = getGeometryBvh(item.geometry); });
+        this._needsRefitTLAS = true;
+        this._pendingGeometryUpdates.clear();
+    }
+    _updateMaterialData() {
+        const update = this._pendingMaterialUpdate;
+        const res = this._preparedMeshData;
+        let materialData = this._materialData;
+        if (update.level === 'textures') {
+            materialData = this._materialData = new MaterialTable(res.materials, this._analyticLights, {
+                maxTextureArrayBytes: this._maxTextureArrayBytes,
+                maxTextureArrayLayers: this._device.limits.maxTextureArrayLayers,
+                maxTextureDimension2D: this._device.limits.maxTextureDimension2D
+            });
+            this._updateTextures(materialData);
+        }
+        else
+            materialData.repackParams(res.materials);
+        this._materialsBuffer = this._updateGPUBuffer('Materials', this._materialsBuffer, materialData.getBufferArray(), MATERIAL_FLOAT_COUNT * 4);
+        this._updateMaterialConstants(res.materials, materialData, res.geometry);
+        if (update.emission || update.emissiveMap) {
+            const resident = this._residentPreparedMeshData;
+            resident.emissiveBindings = resident.instanceBindings.filter(binding => binding.materialIndices.some(index => materialIsEmissive(res.materials[index])));
+            const active = new Set(this._meshes);
+            res.emissiveBindings = resident.emissiveBindings.filter(binding => active.has(binding.mesh));
+            this._emissiveTriangles = this._emissiveCache.collect(res.emissiveBindings, res.materials);
+            this._needsUpdateLightSamplingData = true;
+        }
+        this._needsUpdateBindGroups = true;
+        this._materialChanges.capture([...update.materials]);
+        this._pendingMaterialUpdate = undefined;
+    }
+    /** Rebuilds only instance acceleration data for a cached mesh subset. */
+    _updateMeshMembership() {
+        const resident = this._pendingMembershipData ?? this._residentPreparedMeshData;
+        const pending = this._pendingMembershipData;
+        if (!resident) {
+            this._needsUpdateMeshData = true;
+            this._needsUpdateMeshMembership = false;
+            return;
+        }
+        const activeMeshes = new Set(this._meshes);
+        const instanceBindings = resident.instanceBindings.filter(({ mesh }) => activeMeshes.has(mesh));
+        const emissiveBindings = resident.emissiveBindings.filter(({ mesh }) => activeMeshes.has(mesh));
+        const instances = updateMeshInstanceTransforms(instanceBindings);
+        const res = {
+            ...resident,
+            instances,
+            instanceBindings,
+            emissiveBindings
+        };
+        this._preparedMeshData = res;
+        if (pending)
+            this._residentPreparedMeshData = res;
+        this._pendingMembershipData = undefined;
+        const tlas = buildTLAS(instances, res.blases);
+        this._tlas = tlas;
+        this._uploadBVH(tlas, res.blases);
+        this._emissiveTriangles = this._emissiveCache.collect(emissiveBindings, res.materials);
+        this._needsUpdateLightSamplingData = true;
+        this._rtUniform.views.isEmpty[0] = +(instances.length === 0);
+        this._meshSnapshot.forEach((snapshot) => {
+            snapshot.bvh = getGeometryBvh(snapshot.geometry);
+        });
+        this._needsUpdateMeshMembership = false;
+    }
+    _updateMeshColors() {
+        const res = this._preparedMeshData, tlas = this._tlas;
+        if (res && tlas) {
+            const dirty = updateMeshInstanceColors(res.instanceBindings, res.instances, this._dirtyColorMeshes);
+            const ranges = updateTLASInstanceColors(tlas, res.instances, dirty);
+            if (this._instancesBuffer)
+                for (const { offset, size } of ranges) {
+                    this._device.queue.writeBuffer(this._instancesBuffer, offset, tlas.instancesBuffer, offset, size);
+                }
+        }
+        this._dirtyColorMeshes.clear();
+    }
+    _refitMeshInstances() {
+        const res = this._preparedMeshData;
+        const tlas = this._tlas;
+        if (!res || !tlas || !this._bvhBuffer || !this._instancesBuffer) {
+            this._needsUpdateMeshData = true;
+            this._needsRefitTLAS = false;
+            return;
+        }
+        const dirtyIndices = dirtyMeshInstanceIndices(res.instanceBindings, this._dirtyTransformMeshes, res.instances);
+        const incremental = dirtyIndices.size > 0;
+        const previousInstances = res.instances;
+        res.instances = updateMeshInstanceTransforms(res.instanceBindings, incremental ? res.instances : undefined, incremental ? dirtyIndices : undefined);
+        if (!sameInstanceMembership(previousInstances, res.instances)) {
+            this._tlas = buildTLAS(res.instances, res.blases);
+            this._uploadBVH(this._tlas, res.blases);
+            this._emissiveTriangles = this._emissiveCache.collect(res.emissiveBindings, res.materials);
+            this._needsUpdateLightSamplingData = true;
+            this._rtUniform.views.isEmpty[0] = +(res.instances.length === 0);
+            this._dirtyTransformMeshes.clear();
+            this._needsRefitTLAS = false;
+            return;
+        }
+        const ranges = refitTLAS(tlas, res.instances, res.blases, incremental ? dirtyIndices : undefined);
+        const tlasData = new Float32Array(tlas.buffer);
+        for (const { offset, size } of ranges.tlasRanges) {
+            this._device.queue.writeBuffer(this._bvhBuffer, offset, tlas.buffer, offset, size);
+        }
+        for (const { offset, size } of ranges.instanceRanges) {
+            this._device.queue.writeBuffer(this._instancesBuffer, offset, tlas.instancesBuffer, offset, size);
+        }
+        if (this._debugBVHBuffer) {
+            new Float32Array(this._debugBVHBuffer).set(tlasData);
+        }
+        if (!incremental ||
+            res.emissiveBindings.some(({ mesh }) => this._dirtyTransformMeshes.has(mesh))) {
+            this._emissiveTriangles = this._emissiveCache.collect(res.emissiveBindings, res.materials);
+            this._needsUpdateLightSamplingData = true;
+        }
+        this._dirtyTransformMeshes.clear();
+        this._needsRefitTLAS = false;
+    }
+    _updateTextures(materialData) {
+        // Textures
+        // TODO Avoid zero length array.
+        const mapInfo = materialData.bufferData.mapInfo ?? [0, 0, 0, 0];
+        const mapTransform = materialData.bufferData.mapTransform ?? [1, 1, 0, 0];
+        const mapUvChannel = materialData.bufferData.mapUvChannel ?? [0];
+        const mapColorLinear = materialData.bufferData.mapColorLinear;
+        const numMaps = +this._constants.NUM_MAPS;
+        const mapInfoData = new F32(numMaps * 12);
+        for (let i = 0; i < mapInfo.length; i++) {
+            mapInfoData[i] = mapInfo[i];
+        }
+        for (let i = 0; i < mapTransform.length; i++) {
+            mapInfoData[numMaps * 4 + i] = mapTransform[i];
+        }
+        for (let i = 0; i < mapUvChannel.length; i++) {
+            mapInfoData[numMaps * 8 + i * 4] = mapUvChannel[i];
+            mapInfoData[numMaps * 8 + i * 4 + 1] = mapColorLinear[i];
+        }
+        let mapInfoUniform = this._mapInfoUniform;
+        if (!mapInfoUniform || mapInfoUniform.size !== mapInfoData.byteLength) {
+            mapInfoUniform?.destroy();
+            mapInfoUniform = this._uniformBuffer(mapInfoData.byteLength);
+            this._mapInfoUniform = mapInfoUniform;
+        }
+        this._device.queue.writeBuffer(mapInfoUniform, 0, mapInfoData);
+        const texture = materialData.texture;
+        const maps = this._maps;
+        const textureFormat = texture?.storageType === constants.HALF_FLOAT ? 'rgba16float' : 'rgba8unorm';
+        const bytesPerPixel = textureFormat === 'rgba16float' ? 8 : 4;
+        const textureWidth = Math.max(texture?.width ?? 1, 1);
+        const textureHeight = Math.max(texture?.height ?? 1, 1);
+        // TODO Must at least 2 layers.
+        const textureDepth = Math.max(texture?.source.length ?? 1, 2);
+        const maxTextureArrayLayers = this._device.limits.maxTextureArrayLayers;
+        if (textureDepth > maxTextureArrayLayers) {
+            throw new Error(`The scene needs ${textureDepth} texture-array layers, but this GPU device supports ${maxTextureArrayLayers}.`);
+        }
+        if (!maps ||
+            textureFormat !== maps.format ||
+            textureWidth !== maps.width ||
+            textureHeight !== maps.height ||
+            textureDepth !== maps.depthOrArrayLayers) {
+            maps && maps.destroy();
+            this._maps = this._device.createTexture({
+                format: textureFormat,
+                label: 'Maps',
+                usage: GPUTextureUsage.TEXTURE_BINDING |
+                    GPUTextureUsage.COPY_DST |
+                    GPUTextureUsage.RENDER_ATTACHMENT,
+                size: {
+                    width: textureWidth,
+                    height: textureHeight,
+                    depthOrArrayLayers: textureDepth
+                }
+            });
+            this._needsUpdateBindGroups = true;
+        }
+        // Upload the textures
+        texture?.source.forEach((img, idx) => {
+            if (isTextureDataSource(img)) {
+                if (!(img.data instanceof Uint8Array) && !(img.data instanceof Uint16Array)) {
+                    throw new Error('Material texture atlas GPU upload requires RGBA8 or RGBA16F data.');
+                }
+                this._device.queue.writeTexture({ texture: this._maps, origin: [0, 0, idx] }, img.data, { bytesPerRow: img.width * bytesPerPixel, rowsPerImage: img.height }, { width: img.width, height: img.height, depthOrArrayLayers: 1 });
+                return;
+            }
+            this._device.queue.copyExternalImageToTexture({
+                source: img,
+                // @ts-ignore WebGPU support different flipY for each layer.
+                flipY: texture.flipYArray[idx]
+            }, { texture: this._maps, origin: [0, 0, idx] }, [img.width, img.height]);
+        });
+    }
+    setLights(lights) {
+        const allAnalyticLights = lights.filter((light) => light.type === 'DirectionalLight' ||
+            light.type === 'SphereLight' ||
+            light.type === 'SpotLight' ||
+            light.type === 'RectLight');
+        if (allAnalyticLights.length > FIXED_LIGHT_COUNT) {
+            console.warn(`Too many lights, only the first ${FIXED_LIGHT_COUNT} lights will be used.`);
+        }
+        const analyticLights = allAnalyticLights.slice(0, FIXED_LIGHT_COUNT);
+        const numAnalyticLights = analyticLights.length;
+        const envImage = this._sceneEnvironment.update(lights);
+        this._rtUniform.views.lightsCount[0] = numAnalyticLights;
+        this._setEnvMap(envImage);
+        const lightTexturesChanged = this._rectLightTextures.update(analyticLights);
+        this._analyticLights = analyticLights;
+        if (lightTexturesChanged)
+            this._needsUpdateMeshData = true;
+        this._needsUpdateAnalyticLightsBuffer = true;
+        this._needsUpdateLightSamplingData = true;
+    }
+    _updateViewProjInv(camera, viewProjInv) {
+        mat4.invert(viewProjInv, camera.getProjectionMatrix(this._targetAspect));
+        mat4.mul(viewProjInv, camera.transform, viewProjInv);
+    }
+    // TODO reuse the code of RayTraceNode
+    setCamera(camera) {
+        const viewProjectionInvMat = this._viewProjInv;
+        this._apertureRadius = cameraApertureRadius(camera);
+        this._focusDistance = camera.focusDistance;
+        this._updateViewProjInv(camera, viewProjectionInvMat);
+        mat4.copy(this._cameraWorld, camera.transform);
+    }
+    cameraChanged(camera) {
+        const tmp = mat4.create();
+        this._updateViewProjInv(camera, tmp);
+        return (!numberArraysEqual(this._viewProjInv, tmp) ||
+            cameraApertureRadius(camera) !== this._apertureRadius ||
+            camera.focusDistance !== this._focusDistance);
+    }
+    setSize(width, height, targetAspect = width / height) {
+        this._targetAspect = targetAspect;
+        this._width = width;
+        this._height = height;
+        const arr = this._rtUniform.views.outputSize;
+        arr[0] = width;
+        arr[1] = height;
+        const outColorBuffer = this._outColorBuffer;
+        const bufferSize = width * height * 4 * 4;
+        if (outColorBuffer && outColorBuffer.size === bufferSize) {
+            return;
+        }
+        this._needsUpdateBindGroups = true;
+        const previousBuffers = [];
+        for (let target of [
+            'Color',
+            'Normal',
+            'Albedo',
+            'ShadowCatcher'
+        ]) {
+            const previous = this[`_out${target}Buffer`];
+            if (previous)
+                previousBuffers.push(previous);
+            this[`_out${target}Buffer`] = this._device.createBuffer({
+                label: 'Ray Trace ' + target,
+                // The catcher stores its mask and its primary background contribution.
+                size: target === 'ShadowCatcher' ? width * height * SHADOW_CATCHER_ACCUMULATION_BYTES : bufferSize,
+                usage: GPUBufferUsage.STORAGE |
+                    GPUBufferUsage.COPY_DST |
+                    GPUBufferUsage.COPY_SRC
+            });
+        }
+        this._targetOutputs.set(this._activeTarget, { buffers: [this._outColorBuffer, this._outNormalBuffer, this._outAlbedoBuffer, this._outShadowCatcherBuffer] });
+        // A preview-resolution update can replace these buffers immediately after
+        // an encoded ray-trace or output command was submitted. Retire every old
+        // output only after the queue has completed work already submitted
+        // against it.
+        void this._device.queue
+            .onSubmittedWorkDone()
+            .catch(() => undefined)
+            .then(() => previousBuffers.forEach((buffer) => buffer.destroy()));
+    }
+    setJitter(x, y) {
+        const arr = this._rtUniform.views.jitter;
+        arr[0] = x;
+        arr[1] = y;
+        this._device.queue.writeBuffer(this._uniforms.cameraUniform, 0, new F32([
+            ...this._viewProjInv,
+            ...this._cameraWorld,
+            this._apertureRadius,
+            this._focusDistance,
+            0,
+            0
+        ]));
+    }
+    setSampleTiles(columns, rows, tileX, tileY) {
+        const arr = this._rtUniform.views.scaleOffset;
+        arr[0] = columns;
+        arr[1] = rows;
+        arr[2] = tileX;
+        arr[3] = tileY;
+    }
+    setSampleCount(sampleCount) {
+        this._rtUniform.views.sampleCount[0] = sampleCount;
+    }
+    setTransmissiveOutputAlphaMin(transmissiveAlphaMin) {
+        this._rtUniform.views.transmissiveOutputAlphaMin[0] = transmissiveAlphaMin;
+        const changed = this._transmissiveAlphaMin !== transmissiveAlphaMin;
+        this._transmissiveAlphaMin = transmissiveAlphaMin;
+        return changed;
+    }
+    needsDenoiseAlpha() {
+        return (this._hasShadowCatcher ||
+            (this._transmissiveAlphaMin < 1 && this._hasTransmission));
+    }
+    hasShadowCatcher() {
+        return this._hasShadowCatcher;
+    }
+    dispose() {
+        this._shaderCache.clear();
+        const buffers = new Set([
+            ...Array.from(this._targetOutputs.values()).flatMap(target => target.buffers),
+            this._mapInfoUniform,
+            this._attrBuffers,
+            this._materialsBuffer,
+            this._bvhBuffer,
+            this._instancesBuffer,
+            this._offlineAdaptiveHistory?.varianceBuffer,
+            ...Object.values(this._uniforms)
+        ]);
+        buffers.forEach((buffer) => buffer?.destroy());
+        const textures = new Set([
+            this._maps,
+            this._lightSamplingTexture,
+            this._openPbrEnergyLut,
+            this._envTex,
+            this._envDistributionTex,
+            this._backgroundTex,
+            this._adaptiveSamplingTexture
+        ]);
+        textures.forEach((texture) => texture?.destroy());
+        this._rayTracePipeline = undefined;
+        this._rayTraceBindGroups = undefined;
+    }
+}
+export default WGPURayTracePass;
+//# sourceMappingURL=WGPURayTracePass.js.map