@threenative/core 0.3.6 → 0.3.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -5
- package/capabilities.json +739 -50
- package/dist/{assets-CqvE429w.d.ts → assets-YUbXa3-Y.d.ts} +101 -2
- package/dist/{canvas-layer-C1-5CviZ.d.ts → canvas-layer-vCtanIeB.d.ts} +1 -1
- package/dist/{game-Jz4Fdoeb.d.ts → game-cb99J-YE.d.ts} +100 -31
- package/dist/hot.d.ts +4 -4
- package/dist/hot.js +23 -5
- package/dist/index.d.ts +1742 -29
- package/dist/index.js +22443 -12423
- package/dist/{model-lod-BDAUYgsS.d.ts → model-lod-CTpZ6imz.d.ts} +1 -1
- package/dist/net.js +39 -12
- package/dist/playtest.d.ts +4 -4
- package/dist/playtest.js +48 -9
- package/dist/react-css.js +23 -0
- package/dist/react.d.ts +2 -2
- package/dist/{renderer-9yEo9hPa.d.ts → renderer-rZm0hVqq.d.ts} +178 -5
- package/dist/ui-layer.d.ts +11 -2
- package/dist/ui-layer.js +76 -4
- package/dist/worker.d.ts +36 -0
- package/dist/worker.js +1088 -0
- package/dist/world.d.ts +11 -3
- package/dist/world.js +1117 -197
- package/mcp/animation-server.mjs +265 -0
- package/mcp/animation.mjs +22 -0
- package/mcp/call.mjs +105 -0
- package/mcp/devtools.mjs +5 -0
- package/mcp/engine-server.mjs +713 -37
- package/mcp/launch.mjs +3 -2
- package/mcp/servers.d.mts +2 -0
- package/mcp/servers.mjs +33 -8
- package/package.json +12 -8
- package/patches/three@0.185.1-prd269-upgrade.patch +308 -0
- package/patches/three@0.185.1.patch +481 -272
- package/src/animation-packet-state.ts +88 -0
- package/src/animation-pose-packet.ts +537 -0
- package/src/animation.ts +779 -31
- package/src/asset-cache.ts +719 -0
- package/src/assets.ts +521 -152
- package/src/audio.ts +29 -3
- package/src/auto-batch.ts +792 -0
- package/src/config.ts +2 -0
- package/src/frame-budget.ts +268 -2
- package/src/game.ts +525 -105
- package/src/grounding.ts +7 -6
- package/src/hot.ts +19 -5
- package/src/index.ts +381 -6
- package/src/input.ts +21 -2
- package/src/interpolation.ts +19 -1
- package/src/launch-diagnostics.ts +7 -2
- package/src/look/ao-multibounce.ts +29 -0
- package/src/look/ao-reach.ts +39 -0
- package/src/look/auto-exposure.ts +264 -0
- package/src/look/default-tone-mapping.ts +44 -0
- package/src/look/exposure-graph.ts +208 -0
- package/src/look/exposure-readback.ts +97 -0
- package/src/look/exposure-settings.ts +132 -0
- package/src/look/filmic-tone-mapping.ts +852 -0
- package/src/look/gi-registry.ts +55 -0
- package/src/look/local-exposure.ts +507 -0
- package/src/look/look-diagnostics.ts +24 -0
- package/src/look/motion-blur.ts +42 -0
- package/src/look/quality.ts +309 -0
- package/src/look/reflection-trace.ts +344 -0
- package/src/look/unreal-bloom.ts +295 -0
- package/src/look/vignette.ts +14 -0
- package/src/look/world-environment.ts +2033 -0
- package/src/loop.ts +25 -1
- package/src/merge-parts.ts +25 -10
- package/src/model-lod.ts +14 -0
- package/src/net-session.ts +58 -14
- package/src/ocean/spectral.ts +41 -7
- package/src/picking.ts +72 -5
- package/src/platform.ts +29 -1
- package/src/playtest.ts +54 -8
- package/src/profiling/FrameCounters.ts +166 -5
- package/src/profiling/FrameStages.ts +289 -0
- package/src/profiling/Spans.ts +39 -25
- package/src/profiling/debug-telemetry.ts +312 -0
- package/src/profiling/scene-warning.ts +42 -6
- package/src/projection-apply.ts +11 -3
- package/src/projection-content.ts +189 -0
- package/src/projection-marker.ts +6 -2
- package/src/projection-plan.ts +279 -28
- package/src/projection-skinned.ts +620 -5
- package/src/projection-stability.ts +16 -0
- package/src/projection-uniform.ts +5 -1
- package/src/quiet-markers.ts +56 -0
- package/src/render/budget-ladder.ts +256 -0
- package/src/render/chain.ts +89 -7
- package/src/render/exposure-units.ts +59 -0
- package/src/render/frame-time-budget.ts +162 -0
- package/src/render/gi-budget.ts +231 -0
- package/src/render/gi-visualize.ts +49 -0
- package/src/render/material-key.ts +1 -0
- package/src/render/probe-volume.ts +196 -36
- package/src/render/rough-diffuse.ts +177 -0
- package/src/render/scene-trace.ts +532 -0
- package/src/render/shadow-filter-budget.ts +237 -0
- package/src/render/sky-capture.ts +194 -0
- package/src/render/soft-shadow.ts +607 -0
- package/src/render/surface-cache.ts +418 -0
- package/src/render/traced-reflections.ts +408 -0
- package/src/render/two-sided-foliage.ts +120 -0
- package/src/render/virtual-shadow-pages.ts +112 -12
- package/src/render/virtual-shadow.ts +386 -38
- package/src/render-camera-cull.ts +536 -31
- package/src/render-pass-budget.ts +140 -22
- package/src/renderProjection.ts +65 -9
- package/src/renderer-config.ts +3 -2
- package/src/renderer.ts +289 -14
- package/src/resolution-scaler.ts +65 -7
- package/src/skeletal-mesh.ts +4 -0
- package/src/snow-field.ts +46 -0
- package/src/softbody.ts +6 -5
- package/src/startup-offscreen-bytes.ts +168 -0
- package/src/startup-readiness.ts +137 -2
- package/src/ui-bridge.ts +38 -0
- package/src/ui-hit-regions.ts +6 -2
- package/src/ui-layer.ts +1 -0
- package/src/ui-state.ts +32 -3
- package/src/version.ts +1 -1
- package/src/viewport.ts +8 -5
- package/src/warmup.ts +76 -10
- package/src/worker-audio.ts +579 -0
- package/src/worker.ts +842 -0
- package/src/world-cells.ts +4 -1
- package/gpl/LICENSE.GPL +0 -117
- package/gpl/convert.py +0 -192
- package/gpl/fixtures/make_world_fixture.py +0 -184
- package/gpl/recipes/_common.py +0 -180
- package/gpl/recipes/bake_ao.py +0 -111
- package/gpl/recipes/decimate.py +0 -70
- package/gpl/recipes/export_world.py +0 -699
- package/gpl/recipes/retarget.py +0 -131
- package/gpl/recipes/unwrap.py +0 -71
- package/mcp/blender-server.mjs +0 -689
- package/mcp/blender.mjs +0 -26
|
@@ -84,11 +84,20 @@ export interface IProbeVolumeOptions {
|
|
|
84
84
|
readonly bounds: Box3 | { readonly min: IVector3Like; readonly max: IVector3Like };
|
|
85
85
|
/** Probe spacing expressed as probes per world unit. */
|
|
86
86
|
readonly density: ProbeVolumeDensity;
|
|
87
|
+
/**
|
|
88
|
+
* Where the atlas is rendered. `auto` (default) probes the device: a host that rejects a 3D render
|
|
89
|
+
* attachment (wgpu-native) renders each slice into a 2D target and copies it into the 3D atlas,
|
|
90
|
+
* and a host that accepts one renders into the atlas directly. `render3d` and `copy` force a path.
|
|
91
|
+
*/
|
|
92
|
+
readonly atlasTarget?: "auto" | "render3d" | "copy";
|
|
87
93
|
/** Optional device limit supplied by a host that knows it before construction. */
|
|
88
94
|
readonly maxTextureDimension3D?: number;
|
|
89
95
|
/** Alias for integrations that expose the WebGPU limit under a device-oriented name. */
|
|
90
96
|
readonly deviceTextureLimit?: number;
|
|
91
|
-
/**
|
|
97
|
+
/**
|
|
98
|
+
* Maximum wall-clock work per render phase, in milliseconds. A work item that outruns it fails the
|
|
99
|
+
* bake, except on a CPU rasteriser (the renderer's `softwareAdapter`), where `bakeCostMs` reports it.
|
|
100
|
+
*/
|
|
92
101
|
readonly bakeBudgetMs?: number;
|
|
93
102
|
/** Additional guard that keeps a clock-less host from processing an unbounded queue. */
|
|
94
103
|
readonly maxWorkItemsPerFrame?: number;
|
|
@@ -136,14 +145,20 @@ export function readProbeVolumeObservation(value: unknown): IProbeVolumeObservat
|
|
|
136
145
|
return isProbeVolumeObservation(value) ? value : undefined;
|
|
137
146
|
}
|
|
138
147
|
|
|
148
|
+
interface IProbeDevice {
|
|
149
|
+
readonly limits?: Record<string, unknown>;
|
|
150
|
+
readonly createTexture?: (descriptor: unknown) => { readonly destroy?: () => void };
|
|
151
|
+
readonly popErrorScope?: () => Promise<unknown>;
|
|
152
|
+
readonly pushErrorScope?: (filter: string) => void;
|
|
153
|
+
}
|
|
154
|
+
|
|
139
155
|
interface IProbeRenderer {
|
|
140
156
|
readonly autoClear?: boolean;
|
|
141
157
|
readonly compileAsync?: (scene: Object3D, camera: Camera) => Promise<void>;
|
|
142
158
|
readonly coordinateSystem?: CoordinateSystem;
|
|
143
|
-
readonly backend?: {
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
readonly device?: { readonly limits?: Record<string, unknown> };
|
|
159
|
+
readonly backend?: { readonly device?: IProbeDevice };
|
|
160
|
+
readonly device?: IProbeDevice;
|
|
161
|
+
readonly initTexture?: (texture: unknown) => void;
|
|
147
162
|
readonly shadowMap?: { autoUpdate: boolean; needsUpdate: boolean };
|
|
148
163
|
readonly toneMapping?: number;
|
|
149
164
|
readonly toneMappingExposure?: number;
|
|
@@ -266,6 +281,11 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
|
|
|
266
281
|
#projectionTarget: RenderTarget | undefined;
|
|
267
282
|
#batchTarget: RenderTarget | undefined;
|
|
268
283
|
#atlasTarget: RenderTarget3D | undefined;
|
|
284
|
+
#sliceTarget: RenderTarget | undefined;
|
|
285
|
+
readonly #requestedAtlasTarget: "auto" | "render3d" | "copy";
|
|
286
|
+
#atlasMode: "render3d" | "copy" | undefined;
|
|
287
|
+
#atlasProbeStarted = false;
|
|
288
|
+
#atlasUploaded = false;
|
|
269
289
|
#quadScene: Scene | undefined;
|
|
270
290
|
#quadCamera: OrthographicCamera | undefined;
|
|
271
291
|
#quadMesh: Mesh | undefined;
|
|
@@ -293,6 +313,7 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
|
|
|
293
313
|
this.#report = options.report ?? ((line) => console.info(line));
|
|
294
314
|
this.#now = options.now ?? (() => globalThis.performance?.now() ?? Date.now());
|
|
295
315
|
this.#bakeBudgetMs = positiveNumber(options.bakeBudgetMs ?? 2, "bakeBudgetMs");
|
|
316
|
+
this.#requestedAtlasTarget = options.atlasTarget ?? "auto";
|
|
296
317
|
this.#maxWorkItemsPerFrame = positiveInteger(
|
|
297
318
|
options.maxWorkItemsPerFrame ?? 1,
|
|
298
319
|
"maxWorkItemsPerFrame",
|
|
@@ -349,6 +370,11 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
|
|
|
349
370
|
return this.#atlasTexture;
|
|
350
371
|
}
|
|
351
372
|
|
|
373
|
+
/** The atlas render path in use; `undefined` until the device probe settles. */
|
|
374
|
+
get atlasTarget(): "render3d" | "copy" | undefined {
|
|
375
|
+
return this.#atlasMode;
|
|
376
|
+
}
|
|
377
|
+
|
|
352
378
|
get atlasDepth(): number {
|
|
353
379
|
return this.#atlasDepth;
|
|
354
380
|
}
|
|
@@ -415,6 +441,7 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
|
|
|
415
441
|
const raw = renderer.raw as IProbeRenderer;
|
|
416
442
|
const deviceLimit = readTextureLimit(raw);
|
|
417
443
|
if (deviceLimit !== undefined) assertTextureLimit(this.maximumDimension, deviceLimit);
|
|
444
|
+
this.#startAtlasProbe(raw);
|
|
418
445
|
this.#ensureGpuResources();
|
|
419
446
|
if (this.#pending !== undefined) this.#prepareBake(this.#pending.scene, this.#pending.passes);
|
|
420
447
|
}
|
|
@@ -509,11 +536,29 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
|
|
|
509
536
|
return result.max(new Vector3());
|
|
510
537
|
}
|
|
511
538
|
|
|
512
|
-
/**
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
539
|
+
/**
|
|
540
|
+
* The irradiance averaged over every normal at a point, for a surface or a sample that has no side facing the light:
|
|
541
|
+
* a translucent pane (Unreal's default Volumetric NonDirectional lighting) and a fog sample (its isotropic term). It
|
|
542
|
+
* is the L0 coefficient, `0.886227 * c0`, so it is the mean of `sample(position, n)` over any set of normals that
|
|
543
|
+
* integrates the L2 basis, the six axes among them. It reads one atlas texel, where `sample` reads seven.
|
|
544
|
+
*
|
|
545
|
+
* Divide by pi for the mean radiance a fog sample scatters, and multiply by the colour for a pane: the volume owns
|
|
546
|
+
* no colour.
|
|
547
|
+
*/
|
|
548
|
+
sampleNonDirectional(position: Vector3): Vector3;
|
|
549
|
+
sampleNonDirectional(position?: Node<"vec3">): Node<"vec3">;
|
|
550
|
+
sampleNonDirectional(position: IProbePosition = positionWorld): Vector3 | Node<"vec3"> {
|
|
551
|
+
if (position instanceof Vector3) {
|
|
552
|
+
const c = this.#samplePackedCoefficients(position);
|
|
553
|
+
return new Vector3(c[0] ?? 0, c[1] ?? 0, c[2] ?? 0)
|
|
554
|
+
.multiplyScalar(0.886227)
|
|
555
|
+
.max(new Vector3());
|
|
556
|
+
}
|
|
557
|
+
return this.#atlasNode.sample(this.#atlasAt(position)(0)).rgb.mul(0.886227).max(0);
|
|
558
|
+
}
|
|
559
|
+
|
|
560
|
+
/** The atlas coordinate of a world position inside each packed sub-volume. */
|
|
561
|
+
#atlasAt(position: Node<"vec3">): (subVolume: number) => Node<"vec3"> {
|
|
517
562
|
const local = clamp(vec3(position).sub(this.#boundsMinNode).div(this.#boundsSizeNode), 0, 1);
|
|
518
563
|
const atlasX = local.x
|
|
519
564
|
.mul(this.resolution.x - 1)
|
|
@@ -524,13 +569,24 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
|
|
|
524
569
|
.add(0.5)
|
|
525
570
|
.div(this.resolution.y);
|
|
526
571
|
const sliceStride = this.resolution.z + 2 * SAMPLE_ATLAS_PADDING;
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
.
|
|
532
|
-
|
|
533
|
-
|
|
572
|
+
return (subVolume) =>
|
|
573
|
+
vec3(
|
|
574
|
+
atlasX,
|
|
575
|
+
atlasY,
|
|
576
|
+
local.z
|
|
577
|
+
.mul(this.resolution.z - 1)
|
|
578
|
+
.add(SAMPLE_ATLAS_PADDING + 0.5 + subVolume * sliceStride)
|
|
579
|
+
.div(this.#atlasDepth),
|
|
580
|
+
);
|
|
581
|
+
}
|
|
582
|
+
|
|
583
|
+
/** The GPU graph used by `sample`; exposed so generated materials can compose it explicitly. */
|
|
584
|
+
sampleNode(
|
|
585
|
+
position: Node<"vec3"> = positionWorld,
|
|
586
|
+
normal: Node<"vec3"> = normalWorld,
|
|
587
|
+
): Node<"vec3"> {
|
|
588
|
+
const atlasAt = this.#atlasAt(position);
|
|
589
|
+
const packed = (subVolume: number) => this.#atlasNode.sample(atlasAt(subVolume));
|
|
534
590
|
const packedValues = Array.from({ length: PACKED_SUB_VOLUME_COUNT }, (_, index) =>
|
|
535
591
|
packed(index),
|
|
536
592
|
);
|
|
@@ -614,6 +670,7 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
|
|
|
614
670
|
this.#publish(false);
|
|
615
671
|
return;
|
|
616
672
|
}
|
|
673
|
+
this.#ensureGpuResources();
|
|
617
674
|
if (this.#sceneState === undefined)
|
|
618
675
|
this.#prepareBake(this.#pending.scene, this.#pending.passes);
|
|
619
676
|
this.#processPending(this.#pending);
|
|
@@ -634,6 +691,7 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
|
|
|
634
691
|
|
|
635
692
|
#processPending(pending: IPendingBake): void {
|
|
636
693
|
const started = this.#now();
|
|
694
|
+
const softwareRaster = this.#renderer?.softwareAdapter !== undefined;
|
|
637
695
|
let workItems = 0;
|
|
638
696
|
try {
|
|
639
697
|
while (this.#pending !== undefined && workItems < this.#maxWorkItemsPerFrame) {
|
|
@@ -644,12 +702,14 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
|
|
|
644
702
|
const itemCostMs = Math.max(0, this.#now() - itemStarted);
|
|
645
703
|
this.#maxWorkItemCostMs = Math.max(this.#maxWorkItemCostMs, itemCostMs);
|
|
646
704
|
const elapsed = Math.max(0, this.#now() - started);
|
|
647
|
-
|
|
705
|
+
// A CPU rasteriser cannot hold a hardware frame budget: one cube-face draw costs 12 to 18 ms on
|
|
706
|
+
// SwiftShader. The bake still runs one measured item at a time; `bakeCostMs` reports the overrun.
|
|
707
|
+
if (!softwareRaster && itemCostMs > this.#bakeBudgetMs + BAKE_BUDGET_SLACK_MS) {
|
|
648
708
|
throw new Error(
|
|
649
709
|
`ProbeVolume bake work item cost ${itemCostMs}ms exceeds bakeBudgetMs ${this.#bakeBudgetMs}ms plus ${BAKE_BUDGET_SLACK_MS}ms scheduling slack.`,
|
|
650
710
|
);
|
|
651
711
|
}
|
|
652
|
-
if (elapsed > this.#bakeBudgetMs + BAKE_BUDGET_SLACK_MS) {
|
|
712
|
+
if (!softwareRaster && elapsed > this.#bakeBudgetMs + BAKE_BUDGET_SLACK_MS) {
|
|
653
713
|
throw new Error(
|
|
654
714
|
`ProbeVolume bake frame cost ${elapsed}ms exceeds bakeBudgetMs ${this.#bakeBudgetMs}ms plus ${BAKE_BUDGET_SLACK_MS}ms scheduling slack.`,
|
|
655
715
|
);
|
|
@@ -678,6 +738,7 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
|
|
|
678
738
|
this.#projectionTarget?.dispose();
|
|
679
739
|
this.#batchTarget?.dispose();
|
|
680
740
|
this.#atlasTarget?.dispose();
|
|
741
|
+
this.#sliceTarget?.dispose();
|
|
681
742
|
this.#emptyAtlasTexture.dispose();
|
|
682
743
|
this.#projectionMaterial?.dispose();
|
|
683
744
|
for (const material of this.#repackMaterials ?? []) material.dispose();
|
|
@@ -687,6 +748,7 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
|
|
|
687
748
|
this.#projectionTarget = undefined;
|
|
688
749
|
this.#batchTarget = undefined;
|
|
689
750
|
this.#atlasTarget = undefined;
|
|
751
|
+
this.#sliceTarget = undefined;
|
|
690
752
|
this.#projectionMaterial = undefined;
|
|
691
753
|
this.#repackMaterials = undefined;
|
|
692
754
|
this.#atlasTexture = createCpuAtlas(this.#atlasData, this.resolution, this.#atlasDepth);
|
|
@@ -708,8 +770,59 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
|
|
|
708
770
|
);
|
|
709
771
|
}
|
|
710
772
|
|
|
773
|
+
/**
|
|
774
|
+
* Ask the device whether it accepts a 3D render attachment, as the atlas target needs one. WebGPU
|
|
775
|
+
* names no capability for it, so the probe creates the texture inside a validation scope. The bake
|
|
776
|
+
* waits for the answer through `#gpuWarmupSettled`; a host with no error scopes keeps the 3D path.
|
|
777
|
+
*/
|
|
778
|
+
#startAtlasProbe(raw: IProbeRenderer): void {
|
|
779
|
+
if (this.#atlasMode !== undefined || this.#atlasProbeStarted) return;
|
|
780
|
+
const device = raw.backend?.device ?? raw.device;
|
|
781
|
+
const { createTexture, popErrorScope, pushErrorScope } = device ?? {};
|
|
782
|
+
if (this.#requestedAtlasTarget !== "auto") {
|
|
783
|
+
this.#atlasMode = this.#requestedAtlasTarget;
|
|
784
|
+
} else if (
|
|
785
|
+
device === undefined ||
|
|
786
|
+
createTexture === undefined ||
|
|
787
|
+
popErrorScope === undefined ||
|
|
788
|
+
pushErrorScope === undefined
|
|
789
|
+
) {
|
|
790
|
+
this.#atlasMode = "render3d";
|
|
791
|
+
} else {
|
|
792
|
+
this.#atlasProbeStarted = true;
|
|
793
|
+
this.#gpuWarmupSettled = false;
|
|
794
|
+
let probe: { readonly destroy?: () => void } | undefined;
|
|
795
|
+
let created = true;
|
|
796
|
+
pushErrorScope.call(device, "validation");
|
|
797
|
+
try {
|
|
798
|
+
// GPUTextureUsage.TEXTURE_BINDING | RENDER_ATTACHMENT, the usage of the atlas render target.
|
|
799
|
+
probe = createTexture.call(device, {
|
|
800
|
+
dimension: "3d",
|
|
801
|
+
format: "rgba32float",
|
|
802
|
+
size: [1, 1, 1],
|
|
803
|
+
usage: 0x04 | 0x10,
|
|
804
|
+
});
|
|
805
|
+
} catch {
|
|
806
|
+
created = false;
|
|
807
|
+
}
|
|
808
|
+
popErrorScope.call(device).then(
|
|
809
|
+
(error) =>
|
|
810
|
+
this.#settleAtlasProbe(created && (error === null || error === undefined), probe),
|
|
811
|
+
() => this.#settleAtlasProbe(true, probe),
|
|
812
|
+
);
|
|
813
|
+
}
|
|
814
|
+
}
|
|
815
|
+
|
|
816
|
+
#settleAtlasProbe(accepted: boolean, probe: { readonly destroy?: () => void } | undefined): void {
|
|
817
|
+
probe?.destroy?.();
|
|
818
|
+
this.#atlasMode = accepted ? "render3d" : "copy";
|
|
819
|
+
this.#gpuWarmupSettled = true;
|
|
820
|
+
}
|
|
821
|
+
|
|
711
822
|
#ensureGpuResources(): void {
|
|
712
823
|
if (this.#cubeRenderTarget !== undefined) return;
|
|
824
|
+
const atlasMode = this.#atlasMode;
|
|
825
|
+
if (atlasMode === undefined) return;
|
|
713
826
|
this.#cubeRenderTarget = new CubeRenderTarget(this.#cubemapSize, {
|
|
714
827
|
depthBuffer: true,
|
|
715
828
|
generateMipmaps: false,
|
|
@@ -732,15 +845,31 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
|
|
|
732
845
|
minFilter: NearestFilter,
|
|
733
846
|
type: FloatType,
|
|
734
847
|
});
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
848
|
+
if (atlasMode === "render3d") {
|
|
849
|
+
this.#atlasTarget = new RenderTarget3D(
|
|
850
|
+
this.resolution.x,
|
|
851
|
+
this.resolution.y,
|
|
852
|
+
this.#atlasDepth,
|
|
853
|
+
{
|
|
854
|
+
depthBuffer: false,
|
|
855
|
+
generateMipmaps: false,
|
|
856
|
+
magFilter: LinearFilter,
|
|
857
|
+
minFilter: LinearFilter,
|
|
858
|
+
type: FloatType,
|
|
859
|
+
},
|
|
860
|
+
);
|
|
861
|
+
this.#atlasTexture = this.#atlasTarget.texture as Data3DTexture;
|
|
862
|
+
this.#atlasTexture.format = RGBAFormat;
|
|
863
|
+
} else {
|
|
864
|
+
// The atlas stays the plain 3D texture made at construction; slices are rendered here and copied in.
|
|
865
|
+
this.#sliceTarget = new RenderTarget(this.resolution.x, this.resolution.y, {
|
|
866
|
+
depthBuffer: false,
|
|
867
|
+
generateMipmaps: false,
|
|
868
|
+
magFilter: NearestFilter,
|
|
869
|
+
minFilter: NearestFilter,
|
|
870
|
+
type: FloatType,
|
|
871
|
+
});
|
|
872
|
+
}
|
|
744
873
|
this.#setSamplingIsolated(this.#samplingIsolated);
|
|
745
874
|
this.#quadCamera = new OrthographicCamera(-1, 1, 1, -1, 0, 1);
|
|
746
875
|
this.#quadMesh = new Mesh(new PlaneGeometry(2, 2));
|
|
@@ -762,7 +891,7 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
|
|
|
762
891
|
if (this.#gpuWarmupStarted) return;
|
|
763
892
|
const projectionTarget = this.#projectionTarget;
|
|
764
893
|
const projectionMaterial = this.#projectionMaterial;
|
|
765
|
-
const atlasTarget = this.#atlasTarget;
|
|
894
|
+
const atlasTarget = this.#atlasTarget ?? this.#sliceTarget;
|
|
766
895
|
const repackMaterials = this.#repackMaterials;
|
|
767
896
|
if (
|
|
768
897
|
projectionTarget === undefined ||
|
|
@@ -775,7 +904,11 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
|
|
|
775
904
|
// First-use shader work belongs to scene entry, before bounded bake slices are presented.
|
|
776
905
|
this.#renderQuad(projectionTarget, projectionMaterial);
|
|
777
906
|
repackMaterials.forEach((material, index) => {
|
|
778
|
-
this.#renderQuad(
|
|
907
|
+
this.#renderQuad(
|
|
908
|
+
atlasTarget,
|
|
909
|
+
material,
|
|
910
|
+
this.#atlasTarget === undefined ? undefined : index * this.paddedSlices,
|
|
911
|
+
);
|
|
779
912
|
});
|
|
780
913
|
}
|
|
781
914
|
|
|
@@ -969,7 +1102,7 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
|
|
|
969
1102
|
}
|
|
970
1103
|
|
|
971
1104
|
#repackSliceToAtlas(repackIndex: number): void {
|
|
972
|
-
const atlasTarget = this.#atlasTarget;
|
|
1105
|
+
const atlasTarget = this.#atlasTarget ?? this.#sliceTarget;
|
|
973
1106
|
const materials = this.#repackMaterials;
|
|
974
1107
|
if (atlasTarget === undefined || materials === undefined) {
|
|
975
1108
|
throw new Error("ProbeVolume repack resources were not initialized.");
|
|
@@ -980,10 +1113,35 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
|
|
|
980
1113
|
this.#repackSlice.value = sourceSlice;
|
|
981
1114
|
atlasTarget.viewport.set(0, 0, this.resolution.x, this.resolution.y);
|
|
982
1115
|
atlasTarget.scissorTest = false;
|
|
983
|
-
|
|
984
|
-
|
|
985
|
-
|
|
986
|
-
|
|
1116
|
+
const material = valueAt(materials, subVolume, "repack material");
|
|
1117
|
+
const atlasSlice = subVolume * this.paddedSlices + localSlice;
|
|
1118
|
+
if (this.#atlasTarget !== undefined) {
|
|
1119
|
+
this.#renderQuad(atlasTarget, material, atlasSlice);
|
|
1120
|
+
return;
|
|
1121
|
+
}
|
|
1122
|
+
this.#renderQuad(atlasTarget, material);
|
|
1123
|
+
this.#copySliceToAtlas(atlasSlice);
|
|
1124
|
+
}
|
|
1125
|
+
|
|
1126
|
+
/** The atlas path for a device with no 3D render attachment: the 2D slice target joins the 3D atlas. */
|
|
1127
|
+
#copySliceToAtlas(atlasSlice: number): void {
|
|
1128
|
+
const raw = this.#rawRenderer();
|
|
1129
|
+
const source = this.#sliceTarget;
|
|
1130
|
+
if (source === undefined || raw.copyTextureToTexture === undefined) {
|
|
1131
|
+
throw new Error(
|
|
1132
|
+
"ProbeVolume requires WebGPU texture-to-texture copies for its atlas slices.",
|
|
1133
|
+
);
|
|
1134
|
+
}
|
|
1135
|
+
if (!this.#atlasUploaded) {
|
|
1136
|
+
// The copy needs the GPU atlas to exist; its first upload is the zero-filled CPU atlas.
|
|
1137
|
+
raw.initTexture?.(this.#atlasTexture);
|
|
1138
|
+
this.#atlasUploaded = true;
|
|
1139
|
+
}
|
|
1140
|
+
raw.copyTextureToTexture(
|
|
1141
|
+
source.texture,
|
|
1142
|
+
this.#atlasTexture,
|
|
1143
|
+
new Box2(new Vector2(0, 0), new Vector2(this.resolution.x, this.resolution.y)),
|
|
1144
|
+
new Vector3(0, 0, atlasSlice),
|
|
987
1145
|
);
|
|
988
1146
|
}
|
|
989
1147
|
|
|
@@ -1048,7 +1206,9 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
|
|
|
1048
1206
|
#clearPreviousBake(): void {
|
|
1049
1207
|
this.#coefficients.fill(0);
|
|
1050
1208
|
this.#atlasData.fill(0);
|
|
1051
|
-
if (this.#atlasTarget === undefined
|
|
1209
|
+
if (this.#atlasTarget === undefined && this.#sliceTarget === undefined) {
|
|
1210
|
+
this.#atlasTexture.needsUpdate = true;
|
|
1211
|
+
}
|
|
1052
1212
|
}
|
|
1053
1213
|
|
|
1054
1214
|
#setSamplingIsolated(isolated: boolean): void {
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
import type { Light, Material, Mesh, Object3D } from "three";
|
|
2
|
+
import {
|
|
3
|
+
clamp,
|
|
4
|
+
diffuseColor,
|
|
5
|
+
metalness,
|
|
6
|
+
normalView,
|
|
7
|
+
positionViewDirection,
|
|
8
|
+
roughness,
|
|
9
|
+
uniform,
|
|
10
|
+
vec3,
|
|
11
|
+
} from "three/tsl";
|
|
12
|
+
import { MeshPhysicalNodeMaterial, MeshStandardNodeMaterial, type Node } from "three/webgpu";
|
|
13
|
+
|
|
14
|
+
declare module "three" {
|
|
15
|
+
// quality-allow: declaration merging needs three's own interface name, and the naming rule would demand an I prefix
|
|
16
|
+
// biome-ignore lint/style/useNamingConvention: a module augmentation keeps three's own class name.
|
|
17
|
+
interface Material {
|
|
18
|
+
/**
|
|
19
|
+
* Unreal's Substrate rough diffuse, the EON model (PRD-653): direct light shades the diffuse lobe of a
|
|
20
|
+
* standard or physical material with EON where three shades Lambert. The default is off. Indirect light
|
|
21
|
+
* stays Lambert, and a material changed after its first draw needs `needsUpdate`.
|
|
22
|
+
*/
|
|
23
|
+
roughDiffuse?: boolean;
|
|
24
|
+
}
|
|
25
|
+
// quality-allow: declaration merging needs three's own interface name, and the naming rule would demand an I prefix
|
|
26
|
+
// biome-ignore lint/style/useNamingConvention: a module augmentation keeps three's own class name.
|
|
27
|
+
interface PointLight {
|
|
28
|
+
/** Unreal's Source Radius in metres: how large the lamp is. A rough diffuse surface blends back to Lambert at 20 cm. */
|
|
29
|
+
sourceRadius?: number;
|
|
30
|
+
}
|
|
31
|
+
// quality-allow: declaration merging needs three's own interface name, and the naming rule would demand an I prefix
|
|
32
|
+
// biome-ignore lint/style/useNamingConvention: a module augmentation keeps three's own class name.
|
|
33
|
+
interface SpotLight {
|
|
34
|
+
/** Unreal's Source Radius in metres, as on PointLight. */
|
|
35
|
+
sourceRadius?: number;
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** Diffuse_GGX_Rough (Engine/Shaders/Private/BRDF.ush): EON's roughness is 0.4 x the material's. */
|
|
40
|
+
const ROUGHNESS_SCALE = 0.4;
|
|
41
|
+
/** The same function weights EON by the lamp's size: a lamp of 20 cm or more is shaded as Lambert. */
|
|
42
|
+
const SIZE_LIMIT = 0.2;
|
|
43
|
+
/** The EON model's fit constants (Portsmouth, Kutz and Hill), the ones the native engine's standard program holds too. */
|
|
44
|
+
const SINGLE_LOSS = 1 - 1 / (1 + (0.5 - 2 / (3 * Math.PI)));
|
|
45
|
+
const MULTI_TILT = 0.262048;
|
|
46
|
+
const ALBEDO_GAIN = 0.189468;
|
|
47
|
+
const EPSILON = 1e-6;
|
|
48
|
+
|
|
49
|
+
type Lamp = Light & { readonly isDirectionalLight?: boolean; readonly sourceRadius?: number };
|
|
50
|
+
|
|
51
|
+
/** The lighting model's `direct`, as far as this module drives it. */
|
|
52
|
+
interface IDirectInput {
|
|
53
|
+
readonly lightDirection: Node<"vec3">;
|
|
54
|
+
readonly lightNode?: { readonly light?: Lamp };
|
|
55
|
+
readonly reflectedLight: { readonly directDiffuse: Node<"vec3"> };
|
|
56
|
+
}
|
|
57
|
+
interface ILightingModel {
|
|
58
|
+
direct(input: IDirectInput, builder: unknown): void;
|
|
59
|
+
}
|
|
60
|
+
interface IPatchable {
|
|
61
|
+
setupLightingModel?: (this: Material, builder: unknown) => ILightingModel;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
const sourceRadii = new WeakMap<object, Node<"float">>();
|
|
65
|
+
const installed = new WeakSet<object>();
|
|
66
|
+
|
|
67
|
+
/** Undefined for a sun, else `1 - sourceRadius / 20 cm` held in 0..1; the radius is read each render. */
|
|
68
|
+
function lampWeight(light: Lamp | undefined): Node<"float"> | undefined {
|
|
69
|
+
if (light === undefined || light.isDirectionalLight === true) return undefined;
|
|
70
|
+
let radius = sourceRadii.get(light);
|
|
71
|
+
if (radius === undefined) {
|
|
72
|
+
radius = uniform(0).onRenderUpdate(() => light.sourceRadius ?? 0) as Node<"float">;
|
|
73
|
+
sourceRadii.set(light, radius);
|
|
74
|
+
}
|
|
75
|
+
return clamp(radius.mul(1 / SIZE_LIMIT).oneMinus()) as Node<"float">;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* EON's factor on Lambert for one light, so `albedo / pi * factor` is the EON BRDF (Portsmouth, Kutz and Hill). It is 1 at
|
|
80
|
+
* r = 0, and it never divides by the albedo, so black stays black. The native engine's standard program holds the same
|
|
81
|
+
* arithmetic (`roughDiffuseFactor` in shader/standard.cpp); `conformance/registry.json` keeps the two equal.
|
|
82
|
+
*/
|
|
83
|
+
function roughDiffuseFactor(
|
|
84
|
+
albedo: Node<"vec3">,
|
|
85
|
+
r: Node<"float">,
|
|
86
|
+
nov: Node<"float">,
|
|
87
|
+
nol: Node<"float">,
|
|
88
|
+
vol: Node<"float">,
|
|
89
|
+
): Node<"vec3"> {
|
|
90
|
+
const s = vol.sub(nov.mul(nol));
|
|
91
|
+
const sOverT = s.div(nov.max(nol).max(EPSILON)).max(s);
|
|
92
|
+
const single = r.mul(SINGLE_LOSS).oneMinus();
|
|
93
|
+
const front = single.mul(r.mul(sOverT).add(1));
|
|
94
|
+
const multi = single.mul(r.mul(MULTI_TILT).mul(nov.oneMinus()).add(1)).oneMinus();
|
|
95
|
+
const gain = albedo.oneMinus().mul(ALBEDO_GAIN).mul(r).add(1);
|
|
96
|
+
return gain.mul(front.add(albedo.mul(gain).mul(multi))) as Node<"vec3">;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* Turns a stock lighting model's Lambert diffuse into EON. The model adds irradiance x Lambert to `directDiffuse`; that term
|
|
101
|
+
* goes into a scratch variable here and returns scaled by EON's factor, so whatever else the model multiplies it by (sheen's
|
|
102
|
+
* energy compensation) stays in, and the specular and clearcoat terms are untouched.
|
|
103
|
+
*/
|
|
104
|
+
function roughen(model: ILightingModel): ILightingModel {
|
|
105
|
+
const lambert = model.direct;
|
|
106
|
+
model.direct = function direct(
|
|
107
|
+
this: ILightingModel,
|
|
108
|
+
input: IDirectInput,
|
|
109
|
+
builder: unknown,
|
|
110
|
+
): void {
|
|
111
|
+
const scratch = vec3(0).toVar() as Node<"vec3">;
|
|
112
|
+
lambert.call(
|
|
113
|
+
this,
|
|
114
|
+
{ ...input, reflectedLight: { ...input.reflectedLight, directDiffuse: scratch } },
|
|
115
|
+
builder,
|
|
116
|
+
);
|
|
117
|
+
const nov = clamp(normalView.dot(positionViewDirection)) as Node<"float">;
|
|
118
|
+
const nol = clamp(normalView.dot(input.lightDirection)) as Node<"float">;
|
|
119
|
+
const vol = positionViewDirection.dot(input.lightDirection) as Node<"float">;
|
|
120
|
+
let r = roughness.mul(ROUGHNESS_SCALE) as Node<"float">;
|
|
121
|
+
const weight = lampWeight(input.lightNode?.light);
|
|
122
|
+
if (weight !== undefined) r = r.mul(weight) as Node<"float">;
|
|
123
|
+
// three's diffuseContribution, which three/tsl does not export: the colour less its metal share.
|
|
124
|
+
const albedo = diffuseColor.rgb.mul(metalness.oneMinus()) as Node<"vec3">;
|
|
125
|
+
const factor = roughDiffuseFactor(albedo, r, nov, nol, vol);
|
|
126
|
+
(
|
|
127
|
+
input.reflectedLight.directDiffuse as Node<"vec3"> & { addAssign(value: Node): void }
|
|
128
|
+
).addAssign(scratch.mul(factor));
|
|
129
|
+
};
|
|
130
|
+
return model;
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* Hooks `setupLightingModel` of three's standard and physical node materials once, so a material with `roughDiffuse` set
|
|
135
|
+
* shades its direct diffuse with EON. A material without it gets three's own model back untouched. Idempotent. Call
|
|
136
|
+
* {@link useRoughDiffuse} to mark the materials as well.
|
|
137
|
+
*/
|
|
138
|
+
export function installRoughDiffuse(): void {
|
|
139
|
+
for (const material of [MeshStandardNodeMaterial, MeshPhysicalNodeMaterial]) {
|
|
140
|
+
// quality-allow: three's setupLightingModel types its direct input as LightingModelDirectInput, which IDirectInput narrows to the fields read here
|
|
141
|
+
const proto = material?.prototype as unknown as IPatchable | undefined;
|
|
142
|
+
const original = proto?.setupLightingModel;
|
|
143
|
+
if (proto === undefined || original === undefined || installed.has(proto)) continue;
|
|
144
|
+
installed.add(proto);
|
|
145
|
+
proto.setupLightingModel = function setupLightingModel(this: Material, builder: unknown) {
|
|
146
|
+
const model = original.call(this, builder);
|
|
147
|
+
return this.roughDiffuse === true ? roughen(model) : model;
|
|
148
|
+
};
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
/** The Node variants set no `isMeshStandardMaterial`, so the type name is the one test that covers three and the owned engine. */
|
|
153
|
+
const STANDARD = /^Mesh(?:Standard|Physical)(?:Node)?Material$/u;
|
|
154
|
+
|
|
155
|
+
function isStandard(material: unknown): material is Material {
|
|
156
|
+
return STANDARD.test((material as { type?: string } | null)?.type ?? "");
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
/**
|
|
160
|
+
* Shades every standard and physical material under `root` the way Unreal's Substrate does a rough surface: direct light
|
|
161
|
+
* meets the diffuse lobe with the EON model, not Lambert. Returns how many materials changed. `enabled: false` puts Lambert
|
|
162
|
+
* back. The owned engine reads `material.roughDiffuse` itself; on three's own WebGPU renderer this also installs the hook.
|
|
163
|
+
*/
|
|
164
|
+
export function useRoughDiffuse(root: Object3D, enabled = true): number {
|
|
165
|
+
installRoughDiffuse();
|
|
166
|
+
let changed = 0;
|
|
167
|
+
root.traverse((object) => {
|
|
168
|
+
const material = (object as Partial<Mesh>).material;
|
|
169
|
+
for (const each of Array.isArray(material) ? material : [material]) {
|
|
170
|
+
if (!isStandard(each) || (each.roughDiffuse === true) === enabled) continue;
|
|
171
|
+
each.roughDiffuse = enabled;
|
|
172
|
+
each.needsUpdate = true;
|
|
173
|
+
changed++;
|
|
174
|
+
}
|
|
175
|
+
});
|
|
176
|
+
return changed;
|
|
177
|
+
}
|