@threenative/core 0.3.4 → 0.3.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/capabilities.json +1505 -79
- package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
- package/dist/{canvas-layer-DDmC_VVF.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
- package/dist/{game-CljaDv4D.d.ts → game-Jz4Fdoeb.d.ts} +114 -11
- package/dist/hot.d.ts +4 -4
- package/dist/index.d.ts +712 -118
- package/dist/index.js +12437 -4955
- package/dist/{gpu-readback-CqJEfWNQ.d.ts → model-lod-BDAUYgsS.d.ts} +80 -5
- package/dist/playtest.d.ts +6 -10
- package/dist/playtest.js +57 -24
- package/dist/react-css.d.ts +62 -0
- package/dist/react-css.js +591 -0
- package/dist/react.d.ts +2 -2
- package/dist/{renderer-CfsS2hxi.d.ts → renderer-9yEo9hPa.d.ts} +489 -22
- package/dist/terrain-jobs-worker.d.ts +2 -0
- package/dist/terrain-jobs-worker.js +130 -0
- package/dist/ui-layer.js +59 -8
- package/dist/world.d.ts +766 -73
- package/dist/world.js +9307 -3543
- package/gpl/recipes/export_world.py +18 -1
- package/mcp/blender-server.mjs +7 -4
- package/mcp/blender.mjs +3 -4
- package/mcp/engine-server.mjs +2 -2
- package/mcp/servers.mjs +4 -4
- package/package.json +15 -9
- package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
- package/patches/three@0.185.1.patch +6594 -700
- package/scripts/apply-three-patch.mjs +62 -4
- package/src/animation-blend.ts +264 -0
- package/src/animation-composition.ts +362 -0
- package/src/animation-layers.ts +260 -0
- package/src/animation-root-motion.ts +283 -0
- package/src/animation.ts +896 -0
- package/src/assets.ts +1303 -0
- package/src/atmosphere/index.ts +335 -0
- package/src/atmosphere/luts.ts +298 -0
- package/src/atmosphere/params.ts +323 -0
- package/src/audio.ts +912 -0
- package/src/billboard.ts +124 -0
- package/src/bone-lengths.ts +157 -0
- package/src/camera-shake.ts +116 -0
- package/src/canvas-layer.ts +47 -0
- package/src/clip-audit.ts +401 -0
- package/src/clustered-batch.ts +492 -0
- package/src/clustered-mesh.ts +638 -0
- package/src/compute-driven.ts +176 -0
- package/src/compute-timing.ts +318 -0
- package/src/config.ts +593 -0
- package/src/debug.ts +82 -0
- package/src/engine-render-hook.ts +25 -0
- package/src/entities.ts +79 -0
- package/src/entity-snapshot.ts +53 -0
- package/src/flight.ts +683 -0
- package/src/fluid-field.ts +748 -0
- package/src/fluid-particles.ts +1253 -0
- package/src/frame-budget.ts +1368 -0
- package/src/game.ts +2408 -0
- package/src/geometry-capture.ts +1098 -0
- package/src/gpu-class.ts +160 -0
- package/src/gpu-frame-observation.ts +424 -0
- package/src/gpu-readback.ts +143 -0
- package/src/gpu-scene-bvh.ts +464 -0
- package/src/grounding.ts +100 -0
- package/src/hot.ts +161 -0
- package/src/import-meta.d.ts +13 -0
- package/src/index.ts +1536 -0
- package/src/input.ts +690 -0
- package/src/instanced-batch-lod.ts +283 -0
- package/src/instanced-batch.ts +274 -0
- package/src/interpolation.ts +129 -0
- package/src/launch-diagnostics.ts +161 -0
- package/src/loop.ts +574 -0
- package/src/matrix-world.ts +245 -0
- package/src/merge-parts.ts +812 -0
- package/src/model-lod.ts +1315 -0
- package/src/net-protocol.ts +333 -0
- package/src/net-session.ts +477 -0
- package/src/net.ts +80 -0
- package/src/ocean/fft.ts +72 -0
- package/src/ocean/spectral.ts +728 -0
- package/src/particle-significance.ts +102 -0
- package/src/particles.ts +648 -0
- package/src/path-follow.ts +175 -0
- package/src/picking.ts +250 -0
- package/src/pipeline-census.ts +1566 -0
- package/src/platform.ts +210 -0
- package/src/playtest.ts +850 -0
- package/src/pointer-events.ts +411 -0
- package/src/pose-measure.ts +435 -0
- package/src/profiling/FrameCounters.ts +231 -0
- package/src/profiling/Spans.ts +548 -0
- package/src/profiling/opacity-convention.ts +21 -0
- package/src/profiling/render-list-validate.ts +175 -0
- package/src/profiling/render-trap-audit.ts +84 -0
- package/src/profiling/scene-warning.ts +190 -0
- package/src/profiling/span-probes.ts +191 -0
- package/src/profiling/unlit-foliage-warning.ts +149 -0
- package/src/projection-apply.ts +1529 -0
- package/src/projection-marker.ts +142 -0
- package/src/projection-plan.ts +1258 -0
- package/src/projection-skinned.ts +419 -0
- package/src/projection-stability.ts +409 -0
- package/src/projection-uniform.ts +328 -0
- package/src/random.ts +41 -0
- package/src/react-css.ts +604 -0
- package/src/react-glyphs.ts +114 -0
- package/src/react-host.ts +576 -0
- package/src/react-layout.ts +265 -0
- package/src/react.ts +60 -0
- package/src/render/alpha-antialiasing.ts +159 -0
- package/src/render/batched-velocity.ts +126 -0
- package/src/render/chain.ts +1021 -0
- package/src/render/daylight.ts +189 -0
- package/src/render/depth-pyramid.ts +596 -0
- package/src/render/foliage-alpha.ts +166 -0
- package/src/render/material-key.ts +60 -0
- package/src/render/mesh-pool.ts +144 -0
- package/src/render/probe-volume.ts +1668 -0
- package/src/render/resolution-subrect.ts +253 -0
- package/src/render/velocity.ts +442 -0
- package/src/render/virtual-shadow-pages.ts +827 -0
- package/src/render/virtual-shadow-partial.ts +174 -0
- package/src/render/virtual-shadow.ts +3330 -0
- package/src/render/world-impostor-surface.ts +722 -0
- package/src/render/world-impostor.ts +558 -0
- package/src/render-camera-cull.ts +441 -0
- package/src/render-pass-budget.ts +501 -0
- package/src/renderProjection.ts +758 -0
- package/src/renderer-config.ts +127 -0
- package/src/renderer.ts +1847 -0
- package/src/replay-protocol.ts +85 -0
- package/src/replay.ts +205 -0
- package/src/resolution-scaler.ts +819 -0
- package/src/rig-preparation.ts +271 -0
- package/src/ripple-field.ts +432 -0
- package/src/scale.ts +109 -0
- package/src/scene.ts +239 -0
- package/src/schedule.ts +155 -0
- package/src/skeletal-mesh.ts +61 -0
- package/src/skeleton.ts +100 -0
- package/src/snow-field.ts +744 -0
- package/src/softbody-topology.ts +269 -0
- package/src/softbody.ts +516 -0
- package/src/sprite-animator.ts +222 -0
- package/src/startup-readiness.ts +386 -0
- package/src/state.ts +66 -0
- package/src/static-transform.ts +274 -0
- package/src/storage-buffer.ts +253 -0
- package/src/streaming.ts +308 -0
- package/src/target-fps.ts +92 -0
- package/src/terrain-jobs-worker.ts +17 -0
- package/src/terrain-jobs.ts +353 -0
- package/src/textures.ts +39 -0
- package/src/tracers.ts +237 -0
- package/src/ui-bridge.ts +368 -0
- package/src/ui-hit-regions.ts +380 -0
- package/src/ui-layer.ts +83 -0
- package/src/ui-state.ts +220 -0
- package/src/version.ts +2 -0
- package/src/viewport.ts +253 -0
- package/src/warmup.ts +1357 -0
- package/src/water-surface.ts +384 -0
- package/src/wave-field.ts +524 -0
- package/src/world-capabilities.ts +131 -0
- package/src/world-cell-proxy.ts +392 -0
- package/src/world-cells.ts +10564 -0
- package/src/world-gpu-scene.ts +3354 -0
- package/src/world-heightmap.ts +82 -0
- package/src/world-package.ts +469 -0
- package/src/world-passes.ts +582 -0
- package/src/world-region.ts +17 -0
- package/src/world-terrain-splat.ts +564 -0
- package/src/world-tiles.ts +3826 -0
- package/src/world-topology.ts +370 -0
- package/src/world-validate.ts +48 -0
- package/src/world.ts +805 -0
|
@@ -0,0 +1,335 @@
|
|
|
1
|
+
import { Group, Vector3 } from "three";
|
|
2
|
+
import { exp, float, mix, uniform, vec2, vec3, vec4 } from "three/tsl";
|
|
3
|
+
import type { ComputeNode, Node, TextureNode, UniformNode } from "three/webgpu";
|
|
4
|
+
import type { IRendererLike } from "../renderer.js";
|
|
5
|
+
import { AtmosphereLuts, type IAtmosphereLutResolutions } from "./luts.js";
|
|
6
|
+
import {
|
|
7
|
+
type AtmosphereRgb,
|
|
8
|
+
type IAtmosphereParameterPatch,
|
|
9
|
+
type IAtmosphereParameters,
|
|
10
|
+
type IResolvedAtmosphereParameters,
|
|
11
|
+
type ISolarPosition,
|
|
12
|
+
type ISolarPositionInput,
|
|
13
|
+
directionFromSolarPosition,
|
|
14
|
+
directionalTransmittance,
|
|
15
|
+
resolveAtmosphereParameters,
|
|
16
|
+
solarPosition,
|
|
17
|
+
updateAtmosphereParameters,
|
|
18
|
+
} from "./params.js";
|
|
19
|
+
|
|
20
|
+
/** The structural contract consumed by the compute registry from PRD-242. */
|
|
21
|
+
interface IComputeDriven {
|
|
22
|
+
readonly warmupNodes: readonly unknown[];
|
|
23
|
+
attachRenderer(renderer: IRendererLike): void;
|
|
24
|
+
readonly processCadence?: "fixed" | "render";
|
|
25
|
+
process(renderer: IRendererLike): void;
|
|
26
|
+
detach(): void;
|
|
27
|
+
readonly released: boolean;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
export interface IAtmosphereOptions extends IAtmosphereParameters {
|
|
31
|
+
readonly resolutions?: Partial<IAtmosphereLutResolutions>;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
export interface IAtmosphereScenePass {
|
|
35
|
+
getTextureNode(name?: string): Node<"vec4">;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
export type AtmosphereDirection = Vector3 | readonly [number, number, number] | Node<"vec3">;
|
|
39
|
+
|
|
40
|
+
function isNode(value: unknown): value is Node {
|
|
41
|
+
return (
|
|
42
|
+
value !== null && typeof value === "object" && (value as { isNode?: unknown }).isNode === true
|
|
43
|
+
);
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function asVector(value: Vector3 | readonly [number, number, number]): Vector3 {
|
|
47
|
+
if (!(value instanceof Vector3) && value.length !== 3)
|
|
48
|
+
throw new Error("Atmosphere direction must contain three numbers.");
|
|
49
|
+
const result =
|
|
50
|
+
value instanceof Vector3 ? value.clone() : new Vector3(value[0], value[1], value[2]);
|
|
51
|
+
if (![result.x, result.y, result.z].every((component) => Number.isFinite(component))) {
|
|
52
|
+
throw new Error("Atmosphere direction must contain finite numbers.");
|
|
53
|
+
}
|
|
54
|
+
if (result.lengthSq() === 0) throw new Error("Atmosphere direction must not be zero.");
|
|
55
|
+
return result.normalize();
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
function averageExtinction(parameters: IResolvedAtmosphereParameters): number {
|
|
59
|
+
return (
|
|
60
|
+
(parameters.rayleigh.x +
|
|
61
|
+
parameters.rayleigh.y +
|
|
62
|
+
parameters.rayleigh.z +
|
|
63
|
+
parameters.mie.x +
|
|
64
|
+
parameters.mie.y +
|
|
65
|
+
parameters.mie.z) /
|
|
66
|
+
3
|
|
67
|
+
);
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
function directionNode(direction: AtmosphereDirection): Node<"vec3"> {
|
|
71
|
+
if (isNode(direction)) return direction as Node<"vec3">;
|
|
72
|
+
return vec3(asVector(direction));
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
function nodeRgb(value: TextureNode): Node<"vec3"> {
|
|
76
|
+
return value.rgb;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* Own the compute lifetime and expose only parameter-driven atmosphere nodes.
|
|
81
|
+
*
|
|
82
|
+
* The class deliberately creates no mesh, material, or scene light. A template chooses all of
|
|
83
|
+
* those, and the same object remains useful when a game supplies a completely different look.
|
|
84
|
+
* @situation render a sunrise that changes as time and place change
|
|
85
|
+
* @situation add distance haze from the depth of a scene pass
|
|
86
|
+
* @alias green platforms bright saturated sky
|
|
87
|
+
* @constraint supply rayleigh, mie, ozone, planetRadius, and atmosphereRadius; there is no Earth fallback
|
|
88
|
+
* @constraint the game creates the sky object, surface, and sun from the returned nodes
|
|
89
|
+
* @example const atmosphere = new Atmosphere({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
|
|
90
|
+
* ctx.add(atmosphere);
|
|
91
|
+
*/
|
|
92
|
+
export class Atmosphere extends Group implements IComputeDriven {
|
|
93
|
+
readonly luts: AtmosphereLuts;
|
|
94
|
+
#parameters: IResolvedAtmosphereParameters;
|
|
95
|
+
#renderer: IRendererLike | undefined;
|
|
96
|
+
#released = false;
|
|
97
|
+
#dirty = true;
|
|
98
|
+
#sunDirection = new Vector3(0, 1, 0);
|
|
99
|
+
#sunDirectionNode: UniformNode<"vec3", Vector3>;
|
|
100
|
+
#extinctionNode: UniformNode<"float", number>;
|
|
101
|
+
|
|
102
|
+
constructor(options: IAtmosphereOptions) {
|
|
103
|
+
super();
|
|
104
|
+
this.#parameters = resolveAtmosphereParameters(options);
|
|
105
|
+
this.luts = new AtmosphereLuts(this.#parameters, options.resolutions);
|
|
106
|
+
this.#sunDirectionNode = uniform(this.#sunDirection.clone());
|
|
107
|
+
this.#extinctionNode = uniform(averageExtinction(this.#parameters));
|
|
108
|
+
this.addEventListener("removed", this.#onRemoved);
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
get parameters(): IResolvedAtmosphereParameters {
|
|
112
|
+
return {
|
|
113
|
+
atmosphereRadius: this.#parameters.atmosphereRadius,
|
|
114
|
+
mie: this.#parameters.mie.clone(),
|
|
115
|
+
ozone: this.#parameters.ozone.clone(),
|
|
116
|
+
planetRadius: this.#parameters.planetRadius,
|
|
117
|
+
rayleigh: this.#parameters.rayleigh.clone(),
|
|
118
|
+
};
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
get warmupNodes(): readonly ComputeNode[] {
|
|
122
|
+
return this.luts.warmupNodes;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
get released(): boolean {
|
|
126
|
+
return this.#released;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
get hash(): string {
|
|
130
|
+
return this.luts.hash;
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
attachRenderer(renderer: IRendererLike): void {
|
|
134
|
+
if (this.#released) throw new Error("Atmosphere cannot be attached after release.");
|
|
135
|
+
if (this.#renderer === renderer) return;
|
|
136
|
+
this.#renderer = renderer;
|
|
137
|
+
this.#dispatch(renderer);
|
|
138
|
+
this.#dirty = false;
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
process(renderer = this.#renderer): void {
|
|
142
|
+
if (this.#released) return;
|
|
143
|
+
if (renderer === undefined) throw new Error("Atmosphere is not attached to a renderer.");
|
|
144
|
+
if (this.#dirty) {
|
|
145
|
+
this.#dispatch(renderer);
|
|
146
|
+
this.#dirty = false;
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
detach(): void {
|
|
151
|
+
if (this.#released) return;
|
|
152
|
+
this.#renderer = undefined;
|
|
153
|
+
this.luts.dispose();
|
|
154
|
+
this.#released = true;
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
setAtmosphere(patch: IAtmosphereParameterPatch): this {
|
|
158
|
+
if (this.#released) throw new Error("Atmosphere cannot change after release.");
|
|
159
|
+
this.#parameters = updateAtmosphereParameters(this.#parameters, patch);
|
|
160
|
+
this.luts.update(this.#parameters);
|
|
161
|
+
this.#extinctionNode.value = averageExtinction(this.#parameters);
|
|
162
|
+
this.#dirty = true;
|
|
163
|
+
return this;
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
setCoefficients(patch: IAtmosphereParameterPatch): this {
|
|
167
|
+
return this.setAtmosphere(patch);
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
setSunDirection(elevation: number, azimuth: number): this;
|
|
171
|
+
setSunDirection(direction: Vector3): this;
|
|
172
|
+
setSunDirection(position: Pick<ISolarPosition, "elevation" | "azimuth">): this;
|
|
173
|
+
setSunDirection(
|
|
174
|
+
elevationOrDirection: number | Vector3 | Pick<ISolarPosition, "elevation" | "azimuth">,
|
|
175
|
+
azimuth?: number,
|
|
176
|
+
): this {
|
|
177
|
+
let direction: Vector3;
|
|
178
|
+
if (typeof elevationOrDirection === "number") {
|
|
179
|
+
if (azimuth === undefined)
|
|
180
|
+
throw new Error("Atmosphere sun direction requires elevation and azimuth.");
|
|
181
|
+
direction = directionFromSolarPosition(elevationOrDirection, azimuth);
|
|
182
|
+
} else if (elevationOrDirection instanceof Vector3) {
|
|
183
|
+
direction = asVector(elevationOrDirection);
|
|
184
|
+
} else {
|
|
185
|
+
direction = directionFromSolarPosition(
|
|
186
|
+
elevationOrDirection.elevation,
|
|
187
|
+
elevationOrDirection.azimuth,
|
|
188
|
+
);
|
|
189
|
+
}
|
|
190
|
+
this.#sunDirection.copy(direction);
|
|
191
|
+
this.#sunDirectionNode.value.copy(direction);
|
|
192
|
+
return this;
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
getSunDirection(target = new Vector3()): Vector3 {
|
|
196
|
+
return target.copy(this.#sunDirection);
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/** Return the game-owned sky radiance lookup as a TSL vec3 or a CPU validation sample. */
|
|
200
|
+
radiance(direction: AtmosphereDirection): Node<"vec3"> | Vector3 {
|
|
201
|
+
if (!isNode(direction)) {
|
|
202
|
+
const normal = asVector(direction);
|
|
203
|
+
const horizon = 1 - Math.max(0, normal.y);
|
|
204
|
+
const sunWeight = Math.max(0, normal.dot(this.#sunDirection));
|
|
205
|
+
return new Vector3(
|
|
206
|
+
this.#parameters.rayleigh.x * (0.75 + horizon) + this.#parameters.mie.x * sunWeight,
|
|
207
|
+
this.#parameters.rayleigh.y * (0.75 + horizon) + this.#parameters.mie.y * sunWeight,
|
|
208
|
+
this.#parameters.rayleigh.z * (0.75 + horizon) + this.#parameters.mie.z * sunWeight,
|
|
209
|
+
);
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
const normal = directionNode(direction).normalize();
|
|
213
|
+
const uv = vec2(normal.x.mul(0.5).add(0.5), normal.y.mul(0.5).add(0.5));
|
|
214
|
+
const lookup = nodeRgb(this.luts.sampleSkyView(uv));
|
|
215
|
+
const sunWeight = normal.dot(this.#sunDirectionNode).max(0);
|
|
216
|
+
return lookup.mul(float(0.35).add(sunWeight.mul(0.65)));
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
/** Return direct solar transmittance as a TSL vec3 or a CPU validation sample. */
|
|
220
|
+
sunTransmittance(direction: AtmosphereDirection): Node<"vec3"> | Vector3 {
|
|
221
|
+
if (!isNode(direction)) return directionalTransmittance(this.#parameters, asVector(direction));
|
|
222
|
+
const normal = directionNode(direction).normalize();
|
|
223
|
+
const uv = vec2(normal.y.max(0.05), float(0.5));
|
|
224
|
+
return nodeRgb(this.luts.sampleTransmittance(uv));
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
/**
|
|
228
|
+
* Composite scene colour against game-supplied in-scattered radiance using scene-pass depth.
|
|
229
|
+
*
|
|
230
|
+
* The optional radiance node lets the game apply its own exposure or artistic tint. Leaving it
|
|
231
|
+
* out uses the raw unit-illumination LUT value and does not introduce a framework look.
|
|
232
|
+
*/
|
|
233
|
+
aerialPerspective(
|
|
234
|
+
scenePass: IAtmosphereScenePass,
|
|
235
|
+
depth: Node<"float"> | number,
|
|
236
|
+
inScatteredRadiance?: Node<"vec3"> | Vector3,
|
|
237
|
+
): Node<"vec4"> {
|
|
238
|
+
const sceneColour = scenePass.getTextureNode();
|
|
239
|
+
if (typeof depth === "number" && !Number.isFinite(depth))
|
|
240
|
+
throw new Error("Atmosphere depth must be finite.");
|
|
241
|
+
const depthNode = typeof depth === "number" ? float(depth) : depth;
|
|
242
|
+
const distanceKm = depthNode.abs().div(1000);
|
|
243
|
+
const haze = float(1)
|
|
244
|
+
.sub(exp(distanceKm.mul(this.#extinctionNode).negate()))
|
|
245
|
+
.clamp(0, 0.98);
|
|
246
|
+
const sky =
|
|
247
|
+
inScatteredRadiance === undefined
|
|
248
|
+
? (this.radiance(vec3(0, 1, 0)) as Node<"vec3">)
|
|
249
|
+
: isNode(inScatteredRadiance)
|
|
250
|
+
? (inScatteredRadiance as Node<"vec3">)
|
|
251
|
+
: vec3(inScatteredRadiance);
|
|
252
|
+
return mix(sceneColour, vec4(sky, sceneColour.a), haze);
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
#dispatch(renderer: IRendererLike): void {
|
|
256
|
+
for (const node of this.luts.warmupNodes) renderer.compute(node);
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
#onRemoved = (): void => this.detach();
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
export type {
|
|
263
|
+
AtmosphereRgb,
|
|
264
|
+
IAtmosphereParameterPatch,
|
|
265
|
+
IAtmosphereParameters,
|
|
266
|
+
IResolvedAtmosphereParameters,
|
|
267
|
+
ISolarPosition,
|
|
268
|
+
ISolarPositionInput,
|
|
269
|
+
};
|
|
270
|
+
|
|
271
|
+
/** Approximate direct transmittance for a ray leaving the game surface.
|
|
272
|
+
* @situation colour a game-owned sun from atmosphere extinction
|
|
273
|
+
* @constraint pass a non-zero direction; coefficients and radii come from the game
|
|
274
|
+
* @example const transmittance = directionalTransmittance(parameters, sunDirection);
|
|
275
|
+
*/
|
|
276
|
+
export { directionalTransmittance } from "./params.js";
|
|
277
|
+
|
|
278
|
+
/** Convert solar elevation and azimuth degrees into a normalized Three.js direction.
|
|
279
|
+
* @situation aim a template's sun from solarPosition output
|
|
280
|
+
* @constraint elevation and azimuth must be finite degrees
|
|
281
|
+
* @example const direction = directionFromSolarPosition(sun.elevation, sun.azimuth);
|
|
282
|
+
*/
|
|
283
|
+
export { directionFromSolarPosition } from "./params.js";
|
|
284
|
+
|
|
285
|
+
/** Validate and clone game-owned atmosphere coefficients.
|
|
286
|
+
* @situation validate atmosphere coefficients before a game creates its sky
|
|
287
|
+
* @constraint provide all three coefficient vectors and both radii; omitted fields are errors
|
|
288
|
+
* @example const parameters = resolveAtmosphereParameters({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
|
|
289
|
+
*/
|
|
290
|
+
export { resolveAtmosphereParameters } from "./params.js";
|
|
291
|
+
|
|
292
|
+
/** Calculate solar elevation and azimuth from time, latitude, and longitude.
|
|
293
|
+
* @situation move a sun across a real day at a game's latitude and longitude
|
|
294
|
+
* @situation run a day and night cycle over the game's sky
|
|
295
|
+
* @constraint dates are interpreted as UTC unless utcOffset is supplied; no fixed sun direction is assumed
|
|
296
|
+
* @example const sun = solarPosition({ date, latitude: 49.28, longitude: -123.12, utcOffset: -8 });
|
|
297
|
+
*/
|
|
298
|
+
export { solarPosition } from "./params.js";
|
|
299
|
+
|
|
300
|
+
/** Apply a partial game-owned atmosphere change while preserving validation.
|
|
301
|
+
* @situation change scattering coefficients and rebake an atmosphere
|
|
302
|
+
* @constraint patches cannot introduce omitted, negative, or non-finite physical values
|
|
303
|
+
* @example atmosphere.setAtmosphere({ rayleigh: [0.008, 0.016, 0.04] });
|
|
304
|
+
*/
|
|
305
|
+
export { updateAtmosphereParameters } from "./params.js";
|
|
306
|
+
|
|
307
|
+
/** Return direct vertical transmittance for the supplied atmosphere.
|
|
308
|
+
* @situation check a supplied atmosphere's direct vertical transmittance
|
|
309
|
+
* @constraint use the returned value as a validation oracle; the rendered path samples the LUT
|
|
310
|
+
* @example const zenith = zenithTransmittance({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
|
|
311
|
+
*/
|
|
312
|
+
export { zenithTransmittance } from "./params.js";
|
|
313
|
+
export {
|
|
314
|
+
ATMOSPHERE_LUT_RESOLUTIONS,
|
|
315
|
+
AtmosphereLuts,
|
|
316
|
+
LUT_RESOLUTIONS,
|
|
317
|
+
resolveAtmosphereLutResolutions,
|
|
318
|
+
} from "./luts.js";
|
|
319
|
+
export type {
|
|
320
|
+
IAtmosphereLutResolution,
|
|
321
|
+
IAtmosphereLutResolutions,
|
|
322
|
+
} from "./luts.js";
|
|
323
|
+
|
|
324
|
+
/** Calculate solar elevation and azimuth for one UTC date.
|
|
325
|
+
* @situation calculate a sun direction from a timestamp and a game location
|
|
326
|
+
* @constraint dates are interpreted as UTC; use solarPosition for an explicit local offset
|
|
327
|
+
* @example const sun = solarPositionAt(new Date(), 49.28, -123.12);
|
|
328
|
+
*/
|
|
329
|
+
export function solarPositionAt(
|
|
330
|
+
date: Date | string,
|
|
331
|
+
latitude: number,
|
|
332
|
+
longitude: number,
|
|
333
|
+
): ISolarPosition {
|
|
334
|
+
return solarPosition({ date, latitude, longitude });
|
|
335
|
+
}
|
|
@@ -0,0 +1,298 @@
|
|
|
1
|
+
import { ClampToEdgeWrapping, HalfFloatType, LinearFilter, RGBAFormat } from "three";
|
|
2
|
+
import {
|
|
3
|
+
Fn,
|
|
4
|
+
exp,
|
|
5
|
+
float,
|
|
6
|
+
instanceIndex,
|
|
7
|
+
texture,
|
|
8
|
+
textureStore,
|
|
9
|
+
uniform,
|
|
10
|
+
uvec2,
|
|
11
|
+
vec2,
|
|
12
|
+
vec4,
|
|
13
|
+
} from "three/tsl";
|
|
14
|
+
import { StorageTexture } from "three/webgpu";
|
|
15
|
+
import type { ComputeNode, Node, TextureNode, UniformNode } from "three/webgpu";
|
|
16
|
+
import {
|
|
17
|
+
type IAtmosphereParameters,
|
|
18
|
+
type IResolvedAtmosphereParameters,
|
|
19
|
+
resolveAtmosphereParameters,
|
|
20
|
+
} from "./params.js";
|
|
21
|
+
|
|
22
|
+
export interface IAtmosphereLutResolution {
|
|
23
|
+
readonly width: number;
|
|
24
|
+
readonly height: number;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
export interface IAtmosphereLutResolutions {
|
|
28
|
+
readonly transmittance: IAtmosphereLutResolution;
|
|
29
|
+
readonly multiScattering: IAtmosphereLutResolution;
|
|
30
|
+
readonly skyView: IAtmosphereLutResolution;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/** The reference dimensions; games may provide smaller dimensions when their startup budget says so. */
|
|
34
|
+
export const ATMOSPHERE_LUT_RESOLUTIONS: IAtmosphereLutResolutions = {
|
|
35
|
+
multiScattering: { height: 32, width: 32 },
|
|
36
|
+
skyView: { height: 108, width: 192 },
|
|
37
|
+
transmittance: { height: 64, width: 256 },
|
|
38
|
+
};
|
|
39
|
+
|
|
40
|
+
export const LUT_RESOLUTIONS = ATMOSPHERE_LUT_RESOLUTIONS;
|
|
41
|
+
|
|
42
|
+
interface IParameterUniforms {
|
|
43
|
+
readonly atmosphereRadius: UniformNode<"float", number>;
|
|
44
|
+
readonly mie: UniformNode<"vec3", import("three").Vector3>;
|
|
45
|
+
readonly ozone: UniformNode<"vec3", import("three").Vector3>;
|
|
46
|
+
readonly planetRadius: UniformNode<"float", number>;
|
|
47
|
+
readonly rayleigh: UniformNode<"vec3", import("three").Vector3>;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
function checkedResolution(
|
|
51
|
+
value: IAtmosphereLutResolution,
|
|
52
|
+
name: string,
|
|
53
|
+
): IAtmosphereLutResolution {
|
|
54
|
+
if (
|
|
55
|
+
!Number.isInteger(value.width) ||
|
|
56
|
+
!Number.isInteger(value.height) ||
|
|
57
|
+
value.width <= 0 ||
|
|
58
|
+
value.height <= 0
|
|
59
|
+
) {
|
|
60
|
+
throw new Error(`Atmosphere.${name} resolution must contain positive integers.`);
|
|
61
|
+
}
|
|
62
|
+
return { height: value.height, width: value.width };
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** Resolve the three LUT dimensions, allowing a game to trade startup cost for resolution.
|
|
66
|
+
* @situation choose atmosphere LUT dimensions for a measured startup budget
|
|
67
|
+
* @constraint every width and height must be a positive integer; the dimensions are not a named fidelity tier
|
|
68
|
+
* @example const resolutions = resolveAtmosphereLutResolutions({ skyView: { width: 128, height: 72 } });
|
|
69
|
+
*/
|
|
70
|
+
export function resolveAtmosphereLutResolutions(
|
|
71
|
+
resolutions: Partial<IAtmosphereLutResolutions> | undefined,
|
|
72
|
+
): IAtmosphereLutResolutions {
|
|
73
|
+
const source = resolutions ?? {};
|
|
74
|
+
return {
|
|
75
|
+
multiScattering: checkedResolution(
|
|
76
|
+
source.multiScattering ?? ATMOSPHERE_LUT_RESOLUTIONS.multiScattering,
|
|
77
|
+
"multiScattering",
|
|
78
|
+
),
|
|
79
|
+
skyView: checkedResolution(source.skyView ?? ATMOSPHERE_LUT_RESOLUTIONS.skyView, "skyView"),
|
|
80
|
+
transmittance: checkedResolution(
|
|
81
|
+
source.transmittance ?? ATMOSPHERE_LUT_RESOLUTIONS.transmittance,
|
|
82
|
+
"transmittance",
|
|
83
|
+
),
|
|
84
|
+
};
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
function storageTexture(resolution: IAtmosphereLutResolution): StorageTexture {
|
|
88
|
+
const texture = new StorageTexture(resolution.width, resolution.height);
|
|
89
|
+
texture.type = HalfFloatType;
|
|
90
|
+
texture.format = RGBAFormat;
|
|
91
|
+
texture.minFilter = LinearFilter;
|
|
92
|
+
texture.magFilter = LinearFilter;
|
|
93
|
+
texture.wrapS = ClampToEdgeWrapping;
|
|
94
|
+
texture.wrapT = ClampToEdgeWrapping;
|
|
95
|
+
(texture as StorageTexture & { mipmapsAutoUpdate: boolean }).mipmapsAutoUpdate = false;
|
|
96
|
+
return texture;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
function hashNumber(value: number): number {
|
|
100
|
+
const view = new DataView(new ArrayBuffer(8));
|
|
101
|
+
view.setFloat64(0, value);
|
|
102
|
+
let hash = 2166136261;
|
|
103
|
+
for (let index = 0; index < 8; index += 1) {
|
|
104
|
+
hash ^= view.getUint8(index);
|
|
105
|
+
hash = Math.imul(hash, 16777619);
|
|
106
|
+
}
|
|
107
|
+
return hash >>> 0;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
function hashParameters(
|
|
111
|
+
parameters: IResolvedAtmosphereParameters,
|
|
112
|
+
resolutions: IAtmosphereLutResolutions,
|
|
113
|
+
): string {
|
|
114
|
+
let hash = 2166136261;
|
|
115
|
+
const values = [
|
|
116
|
+
parameters.rayleigh.x,
|
|
117
|
+
parameters.rayleigh.y,
|
|
118
|
+
parameters.rayleigh.z,
|
|
119
|
+
parameters.mie.x,
|
|
120
|
+
parameters.mie.y,
|
|
121
|
+
parameters.mie.z,
|
|
122
|
+
parameters.ozone.x,
|
|
123
|
+
parameters.ozone.y,
|
|
124
|
+
parameters.ozone.z,
|
|
125
|
+
parameters.planetRadius,
|
|
126
|
+
parameters.atmosphereRadius,
|
|
127
|
+
resolutions.transmittance.width,
|
|
128
|
+
resolutions.transmittance.height,
|
|
129
|
+
resolutions.multiScattering.width,
|
|
130
|
+
resolutions.multiScattering.height,
|
|
131
|
+
resolutions.skyView.width,
|
|
132
|
+
resolutions.skyView.height,
|
|
133
|
+
];
|
|
134
|
+
for (const value of values) hash = Math.imul(hash ^ hashNumber(value), 16777619);
|
|
135
|
+
return hash.toString(16).padStart(8, "0");
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
function uniforms(parameters: IResolvedAtmosphereParameters): IParameterUniforms {
|
|
139
|
+
return {
|
|
140
|
+
atmosphereRadius: uniform(parameters.atmosphereRadius),
|
|
141
|
+
mie: uniform(parameters.mie.clone()),
|
|
142
|
+
ozone: uniform(parameters.ozone.clone()),
|
|
143
|
+
planetRadius: uniform(parameters.planetRadius),
|
|
144
|
+
rayleigh: uniform(parameters.rayleigh.clone()),
|
|
145
|
+
};
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
function bake2d(
|
|
149
|
+
target: StorageTexture,
|
|
150
|
+
resolution: IAtmosphereLutResolution,
|
|
151
|
+
value: (uv: Node<"vec2">, x: Node<"uint">, y: Node<"uint">) => Node<"vec4">,
|
|
152
|
+
): ComputeNode {
|
|
153
|
+
return Fn(() => {
|
|
154
|
+
const x = instanceIndex.mod(resolution.width);
|
|
155
|
+
const y = instanceIndex.div(resolution.width);
|
|
156
|
+
const uv = vec2(
|
|
157
|
+
float(x).add(0.5).div(resolution.width),
|
|
158
|
+
float(y).add(0.5).div(resolution.height),
|
|
159
|
+
);
|
|
160
|
+
textureStore(target, uvec2(x, y), value(uv, x, y));
|
|
161
|
+
})().compute(resolution.width * resolution.height);
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
function bakeTransmittance(
|
|
165
|
+
target: StorageTexture,
|
|
166
|
+
resolution: IAtmosphereLutResolution,
|
|
167
|
+
parameterUniforms: IParameterUniforms,
|
|
168
|
+
): ComputeNode {
|
|
169
|
+
return bake2d(target, resolution, (uv) => {
|
|
170
|
+
const thickness = parameterUniforms.atmosphereRadius.sub(parameterUniforms.planetRadius);
|
|
171
|
+
const rayleighColumn = float(8).mul(float(1).sub(exp(thickness.negate().div(8))));
|
|
172
|
+
const mieColumn = float(1.2).mul(float(1).sub(exp(thickness.negate().div(1.2))));
|
|
173
|
+
const airMass = float(1).div(uv.x.max(0.05));
|
|
174
|
+
const opticalDepth = parameterUniforms.rayleigh
|
|
175
|
+
.mul(rayleighColumn)
|
|
176
|
+
.add(parameterUniforms.mie.mul(mieColumn))
|
|
177
|
+
.add(parameterUniforms.ozone.mul(15))
|
|
178
|
+
.mul(airMass);
|
|
179
|
+
return vec4(exp(opticalDepth.negate()), 1);
|
|
180
|
+
});
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
function sampleLut(target: StorageTexture, uv: Node<"vec2">): TextureNode {
|
|
184
|
+
return texture(target, uv.clamp(0, 1)).level(float(0));
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
function bakeMultiScattering(
|
|
188
|
+
target: StorageTexture,
|
|
189
|
+
resolution: IAtmosphereLutResolution,
|
|
190
|
+
parameterUniforms: IParameterUniforms,
|
|
191
|
+
transmittance: StorageTexture,
|
|
192
|
+
): ComputeNode {
|
|
193
|
+
return bake2d(target, resolution, (uv) => {
|
|
194
|
+
const altitudeWeight = float(1).sub(uv.y);
|
|
195
|
+
const angularWeight = float(0.5).add(uv.x.mul(0.5));
|
|
196
|
+
const directTransmittance = sampleLut(transmittance, uv).rgb;
|
|
197
|
+
const scattering = parameterUniforms.rayleigh
|
|
198
|
+
.mul(altitudeWeight)
|
|
199
|
+
.add(parameterUniforms.mie.mul(angularWeight))
|
|
200
|
+
.add(parameterUniforms.ozone.mul(0.02));
|
|
201
|
+
return vec4(scattering.mul(directTransmittance), 1);
|
|
202
|
+
});
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
function bakeSkyView(
|
|
206
|
+
target: StorageTexture,
|
|
207
|
+
resolution: IAtmosphereLutResolution,
|
|
208
|
+
parameterUniforms: IParameterUniforms,
|
|
209
|
+
transmittance: StorageTexture,
|
|
210
|
+
multiScattering: StorageTexture,
|
|
211
|
+
): ComputeNode {
|
|
212
|
+
return bake2d(target, resolution, (uv) => {
|
|
213
|
+
const horizonWeight = float(1).sub(uv.y).max(0);
|
|
214
|
+
const sunWeight = float(0.25).add(uv.x.mul(0.75));
|
|
215
|
+
const directTransmittance = sampleLut(transmittance, uv).rgb;
|
|
216
|
+
const higherOrderScattering = sampleLut(multiScattering, uv).rgb;
|
|
217
|
+
const scattering = parameterUniforms.rayleigh
|
|
218
|
+
.mul(horizonWeight.mul(1.5))
|
|
219
|
+
.add(parameterUniforms.mie.mul(sunWeight))
|
|
220
|
+
.add(parameterUniforms.ozone.mul(0.01));
|
|
221
|
+
return vec4(scattering.mul(directTransmittance).add(higherOrderScattering), 1);
|
|
222
|
+
});
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
/** Own the transmittance, multi-scattering, and sky-view compute lookup textures.
|
|
226
|
+
* @situation bake the three atmosphere LUTs once before a game shows its world
|
|
227
|
+
* @constraint supply all physical parameters; this class creates no scene appearance
|
|
228
|
+
* @example const luts = new AtmosphereLuts({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
|
|
229
|
+
*/
|
|
230
|
+
export class AtmosphereLuts {
|
|
231
|
+
readonly resolutions: IAtmosphereLutResolutions;
|
|
232
|
+
readonly transmittance: StorageTexture;
|
|
233
|
+
readonly multiScattering: StorageTexture;
|
|
234
|
+
readonly skyView: StorageTexture;
|
|
235
|
+
readonly warmupNodes: readonly ComputeNode[];
|
|
236
|
+
readonly uniforms: IParameterUniforms;
|
|
237
|
+
#hash: string;
|
|
238
|
+
|
|
239
|
+
constructor(
|
|
240
|
+
parameters: IAtmosphereParametersLike,
|
|
241
|
+
resolutions?: Partial<IAtmosphereLutResolutions>,
|
|
242
|
+
) {
|
|
243
|
+
const resolved = resolveAtmosphereParameters(parameters);
|
|
244
|
+
this.resolutions = resolveAtmosphereLutResolutions(resolutions);
|
|
245
|
+
this.transmittance = storageTexture(this.resolutions.transmittance);
|
|
246
|
+
this.multiScattering = storageTexture(this.resolutions.multiScattering);
|
|
247
|
+
this.skyView = storageTexture(this.resolutions.skyView);
|
|
248
|
+
this.uniforms = uniforms(resolved);
|
|
249
|
+
this.warmupNodes = [
|
|
250
|
+
bakeTransmittance(this.transmittance, this.resolutions.transmittance, this.uniforms),
|
|
251
|
+
bakeMultiScattering(
|
|
252
|
+
this.multiScattering,
|
|
253
|
+
this.resolutions.multiScattering,
|
|
254
|
+
this.uniforms,
|
|
255
|
+
this.transmittance,
|
|
256
|
+
),
|
|
257
|
+
bakeSkyView(
|
|
258
|
+
this.skyView,
|
|
259
|
+
this.resolutions.skyView,
|
|
260
|
+
this.uniforms,
|
|
261
|
+
this.transmittance,
|
|
262
|
+
this.multiScattering,
|
|
263
|
+
),
|
|
264
|
+
];
|
|
265
|
+
this.#hash = hashParameters(resolved, this.resolutions);
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
get hash(): string {
|
|
269
|
+
return this.#hash;
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
update(parameters: IAtmosphereParametersLike): void {
|
|
273
|
+
const resolved = resolveAtmosphereParameters(parameters);
|
|
274
|
+
this.uniforms.atmosphereRadius.value = resolved.atmosphereRadius;
|
|
275
|
+
this.uniforms.mie.value.copy(resolved.mie);
|
|
276
|
+
this.uniforms.ozone.value.copy(resolved.ozone);
|
|
277
|
+
this.uniforms.planetRadius.value = resolved.planetRadius;
|
|
278
|
+
this.uniforms.rayleigh.value.copy(resolved.rayleigh);
|
|
279
|
+
this.#hash = hashParameters(resolved, this.resolutions);
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
sampleTransmittance(uv: Node<"vec2">): TextureNode {
|
|
283
|
+
return sampleLut(this.transmittance, uv);
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
sampleSkyView(uv: Node<"vec2">): TextureNode {
|
|
287
|
+
return sampleLut(this.skyView, uv);
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
dispose(): void {
|
|
291
|
+
for (const node of this.warmupNodes) node.dispose();
|
|
292
|
+
this.transmittance.dispose();
|
|
293
|
+
this.multiScattering.dispose();
|
|
294
|
+
this.skyView.dispose();
|
|
295
|
+
}
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
export type IAtmosphereParametersLike = IResolvedAtmosphereParameters | IAtmosphereParameters;
|