@threenative/core 0.3.6 → 0.3.9

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 (137) hide show
  1. package/README.md +3 -5
  2. package/capabilities.json +739 -50
  3. package/dist/{assets-CqvE429w.d.ts → assets-YUbXa3-Y.d.ts} +101 -2
  4. package/dist/{canvas-layer-C1-5CviZ.d.ts → canvas-layer-vCtanIeB.d.ts} +1 -1
  5. package/dist/{game-Jz4Fdoeb.d.ts → game-cb99J-YE.d.ts} +100 -31
  6. package/dist/hot.d.ts +4 -4
  7. package/dist/hot.js +23 -5
  8. package/dist/index.d.ts +1742 -29
  9. package/dist/index.js +22443 -12423
  10. package/dist/{model-lod-BDAUYgsS.d.ts → model-lod-CTpZ6imz.d.ts} +1 -1
  11. package/dist/net.js +39 -12
  12. package/dist/playtest.d.ts +4 -4
  13. package/dist/playtest.js +48 -9
  14. package/dist/react-css.js +23 -0
  15. package/dist/react.d.ts +2 -2
  16. package/dist/{renderer-9yEo9hPa.d.ts → renderer-rZm0hVqq.d.ts} +178 -5
  17. package/dist/ui-layer.d.ts +11 -2
  18. package/dist/ui-layer.js +76 -4
  19. package/dist/worker.d.ts +36 -0
  20. package/dist/worker.js +1088 -0
  21. package/dist/world.d.ts +11 -3
  22. package/dist/world.js +1117 -197
  23. package/mcp/animation-server.mjs +265 -0
  24. package/mcp/animation.mjs +22 -0
  25. package/mcp/call.mjs +105 -0
  26. package/mcp/devtools.mjs +5 -0
  27. package/mcp/engine-server.mjs +713 -37
  28. package/mcp/launch.mjs +3 -2
  29. package/mcp/servers.d.mts +2 -0
  30. package/mcp/servers.mjs +33 -8
  31. package/package.json +12 -8
  32. package/patches/three@0.185.1-prd269-upgrade.patch +308 -0
  33. package/patches/three@0.185.1.patch +481 -272
  34. package/src/animation-packet-state.ts +88 -0
  35. package/src/animation-pose-packet.ts +537 -0
  36. package/src/animation.ts +779 -31
  37. package/src/asset-cache.ts +719 -0
  38. package/src/assets.ts +521 -152
  39. package/src/audio.ts +29 -3
  40. package/src/auto-batch.ts +792 -0
  41. package/src/config.ts +2 -0
  42. package/src/frame-budget.ts +268 -2
  43. package/src/game.ts +525 -105
  44. package/src/grounding.ts +7 -6
  45. package/src/hot.ts +19 -5
  46. package/src/index.ts +381 -6
  47. package/src/input.ts +21 -2
  48. package/src/interpolation.ts +19 -1
  49. package/src/launch-diagnostics.ts +7 -2
  50. package/src/look/ao-multibounce.ts +29 -0
  51. package/src/look/ao-reach.ts +39 -0
  52. package/src/look/auto-exposure.ts +264 -0
  53. package/src/look/default-tone-mapping.ts +44 -0
  54. package/src/look/exposure-graph.ts +208 -0
  55. package/src/look/exposure-readback.ts +97 -0
  56. package/src/look/exposure-settings.ts +132 -0
  57. package/src/look/filmic-tone-mapping.ts +852 -0
  58. package/src/look/gi-registry.ts +55 -0
  59. package/src/look/local-exposure.ts +507 -0
  60. package/src/look/look-diagnostics.ts +24 -0
  61. package/src/look/motion-blur.ts +42 -0
  62. package/src/look/quality.ts +309 -0
  63. package/src/look/reflection-trace.ts +344 -0
  64. package/src/look/unreal-bloom.ts +295 -0
  65. package/src/look/vignette.ts +14 -0
  66. package/src/look/world-environment.ts +2033 -0
  67. package/src/loop.ts +25 -1
  68. package/src/merge-parts.ts +25 -10
  69. package/src/model-lod.ts +14 -0
  70. package/src/net-session.ts +58 -14
  71. package/src/ocean/spectral.ts +41 -7
  72. package/src/picking.ts +72 -5
  73. package/src/platform.ts +29 -1
  74. package/src/playtest.ts +54 -8
  75. package/src/profiling/FrameCounters.ts +166 -5
  76. package/src/profiling/FrameStages.ts +289 -0
  77. package/src/profiling/Spans.ts +39 -25
  78. package/src/profiling/debug-telemetry.ts +312 -0
  79. package/src/profiling/scene-warning.ts +42 -6
  80. package/src/projection-apply.ts +11 -3
  81. package/src/projection-content.ts +189 -0
  82. package/src/projection-marker.ts +6 -2
  83. package/src/projection-plan.ts +279 -28
  84. package/src/projection-skinned.ts +620 -5
  85. package/src/projection-stability.ts +16 -0
  86. package/src/projection-uniform.ts +5 -1
  87. package/src/quiet-markers.ts +56 -0
  88. package/src/render/budget-ladder.ts +256 -0
  89. package/src/render/chain.ts +89 -7
  90. package/src/render/exposure-units.ts +59 -0
  91. package/src/render/frame-time-budget.ts +162 -0
  92. package/src/render/gi-budget.ts +231 -0
  93. package/src/render/gi-visualize.ts +49 -0
  94. package/src/render/material-key.ts +1 -0
  95. package/src/render/probe-volume.ts +196 -36
  96. package/src/render/rough-diffuse.ts +177 -0
  97. package/src/render/scene-trace.ts +532 -0
  98. package/src/render/shadow-filter-budget.ts +237 -0
  99. package/src/render/sky-capture.ts +194 -0
  100. package/src/render/soft-shadow.ts +607 -0
  101. package/src/render/surface-cache.ts +418 -0
  102. package/src/render/traced-reflections.ts +408 -0
  103. package/src/render/two-sided-foliage.ts +120 -0
  104. package/src/render/virtual-shadow-pages.ts +112 -12
  105. package/src/render/virtual-shadow.ts +386 -38
  106. package/src/render-camera-cull.ts +536 -31
  107. package/src/render-pass-budget.ts +140 -22
  108. package/src/renderProjection.ts +65 -9
  109. package/src/renderer-config.ts +3 -2
  110. package/src/renderer.ts +289 -14
  111. package/src/resolution-scaler.ts +65 -7
  112. package/src/skeletal-mesh.ts +4 -0
  113. package/src/snow-field.ts +46 -0
  114. package/src/softbody.ts +6 -5
  115. package/src/startup-offscreen-bytes.ts +168 -0
  116. package/src/startup-readiness.ts +137 -2
  117. package/src/ui-bridge.ts +38 -0
  118. package/src/ui-hit-regions.ts +6 -2
  119. package/src/ui-layer.ts +1 -0
  120. package/src/ui-state.ts +32 -3
  121. package/src/version.ts +1 -1
  122. package/src/viewport.ts +8 -5
  123. package/src/warmup.ts +76 -10
  124. package/src/worker-audio.ts +579 -0
  125. package/src/worker.ts +842 -0
  126. package/src/world-cells.ts +4 -1
  127. package/gpl/LICENSE.GPL +0 -117
  128. package/gpl/convert.py +0 -192
  129. package/gpl/fixtures/make_world_fixture.py +0 -184
  130. package/gpl/recipes/_common.py +0 -180
  131. package/gpl/recipes/bake_ao.py +0 -111
  132. package/gpl/recipes/decimate.py +0 -70
  133. package/gpl/recipes/export_world.py +0 -699
  134. package/gpl/recipes/retarget.py +0 -131
  135. package/gpl/recipes/unwrap.py +0 -71
  136. package/mcp/blender-server.mjs +0 -689
  137. package/mcp/blender.mjs +0 -26
