@threenative/core 0.3.5 → 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-Bj8G1wmD.d.ts → game-cb99J-YE.d.ts} +112 -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 +22445 -12411
- 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 +59 -10
- 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 +544 -106
- 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 +40 -6
- 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 +69 -12
- 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
|
@@ -0,0 +1,607 @@
|
|
|
1
|
+
import {
|
|
2
|
+
type CubeTexture,
|
|
3
|
+
type DepthTexture,
|
|
4
|
+
GreaterEqualCompare,
|
|
5
|
+
LessEqualCompare,
|
|
6
|
+
type LightShadow,
|
|
7
|
+
type OrthographicCamera,
|
|
8
|
+
type PerspectiveCamera,
|
|
9
|
+
} from "three";
|
|
10
|
+
import {
|
|
11
|
+
Fn,
|
|
12
|
+
If,
|
|
13
|
+
cameraPosition,
|
|
14
|
+
cross,
|
|
15
|
+
cubeTexture,
|
|
16
|
+
dFdx,
|
|
17
|
+
dFdy,
|
|
18
|
+
float,
|
|
19
|
+
ivec2,
|
|
20
|
+
max,
|
|
21
|
+
min,
|
|
22
|
+
positionWorld,
|
|
23
|
+
reference,
|
|
24
|
+
sqrt,
|
|
25
|
+
step,
|
|
26
|
+
type texture,
|
|
27
|
+
textureLoad,
|
|
28
|
+
uniform,
|
|
29
|
+
vec2,
|
|
30
|
+
vec3,
|
|
31
|
+
} from "three/tsl";
|
|
32
|
+
import type { Node } from "three/webgpu";
|
|
33
|
+
|
|
34
|
+
/** tan(5 degrees): Unreal's `r.Shadow.Virtual.SubsurfaceShadowMinSourceAngle`, the sun's least source on a leaf. */
|
|
35
|
+
export const LEAF_MIN_SOURCE_TANGENT = Math.tan((5 * Math.PI) / 180);
|
|
36
|
+
|
|
37
|
+
declare module "three" {
|
|
38
|
+
// quality-allow: declaration merging needs three's own interface name, and the naming rule would demand an I prefix
|
|
39
|
+
// biome-ignore lint/style/useNamingConvention: a module augmentation keeps three's own class name.
|
|
40
|
+
interface Material {
|
|
41
|
+
/**
|
|
42
|
+
* Unreal's Two Sided Foliage shading model (PRD-651). The receiver looks its shadow up where it
|
|
43
|
+
* stands, without the normal bias, and sees a sun of at least 5 degrees. The default is off: a
|
|
44
|
+
* card with two sides and a cut is a default lit material in Unreal, and keeps the normal bias.
|
|
45
|
+
*/
|
|
46
|
+
twoSidedFoliage?: boolean;
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* A receiver marked `twoSidedFoliage` (PRD-651). Unreal gives its Two Sided Foliage and subsurface
|
|
52
|
+
* pixels no normal bias and a sun source of at least 5 degrees, because a thin leaf biased along its
|
|
53
|
+
* normal either shades itself or lets light through. The sides and the cut do not choose this: Unreal
|
|
54
|
+
* reads the shading model, so the rule reads the marker and never infers it.
|
|
55
|
+
*/
|
|
56
|
+
export function isLeafReceiver(
|
|
57
|
+
material: { readonly twoSidedFoliage?: boolean } | null | undefined,
|
|
58
|
+
): boolean {
|
|
59
|
+
return material?.twoSidedFoliage === true;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** The tangent of the source angle a receiver sees: a leaf receiver sees at least 5 degrees. */
|
|
63
|
+
export function receiverSourceTangent(
|
|
64
|
+
material: Parameters<typeof isLeafReceiver>[0],
|
|
65
|
+
tangent: number,
|
|
66
|
+
): number {
|
|
67
|
+
return isLeafReceiver(material) ? Math.max(tangent, LEAF_MIN_SOURCE_TANGENT) : tangent;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** World-space gap to UV radius; sourceAngleRad is in radians, in [0, PI/2). */
|
|
71
|
+
export function penumbraUv(
|
|
72
|
+
gapMetres: number,
|
|
73
|
+
sourceAngleRad: number,
|
|
74
|
+
frustumWidthMetres: number,
|
|
75
|
+
mapSize: number,
|
|
76
|
+
): number {
|
|
77
|
+
for (const [name, value] of Object.entries({
|
|
78
|
+
gapMetres,
|
|
79
|
+
sourceAngleRad,
|
|
80
|
+
frustumWidthMetres,
|
|
81
|
+
mapSize,
|
|
82
|
+
})) {
|
|
83
|
+
if (!Number.isFinite(value) || value < 0)
|
|
84
|
+
throw new RangeError(`${name} must be finite and non-negative`);
|
|
85
|
+
}
|
|
86
|
+
if (sourceAngleRad >= Math.PI / 2 || frustumWidthMetres === 0 || mapSize === 0) {
|
|
87
|
+
throw new RangeError("angle must be < PI/2; frustum width and map size must be positive");
|
|
88
|
+
}
|
|
89
|
+
return Math.max(1 / mapSize, (gapMetres * Math.tan(sourceAngleRad)) / frustumWidthMetres);
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* The caster gap that Unreal's shadow-map ray test sees (PRD-634). Each ray runs `rayLengthScale` times the
|
|
94
|
+
* receiver's view distance toward the light, sampled `samplesPerRay` times at squared steps from a random
|
|
95
|
+
* start, far end first. It counts as blocked only when its first sample under the caster lies inside the
|
|
96
|
+
* caster's silhouette, so the edge spreads by that sample's distance and not by the caster's: this is that
|
|
97
|
+
* distance, averaged over the random start. 0 samples keeps the gap as it is.
|
|
98
|
+
* UE 5.8.3: Engine/Shaders/Private/VirtualShadowMaps/VirtualShadowMapSMRTTemplate.ush:41-130 (the sample
|
|
99
|
+
* times and the hit test), VirtualShadowMapProjectionDirectional.ush:230 (the ray length),
|
|
100
|
+
* Engine/Config/BaseScalability.ini:263 (4 samples per ray at Epic),
|
|
101
|
+
* Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp:760 (the 1.5 scale).
|
|
102
|
+
*/
|
|
103
|
+
export function shadowRayOccluderGap(
|
|
104
|
+
gap: number,
|
|
105
|
+
viewDistance: number,
|
|
106
|
+
samplesPerRay: number,
|
|
107
|
+
rayLengthScale: number,
|
|
108
|
+
): number {
|
|
109
|
+
if (samplesPerRay === 0) return gap;
|
|
110
|
+
const reach = rayLengthScale * viewDistance;
|
|
111
|
+
const x = reach > 0 ? Math.min(1, Math.sqrt(gap / reach)) : 1;
|
|
112
|
+
const n = samplesPerRay;
|
|
113
|
+
return reach * (x >= 1 / n ? x * x - x / n + 1 / (3 * n * n) : (n * x ** 3) / 3);
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
export interface ISourceAngleShadowOptions {
|
|
117
|
+
/** Required game-owned angular radius in radians, in [0, PI/2). No default. */
|
|
118
|
+
sourceAngleRad: number;
|
|
119
|
+
/** Fixed sample count, integer 1–64; default 16. Recreate the filter to change it. */
|
|
120
|
+
blockerSamples?: number;
|
|
121
|
+
/** Fixed sample count, integer 1–64; default 16. */
|
|
122
|
+
filterSamples?: number;
|
|
123
|
+
/**
|
|
124
|
+
* The receiver's own pixel, this many times over, blurs the edge on top of the source angle (the two add as
|
|
125
|
+
* the blur of two independent sources), so a contact edge is not a one-texel step that crawls as the camera
|
|
126
|
+
* moves. Unreal's sharpest sun-shadow edge is about a pixel wide (its texel dither and temporal resolve).
|
|
127
|
+
* Finite, in [0, 16]; default 0, which leaves the source angle alone.
|
|
128
|
+
*/
|
|
129
|
+
minPenumbraPixels?: number;
|
|
130
|
+
/**
|
|
131
|
+
* Unreal's shadow-map ray samples (`r.Shadow.Virtual.SMRT.SamplesPerRayDirectional`, 4 at Epic): the edge
|
|
132
|
+
* spreads from the caster gap that the ray test sees (`shadowRayOccluderGap`). Integer 0–64; default 4.
|
|
133
|
+
* 0 is the override that spreads the edge by the full geometric gap.
|
|
134
|
+
*/
|
|
135
|
+
samplesPerRay?: number;
|
|
136
|
+
/** The ray's length over the receiver's view distance (`r.Shadow.Virtual.SMRT.RayLengthScaleDirectional`); default 1.5. */
|
|
137
|
+
rayLengthScale?: number;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/** The object passed by three r185 ShadowNode.setupShadowFilter. */
|
|
141
|
+
export interface ISourceAngleShadowInputs {
|
|
142
|
+
depthTexture: DepthTexture;
|
|
143
|
+
shadowCoord: Node<"vec3">;
|
|
144
|
+
shadow: LightShadow;
|
|
145
|
+
depthLayer?: number;
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* Blocker search followed by variable-radius PCF for orthographic directional shadows.
|
|
150
|
+
* Camera bounds, zoom, near/far and mapSize are live references. Use a depth shadow map,
|
|
151
|
+
* not VSM. Both ordinary and reversed depth comparisons are supported.
|
|
152
|
+
* Ideas only: Unreal Engine/Shaders/Private/ShadowPercentageCloserFiltering.ush,
|
|
153
|
+
* DirectionalPCSS (blocker average and source-angle gap); independently written TSL.
|
|
154
|
+
*/
|
|
155
|
+
export function sourceAngleShadowFilter({
|
|
156
|
+
sourceAngleRad,
|
|
157
|
+
blockerSamples = 16,
|
|
158
|
+
filterSamples = 16,
|
|
159
|
+
minPenumbraPixels = 0,
|
|
160
|
+
samplesPerRay = 4,
|
|
161
|
+
rayLengthScale = 1.5,
|
|
162
|
+
}: ISourceAngleShadowOptions): (inputs: ISourceAngleShadowInputs) => Node<"float"> {
|
|
163
|
+
penumbraUv(0, sourceAngleRad, 1, 1);
|
|
164
|
+
for (const count of [blockerSamples, filterSamples]) {
|
|
165
|
+
if (!Number.isInteger(count) || count < 1 || count > 64) {
|
|
166
|
+
throw new RangeError("shadow sample counts must be integers in [1, 64]");
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
if (!Number.isFinite(minPenumbraPixels) || minPenumbraPixels < 0 || minPenumbraPixels > 16)
|
|
170
|
+
throw new RangeError("minPenumbraPixels must be finite and in [0, 16]");
|
|
171
|
+
if (!Number.isInteger(samplesPerRay) || samplesPerRay < 0 || samplesPerRay > 64)
|
|
172
|
+
throw new RangeError("samplesPerRay must be an integer in [0, 64]");
|
|
173
|
+
if (!Number.isFinite(rayLengthScale) || rayLengthScale <= 0)
|
|
174
|
+
throw new RangeError("rayLengthScale must be finite and positive");
|
|
175
|
+
const tangent = Math.tan(sourceAngleRad);
|
|
176
|
+
const disk = (index: number, count: number) => {
|
|
177
|
+
const radius = Math.sqrt((index + 0.5) / count);
|
|
178
|
+
const angle = index * Math.PI * (3 - Math.sqrt(5));
|
|
179
|
+
return vec2(radius * Math.cos(angle), radius * Math.sin(angle));
|
|
180
|
+
};
|
|
181
|
+
const filter = ({
|
|
182
|
+
depthTexture,
|
|
183
|
+
shadowCoord,
|
|
184
|
+
shadow,
|
|
185
|
+
depthLayer = 0,
|
|
186
|
+
}: ISourceAngleShadowInputs) => {
|
|
187
|
+
const camera = shadow.camera as OrthographicCamera;
|
|
188
|
+
if (camera.isOrthographicCamera !== true) {
|
|
189
|
+
throw new RangeError("source-angle shadows require an orthographic shadow camera");
|
|
190
|
+
}
|
|
191
|
+
penumbraUv(0, sourceAngleRad, (camera.right - camera.left) / camera.zoom, shadow.mapSize.x);
|
|
192
|
+
penumbraUv(0, sourceAngleRad, (camera.top - camera.bottom) / camera.zoom, shadow.mapSize.y);
|
|
193
|
+
if (
|
|
194
|
+
!Number.isFinite(camera.near) ||
|
|
195
|
+
camera.near < 0 ||
|
|
196
|
+
!Number.isFinite(camera.far) ||
|
|
197
|
+
camera.far <= camera.near
|
|
198
|
+
) {
|
|
199
|
+
throw new RangeError("shadow camera requires finite 0 <= near < far");
|
|
200
|
+
}
|
|
201
|
+
if (!Number.isFinite(camera.zoom) || camera.zoom <= 0)
|
|
202
|
+
throw new RangeError("shadow camera zoom must be positive and finite");
|
|
203
|
+
if (
|
|
204
|
+
depthTexture.compareFunction !== LessEqualCompare &&
|
|
205
|
+
depthTexture.compareFunction !== GreaterEqualCompare
|
|
206
|
+
)
|
|
207
|
+
throw new RangeError("source-angle shadows require a comparison depth texture, not VSM");
|
|
208
|
+
const reversed = depthTexture.compareFunction === GreaterEqualCompare;
|
|
209
|
+
const size = reference("mapSize", "vec2", shadow);
|
|
210
|
+
const near = reference("near", "float", camera);
|
|
211
|
+
const range = reference("far", "float", camera).sub(near);
|
|
212
|
+
const span = vec2(
|
|
213
|
+
reference("right", "float", camera).sub(reference("left", "float", camera)),
|
|
214
|
+
reference("top", "float", camera).sub(reference("bottom", "float", camera)),
|
|
215
|
+
).div(reference("zoom", "float", camera));
|
|
216
|
+
const texel = vec2(1).div(size);
|
|
217
|
+
const isArray = "isArrayTexture" in depthTexture && depthTexture.isArrayTexture === true;
|
|
218
|
+
const withLayer = (sample: ReturnType<typeof texture>) =>
|
|
219
|
+
isArray ? sample.depth(float(depthLayer)) : sample;
|
|
220
|
+
const linearDepth = (depth: Node<"float">) => (reversed ? depth.oneMinus() : depth);
|
|
221
|
+
return Fn(
|
|
222
|
+
(_inputs: unknown, builder: { readonly material?: Parameters<typeof isLeafReceiver>[0] }) => {
|
|
223
|
+
// A receiver marked twoSidedFoliage sees the sun at 5 degrees at least; the node is built per material.
|
|
224
|
+
const reach = receiverSourceTangent(builder.material, tangent);
|
|
225
|
+
const receiver = linearDepth(shadowCoord.z);
|
|
226
|
+
// Near-plane distance bounds the largest possible caster/receiver gap.
|
|
227
|
+
const searchRadius = max(texel, vec2(receiver.mul(range).mul(reach)).div(span)).toVar();
|
|
228
|
+
const blockerSum = float(0).toVar();
|
|
229
|
+
const blockerCount = float(0).toVar();
|
|
230
|
+
// Integer loads read raw depth without interpolated blockers. Both loops load: three r185
|
|
231
|
+
// gives a depth texture one sampler binding, typed by the first node that registers it, so
|
|
232
|
+
// a load followed by `.compare()` emitted a plain sampler and failed to compile.
|
|
233
|
+
const load = (uv: Node<"vec2">) =>
|
|
234
|
+
linearDepth(
|
|
235
|
+
withLayer(
|
|
236
|
+
textureLoad(
|
|
237
|
+
depthTexture,
|
|
238
|
+
ivec2(min(max(uv.mul(size).floor(), vec2(0)), size.sub(1))),
|
|
239
|
+
),
|
|
240
|
+
).r,
|
|
241
|
+
);
|
|
242
|
+
for (let index = 0; index < blockerSamples; index++) {
|
|
243
|
+
const depth = load(
|
|
244
|
+
shadowCoord.xy.add(disk(index, blockerSamples).mul(searchRadius)),
|
|
245
|
+
).toVar();
|
|
246
|
+
If(depth.lessThan(receiver), () => {
|
|
247
|
+
blockerSum.addAssign(depth);
|
|
248
|
+
blockerCount.addAssign(1);
|
|
249
|
+
});
|
|
250
|
+
}
|
|
251
|
+
const blockerGap = max(0, receiver.sub(blockerSum.div(max(blockerCount, 1)))).mul(range);
|
|
252
|
+
// shadowRayOccluderGap, per receiver.
|
|
253
|
+
const n = samplesPerRay;
|
|
254
|
+
const rayReach = positionWorld.distance(cameraPosition).mul(rayLengthScale);
|
|
255
|
+
const x = min(1, sqrt(blockerGap.div(max(rayReach, 1e-6))));
|
|
256
|
+
const gap =
|
|
257
|
+
n === 0
|
|
258
|
+
? blockerGap
|
|
259
|
+
: rayReach.mul(
|
|
260
|
+
x.greaterThanEqual(1 / n).select(
|
|
261
|
+
x
|
|
262
|
+
.mul(x)
|
|
263
|
+
.sub(x.div(n))
|
|
264
|
+
.add(1 / (3 * n * n)),
|
|
265
|
+
x
|
|
266
|
+
.mul(x)
|
|
267
|
+
.mul(x)
|
|
268
|
+
.mul(n / 3),
|
|
269
|
+
),
|
|
270
|
+
);
|
|
271
|
+
const penumbra = vec2(gap.mul(reach)).div(span);
|
|
272
|
+
// The receiver's pixel in this map's uv, per axis (the length of its two screen steps together), as
|
|
273
|
+
// many times as `minPenumbraPixels` asks for, and at most 16 texels: the steps of a quad that straddles
|
|
274
|
+
// a silhouette are the distance between two surfaces.
|
|
275
|
+
const stepX = dFdx(shadowCoord.xy);
|
|
276
|
+
const stepY = dFdy(shadowCoord.xy);
|
|
277
|
+
const pixels = min(
|
|
278
|
+
sqrt(stepX.mul(stepX).add(stepY.mul(stepY))).mul(minPenumbraPixels),
|
|
279
|
+
texel.mul(16),
|
|
280
|
+
);
|
|
281
|
+
const radius = max(
|
|
282
|
+
texel,
|
|
283
|
+
minPenumbraPixels === 0 ? penumbra : sqrt(penumbra.mul(penumbra).add(pixels.mul(pixels))),
|
|
284
|
+
).toVar();
|
|
285
|
+
const visibility = float(0).toVar();
|
|
286
|
+
for (let index = 0; index < filterSamples; index++) {
|
|
287
|
+
const depth = load(shadowCoord.xy.add(disk(index, filterSamples).mul(radius)));
|
|
288
|
+
visibility.addAssign(step(receiver, depth));
|
|
289
|
+
}
|
|
290
|
+
return blockerCount.greaterThan(0).select(visibility.div(filterSamples), float(1));
|
|
291
|
+
},
|
|
292
|
+
)();
|
|
293
|
+
};
|
|
294
|
+
// Native virtual maps translate the same filter parameters into atlas-aware depth loads.
|
|
295
|
+
return Object.assign(filter, {
|
|
296
|
+
[Symbol.for("threenative.sourceAngleShadowFilter")]: Object.freeze({
|
|
297
|
+
sourceAngleRad,
|
|
298
|
+
blockerSamples,
|
|
299
|
+
filterSamples,
|
|
300
|
+
minPenumbraPixels,
|
|
301
|
+
samplesPerRay,
|
|
302
|
+
rayLengthScale,
|
|
303
|
+
}),
|
|
304
|
+
});
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
/**
|
|
308
|
+
* A lamp's penumbra radius in tangent units (offset over distance) at the receiver: the disk of
|
|
309
|
+
* `sourceRadius` metres seen past a blocker at `blockerDistance` from a receiver at `receiverDistance`.
|
|
310
|
+
* Times the receiver distance it is the penumbra's world radius, linear in the caster gap and the radius.
|
|
311
|
+
*/
|
|
312
|
+
export function lampPenumbraTangent(
|
|
313
|
+
sourceRadius: number,
|
|
314
|
+
blockerDistance: number,
|
|
315
|
+
receiverDistance: number,
|
|
316
|
+
): number {
|
|
317
|
+
if (!Number.isFinite(sourceRadius) || sourceRadius < 0)
|
|
318
|
+
throw new RangeError("sourceRadius must be finite and non-negative");
|
|
319
|
+
if (!(blockerDistance > 0) || !(receiverDistance > 0) || !Number.isFinite(receiverDistance))
|
|
320
|
+
throw new RangeError("blocker and receiver distances must be positive and finite");
|
|
321
|
+
return sourceRadius * Math.max(0, 1 / blockerDistance - 1 / receiverDistance);
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
export interface ISourceRadiusShadowOptions {
|
|
325
|
+
/** Required game-owned lamp radius in metres (Unreal's SourceRadius); 0 is one hard tap. */
|
|
326
|
+
sourceRadius: number;
|
|
327
|
+
/** Fixed sample count, integer 1–64; default 16. Recreate the filter to change it. */
|
|
328
|
+
blockerSamples?: number;
|
|
329
|
+
/** Fixed sample count, integer 1–64; default 16. */
|
|
330
|
+
filterSamples?: number;
|
|
331
|
+
/**
|
|
332
|
+
* The share of the geometric penumbra the lamp keeps, in (0, 4]; default `LAMP_PENUMBRA_SCALE`.
|
|
333
|
+
* 1 is the width a disk lamp throws; Unreal's shadow-map ray test samples each ray a few times and
|
|
334
|
+
* resolves about 0.6 of it at its Epic counts.
|
|
335
|
+
*/
|
|
336
|
+
penumbraScale?: number;
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
/**
|
|
340
|
+
* The default `penumbraScale`. Unreal 5.8.3's local-light ray test (8 rays, 4 samples each at Epic) misses
|
|
341
|
+
* the thin end of a penumbra: measured against a geometric disk lamp it keeps 0.47 to 0.69 of the width on
|
|
342
|
+
* the calibration scenes (`lamp-room`, `cornell`), and a simulation of the test at those counts averages 0.6.
|
|
343
|
+
*/
|
|
344
|
+
export const LAMP_PENUMBRA_SCALE = 0.6;
|
|
345
|
+
|
|
346
|
+
/** A spot light's filter inputs (ShadowNode), or a point light's (PointShadowNode: `bd3D`, `dp`). */
|
|
347
|
+
export interface ISourceRadiusShadowInputs extends ISourceAngleShadowInputs {
|
|
348
|
+
bd3D?: Node<"vec3">;
|
|
349
|
+
dp?: Node<"float">;
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
/**
|
|
353
|
+
* Blocker search followed by variable-radius PCF for a spot light's map or a point light's cube: the
|
|
354
|
+
* penumbra is `penumbraScale * lampPenumbraTangent` at the average blocker that shades the receiver, at
|
|
355
|
+
* least half a texel. The search runs `blockerPasses` times: the nearest blocker in a cone has the widest
|
|
356
|
+
* penumbra and every blocker that shades the receiver lies inside it, so the cone shrinks to that penumbra;
|
|
357
|
+
* the last cone averages only the blockers whose own penumbra reaches the receiver, so a volume's far
|
|
358
|
+
* faces, a wall's own texels and a nearer object off to the side never pull the width. A texel is a blocker
|
|
359
|
+
* only when it is nearer than the receiver's own plane (read from the screen derivatives), so a tilted wall
|
|
360
|
+
* that the lamp sees nearer on one side never shades itself, and the filter compares each tap against
|
|
361
|
+
* that plane too. The receiver's own ray is a tap of every cone and always counts when it is blocked, since
|
|
362
|
+
* it lies inside the lamp's disk: a back-face map stores a box's far face within centimetres of the floor
|
|
363
|
+
* behind it, and a thin rod falls between the taps. A receiver no blocker reaches is lit. Distances are
|
|
364
|
+
* along the receiver's ray, so a cube's faces agree: a face stores the depth along its own axis.
|
|
365
|
+
* The spot map reads raw depth like `sourceAngleShadowFilter`. A cube has no integer load in WGSL and
|
|
366
|
+
* three r185 gives a depth texture one sampler, so the point light's search compares each tap at four
|
|
367
|
+
* depths between the light and the plane and takes the blocker from the step where it turns dark.
|
|
368
|
+
* Ideas only: Unreal VirtualShadowMapProjectionSpot.ush (rays in a cone of SourceRadius / distance);
|
|
369
|
+
* independently written TSL. The owned engine reads the cube's raw depths instead.
|
|
370
|
+
*/
|
|
371
|
+
export function sourceRadiusShadowFilter({
|
|
372
|
+
sourceRadius,
|
|
373
|
+
blockerSamples = 16,
|
|
374
|
+
filterSamples = 16,
|
|
375
|
+
penumbraScale = LAMP_PENUMBRA_SCALE,
|
|
376
|
+
}: ISourceRadiusShadowOptions): (inputs: ISourceRadiusShadowInputs) => Node<"float"> {
|
|
377
|
+
lampPenumbraTangent(sourceRadius, 1, 1);
|
|
378
|
+
if (!Number.isFinite(penumbraScale) || penumbraScale <= 0 || penumbraScale > 4)
|
|
379
|
+
throw new RangeError("penumbraScale must be in (0, 4]");
|
|
380
|
+
for (const count of [blockerSamples, filterSamples]) {
|
|
381
|
+
if (!Number.isInteger(count) || count < 1 || count > 64) {
|
|
382
|
+
throw new RangeError("shadow sample counts must be integers in [1, 64]");
|
|
383
|
+
}
|
|
384
|
+
}
|
|
385
|
+
const levels = 4;
|
|
386
|
+
// ponytail: two passes, as on the owned engine; a third moved the edge by under 3 % in the wall test.
|
|
387
|
+
const blockerPasses = 2;
|
|
388
|
+
const disk = (index: number, count: number) => {
|
|
389
|
+
const radius = Math.sqrt((index + 0.5) / count);
|
|
390
|
+
const angle = index * Math.PI * (3 - Math.sqrt(5));
|
|
391
|
+
return vec2(radius * Math.cos(angle), radius * Math.sin(angle));
|
|
392
|
+
};
|
|
393
|
+
const filter = ({ depthTexture, shadowCoord, shadow, bd3D, dp }: ISourceRadiusShadowInputs) => {
|
|
394
|
+
const camera = shadow.camera as PerspectiveCamera;
|
|
395
|
+
if (camera.isPerspectiveCamera !== true)
|
|
396
|
+
throw new RangeError(
|
|
397
|
+
"source-radius shadows require a spot or point light's perspective camera",
|
|
398
|
+
);
|
|
399
|
+
if (depthTexture.compareFunction !== LessEqualCompare)
|
|
400
|
+
throw new RangeError("source-radius shadows require a forward-depth comparison texture");
|
|
401
|
+
const near = reference("near", "float", camera);
|
|
402
|
+
const far = reference("far", "float", camera);
|
|
403
|
+
const size = reference("mapSize", "vec2", shadow).x;
|
|
404
|
+
// A [0, 1] perspective depth and its view depth.
|
|
405
|
+
const distanceOf = (depth: Node<"float">) =>
|
|
406
|
+
near.mul(far).div(far.sub(depth.mul(far.sub(near))));
|
|
407
|
+
const depthOf = (distance: Node<"float">) =>
|
|
408
|
+
far.mul(distance.sub(near)).div(distance.mul(far.sub(near)));
|
|
409
|
+
const radius = float(sourceRadius);
|
|
410
|
+
// The lamp's disk seen past a blocker, in tangent units: the penumbra's radius at the receiver.
|
|
411
|
+
const spreadOf = (blocker: Node<"float">, receiver: Node<"float">) =>
|
|
412
|
+
radius.mul(max(0, float(1).div(blocker).sub(float(1).div(receiver))));
|
|
413
|
+
const penumbraOf = (blocker: Node<"float">, receiver: Node<"float">, texel: Node<"float">) =>
|
|
414
|
+
sourceRadius === 0
|
|
415
|
+
? float(0)
|
|
416
|
+
: max(texel.mul(0.5), spreadOf(blocker, receiver).mul(penumbraScale));
|
|
417
|
+
// ponytail: the search cone is cut at 0.5 tangent (27 degrees), as on the owned engine.
|
|
418
|
+
const searchOf = (receiver: Node<"float">) => min(0.5, spreadOf(near, receiver));
|
|
419
|
+
// d(distance) / d(tap offset): the 2x2 solve of the distance's screen derivatives against those of
|
|
420
|
+
// the tap coordinates. Called in uniform control flow, before any branch.
|
|
421
|
+
const slopeOf = (
|
|
422
|
+
jx: Node<"vec2">,
|
|
423
|
+
jy: Node<"vec2">,
|
|
424
|
+
distance: Node<"float">,
|
|
425
|
+
scale: Node<"float">,
|
|
426
|
+
) => {
|
|
427
|
+
const [rx, ry] = [dFdx(distance), dFdy(distance)];
|
|
428
|
+
const det = jx.x.mul(jy.y).sub(jx.y.mul(jy.x));
|
|
429
|
+
const flat = det.abs().lessThan(1e-12);
|
|
430
|
+
const safe = flat.select(float(1), det);
|
|
431
|
+
return vec2(
|
|
432
|
+
rx.mul(jy.y).sub(jx.y.mul(ry)).div(safe),
|
|
433
|
+
jx.x.mul(ry).sub(jy.x.mul(rx)).div(safe),
|
|
434
|
+
)
|
|
435
|
+
.mul(flat.select(float(0), scale))
|
|
436
|
+
.toVar();
|
|
437
|
+
};
|
|
438
|
+
if (bd3D && dp) {
|
|
439
|
+
const absDir = bd3D.abs();
|
|
440
|
+
const tangent = cross(
|
|
441
|
+
bd3D,
|
|
442
|
+
absDir.x.greaterThan(absDir.z).select(vec3(0, 1, 0), vec3(1, 0, 0)),
|
|
443
|
+
).normalize();
|
|
444
|
+
const bitangent = cross(bd3D, tangent);
|
|
445
|
+
// A depth compare answers a float; three's types call every texture read a vec4.
|
|
446
|
+
const tap = (offset: Node<"vec2">, reference: Node<"float">) =>
|
|
447
|
+
cubeTexture(
|
|
448
|
+
// quality-allow: the depth texture is a cube map the point-light shadow pass renders into, which three types as a plain DepthTexture
|
|
449
|
+
depthTexture as unknown as CubeTexture,
|
|
450
|
+
bd3D.add(tangent.mul(offset.x).add(bitangent.mul(offset.y))),
|
|
451
|
+
).compare(reference) as unknown as Node<"float">; // quality-allow: a depth compare answers a float, and three 0.185 types every texture read as a vec4
|
|
452
|
+
// The depth along a tap's cube face over the distance along its ray: the ray's largest component
|
|
453
|
+
// over its length.
|
|
454
|
+
const axialPerEuclid = (offset: Node<"vec2">) => {
|
|
455
|
+
const ray = bd3D.add(tangent.mul(offset.x).add(bitangent.mul(offset.y))).abs();
|
|
456
|
+
return max(max(ray.x, ray.y), ray.z).div(
|
|
457
|
+
bd3D.add(tangent.mul(offset.x).add(bitangent.mul(offset.y))).length(),
|
|
458
|
+
);
|
|
459
|
+
};
|
|
460
|
+
return Fn(() => {
|
|
461
|
+
const receiver = distanceOf(dp)
|
|
462
|
+
.div(axialPerEuclid(vec2(0, 0)))
|
|
463
|
+
.toVar();
|
|
464
|
+
const slope = slopeOf(
|
|
465
|
+
vec2(dFdx(bd3D).dot(tangent), dFdx(bd3D).dot(bitangent)),
|
|
466
|
+
vec2(dFdy(bd3D).dot(tangent), dFdy(bd3D).dot(bitangent)),
|
|
467
|
+
receiver,
|
|
468
|
+
float(1),
|
|
469
|
+
);
|
|
470
|
+
// The receiver's plane at a tap offset as a distance along the tap's ray, and as the depth along its face.
|
|
471
|
+
const planeDistance = (offset: Node<"vec2">) =>
|
|
472
|
+
max(0, receiver.add(slope.x.mul(offset.x)).add(slope.y.mul(offset.y)));
|
|
473
|
+
const planeAxial = (offset: Node<"vec2">) =>
|
|
474
|
+
max(planeDistance(offset).mul(axialPerEuclid(offset)), near);
|
|
475
|
+
const visibility = float(1).toVar();
|
|
476
|
+
const cone = searchOf(receiver).toVar();
|
|
477
|
+
// One search cone: how many blockers, their summed distance, and the nearest. The last cone counts only
|
|
478
|
+
// the texels whose own penumbra reaches the receiver, and the receiver's own ray, which is inside the
|
|
479
|
+
// lamp's disk whatever the blocker's reach.
|
|
480
|
+
const blockerAt = (offset: Node<"vec2">) => {
|
|
481
|
+
const plane = planeAxial(offset);
|
|
482
|
+
const blocked = tap(offset, depthOf(plane)).oneMinus().toVar();
|
|
483
|
+
// Darker at more of the levels: the blocker is nearer the light.
|
|
484
|
+
let steps: Node<"float"> = float(0);
|
|
485
|
+
for (let level = 1; level <= levels; level++)
|
|
486
|
+
steps = steps.add(tap(offset, depthOf(plane.mul(level / (levels + 1)))).oneMinus());
|
|
487
|
+
const blocker = plane
|
|
488
|
+
.mul(float(levels + 0.5).sub(steps))
|
|
489
|
+
.div(levels + 1)
|
|
490
|
+
.div(axialPerEuclid(offset));
|
|
491
|
+
return { blocked, blocker };
|
|
492
|
+
};
|
|
493
|
+
const search = (last: boolean) => {
|
|
494
|
+
const sum = float(0).toVar();
|
|
495
|
+
const count = float(0).toVar();
|
|
496
|
+
const nearest = float(1e30).toVar();
|
|
497
|
+
const visit = (offset: Node<"vec2">, own: boolean) => {
|
|
498
|
+
const { blocked, blocker } = blockerAt(offset);
|
|
499
|
+
const reaches = offset.length().lessThanEqual(spreadOf(blocker, planeDistance(offset)));
|
|
500
|
+
const weight = last && !own ? reaches.select(blocked, float(0)) : blocked;
|
|
501
|
+
sum.addAssign(weight.mul(blocker));
|
|
502
|
+
count.addAssign(weight);
|
|
503
|
+
nearest.assign(blocked.greaterThan(0.5).select(min(nearest, blocker), nearest));
|
|
504
|
+
};
|
|
505
|
+
visit(vec2(0, 0), true);
|
|
506
|
+
for (let tapIndex = 0; tapIndex < blockerSamples; tapIndex++)
|
|
507
|
+
visit(disk(tapIndex, blockerSamples).mul(cone), false);
|
|
508
|
+
return { sum, count, nearest };
|
|
509
|
+
};
|
|
510
|
+
const pass = (index: number) => {
|
|
511
|
+
const last = index + 1 === blockerPasses;
|
|
512
|
+
const { sum, count, nearest } = search(last);
|
|
513
|
+
If(count.greaterThan(0), () => {
|
|
514
|
+
if (!last) {
|
|
515
|
+
cone.assign(min(cone, spreadOf(nearest, receiver)));
|
|
516
|
+
pass(index + 1);
|
|
517
|
+
return;
|
|
518
|
+
}
|
|
519
|
+
const blocker = sum.div(count);
|
|
520
|
+
const penumbra = penumbraOf(blocker, receiver, float(2).div(size)).toVar();
|
|
521
|
+
let lit: Node<"float"> = float(0);
|
|
522
|
+
for (let tapIndex = 0; tapIndex < filterSamples; tapIndex++) {
|
|
523
|
+
const offset = disk(tapIndex, filterSamples).mul(penumbra);
|
|
524
|
+
lit = lit.add(tap(offset, depthOf(planeAxial(offset))));
|
|
525
|
+
}
|
|
526
|
+
visibility.assign(lit.div(filterSamples));
|
|
527
|
+
});
|
|
528
|
+
};
|
|
529
|
+
pass(0);
|
|
530
|
+
return visibility;
|
|
531
|
+
})();
|
|
532
|
+
}
|
|
533
|
+
const tanHalf = uniform(1).onRenderUpdate(
|
|
534
|
+
() => Math.tan((camera.fov * Math.PI) / 360) / camera.zoom,
|
|
535
|
+
);
|
|
536
|
+
const uvPerTangent = float(0.5).div(tanHalf);
|
|
537
|
+
const sizes = vec2(size);
|
|
538
|
+
const load = (uv: Node<"vec2">) =>
|
|
539
|
+
textureLoad(depthTexture, ivec2(min(max(uv.mul(sizes).floor(), vec2(0)), sizes.sub(1)))).r;
|
|
540
|
+
return Fn(() => {
|
|
541
|
+
const receiver = distanceOf(shadowCoord.z).toVar();
|
|
542
|
+
const slope = slopeOf(dFdx(shadowCoord.xy), dFdy(shadowCoord.xy), receiver, uvPerTangent);
|
|
543
|
+
// The receiver's plane at a tap offset, as a distance and as a [0, 1] depth.
|
|
544
|
+
const planeDistance = (offset: Node<"vec2">) =>
|
|
545
|
+
max(near, receiver.add(slope.x.mul(offset.x)).add(slope.y.mul(offset.y)));
|
|
546
|
+
const planeDepth = (offset: Node<"vec2">) => depthOf(planeDistance(offset));
|
|
547
|
+
const visibility = float(1).toVar();
|
|
548
|
+
const cone = searchOf(receiver).toVar();
|
|
549
|
+
const pass = (index: number) => {
|
|
550
|
+
const last = index + 1 === blockerPasses;
|
|
551
|
+
const sum = float(0).toVar();
|
|
552
|
+
const count = float(0).toVar();
|
|
553
|
+
const nearest = float(1e30).toVar();
|
|
554
|
+
const visit = (offset: Node<"vec2">, own: boolean) => {
|
|
555
|
+
const depth = load(shadowCoord.xy.add(offset.mul(uvPerTangent))).toVar();
|
|
556
|
+
If(depth.lessThan(planeDepth(offset)), () => {
|
|
557
|
+
const blocker = distanceOf(depth);
|
|
558
|
+
if (!last) {
|
|
559
|
+
nearest.assign(min(nearest, blocker));
|
|
560
|
+
count.addAssign(1);
|
|
561
|
+
return;
|
|
562
|
+
}
|
|
563
|
+
const shade = () => {
|
|
564
|
+
sum.addAssign(blocker);
|
|
565
|
+
count.addAssign(1);
|
|
566
|
+
};
|
|
567
|
+
// The receiver's own ray is inside the lamp's disk; any other texel shades the receiver only
|
|
568
|
+
// when its own penumbra reaches it.
|
|
569
|
+
if (own) shade();
|
|
570
|
+
else If(offset.length().lessThanEqual(spreadOf(blocker, planeDistance(offset))), shade);
|
|
571
|
+
});
|
|
572
|
+
};
|
|
573
|
+
visit(vec2(0, 0), true);
|
|
574
|
+
for (let tapIndex = 0; tapIndex < blockerSamples; tapIndex++)
|
|
575
|
+
visit(disk(tapIndex, blockerSamples).mul(cone), false);
|
|
576
|
+
If(count.greaterThan(0), () => {
|
|
577
|
+
if (!last) {
|
|
578
|
+
cone.assign(min(cone, spreadOf(nearest, receiver)));
|
|
579
|
+
pass(index + 1);
|
|
580
|
+
return;
|
|
581
|
+
}
|
|
582
|
+
const blocker = sum.div(count);
|
|
583
|
+
const penumbra = penumbraOf(blocker, receiver, tanHalf.mul(2).div(size)).toVar();
|
|
584
|
+
const lit = float(0).toVar();
|
|
585
|
+
for (let tapIndex = 0; tapIndex < filterSamples; tapIndex++) {
|
|
586
|
+
const offset = disk(tapIndex, filterSamples).mul(penumbra);
|
|
587
|
+
lit.addAssign(
|
|
588
|
+
step(planeDepth(offset), load(shadowCoord.xy.add(offset.mul(uvPerTangent)))),
|
|
589
|
+
);
|
|
590
|
+
}
|
|
591
|
+
visibility.assign(lit.div(filterSamples));
|
|
592
|
+
});
|
|
593
|
+
};
|
|
594
|
+
pass(0);
|
|
595
|
+
return visibility;
|
|
596
|
+
})();
|
|
597
|
+
};
|
|
598
|
+
// The owned engine reads the same parameters from this tag (a lamp's filterNode).
|
|
599
|
+
return Object.assign(filter, {
|
|
600
|
+
[Symbol.for("threenative.sourceRadiusShadowFilter")]: Object.freeze({
|
|
601
|
+
sourceRadius,
|
|
602
|
+
blockerSamples,
|
|
603
|
+
filterSamples,
|
|
604
|
+
penumbraScale,
|
|
605
|
+
}),
|
|
606
|
+
});
|
|
607
|
+
}
|