@aura3d/rendering 4.3.7 → 4.6.0

package/dist/ForwardPass.js

@@ -4,6 +4,8 @@ import { LightUniforms } from "./LightUniforms.js";
 import { Material } from "./Material.js";
 import { MaterialBinding, MaterialBindingError } from "./MaterialBinding.js";
 import { MaterialInstance } from "./MaterialInstance.js";
+import { PortableShaderMaterial } from "./PortableShaderMaterial.js";
+import { cullInstancesToFrustum, MIN_CULLED_INSTANCES } from "./renderer/InstanceFrustumCull.js";
 import { RenderDeviceError } from "./RenderDevice.js";
 import { RenderPipeline } from "./RenderPipeline.js";
 import { BaseRenderPass } from "./RenderPass.js";
@@ -23,7 +25,7 @@ import { instanceBufferSlot } from "./contracts/geometry.js";
 import {} from "./VertexFormat.js";
 import {} from "./ClusteredForwardLighting.js";
 import { programCacheSlot } from "./contracts/program.js";
-import { normalizeProgramFeatures } from "./program/ProgramFeatures.js";
+import { normalizeProgramFeatures, PROGRAM_OUTPUT_SRGB_FEATURE } from "./program/ProgramFeatures.js";
 import { featuresForGeometry, geometryHasSkin, materialFeatureWarning, materialRoutesToGeneratedProgram } from "./program/MaterialFeatures.js";
 import { bindShaderFeatureUniforms, selectShaderFeatureBits } from "./program/FeatureSelect.js";
 import { bindMaterialLobeUniforms } from "./materials/PhysicalFeatures.js";
