Official Codebase of 3DCodeVerse
Python
scene lib: one guarded planar capture (shader.planarCapture) — the ocean's reflection no longer runs in override passes or clobbers the viewport
gaoypeng38331f059d33
diff --git a/harness/codeverse3d/languages/scene_threejs/starter/src/lib/ocean.js b/harness/codeverse3d/languages/scene_threejs/starter/src/lib/ocean.jsindex e3de0cac..55cf4323 100644--- a/harness/codeverse3d/languages/scene_threejs/starter/src/lib/ocean.js+++ b/harness/codeverse3d/languages/scene_threejs/starter/src/lib/ocean.js@@ -15,7 +15,7 @@*/import * as THREE from 'three';import { mulberry32 } from './noise.js';-import { GLSL_UTIL } from './shader.js';+import { GLSL_UTIL, planarCapture } from './shader.js';import { Reflector } from 'three/addons/objects/Reflector.js';const TAU = Math.PI * 2;@@ -275,6 +275,7 @@ void main() {* be translated/rotated/scaled. Local heights are not world-space raycasts.*/export function makeOceanSurface(opts = {}) {+ let disposed = false;const width = finite(opts.width, 160, 'width', 1, 10000),depth = finite(opts.depth, 160, 'depth', 1, 10000);const height = finite(opts.waveHeight, 1.2, 'waveHeight', 0, 20);@@ -460,7 +461,9 @@ export function makeOceanSurface(opts = {}) {tp = new THREE.Vector3(),ambientContribution = new THREE.Color(),environmentRotation = new THREE.Matrix4();- sea.onBeforeRender = function (renderer, scene, camera) {+ // One guarded colour-pass capture: never in override (GTAO/depth) passes or+ // nested captures, renderer state restored, rigid mirror frame under scale.+ planarCapture(sea, (renderer, scene, camera, toRigid) => {const environment = scene.environment;const equirect =environment &&@@ -496,10 +499,10 @@ export function makeOceanSurface(opts = {}) {}group.updateWorldMatrix(true, false);u.seaRotation.value.getNormalMatrix(group.matrixWorld);- base.call(this, renderer, scene, camera);- };- let time = 0,- disposed = false;+ base.call(sea, renderer, scene, camera);+ u.textureMatrix.value.multiply(toRigid);+ }, { skip: () => disposed });+ let time = 0;const smooth = (x) => {x = Math.max(0, Math.min(1, x));return x * x * (3 - 2 * x);diff --git a/harness/codeverse3d/languages/scene_threejs/starter/src/lib/shader.js b/harness/codeverse3d/languages/scene_threejs/starter/src/lib/shader.jsindex e92eea28..5d1b6574 100644--- a/harness/codeverse3d/languages/scene_threejs/starter/src/lib/shader.js+++ b/harness/codeverse3d/languages/scene_threejs/starter/src/lib/shader.js@@ -1346,3 +1346,76 @@ export function withRendererState(renderer, callback) {}}}++const PLANE_AXIS = new THREE.Vector3(0, 0, 1);+const PLANE_ORIGIN = new THREE.Vector3();++/**+ * Install `mesh.onBeforeRender` for a three.js planar reflection addon+ * (Reflector / Water). The capture runs once per COLOUR draw of `material`:+ * never in an override pass (GTAO, depth), a nested capture or a draw of a+ * replaced material, and never when the camera is behind the plane (unless+ * `mirror.forceUpdate`). The addon reads its plane from a rotation of+ * `mirror.matrixWorld`, which is wrong under nonuniform scale or shear, so+ * during `capture` that matrix is a RIGID frame on the true (inverse-transpose)+ * plane, then restored with the caller's descendants untouched. Renderer+ * state is scoped by withRendererState.+ *+ * capture(renderer, scene, camera, toRigid): toRigid = rigid⁻¹ · mesh.matrixWorld,+ * the factor that maps the addon's rigid-frame texture matrix back onto the+ * mesh's actual local positions. `frame`, `normal` and `point` place the+ * plane (frame-local); both default to the mesh itself and its local +Z.+ */+export function planarCapture(mesh, capture, {+ material = mesh.material, mirror = mesh, frame = mesh,+ normal = PLANE_AXIS, point = PLANE_ORIGIN, skip = null,+} = {}) {+ const actual = new THREE.Matrix4(), rigid = new THREE.Matrix4(), toRigid = new THREE.Matrix4();+ const saved = new THREE.Matrix4(), normalMatrix = new THREE.Matrix3();+ const worldNormal = new THREE.Vector3(), worldPoint = new THREE.Vector3(), eye = new THREE.Vector3();+ const rotation = new THREE.Quaternion();+ let capturing = false;+ mesh.onBeforeRender = function (renderer, scene, camera, geometry, drawMaterial) {+ if (capturing || scene.overrideMaterial || mesh.material !== material+ || (drawMaterial && drawMaterial !== material) || skip?.()) return;+ actual.copy(frame.matrixWorld);+ normalMatrix.getNormalMatrix(actual);+ worldNormal.copy(normal).applyMatrix3(normalMatrix).normalize();+ if (worldNormal.lengthSq() < 0.5) return;+ worldPoint.copy(point).applyMatrix4(actual);+ eye.setFromMatrixPosition(camera.matrixWorld);+ if (eye.sub(worldPoint).dot(worldNormal) < 0 && !mirror.forceUpdate) return;+ rotation.setFromUnitVectors(PLANE_AXIS, worldNormal);+ rigid.makeRotationFromQuaternion(rotation).setPosition(worldPoint);+ toRigid.copy(rigid).invert().multiply(mesh.matrixWorld);+ saved.copy(mirror.matrixWorld);+ const autoUpdate = mirror.matrixWorldAutoUpdate, needsUpdate = mirror.matrixWorldNeedsUpdate;+ const visible = mesh.visible, mirrorVisible = mirror.visible;+ // Nested scene updates must not propagate the temporary rigid frame+ // into caller-owned descendants (including cameras and bones).+ const descendants = [];+ for (const child of mirror.children) child.traverse((node) => {+ descendants.push([node, node.matrixWorldAutoUpdate, node.matrixWorldNeedsUpdate]);+ node.matrixWorldAutoUpdate = false;+ });+ capturing = true;+ mirror.matrixWorldAutoUpdate = false;+ mirror.matrixWorld.copy(rigid);+ mesh.visible = false;+ try {+ return withRendererState(renderer, () => capture(renderer, scene, camera, toRigid));+ } finally {+ mirror.matrixWorld.copy(saved);+ mirror.matrixWorldAutoUpdate = autoUpdate;+ mirror.matrixWorldNeedsUpdate = needsUpdate;+ for (const [node, childAutoUpdate, childNeedsUpdate] of descendants) {+ node.matrixWorldAutoUpdate = childAutoUpdate;+ node.matrixWorldNeedsUpdate = childNeedsUpdate;+ }+ mesh.visible = visible;+ mirror.visible = mirrorVisible;+ capturing = false;+ }+ };+ return mesh;+}diff --git a/harness/codeverse3d/languages/scene_threejs/starter/src/lib/stream.js b/harness/codeverse3d/languages/scene_threejs/starter/src/lib/stream.jsindex bc09a5d0..d23c693c 100644--- a/harness/codeverse3d/languages/scene_threejs/starter/src/lib/stream.js+++ b/harness/codeverse3d/languages/scene_threejs/starter/src/lib/stream.js@@ -13,7 +13,7 @@import * as THREE from 'three';import { Reflector } from 'three/addons/objects/Reflector.js';import { mulberry32 } from './noise.js';-import { GLSL_UTIL, withRendererState } from './shader.js';+import { GLSL_UTIL, planarCapture } from './shader.js';// IcosahedronGeometry duplicates triangle vertices. Preserve rounded cobble// shading after deformation by averaging normals at coincident positions.@@ -503,44 +503,13 @@ export function makeStream(opts = {}) {target.texture.minFilter = THREE.LinearMipmapLinearFilter;uniforms.streamReflection = { value: target.texture };uniforms.streamReflectionMatrix = { value: new THREE.Matrix4() };- const inverseMirror = new THREE.Matrix4();- const mirrorNormalMatrix = new THREE.Matrix3();- const worldMirrorNormal = new THREE.Vector3();- const worldMirrorPoint = new THREE.Vector3();- const mirrorRotation = new THREE.Quaternion();- const mirrorAxis = new THREE.Vector3(0, 0, 1);- let capturing = false;- surface.onBeforeRender = (renderer, scene, camera, geometry, drawMaterial) => {- // GTAO/depth override passes need no colour reflection capture.- if (scene.overrideMaterial || capturing || surface.material !== material- || (drawMaterial && drawMaterial !== material)) return;- // Reflector extracts a rotation from matrixWorld. Passing a scaled or- // sheared plane matrix gives it the wrong normal. Transform the plane- // by the inverse transpose, then supply an equivalent rigid world frame.- mirrorNormalMatrix.getNormalMatrix(group.matrixWorld);- worldMirrorNormal.copy(gradeNormal).applyMatrix3(mirrorNormalMatrix).normalize();- if (worldMirrorNormal.lengthSq() < .5) return;- worldMirrorPoint.copy(reflection.position).applyMatrix4(group.matrixWorld);- mirrorRotation.setFromUnitVectors(mirrorAxis, worldMirrorNormal);- reflection.matrixWorld.makeRotationFromQuaternion(mirrorRotation).setPosition(worldMirrorPoint);- const oldVisible = surface.visible;- const oldMirrorVisible = reflection.visible;- capturing = true;- surface.visible = false;- try {- withRendererState(renderer, () => {- reflection.onBeforeRender(renderer, scene, camera);- inverseMirror.copy(reflection.matrixWorld).invert();- uniforms.streamReflectionMatrix.value- .copy(reflection.material.uniforms.textureMatrix.value)- .multiply(inverseMirror).multiply(surface.matrixWorld);- });- } finally {- surface.visible = oldVisible;- reflection.visible = oldMirrorVisible;- capturing = false;- }- };+ // The helper Reflector is placed on the group's (possibly affine) mean+ // grade; its texture matrix is mapped back onto the surface's positions.+ planarCapture(surface, (renderer, scene, camera, toRigid) => {+ reflection.onBeforeRender(renderer, scene, camera);+ uniforms.streamReflectionMatrix.value+ .copy(reflection.material.uniforms.textureMatrix.value).multiply(toRigid);+ }, { mirror: reflection, frame: group, normal: gradeNormal, point: reflection.position });}if (opts.bed !== false) {const bedMaterial = new THREE.MeshStandardMaterial({diff --git a/harness/codeverse3d/languages/scene_threejs/starter/src/lib/water.js b/harness/codeverse3d/languages/scene_threejs/starter/src/lib/water.jsindex 81f42fd6..ecf3f05f 100644--- a/harness/codeverse3d/languages/scene_threejs/starter/src/lib/water.js+++ b/harness/codeverse3d/languages/scene_threejs/starter/src/lib/water.js@@ -16,7 +16,7 @@import * as THREE from 'three';import { attachDisposal, snapshotResources } from './lifecycle.js';import { Water } from 'three/addons/objects/Water.js';-import { withRendererState } from './shader.js';+import { planarCapture } from './shader.js';// Battery-graded freeze point: mid-phase, waves clearly formed.const FROZEN_TIME = 7.3;@@ -386,18 +386,11 @@ export function makeOcean(width, depth, opts = {}) {ambient: opts.ambient !== undefined,};const base = water.onBeforeRender;- const captureMaterial = water.material;- const actualWorld = new THREE.Matrix4();- const normalMatrix = new THREE.Matrix3();- const worldNormal = new THREE.Vector3();- const worldPoint = new THREE.Vector3();- const rotation = new THREE.Quaternion();- const axis = new THREE.Vector3(0, 0, 1);let first = true;- let capturing = false;- water.onBeforeRender = function (renderer, scene, camera, geometry, material) {- if (disposed || scene.overrideMaterial || capturing || this.material !== captureMaterial- || (material && material !== captureMaterial)) return;+ // Water's plane calculation assumes a rigid matrix; planarCapture+ // supplies one while keeping Water's world-space textureMatrix (unlike+ // Reflector, Water does not project mesh-local positions).+ planarCapture(water, (renderer, scene, camera) => {_readScene(scene, uniforms, pinned);if (first) {first = false;@@ -412,61 +405,20 @@ export function makeOcean(width, depth, opts = {}) {mirror.type = THREE.HalfFloatType;}}- // Water's plane calculation assumes a rigid matrix. Supply the true- // inverse-transpose normal while keeping its world-space textureMatrix:- // unlike Reflector, Water does not project mesh-local positions.- actualWorld.copy(this.matrixWorld);- normalMatrix.getNormalMatrix(actualWorld);- worldNormal.copy(axis).applyMatrix3(normalMatrix).normalize();- if (worldNormal.lengthSq() < 0.5) return;- worldPoint.setFromMatrixPosition(actualWorld);- rotation.setFromUnitVectors(axis, worldNormal);- const autoUpdate = this.matrixWorldAutoUpdate;- const needsUpdate = this.matrixWorldNeedsUpdate;- const visible = this.visible;- // Nested scene updates must not propagate the temporary rigid frame- // into caller-owned descendants (including cameras and bones).- const descendants = [];- for (const child of this.children) child.traverse((node) => {- descendants.push([node, node.matrixWorldAutoUpdate, node.matrixWorldNeedsUpdate]);- node.matrixWorldAutoUpdate = false;- });- capturing = true;- this.matrixWorldAutoUpdate = false;- this.matrixWorld.makeRotationFromQuaternion(rotation).setPosition(worldPoint);+ if (ownedTarget) return base.call(water, renderer, scene, camera);+ // Three keeps this target private. Capture only its own target+ // on the first mirror draw, restoring the method even on error.+ const setTarget = renderer.setRenderTarget;+ renderer.setRenderTarget = function (target, ...args) {+ if (target && target.texture === uniforms.mirrorSampler.value) ownedTarget = target;+ return setTarget.call(this, target, ...args);+ };try {- withRendererState(renderer, () => {- if (ownedTarget) {- base.call(this, renderer, scene, camera);- } else {- // Three keeps this target private. Capture only its own target- // on the first mirror draw, restoring the method even on error.- const setTarget = renderer.setRenderTarget;- renderer.setRenderTarget = function (target, ...args) {- if (target && target.texture === uniforms.mirrorSampler.value) {- ownedTarget = target;- }- return setTarget.call(this, target, ...args);- };- try {- base.call(this, renderer, scene, camera);- } finally {- renderer.setRenderTarget = setTarget;- }- }- });+ return base.call(water, renderer, scene, camera);} finally {- this.matrixWorld.copy(actualWorld);- this.matrixWorldAutoUpdate = autoUpdate;- this.matrixWorldNeedsUpdate = needsUpdate;- for (const [node, childAutoUpdate, childNeedsUpdate] of descendants) {- node.matrixWorldAutoUpdate = childAutoUpdate;- node.matrixWorldNeedsUpdate = childNeedsUpdate;- }- this.visible = visible;- capturing = false;+ renderer.setRenderTarget = setTarget;}- };+ }, { skip: () => disposed });}const owned = snapshotResources(water);if (!opts.waterNormals) owned.add(uniforms.normalSampler.value);diff --git a/harness/codeverse3d/languages/scene_threejs/starter/src/lib/wetground.js b/harness/codeverse3d/languages/scene_threejs/starter/src/lib/wetground.jsindex f3e900a2..a252d80d 100644--- a/harness/codeverse3d/languages/scene_threejs/starter/src/lib/wetground.js+++ b/harness/codeverse3d/languages/scene_threejs/starter/src/lib/wetground.js@@ -36,7 +36,7 @@ import * as THREE from 'three';import { attachDisposal, snapshotResources } from './lifecycle.js';import { Reflector } from 'three/addons/objects/Reflector.js';import { fbm2, noiseDataTexture } from './noise.js';-import { GLSL_UTIL, patchStandard, withRendererState } from './shader.js';+import { GLSL_UTIL, patchStandard, planarCapture } from './shader.js';/*** The film's swell, shared verbatim by the mirror and the overlay.@@ -321,66 +321,13 @@ export function makeMirrorFloor(w, d, opts = {}) {mirror.material.dithering = true;group.add(mirror);- // The addon extracts a rotation from its world matrix, which does not- // transform a plane normal correctly under nonuniform scale or shear.- // Capture in a rigid frame, then map its local projection back to the- // actual affine geometry used by the ordinary draw.+ // Reflector projects mesh-local positions through a rigid-frame capture;+ // map that projection back onto the actual (possibly affine) geometry.const capture = mirror.onBeforeRender;- const captureMaterial = mirror.material;- const actualWorld = new THREE.Matrix4();- const rigidWorld = new THREE.Matrix4();- const inverseRigid = new THREE.Matrix4();- const normalMatrix = new THREE.Matrix3();- const worldNormal = new THREE.Vector3();- const worldPoint = new THREE.Vector3();- const cameraPoint = new THREE.Vector3();- const rotation = new THREE.Quaternion();- const axis = new THREE.Vector3(0, 0, 1);- let capturing = false;- mirror.onBeforeRender = function (renderer, scene, camera, geometry, material) {- if (scene.overrideMaterial || capturing || this.material !== captureMaterial- || (material && material !== captureMaterial)) return;- actualWorld.copy(this.matrixWorld);- normalMatrix.getNormalMatrix(actualWorld);- worldNormal.copy(axis).applyMatrix3(normalMatrix).normalize();- if (worldNormal.lengthSq() < 0.5) return;- worldPoint.setFromMatrixPosition(actualWorld);- cameraPoint.setFromMatrixPosition(camera.matrixWorld);- if (cameraPoint.sub(worldPoint).dot(worldNormal) < 0 && !this.forceUpdate) return;- rotation.setFromUnitVectors(axis, worldNormal);- rigidWorld.makeRotationFromQuaternion(rotation).setPosition(worldPoint);- const autoUpdate = this.matrixWorldAutoUpdate;- const needsUpdate = this.matrixWorldNeedsUpdate;- const visible = this.visible;- // Nested scene updates must not propagate the temporary rigid frame- // into caller-owned descendants (including cameras and bones).- const descendants = [];- for (const child of this.children) child.traverse((node) => {- descendants.push([node, node.matrixWorldAutoUpdate, node.matrixWorldNeedsUpdate]);- node.matrixWorldAutoUpdate = false;- });- capturing = true;- this.matrixWorldAutoUpdate = false;- this.matrixWorld.copy(rigidWorld);- try {- withRendererState(renderer, () => {- capture.call(this, renderer, scene, camera);- inverseRigid.copy(rigidWorld).invert();- captureMaterial.uniforms.textureMatrix.value- .multiply(inverseRigid).multiply(actualWorld);- });- } finally {- this.matrixWorld.copy(actualWorld);- this.matrixWorldAutoUpdate = autoUpdate;- this.matrixWorldNeedsUpdate = needsUpdate;- for (const [node, childAutoUpdate, childNeedsUpdate] of descendants) {- node.matrixWorldAutoUpdate = childAutoUpdate;- node.matrixWorldNeedsUpdate = childNeedsUpdate;- }- this.visible = visible;- capturing = false;- }- };+ planarCapture(mirror, (renderer, scene, camera, toRigid) => {+ capture.call(mirror, renderer, scene, camera);+ mirror.material.uniforms.textureMatrix.value.multiply(toRigid);+ });const overlayMat = new THREE.MeshStandardMaterial({color: overlayColor,diff --git a/harness/tests/scene_runtime/lib/test_library.py b/harness/tests/scene_runtime/lib/test_library.pyindex ea4fa6f9..4642a291 100644--- a/harness/tests/scene_runtime/lib/test_library.py+++ b/harness/tests/scene_runtime/lib/test_library.py@@ -169,7 +169,7 @@ BUILD: dict[str, str] = {"sand.js": "[L.sand.makeSandTerrain({ size: [20, 20], seed: 3 })]","smoke.js": "[L.smoke.makeSmoke({ quality: 'low', seed: 2 }), L.smoke.makeSteam({ quality: 'low' })]","stream.js": "[L.stream.makeStream({ points: [[0, 0.6, -8], [2, 0.3, 0], [0, 0, 8]], width: 2, depth: 0.3,"- " seed: 4, obstacles: [{ u: 0.5, lateral: 0.2, radius: 0.3 }] })]",+ " seed: 4, reflectionSize: 256, obstacles: [{ u: 0.5, lateral: 0.2, radius: 0.3 }] })]","tree.js": "[L.tree.makeTree({ species: 'birch', height: 4, maxLeaves: 600, seed: 3 }),"" L.tree.makeShrub({ maxLeaves: 300, seed: 2 })]","waterfall.js": "[L.waterfall.makeWaterfall({ width: 2, height: 3, seed: 4 })]",diff --git a/harness/tests/scene_runtime/lib/test_planar_capture.py b/harness/tests/scene_runtime/lib/test_planar_capture.pyindex 4c773211..a5e61aed 100644--- a/harness/tests/scene_runtime/lib/test_planar_capture.py+++ b/harness/tests/scene_runtime/lib/test_planar_capture.py@@ -5,21 +5,24 @@ import pytestfrom tests.scene_runtime.lib._probe import compile_scene-_LIBS = ("water.js", "wetground.js")+_LIBS = ("water.js", "wetground.js", "ocean.js")[email protected]("factory", ["wetground", "water"])+# ocean: its reflection once ran in override passes and clobbered the viewport.[email protected]("factory", ["wetground", "water", "ocean"])def test_addon_capture_preserves_affine_projection_and_renderer_state(factory: str) -> None:script = r"""import * as THREE from 'three';import { makeMirrorFloor } from './lib/wetground.js';import { makeOcean } from './lib/water.js';+import { makeOceanSurface } from './lib/ocean.js';import { withRendererState } from './lib/shader.js';export function createScene({renderer}) {const kind='FACTORY';const scene=new THREE.Scene();scene.background=new THREE.Color(0x667788);- const object=kind==='wetground'?makeMirrorFloor(8,8,{rttSize:64,detail:0,ripple:0}):makeOcean(8,8,{rttSize:64,distortionScale:0});- const surface=kind==='wetground'?object.getObjectByName('MirrorSurface'):object;+ const object=kind==='wetground'?makeMirrorFloor(8,8,{rttSize:64,detail:0,ripple:0})+ :kind==='ocean'?makeOceanSurface({width:8,depth:8,segments:16,reflectionSize:64}):makeOcean(8,8,{rttSize:64,distortionScale:0});+ const surface=kind==='wetground'?object.getObjectByName('MirrorSurface'):kind==='ocean'?object.userData.surface:object;// Caller attachments include a mesh, a camera, a bone hierarchy, and a// manually managed world transform; no capture may take ownership of them.const attached=new THREE.Mesh(new THREE.BoxGeometry(.2,.3,.4),new THREE.MeshBasicMaterial());