Skip to content

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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.py
index 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.py
index 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 pytest
from 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());