@threenative/core 0.3.13 → 0.3.15

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 (50) hide show
  1. package/capabilities.json +299 -10
  2. package/dist/{chunk-4SRAQFTU.js → chunk-2GPHICV6.js} +1 -1
  3. package/dist/{chunk-DIPIJICH.js → chunk-GEMQJBY4.js} +70 -18
  4. package/dist/{chunk-EFWZWLPY.js → chunk-QAMSM3Z5.js} +354 -12
  5. package/dist/{chunk-SV4QVUTQ.js → chunk-QAQHYOWY.js} +1 -1
  6. package/dist/{chunk-EEABDLUC.js → chunk-VBBYWGAT.js} +2 -2
  7. package/dist/{chunk-GYUZJQ7U.js → chunk-VQRPEOKY.js} +4 -1
  8. package/dist/index.d.ts +605 -7
  9. package/dist/index.js +1973 -609
  10. package/dist/playtest.js +3 -3
  11. package/dist/{quality-BYqKGAwo.d.ts → quality-BADStsTn.d.ts} +2 -2
  12. package/dist/render-environment.d.ts +1 -1
  13. package/dist/ui-layer.js +2 -2
  14. package/dist/worker.js +2 -2
  15. package/dist/world.d.ts +13 -3
  16. package/dist/world.js +179 -36
  17. package/mcp/animation-server.mjs +1 -1
  18. package/mcp/engine-server.mjs +32 -6
  19. package/mcp/servers.mjs +3 -3
  20. package/package.json +5 -5
  21. package/scripts/ensure-mcp.mjs +6 -1
  22. package/src/clustered-batch.ts +146 -3
  23. package/src/clustered-mesh.ts +548 -20
  24. package/src/debug.ts +16 -0
  25. package/src/displaced-surface.ts +428 -0
  26. package/src/frame-budget.ts +16 -0
  27. package/src/generated/console-markers.ts +1 -0
  28. package/src/grass-field.ts +628 -0
  29. package/src/index.ts +112 -0
  30. package/src/render/material-key.ts +21 -1
  31. package/src/render/screen-probe-gather.ts +303 -0
  32. package/src/render/short-range-ao.ts +274 -0
  33. package/src/render/world-impostor-surface.ts +98 -3
  34. package/src/render-camera-cull.ts +9 -3
  35. package/src/renderer.ts +26 -4
  36. package/src/scatter-field.ts +496 -0
  37. package/src/startup-offscreen-bytes.ts +11 -5
  38. package/src/state.ts +16 -3
  39. package/src/static-transform.ts +75 -6
  40. package/src/tile-ring.ts +294 -0
  41. package/src/version.ts +1 -1
  42. package/src/warmup.ts +15 -2
  43. package/src/world-cell-batches.ts +4 -0
  44. package/src/world-cell-data.ts +7 -0
  45. package/src/world-cell-models.ts +36 -8
  46. package/src/world-cell-render-gpu-dress.ts +4 -2
  47. package/src/world-cell-render-util.ts +2 -2
  48. package/src/world-cells.ts +1 -1
  49. package/src/world-river-ribbon.ts +13 -22
  50. package/src/world-water-bodies.ts +113 -3
package/src/index.ts CHANGED
@@ -360,6 +360,60 @@ export type {
360
360
  ITracedRay,
361
361
  ITracedReflectionsOptions,
362
362
  } from "./render/traced-reflections.js";