@@ -0,0 +1,55 @@
1
+ import type { Data3DTexture, PerspectiveCamera, Vector3 } from "three";
2
+ import { uniform, vec3 } from "three/tsl";
3
+ import type { Node } from "three/webgpu";
4
+
5
+ export interface IGrid {
6
+ readonly origin: Vector3;
7
+ readonly cell: number;
8
+ readonly nx: number;
9
+ readonly ny: number;
10
+ readonly nz: number;
11
+ }
12
+
13
+ /**
14
+ * The cache's read, registered when the bake finishes: a screen-space gather asks it what a ray that finds
15
+ * nothing on screen would have returned (the tier below its own), with the pixel's world position and normal.
16
+ */
17
+ export const giCache: {
18
+ irradiance?: (position: Node<"vec3">, normal: Node<"vec3">) => Node<"vec3">;
19
+ /**
20
+ * The baked field at its final resolution, for tools and tests: per texel, six faces of RGB (E / pi), six
21
+ * environment shares, and whether the texel's centre lies inside a solid (a read gives it no weight).
22
+ */
23
+ field?: {
24
+ grid: IGrid;
25
+ values: Float32Array;
26
+ sky: Float32Array;
27
+ solid: Uint8Array;
28
+ /** Per texel and axis (x, y, z): where the wall on the link to the next texel starts, 0 to 255 of the way (0 when open). */
29
+ walls: Uint8Array;
30
+ };
31
+ /** The texture the materials read, for the light-change update. */
32
+ volumeTexture?: Data3DTexture;
33
+ /**
34
+ * Follows the lights that have a `source`: when one changed since the last call, rewrites the field and the texture and
35
+ * returns true. The game's frame hook calls it every frame (`IRayContext.beforeRender`); a test calls it by hand.
36
+ */
37
+ refresh?: () => boolean;
38
+ } = {};
39
+
40
+ /**
41
+ * The cache as the tier below a screen-space gather: a function of the pixel's view-space position and unit
42
+ * normal, reading the cache through the camera's world matrix (refreshed every render). Undefined before the bake.
43
+ */
44
+ export function cacheFallback(
45
+ camera: PerspectiveCamera,
46
+ ): ((position: Node<"vec3">, normal: Node<"vec3">) => Node<"vec3">) | undefined {
47
+ const read = giCache.irradiance;
48
+ if (read === undefined) return undefined;
49
+ const live = (index: number) =>
50
+ uniform(0).onRenderUpdate(() => camera.matrixWorld.elements[index] ?? 0);
51
+ const column = (a: number) => vec3(live(a), live(a + 1), live(a + 2));
52
+ const [right, up, back, at] = [column(0), column(4), column(8), column(12)];
53
+ const toWorld = (v: Node<"vec3">) => right.mul(v.x).add(up.mul(v.y)).add(back.mul(v.z));
54
+ return (position, normal) => read(toWorld(position).add(at), toWorld(normal).normalize());
55
+ }
@@ -0,0 +1,507 @@
1
+ import {
2
+ FloatType,
3
+ HalfFloatType,
4
+ LinearFilter,
5
+ NearestFilter,
6
+ RenderTarget,
7
+ Vector2,
8
+ } from "three";
9
+ import {
10
+ Fn,
11
+ If,
12
+ Loop,
13
+ float,
14
+ int,
15
+ mix,
16
+ nodeObject,
17
+ texture,
18
+ uniform,
19
+ uv,
20
+ vec2,
21
+ vec3,
22
+ vec4,
23
+ } from "three/tsl";
24
+ import {
25
+ type Node,
26
+ type NodeBuilder,
27
+ type NodeFrame,
28
+ NodeMaterial,
29
+ NodeUpdateType,
30
+ QuadMesh,
31
+ RendererUtils,
32
+ TempNode,
33
+ } from "three/webgpu";
34
+ import { exposureMeter, exposureSettings } from "./exposure-settings.js";
35
+
36
+ type ColourTexture = ReturnType<typeof texture>;
37
+
38
+ /** The look: change a number here, not the passes below. */
39
+ const localExposureSettings = {
40
+ /** Scale on how far a bright base sits above middle grey; 1 leaves the global exposure alone. */
41
+ highlightContrastScale: 0.8,
42
+ /** The same for a dark base. */
43
+ shadowContrastScale: 0.8,
44
+ /** 1 keeps all the detail above the local base. */
45
+ detailStrength: 1,
46
+ /** 0 uses only the depth-aware grid for the base, 1 only the blurred luminance. */
47
+ blurredLuminanceBlend: 0.6,
48
+ /** Middle grey after the global exposure bias; the global key is the same number. */
49
+ middleGrey: exposureSettings.key,
50
+ } as const;
51
+
52
+ /** Unreal's histogram range, in log2 luminance: Scene.cpp extended default luminance range. */
53
+ const LOG_MIN = -10;
54
+ const LOG_SPAN = 30;
55
+ /** BILATERAL_GRID_DEPTH in PostProcessHistogramCommon.ush: bins of log luminance per cell. */
56
+ const DEPTH = 32;
57
+ /** A grid cell is 8x8 threads times 8x8 texels each of the half resolution image. */
58
+ const CELL = 64;
59
+ /** Half resolution logs per log texel: neighbours along a row, so a row sum reads four with one tap. */
60
+ const PACK = 4;
61
+ /** Gaussian taps either side: the unrolled loop's 32 samples (r.Filter.LoopMode 0) cap the radius. */
62
+ const BLUR_RADIUS = 31;
63
+ /** PostProcessWeightedSampleSum.cpp LegacyCompatibilityConstant. */
64
+ const BLUR_SHAPE = -16.7;
65
+ /**
66
+ * The blurred luminance reads SceneDownsampleChain mip 4, a sixteenth of the view (PostProcessing.cpp:1431-1434),
67
+ * and blurs it there: a radius of 31 texels at that size spans a quarter of the view, as Unreal's does.
68
+ */
69
+ const BLUR_DOWNSAMPLE = 16;
70
+ /** LocalExposureBlurredLuminanceKernelSizePercent (Scene.cpp:531): the kernel's diameter as a share of the width. */
71
+ const BLUR_KERNEL_PERCENT = 50;
72
+
73
+ /** The pass sizes for a drawing buffer, in texels: half for the grid's input, a sixteenth for the blur. */
74
+ export function localExposureSizes(
75
+ width: number,
76
+ height: number,
77
+ ): {
78
+ readonly half: readonly [number, number];
79
+ readonly blur: readonly [number, number];
80
+ readonly cells: readonly [number, number];
81
+ readonly log: readonly [number, number];
82
+ readonly rows: readonly [number, number];
83
+ readonly grid: readonly [number, number];
84
+ readonly blurRadius: number;
85
+ readonly rangeStride: number;
86
+ } {
87
+ const half = [Math.max(1, Math.ceil(width / 2)), Math.max(1, Math.ceil(height / 2))] as const;
88
+ const blur = [
89
+ Math.max(1, Math.ceil(width / BLUR_DOWNSAMPLE)),
90
+ Math.max(1, Math.ceil(height / BLUR_DOWNSAMPLE)),
91
+ ] as const;
92
+ // GetBlurRadius takes the filter width times the percent as a diameter; GetClampedKernelRadius caps it.
93
+ const blurRadius = Math.min(
94
+ BLUR_RADIUS,
95
+ Math.max(1e-4, blur[0] * BLUR_KERNEL_PERCENT * 0.01 * 0.5),
96
+ );
97
+ const cells = [Math.ceil(half[0] / CELL), Math.ceil(half[1] / CELL)] as const;
98
+ // The grid's row sums: one texel per cell, pair of bins and half resolution row, CELL logs each.
99
+ return {
100
+ half,
101
+ blur,
102
+ cells,
103
+ log: [Math.ceil(half[0] / PACK), half[1]],
104
+ rows: [(cells[0] * DEPTH) / 2, cells[1] * CELL],
105
+ grid: [cells[0] * DEPTH, cells[1]],
106
+ blurRadius,
107
+ rangeStride: Math.ceil((cells[0] * half[1]) / (blur[0] * blur[1])),
108
+ };
109
+ }
110
+
111
+ function scratch(type: typeof FloatType | typeof HalfFloatType, linear: boolean): RenderTarget {
112
+ return new RenderTarget(1, 1, {
113
+ type,
114
+ minFilter: linear ? LinearFilter : NearestFilter,
115
+ magFilter: linear ? LinearFilter : NearestFilter,
116
+ depthBuffer: false,
117
+ });
118
+ }
119
+
120
+ /** The unit-interval coordinate mirrored back inside [0, 1] (the blur's mirror address mode). */
121
+ function mirror(u: Node<"float">): Node<"float"> {
122
+ return u.mod(2).sub(1).abs().oneMinus();
123
+ }
124
+
125
+ /** Owns scratch targets only. Never draws the world or installs another output transform. */
126
+ export class LocalExposureNode extends TempNode<"float"> {
127
+ static get type(): string {
128
+ return "LocalExposureNode";
129
+ }
130
+ readonly input: ColourTexture;
131
+ readonly #exposure: Node<"float">;
132
+ readonly #size = new Vector2();
133
+ readonly #full = uniform(new Vector2(1, 1));
134
+ readonly #half = uniform(new Vector2(1, 1));
135
+ readonly #logSize = uniform(new Vector2(1, 1));
136
+ readonly #rows = uniform(new Vector2(1, 1));
137
+ readonly #grid = uniform(new Vector2(1, 1));
138
+ readonly #cells = uniform(new Vector2(1, 1));
139
+ readonly #blurSize = uniform(new Vector2(1, 1));
140
+ readonly #blurRadius = uniform(BLUR_RADIUS);
141
+ readonly #rangeStride = uniform(1);
142
+ readonly #quad = new QuadMesh();
143
+ readonly #logMaterial = new NodeMaterial();
144
+ readonly #lumMaterial = new NodeMaterial();
145
+ readonly #blurXMaterial = new NodeMaterial();
146
+ readonly #blurYMaterial = new NodeMaterial();
147
+ readonly #rowMaterial = new NodeMaterial();
148
+ readonly #gridMaterial = new NodeMaterial();
149
+ readonly #logTarget = scratch(FloatType, false);
150
+ readonly #lumTarget = scratch(FloatType, false);
151
+ readonly #blurXTarget = scratch(FloatType, false);
152
+ readonly #blurTarget = scratch(HalfFloatType, true);
153
+ readonly #rowTarget = scratch(FloatType, false);
154
+ readonly #gridTarget = scratch(FloatType, false);
155
+ readonly #logTexture = texture(this.#logTarget.texture);
156
+ readonly #lumTexture = texture(this.#lumTarget.texture);
157
+ readonly #blurXTexture = texture(this.#blurXTarget.texture);
158
+ readonly #blurTexture = texture(this.#blurTarget.texture);
159
+ readonly #rowTexture = texture(this.#rowTarget.texture);
160
+ readonly #gridTexture = texture(this.#gridTarget.texture);
161
+ // Three's runtime accepts undefined on first use, but its declaration requires a state.
162
+ #rendererState: Parameters<typeof RendererUtils.resetRendererState>[1] | undefined;
163
+ #configuredWidth = -1;
164
+ #configuredHeight = -1;
165
+ #disposed = false;
166
+
167
+ constructor(input: ColourTexture, exposure: Node<"float">) {
168
+ super("float");
169
+ this.input = input;
170
+ this.#exposure = exposure;
171
+ this.updateBeforeType = NodeUpdateType.FRAME;
172
+ const half = this.#half;
173
+ const blurSize = this.#blurSize;
174
+ const radius = this.#blurRadius;
175
+
176
+ // Pass 1: log2 luminance of the half resolution image (a 2x2 average of colour), PACK neighbouring
177
+ // half resolution texels of a row per texel, so the row sums read four logs with one tap.
178
+ this.#logMaterial.fragmentNode = Fn(() => {
179
+ const c = uv();
180
+ const texel = vec2(0.5).div(this.#full);
181
+ const first = c.x.mul(this.#logSize.x).floor().mul(PACK);
182
+ const logAt = (k: number): Node<"float"> => {
183
+ const at = vec2(first.add(k + 0.5).div(half.x), c.y);
184
+ const sum = vec3(0).toVar();
185
+ for (const [x, y] of [
186
+ [-1, -1],
187
+ [1, -1],
188
+ [-1, 1],
189
+ [1, 1],
190
+ ] as const)
191
+ sum.addAssign(input.sample(at.add(texel.mul(vec2(x, y)))).rgb);
192
+ return exposureMeter(vec4(sum.div(4), 1), at)
193
+ .x.max(2 ** LOG_MIN)
194
+ .log2();
195
+ };
196
+ return vec4(logAt(0), logAt(1), logAt(2), logAt(3));
197
+ })();
198
+
199
+ // Pass 2: log2 luminance of the colour averaged over each 16x16 block, the downsample chain's mip 4
200
+ // (SetupLogLuminanceCS takes the log after the downsample). Point taps at texel centres, so the
201
+ // input's filter does not matter.
202
+ this.#lumMaterial.fragmentNode = Fn(() => {
203
+ const c = uv();
204
+ const texel = float(1).div(this.#full);
205
+ const sum = vec3(0).toVar();
206
+ Loop(BLUR_DOWNSAMPLE * BLUR_DOWNSAMPLE, ({ i }) => {
207
+ const x = float(i)
208
+ .mod(BLUR_DOWNSAMPLE)
209
+ .sub((BLUR_DOWNSAMPLE - 1) / 2);
210
+ const y = float(i)
211
+ .div(BLUR_DOWNSAMPLE)
212
+ .floor()
213
+ .sub((BLUR_DOWNSAMPLE - 1) / 2);
214
+ sum.addAssign(input.sample(c.add(texel.mul(vec2(x, y)))).rgb);
215
+ });
216
+ const luminance = exposureMeter(vec4(sum.div(BLUR_DOWNSAMPLE * BLUR_DOWNSAMPLE), 1), c).x.max(
217
+ 2 ** LOG_MIN,
218
+ );
219
+ // Reuse G/B for conservative row-bin bounds; the blur reads only the unchanged R.
220
+ const group = c.y.mul(blurSize.y).floor().mul(blurSize.x).add(c.x.mul(blurSize.x).floor());
221
+ const minimum = float(DEPTH - 1).toVar();
222
+ const maximum = float(0).toVar();
223
+ // 1 while every sampled raw log is finite in range, so invalid input widens instead of pruning.
224
+ // Two rows is the maximum this pass proves; a larger stride widens to the full range.
225
+ const finite = this.#rangeStride.lessThanEqual(2).select(1, 0).toVar();
226
+ Loop(2 * (CELL / PACK), ({ i }) => {
227
+ const row = group.mul(this.#rangeStride).add(
228
+ float(i)
229
+ .div(CELL / PACK)
230
+ .floor(),
231
+ );
232
+ const packed = row
233
+ .mod(this.#cells.x)
234
+ .mul(CELL / PACK)
235
+ .add(float(i).mod(CELL / PACK));
236
+ const y = row.div(this.#cells.x).floor();
237
+ // Clamp to the real texels: a partial last cell or short row must not sample outside them.
238
+ const px = packed.min(this.#logSize.x.sub(1));
239
+ const py = y.min(half.y.sub(1));
240
+ const logs = this.#logTexture
241
+ .sample(vec2(px.add(0.5).div(this.#logSize.x), py.add(0.5).div(half.y)))
242
+ .level(float(0));
243
+ // 128 bounds log2 of finite f32 luminance. Invalid samples disable pruning, preserving propagation.
244
+ const inRange = logs
245
+ .greaterThanEqual(vec4(LOG_MIN))
246
+ .all()
247
+ .and(logs.lessThanEqual(vec4(128)).all());
248
+ finite.assign(finite.mul(inRange.select(1, 0)));
249
+ const position = logs
250
+ .sub(LOG_MIN)
251
+ .div(LOG_SPAN)
252
+ .clamp(0, 1)
253
+ .mul(DEPTH - 1);
254
+ minimum.assign(minimum.min(position.x).min(position.y).min(position.z).min(position.w));
255
+ maximum.assign(maximum.max(position.x).max(position.y).max(position.z).max(position.w));
256
+ });
257
+ return vec4(
258
+ luminance.log2(),
259
+ mix(float(0), minimum, finite),
260
+ mix(float(DEPTH - 1), maximum, finite),
261
+ 1,
262
+ );
263
+ })();
264
+
265
+ // Passes 3 and 4: the Gaussian of that log luminance, one axis each, mirror addressed, with the
266
+ // radius Compute1DGaussianFilterKernel takes from the width (both axes use it).
267
+ const blur = (source: ColourTexture, axis: 0 | 1): Node<"vec4"> =>
268
+ Fn(() => {
269
+ const c = uv();
270
+ const step = float(1).div(axis === 0 ? blurSize.x : blurSize.y);
271
+ const reach = radius.ceil();
272
+ const sum = float(0).toVar();
273
+ const weights = float(0).toVar();
274
+ Loop(2 * BLUR_RADIUS + 1, ({ i }) => {
275
+ const offset = float(i).sub(BLUR_RADIUS);
276
+ const t = offset.div(radius);
277
+ const weight = offset
278
+ .abs()
279
+ .lessThanEqual(reach)
280
+ .select(t.mul(t).mul(BLUR_SHAPE).exp(), 0);
281
+ const along = mirror((axis === 0 ? c.x : c.y).add(offset.mul(step)));
282
+ const at = axis === 0 ? vec2(along, c.y) : vec2(c.x, along);
283
+ sum.addAssign(source.sample(at).level(float(0)).r.mul(weight));
284
+ weights.addAssign(weight);
285
+ });
286
+ return vec4(sum.div(weights), 0, 0, 1);
287
+ })();
288
+ this.#blurXMaterial.fragmentNode = blur(this.#lumTexture, 0);
289
+ this.#blurYMaterial.fragmentNode = blur(this.#blurXTexture, 1);
290
+
291
+ // Passes 5 and 6: the bilateral grid. Each half resolution texel of a cell is shared between its
292
+ // two nearest bins of log luminance by linear weights (PostProcessHistogram.usf), and the grid
293
+ // sums the weight and the weighted log per cell and bin. Pass 5 sums each cell row, pass 6 sums
294
+ // the rows: one fragment looping over the whole cell ran 7,680 threads of 4,096 serial taps at
295
+ // 2560x1440, 1.3 ms on an RTX 2080. Unreal also spreads a cell over 64 threads and reduces their
296
+ // histograms after (UE 5.8.3: Engine/Shaders/Private/PostProcessHistogram.usf:99-102,209-224).
297
+ // A row sum texel (cell x * DEPTH / 2 + pair, cell y * CELL + row) holds bins 2 pair and 2 pair + 1
298
+ // as (log sum, weight, log sum, weight), reading the row's logs PACK at a time: one bin a texel
299
+ // read each log once per bin, 17.7M taps and 1.25 ms at 1920x1080 on Iris Xe.
300
+ this.#rowMaterial.fragmentNode = Fn(() => {
301
+ const c = uv();
302
+ const column = c.x.mul(this.#rows.x).floor();
303
+ const y = c.y.mul(this.#rows.y).floor();
304
+ const cell = column.div(DEPTH / 2).floor();
305
+ const bin = column.sub(cell.mul(DEPTH / 2)).mul(2);
306
+ const sums = vec4(0).toVar();
307
+ If(y.lessThan(half.y), () => {
308
+ // +0.5 keeps float division from rounding an exact multiple down to the previous slot.
309
+ const group = y.mul(this.#cells.x).add(cell).add(0.5).div(this.#rangeStride).floor();
310
+ const lumY = group.add(0.5).div(blurSize.x).floor();
311
+ const lumX = group.sub(lumY.mul(blurSize.x));
312
+ const bounds = this.#lumTexture
313
+ .sample(vec2(lumX.add(0.5).div(blurSize.x), lumY.add(0.5).div(blurSize.y)))
314
+ .level(float(0)).gb;
315
+ // A pair has nonzero triangular weight only inside (bin - 1, bin + 2).
316
+ If(bounds.y.greaterThan(bin.sub(1)).and(bounds.x.lessThan(bin.add(2))), () => {
317
+ Loop(CELL / PACK, ({ i }) => {
318
+ const packed = cell.mul(CELL / PACK).add(float(i));
319
+ const logs = this.#logTexture
320
+ .sample(vec2(packed.add(0.5).div(this.#logSize.x), y.add(0.5).div(half.y)))
321
+ .level(float(0));
322
+ for (const [k, lane] of (["x", "y", "z", "w"] as const).entries()) {
323
+ If(packed.mul(PACK).add(k).lessThan(half.x).and(y.lessThan(half.y)), () => {
324
+ const log = logs[lane];
325
+ const position = log
326
+ .sub(LOG_MIN)
327
+ .div(LOG_SPAN)
328
+ .clamp(0, 1)
329
+ .mul(DEPTH - 1);
330
+ const low = position.sub(bin).abs().oneMinus().max(0);
331
+ const high = position.sub(bin.add(1)).abs().oneMinus().max(0);
332
+ sums.addAssign(vec4(low.mul(log), low, high.mul(log), high));
333
+ });
334
+ }
335
+ });
336
+ });
337
+ });
338
+ return sums;
339
+ })();
340
+ // Grid texel (cell x * DEPTH + bin, cell y) holds bin and bin + 1 (the last bin twice) as
341
+ // (log sum, weight, log sum, weight), so the trilinear lookup reads both bins with one tap.
342
+ this.#gridMaterial.fragmentNode = Fn(() => {
343
+ const c = uv();
344
+ const column = c.x.mul(this.#grid.x).floor();
345
+ const row = c.y.mul(this.#grid.y).floor();
346
+ const cell = column.div(DEPTH).floor();
347
+ const bin = column.sub(cell.mul(DEPTH));
348
+ const next = bin.add(1).min(DEPTH - 1);
349
+ const at = (b: Node<"float">): Node<"float"> =>
350
+ cell
351
+ .mul(DEPTH / 2)
352
+ .add(b.div(2).floor())
353
+ .add(0.5)
354
+ .div(this.#rows.x);
355
+ const odd = (b: Node<"float">): Node<"bool"> => b.mod(2).greaterThan(0.5);
356
+ const sum = vec4(0).toVar();
357
+ Loop(CELL, ({ i }) => {
358
+ const v = row.mul(CELL).add(float(i)).add(0.5).div(this.#rows.y);
359
+ const own = this.#rowTexture.sample(vec2(at(bin), v)).level(float(0));
360
+ const above = this.#rowTexture.sample(vec2(at(next), v)).level(float(0));
361
+ sum.addAssign(vec4(odd(bin).select(own.zw, own.xy), odd(next).select(above.zw, above.xy)));
362
+ });
363
+ return sum;
364
+ })();
365
+ }
366
+
367
+ override setup(builder: NodeBuilder): Node<"float"> {
368
+ // Force the existing pass dependency, as the exposure node does.
369
+ super.setup(builder);
370
+ const settings = localExposureSettings;
371
+ const c = uv();
372
+ const rgb = this.input.rgb;
373
+ const log = exposureMeter(vec4(rgb, 1), c)
374
+ .x.max(2 ** LOG_MIN)
375
+ .log2();
376
+ const logExposure = this.#exposure.log2();
377
+
378
+ // Trilinear lookup of the grid at this pixel and this pixel's luminance bin.
379
+ const cells = this.#cells;
380
+ const gridSize = this.#grid;
381
+ const gx = c.x.mul(this.#half.x.div(CELL)).sub(0.5).clamp(0, cells.x.sub(1));
382
+ const gy = c.y.mul(this.#half.y.div(CELL)).sub(0.5).clamp(0, cells.y.sub(1));
383
+ const gz = log
384
+ .sub(LOG_MIN)
385
+ .div(LOG_SPAN)
386
+ .clamp(0, 1)
387
+ .mul(DEPTH - 1);
388
+ const x0 = gx.floor();
389
+ const y0 = gy.floor();
390
+ const z0 = gz.floor();
391
+ const fx = gx.sub(x0);
392
+ const fy = gy.sub(y0);
393
+ const fz = gz.sub(z0);
394
+ // One tap holds bin z0 and the next (the last bin twice), so the eight corners take four taps.
395
+ const fetch = (dx: number, dy: number): Node<"vec4"> => {
396
+ const x = x0.add(dx).min(cells.x.sub(1));
397
+ const y = y0.add(dy).min(cells.y.sub(1));
398
+ return this.#gridTexture
399
+ .sample(vec2(x.mul(DEPTH).add(z0).add(0.5).div(gridSize.x), y.add(0.5).div(gridSize.y)))
400
+ .level(float(0));
401
+ };
402
+ let grid: Node<"vec2"> = vec2(0);
403
+ for (const dy of [0, 1])
404
+ for (const dx of [0, 1]) {
405
+ const corner = fetch(dx, dy);
406
+ const weight = (dx ? fx : fx.oneMinus()).mul(dy ? fy : fy.oneMinus());
407
+ grid = grid.add(mix(corner.xy, corner.zw, fz).mul(weight));
408
+ }
409
+ const blurred = this.#blurTexture.sample(c).level(float(0)).r;
410
+ // A cell with no samples (the grid is built from the half resolution image) uses the blur.
411
+ const bilateral = grid.y.lessThan(0.001).select(blurred, grid.x.div(grid.y.max(0.001)));
412
+ const base = mix(bilateral, blurred, settings.blurredLuminanceBlend).add(logExposure);
413
+
414
+ const middleGrey = Math.log2(settings.middleGrey);
415
+ const centred = base.sub(middleGrey);
416
+ const contrast = centred
417
+ .greaterThan(0)
418
+ .select(settings.highlightContrastScale, settings.shadowContrastScale);
419
+ // The highlight and shadow thresholds are off at their defaults (strength 1 in Scene.cpp), so
420
+ // the gain is the contrast pull plus the detail above the base, minus the pixel itself.
421
+ const logGain = centred
422
+ .mul(contrast)
423
+ .add(log.add(logExposure).sub(base).mul(settings.detailStrength))
424
+ .add(middleGrey)
425
+ .sub(log.add(logExposure));
426
+ return logGain.exp2();
427
+ }
428
+
429
+ get gainNode(): Node<"float"> {
430
+ return nodeObject(this);
431
+ }
432
+
433
+ override updateBefore(frame: NodeFrame): undefined {
434
+ if (this.#disposed) throw new Error("Local exposure node is disposed.");
435
+ const renderer = frame.renderer;
436
+ if (renderer === null) throw new Error("Local exposure requires a renderer.");
437
+ renderer.getDrawingBufferSize(this.#size);
438
+ if (this.#configuredWidth !== this.#size.x || this.#configuredHeight !== this.#size.y) {
439
+ this.#full.value.copy(this.#size);
440
+ const sizes = localExposureSizes(this.#size.x, this.#size.y);
441
+ const [halfWidth, halfHeight] = sizes.half;
442
+ const [blurWidth, blurHeight] = sizes.blur;
443
+ const [cellsX, cellsY] = sizes.cells;
444
+ const [logWidth, logHeight] = sizes.log;
445
+ const [rowsWidth, rowsHeight] = sizes.rows;
446
+ const [gridWidth, gridHeight] = sizes.grid;
447
+ this.#half.value.set(halfWidth, halfHeight);
448
+ this.#logSize.value.set(logWidth, logHeight);
449
+ this.#rows.value.set(rowsWidth, rowsHeight);
450
+ this.#blurSize.value.set(blurWidth, blurHeight);
451
+ this.#blurRadius.value = sizes.blurRadius;
452
+ this.#rangeStride.value = sizes.rangeStride;
453
+ this.#cells.value.set(cellsX, cellsY);
454
+ this.#grid.value.set(gridWidth, gridHeight);
455
+ this.#logTarget.setSize(logWidth, logHeight);
456
+ this.#lumTarget.setSize(blurWidth, blurHeight);
457
+ this.#blurXTarget.setSize(blurWidth, blurHeight);
458
+ this.#blurTarget.setSize(blurWidth, blurHeight);
459
+ this.#rowTarget.setSize(rowsWidth, rowsHeight);
460
+ this.#gridTarget.setSize(gridWidth, gridHeight);
461
+ this.#configuredWidth = this.#size.x;
462
+ this.#configuredHeight = this.#size.y;
463
+ }
464
+ this.#rendererState ??= RendererUtils.saveRendererState(renderer);
465
+ this.#rendererState = RendererUtils.resetRendererState(renderer, this.#rendererState);
466
+ try {
467
+ for (const [material, target] of [
468
+ [this.#logMaterial, this.#logTarget],
469
+ [this.#lumMaterial, this.#lumTarget],
470
+ [this.#blurXMaterial, this.#blurXTarget],
471
+ [this.#blurYMaterial, this.#blurTarget],
472
+ [this.#rowMaterial, this.#rowTarget],
473
+ [this.#gridMaterial, this.#gridTarget],
474
+ ] as const) {
475
+ this.#quad.material = material;
476
+ renderer.setRenderTarget(target);
477
+ this.#quad.render(renderer);
478
+ }
479
+ } finally {
480
+ RendererUtils.restoreRendererState(renderer, this.#rendererState);
481
+ }
482
+ }
483
+
484
+ override dispose(): void {
485
+ if (this.#disposed) return;
486
+ this.#disposed = true;
487
+ for (const target of [
488
+ this.#logTarget,
489
+ this.#lumTarget,
490
+ this.#blurXTarget,
491
+ this.#blurTarget,
492
+ this.#rowTarget,
493
+ this.#gridTarget,
494
+ ])
495
+ target.dispose();
496
+ for (const material of [
497
+ this.#logMaterial,
498
+ this.#lumMaterial,
499
+ this.#blurXMaterial,
500
+ this.#blurYMaterial,
501
+ this.#rowMaterial,
502
+ this.#gridMaterial,
503
+ ])
504
+ material.dispose();
505
+ super.dispose();
506
+ }
507
+ }
@@ -0,0 +1,24 @@
1
+ import type { GIVisualizeMode } from "../render/gi-visualize.js";
2
+
3
+ /**
4
+ * Diagnosis knobs of the calibration harness, kept out of the engine's own reading of the page URL: the harness sets
5
+ * them before it builds a `WorldEnvironment`, and a game never needs to. The defaults are the shipped look.
6
+ */
7
+ export const lookDiagnostics: {
8
+ /** The harness ladder layer, 0 to 9 (9 is everything on): below 7 the SSGI gather is off, below 8 so are the reflections. */
9
+ layer: number;
10
+ /** Brings back the antialias stage that squeezed alpha with the colour, for the BEFORE arm of the glint proof. */
11
+ aaAlphaSqueezed: boolean;
12
+ /** Runs N denoise passes over the SSGI gather at any layer, for an A/B against the tier's count. */
13
+ denoisePasses: number | undefined;
14
+ /** Turns on the film curve's 43.7 channel clip (off by default), the ON arm of a paired capture. */
15
+ lutClipOn: boolean;
16
+ /** Draws one GI term alone (PRD-646); needs the gather, so it applies at layer 7 and above. */
17
+ giVisualize: GIVisualizeMode;
18
+ } = {
19
+ layer: 9,
20
+ aaAlphaSqueezed: false,
21
+ denoisePasses: undefined,
22
+ lutClipOn: false,
23
+ giVisualize: "off",
24
+ };
@@ -0,0 +1,42 @@
1
+ import { Fn, Loop, deltaTime, float, int, screenSize, uv, vec2, vec4 } from "three/tsl";
2
+ import type { Node, TextureNode } from "three/webgpu";
3
+
4
+ /** The look: Scene.cpp defaults. */
5
+ const motionBlurSettings = {
6
+ amount: 0.5,
7
+ /** The longest blur, as a percent of the screen width. */
8
+ maxPercent: 5,
9
+ /** The frame rate whose frame time the blur lasts for. */
10
+ targetFps: 30,
11
+ } as const;
12
+
13
+ /** Taps along the blur: enough to hide the steps at the 5 percent limit on a 1080p frame. */
14
+ const SAMPLES = 16;
15
+
16
+ /** The frame blurred along each pixel's velocity, from the colour and the velocity texture nodes. */
17
+ export function motionBlur(colour: TextureNode, velocity: TextureNode): Node<"vec4"> {
18
+ const { amount, maxPercent, targetFps } = motionBlurSettings;
19
+ return Fn(() => {
20
+ const c = uv();
21
+ const v = velocity.sample(c).xy;
22
+ const timeScale = float(1 / targetFps).div(deltaTime.max(1e-4));
23
+ // Normalised device units to pixels: half the frame size per unit, and the screen's y runs down.
24
+ const half = v
25
+ .mul(vec2(1, -1))
26
+ .mul(screenSize)
27
+ .mul(0.5)
28
+ .mul(timeScale.mul(amount * 0.5));
29
+ const limit = screenSize.x.mul(0.5 * (maxPercent / 100));
30
+ const length = half.length();
31
+ const clamped = half.mul(float(1).min(limit.div(length.max(1e-4))));
32
+ const sum = vec4(0).toVar();
33
+ Loop({ start: int(0), end: int(SAMPLES), type: "int" }, ({ i }) => {
34
+ const t = float(i)
35
+ .div(SAMPLES - 1)
36
+ .mul(2)
37
+ .sub(1);
38
+ sum.addAssign(colour.sample(c.add(clamped.mul(t).div(screenSize))).level(float(0)));
39
+ });
40
+ return length.lessThan(0.25).select(colour.sample(c), sum.div(SAMPLES));
41
+ })();
42
+ }