@@ -71,8 +73,9 @@ export class ForwardPass extends BaseRenderPass {
     // `shaderCaches`) and die with the device.
     static pipelineCaches = new WeakMap();
     static uniformPacketPools = new WeakMap();
-    static instanceSlotPools = new WeakMap();
-    instanceSlotCursor = 0;
+    // SI-3: one owner-keyed slot allocator per device, shared by every ForwardPass (opaque pass, interleaved
+    // transparent segments, mirror/probe views), so an instanced item keeps its buffer across passes and frames.
+    static instanceSlotAllocators = new WeakMap();
     static vertexFormatIds = new WeakMap();
     static nextVertexFormatId = 1;
     static renderStateIds = new WeakMap();
@@ -83,6 +86,8 @@ export class ForwardPass extends BaseRenderPass {
     // execute() because drawItem() does not carry the pass context.
     frameWidth = 0;
     frameHeight = 0;
+    // WP-4: which view this pass renders, so the contact-shadow mask binds only to the main camera's draws (one object per frame).
+    contactMaskScope;
     constructor(options) {
         super(options.framePass?.name ?? "forward", [...(options.inputColorResource ? [options.inputColorResource] : []), ...(options.framePass?.reads ?? [])], options.framePass?.writes ?? ["color"]);
         this.options = options;
@@ -92,6 +97,7 @@ export class ForwardPass extends BaseRenderPass {
         this.skinningPaletteUploads.beginFrame();
         this.frameWidth = context.width;
         this.frameHeight = context.height;
+        this.contactMaskScope = { device: context.device, width: context.width, height: context.height, cameraPosition: this.options.cameraPosition };
         this.beginFramePools(context.device);
         this.clusteredLighting = resolveForwardClusteredLighting(this.options.lights, context.width, context.height, this.options.cameraViewProjectionMatrix);
         const flags = rendererQrFlags(context.device);
@@ -131,7 +137,8 @@ export class ForwardPass extends BaseRenderPass {
             this.clusteredLighting = null;
         }
     }
-    drawItem(device, item) {
+    drawItem(device, sourceItem) {
+        let item = sourceItem;
         // An instanced item with zero instances draws nothing (never a contract throw that blanks the frame).
         if (item.instanceTransforms !== undefined && item.instanceTransforms.length === 0)
             return;
@@ -170,6 +177,13 @@ export class ForwardPass extends BaseRenderPass {
         // Generated iff getShader resolved a generated program for this draw (a
         // compile-failed fallback or an unskinnable skinned item is a legacy draw).
         let generated = this.lastProgramFeatures !== undefined;
+        // Large instanced draws: submit only the instances whose bounding sphere meets this pass's view frustum.
+        const culled = this.cullInstancesToView(item, baseMaterial);
+        if (culled !== null) {
+            if (culled.count === 0)
+                return;
+            item = { ...item, instanceTransforms: culled.transforms, ...(culled.colors ? { instanceColors: culled.colors } : {}) };
+        }
         if (item.instanceTransforms && baseMaterial.renderState.cullMode !== "none" && instancedItemNeedsPerInstanceCullState(item)) {
             for (const expanded of expandInstancedRenderItem(item)) {
                 this.drawItem(device, expanded);
@@ -247,7 +261,7 @@ export class ForwardPass extends BaseRenderPass {
         applyEnvironmentFogUniforms(itemFog, item, shader, uniforms);
         if (generated)
             applyGeneratedFogUniforms(itemFog, shader, uniforms);
-        applyForwardShadowMapUniforms(selectForwardShadowMap(this.options.shadowMap, item, this.options.cameraViewMatrix, this.options.cameraPosition), item, shader, uniforms);
+        applyForwardShadowMapUniforms(selectForwardShadowMap(this.options.shadowMap, item, this.options.cameraViewMatrix, this.options.cameraPosition), item, shader, uniforms, this.contactMaskScope);
         applyOutputColorSpaceUniform(this.options.outputColorSpace ?? "srgb", item, shader, uniforms);
         applyCameraUniforms(this.options.cameraPosition, item, shader, uniforms);
         applyAlphaCutoffUniform(item, shader, uniforms);
@@ -305,6 +319,25 @@ export class ForwardPass extends BaseRenderPass {
             }
         }
     }
+    /**
+     * Per-instance frustum culling for large instanced items (see renderer/InstanceFrustumCull.ts). Only the main camera of this pass is used,
+     * and only for plain meshes: skinned/morphed/custom-attribute items, custom shader materials (vertex displacement) and items that opt out
+     * with `frustumCulled: false` always draw every instance.
+     */
+    cullInstancesToView(item, baseMaterial) {
+        const transforms = item.instanceTransforms;
+        const viewProjection = this.options.cameraViewProjectionMatrix;
+        if (!(transforms instanceof Float32Array) || viewProjection === undefined || viewProjection.length < 16)
+            return null;
+        if (transforms.length < MIN_CULLED_INSTANCES * 16)
+            return null;
+        if (instanceCullExcluded(item, baseMaterial instanceof PortableShaderMaterial))
+            return null;
+        const colors = item.instanceColors;
+        if (colors !== undefined && !(colors instanceof Float32Array))
+            return null;
+        return cullInstancesToFrustum({ viewProjection, modelMatrix: item.modelMatrix, bounds: item.geometry.bounds, transforms, ...(colors ? { colors } : {}) });
+    }
     /**
      * Generated-path instancing (Phase 6): attribute matrices only — the
      * `u_instanceMatrices[64]` uniform path exists solely in the frozen legacy
@@ -317,7 +350,7 @@ export class ForwardPass extends BaseRenderPass {
             return applyInstanceBinding(device, item, shader, uniforms);
         const source = validateInstanceTransformSource(item);
         const count = source.length / 16;
-        const slot = this.instanceSlotFor(device, count, item.instanceColors !== undefined);
+        const slot = this.instanceSlotFor(device, item.label, source, count, item.instanceColors !== undefined);
         slot.buffer.setMatrices(source instanceof Float32Array ? source : new Float32Array(source), count);
         if (item.instanceColors) {
             slot.buffer.setColors(item.instanceColors instanceof Float32Array ? item.instanceColors : new Float32Array(item.instanceColors));
@@ -474,8 +507,10 @@ export class ForwardPass extends BaseRenderPass {
         if (selected[PRD02_IBL_FEATURE] !== undefined && !prd02IblEnvironmentAvailable(this.options.environmentLighting, item)) {
             delete selected[PRD02_IBL_FEATURE];
         }
-        // #867 (games): the feature set follows what the geometry carries
-        // (three.js semantics): no uv → no uv maps, no joints/weights → no skin.
+        // Direct render path (frame output colour space is sRGB: no post chain, no OutputPass): the generated program
+        // tone-maps and encodes its own output. Explicit "srgb" only; an unset option keeps the linear program.
+        if (this.options.outputColorSpace === "srgb")
+            selected[PROGRAM_OUTPUT_SRGB_FEATURE] = true;
         const record = item ? featuresForGeometry({ ...mf, features: { ...mf.features, ...selected } }, (a) => geometryHasAttribute(item.geometry, a)) : { ...mf, features: { ...mf.features, ...selected } };
         return normalizeProgramFeatures({
             ...record,
@@ -509,7 +544,7 @@ export class ForwardPass extends BaseRenderPass {
             pool.free.push(...pool.used);
             pool.used = [];
         }
-        this.instanceSlotCursor = 0;
+        ForwardPass.instanceSlotAllocators.get(device)?.beginPass();
     }
     /** A cleared per-item scratch map; recycled after the next execute begins. */
     acquireUniformPacket(device) {
@@ -564,32 +599,105 @@ export class ForwardPass extends BaseRenderPass {
         return pipeline;
     }
     /**
-     * Persistent attribute-matrix slot for the generated path (Phase 6): slots
-     * are reused in draw order; capacity/colors mismatches retire the old
-     * buffer (its VAOs are evicted by the §6.1 dispose fix).
+     * Persistent attribute-matrix slot for the generated path (Phase 6). SI-3: slots are keyed by the item's
+     * transform array (its owner), not by draw order inside one pass. The order-keyed cursor restarted at 0 in every
+     * ForwardPass, so the opaque pass and each transparent segment wrote different items into slot 0 and the
+     * content-compare upload skip never hit when several passes drew instanced items.
      */
-    instanceSlotFor(device, count, colors) {
-        const index = this.instanceSlotCursor;
-        this.instanceSlotCursor += 1;
+    instanceSlotFor(device, label, transforms, count, colors) {
+        let allocator = ForwardPass.instanceSlotAllocators.get(device);
+        if (!allocator) {
+            allocator = new InstanceSlotAllocator((capacity, withColors) => instanceBufferSlot.get(rendererQrFlags(device))(device, capacity, { colors: withColors }), (buffer) => buffer.dispose());
+            ForwardPass.instanceSlotAllocators.set(device, allocator);
+        }
+        return allocator.acquire(label ? allocator.labelKey(label) : transforms, count, colors);
+    }
+}
+/**
+ * SI-3: owner-keyed pool of persistent instance buffers. The owner is the item label (with its occurrence index in
+ * the pass, so two items sharing a label keep two slots), or the transform array when the item has no label; labels
+ * survive the per-frame RenderItem rebuilds that replace arrays. `acquire(owner)` returns the slot that owner used last
+ * (re-created only when its capacity or colour layout no longer fits); a new owner takes a slot idle for at least
+ * `staleAfterPasses` pass executions, then a new slot up to `maxSlots`, then the least recently used one. Sharing a
+ * slot between two draws is still correct (GL orders the uploads), it only costs a re-upload.
+ */
+export class InstanceSlotAllocator {
+    create;
+    dispose;
+    maxSlots;
+    staleAfterPasses;
+    slots = [];
+    // Strong keys, bounded: an owner's entry is deleted when its slot is taken over, so it never exceeds maxSlots.
+    byOwner = new Map();
+    labelCounts = new Map();
+    pass = 0;
+    constructor(create, dispose, maxSlots = 256, staleAfterPasses = 16) {
+        this.create = create;
+        this.dispose = dispose;
+        this.maxSlots = maxSlots;
+        this.staleAfterPasses = staleAfterPasses;
+    }
+    /** One pass execution started (the idle clock). */
+    beginPass() {
+        this.pass += 1;
+        this.labelCounts.clear();
+    }
+    /** `label#n`: the n-th draw with this label in the current pass. */
+    labelKey(label) {
+        const n = this.labelCounts.get(label) ?? 0;
+        this.labelCounts.set(label, n + 1);
+        return `${label}#${n}`;
+    }
+    get size() {
+        return this.slots.length;
+    }
+    acquire(owner, count, colors) {
         const capacity = Math.max(64, 2 ** Math.ceil(Math.log2(Math.max(1, count))));
-        let slots = ForwardPass.instanceSlotPools.get(device);
-        if (!slots) {
-            slots = [];
-            ForwardPass.instanceSlotPools.set(device, slots);
+        const owned = this.byOwner.get(owner);
+        let index = owned !== undefined && this.slots[owned]?.owner === owner ? owned : -1;
+        if (index < 0) {
+            index = this.slots.findIndex((slot) => slot.owner === null || slot.lastUse <= this.pass - this.staleAfterPasses);
+            if (index < 0 && this.slots.length >= this.maxSlots) {
+                index = 0;
+                for (let i = 1; i < this.slots.length; i += 1)
+                    if (this.slots[i].lastUse < this.slots[index].lastUse)
+                        index = i;
+            }
         }
-        const existing = slots[index];
-        if (existing && existing.colors === colors && existing.capacity >= count) {
-            return existing;
+        if (index < 0) {
+            this.slots.push({ buffer: this.create(capacity, colors), colors, capacity, owner, lastUse: this.pass });
+            index = this.slots.length - 1;
+        }
+        const slot = this.slots[index];
+        if (slot.colors !== colors || slot.capacity < count) {
+            this.dispose(slot.buffer);
+            slot.buffer = this.create(capacity, colors);
+            slot.colors = colors;
+            slot.capacity = capacity;
+        }
+        if (slot.owner !== owner) {
+            if (slot.owner)
+                this.byOwner.delete(slot.owner);
+            slot.owner = owner;
         }
-        existing?.buffer.dispose();
-        const buffer = instanceBufferSlot.get(rendererQrFlags(device))(device, capacity, { colors });
-        const slot = { buffer, colors, capacity };
-        slots[index] = slot;
-        if (slots.length > index + 64)
-            slots.length = index + 64;
+        slot.lastUse = this.pass;
+        this.byOwner.set(owner, index);
         return slot;
     }
 }
+/**
+ * Items the per-instance frustum cull must draw whole: three's `frustumCulled: false`, CPU-unknown vertex motion
+ * (skinning, morphs, custom attributes, custom shader materials), draw ranges, and SI-8 `prd10.wind` vegetation. Wind
+ * bends a plant's top by up to about 0.74 of its height while the cull sphere (1.15 x the bounds radius) covers about
+ * 0.625 of it, so a strongly bent plant at the view edge was culled while still on screen.
+ */
+export function instanceCullExcluded(item, customShaderMaterial) {
+    if (item.frustumCulled === false || item.skinning || item.morphTargets || item.morphWeights || item.instanceAttributes || item.drawRange)
+        return true;
+    if (customShaderMaterial)
+        return true;
+    return item.label?.startsWith("prd10.wind:") === true;
+}
 function lightBucket(count, max = 8) {
     return count <= 0 ? 0 : count === 1 ? 1 : count === 2 ? 2 : count <= 4 ? 4 : max;
 }
@@ -923,13 +1031,30 @@ function renderStateForItem(renderState, item) {
 }
 function instancedItemNeedsPerInstanceCullState(item) {
     const source = validateInstanceTransformSource(item);
-    const baseModel = toMat4Values(item.modelMatrix ?? identityMatrix(), "modelMatrix", item.label);
-    const handedness = new Set();
+    const base = toMat4Values(item.modelMatrix ?? identityMatrix(), "modelMatrix", item.label);
+    // Allocation-free: a 10,000-instance draw runs this every pass. Only the upper 3x3 of
+    // `base * instance` feeds the handedness test, so build it from scalars (same sums as
+    // `multiplyMat4`, rows 0..2 / columns 0..2) instead of two arrays per instance.
     for (let offset = 0; offset < source.length; offset += 16) {
-        const instanceMatrix = mat4FromArrayLike(source, offset);
-        handedness.add(hasNegativeHandedness(multiplyMat4(baseModel, instanceMatrix)));
-    }
-    return handedness.has(true);
+        if (instanceProductHasNegativeHandedness(base, source, offset))
+            return true;
+    }
+    return false;
+}
+function instanceProductHasNegativeHandedness(base, source, offset) {
+    const o = offset;
+    const c00 = base[0 * 4 + 0] * source[o] + base[1 * 4 + 0] * source[o + 1] + base[2 * 4 + 0] * source[o + 2] + base[3 * 4 + 0] * source[o + 3];
+    const c01 = base[0 * 4 + 1] * source[o] + base[1 * 4 + 1] * source[o + 1] + base[2 * 4 + 1] * source[o + 2] + base[3 * 4 + 1] * source[o + 3];
+    const c02 = base[0 * 4 + 2] * source[o] + base[1 * 4 + 2] * source[o + 1] + base[2 * 4 + 2] * source[o + 2] + base[3 * 4 + 2] * source[o + 3];
+    const c10 = base[0 * 4 + 0] * source[o + 4] + base[1 * 4 + 0] * source[o + 5] + base[2 * 4 + 0] * source[o + 6] + base[3 * 4 + 0] * source[o + 7];
+    const c11 = base[0 * 4 + 1] * source[o + 4] + base[1 * 4 + 1] * source[o + 5] + base[2 * 4 + 1] * source[o + 6] + base[3 * 4 + 1] * source[o + 7];
+    const c12 = base[0 * 4 + 2] * source[o + 4] + base[1 * 4 + 2] * source[o + 5] + base[2 * 4 + 2] * source[o + 6] + base[3 * 4 + 2] * source[o + 7];
+    const c20 = base[0 * 4 + 0] * source[o + 8] + base[1 * 4 + 0] * source[o + 9] + base[2 * 4 + 0] * source[o + 10] + base[3 * 4 + 0] * source[o + 11];
+    const c21 = base[0 * 4 + 1] * source[o + 8] + base[1 * 4 + 1] * source[o + 9] + base[2 * 4 + 1] * source[o + 10] + base[3 * 4 + 1] * source[o + 11];
+    const c22 = base[0 * 4 + 2] * source[o + 8] + base[1 * 4 + 2] * source[o + 9] + base[2 * 4 + 2] * source[o + 10] + base[3 * 4 + 2] * source[o + 11];
+    // Column-major: matrix[0..2] = c00,c01,c02; [4..6] = c10,c11,c12; [8..10] = c20,c21,c22 (see hasNegativeHandedness).
+    const determinant = c00 * (c11 * c22 - c21 * c12) - c10 * (c01 * c22 - c21 * c02) + c20 * (c01 * c12 - c11 * c02);
+    return Number.isFinite(determinant) && determinant < -1e-8;
 }
 function expandInstancedRenderItem(item) {
     const source = validateInstanceTransformSource(item);
@@ -1316,7 +1441,7 @@ export function applyPrd02EnvironmentUniforms(environment, item, material, unifo
     }
     const packed = packA3DEnvironmentUniforms({
         probe,
-        ...(env ? { ambient: { color: env.color, intensity: env.intensity } } : {}),
+        ...(env ? prd02AmbientAndHemisphere(env) : {}),
         // EnvironmentLightingOptions rotation is in turns (indirect_default);
         // the PRD-02 chunk's u_envRotation is radians.
         rotation: (env?.environmentMapRotation ?? 0) * Math.PI * 2,
@@ -1335,6 +1460,26 @@ export function applyPrd02EnvironmentUniforms(environment, item, material, unifo
         expectedColorSpace: "linear"
     }));
 }
+/**
+ * LIGHT-05/08: splits the pass ambient (which carries the hemisphere's flat mean for the programs that read only
+ * the ambient scalar) back into the constant ambient and the directional hemisphere pair for the PRD-02 chunk.
+ * With no hemisphere the ambient is passed through unchanged (byte-identical packet).
+ */
+export function prd02AmbientAndHemisphere(env) {
+    const hemi = env.hemisphere;
+    if (!hemi)
+        return { ambient: { color: env.color, intensity: env.intensity } };
+    const rest = [0, 0, 0];
+    for (let i = 0; i < 3; i += 1) {
+        const value = env.color[i] * env.intensity - (hemi.sky[i] + hemi.ground[i]) / 2;
+        // Float residue of the add-then-subtract round trip is clamped; a real ambient is never negative.
+        rest[i] = value > 1e-7 ? value : 0;
+    }
+    return {
+        ambient: { color: rest, intensity: 1 },
+        hemisphere: { sky: hemi.sky, ground: hemi.ground, intensity: 1, direction: hemi.direction }
+    };
+}
 function applyProceduralEnvironmentMapUniforms(proceduralMap, item, shader, uniforms, generatedE3Conjunction = false) {
     if (!proceduralMap) {
         clearProceduralEnvironmentMapUniforms(shader, uniforms);