@threenative/core 0.3.6 → 0.3.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -5
- package/capabilities.json +739 -50
- package/dist/{assets-CqvE429w.d.ts → assets-YUbXa3-Y.d.ts} +101 -2
- package/dist/{canvas-layer-C1-5CviZ.d.ts → canvas-layer-vCtanIeB.d.ts} +1 -1
- package/dist/{game-Jz4Fdoeb.d.ts → game-cb99J-YE.d.ts} +100 -31
- package/dist/hot.d.ts +4 -4
- package/dist/hot.js +23 -5
- package/dist/index.d.ts +1742 -29
- package/dist/index.js +22443 -12423
- package/dist/{model-lod-BDAUYgsS.d.ts → model-lod-CTpZ6imz.d.ts} +1 -1
- package/dist/net.js +39 -12
- package/dist/playtest.d.ts +4 -4
- package/dist/playtest.js +48 -9
- package/dist/react-css.js +23 -0
- package/dist/react.d.ts +2 -2
- package/dist/{renderer-9yEo9hPa.d.ts → renderer-rZm0hVqq.d.ts} +178 -5
- package/dist/ui-layer.d.ts +11 -2
- package/dist/ui-layer.js +76 -4
- package/dist/worker.d.ts +36 -0
- package/dist/worker.js +1088 -0
- package/dist/world.d.ts +11 -3
- package/dist/world.js +1117 -197
- package/mcp/animation-server.mjs +265 -0
- package/mcp/animation.mjs +22 -0
- package/mcp/call.mjs +105 -0
- package/mcp/devtools.mjs +5 -0
- package/mcp/engine-server.mjs +713 -37
- package/mcp/launch.mjs +3 -2
- package/mcp/servers.d.mts +2 -0
- package/mcp/servers.mjs +33 -8
- package/package.json +12 -8
- package/patches/three@0.185.1-prd269-upgrade.patch +308 -0
- package/patches/three@0.185.1.patch +481 -272
- package/src/animation-packet-state.ts +88 -0
- package/src/animation-pose-packet.ts +537 -0
- package/src/animation.ts +779 -31
- package/src/asset-cache.ts +719 -0
- package/src/assets.ts +521 -152
- package/src/audio.ts +29 -3
- package/src/auto-batch.ts +792 -0
- package/src/config.ts +2 -0
- package/src/frame-budget.ts +268 -2
- package/src/game.ts +525 -105
- package/src/grounding.ts +7 -6
- package/src/hot.ts +19 -5
- package/src/index.ts +381 -6
- package/src/input.ts +21 -2
- package/src/interpolation.ts +19 -1
- package/src/launch-diagnostics.ts +7 -2
- package/src/look/ao-multibounce.ts +29 -0
- package/src/look/ao-reach.ts +39 -0
- package/src/look/auto-exposure.ts +264 -0
- package/src/look/default-tone-mapping.ts +44 -0
- package/src/look/exposure-graph.ts +208 -0
- package/src/look/exposure-readback.ts +97 -0
- package/src/look/exposure-settings.ts +132 -0
- package/src/look/filmic-tone-mapping.ts +852 -0
- package/src/look/gi-registry.ts +55 -0
- package/src/look/local-exposure.ts +507 -0
- package/src/look/look-diagnostics.ts +24 -0
- package/src/look/motion-blur.ts +42 -0
- package/src/look/quality.ts +309 -0
- package/src/look/reflection-trace.ts +344 -0
- package/src/look/unreal-bloom.ts +295 -0
- package/src/look/vignette.ts +14 -0
- package/src/look/world-environment.ts +2033 -0
- package/src/loop.ts +25 -1
- package/src/merge-parts.ts +25 -10
- package/src/model-lod.ts +14 -0
- package/src/net-session.ts +58 -14
- package/src/ocean/spectral.ts +41 -7
- package/src/picking.ts +72 -5
- package/src/platform.ts +29 -1
- package/src/playtest.ts +54 -8
- package/src/profiling/FrameCounters.ts +166 -5
- package/src/profiling/FrameStages.ts +289 -0
- package/src/profiling/Spans.ts +39 -25
- package/src/profiling/debug-telemetry.ts +312 -0
- package/src/profiling/scene-warning.ts +42 -6
- package/src/projection-apply.ts +11 -3
- package/src/projection-content.ts +189 -0
- package/src/projection-marker.ts +6 -2
- package/src/projection-plan.ts +279 -28
- package/src/projection-skinned.ts +620 -5
- package/src/projection-stability.ts +16 -0
- package/src/projection-uniform.ts +5 -1
- package/src/quiet-markers.ts +56 -0
- package/src/render/budget-ladder.ts +256 -0
- package/src/render/chain.ts +89 -7
- package/src/render/exposure-units.ts +59 -0
- package/src/render/frame-time-budget.ts +162 -0
- package/src/render/gi-budget.ts +231 -0
- package/src/render/gi-visualize.ts +49 -0
- package/src/render/material-key.ts +1 -0
- package/src/render/probe-volume.ts +196 -36
- package/src/render/rough-diffuse.ts +177 -0
- package/src/render/scene-trace.ts +532 -0
- package/src/render/shadow-filter-budget.ts +237 -0
- package/src/render/sky-capture.ts +194 -0
- package/src/render/soft-shadow.ts +607 -0
- package/src/render/surface-cache.ts +418 -0
- package/src/render/traced-reflections.ts +408 -0
- package/src/render/two-sided-foliage.ts +120 -0
- package/src/render/virtual-shadow-pages.ts +112 -12
- package/src/render/virtual-shadow.ts +386 -38
- package/src/render-camera-cull.ts +536 -31
- package/src/render-pass-budget.ts +140 -22
- package/src/renderProjection.ts +65 -9
- package/src/renderer-config.ts +3 -2
- package/src/renderer.ts +289 -14
- package/src/resolution-scaler.ts +65 -7
- package/src/skeletal-mesh.ts +4 -0
- package/src/snow-field.ts +46 -0
- package/src/softbody.ts +6 -5
- package/src/startup-offscreen-bytes.ts +168 -0
- package/src/startup-readiness.ts +137 -2
- package/src/ui-bridge.ts +38 -0
- package/src/ui-hit-regions.ts +6 -2
- package/src/ui-layer.ts +1 -0
- package/src/ui-state.ts +32 -3
- package/src/version.ts +1 -1
- package/src/viewport.ts +8 -5
- package/src/warmup.ts +76 -10
- package/src/worker-audio.ts +579 -0
- package/src/worker.ts +842 -0
- package/src/world-cells.ts +4 -1
- package/gpl/LICENSE.GPL +0 -117
- package/gpl/convert.py +0 -192
- package/gpl/fixtures/make_world_fixture.py +0 -184
- package/gpl/recipes/_common.py +0 -180
- package/gpl/recipes/bake_ao.py +0 -111
- package/gpl/recipes/decimate.py +0 -70
- package/gpl/recipes/export_world.py +0 -699
- package/gpl/recipes/retarget.py +0 -131
- package/gpl/recipes/unwrap.py +0 -71
- package/mcp/blender-server.mjs +0 -689
- package/mcp/blender.mjs +0 -26
package/src/input.ts
CHANGED
|
@@ -288,7 +288,10 @@ export class InputMap {
|
|
|
288
288
|
const lockTargets = new Set<EventTarget>([this.#target, this.#pointerTarget]);
|
|
289
289
|
if (lockDocument !== undefined) lockTargets.add(lockDocument);
|
|
290
290
|
for (const target of lockTargets) {
|
|
291
|
-
|
|
291
|
+
// A worker has no document to ask; its host forwards the page's verdict as `captured`.
|
|
292
|
+
this.#listen(target, "pointerlockchange", (event) =>
|
|
293
|
+
this.#syncCaptured((event as Event & { captured?: boolean }).captured),
|
|
294
|
+
);
|
|
292
295
|
}
|
|
293
296
|
}
|
|
294
297
|
|
|
@@ -559,6 +562,17 @@ export class InputMap {
|
|
|
559
562
|
}
|
|
560
563
|
|
|
561
564
|
#wheelEvent(event: Event): void {
|
|
565
|
+
// The game's wheel listener lives on the window so a game with no HUD still zooms anywhere.
|
|
566
|
+
// A wheel that landed on a DOM overlay (a scrollable settings list, say) belongs to that
|
|
567
|
+
// overlay: bubbling it into the game would zoom the camera while the player scrolls the HUD.
|
|
568
|
+
const eventTarget = event.target;
|
|
569
|
+
if (
|
|
570
|
+
eventTarget !== null &&
|
|
571
|
+
eventTarget !== undefined &&
|
|
572
|
+
eventTarget !== this.#target &&
|
|
573
|
+
eventTarget !== this.#pointerTarget
|
|
574
|
+
)
|
|
575
|
+
return;
|
|
562
576
|
const wheel = event as Event & { deltaMode?: number; deltaY?: number };
|
|
563
577
|
const deltaY = wheel.deltaY;
|
|
564
578
|
if (deltaY === undefined || !Number.isFinite(deltaY)) return;
|
|
@@ -641,7 +655,12 @@ export class InputMap {
|
|
|
641
655
|
} else if (edgeType === "up" || edgeType === "cancel") {
|
|
642
656
|
this.#pointers.delete(id);
|
|
643
657
|
} else if (tracked !== undefined) {
|
|
644
|
-
|
|
658
|
+
// Under pointer lock Chromium sends a move that presses or releases nothing (`button` -1)
|
|
659
|
+
// with `buttons` 0 while a button is held, about every fifth frame: it released a held block
|
|
660
|
+
// or lock button. Locked, the pointer cannot leave the page, so its pointerup still arrives.
|
|
661
|
+
// Unlocked, the same move is what clears a button released outside the window.
|
|
662
|
+
const phantomRelease = this.raw.pointer.captured && buttons === 0 && pointer.button === -1;
|
|
663
|
+
if (!phantomRelease) tracked.buttons = buttons;
|
|
645
664
|
tracked.position.set(x, y);
|
|
646
665
|
}
|
|
647
666
|
const primary = this.#pointers.values().next().value as IRawInputPointer | undefined;
|
package/src/interpolation.ts
CHANGED
|
@@ -11,6 +11,24 @@ interface ITransformHistory {
|
|
|
11
11
|
references: number;
|
|
12
12
|
}
|
|
13
13
|
|
|
14
|
+
/**
|
|
15
|
+
* Arming the object's world-matrix recompose. The engine composes a node's own matrix from
|
|
16
|
+
* `position`/`quaternion`/`scale` at its walk, whenever the world-matrix dirty flag is set — three's
|
|
17
|
+
* `updateMatrix` for a `matrixAutoUpdate` node, done again one instant later. Core's restore used to cross
|
|
18
|
+
* to request exactly that (one `Mesh.updateMatrix` a body a frame, 300 on the stress lab), so on the engine
|
|
19
|
+
* it sets the flag the walk reads instead. The bridge writes that byte in place (`bindings_scene.cpp`
|
|
20
|
+
* `matrixWorldNeedsUpdate`), so the whole restore crosses nothing. Plain three keeps the call, and so does
|
|
21
|
+
* a node the walk will not compose.
|
|
22
|
+
*/
|
|
23
|
+
function recompose(object: Object3D): void {
|
|
24
|
+
const engine = object as Object3D & { __tnCopyMatrixWorld?: unknown };
|
|
25
|
+
if (object.matrixAutoUpdate && engine.__tnCopyMatrixWorld !== undefined) {
|
|
26
|
+
engine.matrixWorldNeedsUpdate = true;
|
|
27
|
+
return;
|
|
28
|
+
}
|
|
29
|
+
object.updateMatrix();
|
|
30
|
+
}
|
|
31
|
+
|
|
14
32
|
/** Draw-only transforms: simulation and queries always retain the solved tick pose. */
|
|
15
33
|
export class PhysicsInterpolation {
|
|
16
34
|
readonly enabled: boolean;
|
|
@@ -122,7 +140,7 @@ export class PhysicsInterpolation {
|
|
|
122
140
|
continue;
|
|
123
141
|
history.object.position.copy(history.savedPosition);
|
|
124
142
|
history.object.quaternion.copy(history.savedRotation);
|
|
125
|
-
history.object
|
|
143
|
+
recompose(history.object);
|
|
126
144
|
}
|
|
127
145
|
}
|
|
128
146
|
}
|
|
@@ -136,15 +136,20 @@ export function watchStartupStall(options: IStallWatchOptions): () => void {
|
|
|
136
136
|
/**
|
|
137
137
|
* Reports a lost GPU device. Every backend that can lose one exposes the same `device.lost`
|
|
138
138
|
* promise; a renderer that has no device yet (or never will) is not an error here.
|
|
139
|
+
*
|
|
140
|
+
* `destroyedByGame` says whether the game itself shut the renderer down. Only then is a
|
|
141
|
+
* `destroyed` loss quiet: headless Chromium on SwiftShader destroys the device at the first canvas
|
|
142
|
+
* present while the game runs, and that read as a shutdown and was reported nowhere.
|
|
139
143
|
*/
|
|
140
144
|
export function watchDeviceLoss(
|
|
141
145
|
device: { lost?: Promise<{ reason?: string; message?: string }> } | undefined,
|
|
146
|
+
destroyedByGame: () => boolean = () => false,
|
|
142
147
|
): void {
|
|
143
148
|
const lost = device?.lost;
|
|
144
149
|
if (lost === undefined) return;
|
|
145
150
|
void lost.then((info) => {
|
|
146
|
-
// `reason: "destroyed"` is the shutdown path:
|
|
147
|
-
if (info?.reason === "destroyed") return;
|
|
151
|
+
// `reason: "destroyed"` after the game stopped is the shutdown path: it asked for it.
|
|
152
|
+
if (info?.reason === "destroyed" && destroyedByGame()) return;
|
|
148
153
|
// A real loss always says something — WebGPU requires a reason, and Dawn fills in a message.
|
|
149
154
|
// A resolution carrying neither is a host stub settling its own placeholder promise, which the
|
|
150
155
|
// desktop host does at loop start; reporting that would cry wolf on every launch.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
// Multi-bounce on the contact occlusion (PRD-635). Light that an occluder blocks bounces off other pale surfaces, so a
|
|
2
|
+
// pale surface loses less to its own occlusion than a dark one. Unreal passes the short-range AO through the
|
|
3
|
+
// Jimenez et al. 2016 fit ("Practical Realtime Strategies for Accurate Indirect Occlusion") per colour channel, with
|
|
4
|
+
// the albedo capped at 0.5 (UE 5.8.3: Engine/Shaders/Private/DiffuseIndirectComposite.usf:195,
|
|
5
|
+
// Engine/Shaders/Private/DeferredShadingCommon.ush:1364 and
|
|
6
|
+
// Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenSpaceBentNormal.cpp:56).
|
|
7
|
+
|
|
8
|
+
/** The albedo cap, `r.Lumen.ScreenProbeGather.ShortRangeAO.MaxMultibounceAlbedo`. 0 leaves the occlusion as it is. */
|
|
9
|
+
export const UNREAL_AO_MULTIBOUNCE_ALBEDO = 0.5;
|
|
10
|
+
|
|
11
|
+
/** The fit's coefficients as `[slope, offset]` of the albedo, for the cubic's three terms. */
|
|
12
|
+
export const AO_MULTIBOUNCE_FIT = {
|
|
13
|
+
a: [2.0404, -0.3324],
|
|
14
|
+
b: [-4.7951, 0.6417],
|
|
15
|
+
c: [2.7552, 0.6903],
|
|
16
|
+
} as const;
|
|
17
|
+
|
|
18
|
+
/** The occlusion one colour channel keeps after multi-bounce, for the albedo of that channel. */
|
|
19
|
+
export function aoMultiBounce(
|
|
20
|
+
albedo: number,
|
|
21
|
+
occlusion: number,
|
|
22
|
+
cap = UNREAL_AO_MULTIBOUNCE_ALBEDO,
|
|
23
|
+
): number {
|
|
24
|
+
const base = Math.min(albedo, cap);
|
|
25
|
+
const [a, b, c] = [AO_MULTIBOUNCE_FIT.a, AO_MULTIBOUNCE_FIT.b, AO_MULTIBOUNCE_FIT.c].map(
|
|
26
|
+
([slope, offset]) => slope * base + offset,
|
|
27
|
+
) as [number, number, number];
|
|
28
|
+
return Math.max(occlusion, ((occlusion * a + b) * occlusion + c) * occlusion);
|
|
29
|
+
}
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
// The reach of the contact occlusion (PRD-635). Unreal's short-range AO searches a fixed distance on the screen,
|
|
2
|
+
// not in the world: the reach is twice the screen probe downsample factor, 2 x 16 = 32 px
|
|
3
|
+
// (UE 5.8.3: Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeGather.cpp:2665), and each step lands at
|
|
4
|
+
// the squared step fraction of it (Engine/Shaders/Private/Lumen/LumenScreenSpaceBentNormal.usf:355-358).
|
|
5
|
+
// The owned engine's GTAO takes it as the `reachPx` uniform (post_effects.cpp), in pixels of the occlusion target.
|
|
6
|
+
|
|
7
|
+
/** Unreal's screen reach in pixels at the display height. */
|
|
8
|
+
export const UNREAL_AO_REACH_PX = 32;
|
|
9
|
+
|
|
10
|
+
// Diagnosis: the contact occlusion's knobs by URL name on a calibration scene, every layer (PRD-635); Reference.ts.in
|
|
11
|
+
// keeps its own table, because a --baseline scaffold has no aoReach.ts. ?gtaoR=M (metres)
|
|
12
|
+
// and ?gtaoS=N are the short names of gtaoRadius and gtaoScale; ?gtaoReachPx=N sets the screen reach (Unreal's is 32);
|
|
13
|
+
// ?gtaoIndirectOnly=0 lets the whole frame take the occlusion.
|
|
14
|
+
const GTAO_KNOBS: Record<string, string> = {
|
|
15
|
+
gtaoR: "gtaoRadius",
|
|
16
|
+
gtaoS: "gtaoScale",
|
|
17
|
+
gtaoRadius: "gtaoRadius",
|
|
18
|
+
gtaoReachPx: "gtaoReachPx",
|
|
19
|
+
gtaoSamples: "gtaoSamples",
|
|
20
|
+
gtaoScale: "gtaoScale",
|
|
21
|
+
gtaoDistanceExponent: "gtaoDistanceExponent",
|
|
22
|
+
gtaoDistanceFalloff: "gtaoDistanceFalloff",
|
|
23
|
+
gtaoThickness: "gtaoThickness",
|
|
24
|
+
gtaoDenoiseRadius: "gtaoDenoiseRadius",
|
|
25
|
+
gtaoMultiBounceAlbedo: "gtaoMultiBounceAlbedo",
|
|
26
|
+
gtaoIndirectOnly: "gtaoIndirectOnly",
|
|
27
|
+
};
|
|
28
|
+
|
|
29
|
+
/** The `WorldEnvironment` options that the page URL sets through the knobs above. */
|
|
30
|
+
export function gtaoUrlKnobs(params: URLSearchParams): Record<string, number | boolean> {
|
|
31
|
+
return Object.fromEntries(
|
|
32
|
+
Object.entries(GTAO_KNOBS)
|
|
33
|
+
.filter(([name]) => params.get(name) !== null)
|
|
34
|
+
.map(([name, option]) => [
|
|
35
|
+
option,
|
|
36
|
+
option === "gtaoIndirectOnly" ? params.get(name) !== "0" : Number(params.get(name)),
|
|
37
|
+
]),
|
|
38
|
+
);
|
|
39
|
+
}
|
|
@@ -0,0 +1,264 @@
|
|
|
1
|
+
// Auto exposure with Unreal 5.8.3's metering (owner exception to "never own the look", 2026-10-22): a histogram
|
|
2
|
+
// of log luminance, the darkest and brightest 10% ignored, adapted in log2 space. The settings are
|
|
3
|
+
// `exposure-settings.ts`; every field is an override.
|
|
4
|
+
import { type RenderTarget, Texture, Vector2 } from "three";
|
|
5
|
+
import { float, ivec2, nodeObject, texture, textureLoad, uniform, vec4 } from "three/tsl";
|
|
6
|
+
import {
|
|
7
|
+
type Node,
|
|
8
|
+
type NodeBuilder,
|
|
9
|
+
type NodeFrame,
|
|
10
|
+
NodeMaterial,
|
|
11
|
+
NodeUpdateType,
|
|
12
|
+
QuadMesh,
|
|
13
|
+
RendererUtils,
|
|
14
|
+
TempNode,
|
|
15
|
+
} from "three/webgpu";
|
|
16
|
+
import {
|
|
17
|
+
type IExposureSettings,
|
|
18
|
+
exposureLuminance,
|
|
19
|
+
exposureMeter,
|
|
20
|
+
exposureReductionSizes,
|
|
21
|
+
validateExposureSettings,
|
|
22
|
+
} from "./exposure-settings.js";
|
|
23
|
+
|
|
24
|
+
import { rendererEnvironmentBake, rendererFrameGateSkips } from "../renderer.js";
|
|
25
|
+
import {
|
|
26
|
+
type ColourTexture,
|
|
27
|
+
type Decode,
|
|
28
|
+
type Meter,
|
|
29
|
+
adaptExposure,
|
|
30
|
+
exposureBins,
|
|
31
|
+
exposureTarget,
|
|
32
|
+
exposureTiles,
|
|
33
|
+
histogramExposure,
|
|
34
|
+
histogramTiles,
|
|
35
|
+
reduceExposure,
|
|
36
|
+
} from "./exposure-graph.js";
|
|
37
|
+
import { ExposureReadback } from "./exposure-readback.js";
|
|
38
|
+
|
|
39
|
+
/** Scene-referred exposure changes light, never coverage/compositing alpha. */
|
|
40
|
+
export function applyExposure(colour: Node<"vec4">, exposure: Node<"float">): Node<"vec4"> {
|
|
41
|
+
return vec4(colour.rgb.mul(exposure), colour.a);
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/** Owns scratch targets only. Never draws the world or installs another output transform. */
|
|
45
|
+
export class AutoExposureNode extends TempNode<"float"> {
|
|
46
|
+
static get type(): string {
|
|
47
|
+
return "AutoExposureNode";
|
|
48
|
+
}
|
|
49
|
+
readonly input: ColourTexture;
|
|
50
|
+
readonly settings: Readonly<IExposureSettings>;
|
|
51
|
+
readonly #constant: number;
|
|
52
|
+
readonly #size = new Vector2();
|
|
53
|
+
readonly #sourceSize = uniform(new Vector2(1, 1));
|
|
54
|
+
readonly #reduceSize = uniform(new Vector2(1, 1));
|
|
55
|
+
readonly #blockSize = uniform(new Vector2(1, 1));
|
|
56
|
+
readonly #delta = uniform(0);
|
|
57
|
+
// 0 = history, 1 = seed, 2 = next measured target. The first frame adopts its measured target,
|
|
58
|
+
// as Unreal forces the target on a view's first frame (UE 5.8.3: Engine/Source/Runtime/
|
|
59
|
+
// Renderer/Private/SceneVisibility.cpp:5495, PostProcess/PostProcessEyeAdaptation.cpp:723).
|
|
60
|
+
readonly #resetMode = uniform(2);
|
|
61
|
+
readonly #seed = uniform(0);
|
|
62
|
+
readonly #enabled = uniform(false);
|
|
63
|
+
readonly #bias = uniform(0);
|
|
64
|
+
readonly #quad = new QuadMesh();
|
|
65
|
+
readonly #meterMaterial = new NodeMaterial();
|
|
66
|
+
readonly #reduceMaterial = new NodeMaterial();
|
|
67
|
+
readonly #tilesMaterial = new NodeMaterial();
|
|
68
|
+
readonly #histogramMaterial = new NodeMaterial();
|
|
69
|
+
readonly #adaptMaterial = new NodeMaterial();
|
|
70
|
+
readonly #tilesTarget = exposureTarget();
|
|
71
|
+
readonly #histogramTarget = exposureTarget();
|
|
72
|
+
#readTarget = exposureTarget();
|
|
73
|
+
#writeTarget = exposureTarget();
|
|
74
|
+
#levels: RenderTarget[] = [];
|
|
75
|
+
readonly #reduced = texture(new Texture());
|
|
76
|
+
readonly #blocks = texture(new Texture());
|
|
77
|
+
readonly #previous = texture(this.#readTarget.texture);
|
|
78
|
+
readonly #result = texture(this.#writeTarget.texture);
|
|
79
|
+
#disposed = false;
|
|
80
|
+
readonly #observation: ExposureReadback;
|
|
81
|
+
#gateSkips: number | undefined;
|
|
82
|
+
// Three's runtime accepts undefined on first use, but its declaration requires a state.
|
|
83
|
+
#rendererState: Parameters<typeof RendererUtils.resetRendererState>[1] | undefined;
|
|
84
|
+
|
|
85
|
+
constructor(
|
|
86
|
+
input: ColourTexture,
|
|
87
|
+
settings: IExposureSettings,
|
|
88
|
+
constantExposure: number,
|
|
89
|
+
meter: Meter = (colour, uv) => exposureMeter(colour, uv),
|
|
90
|
+
decode: Decode = (mean) => exposureLuminance(mean),
|
|
91
|
+
) {
|
|
92
|
+
super("float");
|
|
93
|
+
validateExposureSettings(settings);
|
|
94
|
+
if (!Number.isFinite(Math.fround(constantExposure)) || Math.fround(constantExposure) <= 0)
|
|
95
|
+
throw new Error("Exposure constant must be finite and positive.");
|
|
96
|
+
this.input = input;
|
|
97
|
+
this.settings = Object.freeze({ ...settings });
|
|
98
|
+
const policy = this.settings;
|
|
99
|
+
this.#constant = constantExposure;
|
|
100
|
+
this.#seed.value = Math.log2(settings.initialExposure);
|
|
101
|
+
this.#enabled.value = settings.enabled;
|
|
102
|
+
this.#observation = new ExposureReadback(constantExposure, () => this.#enabled.value);
|
|
103
|
+
this.updateBeforeType = NodeUpdateType.FRAME;
|
|
104
|
+
this.#meterMaterial.fragmentNode = reduceExposure(input, this.#sourceSize, meter);
|
|
105
|
+
this.#reduceMaterial.fragmentNode = reduceExposure(this.#reduced, this.#reduceSize);
|
|
106
|
+
this.#tilesTarget.setSize(exposureBins, exposureTiles);
|
|
107
|
+
this.#histogramTarget.setSize(exposureBins, 1);
|
|
108
|
+
this.#tilesMaterial.fragmentNode = histogramTiles(this.#blocks, this.#blockSize, policy);
|
|
109
|
+
this.#histogramMaterial.fragmentNode = histogramExposure(texture(this.#tilesTarget.texture));
|
|
110
|
+
this.#adaptMaterial.fragmentNode = adaptExposure(
|
|
111
|
+
texture(this.#histogramTarget.texture),
|
|
112
|
+
this.#previous,
|
|
113
|
+
this.#resetMode,
|
|
114
|
+
this.#seed,
|
|
115
|
+
this.#delta,
|
|
116
|
+
policy,
|
|
117
|
+
decode,
|
|
118
|
+
this.#bias,
|
|
119
|
+
);
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
override setup(builder: NodeBuilder): Node<"float"> {
|
|
123
|
+
// Force the existing pass dependency even in disabled mode; off never means unmeasured.
|
|
124
|
+
super.setup(builder);
|
|
125
|
+
return this.#enabled.select(
|
|
126
|
+
textureLoad(this.#result, ivec2(0)).r.exp2(),
|
|
127
|
+
float(this.#constant),
|
|
128
|
+
);
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
get exposureNode(): Node<"float"> {
|
|
132
|
+
return nodeObject(this);
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
reset(exposure?: number): void {
|
|
136
|
+
if (this.#disposed) throw new Error("Exposure node is disposed.");
|
|
137
|
+
if (
|
|
138
|
+
exposure !== undefined &&
|
|
139
|
+
(!Number.isFinite(Math.fround(exposure)) || Math.fround(exposure) <= 0)
|
|
140
|
+
)
|
|
141
|
+
throw new Error("Exposure reset must be finite and positive.");
|
|
142
|
+
this.#resetMode.value = exposure === undefined ? 2 : 1;
|
|
143
|
+
if (exposure !== undefined) this.#seed.value = Math.log2(exposure);
|
|
144
|
+
this.#observation.invalidate();
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
setEnabled(enabled: boolean): void {
|
|
148
|
+
if (typeof enabled !== "boolean") throw new Error("Exposure enabled must be boolean.");
|
|
149
|
+
if (this.#disposed) throw new Error("Exposure node is disposed.");
|
|
150
|
+
this.#enabled.value = enabled;
|
|
151
|
+
this.#observation.invalidate();
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/**
|
|
155
|
+
* Exposure compensation in stops over the metered key, live: Unreal's AutoExposureBias
|
|
156
|
+
* (UE 5.8.3: Engine/Source/Runtime/Engine/Classes/Engine/Scene.h:1933), which post-process
|
|
157
|
+
* volumes blend at run time. Unreal applies 2^bias outside the smoothing
|
|
158
|
+
* (Engine/Shaders/Private/PostProcessEyeAdaptation.usf:179); here it moves the goal, so a change
|
|
159
|
+
* adapts at `rateUp`/`rateDown` and the reported exposure includes it.
|
|
160
|
+
*/
|
|
161
|
+
setExposureBias(stops: number): void {
|
|
162
|
+
if (this.#disposed) throw new Error("Exposure node is disposed.");
|
|
163
|
+
if (!Number.isFinite(Math.fround(stops)))
|
|
164
|
+
throw new Error("Exposure bias must be a finite float32 number of stops.");
|
|
165
|
+
this.#bias.value = stops;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
getObservation(): Record<string, unknown> {
|
|
169
|
+
return this.#observation.get();
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
override updateBefore(frame: NodeFrame): undefined {
|
|
173
|
+
if (this.#disposed) throw new Error("Exposure node is disposed.");
|
|
174
|
+
const renderer = frame.renderer;
|
|
175
|
+
if (renderer === null) throw new Error("Exposure requires a renderer.");
|
|
176
|
+
if (!Number.isFinite(frame.deltaTime) || frame.deltaTime < 0 || !Number.isFinite(frame.time))
|
|
177
|
+
throw new Error("Exposure frame time must be finite and nonnegative.");
|
|
178
|
+
// The owned engine draws the held scene under the loading cover while it bakes the
|
|
179
|
+
// environment, and that world is still unlit. Metering it clamps the target to maxStops and the
|
|
180
|
+
// first-frame adoption takes it, so the world opens several stops bright when the cover lifts
|
|
181
|
+
// and then adapts down at the authored rate. A bake draw presents nothing; the first presented
|
|
182
|
+
// frame adopts its measured target, as Unreal forces it on a view's first frame (UE 5.8.3:
|
|
183
|
+
// Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessEyeAdaptation.cpp:723).
|
|
184
|
+
if (rendererEnvironmentBake(renderer)) return;
|
|
185
|
+
renderer.getDrawingBufferSize(this.#size);
|
|
186
|
+
// Level 0 meters 4x4 pixels, level 1 averages 16x16. The histogram gathers level 1.
|
|
187
|
+
const sizes = exposureReductionSizes(this.#size.x, this.#size.y).slice(0, 2);
|
|
188
|
+
this.#sourceSize.value.copy(this.#size);
|
|
189
|
+
// The frame gate declines a draw while two frames are still on the GPU. The drawn frame's
|
|
190
|
+
// deltaTime already spans those declined calls (they never reach this node), so the decline is
|
|
191
|
+
// engine pacing, not a suspension: spend that time, up to maxDelta for each frame the call
|
|
192
|
+
// stands for. A frozen page banks no declined render and stays at one maxDelta.
|
|
193
|
+
const skips = rendererFrameGateSkips(renderer);
|
|
194
|
+
const declined =
|
|
195
|
+
skips !== undefined && this.#gateSkips !== undefined
|
|
196
|
+
? Math.max(0, skips - this.#gateSkips)
|
|
197
|
+
: 0;
|
|
198
|
+
if (skips !== undefined) this.#gateSkips = skips;
|
|
199
|
+
this.#delta.value = Math.min(frame.deltaTime, this.settings.maxDelta * (1 + declined));
|
|
200
|
+
while (this.#levels.length > sizes.length) this.#levels.pop()?.dispose();
|
|
201
|
+
for (const [i, [width, height]] of sizes.entries()) {
|
|
202
|
+
const level = this.#levels[i] ?? exposureTarget();
|
|
203
|
+
this.#levels[i] = level;
|
|
204
|
+
level.setSize(width, height);
|
|
205
|
+
}
|
|
206
|
+
this.#rendererState ??= RendererUtils.saveRendererState(renderer);
|
|
207
|
+
this.#rendererState = RendererUtils.resetRendererState(renderer, this.#rendererState);
|
|
208
|
+
try {
|
|
209
|
+
for (const [i, level] of this.#levels.entries()) {
|
|
210
|
+
const previous = this.#levels[i - 1];
|
|
211
|
+
if (previous !== undefined) {
|
|
212
|
+
this.#reduced.value = previous.texture;
|
|
213
|
+
this.#reduceSize.value.set(previous.width, previous.height);
|
|
214
|
+
}
|
|
215
|
+
this.#quad.material = i === 0 ? this.#meterMaterial : this.#reduceMaterial;
|
|
216
|
+
renderer.setRenderTarget(level);
|
|
217
|
+
this.#quad.render(renderer);
|
|
218
|
+
}
|
|
219
|
+
const final = this.#levels.at(-1);
|
|
220
|
+
if (final === undefined) throw new Error("Exposure reduction is empty.");
|
|
221
|
+
this.#blocks.value = final.texture;
|
|
222
|
+
this.#blockSize.value.set(final.width, final.height);
|
|
223
|
+
this.#quad.material = this.#tilesMaterial;
|
|
224
|
+
renderer.setRenderTarget(this.#tilesTarget);
|
|
225
|
+
this.#quad.render(renderer);
|
|
226
|
+
this.#quad.material = this.#histogramMaterial;
|
|
227
|
+
renderer.setRenderTarget(this.#histogramTarget);
|
|
228
|
+
this.#quad.render(renderer);
|
|
229
|
+
const write = this.#writeTarget;
|
|
230
|
+
this.#previous.value = this.#readTarget.texture;
|
|
231
|
+
this.#quad.material = this.#adaptMaterial;
|
|
232
|
+
renderer.setRenderTarget(write);
|
|
233
|
+
this.#quad.render(renderer);
|
|
234
|
+
this.#result.value = write.texture;
|
|
235
|
+
this.#writeTarget = this.#readTarget;
|
|
236
|
+
this.#readTarget = write;
|
|
237
|
+
this.#resetMode.value = 0;
|
|
238
|
+
this.#observation.report(renderer, write, frame.time, this.settings.reportInterval);
|
|
239
|
+
} finally {
|
|
240
|
+
RendererUtils.restoreRendererState(renderer, this.#rendererState);
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
override dispose(): void {
|
|
245
|
+
if (this.#disposed) return;
|
|
246
|
+
this.#disposed = true;
|
|
247
|
+
this.#observation.dispose();
|
|
248
|
+
for (const level of [
|
|
249
|
+
...this.#levels,
|
|
250
|
+
this.#tilesTarget,
|
|
251
|
+
this.#histogramTarget,
|
|
252
|
+
this.#readTarget,
|
|
253
|
+
this.#writeTarget,
|
|
254
|
+
])
|
|
255
|
+
level.dispose();
|
|
256
|
+
this.#levels = [];
|
|
257
|
+
this.#meterMaterial.dispose();
|
|
258
|
+
this.#reduceMaterial.dispose();
|
|
259
|
+
this.#tilesMaterial.dispose();
|
|
260
|
+
this.#histogramMaterial.dispose();
|
|
261
|
+
this.#adaptMaterial.dispose();
|
|
262
|
+
super.dispose();
|
|
263
|
+
}
|
|
264
|
+
}
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import { ACESFilmicToneMapping, AgXToneMapping, NeutralToneMapping, NoToneMapping } from "three";
|
|
2
|
+
import { installFilmicToneMapping } from "./filmic-tone-mapping.js";
|
|
3
|
+
|
|
4
|
+
/** `filmic` is a fresh Unreal 5.8.3 project's curve and the default; the rest are the named overrides. */
|
|
5
|
+
export type RendererToneMapping = "filmic" | "aces" | "agx" | "neutral" | "none";
|
|
6
|
+
|
|
7
|
+
const THREE_MODE: Record<Exclude<RendererToneMapping, "filmic">, number> = {
|
|
8
|
+
aces: ACESFilmicToneMapping,
|
|
9
|
+
agx: AgXToneMapping,
|
|
10
|
+
neutral: NeutralToneMapping,
|
|
11
|
+
none: NoToneMapping,
|
|
12
|
+
};
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Puts `mode` on a WebGPU renderer. `filmic` registers Unreal's curve as three's custom tone
|
|
16
|
+
* mapping; a renderer without a node library cannot run it, keeps ACES and says so
|
|
17
|
+
* (`TN_TONEMAP`). An unknown mode throws rather than quietly becoming the default.
|
|
18
|
+
*/
|
|
19
|
+
export function applyRendererToneMapping(
|
|
20
|
+
raw: unknown,
|
|
21
|
+
mode: RendererToneMapping,
|
|
22
|
+
report: (line: string) => void,
|
|
23
|
+
): number {
|
|
24
|
+
const target = raw as { toneMapping?: number };
|
|
25
|
+
if (mode !== "filmic") {
|
|
26
|
+
const three = THREE_MODE[mode];
|
|
27
|
+
if (three === undefined)
|
|
28
|
+
throw new Error(
|
|
29
|
+
`Unknown toneMapping '${String(mode)}'. Use one of: filmic, ${Object.keys(THREE_MODE).join(", ")}.`,
|
|
30
|
+
);
|
|
31
|
+
target.toneMapping = three;
|
|
32
|
+
return three;
|
|
33
|
+
}
|
|
34
|
+
const installed = installFilmicToneMapping(raw);
|
|
35
|
+
if (installed !== undefined) {
|
|
36
|
+
target.toneMapping = installed;
|
|
37
|
+
return installed;
|
|
38
|
+
}
|
|
39
|
+
report(
|
|
40
|
+
`TN_TONEMAP ${JSON.stringify({ requested: "filmic", applied: "aces", reason: "renderer:no-node-library" })}`,
|
|
41
|
+
);
|
|
42
|
+
target.toneMapping = ACESFilmicToneMapping;
|
|
43
|
+
return ACESFilmicToneMapping;
|
|
44
|
+
}
|