@threenative/core 0.3.13 → 0.3.16

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.
Files changed (60) hide show
  1. package/capabilities.json +1008 -83
  2. package/dist/{chunk-4SRAQFTU.js → chunk-2GPHICV6.js} +1 -1
  3. package/dist/{chunk-EEABDLUC.js → chunk-5C4TCWI3.js} +2 -2
  4. package/dist/{chunk-DIPIJICH.js → chunk-FQURMC2F.js} +122 -18
  5. package/dist/{chunk-EFWZWLPY.js → chunk-OMGIYWW7.js} +400 -13
  6. package/dist/{chunk-SV4QVUTQ.js → chunk-QAQHYOWY.js} +1 -1
  7. package/dist/{chunk-GYUZJQ7U.js → chunk-VQRPEOKY.js} +4 -1
  8. package/dist/hot.js +10 -2
  9. package/dist/index.d.ts +608 -16
  10. package/dist/index.js +2037 -633
  11. package/dist/{model-lod-DPTzeCcD.d.ts → model-lod-B921F6kQ.d.ts} +0 -10
  12. package/dist/playtest.js +3 -3
  13. package/dist/{quality-BYqKGAwo.d.ts → quality-BADStsTn.d.ts} +2 -2
  14. package/dist/render-environment.d.ts +1 -1
  15. package/dist/ui-layer.js +2 -2
  16. package/dist/worker.js +2 -2
  17. package/dist/world.d.ts +14 -4
  18. package/dist/world.js +179 -36
  19. package/mcp/animation-server.mjs +1 -1
  20. package/mcp/engine-server.mjs +44 -17
  21. package/mcp/servers.mjs +4 -4
  22. package/package.json +6 -6
  23. package/patches/three@0.187.0-prd269-upgrade.patch +126 -2
  24. package/patches/three@0.187.0.patch +108 -21
  25. package/scripts/ensure-mcp.mjs +6 -1
  26. package/src/clustered-batch.ts +146 -3
  27. package/src/clustered-mesh.ts +548 -20
  28. package/src/debug.ts +16 -0
  29. package/src/displaced-surface.ts +428 -0
  30. package/src/engine-hooks.ts +29 -0
  31. package/src/frame-budget.ts +16 -0
  32. package/src/generated/console-markers.ts +1 -0
  33. package/src/grass-field.ts +628 -0
  34. package/src/grounding.ts +19 -10
  35. package/src/hot.ts +18 -2
  36. package/src/index.ts +112 -0
  37. package/src/instanced-batch-lod.ts +54 -0
  38. package/src/model-lod.ts +77 -1
  39. package/src/pose-measure.ts +27 -2
  40. package/src/render/material-key.ts +21 -1
  41. package/src/render/screen-probe-gather.ts +303 -0
  42. package/src/render/short-range-ao.ts +274 -0
  43. package/src/render/world-impostor-surface.ts +98 -3
  44. package/src/render-camera-cull.ts +9 -3
  45. package/src/renderer.ts +26 -4
  46. package/src/scatter-field.ts +497 -0
  47. package/src/startup-offscreen-bytes.ts +11 -5
  48. package/src/state.ts +16 -3
  49. package/src/static-transform.ts +109 -6
  50. package/src/tile-ring.ts +294 -0
  51. package/src/version.ts +1 -1
  52. package/src/warmup.ts +15 -2
  53. package/src/world-cell-batches.ts +4 -0
  54. package/src/world-cell-data.ts +7 -0
  55. package/src/world-cell-models.ts +36 -8
  56. package/src/world-cell-render-gpu-dress.ts +4 -2
  57. package/src/world-cell-render-util.ts +2 -2
  58. package/src/world-cells.ts +1 -1
  59. package/src/world-river-ribbon.ts +13 -22
  60. package/src/world-water-bodies.ts +113 -3