363
+ /**
364
+ * Lumen's Screen Probe Gather: one probe per 16 x 16 pixels traces an 8 x 8 octahedron of rays, the probes are filtered
365
+ * into an irradiance octahedron each, and a pixel blends the four nearest probes it can see, instead of every pixel
366
+ * tracing its own rays. A ray that hits on screen returns the lit frame minus the cache along it; a ray that leaves the
367
+ * screen continues through the packed scene up to the radiance cache's cell and reads the cache where it ended, so the
368
+ * light that arrives from off screen is that direction's and not the pixel's mean.
369
+ * @situation bounce light that reads the room off screen instead of a flat ambient term
370
+ * @situation global illumination that costs a fraction of one ray per pixel
371
+ * @situation the light a corner sees from around the wall, which a per-pixel screen trace loses
372
+ * @situation lumen screen probe gather
373
+ * @situation lumen final gather
374
+ * @constraint the owned engine only: on engine: "threejs" the upstream node takes the camera as its fourth argument and has no probes, and gather() refuses
375
+ * @constraint the gather is a delta in E / pi: multiply it by the receiver's diffuse colour (mrt({ diffuseColor })) and add it after the scene pass, and give the scene pass no other indirect diffuse or the light is counted twice
376
+ * @constraint a viewport resize needs a new gather: the probe grid is fixed when it is built
377
+ * @constraint the grid is the cost: downsampleFactor 16 and an 8 x 8 octahedron are Unreal's Epic, 32 and 8 its High
378
+ * @constraint radiance answers in the frame's units (the cache read times the frame's gain), and a trace reads it only where the screen has nothing
379
+ * @override downsampleFactor, tracingOctahedronResolution, cacheCellSize, timedPass and the strength of the composite are game-owned choices
380
+ * @example
381
+ * const gather = new ScreenProbeGather({ camera, viewport, radiance, trace });
382
+ * const gi = gather.gather(convertToTexture(input), depth(), normalView());
383
+ * const bounce = gather.getGINode().rgb.mul(diffuseColor.rgb);
384
+ */
385
+ export { ScreenProbeGather } from "./render/screen-probe-gather.js";
386
+ export type {
387
+ IScreenProbeCamera,
388
+ IScreenProbeGatherOptions,
389
+ IScreenProbeGatherReport,
390
+ ScreenProbePass,
391
+ } from "./render/screen-probe-gather.js";
392
+ /**
393
+ * Unreal's Short Range AO: a horizon search of 2 sweeps around the view normal, 3 samples each at the squared fraction
394
+ * of a 32 px screen reach, at full resolution, with a bent normal at Epic. It is the occlusion that runs *with* dynamic
395
+ * global illumination — the contact detail Lumen keeps after the screen probe gather has already answered the wide
396
+ * occlusion — so a gathered frame is not darkened twice by two wide treatments. The result is one texture: `rgb` the
397
+ * bent normal in view space, `a` the share of the hemisphere left open, which multiplies indirect light only.
398
+ * @situation contact shadow at the foot of an object while dynamic GI runs
399
+ * @situation dark line where a wall meets the floor, without a second wide AO over the gathered light
400
+ * @situation lumen short range ao
401
+ * @constraint it replaces GTAO when dynamic GI runs; a tier without GI keeps ambientOcclusion
402
+ * @constraint the occlusion multiplies indirect light only: direct light and emission keep their own occlusion
403
+ * @constraint multi-bounce and its albedo cap belong to the game's composite; Unreal caps the albedo at 0.5
404
+ * @constraint an authored stage that carries its name must anchor itself (`before: "ssgi"`), because the chain's built-in order names no shortRangeAO
405
+ * @override horizonSearchSliceCount, horizonSearchStepCount, reachPx, bentNormal and intensity are game-owned choices
406
+ * @example
407
+ * const shortRange = new ShortRangeAO({ camera, viewport: renderer.drawingBufferSize });
408
+ * const contact = shortRange.occlusion(depth(), normalView());
409
+ * const indirect = input.rgb.mul(contact.a);
410
+ */
411
+ export { ShortRangeAO } from "./render/short-range-ao.js";
412
+ export type {
413
+ IShortRangeAOCamera,
414
+ IShortRangeAOOptions,
415
+ IShortRangeAOReport,
416
+ } from "./render/short-range-ao.js";
363
417
  /**
364
418
  * Collapse many copies of one game-authored shape into a single draw, without counting them first.
365
419
  *
@@ -456,6 +510,15 @@ export type { IMergeByMaterialOptions } from "./merge-parts.js";
456
510
  * if (debugFlag("freeCam")) camera.flyMode = true;
457
511
  */
458
512
  export { debugFlag } from "./debug.js";
513
+ /**
514
+ * Read the text a debug switch was given by the launch, on the same rule as `debugFlag`.
515
+ * @situation read a debug override whose value is not a boolean
516
+ * @situation override a quality tier or a mode for one run without changing the code
517
+ * @constraint the same name rule as `debugFlag`: `?quality=` on the web, `TN_DEBUG_QUALITY` on a native launch
518
+ * @example import { debugValue } from "@threenative/core";
519
+ * const tier = debugValue("quality");
520
+ */
521
+ export { debugValue } from "./debug.js";
459
522
  /**
460
523
  * Publish one game object under `__THREENATIVE__.debug` for a capture script or the console.
461
524
  * @situation expose a game object to a capture script or the console in dev builds
@@ -1477,6 +1540,55 @@ export type {
1477
1540
  */
1478
1541
  export { GPUReadback } from "./gpu-readback.js";
1479
1542
  export type { IGPUReadbackOptions, IGPUReadbackSample } from "./gpu-readback.js";
