@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.
- package/capabilities.json +299 -10
- package/dist/{chunk-4SRAQFTU.js → chunk-2GPHICV6.js} +1 -1
- package/dist/{chunk-DIPIJICH.js → chunk-GEMQJBY4.js} +70 -18
- package/dist/{chunk-EFWZWLPY.js → chunk-QAMSM3Z5.js} +354 -12
- package/dist/{chunk-SV4QVUTQ.js → chunk-QAQHYOWY.js} +1 -1
- package/dist/{chunk-EEABDLUC.js → chunk-VBBYWGAT.js} +2 -2
- package/dist/{chunk-GYUZJQ7U.js → chunk-VQRPEOKY.js} +4 -1
- package/dist/index.d.ts +605 -7
- package/dist/index.js +1973 -609
- package/dist/playtest.js +3 -3
- package/dist/{quality-BYqKGAwo.d.ts → quality-BADStsTn.d.ts} +2 -2
- package/dist/render-environment.d.ts +1 -1
- package/dist/ui-layer.js +2 -2
- package/dist/worker.js +2 -2
- package/dist/world.d.ts +13 -3
- package/dist/world.js +179 -36
- package/mcp/animation-server.mjs +1 -1
- package/mcp/engine-server.mjs +32 -6
- package/mcp/servers.mjs +3 -3
- package/package.json +5 -5
- package/scripts/ensure-mcp.mjs +6 -1
- package/src/clustered-batch.ts +146 -3
- package/src/clustered-mesh.ts +548 -20
- package/src/debug.ts +16 -0
- package/src/displaced-surface.ts +428 -0
- package/src/frame-budget.ts +16 -0
- package/src/generated/console-markers.ts +1 -0
- package/src/grass-field.ts +628 -0
- package/src/index.ts +112 -0
- package/src/render/material-key.ts +21 -1
- package/src/render/screen-probe-gather.ts +303 -0
- package/src/render/short-range-ao.ts +274 -0
- package/src/render/world-impostor-surface.ts +98 -3
- package/src/render-camera-cull.ts +9 -3
- package/src/renderer.ts +26 -4
- package/src/scatter-field.ts +496 -0
- package/src/startup-offscreen-bytes.ts +11 -5
- package/src/state.ts +16 -3
- package/src/static-transform.ts +75 -6
- package/src/tile-ring.ts +294 -0
- package/src/version.ts +1 -1
- package/src/warmup.ts +15 -2
- package/src/world-cell-batches.ts +4 -0
- package/src/world-cell-data.ts +7 -0
- package/src/world-cell-models.ts +36 -8
- package/src/world-cell-render-gpu-dress.ts +4 -2
- package/src/world-cell-render-util.ts +2 -2
- package/src/world-cells.ts +1 -1
- package/src/world-river-ribbon.ts +13 -22
- 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
|
-
|
|
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
|
+
}
|