@@ -0,0 +1,303 @@
1
+ import { ssgi } from "three/addons/tsl/display/SSGINode.js";
2
+ import { float, max, normalize, uniform, vec3 } from "three/tsl";
3
+ import type { Node } from "three/webgpu";
4
+ import type { TracedReflections } from "./traced-reflections.js";
5
+
6
+ /** The marker a gather prints once, with the grid it placed and the tier below it reads. */
7
+ export const SCREEN_PROBE_GATHER_MARKER = "TN_SCREEN_PROBE_GATHER";
8
+
9
+ /** The gather's pass groups, in the order they draw (the engine's own, `three-native/src/addons/screen-space.ts`). */
10
+ export const SCREEN_PROBE_PASSES = ["trace", "filter", "gather"] as const;
11
+ export type ScreenProbePass = (typeof SCREEN_PROBE_PASSES)[number];
12
+
13
+ /** Unreal's real-time Epic grid: one probe per 16 x 16 pixels (`r.Lumen.ScreenProbeGather.DownsampleFactor`). */
14
+ const DEFAULT_DOWNSAMPLE = 16;
15
+ /** Unreal's 8 x 8 octahedron at Epic (`r.Lumen.ScreenProbeGather.TracingOctahedronResolution`). */
16
+ const DEFAULT_OCTAHEDRON = 8;
17
+ /**
18
+ * How far a ray that leaves the screen walks the packed scene before it reads the radiance cache, in metres: the cache's
19
+ * own cell. A longer walk reads cells the ray cannot see, which is the per-pixel look this gather replaces.
20
+ */
21
+ const DEFAULT_CELL_SIZE = 1;
22
+ /** A ray starts this far off its surface, and this much more per metre of depth, so it cannot hit the pixel it left. */
23
+ const START_OFFSET = 0.01;
24
+ const START_OFFSET_PER_METRE = 0.004;
25
+
26
+ /** The camera the scene pass draws with: a projection to map the screen, and a world matrix to leave it. */
27
+ export interface IScreenProbeCamera {
28
+ readonly near: number;
29
+ readonly projectionMatrix: { readonly elements: readonly number[] };
30
+ readonly matrixWorld: { readonly elements: readonly number[] };
31
+ }
32
+
33
+ export interface IScreenProbeGatherOptions {
34
+ /** The camera the scene pass draws with. */
35
+ readonly camera: IScreenProbeCamera;
36
+ /** The drawing buffer, in pixels. It fixes the probe grid; a resize needs a new gather. */
37
+ readonly viewport: { readonly width: number; readonly height: number };
38
+ /** Pixels between probes: Unreal's `DownsampleFactor`, 16 at Epic and 32 at High. */
39
+ readonly downsampleFactor?: number;
40
+ /** Rays on a side of each probe's octahedron: Unreal's `TracingOctahedronResolution`, 8 at Epic. */
41
+ readonly tracingOctahedronResolution?: number;
42
+ /**
43
+ * The tier below the screen along a ray that hits, in view space, exactly as the engine asks it: the light the radiance
44
+ * cache would have returned along that ray, which the gather subtracts so the two tiers never add the same light twice.
45
+ * A game with its own tier passes it here; without either tier a hit keeps the frame's own light, as three's SSGINode.
46
+ */
47
+ readonly fallback?: (
48
+ position: Node<"vec3">,
49
+ direction: Node<"vec3">,
50
+ normal: Node<"vec3">,
51
+ ) => Node<"vec3">;
52
+ /**
53
+ * The radiance cache in world space, in the frame's units: the light arriving along a direction at a point. It answers
54
+ * the tier past the screen, where a ray that leaves it reads the cache. With no `fallback`, it also answers the tier
55
+ * below along each ray. Unreal reads its cache per ray direction the same way (UE 5.8.3:
56
+ * Engine/Shaders/Private/Lumen/LumenScreenProbeTracing.usf, SampleRadianceCacheAndApply).
57
+ */
58
+ readonly radiance?: (position: Node<"vec3">, direction: Node<"vec3">) => Node<"vec3">;
59
+ /**
60
+ * The packed scene a ray that leaves the screen walks before it reads `radiance`: Unreal continues the ray in the
61
+ * distance field up to the cache's coverage and reads the cache where it ended, so a miss is a direction's radiance
62
+ * and not the pixel's mean over the hemisphere. Without it there is no walk and no miss tier.
63
+ */
64
+ readonly trace?: Pick<TracedReflections, "trace">;
65
+ /** Metres a ray that left the screen walks the packed scene before it reads `radiance`. 1: the cache's cell. */
66
+ readonly cacheCellSize?: number;
67
+ /**
68
+ * Diagnosis: label only this pass group as the `SSGI` GPU stage, so `info.engine.gpuStages.SSGI` times it alone.
69
+ * Omit to label every pass; `null` labels none (another stage is being timed).
70
+ */
71
+ readonly timedPass?: ScreenProbePass | null;
72
+ /** False silences the `TN_SCREEN_PROBE_GATHER` line, not the report. */
73
+ readonly marker?: boolean;
74
+ }
75
+
76
+ /** What the gather placed, printed once and readable by a tool: Unreal's grid, in pixels and probes. */
77
+ export interface IScreenProbeGatherReport {
78
+ readonly downsampleFactor: number;
79
+ readonly tracingOctahedronResolution: number;
80
+ readonly viewportWidth: number;
81
+ readonly viewportHeight: number;
82
+ /** Probes over the whole grid: one per tile, the last row and column rounded up. */
83
+ readonly probes: number;
84
+ readonly raysPerProbe: number;
85
+ /** Whether a ray that leaves the screen walks the scene, or reads the cache at its cell with none. */
86
+ readonly worldTrace: boolean;
87
+ }
88
+
89
+ /**
90
+ * The engine's gather node: three's declaration of `ssgi` carries neither the probes option nor the node's own readers, so
91
+ * the class holds the engine's shape once here instead of casting at every use.
92
+ */
93
+ type ScreenProbeNode = Node<"vec4"> & {
94
+ getGINode(): Node<"vec4">;
95
+ getAONode(): Node<"vec4">;
96
+ };
97
+
98
+ /** The engine's call shape: the camera and the tiers in an options object, where three names a camera inline. */
99
+ type ScreenProbeSignature = (
100
+ color: Node,
101
+ depth: Node,
102
+ normal: Node,
103
+ options: object,
104
+ ) => ScreenProbeNode;
105
+
106
+ const gatherScreenProbes = ssgi as unknown as ScreenProbeSignature; // quality-allow: the engine extends three's ssgi with probes and the tiers below the screen, which its declaration does not carry
107
+
108
+ /** The world matrix of the scene camera as uniforms refreshed every render, and the view -> world map they build. */
109
+ function defineWorldMapping(camera: IScreenProbeCamera) {
110
+ const live = (index: number): Node<"float"> =>
111
+ uniform(camera.matrixWorld.elements[index] ?? 0).onRenderUpdate(
112
+ () => camera.matrixWorld.elements[index] ?? 0,
113
+ );
114
+ const column = (first: number): Node<"vec3"> =>
115
+ vec3(live(first), live(first + 1), live(first + 2));
116
+ const [right, up, back, at] = [column(0), column(4), column(8), column(12)];
117
+ return {
118
+ /** A view-space vector in world space: the camera's rotation, which is all a direction needs. */
119
+ direction: (value: Node<"vec3">): Node<"vec3"> =>
120
+ right.mul(value.x).add(up.mul(value.y)).add(back.mul(value.z)),
121
+ /** A view-space point in world space. */
122
+ position: (value: Node<"vec3">): Node<"vec3"> =>
123
+ right.mul(value.x).add(up.mul(value.y)).add(back.mul(value.z)).add(at),
124
+ };
125
+ }
126
+
127
+ /**
128
+ * Lumen's Screen Probe Gather (PRD-640): one probe per `downsampleFactor` pixel tile traces an octahedron of rays
129
+ * instead of every pixel tracing its own, the probes' radiance is filtered into an irradiance octahedron each, and a
130
+ * pixel blends the four nearest probes it can see. The engine owns the three passes
131
+ * (`three-native/src/addons/screen-space.ts`); this composes the tier below them, which every game repeats:
132
+ *
133
+ * a ray that hits on screen returns the lit frame minus the cache along it (`fallback`), so the two never add the
134
+ * same light twice;
135
+ * a ray that leaves the screen continues through the packed scene (`trace`) up to `cacheCellSize` and reads the
136
+ * radiance cache where it ended (`miss`), so the light it brings is that direction's, not the pixel's mean.
137
+ *
138
+ * The result is the incident radiance the traces add to what the game's composite already holds, E / pi units: multiply
139
+ * it by the receiver's albedo (`mrt({ diffuseColor })`) and add it after the scene pass.
140
+ *
141
+ * The owned engine only: on `engine: "threejs"` the upstream node takes the camera as its fourth argument and has no
142
+ * probes, which `gather()` refuses rather than drawing a frame with no bounce light.
143
+ */
144
+ export class ScreenProbeGather {
145
+ readonly report: IScreenProbeGatherReport;
146
+ readonly downsampleFactor: number;
147
+ readonly tracingOctahedronResolution: number;
148
+ readonly cacheCellSize: number;
149
+ readonly #camera: IScreenProbeCamera;
150
+ readonly #viewport: { readonly width: number; readonly height: number };
151
+ readonly #fallback: IScreenProbeGatherOptions["fallback"];
152
+ readonly #radiance: IScreenProbeGatherOptions["radiance"];
153
+ readonly #trace: IScreenProbeGatherOptions["trace"];
154
+ readonly #timedPass: ScreenProbePass | null | undefined;
155
+ #node: ScreenProbeNode | undefined;
156
+
157
+ constructor(options: IScreenProbeGatherOptions) {
158
+ const downsampleFactor = options.downsampleFactor ?? DEFAULT_DOWNSAMPLE;
159
+ const tracingOctahedronResolution = options.tracingOctahedronResolution ?? DEFAULT_OCTAHEDRON;
160
+ const cacheCellSize = options.cacheCellSize ?? DEFAULT_CELL_SIZE;
161
+ if (!(Number.isInteger(downsampleFactor) && downsampleFactor >= 1))
162
+ throw new RangeError(
163
+ `TN_SCREEN_PROBE_GATHER: downsampleFactor ${downsampleFactor} must be a whole number of pixels, at least 1`,
164
+ );
165
+ if (!(Number.isInteger(tracingOctahedronResolution) && tracingOctahedronResolution >= 2))
166
+ throw new RangeError(
167
+ `TN_SCREEN_PROBE_GATHER: tracingOctahedronResolution ${tracingOctahedronResolution} must be a whole number of rays, at least 2`,
168
+ );
169
+ if (!(options.viewport.width > 0 && options.viewport.height > 0))
170
+ throw new RangeError(
171
+ `TN_SCREEN_PROBE_GATHER: viewport ${options.viewport.width}x${options.viewport.height} must be the drawing buffer`,
172
+ );
173
+ if (
174
+ options.timedPass != null &&
175
+ !SCREEN_PROBE_PASSES.includes(options.timedPass as ScreenProbePass)
176
+ )
177
+ throw new TypeError(
178
+ `TN_SCREEN_PROBE_GATHER: timedPass ${String(options.timedPass)} is not one of ${SCREEN_PROBE_PASSES.join(", ")}`,
179
+ );
180
+ if (options.trace !== undefined && !(cacheCellSize > 0))
181
+ throw new RangeError(
182
+ `TN_SCREEN_PROBE_GATHER: cacheCellSize ${cacheCellSize} must be metres beyond 0`,
183
+ );
184
+ if (options.trace !== undefined && options.radiance === undefined)
185
+ throw new TypeError(
186
+ "TN_SCREEN_PROBE_GATHER_RADIANCE: a ray that leaves the screen reads options.radiance, and none was given",
187
+ );
188
+ if (
189
+ (options.radiance !== undefined || options.trace !== undefined) &&
190
+ options.camera?.matrixWorld === undefined
191
+ )
192
+ throw new TypeError(
193
+ "TN_SCREEN_PROBE_GATHER_CAMERA: a gather that leaves the screen needs the scene camera's matrixWorld",
194
+ );
195
+ this.downsampleFactor = downsampleFactor;
196
+ this.tracingOctahedronResolution = tracingOctahedronResolution;
197
+ this.cacheCellSize = cacheCellSize;
198
+ this.#camera = options.camera;
199
+ this.#viewport = options.viewport;
200
+ this.#fallback = options.fallback;
201
+ this.#radiance = options.radiance;
202
+ this.#trace = options.trace;
203
+ this.#timedPass = options.timedPass;
204
+ const tilesX = Math.ceil(options.viewport.width / downsampleFactor);
205
+ const tilesY = Math.ceil(options.viewport.height / downsampleFactor);
206
+ this.report = {
207
+ downsampleFactor,
208
+ tracingOctahedronResolution,
209
+ viewportWidth: options.viewport.width,
210
+ viewportHeight: options.viewport.height,
211
+ probes: tilesX * tilesY,
212
+ raysPerProbe: tracingOctahedronResolution * tracingOctahedronResolution,
213
+ worldTrace: options.trace !== undefined,
214
+ };
215
+ if (options.marker !== false)
216
+ console.info(`${SCREEN_PROBE_GATHER_MARKER} ${JSON.stringify(this.report)}`);
217
+ }
218
+
219
+ /**
220
+ * The gather itself: `ssgi(base, depth, normal, { camera, probes, fallback, miss })`, with `base` the lit frame the
221
+ * traces read and the depth and normal of the scene pass. `getGINode()` and `getAONode()` read what it built.
222
+ */
223
+ gather(colorNode: Node, depthNode: Node, normalNode: Node): Node<"vec4"> {
224
+ const { fallback, miss } = this.#tiers();
225
+ const node = gatherScreenProbes(colorNode, depthNode, normalNode, {
226
+ camera: this.#camera,
227
+ probes: {
228
+ downsampleFactor: this.downsampleFactor,
229
+ tracingOctahedronResolution: this.tracingOctahedronResolution,
230
+ viewport: this.#viewport,
231
+ ...(this.#timedPass === undefined ? {} : { timedPass: this.#timedPass }),
232
+ },
233
+ ...(fallback === undefined ? {} : { fallback }),
234
+ ...(miss === undefined ? {} : { miss }),
235
+ });
236
+ this.#node = node;
237
+ return node;
238
+ }
239
+
240
+ /** The gather's radiance, E / pi: multiply by the receiver's albedo and add it after the scene pass. */
241
+ getGINode(): Node<"vec4"> {
242
+ return this.#built().getGINode();
243
+ }
244
+
245
+ /** The share of the gather's rays that found nothing, as the occlusion the caller applies to the lit frame. */
246
+ getAONode(): Node<"vec4"> {
247
+ return this.#built().getAONode();
248
+ }
249
+
250
+ #built(): ScreenProbeNode {
251
+ if (this.#node === undefined)
252
+ throw new Error("TN_SCREEN_PROBE_GATHER_UNBUILT: call gather() before reading its nodes");
253
+ return this.#node;
254
+ }
255
+
256
+ /**
257
+ * The two tiers below the screen. Both are asked in view space, because the screen pass works there: the mapping to
258
+ * the world is this class's, so a game answers one question in world space (what light arrives along this direction
259
+ * at this point) and not two in two spaces.
260
+ */
261
+ #tiers(): {
262
+ fallback?: (
263
+ position: Node<"vec3">,
264
+ direction: Node<"vec3">,
265
+ normal: Node<"vec3">,
266
+ ) => Node<"vec3">;
267
+ miss?: (position: Node<"vec3">, direction: Node<"vec3">, normal: Node<"vec3">) => Node<"vec3">;
268
+ } {
269
+ const radiance = this.#radiance;
270
+ const trace = this.#trace;
271
+ const given = this.#fallback;
272
+ if (radiance === undefined) return given === undefined ? {} : { fallback: given };
273
+ const mapping = defineWorldMapping(this.#camera);
274
+ const cellSize = this.cacheCellSize;
275
+ // A game that already maps its own tier hands it over untouched; one with a world-space cache gets it here.
276
+ const fallback =
277
+ given ??
278
+ ((position: Node<"vec3">, direction: Node<"vec3">) =>
279
+ radiance(mapping.position(position), normalize(mapping.direction(direction))));
280
+ // Without a packed scene there is no walk, so a ray that leaves the screen adds nothing: the pixel keeps the mean.
281
+ if (trace === undefined) return { fallback };
282
+ return {
283
+ // The tier below the screen along a ray that hit: what the cache holds there, which the composite already adds.
284
+ fallback,
285
+ // The tier past the screen along a ray that missed: the distance field continued to the cache's cell, then the
286
+ // cache read where the ray ended, less the light this pixel already receives (the composite adds that too).
287
+ miss: (position, direction, normal) => {
288
+ const at = mapping.position(position);
289
+ const towards = normalize(mapping.direction(direction));
290
+ const facing = normalize(mapping.direction(normal));
291
+ const offset = max(float(START_OFFSET), position.z.abs().mul(START_OFFSET_PER_METRE));
292
+ const reached = at.add(towards.mul(cellSize));
293
+ const found = trace.trace({
294
+ origin: at.add(facing.mul(offset)),
295
+ direction: towards,
296
+ far: cellSize,
297
+ });
298
+ const end = found.hit.greaterThan(0).select(found.position, reached);
299
+ return radiance(end, towards).sub(radiance(at, facing));
300
+ },
301
+ };
302
+ }
303
+ }
@@ -0,0 +1,274 @@
1
+ import {
2
+ Break,
3
+ Fn,
4
+ If,
5
+ Loop,
6
+ clamp,
7
+ cos,
8
+ float,
9
+ floor,
10
+ int,
11
+ length,
12
+ max,
13
+ normalize,
14
+ pow,
15
+ rtt,
16
+ sin,
17
+ uniform,
18
+ uv,
19
+ vec2,
20
+ vec3,
21
+ vec4,
22
+ } from "three/tsl";
23
+ import type { Node, TextureNode } from "three/webgpu";
24
+
25
+ /** The marker the pass prints once, with the sweep it ran. */
26
+ export const SHORT_RANGE_AO_MARKER = "TN_SHORT_RANGE_AO";
27
+
28
+ /** Half-hemisphere sweeps around the view normal (Unreal's `ShortRangeAO.HorizonSearchSliceCount`, 2 at Epic). */
29
+ const SLICE_COUNT = 2;
30
+ /** Samples per sweep, at the squared step fraction (Unreal's `HorizonSearchStepCount`, 3 at Epic). */
31
+ const STEP_COUNT = 3;
32
+ /**
33
+ * Metres the search would cover in the world at the display height, as Unreal states it: twice the screen probe
34
+ * downsample factor, 2 x 16 px (`r.Lumen.ScreenProbeGather.ShortRangeAO`, LumenScreenProbeGather.cpp:2665).
35
+ */
36
+ const REACH_PX = 32;
37
+ /** The most sweeps the loops may run, so a driver cannot unroll them into a program too large to compile. */
38
+ const MAX_SLICES = 8;
39
+ const MAX_STEPS = 8;
40
+ /** A sample this close to the pixel says nothing about a horizon. */
41
+ const MIN_DISTANCE = 1e-5;
42
+ const HALF_FLOAT_TYPE = 1016;
43
+
44
+ /** The scene camera the pass reads: a projection to map the screen and a depth to come back to view space. */
45
+ export interface IShortRangeAOCamera {
46
+ readonly projectionMatrix: { readonly elements: readonly number[] };
47
+ }
48
+
49
+ export interface IShortRangeAOOptions {
50
+ /** The camera the scene pass drew with: a post quad's own camera nodes are the quad's, not the scene's. */
51
+ readonly camera: IShortRangeAOCamera;
52
+ /** The drawing buffer, in pixels. The search's reach is a distance on the screen, so it needs the size. */
53
+ readonly viewport: { readonly width: number; readonly height: number };
54
+ /** Sweeps around the view normal (`horizonSearchSliceCount`): 2, Unreal's Epic setting. */
55
+ readonly horizonSearchSliceCount?: number;
56
+ /** Samples per sweep (`horizonSearchStepCount`): 3, Unreal's Epic setting. */
57
+ readonly horizonSearchStepCount?: number;
58
+ /** The reach in pixels of the drawing buffer: 32, twice Unreal's 16 px screen probe downsample. */
59
+ readonly reachPx?: number;
60
+ /**
61
+ * Whether the pass also answers the bent normal (`.rgb`), Unreal's Epic-only setting. The occlusion alone is
62
+ * `.a`, so a composite that does not read a bent normal pays one channel, not a second pass.
63
+ */
64
+ readonly bentNormal?: boolean;
65
+ /** How strongly the occlusion applies: 1 keeps the horizon's own answer. */
66
+ readonly intensity?: number;
67
+ /** False silences the `TN_SHORT_RANGE_AO` line, not the report. */
68
+ readonly marker?: boolean;
69
+ }
70
+
71
+ /** What the pass swept, printed once and readable by a tool. */
72
+ export interface IShortRangeAOReport {
73
+ readonly horizonSearchSliceCount: number;
74
+ readonly horizonSearchStepCount: number;
75
+ readonly reachPx: number;
76
+ /** Samples each pixel's normal hemisphere took: slices x steps. */
77
+ readonly samplesPerPixel: number;
78
+ readonly bentNormal: boolean;
79
+ }
80
+
81
+ /**
82
+ * Unreal's Short Range AO (PRD-640 Phase 3): a horizon search of `horizonSearchSliceCount` sweeps around the view
83
+ * normal, `horizonSearchStepCount` samples each at the squared fraction of a screen-space reach, at full resolution,
84
+ * with a bent normal at Epic. It is the AO that runs *with* dynamic GI: the contact detail Lumen keeps after the screen
85
+ * probe gather has already answered the wide occlusion, so the frame is not darkened twice by two wide treatments
86
+ * (UE 5.8.3: Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenSpaceBentNormal.cpp and
87
+ * Engine/Shaders/Private/Lumen/LumenScreenSpaceBentNormal.usf). GTAO through `ambientOcclusion` stays the AO of the
88
+ * tiers without dynamic GI.
89
+ *
90
+ * The result is one texture: `rgb` the bent normal in view space (the space the normal target and the GI gather work
91
+ * in), `a` the share of the hemisphere left open, which multiplies *indirect* light only — direct light and emission
92
+ * keep their own occlusion, as Unreal's `DiffuseIndirectComposite` applies it. Multi-bounce and the albedo cap belong
93
+ * to the game's composite, because they decide how a surface looks.
94
+ */
95
+ export class ShortRangeAO {
96
+ readonly report: IShortRangeAOReport;
97
+ readonly horizonSearchSliceCount: number;
98
+ readonly horizonSearchStepCount: number;
99
+ readonly reachPx: number;
100
+ readonly bentNormal: boolean;
101
+ readonly intensity: number;
102
+ readonly #camera: IShortRangeAOCamera;
103
+ readonly #viewport: { readonly width: number; readonly height: number };
104
+
105
+ constructor(options: IShortRangeAOOptions) {
106
+ const horizonSearchSliceCount = options.horizonSearchSliceCount ?? SLICE_COUNT;
107
+ const horizonSearchStepCount = options.horizonSearchStepCount ?? STEP_COUNT;
108
+ const reachPx = options.reachPx ?? REACH_PX;
109
+ const intensity = options.intensity ?? 1;
110
+ if (!(Number.isInteger(horizonSearchSliceCount) && horizonSearchSliceCount >= 1))
111
+ throw new RangeError(
112
+ `TN_SHORT_RANGE_AO: horizonSearchSliceCount ${horizonSearchSliceCount} must be a whole number of sweeps, at least 1`,
113
+ );
114
+ if (!(Number.isInteger(horizonSearchStepCount) && horizonSearchStepCount >= 1))
115
+ throw new RangeError(
116
+ `TN_SHORT_RANGE_AO: horizonSearchStepCount ${horizonSearchStepCount} must be a whole number of samples, at least 1`,
117
+ );
118
+ if (horizonSearchSliceCount > MAX_SLICES || horizonSearchStepCount > MAX_STEPS)
119
+ throw new RangeError(
120
+ `TN_SHORT_RANGE_AO: a sweep of ${horizonSearchSliceCount} x ${horizonSearchStepCount} is more than the pass compiles (${MAX_SLICES} x ${MAX_STEPS})`,
121
+ );
122
+ if (!(reachPx > 0))
123
+ throw new RangeError(
124
+ `TN_SHORT_RANGE_AO: reachPx ${reachPx} must be pixels of the drawing buffer beyond 0`,
125
+ );
126
+ if (!(intensity > 0))
127
+ throw new RangeError(`TN_SHORT_RANGE_AO: intensity ${intensity} must be beyond 0`);
128
+ if (!(options.viewport.width > 0 && options.viewport.height > 0))
129
+ throw new RangeError(
130
+ `TN_SHORT_RANGE_AO: viewport ${options.viewport.width}x${options.viewport.height} must be the drawing buffer`,
131
+ );
132
+ if (options.camera?.projectionMatrix === undefined)
133
+ throw new TypeError(
134
+ "TN_SHORT_RANGE_AO_CAMERA: the pass needs the scene camera's projectionMatrix",
135
+ );
136
+ this.horizonSearchSliceCount = horizonSearchSliceCount;
137
+ this.horizonSearchStepCount = horizonSearchStepCount;
138
+ this.reachPx = reachPx;
139
+ this.bentNormal = options.bentNormal ?? true;
140
+ this.intensity = intensity;
141
+ this.#camera = options.camera;
142
+ this.#viewport = options.viewport;
143
+ this.report = {
144
+ horizonSearchSliceCount,
145
+ horizonSearchStepCount,
146
+ reachPx,
147
+ samplesPerPixel: horizonSearchSliceCount * horizonSearchStepCount,
148
+ bentNormal: this.bentNormal,
149
+ };
150
+ if (options.marker !== false)
151
+ console.info(`${SHORT_RANGE_AO_MARKER} ${JSON.stringify(this.report)}`);
152
+ }
153
+
154
+ /**
155
+ * The occlusion of one frame: `rgb` the bent normal in view space, `a` the share of the hemisphere left open. `depth`
156
+ * is the scene pass's depth target and `normal` its view-space normal target.
157
+ */
158
+ occlusion(depthNode: TextureNode, normalNode: TextureNode): Node<"vec4"> {
159
+ const element = (index: number): Node<"float"> =>
160
+ uniform(this.#camera.projectionMatrix.elements[index] ?? 0).onRenderUpdate(
161
+ () => this.#camera.projectionMatrix.elements[index] ?? 0,
162
+ ) as Node<"float">;
163
+ const [p0, p5, p8, p9, p10, p14] = [0, 5, 8, 9, 10, 14].map(element) as [
164
+ Node<"float">,
165
+ Node<"float">,
166
+ Node<"float">,
167
+ Node<"float">,
168
+ Node<"float">,
169
+ Node<"float">,
170
+ ];
171
+ // Depth is (A z + B) / -z, so z = -B / (depth + A): the same mapping the gather and the reflections use.
172
+ const viewPosition = (coordinate: Node<"vec2">, depth: Node<"float">): Node<"vec3"> => {
173
+ const z = p14.negate().div(depth.add(p10));
174
+ const ndc = vec2(coordinate.x.mul(2).sub(1), float(1).sub(coordinate.y).mul(2).sub(1));
175
+ return vec3(z.negate().mul(ndc.x.add(p8)).div(p0), z.negate().mul(ndc.y.add(p9)).div(p5), z);
176
+ };
177
+ const slices = uniform(this.horizonSearchSliceCount);
178
+ const steps = uniform(this.horizonSearchStepCount);
179
+ // The reach is a distance on the screen, so one step is that many pixels of the drawing buffer, in uv.
180
+ const stepOffset = vec2(
181
+ this.reachPx / this.#viewport.width,
182
+ this.reachPx / this.#viewport.height,
183
+ );
184
+ const intensity = uniform(this.intensity);
185
+ const bent = this.bentNormal;
186
+
187
+ const graph = Fn(() => {
188
+ const coordinate = uv();
189
+ const result = vec4(0, 0, 1, 1).toVar();
190
+ const centreDepth = depthNode.sample(coordinate).r;
191
+ const centreNormal = normalNode.sample(coordinate).xyz;
192
+ // The sky and a draw the normal pass skips (an unlit material) take no occlusion.
193
+ If(centreDepth.lessThan(1).and(centreNormal.dot(centreNormal).greaterThan(0.25)), () => {
194
+ const position = viewPosition(coordinate, centreDepth);
195
+ const normal = normalize(centreNormal);
196
+ // A frame around the normal, so a sweep turns in the surface's tangent plane.
197
+ const helper = normal.y
198
+ .abs()
199
+ .lessThan(0.99)
200
+ .select(vec3(0, 1, 0), vec3(1, 0, 0));
201
+ const tangent = normalize(helper.cross(normal));
202
+ const bitangent = normal.cross(tangent);
203
+ // Each pixel turns its sweeps by its own angle (interleaved gradient noise on a fixed lattice of the uv), so
204
+ // two sweeps do not leave the pattern of the sweep set on the frame.
205
+ const cell = coordinate.mul(2048).floor();
206
+ const noise = cell.x
207
+ .mul(0.06711056)
208
+ .add(cell.y.mul(0.00583715))
209
+ .fract()
210
+ .mul(52.9829189)
211
+ .fract();
212
+ const open = float(0).toVar();
213
+ const direction = vec3(0, 0, 1).toVar();
214
+ const bentNormal = vec3(0, 0, 0).toVar();
215
+ Loop(
216
+ { start: int(0), end: int(MAX_SLICES), type: "int", condition: "<" },
217
+ ({ i: slice }) => {
218
+ If(float(slice).greaterThanEqual(slices), () => {
219
+ Break();
220
+ });
221
+ const angle = float(slice).add(noise).div(slices).mul(Math.PI);
222
+ direction.assign(normalize(tangent.mul(cos(angle)).add(bitangent.mul(sin(angle)))));
223
+ // The horizon starts at the surface itself: nothing beyond it is above the plane.
224
+ const horizon = float(-1).toVar();
225
+ Loop(
226
+ { start: int(0), end: int(MAX_STEPS), type: "int", condition: "<" },
227
+ ({ i: step }) => {
228
+ If(float(step).greaterThanEqual(steps), () => {
229
+ Break();
230
+ });
231
+ // Unreal lands each step at the squared step fraction of the reach (LumenScreenSpaceBentNormal.usf:355).
232
+ const fraction = float(step).add(1).div(steps);
233
+ const sampleCoordinate = coordinate.add(
234
+ stepOffset.mul(direction.xy).mul(fraction.mul(fraction)),
235
+ );
236
+ const sampleDepth = depthNode.sample(sampleCoordinate).r;
237
+ const inside = sampleCoordinate.x
238
+ .greaterThanEqual(0)
239
+ .and(sampleCoordinate.x.lessThanEqual(1))
240
+ .and(sampleCoordinate.y.greaterThanEqual(0))
241
+ .and(sampleCoordinate.y.lessThanEqual(1))
242
+ .and(sampleDepth.lessThan(1));
243
+ const delta = viewPosition(sampleCoordinate, sampleDepth).sub(position);
244
+ // How far above the tangent plane the sample stands: its sine, which is the horizon's angle.
245
+ const sine = delta.dot(normal).div(max(length(delta), float(MIN_DISTANCE)));
246
+ horizon.assign(max(horizon, inside.select(sine, float(-1))));
247
+ },
248
+ );
249
+ const kept = clamp(float(1).sub(max(horizon, float(0))), float(0), float(1));
250
+ open.assign(open.add(kept));
251
+ if (bent)
252
+ bentNormal.assign(
253
+ bentNormal.add(direction.mul(kept)).add(normal.mul(kept.mul(0.5).add(0.25))),
254
+ );
255
+ },
256
+ );
257
+ const visibility = pow(clamp(open.div(slices), float(0), float(1)), intensity);
258
+ // A bent normal alone can point along the geometric one or degenerate in a fully open pixel: adding the
259
+ // geometric normal and normalising once keeps the axis well behaved at both ends.
260
+ const axis = bent ? normalize(normalize(bentNormal).add(normal)) : normal;
261
+ result.assign(vec4(axis, visibility));
262
+ });
263
+ return result;
264
+ })();
265
+
266
+ const node = rtt(graph, null, null, { type: HALF_FLOAT_TYPE });
267
+ return Object.defineProperties(node, {
268
+ bentNormal: { value: bent },
269
+ reachPx: { value: this.reachPx },
270
+ slices: { value: this.horizonSearchSliceCount },
271
+ steps: { value: this.horizonSearchStepCount },
272
+ }) as Node<"vec4">;
273
+ }
274
+ }