1543
+ /**
1544
+ * Stream instanced grass in chunks around the camera; the game owns the blade and its TSL material.
1545
+ * @situation grass that sways and parts around the player
1546
+ * @situation a meadow, lawn or grassy field over terrain that streams around the camera
1547
+ * @situation ground cover grass blades with distance thinning and LOD that does not pop
1548
+ * @situation grass flattened or pushed aside where the player, a creature or a vehicle walks
1549
+ * @situation grow grass on a terrain biome's grass rows with grassFieldFromBiome
1550
+ * @constraint call `update(camera)` once per rendered frame from `ctx.beforeRender`; chunks build nearest first inside `buildBudgetMs`
1551
+ * @constraint the material reads `GRASS_FIELD_ATTRIBUTES` and the field's `nodes` uniforms, so its thinning matches the CPU trim
1552
+ * @constraint a chunk is built inside 1.3 × the draw distance and discarded past 1.4 ×, so a camera on the edge rebuilds nothing
1553
+ * @override densityScale and cullDistanceScale scale every density and distance at once; prewarm() builds all in range on the next update
1554
+ * @example // the look lives in the kit's src/render/grass.ts
1555
+ * const grass = new GrassField3D({ blade: grassBlade(), material: grassMaterial, getHeight: height });
1556
+ * ctx.add(grass);
1557
+ * ctx.beforeRender(() => { grass.pushers[0]?.set(hero.x, hero.y, hero.z, 1.2); grass.update(ctx.camera); });
1558
+ */
1559
+ export { GRASS_FIELD_ATTRIBUTES, GrassField3D } from "./grass-field.js";
1560
+ export type {
1561
+ IGrassField3DOptions,
1562
+ IGrassFieldBlade,
1563
+ IGrassFieldBounds,
1564
+ IGrassFieldNodes,
1565
+ IGrassFieldStats,
1566
+ } from "./grass-field.js";
1567
+
1568
+ /**
1569
+ * Stream instanced copies of any baked mesh around a follow point, with distance thinning and levels
1570
+ * of detail, from the game's own placement rule.
1571
+ * @situation scatter fallen logs, twigs, leaf litter, stones and ferns over a forest floor
1572
+ * @situation stream instanced props of any baked mesh round the player without one draw per prop
1573
+ * @situation place rocks, debris or plants on a heightfield with distance thinning and level of detail
1574
+ * @constraint call `update(follow)` once per rendered frame
1575
+ * @constraint `place` runs once per candidate per tile build: return false for paths and clearings
1576
+ * @constraint rotating or scaling the field is not supported; translating it is
1577
+ * @requires npm i -D @threenative/procedural-vegetation for the bake these instances come from
1578
+ * @example
1579
+ * const floor = new ScatterField3D({ parts: [{ lods, material }], getHeight, density: 0.05, place });
1580
+ * ctx.add(floor);
1581
+ * ctx.beforeRender(() => floor.update(hero.position));
1582
+ */
1583
+ export { ScatterField3D } from "./scatter-field.js";
1584
+ export type {
1585
+ IScatterField3DOptions,
1586
+ IScatterFieldBounds,
1587
+ IScatterFieldStats,
1588
+ IScatterPart,
1589
+ IScatterPlacement,
1590
+ IScatterPoint,
1591
+ } from "./scatter-field.js";
1480
1592
  /**
1481
1593
  * Dispatch a game-owned particle surface and process function through a pooled system.
1482
1594
  * @situation emit sparks, smoke, or other transient effects
@@ -16,11 +16,31 @@ const TEXTURE_SLOTS = [
16
16
  "alphaMap",
17
17
  ] as const;
18
18
 
19
+ /** Ids for unnamed textures whose source carries no `uuid` (the owned engine's), one per texture. */
20
+ const unnamedIds = new WeakMap<Texture, number>();
21
+ let nextUnnamedId = 0;
22
+
23
+ /** The texture's own source identity: three's source `uuid`, else a per-texture id from this module. */
24
+ function sourceId(texture: Texture): string {
25
+ const uuid = (texture.source as { uuid?: string } | undefined)?.uuid;
26
+ if (uuid !== undefined) return uuid;
27
+ let id = unnamedIds.get(texture);
28
+ if (id === undefined) {
29
+ id = nextUnnamedId++;
30
+ unnamedIds.set(texture, id);
31
+ }
32
+ return `#${String(id)}`;
33
+ }
34
+
19
35
  function textureKey(texture: Texture | null | undefined): string {
20
36
  if (texture === null || texture === undefined) return "-";
21
37
  const image = texture.image as { width?: number; height?: number } | undefined;
22
38
  const mips = (texture as { mipmaps?: readonly { data?: { byteLength?: number } }[] }).mipmaps;
23
- return `${texture.name}:${String(image?.width ?? 0)}x${String(image?.height ?? 0)}:${String(mips?.[0]?.data?.byteLength ?? 0)}:${texture.flipY ? 1 : 0}`;
39
+ // A name is what lets two loads of one image match. Without one, nothing here tells two images of
40
+ // one size apart (generated leaf atlases are all 1024², unnamed, with no mip bytes), so the
41
+ // texture's own source is its identity: it never shares, and never draws another's pixels.
42
+ const id = texture.name !== "" ? texture.name : `source:${sourceId(texture)}`;
43
+ return `${id}:${String(image?.width ?? 0)}x${String(image?.height ?? 0)}:${String(mips?.[0]?.data?.byteLength ?? 0)}:${texture.flipY ? 1 : 0}`;
24
44
  }
25
45
 
26
46
  /**
@@ -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
+ }