@threenative/core 0.3.11 → 0.3.13
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 +1 -1
- package/capabilities.json +1988 -204
- package/dist/{assets-YUbXa3-Y.d.ts → assets-CfMKnOsK.d.ts} +78 -1
- package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
- package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-G7ttVy7y.d.ts} +1 -1
- package/dist/chunk-4SRAQFTU.js +133 -0
- package/dist/chunk-CFGTPFUH.js +231 -0
- package/dist/chunk-DIPIJICH.js +8916 -0
- package/dist/chunk-EEABDLUC.js +2237 -0
- package/dist/chunk-EFWZWLPY.js +1895 -0
- package/dist/chunk-GXY7B3JG.js +46 -0
- package/dist/chunk-GYUZJQ7U.js +280 -0
- package/dist/chunk-H4J6IAJE.js +504 -0
- package/dist/chunk-KIRUKTBQ.js +187 -0
- package/dist/chunk-QWJEMUUT.js +94 -0
- package/dist/chunk-SV4QVUTQ.js +31 -0
- package/dist/chunk-U4YHUKKL.js +615 -0
- package/dist/chunk-VP43GIWW.js +18 -0
- package/dist/chunk-XDTZ4QMO.js +160 -0
- package/dist/default-tone-mapping-GgKPTiBP.d.ts +4 -0
- package/dist/{game-DzMcitDO.d.ts → game-k8K3hZai.d.ts} +85 -9
- package/dist/hot.d.ts +5 -4
- package/dist/hot.js +5 -52
- package/dist/index.d.ts +633 -1351
- package/dist/index.js +12873 -23068
- package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-DPTzeCcD.d.ts} +35 -3
- package/dist/playtest.d.ts +5 -4
- package/dist/playtest.js +25 -75
- package/dist/quality-BYqKGAwo.d.ts +868 -0
- package/dist/react-css.js +1 -215
- package/dist/react.d.ts +3 -2
- package/dist/render-environment.d.ts +170 -0
- package/dist/render-environment.js +352 -0
- package/dist/{renderer-rZm0hVqq.d.ts → renderer-BtOSseYf.d.ts} +42 -35
- package/dist/spells/index.d.ts +643 -0
- package/dist/spells/index.js +1558 -0
- package/dist/spells/ultra/index.d.ts +1600 -0
- package/dist/spells/ultra/index.js +6804 -0
- package/dist/terrain-jobs-worker.js +1 -123
- package/dist/two-sided-foliage-W523J3UM.js +1 -0
- package/dist/ui-layer.js +6 -384
- package/dist/worker.js +13 -43
- package/dist/world.d.ts +988 -268
- package/dist/world.js +17464 -18290
- package/mcp/animation-server.mjs +1 -1
- package/mcp/animation.mjs +2 -3
- package/mcp/engine-server.mjs +245 -52
- package/mcp/servers.mjs +10 -3
- package/mcp/terrain.mjs +8 -0
- package/package.json +19 -7
- package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
- package/patches/three@0.187.0.patch +2004 -407
- package/src/animation-batch.ts +193 -0
- package/src/animation-layers.ts +7 -3
- package/src/animation.ts +209 -29
- package/src/asset-cache.ts +3 -3
- package/src/asset-memo.ts +202 -0
- package/src/assets.ts +437 -125
- package/src/auto-batch.ts +190 -44
- package/src/card-lod.ts +152 -0
- package/src/compressed-texture-preparation.ts +1008 -0
- package/src/compute-driven.ts +1 -1
- package/src/config.ts +8 -0
- package/src/debug.ts +103 -22
- package/src/dev-global.ts +54 -0
- package/src/engine-hooks.ts +37 -0
- package/src/frame-budget.ts +50 -23
- package/src/game-boot-phase.ts +269 -0
- package/src/game-dev-tools.ts +86 -0
- package/src/game-frame-loop.ts +958 -0
- package/src/game-renderer-metrics.ts +77 -0
- package/src/game-startup.ts +1076 -0
- package/src/game-ui.ts +84 -0
- package/src/game-validate.ts +70 -0
- package/src/game.ts +198 -2264
- package/src/gamepad-mappings.ts +269 -0
- package/src/generated/console-markers.ts +13 -0
- package/src/geometry-capture.ts +28 -4
- package/src/gpu-readings.ts +98 -0
- package/src/gpu-scene-bvh.ts +149 -36
- package/src/hot.ts +4 -7
- package/src/index.ts +141 -9
- package/src/input.ts +237 -25
- package/src/instanced-batch-lod.ts +3 -8
- package/src/interpolation.ts +171 -40
- package/src/launch-diagnostics.ts +22 -12
- package/src/look/ao-admission.ts +25 -0
- package/src/look/auto-exposure.ts +5 -16
- package/src/look/default-tone-mapping.ts +41 -5
- package/src/look/filmic-tone-mapping.ts +15 -13
- package/src/look/local-exposure.ts +2 -7
- package/src/look/look-diagnostics.ts +3 -3
- package/src/look/quad-pass.ts +21 -0
- package/src/look/quality.ts +14 -5
- package/src/look/unreal-bloom.ts +4 -13
- package/src/look/world-environment.ts +113 -103
- package/src/loop.ts +29 -0
- package/src/merge-parts.ts +20 -24
- package/src/model-lod.ts +139 -17
- package/src/particle-kinds.ts +515 -0
- package/src/particle-significance.ts +12 -0
- package/src/particles.ts +19 -10
- package/src/picking.ts +17 -3
- package/src/platform.ts +23 -4
- package/src/playtest.ts +27 -1
- package/src/profiling/FrameStages.ts +5 -6
- package/src/profiling/Spans.ts +3 -17
- package/src/profiling/debug-telemetry.ts +2 -6
- package/src/profiling/render-list-validate.ts +6 -15
- package/src/projection-apply.ts +4 -1
- package/src/projection-marker.ts +2 -1
- package/src/projection-plan.ts +9 -6
- package/src/quiet-markers.ts +3 -10
- package/src/render/cpu-bvh.ts +100 -0
- package/src/render/depth-pyramid.ts +6 -14
- package/src/render/environment/environmentContribution.ts +202 -0
- package/src/render/environment/environmentRadiance.ts +44 -0
- package/src/render/environment/environmentSampleCache.ts +56 -0
- package/src/render/environment/environmentSampling.ts +201 -0
- package/src/render/environment/environmentSnapshot.ts +71 -0
- package/src/render/environment/gate.ts +57 -0
- package/src/render/mesh-pool.ts +4 -20
- package/src/render/probe-trace.ts +872 -0
- package/src/render/probe-volume.ts +780 -34
- package/src/render/radiance-cache.ts +17 -0
- package/src/render/resolution-subrect.ts +2 -0
- package/src/render/rough-diffuse.ts +46 -12
- package/src/render/soft-shadow.ts +27 -12
- package/src/render/virtual-shadow-adaptive.ts +55 -0
- package/src/render/virtual-shadow-casters.ts +175 -0
- package/src/render/virtual-shadow-layers.ts +76 -0
- package/src/render/virtual-shadow-level.ts +224 -0
- package/src/render/virtual-shadow-markers.ts +193 -0
- package/src/render/virtual-shadow-options.ts +370 -0
- package/src/render/virtual-shadow-pages.ts +5 -0
- package/src/render/virtual-shadow-partial.ts +13 -0
- package/src/render/virtual-shadow.ts +231 -1008
- package/src/render/world-impostor-surface.ts +402 -40
- package/src/render/world-impostor.ts +5 -2
- package/src/render-camera-cull.ts +98 -3
- package/src/render-environment.ts +41 -0
- package/src/render-pass-budget.ts +34 -7
- package/src/renderProjection.ts +22 -0
- package/src/renderer-config.ts +36 -0
- package/src/renderer-facts.ts +37 -0
- package/src/renderer.ts +144 -65
- package/src/resolution-scaler.ts +3 -2
- package/src/scene-entry-inspectors.ts +61 -0
- package/src/snow-field.ts +2 -1
- package/src/spells/cast-pool.ts +361 -0
- package/src/spells/index.ts +177 -0
- package/src/spells/mechanisms.ts +295 -0
- package/src/spells/reaction-field.ts +415 -0
- package/src/spells/spell-lights.ts +139 -0
- package/src/spells/spell-world.ts +187 -0
- package/src/spells/spell.ts +397 -0
- package/src/spells/spells.ts +283 -0
- package/src/spells/ultra/engine/camera.ts +184 -0
- package/src/spells/ultra/engine/quality.ts +96 -0
- package/src/spells/ultra/index.ts +52 -0
- package/src/spells/ultra/main.ts +305 -0
- package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
- package/src/spells/ultra/spells/cast.ts +233 -0
- package/src/spells/ultra/spells/fire.ts +1267 -0
- package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
- package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
- package/src/spells/ultra/vfx/FxTarget.ts +61 -0
- package/src/spells/ultra/vfx/GroundField.ts +1399 -0
- package/src/spells/ultra/vfx/Particles.ts +1475 -0
- package/src/spells/ultra/vfx/Ribbons.ts +645 -0
- package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
- package/src/spells/ultra/vfx/Volumes.ts +489 -0
- package/src/spells/ultra/vfx/common.ts +1195 -0
- package/src/spells/ultra/vfx/noise.ts +441 -0
- package/src/startup-offscreen-bytes.ts +78 -0
- package/src/startup-readiness.ts +128 -34
- package/src/static-transform.ts +25 -19
- package/src/streamed-textures.ts +112 -0
- package/src/streaming.ts +68 -4
- package/src/texture-streaming.ts +331 -0
- package/src/version.ts +1 -1
- package/src/warmup.ts +56 -8
- package/src/water-surface.ts +9 -3
- package/src/worker.ts +12 -2
- package/src/world-bundle-safety.ts +446 -0
- package/src/world-cell-batches.ts +1178 -0
- package/src/world-cell-chunks.ts +1128 -0
- package/src/world-cell-data.ts +995 -0
- package/src/world-cell-impostors.ts +1461 -0
- package/src/world-cell-lod-bias.ts +151 -0
- package/src/world-cell-models.ts +1074 -0
- package/src/world-cell-options.ts +177 -0
- package/src/world-cell-placements.ts +798 -0
- package/src/world-cell-prewarm.ts +592 -0
- package/src/world-cell-readiness.ts +357 -0
- package/src/world-cell-records.ts +401 -0
- package/src/world-cell-render-bundles.ts +459 -0
- package/src/world-cell-render-gpu-dress.ts +710 -0
- package/src/world-cell-render-main-cull.ts +540 -0
- package/src/world-cell-render-shadow-claims.ts +198 -0
- package/src/world-cell-render-util.ts +259 -0
- package/src/world-cell-render.ts +1501 -0
- package/src/world-cell-residency.ts +754 -0
- package/src/world-cell-stale.ts +238 -0
- package/src/world-cells.ts +1335 -10418
- package/src/world-chunk-shadow.ts +308 -0
- package/src/world-collar.ts +315 -0
- package/src/world-gpu-flags.ts +131 -0
- package/src/world-gpu-readback.ts +881 -0
- package/src/world-gpu-reference.ts +524 -0
- package/src/world-gpu-scene.ts +256 -2286
- package/src/world-gpu-shadow.ts +203 -0
- package/src/world-gpu-types.ts +409 -0
- package/src/world-gpu-validation.ts +518 -0
- package/src/world-heightfield.ts +802 -0
- package/src/world-load-limiter.ts +111 -0
- package/src/world-model-sections.ts +80 -0
- package/src/world-noise.ts +241 -0
- package/src/world-package.ts +42 -0
- package/src/world-region.ts +1 -1
- package/src/world-river-ribbon.ts +282 -0
- package/src/world-root-frame.ts +39 -0
- package/src/world-shore-field.ts +91 -0
- package/src/world-static-pose.ts +163 -0
- package/src/world-surface-sampler.ts +48 -0
- package/src/world-terrain-splat.ts +361 -153
- package/src/world-tile-budget.ts +249 -0
- package/src/world-tile-geometry.ts +469 -0
- package/src/world-tile-lod.ts +408 -0
- package/src/world-tile-observation.ts +566 -0
- package/src/world-tile-stitch.ts +166 -0
- package/src/world-tiles.ts +247 -1755
- package/src/world-validate.ts +6 -14
- package/src/world-warm.ts +51 -0
- package/src/world-water-bodies.ts +359 -0
- package/src/world.ts +48 -741
package/dist/index.d.ts
CHANGED
|
@@ -1,46 +1,25 @@
|
|
|
1
1
|
import * as three from 'three';
|
|
2
|
-
import { Object3D, AnimationClip, AnimationMixer, Vector3, Camera, Group, Scene, Texture, Matrix4, Mesh, BufferGeometry,
|
|
3
|
-
export {
|
|
2
|
+
import { Object3D, AnimationClip, AnimationMixer, Vector3, Camera, Group, Scene, Texture, Matrix4, Mesh, BufferGeometry, Material, Color, InstancedMesh, ColorRepresentation, Box3, DirectionalLight, DepthTexture, LightShadow, HemisphereLight, ToneMapping, FogExp2, Sprite, DataTexture, CatmullRomCurve3 } from 'three';
|
|
3
|
+
export { a as CameraShake, C as CameraShakeCurve, I as ICameraShakeOffset, b as ICameraShakeOptions } from './camera-shake-CZKOfGn4.js';
|
|
4
|
+
export { A as ASSET_LATE_MARKER, b as AssetPriority, c as IAssetCacheReport, d as IAssetCacheState, I as IAssetLoader, a as IAssetLoaderOptions, e as IAssetPrefetchProgress, f as IAssetRequestOptions, g as ITextureOptions, h as createAssetLoader, i as fetchAsset, r as reconcileMirroredClips } from './assets-CfMKnOsK.js';
|
|
4
5
|
export { A as AudioBus, I as IAudioBusOptions, b as IAudioCompressorOptions, c as IAudioPlayOptions, r as resetAudioCueLedger } from './audio-DIJE5HTr.js';
|
|
5
|
-
export { C as CanvasLayer } from './canvas-layer-
|
|
6
|
-
import { b as IGamePluginRuntime, a as IGamePluginHooks } from './game-
|
|
7
|
-
export { A as AfterPhysicsCallback, C as ContextMenuPolicy, G as GEOMETRY_ASSET_KEY,
|
|
6
|
+
export { C as CanvasLayer } from './canvas-layer-G7ttVy7y.js';
|
|
7
|
+
import { E as EntitySnapshot, b as IGeometryCaptureRequest, c as IGeometryCaptureReport, d as IGamePluginRuntime, a as IGamePluginHooks } from './game-k8K3hZai.js';
|
|
8
|
+
export { A as AfterPhysicsCallback, C as ContextMenuPolicy, G as GEOMETRY_ASSET_KEY, e as GEOMETRY_CAPTURE_DEFAULT_LIMIT, f as GEOMETRY_CAPTURE_MAX_LIMIT, g as GEOMETRY_CAPTURE_SORTS, h as GEOMETRY_CAPTURE_TIMEOUT_MS, i as GEOMETRY_CAPTURE_WALK_CAP, j as GeometryCaptureSort, k as ICtx, I as IGame, l as IGameObservationContribution, m as IGameObservationSampleRequest, n as IGamePlatformSource, o as IGeometryCaptureAsset, p as IGeometryCaptureMesh, q as IGeometryCapturePass, r as IGeometryCaptureRow, s as IInputAction, t as IInputGamepad, u as IInputMapOptions, v as IPointerDragHandle, w as IPointerEvent3D, x as IPointerEvents3D, y as IPointerEvents3DOptions, z as IPointerEvents3DPicker, B as IPointerState, D as IRandom, F as IRawInputPointer, H as IRawInputPointerEdge, J as IRawInputState, K as IRaycastOptions, L as IScenePickerOptions, M as IThreeNativeAudioConfig, N as IThreeNativeAudioLoop, O as IThreeNativeAudioOverride, P as IThreeNativeAudioSpectrum, Q as IThreeNativeBootSplash, R as IThreeNativeConfig, S as IThreeNativeIconVariants, T as IThreeNativeLodConfig, U as IThreeNativeLodGenerationConfig, V as IThreeNativeLodOverride, W as IThreeNativeLodRuntimeConfig, X as IThreeNativeTexturesConfig, Y as ITweenOptions, Z as IWarmUpCacheOptions, _ as IWarmUpObservation, $ as IWarmUpOptions, a0 as IWarmUpProgress, a1 as IWarmUpRenderer, a2 as IWarmUpReport, a3 as InputBindings, a4 as InputMap, a5 as InputPlatformSource, a6 as PointerEvent3DListener, a7 as PointerEvent3DType, a8 as PointerEvents3D, a9 as Scene, aa as SceneFrame, ab as ScenePicker, ac as ScheduleHandle, ad as Scheduler, ae as ThreeNativeBackgroundMode, af as ThreeNativeLodMinTrianglesScope, ag as ThreeNativeLodPreset, ah as ThreeNativeOrientation, ai as ThreeNativeUiRenderer, aj as WarmUpCacheStatus, ak as WarmUpObservationStatus, al as afterPhysics, am as captureMouse, an as createRandom, ao as defineGame, ap as warmUpScene } from './game-k8K3hZai.js';
|
|
8
9
|
import * as three_webgpu from 'three/webgpu';
|
|
9
10
|
import { StorageTexture, ComputeNode, UniformNode, Node, TextureNode, CubeRenderTarget, WebGPURenderer, NodeMaterial, StorageBufferNode, StructTypeNode, Data3DTexture, ShadowBaseNode, NodeBuilder, NodeFrame, SpriteNodeMaterial, StorageTextureNode, Storage3DTexture } from 'three/webgpu';
|
|
10
|
-
import { I as IRendererLike, h as IStageGpuReading, F as FramePassKind, a as IFrameBudgetWindow } from './renderer-
|
|
11
|
-
export { D as DEFAULT_PIPELINE_CENSUS_LIMIT, i as DEFAULT_TARGET_FPS, j as FRAME_BUDGET_MARKER, k as FRAME_BUDGET_PHASES, l as FRAME_HITCH_MARKER, m as FrameBudget, n as FrameBudgetPhase, o as FrameCounters, p as ICounterDevice, g as IFrameBudgetOptions, q as IFrameBudgetPassSummary, b as IFrameBudgetSimulation, r as IFrameBudgetSummary, s as IFrameCounters, d as IFramePhaseSample,
|
|
12
|
-
import { I as IComputeDriven$1,
|
|
13
|
-
export { C as ComputeDrivenRegistry, D as DISCRETE_LOD_DEFAULT_ERROR_PIXELS, e as DISCRETE_LOD_DEFAULT_HYSTERESIS, G as GPUReadback, f as IGPUReadbackOptions, g as baseGeometryOf, l as lodPixelScale, u as updateModelLods } from './model-lod-
|
|
11
|
+
import { I as IRendererLike, h as IStageGpuReading, F as FramePassKind, a as IFrameBudgetWindow } from './renderer-BtOSseYf.js';
|
|
12
|
+
export { D as DEFAULT_PIPELINE_CENSUS_LIMIT, i as DEFAULT_TARGET_FPS, j as FRAME_BUDGET_MARKER, k as FRAME_BUDGET_PHASES, l as FRAME_HITCH_MARKER, m as FrameBudget, n as FrameBudgetPhase, o as FrameCounters, p as ICounterDevice, g as IFrameBudgetOptions, q as IFrameBudgetPassSummary, b as IFrameBudgetSimulation, r as IFrameBudgetSummary, s as IFrameCounters, d as IFramePhaseSample, f as IPipelineCensus, t as IPipelineCensusCounts, u as IPipelineCensusEvent, v as IPipelineCensusOptions, w as IPipelineProvenance, x as IPipelineShaderObservation, y as IPlatformInfo, z as IRenderChainApplied, A as IRenderChainBudgetWindow, B as IRenderChainDroppedStage, C as IRenderChainOptions, E as IRenderChainRenderer, G as IRenderChainRequest, H as IRenderChainStage, J as IRenderChainStageContext, K as IRenderChainVelocityMeasurement, L as IRenderChainVelocityReport, M as IRenderChainVelocityRequest, N as IRenderChainVelocityResult, c as IRenderPassSample, O as ITargetFps, P as IVelocityRenderPass, Q as MAX_TARGET_FPS, R as MainDrawSource, S as PIPELINE_CENSUS_CAPABILITY, T as PIPELINE_CENSUS_VERSION, U as PipelineCensus, V as PipelineCensusMode, W as PipelineCensusStatus, X as PlatformFormFactor, Y as PlatformOS, Z as PlatformRuntime, _ as RENDER_CHAIN_MARKER, $ as RENDER_CHAIN_STAGE_ORDER, a0 as RENDER_CHAIN_TIERS, a1 as RenderChain, a2 as RenderChainSource, a3 as RenderChainStageId, a4 as RenderChainStageName, a5 as RenderChainTier, a6 as RenderChainTierRequest, a7 as RenderChainVelocitySource, a8 as TargetFpsSource, a9 as VELOCITY_OUTPUT_NAME, aa as VELOCITY_PREVIOUS_BONE_MATRICES, ab as VELOCITY_PREVIOUS_INSTANCE_MATRICES, ac as VELOCITY_PREVIOUS_WORLD_MATRIX, ad as VelocityTracker, ae as counterDeviceOf, af as createPipelineCensus, ag as ensureVelocityOutput, ah as getPlatform, ai as isConsole, aj as isMobile, ak as isNative, al as isPs4, am as isTouchscreenAvailable, an as isWeb, ao as prewarm, ap as readRenderChainObservation, aq as readRenderChainReport, ar as readVelocityPreviousBoneMatrices, as as readVelocityPreviousMatrices, at as readVelocityPreviousWorldMatrix, au as resolveTargetFps, av as snapRefreshRate, aw as stageGpuReading, ax as velocityTexture, ay as withVelocityContext } from './renderer-BtOSseYf.js';
|
|
13
|
+
import { I as IComputeDriven$1, a as IGPUReadbackSample, d as IBudgetCandidate } from './model-lod-DPTzeCcD.js';
|
|
14
|
+
export { C as ComputeDrivenRegistry, D as DISCRETE_LOD_DEFAULT_ERROR_PIXELS, e as DISCRETE_LOD_DEFAULT_HYSTERESIS, G as GPUReadback, f as IGPUReadbackOptions, g as baseGeometryOf, i as isStreamedGeometry, l as lodChainOf, h as lodPixelScale, u as updateModelLods } from './model-lod-DPTzeCcD.js';
|
|
15
|
+
import { G as GIVisualizeMode } from './quality-BYqKGAwo.js';
|
|
16
|
+
export { A as AutoExposureNode, C as ChainStage, E as EPIC_SSGI, F as FinalGatherMethod, a as GIVisualize, b as GI_VISUALIZE_MODES, I as IExposureSettings, c as IGIVisualizeOptions, d as IGiTier, e as IReflectionRoute, f as IShadowFilter, g as IShadowTier, h as ITracedHit, i as ITracedRay, j as ITracedReflectionsOptions, k as IWorldEnvironmentOptions, l as IWorldEnvironmentStageContext, m as IWorldEnvironmentTarget, O as OutputRenderer, Q as QualityTier, S as ScreenSpaceAA, n as SsgiQuality, T as TonemapMode, o as TracedReflections, W as WorldEnvironment, p as exposureSettings, q as installFilmicToneMapping, r as qualityPreset, s as qualityTiers } from './quality-BYqKGAwo.js';
|
|
14
17
|
import { SkyMesh } from 'three/addons/objects/SkyMesh.js';
|
|
15
|
-
|
|
18
|
+
export { R as RendererToneMapping } from './default-tone-mapping-GgKPTiBP.js';
|
|
16
19
|
import { Node as Node$1, UniformNode as UniformNode$1 } from 'three/src/nodes/Nodes.js';
|
|
17
20
|
import 'zustand/vanilla';
|
|
21
|
+
import 'three/tsl';
|
|
18
22
|
|
|
19
|
-
/**
|
|
20
|
-
* Nested cost spans across the render phase, default-off.
|
|
21
|
-
*
|
|
22
|
-
* The frame budget names six phases and one of them — `render` — is 16.1 ms of a 20.2 ms frame
|
|
23
|
-
* while every engine-owned thing inside it sums to under 1.5 ms. A phase that big with nothing
|
|
24
|
-
* inside it is not a measurement, it is a question, and four ranked optimisation options were
|
|
25
|
-
* priced against four different answers to it. This is the instrument that answers it: a span tree
|
|
26
|
-
* whose leaves are the parts of the render phase, with the leftover computed rather than assumed.
|
|
27
|
-
*
|
|
28
|
-
* Three properties make it trustworthy enough to price work against:
|
|
29
|
-
*
|
|
30
|
-
* - **The residual is arithmetic, not a category.** Every non-leaf reports its own duration minus
|
|
31
|
-
* the durations of the spans it contains, so an unmeasured part shows up as a number instead of
|
|
32
|
-
* being quietly filed under "other". A child that outlives its parent reports a negative
|
|
33
|
-
* residual rather than being clamped to zero, because a negative residual means the nesting is
|
|
34
|
-
* wrong and a clamped one means nothing at all.
|
|
35
|
-
* - **It is default-off and costs one guarded return when off.** `TN_FRAME_SPANS=1` installs it;
|
|
36
|
-
* unset, every call site is `if (recorder === undefined) return;` with no clock read.
|
|
37
|
-
* - **Nothing here decides anything.** It measures the path that exists. It does not select a
|
|
38
|
-
* renderer, a traversal strategy or a pass order, and no number it produces is evidence for
|
|
39
|
-
* owning the renderer.
|
|
40
|
-
*
|
|
41
|
-
* The ids are integers on the hot path — a span call must not allocate a string to be cheap enough
|
|
42
|
-
* to put around a per-draw call — and the names exist only in the report.
|
|
43
|
-
*/
|
|
44
23
|
declare const SPANS_MARKER = "TN_FRAME_SPANS";
|
|
45
24
|
/**
|
|
46
25
|
* The launch flag that installs the spans. Off by default: this is a diagnostic that adds work to
|
|
@@ -200,6 +179,104 @@ declare function spansRequested(): boolean;
|
|
|
200
179
|
/** The window as the marker line prints it. */
|
|
201
180
|
declare function formatSpansWindow(window: ISpanWindow): string;
|
|
202
181
|
|
|
182
|
+
/**
|
|
183
|
+
* The per-frame world-matrix walk, with a hidden subtree left where it stands.
|
|
184
|
+
*
|
|
185
|
+
* `three`'s `Object3D.updateMatrixWorld` recurses into every child of every node whatever its
|
|
186
|
+
* `visible` flag, multiplying a world matrix for each. That is the correct default for a library
|
|
187
|
+
* that cannot know what a game is doing, and it is the wrong one for a renderer that is about to
|
|
188
|
+
* skip exactly those subtrees: a full-detail body while its merged stand-in draws, a hidden LOD
|
|
189
|
+
* level, a parked or hangared model each pay the walk and none of them can draw.
|
|
190
|
+
*
|
|
191
|
+
* Native flight in `sandbox/midway-open-pacific` profiled `updateMatrixWorld` plus
|
|
192
|
+
* `multiplyMatrices` at **29 % of all JavaScript ticks**, and the same scene's hand-rolled
|
|
193
|
+
* visible-only pass walked **779 nodes per frame instead of 9,903**, 3.1 ms down to 0.3 ms. That
|
|
194
|
+
* pass was the game's; this is the engine's, so the next game does not write it again.
|
|
195
|
+
*
|
|
196
|
+
* The pass mirrors three exactly for a visible node: `matrixAutoUpdate` -> `updateMatrix()`, then
|
|
197
|
+
* the `matrixWorldNeedsUpdate || force` recompute honouring `matrixWorldAutoUpdate` and a null
|
|
198
|
+
* parent, then force the children. A node with `visible === false` defers its own compose and its
|
|
199
|
+
* subtree's walk. Every skipped root is remembered, so the first frame it is visible again both
|
|
200
|
+
* its own world matrix and its descendants are recomputed with `force = true`.
|
|
201
|
+
*
|
|
202
|
+
* Two things are never dropped by the pruning, because both are read while nothing above them is
|
|
203
|
+
* visible:
|
|
204
|
+
*
|
|
205
|
+
* - a class that overrides `updateMatrixWorld` runs its own — never a `Scene`, which three does not
|
|
206
|
+
* override and whose method only differs when something patched the prototype. `SkinnedMesh`
|
|
207
|
+
* refreshes `bindMatrixInverse`, `Camera` its `matrixWorldInverse`; re-implementing only the base
|
|
208
|
+
* walk left every deck-crew sailor that had moved since load drawing with a stale bind matrix and
|
|
209
|
+
* vanishing from the frame. Their subtrees are small, so walking them whole costs nothing;
|
|
210
|
+
* - a hidden node that holds a `Bone` is walked, because a visible `SkinnedMesh` draws with its
|
|
211
|
+
* skeleton's matrices wherever the armature happens to sit. Whether bones sit below a node is
|
|
212
|
+
* decided once and remembered — a rig is built whole and does not grow.
|
|
213
|
+
*
|
|
214
|
+
* A third thing is dropped, and it is the walk's largest single share on a streamed world: a subtree
|
|
215
|
+
* frozen with `markStatic`. `markStatic` composes the subtree once and turns off the two flags that
|
|
216
|
+
* would recompose it, which until now still left three's unconditional recursion visiting every node
|
|
217
|
+
* under it every frame. A frozen root that carries no dirty flag is a leaf here, and it is one
|
|
218
|
+
* whether the walk was forced or not: `refreshStaticTransforms` re-arms a root whose own transform
|
|
219
|
+
* moved, `invalidateStatic` re-arms one something wrote inside, and both compose the subtree once at
|
|
220
|
+
* that moment. `isStatic` is what separates the engine's freeze from a game that turned the flags off
|
|
221
|
+
* for its own reasons. See `static-transform.ts`.
|
|
222
|
+
*
|
|
223
|
+
* Where the root is a native-engine object it has its own walk, `__tnUpdateMatrixWorld(force, prune)`: this
|
|
224
|
+
* pass run natively in one call, answering the nodes it visited. The pass calls that and nothing else, since the
|
|
225
|
+
* walk above costs a bridge call per node read and written (about 16 to 25 thousand a frame at 4,096 cubes).
|
|
226
|
+
* With `prune` (the `"visible"` mode) the native walk leaves a hidden subtree where it stands by the same rules,
|
|
227
|
+
* bones included; `"all"` visits every node. A JS subclass of `Object3D` that overrides `updateMatrixWorld` is not
|
|
228
|
+
* called from inside it; the engine's own `SkinnedMesh` and `Camera` keep their derived matrices. The web and the
|
|
229
|
+
* legacy host have no such method and walk as above.
|
|
230
|
+
*
|
|
231
|
+
* A game that reads a **hidden** object's `matrixWorld` directly must not rely on this pass
|
|
232
|
+
* having reached it: use `getWorldPosition`/`getWorldQuaternion`/`getWorldScale` (which update the
|
|
233
|
+
* chain they need) or call `object.updateWorldMatrix(true, false)` first. The convention's named
|
|
234
|
+
* override is `renderer.matrixWorld: "all"`, which visits every node exactly as three's own walk
|
|
235
|
+
* does; `"visible"` is the default.
|
|
236
|
+
*/
|
|
237
|
+
/** How much of the scene graph the engine walks for world matrices each frame. */
|
|
238
|
+
type MatrixWorldMode = "visible" | "all";
|
|
239
|
+
/** What the pass did on the last frame, for the frame telemetry a window reports. */
|
|
240
|
+
interface IMatrixWorldReport {
|
|
241
|
+
readonly schemaVersion: 1;
|
|
242
|
+
readonly mode: MatrixWorldMode;
|
|
243
|
+
/**
|
|
244
|
+
* Nodes the engine walked this frame, summed over every application (authored scene and a
|
|
245
|
+
* projection mirror when one is in use). One number both ways, so `"all"` can be read as the
|
|
246
|
+
* cost of the walk the convention just removed.
|
|
247
|
+
*/
|
|
248
|
+
readonly visited: number;
|
|
249
|
+
}
|
|
250
|
+
interface IMatrixWorldOptions {
|
|
251
|
+
/** `"visible"` (default) skips a hidden subtree; `"all"` reproduces three's own walk. */
|
|
252
|
+
readonly mode?: MatrixWorldMode;
|
|
253
|
+
}
|
|
254
|
+
/**
|
|
255
|
+
* One game's world-matrix walk, holding the state the pruning needs between frames.
|
|
256
|
+
*
|
|
257
|
+
* The stale set and the bone cache live on the instance rather than in module scope: two games,
|
|
258
|
+
* two playtest scenarios or two roots in one process must not share "this subtree was skipped
|
|
259
|
+
* while hidden", or one game's hidden node would be force-refreshed by the other's frame.
|
|
260
|
+
*/
|
|
261
|
+
declare class MatrixWorldPass {
|
|
262
|
+
#private;
|
|
263
|
+
constructor(options?: IMatrixWorldOptions);
|
|
264
|
+
get mode(): MatrixWorldMode;
|
|
265
|
+
/** What the current frame has walked so far, across every {@link apply} call. */
|
|
266
|
+
get report(): IMatrixWorldReport;
|
|
267
|
+
/** Starts a frame's count. The pass's state (stale set, bone cache) is untouched. */
|
|
268
|
+
beginFrame(): void;
|
|
269
|
+
/**
|
|
270
|
+
* Walks `root`, mirroring three for every node the mode visits.
|
|
271
|
+
*
|
|
272
|
+
* Returns the nodes this call visited, so a caller can report one application's cost without
|
|
273
|
+
* also reporting the frame's total.
|
|
274
|
+
*/
|
|
275
|
+
apply(root: Object3D, force?: boolean): number;
|
|
276
|
+
/** Forgets what was skipped. A whole-scene swap has no hidden ancestors left to refresh. */
|
|
277
|
+
dispose(): void;
|
|
278
|
+
}
|
|
279
|
+
|
|
203
280
|
/** A stride measured at unit world scale, so uniformly scaled clones can share it. */
|
|
204
281
|
interface ISharedStride {
|
|
205
282
|
/** Metres of ground per clip-second at rate 1, per unit of uniform world scale. */
|
|
@@ -580,57 +657,12 @@ declare class Billboard3D {
|
|
|
580
657
|
update(camera?: Camera): this;
|
|
581
658
|
}
|
|
582
659
|
|
|
583
|
-
type CameraShakeCurve = (phase: number) => number;
|
|
584
|
-
interface ICameraShakeOptions {
|
|
585
|
-
/** Position amplitude in world metres, supplied by the game. */
|
|
586
|
-
readonly amplitude: Vector3;
|
|
587
|
-
/** Rotation amplitude in radians around x/y/z, supplied by the game. */
|
|
588
|
-
readonly rotationAmplitude: Vector3;
|
|
589
|
-
/** Curve cycles per second, supplied by the game. */
|
|
590
|
-
readonly frequency: number;
|
|
591
|
-
/** Exponential envelope decay per second, supplied by the game. */
|
|
592
|
-
readonly decay: number;
|
|
593
|
-
/** Game-authored waveform sampled at `elapsed * frequency * 2π`. */
|
|
594
|
-
readonly curve: CameraShakeCurve;
|
|
595
|
-
}
|
|
596
|
-
interface ICameraShakeOffset {
|
|
597
|
-
readonly position: Vector3;
|
|
598
|
-
readonly rotation: Vector3;
|
|
599
|
-
}
|
|
600
|
-
/**
|
|
601
|
-
* Produce a transient camera offset without owning or mutating a camera.
|
|
602
|
-
*
|
|
603
|
-
* The caller supplies the amplitudes, frequency, decay and waveform. {@link update} evaluates the
|
|
604
|
-
* waveform against the caller's fixed-step delta and returns a reusable position/rotation offset;
|
|
605
|
-
* a template can compose it after its own camera rig and damping.
|
|
606
|
-
*/
|
|
607
|
-
declare class CameraShake {
|
|
608
|
-
#private;
|
|
609
|
-
readonly amplitude: Vector3;
|
|
610
|
-
readonly rotationAmplitude: Vector3;
|
|
611
|
-
readonly frequency: number;
|
|
612
|
-
readonly decay: number;
|
|
613
|
-
readonly curve: CameraShakeCurve;
|
|
614
|
-
readonly offset: ICameraShakeOffset;
|
|
615
|
-
constructor(options: ICameraShakeOptions);
|
|
616
|
-
get active(): boolean;
|
|
617
|
-
get elapsed(): number;
|
|
618
|
-
/** Start or restart the authored shake waveform. */
|
|
619
|
-
trigger(): this;
|
|
620
|
-
/** Stop the effect and clear the offset. */
|
|
621
|
-
stop(): this;
|
|
622
|
-
/** Evaluate the current offset and advance by one caller-supplied fixed-step delta. */
|
|
623
|
-
update(dt: number): ICameraShakeOffset;
|
|
624
|
-
}
|
|
625
|
-
|
|
626
660
|
/**
|
|
627
661
|
* Why a launch stopped, said where the player can read it.
|
|
628
662
|
*
|
|
629
|
-
* A launch
|
|
630
|
-
*
|
|
631
|
-
*
|
|
632
|
-
* loading layer keeps painting, and the only account of what happened is a line on stdout — which
|
|
633
|
-
* a player does not have, and which a bug report therefore never carries.
|
|
663
|
+
* A launch can fail when a scene load rejects, progress stops moving, or the GPU device is
|
|
664
|
+
* lost. Without a report, the player sees a loading layer while the actionable error stays
|
|
665
|
+
* on stdout or in a discarded scene-transition promise.
|
|
634
666
|
*
|
|
635
667
|
* So the failure is reported as text, once, through `onLaunchFailure` — and core stops there. Core
|
|
636
668
|
* cannot draw it: on the native host `document` is a Three.js compatibility stub whose
|
|
@@ -638,12 +670,8 @@ declare class CameraShake {
|
|
|
638
670
|
* that needs it. The page owns the presentation (and the copy-to-clipboard button players are
|
|
639
671
|
* asked for when they report a launch that hung); this owns the noticing and the wording.
|
|
640
672
|
*/
|
|
641
|
-
/**
|
|
642
|
-
|
|
643
|
-
* `scene-load-failed` is a scene's `load()` rejecting and `start-failed` is `start()` rejecting,
|
|
644
|
-
* each of which otherwise reads as a stall.
|
|
645
|
-
*/
|
|
646
|
-
type LaunchFailureKind = "stalled" | "device-lost" | "scene-load-failed" | "start-failed";
|
|
673
|
+
/** What failed: startup progress, a rejected scene load/start, or a lost GPU device. */
|
|
674
|
+
type LaunchFailureKind = "stalled" | "device-lost" | "load-failed" | "scene-load-failed" | "start-failed";
|
|
647
675
|
interface ILaunchFailure {
|
|
648
676
|
readonly kind: LaunchFailureKind;
|
|
649
677
|
/** One human sentence, already naming the numbers — this is what the Copy button copies. */
|
|
@@ -950,6 +978,40 @@ declare class SoftBody3D extends Mesh<BufferGeometry, NodeMaterial> implements I
|
|
|
950
978
|
detach(): void;
|
|
951
979
|
}
|
|
952
980
|
|
|
981
|
+
/** The CPU snapshot a GPUSceneBVH packs, in BVH leaf order, that the probe trace reads. */
|
|
982
|
+
interface IProbeTraceScene {
|
|
983
|
+
/** three-mesh-bvh serialized root: 8 words per node. */
|
|
984
|
+
readonly nodes: Uint32Array;
|
|
985
|
+
/** World positions, 4 floats per vertex. */
|
|
986
|
+
readonly positions: Float32Array;
|
|
987
|
+
/** Leaf-ordered triangle corners, 3 per triangle. */
|
|
988
|
+
readonly indices: Uint32Array;
|
|
989
|
+
/** Leaf-ordered material slot per triangle, an index into `materials`. */
|
|
990
|
+
readonly triangleMaterials: Uint32Array;
|
|
991
|
+
readonly materials: readonly Material[];
|
|
992
|
+
}
|
|
993
|
+
/** The sun and sky the game already holds for its daylight; the volume owns no light. */
|
|
994
|
+
interface IProbeTraceLighting {
|
|
995
|
+
/** World direction toward the sun (the light's position minus its target). */
|
|
996
|
+
readonly direction: Vector3;
|
|
997
|
+
readonly color: Color;
|
|
998
|
+
readonly intensity: number;
|
|
999
|
+
/** Radiance of a ray that leaves the scene. Black for an interior with no sky. */
|
|
1000
|
+
readonly sky: Color;
|
|
1001
|
+
/**
|
|
1002
|
+
* Point lights, at most the count the kernels were built for. Intensity is the irradiance on a surface 1 m
|
|
1003
|
+
* from the light that faces it, in the same units as the sun; `distance` closes the attenuation window
|
|
1004
|
+
* (three's `getDistanceAttenuation`), 0 for none. A change to a point light needs `requestBake`.
|
|
1005
|
+
*/
|
|
1006
|
+
readonly points?: readonly IProbeTracePoint[];
|
|
1007
|
+
}
|
|
1008
|
+
interface IProbeTracePoint {
|
|
1009
|
+
readonly position: Vector3;
|
|
1010
|
+
readonly color: Color;
|
|
1011
|
+
readonly intensity: number;
|
|
1012
|
+
readonly distance?: number;
|
|
1013
|
+
}
|
|
1014
|
+
|
|
953
1015
|
/** Selects the meshes that become part of a GPU trace set. */
|
|
954
1016
|
interface IGPUSceneBVHOptions {
|
|
955
1017
|
readonly include?: (object: Mesh) => boolean;
|
|
@@ -979,12 +1041,20 @@ declare const rayStruct: StructTypeNode;
|
|
|
979
1041
|
*/
|
|
980
1042
|
declare class GPUSceneBVH extends Group implements IComputeDriven$1 {
|
|
981
1043
|
#private;
|
|
982
|
-
readonly indices: StorageBufferNode<"uvec3">;
|
|
983
|
-
readonly nodes: StorageBufferNode<"struct">;
|
|
984
|
-
readonly normals: StorageBufferNode<"vec3">;
|
|
985
|
-
readonly positions: StorageBufferNode<"vec3">;
|
|
986
1044
|
readonly warmupNodes: readonly unknown[];
|
|
987
1045
|
constructor(scene: Object3D, options?: IGPUSceneBVHOptions);
|
|
1046
|
+
/** Packed triangle indices as a storage node, built on first read. */
|
|
1047
|
+
get indices(): StorageBufferNode<"uvec3">;
|
|
1048
|
+
/** Packed vertex normals as a storage node, built on first read. */
|
|
1049
|
+
get normals(): StorageBufferNode<"vec3">;
|
|
1050
|
+
/** Packed world-space vertex positions as a storage node, built on first read. */
|
|
1051
|
+
get positions(): StorageBufferNode<"vec3">;
|
|
1052
|
+
/** The upstream TSL query's node table, built on first read. */
|
|
1053
|
+
get nodes(): StorageBufferNode<"struct">;
|
|
1054
|
+
/** The CPU snapshot in leaf order, with one material slot per triangle: what `RadianceCache` traces. */
|
|
1055
|
+
get traceScene(): IProbeTraceScene;
|
|
1056
|
+
/** Increments on every rebuild, so a consumer of `traceScene` knows to re-upload. */
|
|
1057
|
+
get version(): number;
|
|
988
1058
|
get buildMs(): number;
|
|
989
1059
|
get materialGroups(): readonly IGPUSceneBVHMaterialGroup[];
|
|
990
1060
|
get objectCount(): number;
|
|
@@ -999,140 +1069,6 @@ declare class GPUSceneBVH extends Group implements IComputeDriven$1 {
|
|
|
999
1069
|
detach(): void;
|
|
1000
1070
|
}
|
|
1001
1071
|
|
|
1002
|
-
interface ITraceSceneReport {
|
|
1003
|
-
readonly triangles: number;
|
|
1004
|
-
readonly nodes: number;
|
|
1005
|
-
readonly materials: number;
|
|
1006
|
-
/** Meshes left out because their triangles move (instanced, skinned, batched, morphing). */
|
|
1007
|
-
readonly skippedMoving: number;
|
|
1008
|
-
readonly milliseconds: number;
|
|
1009
|
-
}
|
|
1010
|
-
interface ITraceScene {
|
|
1011
|
-
readonly report: ITraceSceneReport;
|
|
1012
|
-
readonly bounds: Box3;
|
|
1013
|
-
/** The material of every id, for what the table cannot hold (a map, a node). */
|
|
1014
|
-
readonly materials: readonly Material[];
|
|
1015
|
-
readonly nodes: DataTexture;
|
|
1016
|
-
readonly triangles: DataTexture;
|
|
1017
|
-
readonly materialTable: DataTexture;
|
|
1018
|
-
readonly nodeData: Float32Array;
|
|
1019
|
-
readonly triangleData: Float32Array;
|
|
1020
|
-
readonly materialData: Float32Array;
|
|
1021
|
-
dispose(): void;
|
|
1022
|
-
}
|
|
1023
|
-
|
|
1024
|
-
interface ITracedReflectionsOptions {
|
|
1025
|
-
/** Which meshes a ray can hit. Default: every mesh under a visible parent chain. */
|
|
1026
|
-
readonly include?: (mesh: Mesh) => boolean;
|
|
1027
|
-
/** Surfaces rougher than this take no traced reflection. Unreal's `LumenMaxRoughnessToTrace`: 0.4. */
|
|
1028
|
-
readonly maxRoughnessToTrace?: number;
|
|
1029
|
-
/** The weight falls from 1 to 0 over this much roughness, ending at `maxRoughnessToTrace`: 0.1. */
|
|
1030
|
-
readonly roughnessFadeLength?: number;
|
|
1031
|
-
/**
|
|
1032
|
-
* Surfaces rougher than this take the diffuse GI for specular, not the radiance cache. Unreal's
|
|
1033
|
-
* `MaxRoughnessToEvaluateRoughSpecular`: 0.8.
|
|
1034
|
-
*/
|
|
1035
|
-
readonly maxRoughnessToEvaluateRoughSpecular?: number;
|
|
1036
|
-
/** The share of diffuse GI rises from 0 to 1 over this much roughness, ending at the limit above: 0.2. */
|
|
1037
|
-
readonly roughSpecularFadeLength?: number;
|
|
1038
|
-
/**
|
|
1039
|
-
* Most nodes one ray visits before it stops walking with the nearest surface found so far, which may be the
|
|
1040
|
-
* wrong one. A walk visits each node at most once, so the default, the tree's node count up to 2048, never
|
|
1041
|
-
* cuts a ray short in a scene of up to 2048 nodes.
|
|
1042
|
-
*/
|
|
1043
|
-
readonly maxSteps?: number;
|
|
1044
|
-
/** False silences the TN_TRACED_REFLECTIONS line, not the report. */
|
|
1045
|
-
readonly marker?: boolean;
|
|
1046
|
-
}
|
|
1047
|
-
/**
|
|
1048
|
-
* Where a surface's specular comes from, as shares that add to 1: the traced ray, the radiance cache read along the
|
|
1049
|
-
* reflected direction (a rough lobe), or the diffuse GI (a surface too rough for a lobe).
|
|
1050
|
-
*/
|
|
1051
|
-
interface IReflectionRoute<T> {
|
|
1052
|
-
readonly traced: T;
|
|
1053
|
-
readonly roughSpecular: T;
|
|
1054
|
-
readonly diffuse: T;
|
|
1055
|
-
}
|
|
1056
|
-
/** One ray's answer, as nodes. Every field is meaningful only where `hit` is 1. */
|
|
1057
|
-
interface ITracedHit {
|
|
1058
|
-
/** 1 where the ray found a surface, else 0. */
|
|
1059
|
-
readonly hit: Node<"float">;
|
|
1060
|
-
/** Metres along the (unit) ray, or -1 on a miss. */
|
|
1061
|
-
readonly distance: Node<"float">;
|
|
1062
|
-
readonly position: Node<"vec3">;
|
|
1063
|
-
/** The interpolated vertex normal, flipped to face the ray. */
|
|
1064
|
-
readonly normal: Node<"vec3">;
|
|
1065
|
-
/** The hit triangle's index in the pack's leaf order. */
|
|
1066
|
-
readonly triangle: Node<"float">;
|
|
1067
|
-
/** The hit material's colour, roughness, emissive (times intensity) and metalness, from the pack's table. */
|
|
1068
|
-
readonly albedo: Node<"vec3">;
|
|
1069
|
-
readonly roughness: Node<"float">;
|
|
1070
|
-
readonly emissive: Node<"vec3">;
|
|
1071
|
-
readonly metalness: Node<"float">;
|
|
1072
|
-
/** The index into `TracedReflections.scene.materials`: a game that needs a map or a node looks the material up. */
|
|
1073
|
-
readonly material: Node<"float">;
|
|
1074
|
-
}
|
|
1075
|
-
interface ITracedRay {
|
|
1076
|
-
readonly origin: Node<"vec3">;
|
|
1077
|
-
/** Unit length. */
|
|
1078
|
-
readonly direction: Node<"vec3">;
|
|
1079
|
-
/** Closest hit allowed, in metres. Default 0.001. */
|
|
1080
|
-
readonly near?: Node<"float"> | number;
|
|
1081
|
-
/** Farthest hit allowed, in metres. Default 1e4. */
|
|
1082
|
-
readonly far?: Node<"float"> | number;
|
|
1083
|
-
/**
|
|
1084
|
-
* Stop at the first surface found, which need not be the nearest: the answer for a shadow ray, which only asks
|
|
1085
|
-
* whether anything is in the way. `distance`, `position` and the material then describe that surface.
|
|
1086
|
-
*/
|
|
1087
|
-
readonly anyHit?: boolean;
|
|
1088
|
-
}
|
|
1089
|
-
/**
|
|
1090
|
-
* Ray queries against the scene's triangles for reflections, in the engine's own TSL: the pack is float
|
|
1091
|
-
* textures and the walk is a loop, so the kernel needs no storage buffer and no WGSL of its own.
|
|
1092
|
-
*
|
|
1093
|
-
* Unreal's Lumen reflections trace what the screen cannot see through a software scene (mesh SDFs, or hardware
|
|
1094
|
-
* rays) for surfaces smoother than a roughness cut-off, and fall back to a cached radiance below it. This is
|
|
1095
|
-
* the scene half of that: `trace()` answers "what does this ray hit" and the material at the hit. How the hit
|
|
1096
|
-
* is lit, what a miss sees and how the result joins the frame stay in the game's `src/render/` code.
|
|
1097
|
-
*/
|
|
1098
|
-
declare class TracedReflections {
|
|
1099
|
-
#private;
|
|
1100
|
-
/** The packed triangles; `scene.materials[hit.material]` is the three material of a hit. */
|
|
1101
|
-
readonly scene: ITraceScene;
|
|
1102
|
-
readonly maxRoughnessToTrace: number;
|
|
1103
|
-
readonly roughnessFadeLength: number;
|
|
1104
|
-
readonly maxRoughnessToEvaluateRoughSpecular: number;
|
|
1105
|
-
readonly roughSpecularFadeLength: number;
|
|
1106
|
-
readonly maxSteps: number;
|
|
1107
|
-
constructor(root: Object3D, options?: ITracedReflectionsOptions);
|
|
1108
|
-
get report(): ITraceSceneReport & {
|
|
1109
|
-
readonly bytes: number;
|
|
1110
|
-
};
|
|
1111
|
-
/**
|
|
1112
|
-
* 1 for a surface at least as smooth as the cut-off minus the fade, falling to 0 at `maxRoughnessToTrace`.
|
|
1113
|
-
* Multiply a traced reflection by it so a rough surface never shows a trace's noise.
|
|
1114
|
-
*/
|
|
1115
|
-
weight(roughness: Node<"float">): Node<"float">;
|
|
1116
|
-
/** `weight` for one roughness on the CPU: a surface rougher than `maxRoughnessToTrace` casts no ray. */
|
|
1117
|
-
weightAt(roughness: number): number;
|
|
1118
|
-
/**
|
|
1119
|
-
* Where a surface's specular comes from (Unreal: `LumenCombineReflectionsAlpha` picks the ray, and
|
|
1120
|
-
* `RoughReflectionsDiffuseLerp` in `LumenReflectionsCombine.ush` fades the rest from the gather's rough specular to
|
|
1121
|
-
* the diffuse GI). The ray's share is `weight`; of the rest, the diffuse share rises from 0 at the limit minus the
|
|
1122
|
-
* fade to 1 at the limit, and the radiance cache answers for what is left.
|
|
1123
|
-
*/
|
|
1124
|
-
route(roughness: Node<"float">): IReflectionRoute<Node<"float">>;
|
|
1125
|
-
/** `route` for one roughness on the CPU. */
|
|
1126
|
-
routeAt(roughness: number): IReflectionRoute<number>;
|
|
1127
|
-
/**
|
|
1128
|
-
* The nearest surface along a ray, with its normal and material. The walk is the depth-first, skip-pointer one
|
|
1129
|
-
* `traceScene` runs on the CPU: a node's box is tested, a miss jumps to the node after the subtree, a hit on an
|
|
1130
|
-
* inner node steps to its left child, a leaf tests its triangles in a loop.
|
|
1131
|
-
*/
|
|
1132
|
-
trace(ray: ITracedRay): ITracedHit;
|
|
1133
|
-
dispose(): void;
|
|
1134
|
-
}
|
|
1135
|
-
|
|
1136
1072
|
interface IInstancedLodOptions {
|
|
1137
1073
|
/** Baked-chain selection is automatic. `false` leaves detail to the caller. */
|
|
1138
1074
|
readonly autoLod?: false | {
|
|
@@ -1352,18 +1288,10 @@ declare function mergeParts(parts: Iterable<IMergePart>, options: IMergePartsOpt
|
|
|
1352
1288
|
*/
|
|
1353
1289
|
declare function mergeByMaterial(root: Object3D, options: IMergeByMaterialOptions): Mesh[];
|
|
1354
1290
|
|
|
1355
|
-
/**
|
|
1356
|
-
* A debug switch a game reads the same way on every platform it ships to.
|
|
1357
|
-
*
|
|
1358
|
-
* Two questions an agent answers differently in every game, both of which cost a rewrite: how do I
|
|
1359
|
-
* turn this on for one run without changing the code, and how does a capture script reach the object
|
|
1360
|
-
* it wants to look at. The answers here are one function each, and neither decides how anything
|
|
1361
|
-
* looks.
|
|
1362
|
-
*/
|
|
1363
1291
|
/**
|
|
1364
1292
|
* A debug switch read from the URL, or from the environment on a native launch.
|
|
1365
1293
|
*
|
|
1366
|
-
* @situation read a debug toggle from the URL
|
|
1294
|
+
* @situation read a debug toggle from the URL, an environment variable or a harness global
|
|
1367
1295
|
*
|
|
1368
1296
|
* A browser asks with the query string — `?freeCam`, or `?freeCam=0` to force it off — and a native
|
|
1369
1297
|
* launch asks with `TN_DEBUG_FREE_CAM`, because a query string is not something a developer sets on
|
|
@@ -1383,6 +1311,40 @@ declare function debugFlag(name: string): boolean;
|
|
|
1383
1311
|
*/
|
|
1384
1312
|
declare function exposeDebug(name: string, value: unknown): void;
|
|
1385
1313
|
|
|
1314
|
+
/**
|
|
1315
|
+
* The one owner of `__THREENATIVE__`, the object every dev surface publishes under.
|
|
1316
|
+
*
|
|
1317
|
+
* Five places used to spell the key itself — the debug flag, hot reload, the game's dev tools, the
|
|
1318
|
+
* UI overlay and the engine's export — so the global's name and its shape were written twice at
|
|
1319
|
+
* least. The worker keeps its own mirror list: that list is a typed tuple its mirror machinery is
|
|
1320
|
+
* built from, and moving it here changed what the worker host forwarded.
|
|
1321
|
+
*
|
|
1322
|
+
* Nothing here decides how anything looks: it is the seam a capture script, the console and the dev
|
|
1323
|
+
* overlay reach the running game through.
|
|
1324
|
+
*/
|
|
1325
|
+
/** The property name a dev surface publishes under, on the window and on a worker's global. */
|
|
1326
|
+
declare const DEV_GLOBAL_KEY = "__THREENATIVE__";
|
|
1327
|
+
/** What the game's own dev tools publish: a snapshot, and an armed geometry capture. */
|
|
1328
|
+
interface IDevTools {
|
|
1329
|
+
snapshot(): EntitySnapshot;
|
|
1330
|
+
/**
|
|
1331
|
+
* Arms one per-object geometry capture for a development overlay. Absent until the game has a
|
|
1332
|
+
* render loop; the overlay treats that as "not ready", never as an empty scene.
|
|
1333
|
+
*/
|
|
1334
|
+
geometry?(request?: IGeometryCaptureRequest): Promise<IGeometryCaptureReport>;
|
|
1335
|
+
}
|
|
1336
|
+
/** What a dev surface may publish under {@link DEV_GLOBAL_KEY}. */
|
|
1337
|
+
type DevGlobal = Partial<IDevTools> & Record<string, unknown>;
|
|
1338
|
+
/**
|
|
1339
|
+
* The global a host installed, or `undefined` outside a dev launch.
|
|
1340
|
+
*
|
|
1341
|
+
* `scope` is required on purpose: a default of `globalThis` would make an explicit `undefined` read
|
|
1342
|
+
* the page's global, which is exactly the worker case a caller is asking about.
|
|
1343
|
+
*/
|
|
1344
|
+
declare function devGlobal(scope: unknown): DevGlobal | undefined;
|
|
1345
|
+
/** Adds one member to the global, keeping whatever another surface already published. */
|
|
1346
|
+
declare function publishDevGlobal(name: string, value: unknown, scope: unknown): void;
|
|
1347
|
+
|
|
1386
1348
|
/**
|
|
1387
1349
|
* A mesh that draws only the clusters this camera can resolve.
|
|
1388
1350
|
*
|
|
@@ -1568,6 +1530,25 @@ declare class ClusteredBatch {
|
|
|
1568
1530
|
update(camera: Camera, viewportHeight: number): number;
|
|
1569
1531
|
}
|
|
1570
1532
|
|
|
1533
|
+
/**
|
|
1534
|
+
* A far level for a card mesh: keep `keep` of its cards and grow each kept card about its own
|
|
1535
|
+
* centre so the mesh holds its total surface area.
|
|
1536
|
+
*
|
|
1537
|
+
* Needle and leaf cards are disconnected quads, so an edge-collapse simplifier cannot reduce them
|
|
1538
|
+
* (the asset cook's chain skips them, and a far tree drew every card of its middle level to the
|
|
1539
|
+
* horizon). Dropping cards alone thins the crown, so the kept ones take the lost area, as Unreal's
|
|
1540
|
+
* Nanite "Preserve Area" foliage does (UE 5.8.3:
|
|
1541
|
+
* Engine/Source/Developer/MeshSimplifier/Private/MeshSimplify.cpp `PreserveSurfaceArea`).
|
|
1542
|
+
*
|
|
1543
|
+
* A card is one island of triangles joined by shared vertex indices. The choice is deterministic: a
|
|
1544
|
+
* fixed-seed shuffle of the islands, taken until the triangle share is met. Positions move; every
|
|
1545
|
+
* other attribute is kept, and a uniform scale about the centre leaves normals and UVs valid.
|
|
1546
|
+
*
|
|
1547
|
+
* Only the drawn range counts: a material section cut from a shared index by `setDrawRange` thins its
|
|
1548
|
+
* own triangles, and the result, whose index holds just the kept ones, draws its whole index.
|
|
1549
|
+
*/
|
|
1550
|
+
declare function thinCards(geometry: BufferGeometry, keep: number): BufferGeometry;
|
|
1551
|
+
|
|
1571
1552
|
/**
|
|
1572
1553
|
* What the gate did on the last frame, in the shape a frame-budget window reports.
|
|
1573
1554
|
*
|
|
@@ -1618,116 +1599,18 @@ interface IRenderCameraCullReport {
|
|
|
1618
1599
|
declare function alwaysRender(object: Object3D, enabled?: boolean): void;
|
|
1619
1600
|
|
|
1620
1601
|
/**
|
|
1621
|
-
* The
|
|
1622
|
-
*
|
|
1623
|
-
* `three`'s `Object3D.updateMatrixWorld` recurses into every child of every node whatever its
|
|
1624
|
-
* `visible` flag, multiplying a world matrix for each. That is the correct default for a library
|
|
1625
|
-
* that cannot know what a game is doing, and it is the wrong one for a renderer that is about to
|
|
1626
|
-
* skip exactly those subtrees: a full-detail body while its merged stand-in draws, a hidden LOD
|
|
1627
|
-
* level, a parked or hangared model each pay the walk and none of them can draw.
|
|
1628
|
-
*
|
|
1629
|
-
* Native flight in `sandbox/midway-open-pacific` profiled `updateMatrixWorld` plus
|
|
1630
|
-
* `multiplyMatrices` at **29 % of all JavaScript ticks**, and the same scene's hand-rolled
|
|
1631
|
-
* visible-only pass walked **779 nodes per frame instead of 9,903**, 3.1 ms down to 0.3 ms. That
|
|
1632
|
-
* pass was the game's; this is the engine's, so the next game does not write it again.
|
|
1633
|
-
*
|
|
1634
|
-
* The pass mirrors three exactly for a visible node: `matrixAutoUpdate` -> `updateMatrix()`, then
|
|
1635
|
-
* the `matrixWorldNeedsUpdate || force` recompute honouring `matrixWorldAutoUpdate` and a null
|
|
1636
|
-
* parent, then force the children. A node with `visible === false` defers its own compose and its
|
|
1637
|
-
* subtree's walk. Every skipped root is remembered, so the first frame it is visible again both
|
|
1638
|
-
* its own world matrix and its descendants are recomputed with `force = true`.
|
|
1639
|
-
*
|
|
1640
|
-
* Two things are never dropped by the pruning, because both are read while nothing above them is
|
|
1641
|
-
* visible:
|
|
1642
|
-
*
|
|
1643
|
-
* - a class that overrides `updateMatrixWorld` runs its own — never a `Scene`, which three does not
|
|
1644
|
-
* override and whose method only differs when something patched the prototype. `SkinnedMesh`
|
|
1645
|
-
* refreshes `bindMatrixInverse`, `Camera` its `matrixWorldInverse`; re-implementing only the base
|
|
1646
|
-
* walk left every deck-crew sailor that had moved since load drawing with a stale bind matrix and
|
|
1647
|
-
* vanishing from the frame. Their subtrees are small, so walking them whole costs nothing;
|
|
1648
|
-
* - a hidden node that holds a `Bone` is walked, because a visible `SkinnedMesh` draws with its
|
|
1649
|
-
* skeleton's matrices wherever the armature happens to sit. Whether bones sit below a node is
|
|
1650
|
-
* decided once and remembered — a rig is built whole and does not grow.
|
|
1651
|
-
*
|
|
1652
|
-
* A third thing is dropped, and it is the walk's largest single share on a streamed world: a subtree
|
|
1653
|
-
* frozen with `markStatic`. `markStatic` composes the subtree once and turns off the two flags that
|
|
1654
|
-
* would recompose it, which until now still left three's unconditional recursion visiting every node
|
|
1655
|
-
* under it every frame. A frozen root that carries no dirty flag is a leaf here, and it is one
|
|
1656
|
-
* whether the walk was forced or not: `refreshStaticTransforms` re-arms a root whose own transform
|
|
1657
|
-
* moved, `invalidateStatic` re-arms one something wrote inside, and both compose the subtree once at
|
|
1658
|
-
* that moment. `isStatic` is what separates the engine's freeze from a game that turned the flags off
|
|
1659
|
-
* for its own reasons. See `static-transform.ts`.
|
|
1602
|
+
* The frame-period rule that decides when a render cost moves, as Unreal's DynamicRenderScaling does.
|
|
1660
1603
|
*
|
|
1661
|
-
*
|
|
1662
|
-
*
|
|
1663
|
-
*
|
|
1664
|
-
*
|
|
1665
|
-
*
|
|
1666
|
-
*
|
|
1667
|
-
*
|
|
1604
|
+
* It compares the whole GPU frame with the frame period, never one stage's milliseconds. A stage
|
|
1605
|
+
* reading depends on the GPU clock (the SSGI pass read 6.3 ms at P5 and 2.1 to 3.0 ms at boost on one
|
|
1606
|
+
* scene), and the frame period does not. The rule follows UE 5.8.3:
|
|
1607
|
+
* `Engine/Source/Runtime/Engine/Private/DynamicResolution.cpp` (the `r.DynamicRes.*` defaults at
|
|
1608
|
+
* `:32-103`, the history walk at `:219-330`, the change gate at `:370-390`) and
|
|
1609
|
+
* `Engine/Source/Runtime/RenderCore/Private/DynamicRenderScaling.cpp` (`GetTargetedMs`,
|
|
1610
|
+
* `EstimateResolutionFactor`, `DoesResolutionChangeEnough`).
|
|
1668
1611
|
*
|
|
1669
|
-
*
|
|
1670
|
-
*
|
|
1671
|
-
* chain they need) or call `object.updateWorldMatrix(true, false)` first. The convention's named
|
|
1672
|
-
* override is `renderer.matrixWorld: "all"`, which visits every node exactly as three's own walk
|
|
1673
|
-
* does; `"visible"` is the default.
|
|
1674
|
-
*/
|
|
1675
|
-
/** How much of the scene graph the engine walks for world matrices each frame. */
|
|
1676
|
-
type MatrixWorldMode = "visible" | "all";
|
|
1677
|
-
/** What the pass did on the last frame, for the frame telemetry a window reports. */
|
|
1678
|
-
interface IMatrixWorldReport {
|
|
1679
|
-
readonly schemaVersion: 1;
|
|
1680
|
-
readonly mode: MatrixWorldMode;
|
|
1681
|
-
/**
|
|
1682
|
-
* Nodes the engine walked this frame, summed over every application (authored scene and a
|
|
1683
|
-
* projection mirror when one is in use). One number both ways, so `"all"` can be read as the
|
|
1684
|
-
* cost of the walk the convention just removed.
|
|
1685
|
-
*/
|
|
1686
|
-
readonly visited: number;
|
|
1687
|
-
}
|
|
1688
|
-
interface IMatrixWorldOptions {
|
|
1689
|
-
/** `"visible"` (default) skips a hidden subtree; `"all"` reproduces three's own walk. */
|
|
1690
|
-
readonly mode?: MatrixWorldMode;
|
|
1691
|
-
}
|
|
1692
|
-
/**
|
|
1693
|
-
* One game's world-matrix walk, holding the state the pruning needs between frames.
|
|
1694
|
-
*
|
|
1695
|
-
* The stale set and the bone cache live on the instance rather than in module scope: two games,
|
|
1696
|
-
* two playtest scenarios or two roots in one process must not share "this subtree was skipped
|
|
1697
|
-
* while hidden", or one game's hidden node would be force-refreshed by the other's frame.
|
|
1698
|
-
*/
|
|
1699
|
-
declare class MatrixWorldPass {
|
|
1700
|
-
#private;
|
|
1701
|
-
constructor(options?: IMatrixWorldOptions);
|
|
1702
|
-
get mode(): MatrixWorldMode;
|
|
1703
|
-
/** What the current frame has walked so far, across every {@link apply} call. */
|
|
1704
|
-
get report(): IMatrixWorldReport;
|
|
1705
|
-
/** Starts a frame's count. The pass's state (stale set, bone cache) is untouched. */
|
|
1706
|
-
beginFrame(): void;
|
|
1707
|
-
/**
|
|
1708
|
-
* Walks `root`, mirroring three for every node the mode visits.
|
|
1709
|
-
*
|
|
1710
|
-
* Returns the nodes this call visited, so a caller can report one application's cost without
|
|
1711
|
-
* also reporting the frame's total.
|
|
1712
|
-
*/
|
|
1713
|
-
apply(root: Object3D, force?: boolean): number;
|
|
1714
|
-
/** Forgets what was skipped. A whole-scene swap has no hidden ancestors left to refresh. */
|
|
1715
|
-
dispose(): void;
|
|
1716
|
-
}
|
|
1717
|
-
|
|
1718
|
-
/**
|
|
1719
|
-
* The frame-period rule that decides when a render cost moves, as Unreal's DynamicRenderScaling does.
|
|
1720
|
-
*
|
|
1721
|
-
* It compares the whole GPU frame with the frame period, never one stage's milliseconds. A stage
|
|
1722
|
-
* reading depends on the GPU clock (the SSGI pass read 6.3 ms at P5 and 2.1 to 3.0 ms at boost on one
|
|
1723
|
-
* scene), and the frame period does not. The rule follows UE 5.8.3:
|
|
1724
|
-
* `Engine/Source/Runtime/Engine/Private/DynamicResolution.cpp` (the `r.DynamicRes.*` defaults at
|
|
1725
|
-
* `:32-103`, the history walk at `:219-330`, the change gate at `:370-390`) and
|
|
1726
|
-
* `Engine/Source/Runtime/RenderCore/Private/DynamicRenderScaling.cpp` (`GetTargetedMs`,
|
|
1727
|
-
* `EstimateResolutionFactor`, `DoesResolutionChangeEnough`).
|
|
1728
|
-
*
|
|
1729
|
-
* Measurement and decision only: the caller applies a move and calls `reset()`, because the frames of
|
|
1730
|
-
* the old level say nothing about the new one.
|
|
1612
|
+
* Measurement and decision only: the caller applies a move and calls `reset()`, because the frames of
|
|
1613
|
+
* the old level say nothing about the new one.
|
|
1731
1614
|
*/
|
|
1732
1615
|
type FrameTimeModel = "linear" | "quadratic";
|
|
1733
1616
|
interface IFrameTimeBudgetOptions {
|
|
@@ -1917,34 +1800,6 @@ declare class GIBudget {
|
|
|
1917
1800
|
/** Parses a `TN_GI` line back into its report, or `undefined` for any other line. */
|
|
1918
1801
|
declare function readGIMarker(line: string): IGIBudgetReport | undefined;
|
|
1919
1802
|
|
|
1920
|
-
/**
|
|
1921
|
-
* What a visualize mode shows. `off` is the finished frame; `indirectDiffuse` is the bounce light alone, the
|
|
1922
|
-
* counterpart of Unreal's `r.Lumen.Visualize.IndirectDiffuse`. Other GI work adds its modes here when its data exists.
|
|
1923
|
-
*/
|
|
1924
|
-
declare const GI_VISUALIZE_MODES: readonly ["off", "indirectDiffuse"];
|
|
1925
|
-
type GIVisualizeMode = (typeof GI_VISUALIZE_MODES)[number];
|
|
1926
|
-
interface IGIVisualizeOptions {
|
|
1927
|
-
readonly mode: GIVisualizeMode;
|
|
1928
|
-
/** The finished frame, returned unchanged in `off` mode. */
|
|
1929
|
-
readonly beauty: Node<"vec4">;
|
|
1930
|
-
/**
|
|
1931
|
-
* The indirect diffuse light as the surface returns it: the gathered and cached light times the surface's own
|
|
1932
|
-
* albedo, in the frame's exposure. The game's chain builds it, because it owns what the chain gathers.
|
|
1933
|
-
*/
|
|
1934
|
-
readonly indirectDiffuse?: Node<"vec3">;
|
|
1935
|
-
}
|
|
1936
|
-
/**
|
|
1937
|
-
* Shows one lighting term of a frame by itself, so a lighting difference against a reference can be told apart from a
|
|
1938
|
-
* scene difference. The game builds each term in its own chain and picks the mode; this class only selects, and it
|
|
1939
|
-
* fails when the chain did not build the term the mode needs, so a frame never claims to show a term it does not hold.
|
|
1940
|
-
*/
|
|
1941
|
-
declare class GIVisualize {
|
|
1942
|
-
readonly mode: GIVisualizeMode;
|
|
1943
|
-
/** The node to output: `beauty` for `off`, the chosen term with an opaque alpha otherwise. */
|
|
1944
|
-
readonly node: Node<"vec4">;
|
|
1945
|
-
constructor(options: IGIVisualizeOptions);
|
|
1946
|
-
}
|
|
1947
|
-
|
|
1948
1803
|
/** The shadow filter tiers, cheapest first. The game maps each one to its own sample counts. */
|
|
1949
1804
|
declare const SHADOW_FILTER_TIERS: readonly ["low", "medium", "high"];
|
|
1950
1805
|
type ShadowFilterTier = (typeof SHADOW_FILTER_TIERS)[number];
|
|
@@ -2243,7 +2098,7 @@ declare function renderTrapAudit(scene: Object3D & {
|
|
|
2243
2098
|
* **Staticness is authored, never guessed.** A heuristic that decides an object has "not moved in
|
|
2244
2099
|
* 60 frames" is a correctness bug with no reproduction, so nothing here watches gameplay. What the
|
|
2245
2100
|
* engine does do is check the promise where it is cheap to check it: the root's own local transform
|
|
2246
|
-
*
|
|
2101
|
+
* and its parent's world matrix are compared against what was frozen, once per frame, and a root the author moved thaws and
|
|
2247
2102
|
* refreezes itself. That is O(static roots), not O(objects), and it turns the most common way to
|
|
2248
2103
|
* get this wrong into a non-event. Writes deeper inside a frozen subtree are the author's to
|
|
2249
2104
|
* announce with `invalidateStatic`, and `TN_RENDERLIST_VALIDATE=1` is what proves they did.
|
|
@@ -2301,22 +2156,6 @@ declare function staticTransformCensus(): IStaticTransformCensus;
|
|
|
2301
2156
|
/** Drops every registration. A game that tore down its scene must not keep its roots alive. */
|
|
2302
2157
|
declare function resetStaticTransforms(): void;
|
|
2303
2158
|
|
|
2304
|
-
/**
|
|
2305
|
-
* The parity oracle for anything that stops recomputing a transform.
|
|
2306
|
-
*
|
|
2307
|
-
* A cache that is right on the scene you tested and wrong on the one you did not is worse than no
|
|
2308
|
-
* cache, because it ships as a visual bug nobody can reproduce. This is the instrument that makes
|
|
2309
|
-
* the difference falsifiable: with `TN_RENDERLIST_VALIDATE=1`, every frame recomputes every world
|
|
2310
|
-
* matrix from the authored transforms, the long way, and compares it elementwise against the one
|
|
2311
|
-
* the frame is about to draw with. The first disagreement throws, naming the object and the
|
|
2312
|
-
* element, because a validation mode that logs and continues is a validation mode nobody reads.
|
|
2313
|
-
*
|
|
2314
|
-
* It is a validation mode, not a proof: it proves the frames it ran on. Run it on the scenes you
|
|
2315
|
-
* care about, in CI, for as many frames as you can afford.
|
|
2316
|
-
*
|
|
2317
|
-
* Off by default and expensive by construction — it does the work it is checking, twice.
|
|
2318
|
-
*/
|
|
2319
|
-
|
|
2320
2159
|
/** Marker printed when the validator is installed, so a log says which mode produced it. */
|
|
2321
2160
|
declare const RENDERLIST_VALIDATE_MARKER = "TN_RENDERLIST_VALIDATE";
|
|
2322
2161
|
/** The launch flag. */
|
|
@@ -2420,6 +2259,64 @@ interface IProbeVolumeOptions {
|
|
|
2420
2259
|
/** Injectable clock for deterministic scheduling tests. */
|
|
2421
2260
|
readonly now?: () => number;
|
|
2422
2261
|
readonly report?: (line: string) => void;
|
|
2262
|
+
/**
|
|
2263
|
+
* Refresh probes by tracing a GPUSceneBVH (PRD-603) instead of drawing the scene six times per probe.
|
|
2264
|
+
* The default is `trace` when `trace` inputs are given and `capture` otherwise. `capture` is the named
|
|
2265
|
+
* override for scenes that need textured albedo or local lights in their bounce.
|
|
2266
|
+
*/
|
|
2267
|
+
readonly update?: "capture" | "trace";
|
|
2268
|
+
/** The traced refresh's inputs: the packed scene, and the sun and sky the game already holds. */
|
|
2269
|
+
readonly trace?: IProbeVolumeTrace;
|
|
2270
|
+
/** Most probes one frame traces (Unreal's r.Lumen.RadianceCache.NumProbesToTraceBudget, 100). */
|
|
2271
|
+
readonly numProbesToTraceBudget?: number;
|
|
2272
|
+
/**
|
|
2273
|
+
* A fixed batch: probes traced a frame, up to `numProbesToTraceBudget`, whatever the GPU reports. Unset, the batch follows
|
|
2274
|
+
* the measured GPU time toward `bakeBudgetMs` and stays at 16 where the adapter reports none (the owned engine today). A
|
|
2275
|
+
* capture that must trace a whole field before its frame sets it; a game leaves it unset.
|
|
2276
|
+
*/
|
|
2277
|
+
readonly probesPerFrame?: number;
|
|
2278
|
+
/**
|
|
2279
|
+
* Rays per probe along one side: `probeResolution` squared rays. The default is 8 (64 rays), the cost gate's
|
|
2280
|
+
* figure: an Intel Xe traces about 0.09 ms a probe at 8 and 0.41 ms at 32 (1,024 rays, Unreal's radiance-cache
|
|
2281
|
+
* ProbeResolution). A small emitter far from a probe needs the larger value to be hit at all.
|
|
2282
|
+
*/
|
|
2283
|
+
readonly probeResolution?: number;
|
|
2284
|
+
/**
|
|
2285
|
+
* Cells per side of an octahedral radiance map per probe, beside the SH: the traced rays binned by direction, as
|
|
2286
|
+
* Unreal's radiance cache stores 32 x 32 radiance per probe (UE 5.8.3:
|
|
2287
|
+
* Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeGather.cpp:641, GRadianceCacheProbeResolution).
|
|
2288
|
+
* `sampleRadianceNode` then reads the map, sharp where SH L2 smears a coloured wall across the sphere. 0 (the default)
|
|
2289
|
+
* keeps SH only. Traced refresh only.
|
|
2290
|
+
*/
|
|
2291
|
+
readonly radianceProbeResolution?: number;
|
|
2292
|
+
/**
|
|
2293
|
+
* Weight each of the eight probes a read blends by Unreal's depth test: a probe whose map depth toward the read point is
|
|
2294
|
+
* shorter than the point's distance sees a surface first, so it sits behind a wall and drops out (UE 5.8.3:
|
|
2295
|
+
* Engine/Shaders/Private/Lumen/LumenRadianceCacheInterpolation.ush:390, `StepHitDistanceFromProbe` against
|
|
2296
|
+
* `StepRayDistanceFromProbeSq`). Stops light leaking through a wall thinner than a probe spacing. Needs
|
|
2297
|
+
* `radianceProbeResolution`. Off by default.
|
|
2298
|
+
*/
|
|
2299
|
+
readonly probeVisibility?: boolean;
|
|
2300
|
+
}
|
|
2301
|
+
/** What a traced refresh reads. Every value is the game's: the volume owns no light and no colour. */
|
|
2302
|
+
interface IProbeVolumeTrace {
|
|
2303
|
+
/** A GPUSceneBVH, or anything with its CPU snapshot and version. */
|
|
2304
|
+
readonly bvh: {
|
|
2305
|
+
readonly traceScene: IProbeTraceScene;
|
|
2306
|
+
readonly version: number;
|
|
2307
|
+
};
|
|
2308
|
+
/** World direction toward the sun, its linear colour and its intensity; read every frame. */
|
|
2309
|
+
readonly sun: {
|
|
2310
|
+
readonly direction: Vector3;
|
|
2311
|
+
readonly color: Color;
|
|
2312
|
+
readonly intensity: number;
|
|
2313
|
+
};
|
|
2314
|
+
/** Radiance of a ray that leaves the scene; black for a closed interior. Read every frame. */
|
|
2315
|
+
readonly sky: Color;
|
|
2316
|
+
/** Point lights read every frame; the first `points.length` at build are traced (see `IProbeTraceLighting`). */
|
|
2317
|
+
readonly points?: IProbeTraceLighting["points"];
|
|
2318
|
+
/** The view whose frustum marks probes as in use, so they refresh first. Absent: none ranks first. */
|
|
2319
|
+
readonly camera?: Camera;
|
|
2423
2320
|
}
|
|
2424
2321
|
interface IProbeVolumeBakeProgress {
|
|
2425
2322
|
readonly completed: number;
|
|
@@ -2450,6 +2347,16 @@ interface IProbeVolumeObservation {
|
|
|
2450
2347
|
readonly bakeBudgetMs: number;
|
|
2451
2348
|
/** True while pass zero samples a black texture instead of a previous bake. */
|
|
2452
2349
|
readonly samplingIsolated: boolean;
|
|
2350
|
+
/** Which refresh ran: `capture` (six scene draws a probe) or `trace` (one dispatch). Absent means capture. */
|
|
2351
|
+
readonly update?: "capture" | "trace";
|
|
2352
|
+
/** Trace path: probes traced in the last frame. */
|
|
2353
|
+
readonly probesTraced?: number;
|
|
2354
|
+
/** Trace path: probes of the last field that sat inside a solid or behind a wall, filled from open neighbours. */
|
|
2355
|
+
readonly probesRejected?: number;
|
|
2356
|
+
/** Trace path: frames since the least recently traced probe was traced, `null` while one never was. */
|
|
2357
|
+
readonly oldestProbeAgeFrames?: number | null;
|
|
2358
|
+
/** Trace path: materials whose texture or node graph the flat material table ignored. */
|
|
2359
|
+
readonly ignoredTextureMaterials?: number;
|
|
2453
2360
|
}
|
|
2454
2361
|
/** Read a complete marker-shaped observation without accepting malformed data. */
|
|
2455
2362
|
declare function readProbeVolumeObservation(value: unknown): IProbeVolumeObservation | undefined;
|
|
@@ -2504,6 +2411,12 @@ declare class ProbeVolume extends Object3D implements IComputeDriven$1 {
|
|
|
2504
2411
|
sample(position: Vector3, normal: Vector3): Vector3;
|
|
2505
2412
|
sample(position: IProbePosition, normal?: Vector3 | Node<"vec3">): Vector3 | Node<"vec3">;
|
|
2506
2413
|
sampleIrradiance(position: Vector3, normal: Vector3): Vector3;
|
|
2414
|
+
/**
|
|
2415
|
+
* The radiance arriving along `direction` (the SH itself, not convolved with a cosine lobe), clamped at zero. A
|
|
2416
|
+
* screen gather subtracts this per ray, because a hit replaces the cache's radiance along that ray: Lumen reads its
|
|
2417
|
+
* radiance cache per ray direction (UE 5.8.3: Engine/Shaders/Private/Lumen/LumenScreenProbeTracing.usf:831).
|
|
2418
|
+
*/
|
|
2419
|
+
sampleRadiance(position: Vector3, direction: Vector3): Vector3;
|
|
2507
2420
|
/**
|
|
2508
2421
|
* The irradiance averaged over every normal at a point, for a surface or a sample that has no side facing the light:
|
|
2509
2422
|
* a translucent pane (Unreal's default Volumetric NonDirectional lighting) and a fog sample (its isotropic term). It
|
|
@@ -2517,10 +2430,17 @@ declare class ProbeVolume extends Object3D implements IComputeDriven$1 {
|
|
|
2517
2430
|
sampleNonDirectional(position?: Node<"vec3">): Node<"vec3">;
|
|
2518
2431
|
/** The GPU graph used by `sample`; exposed so generated materials can compose it explicitly. */
|
|
2519
2432
|
sampleNode(position?: Node<"vec3">, normal?: Node<"vec3">): Node<"vec3">;
|
|
2433
|
+
/** The GPU graph of `sampleRadiance`: the radiance arriving along `direction`, clamped at zero. */
|
|
2434
|
+
sampleRadianceNode(position?: Node<"vec3">, direction?: Node<"vec3">): Node<"vec3">;
|
|
2520
2435
|
/** Internal data seam used by unit/conformance fixtures to seed a known SH atlas without a GPU. */
|
|
2521
2436
|
setProbeCoefficients(ix: number, iy: number, iz: number, coefficients: readonly IProbeVolumeCoefficient[]): void;
|
|
2522
2437
|
/** One bounded render-phase slice. The game loop calls this through IComputeDriven. */
|
|
2523
2438
|
process(renderer: IRendererLike): void;
|
|
2439
|
+
/**
|
|
2440
|
+
* The stale probes this frame traces, at most the budget: never-traced first, then the largest gap between
|
|
2441
|
+
* last use and last trace (Unreal's priority, UE 5.8.3: LumenRadianceCacheUpdate.usf:221-241), then index.
|
|
2442
|
+
*/
|
|
2443
|
+
selectStaleProbes(): number[];
|
|
2524
2444
|
detach(): void;
|
|
2525
2445
|
get paddedSlices(): number;
|
|
2526
2446
|
get maximumDimension(): number;
|
|
@@ -2528,6 +2448,19 @@ declare class ProbeVolume extends Object3D implements IComputeDriven$1 {
|
|
|
2528
2448
|
probePosition(ix: number, iy: number, iz: number, target?: Vector3): Vector3;
|
|
2529
2449
|
}
|
|
2530
2450
|
|
|
2451
|
+
interface IRadianceCacheOptions extends Omit<IProbeVolumeOptions, "trace" | "update"> {
|
|
2452
|
+
/** The packed scene a probe traces, the sun and the sky it reads. Every value is the game's. */
|
|
2453
|
+
readonly trace: IProbeVolumeTrace;
|
|
2454
|
+
}
|
|
2455
|
+
/**
|
|
2456
|
+
* A probe field that refreshes by tracing the packed scene, Unreal's radiance-cache update model: probes in view
|
|
2457
|
+
* refresh first, the oldest first, a few hundred a frame at most, and the old values serve until replaced.
|
|
2458
|
+
* It is a `ProbeVolume` whose update is always `trace`; sample it with `sampleNode`.
|
|
2459
|
+
*/
|
|
2460
|
+
declare class RadianceCache extends ProbeVolume {
|
|
2461
|
+
constructor(options: IRadianceCacheOptions);
|
|
2462
|
+
}
|
|
2463
|
+
|
|
2531
2464
|
/**
|
|
2532
2465
|
* The Surface Cache: what a traced global-illumination ray reads at the surface it hits (PRD-639).
|
|
2533
2466
|
*
|
|
@@ -2649,176 +2582,10 @@ declare class SurfaceLights {
|
|
|
2649
2582
|
}
|
|
2650
2583
|
|
|
2651
2584
|
/**
|
|
2652
|
-
*
|
|
2585
|
+
* What a {@link VirtualShadowNode} is asked for, what it reports, and the default of every knob.
|
|
2653
2586
|
*
|
|
2654
|
-
*
|
|
2655
|
-
* physical page pool with LRU eviction (`PhysicalPagePool`), camera-centred clip windows snapped
|
|
2656
|
-
* to whole pages in a light-space basis (`DirectionalClipmap`), the pages a frame needs from
|
|
2657
|
-
* receiver points and visible caster bounds (`ReceiverDemandPass`), and the pages a moving caster
|
|
2658
|
-
* dirties (`ShadowInvalidationTracker`). `VirtualShadowNode` in `virtual-shadow.ts` is the only
|
|
2659
|
-
* consumer; everything here is pure so its rules are provable in a node-environment spec.
|
|
2660
|
-
*
|
|
2661
|
-
* Fail closed: malformed input throws at the boundary instead of producing a page that samples
|
|
2662
|
-
* nothing.
|
|
2587
|
+
* Types and defaults only: the node owns the mechanism these describe.
|
|
2663
2588
|
*/
|
|
2664
|
-
/** A plain `{x, y, z}` triple; three's `Vector3` satisfies it without a copy. */
|
|
2665
|
-
interface IVector3Like {
|
|
2666
|
-
readonly x: number;
|
|
2667
|
-
readonly y: number;
|
|
2668
|
-
readonly z: number;
|
|
2669
|
-
}
|
|
2670
|
-
/** An axis-aligned world-space box as two corners. */
|
|
2671
|
-
interface IBoundsLike {
|
|
2672
|
-
readonly min: IVector3Like;
|
|
2673
|
-
readonly max: IVector3Like;
|
|
2674
|
-
}
|
|
2675
|
-
/** A point in the light-space basis: `u` and `v` across the light, `w` toward it. */
|
|
2676
|
-
interface ILightSpacePoint {
|
|
2677
|
-
readonly u: number;
|
|
2678
|
-
readonly v: number;
|
|
2679
|
-
readonly w: number;
|
|
2680
|
-
}
|
|
2681
|
-
/** The address of one virtual page: a clip level and integer page coordinates. */
|
|
2682
|
-
interface IVirtualPageAddress {
|
|
2683
|
-
readonly level: number;
|
|
2684
|
-
readonly x: number;
|
|
2685
|
-
readonly y: number;
|
|
2686
|
-
readonly key: string;
|
|
2687
|
-
}
|
|
2688
|
-
/** One clip level's window of `pagesPerAxis²` virtual pages around the centre. */
|
|
2689
|
-
interface IClipWindow {
|
|
2690
|
-
readonly level: number;
|
|
2691
|
-
readonly extent: number;
|
|
2692
|
-
readonly pageWorldSize: number;
|
|
2693
|
-
/** Pages a window trails its followed centre by before it moves and re-renders. */
|
|
2694
|
-
readonly refreshPages: number;
|
|
2695
|
-
readonly minX: number;
|
|
2696
|
-
readonly minY: number;
|
|
2697
|
-
readonly maxX: number;
|
|
2698
|
-
readonly maxY: number;
|
|
2699
|
-
}
|
|
2700
|
-
interface IDirectionalClipmapOptions {
|
|
2701
|
-
/** Unit-free direction *toward* the source; normalised here. */
|
|
2702
|
-
readonly direction: IVector3Like;
|
|
2703
|
-
/** Half-width of each level's window in world units, finest first. */
|
|
2704
|
-
readonly clipExtents: readonly number[];
|
|
2705
|
-
/** Texels per window edge: one value for every level, or one per level finest first. */
|
|
2706
|
-
readonly pagesPerAxis: number | readonly number[];
|
|
2707
|
-
/**
|
|
2708
|
-
* Fraction of an extent inside which a point selects that level, `(0, 1]`, default 0.9. One value
|
|
2709
|
-
* for every level, or one per level finest first, the last entry standing in for the rest.
|
|
2710
|
-
*/
|
|
2711
|
-
readonly selectionGuard?: number | readonly number[];
|
|
2712
|
-
/**
|
|
2713
|
-
* Fraction of an extent a level's window may trail its followed centre by before it re-renders,
|
|
2714
|
-
* `[0, 1)`, default 0.125. Rounded to whole texels with one texel reserved for a deferred render;
|
|
2715
|
-
* `0` keeps the old one-texel step. Larger steps re-render a level less often as the camera walks. One value
|
|
2716
|
-
* for every level, or one per level finest first, the last entry standing in for the rest.
|
|
2717
|
-
*/
|
|
2718
|
-
readonly refreshStep?: number | readonly number[];
|
|
2719
|
-
/**
|
|
2720
|
-
* The smallest ratio of a window's light-space height to its width, `(0, 1]`, default 1. A low
|
|
2721
|
-
* sun stretches a texel along the light's V axis by `1 / sin(elevation)` of floor, so a window
|
|
2722
|
-
* the same height as it is wide would make every shadow edge across the floor that much blurrier.
|
|
2723
|
-
* A ratio below 1 shrinks the height to `sin(elevation)`, never under this value, and the texels
|
|
2724
|
-
* then cover the same floor area at any sun height. A sun within 18 degrees of the zenith keeps
|
|
2725
|
-
* square windows. Page coordinates stay square: `v` counts pages in that shrunken height.
|
|
2726
|
-
*/
|
|
2727
|
-
readonly minAspect?: number;
|
|
2728
|
-
}
|
|
2729
|
-
/**
|
|
2730
|
-
* Camera-centred clip windows in a light-space basis, snapped to whole pages.
|
|
2731
|
-
*
|
|
2732
|
-
* The basis is right-handed (`U × V = W`). A page camera placed along `+W` with `up = V` then
|
|
2733
|
-
* renders screen X = `V × W` = `+U`, which is the axis the sampler reads the atlas along. The
|
|
2734
|
-
* prototype this was ported from built `V = U × W` and every page came out mirrored.
|
|
2735
|
-
*/
|
|
2736
|
-
declare class DirectionalClipmap {
|
|
2737
|
-
#private;
|
|
2738
|
-
readonly clipExtents: readonly number[];
|
|
2739
|
-
/**
|
|
2740
|
-
* Per level, finest first; the last entry stands in for every level past it. Mutable through
|
|
2741
|
-
* {@link setRefreshStep} so a level whose own render is expensive can be stepped further, which
|
|
2742
|
-
* is fewer grid positions for its window rather than a different grid.
|
|
2743
|
-
*/
|
|
2744
|
-
refreshStep: number[];
|
|
2745
|
-
/** Per level, finest first; the last entry stands in for every level past it. */
|
|
2746
|
-
readonly selectionGuard: readonly number[];
|
|
2747
|
-
readonly levelCount: number;
|
|
2748
|
-
basisU: IVector3Like;
|
|
2749
|
-
basisV: IVector3Like;
|
|
2750
|
-
basisW: IVector3Like;
|
|
2751
|
-
/** Window height over width: `v` is metres along `basisV` divided by this. 1 is a square window. */
|
|
2752
|
-
vScale: number;
|
|
2753
|
-
readonly minAspect: number;
|
|
2754
|
-
centerWorld: IVector3Like;
|
|
2755
|
-
centerLight: ILightSpacePoint;
|
|
2756
|
-
constructor({ direction, clipExtents, pagesPerAxis, selectionGuard, refreshStep, minAspect, }: IDirectionalClipmapOptions);
|
|
2757
|
-
/** Re-orient the basis; returns true when it changed enough that cached pages are stale. */
|
|
2758
|
-
setDirection(direction: IVector3Like): boolean;
|
|
2759
|
-
project(worldPoint: IVector3Like): ILightSpacePoint;
|
|
2760
|
-
unproject({ u, v, w }: {
|
|
2761
|
-
u: number;
|
|
2762
|
-
v: number;
|
|
2763
|
-
w?: number;
|
|
2764
|
-
}): IVector3Like;
|
|
2765
|
-
/** Re-step one level's window: the trail its followed centre may move before it re-renders. */
|
|
2766
|
-
setRefreshStep(level: number, step: number): void;
|
|
2767
|
-
/** Texels per edge of `level`'s window. */
|
|
2768
|
-
pagesAt(level: number): number;
|
|
2769
|
-
/** Resize the windows (one value, or one per level); every window is placed afresh. */
|
|
2770
|
-
setPagesPerAxis(pagesPerAxis: number | readonly number[]): void;
|
|
2771
|
-
updateCenter(worldPoint: IVector3Like): readonly IClipWindow[];
|
|
2772
|
-
getWindow(level: number): IClipWindow;
|
|
2773
|
-
pageWorldSize(level: number): number;
|
|
2774
|
-
containsPage(level: number, x: number, y: number): boolean;
|
|
2775
|
-
worldToPage(worldPoint: IVector3Like, level: number): IVirtualPageAddress;
|
|
2776
|
-
/** The finest level whose guarded extent contains the point, else the coarsest. */
|
|
2777
|
-
selectLevel(worldPoint: IVector3Like): number;
|
|
2778
|
-
/** Light-space extent and world centre (at `w = 0`) of one page. */
|
|
2779
|
-
pageBounds(level: number, x: number, y: number): {
|
|
2780
|
-
level: number;
|
|
2781
|
-
x: number;
|
|
2782
|
-
y: number;
|
|
2783
|
-
minU: number;
|
|
2784
|
-
minV: number;
|
|
2785
|
-
maxU: number;
|
|
2786
|
-
maxV: number;
|
|
2787
|
-
centerU: number;
|
|
2788
|
-
centerV: number;
|
|
2789
|
-
pageWorldSize: number;
|
|
2790
|
-
centerWorld: IVector3Like;
|
|
2791
|
-
};
|
|
2792
|
-
boundsToPageRange(bounds: IBoundsLike, level: number): {
|
|
2793
|
-
minX: number;
|
|
2794
|
-
maxX: number;
|
|
2795
|
-
minY: number;
|
|
2796
|
-
maxY: number;
|
|
2797
|
-
};
|
|
2798
|
-
boundsToPageKeys(bounds: IBoundsLike, level: number): string[];
|
|
2799
|
-
windowPages(level: number): IVirtualPageAddress[];
|
|
2800
|
-
}
|
|
2801
|
-
/**
|
|
2802
|
-
* Remembers each tracked caster's last bounds and dirties every page the old and new bounds
|
|
2803
|
-
* cover on every level when they change. Unchanged bounds dirty nothing.
|
|
2804
|
-
*/
|
|
2805
|
-
declare class ShadowInvalidationTracker {
|
|
2806
|
-
#private;
|
|
2807
|
-
readonly clipmap: DirectionalClipmap;
|
|
2808
|
-
constructor(clipmap: DirectionalClipmap);
|
|
2809
|
-
get trackedCount(): number;
|
|
2810
|
-
/** Record a caster's current bounds; returns true when pages were dirtied. */
|
|
2811
|
-
update(id: number | string, bounds: IBoundsLike): boolean;
|
|
2812
|
-
has(id: number | string): boolean;
|
|
2813
|
-
remove(id: number | string): boolean;
|
|
2814
|
-
/** Dirty the current coverage of every tracked caster; returns the pending key count. */
|
|
2815
|
-
invalidateAll(): number;
|
|
2816
|
-
/** Drop trackers whose id is not in `liveIds`, dirtying the pages they covered. */
|
|
2817
|
-
prune(liveIds: ReadonlySet<number | string>): number;
|
|
2818
|
-
consumeInvalidatedKeys(): Set<string>;
|
|
2819
|
-
clear(): void;
|
|
2820
|
-
}
|
|
2821
|
-
|
|
2822
2589
|
/**
|
|
2823
2590
|
* Options for {@link VirtualShadowNode}. Every value is a mechanism parameter; the light's own
|
|
2824
2591
|
* `shadow` keeps bias, normalBias, intensity, map type and filter, exactly as with a stock shadow.
|
|
@@ -2829,6 +2596,17 @@ interface IVirtualShadowOptions {
|
|
|
2829
2596
|
* increasing. Default `[16, 48, 144]`: three windows, each three times wider than the last.
|
|
2830
2597
|
*/
|
|
2831
2598
|
readonly clipExtents?: readonly number[];
|
|
2599
|
+
/**
|
|
2600
|
+
* The widest step between two levels, default 2: where `clipExtents` jump further, levels are
|
|
2601
|
+
* inserted at even ratios, as UE 5.8.3 doubles every clipmap level (`GetLevelRadius`,
|
|
2602
|
+
* Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapClipmap.cpp:175-179). A
|
|
2603
|
+
* receiver crossing a level edge then changes texel size by at most this ratio: across `[24, 320]`
|
|
2604
|
+
* the texel grew 13 times at once and every tree on the edge flipped from self-shadowed to flat
|
|
2605
|
+
* lit. Per-level lists (`mapSize`, `refreshStep`, `selectionGuard`, `invalidationDelay`) give an
|
|
2606
|
+
* inserted level the value of the authored level it leads into. `Infinity` keeps the authored
|
|
2607
|
+
* levels as they are, and `TN_VIRTUAL_SHADOW_OVERRIDE` reports it.
|
|
2608
|
+
*/
|
|
2609
|
+
readonly maxLevelRatio?: number;
|
|
2832
2610
|
/**
|
|
2833
2611
|
* Resolution bias in stops, default 0. Mirrors Unreal's
|
|
2834
2612
|
* `r.Shadow.Virtual.ResolutionLodBiasDirectional`; a quality tier sets it. With the default map
|
|
@@ -3134,27 +2912,282 @@ interface IVirtualShadowDraws {
|
|
|
3134
2912
|
*/
|
|
3135
2913
|
readonly keys: number;
|
|
3136
2914
|
}
|
|
3137
|
-
|
|
3138
|
-
/**
|
|
3139
|
-
*
|
|
3140
|
-
*
|
|
3141
|
-
|
|
3142
|
-
|
|
2915
|
+
|
|
2916
|
+
/**
|
|
2917
|
+
* Renderer-independent bookkeeping for virtual shadow pages.
|
|
2918
|
+
*
|
|
2919
|
+
* Four pieces, none of which know a GPU exists: stable virtual page addresses and a bounded
|
|
2920
|
+
* physical page pool with LRU eviction (`PhysicalPagePool`), camera-centred clip windows snapped
|
|
2921
|
+
* to whole pages in a light-space basis (`DirectionalClipmap`), the pages a frame needs from
|
|
2922
|
+
* receiver points and visible caster bounds (`ReceiverDemandPass`), and the pages a moving caster
|
|
2923
|
+
* dirties (`ShadowInvalidationTracker`). `VirtualShadowNode` in `virtual-shadow.ts` is the only
|
|
2924
|
+
* consumer; everything here is pure so its rules are provable in a node-environment spec.
|
|
2925
|
+
*
|
|
2926
|
+
* Fail closed: malformed input throws at the boundary instead of producing a page that samples
|
|
2927
|
+
* nothing.
|
|
2928
|
+
*/
|
|
2929
|
+
/** A plain `{x, y, z}` triple; three's `Vector3` satisfies it without a copy. */
|
|
2930
|
+
interface IVector3Like {
|
|
2931
|
+
readonly x: number;
|
|
2932
|
+
readonly y: number;
|
|
2933
|
+
readonly z: number;
|
|
2934
|
+
}
|
|
2935
|
+
/** An axis-aligned world-space box as two corners. */
|
|
2936
|
+
interface IBoundsLike {
|
|
2937
|
+
readonly min: IVector3Like;
|
|
2938
|
+
readonly max: IVector3Like;
|
|
2939
|
+
}
|
|
2940
|
+
/** A point in the light-space basis: `u` and `v` across the light, `w` toward it. */
|
|
2941
|
+
interface ILightSpacePoint {
|
|
2942
|
+
readonly u: number;
|
|
2943
|
+
readonly v: number;
|
|
2944
|
+
readonly w: number;
|
|
2945
|
+
}
|
|
2946
|
+
/** The address of one virtual page: a clip level and integer page coordinates. */
|
|
2947
|
+
interface IVirtualPageAddress {
|
|
2948
|
+
readonly level: number;
|
|
2949
|
+
readonly x: number;
|
|
2950
|
+
readonly y: number;
|
|
2951
|
+
readonly key: string;
|
|
2952
|
+
}
|
|
2953
|
+
/** One clip level's window of `pagesPerAxis²` virtual pages around the centre. */
|
|
2954
|
+
interface IClipWindow {
|
|
2955
|
+
readonly level: number;
|
|
2956
|
+
readonly extent: number;
|
|
2957
|
+
readonly pageWorldSize: number;
|
|
2958
|
+
/** Pages a window trails its followed centre by before it moves and re-renders. */
|
|
2959
|
+
readonly refreshPages: number;
|
|
2960
|
+
readonly minX: number;
|
|
2961
|
+
readonly minY: number;
|
|
2962
|
+
readonly maxX: number;
|
|
2963
|
+
readonly maxY: number;
|
|
2964
|
+
}
|
|
2965
|
+
interface IDirectionalClipmapOptions {
|
|
2966
|
+
/** Unit-free direction *toward* the source; normalised here. */
|
|
2967
|
+
readonly direction: IVector3Like;
|
|
2968
|
+
/** Half-width of each level's window in world units, finest first. */
|
|
2969
|
+
readonly clipExtents: readonly number[];
|
|
2970
|
+
/** Texels per window edge: one value for every level, or one per level finest first. */
|
|
2971
|
+
readonly pagesPerAxis: number | readonly number[];
|
|
2972
|
+
/**
|
|
2973
|
+
* Fraction of an extent inside which a point selects that level, `(0, 1]`, default 0.9. One value
|
|
2974
|
+
* for every level, or one per level finest first, the last entry standing in for the rest.
|
|
2975
|
+
*/
|
|
2976
|
+
readonly selectionGuard?: number | readonly number[];
|
|
2977
|
+
/**
|
|
2978
|
+
* Fraction of an extent a level's window may trail its followed centre by before it re-renders,
|
|
2979
|
+
* `[0, 1)`, default 0.125. Rounded to whole texels with one texel reserved for a deferred render;
|
|
2980
|
+
* `0` keeps the old one-texel step. Larger steps re-render a level less often as the camera walks. One value
|
|
2981
|
+
* for every level, or one per level finest first, the last entry standing in for the rest.
|
|
2982
|
+
*/
|
|
2983
|
+
readonly refreshStep?: number | readonly number[];
|
|
2984
|
+
/**
|
|
2985
|
+
* The smallest ratio of a window's light-space height to its width, `(0, 1]`, default 1. A low
|
|
2986
|
+
* sun stretches a texel along the light's V axis by `1 / sin(elevation)` of floor, so a window
|
|
2987
|
+
* the same height as it is wide would make every shadow edge across the floor that much blurrier.
|
|
2988
|
+
* A ratio below 1 shrinks the height to `sin(elevation)`, never under this value, and the texels
|
|
2989
|
+
* then cover the same floor area at any sun height. A sun within 18 degrees of the zenith keeps
|
|
2990
|
+
* square windows. Page coordinates stay square: `v` counts pages in that shrunken height.
|
|
2991
|
+
*/
|
|
2992
|
+
readonly minAspect?: number;
|
|
2993
|
+
}
|
|
2994
|
+
/**
|
|
2995
|
+
* Camera-centred clip windows in a light-space basis, snapped to whole pages.
|
|
2996
|
+
*
|
|
2997
|
+
* The basis is right-handed (`U × V = W`). A page camera placed along `+W` with `up = V` then
|
|
2998
|
+
* renders screen X = `V × W` = `+U`, which is the axis the sampler reads the atlas along. The
|
|
2999
|
+
* prototype this was ported from built `V = U × W` and every page came out mirrored.
|
|
3000
|
+
*/
|
|
3001
|
+
declare class DirectionalClipmap {
|
|
3002
|
+
#private;
|
|
3003
|
+
readonly clipExtents: readonly number[];
|
|
3004
|
+
/**
|
|
3005
|
+
* Per level, finest first; the last entry stands in for every level past it. Mutable through
|
|
3006
|
+
* {@link setRefreshStep} so a level whose own render is expensive can be stepped further, which
|
|
3007
|
+
* is fewer grid positions for its window rather than a different grid.
|
|
3008
|
+
*/
|
|
3009
|
+
refreshStep: number[];
|
|
3010
|
+
/** Per level, finest first; the last entry stands in for every level past it. */
|
|
3011
|
+
readonly selectionGuard: readonly number[];
|
|
3012
|
+
readonly levelCount: number;
|
|
3013
|
+
basisU: IVector3Like;
|
|
3014
|
+
basisV: IVector3Like;
|
|
3015
|
+
basisW: IVector3Like;
|
|
3016
|
+
/** Window height over width: `v` is metres along `basisV` divided by this. 1 is a square window. */
|
|
3017
|
+
vScale: number;
|
|
3018
|
+
readonly minAspect: number;
|
|
3019
|
+
centerWorld: IVector3Like;
|
|
3020
|
+
centerLight: ILightSpacePoint;
|
|
3021
|
+
constructor({ direction, clipExtents, pagesPerAxis, selectionGuard, refreshStep, minAspect, }: IDirectionalClipmapOptions);
|
|
3022
|
+
/** Re-orient the basis; returns true when it changed enough that cached pages are stale. */
|
|
3023
|
+
setDirection(direction: IVector3Like): boolean;
|
|
3024
|
+
project(worldPoint: IVector3Like): ILightSpacePoint;
|
|
3025
|
+
unproject({ u, v, w }: {
|
|
3026
|
+
u: number;
|
|
3027
|
+
v: number;
|
|
3028
|
+
w?: number;
|
|
3029
|
+
}): IVector3Like;
|
|
3030
|
+
/** Re-step one level's window: the trail its followed centre may move before it re-renders. */
|
|
3031
|
+
setRefreshStep(level: number, step: number): void;
|
|
3032
|
+
/** Texels per edge of `level`'s window. */
|
|
3033
|
+
pagesAt(level: number): number;
|
|
3034
|
+
/** Resize the windows (one value, or one per level); every window is placed afresh. */
|
|
3035
|
+
setPagesPerAxis(pagesPerAxis: number | readonly number[]): void;
|
|
3036
|
+
updateCenter(worldPoint: IVector3Like): readonly IClipWindow[];
|
|
3037
|
+
getWindow(level: number): IClipWindow;
|
|
3038
|
+
pageWorldSize(level: number): number;
|
|
3039
|
+
containsPage(level: number, x: number, y: number): boolean;
|
|
3040
|
+
worldToPage(worldPoint: IVector3Like, level: number): IVirtualPageAddress;
|
|
3041
|
+
/** The finest level whose guarded extent contains the point, else the coarsest. */
|
|
3042
|
+
selectLevel(worldPoint: IVector3Like): number;
|
|
3043
|
+
/** Light-space extent and world centre (at `w = 0`) of one page. */
|
|
3044
|
+
pageBounds(level: number, x: number, y: number): {
|
|
3045
|
+
level: number;
|
|
3046
|
+
x: number;
|
|
3047
|
+
y: number;
|
|
3048
|
+
minU: number;
|
|
3049
|
+
minV: number;
|
|
3050
|
+
maxU: number;
|
|
3051
|
+
maxV: number;
|
|
3052
|
+
centerU: number;
|
|
3053
|
+
centerV: number;
|
|
3054
|
+
pageWorldSize: number;
|
|
3055
|
+
centerWorld: IVector3Like;
|
|
3056
|
+
};
|
|
3057
|
+
boundsToPageRange(bounds: IBoundsLike, level: number): {
|
|
3058
|
+
minX: number;
|
|
3059
|
+
maxX: number;
|
|
3060
|
+
minY: number;
|
|
3061
|
+
maxY: number;
|
|
3062
|
+
};
|
|
3063
|
+
boundsToPageKeys(bounds: IBoundsLike, level: number): string[];
|
|
3064
|
+
windowPages(level: number): IVirtualPageAddress[];
|
|
3065
|
+
}
|
|
3066
|
+
/**
|
|
3067
|
+
* Remembers each tracked caster's last bounds and dirties every page the old and new bounds
|
|
3068
|
+
* cover on every level when they change. Unchanged bounds dirty nothing.
|
|
3069
|
+
*/
|
|
3070
|
+
declare class ShadowInvalidationTracker {
|
|
3071
|
+
#private;
|
|
3072
|
+
readonly clipmap: DirectionalClipmap;
|
|
3073
|
+
constructor(clipmap: DirectionalClipmap);
|
|
3074
|
+
/** Dirty page keys not yet consumed by the next shadow render. */
|
|
3075
|
+
get pending(): number;
|
|
3076
|
+
get trackedCount(): number;
|
|
3077
|
+
/** Record a caster's current bounds; returns true when pages were dirtied. */
|
|
3078
|
+
update(id: number | string, bounds: IBoundsLike): boolean;
|
|
3079
|
+
has(id: number | string): boolean;
|
|
3080
|
+
remove(id: number | string): boolean;
|
|
3081
|
+
/** Dirty the current coverage of every tracked caster; returns the pending key count. */
|
|
3082
|
+
invalidateAll(): number;
|
|
3083
|
+
/** Drop trackers whose id is not in `liveIds`, dirtying the pages they covered. */
|
|
3084
|
+
prune(liveIds: ReadonlySet<number | string>): number;
|
|
3085
|
+
consumeInvalidatedKeys(): Set<string>;
|
|
3086
|
+
clear(): void;
|
|
3087
|
+
}
|
|
3088
|
+
|
|
3089
|
+
/**
|
|
3090
|
+
* The object layers a virtual shadow draws on, and the clip ladder its levels sit at.
|
|
3091
|
+
*
|
|
3092
|
+
* One owner for the numbers: the node renders the maps, `WorldCells` mints the casters on these
|
|
3093
|
+
* bits, and the chunk proxies stand in for merged geometry. A copy that drifts puts the world's
|
|
3094
|
+
* casters on a layer no level camera reads, and no error says so — the shadow is simply missing.
|
|
3095
|
+
*/
|
|
3096
|
+
/**
|
|
3097
|
+
* The object layer tracked casters are enabled on, so each level's mover camera sees only them.
|
|
3098
|
+
* Keep it free of other uses; the main camera never needs it (tracked objects keep layer 0).
|
|
3099
|
+
*/
|
|
3100
|
+
declare const VIRTUAL_SHADOW_MOVER_LAYER = 29;
|
|
3101
|
+
/**
|
|
3102
|
+
* The object layer a shadow-only caster is put on, so each level's own shadow camera renders it and
|
|
3103
|
+
* the main camera never sees it. The level cameras have it enabled already; an object that exists
|
|
3104
|
+
* only as a shadow caster calls `object.layers.set(VIRTUAL_SHADOW_CASTER_LAYER)`.
|
|
3105
|
+
*/
|
|
3106
|
+
declare const VIRTUAL_SHADOW_CASTER_LAYER = 28;
|
|
3107
|
+
/**
|
|
3108
|
+
* The wide counterpart of {@link VIRTUAL_SHADOW_CASTER_LAYER}: one caster mesh per
|
|
3109
|
+
* `asset:level:part` holding every resident cell's records, for the levels whose window covers the
|
|
3110
|
+
* whole resident ring. A level renders exactly one of the two caster layers — whichever submits
|
|
3111
|
+
* fewer draws, counted off the meshes themselves, because a cluster per square is a draw per square
|
|
3112
|
+
* for the same pixels once the window holds the ring. `WorldCells` writes both halves of every key,
|
|
3113
|
+
* so whichever a level picks is there; the main camera renders neither.
|
|
3114
|
+
*/
|
|
3115
|
+
declare const VIRTUAL_SHADOW_WIDE_CASTER_LAYER = 27;
|
|
3116
|
+
|
|
3117
|
+
/**
|
|
3118
|
+
* The `TN_VIRTUAL_SHADOW`, `TN_SHADOW_REFRESH`, `TN_SHADOW_GATE` and `TN_LAMP_SHADOW` lines, how
|
|
3119
|
+
* often each prints, and the parsers that read them back.
|
|
3120
|
+
*
|
|
3121
|
+
* A marker is the only way a browser run can see inside the node: which level is being throttled,
|
|
3122
|
+
* which one is shedding its tiniest casters, and what a frame's shadow work cost. The parsers are
|
|
3123
|
+
* here so a harness reads exactly the shape the node prints.
|
|
3124
|
+
*/
|
|
3125
|
+
declare const VIRTUAL_SHADOW_MARKER = "TN_VIRTUAL_SHADOW";
|
|
3126
|
+
/**
|
|
3127
|
+
* Parse a `TN_VIRTUAL_SHADOW` console line back into its complete stats, or `undefined`.
|
|
3128
|
+
*
|
|
3129
|
+
* @situation inspect virtual shadow cache and mover counters from a renderer log
|
|
3130
|
+
* @constraint non-marker lines and markers with incomplete or non-numeric stats return `undefined`
|
|
3131
|
+
* @example
|
|
3132
|
+
* const stats = readVirtualShadowMarker(line);
|
|
3133
|
+
* if (stats !== undefined) console.log(stats.reuseRatio);
|
|
3134
|
+
*/
|
|
3135
|
+
declare function readVirtualShadowMarker(line: string): IVirtualShadowStats | undefined;
|
|
3136
|
+
/**
|
|
3137
|
+
* One frame's shadow passes on the owned engine with the spot and point light maps apart from the
|
|
3138
|
+
* sun's (PRD-650). The sun's draws and the lamps' add up to every shadow draw the renderer submitted.
|
|
3139
|
+
*/
|
|
3140
|
+
interface ILampShadowStats {
|
|
3141
|
+
readonly frame: number;
|
|
3142
|
+
readonly shadowDraws: number;
|
|
3143
|
+
/** The sun's maps: its virtual levels or its plain map. `gpuMs` is -1 until a GPU sample resolves. */
|
|
3144
|
+
readonly sun: {
|
|
3145
|
+
readonly draws: number;
|
|
3146
|
+
readonly gpuMs: number;
|
|
3147
|
+
};
|
|
3148
|
+
/** The lamp maps the frame redrew (a cube's six faces are one), their draws, and their GPU time. */
|
|
3149
|
+
readonly lamps: {
|
|
3150
|
+
readonly redraws: number;
|
|
3151
|
+
readonly draws: number;
|
|
3152
|
+
readonly gpuMs: number;
|
|
3153
|
+
};
|
|
3154
|
+
}
|
|
3155
|
+
declare const LAMP_SHADOW_MARKER = "TN_LAMP_SHADOW";
|
|
3156
|
+
interface ILampShadowCounters {
|
|
3157
|
+
readonly lampRedraws: number;
|
|
3158
|
+
readonly lampDraws: number;
|
|
3159
|
+
readonly shadowDraws: number;
|
|
3160
|
+
readonly sunGpuMs: number;
|
|
3161
|
+
readonly lampGpuMs: number;
|
|
3162
|
+
}
|
|
3143
3163
|
/**
|
|
3144
|
-
* The
|
|
3145
|
-
*
|
|
3146
|
-
*
|
|
3164
|
+
* The `TN_LAMP_SHADOW` line for the renderer's last frame, or `undefined` on a renderer that keeps
|
|
3165
|
+
* no lamp counters (three's own).
|
|
3166
|
+
*
|
|
3167
|
+
* @situation log lamp shadow redraws and GPU time apart from the sun's on the owned engine
|
|
3168
|
+
* @constraint counters that do not add up to the frame's shadow draws throw TN_LAMP_SHADOW_INVALID
|
|
3169
|
+
* @example
|
|
3170
|
+
* const line = lampShadowMarker(renderer, frame);
|
|
3171
|
+
* if (line !== undefined) console.info(line);
|
|
3147
3172
|
*/
|
|
3148
|
-
declare
|
|
3173
|
+
declare function lampShadowMarker(renderer: {
|
|
3174
|
+
readonly info?: {
|
|
3175
|
+
readonly engine?: {
|
|
3176
|
+
readonly shadows?: ILampShadowCounters;
|
|
3177
|
+
};
|
|
3178
|
+
};
|
|
3179
|
+
}, frame: number): string | undefined;
|
|
3149
3180
|
/**
|
|
3150
|
-
*
|
|
3151
|
-
*
|
|
3152
|
-
*
|
|
3153
|
-
*
|
|
3154
|
-
*
|
|
3155
|
-
*
|
|
3181
|
+
* Parse a `TN_LAMP_SHADOW` line back into its stats, or `undefined`.
|
|
3182
|
+
*
|
|
3183
|
+
* @situation count lamp shadow redraws from a renderer log, for example a moving-caster run
|
|
3184
|
+
* @constraint non-marker lines and markers whose sun and lamp draws do not add up return `undefined`
|
|
3185
|
+
* @example
|
|
3186
|
+
* const stats = readLampShadowMarker(line);
|
|
3187
|
+
* if (stats !== undefined) console.log(stats.lamps.redraws);
|
|
3156
3188
|
*/
|
|
3157
|
-
declare
|
|
3189
|
+
declare function readLampShadowMarker(line: string): ILampShadowStats | undefined;
|
|
3190
|
+
|
|
3158
3191
|
/**
|
|
3159
3192
|
* One directional shadow for a whole open world: camera-centred clip levels, each snapped to its
|
|
3160
3193
|
* own texel grid and re-rendered only when its window moves. Movers never touch that cache: a
|
|
@@ -3182,11 +3215,13 @@ declare const VIRTUAL_SHADOW_WIDE_CASTER_LAYER = 27;
|
|
|
3182
3215
|
* @situation shadow map too coarse over a big terrain
|
|
3183
3216
|
* @situation one directional light shadow for a whole open world
|
|
3184
3217
|
* @situation shadows shimmer when the camera moves
|
|
3218
|
+
* @situation shadow edges, tree lighting or level sharpness change while a third-person camera turns around its hero
|
|
3185
3219
|
* @constraint the light must be a DirectionalLight with `castShadow` and a target in the scene
|
|
3186
3220
|
* @constraint clipExtents are half-widths in world units, finest first, strictly increasing
|
|
3187
3221
|
* @constraint movers sort themselves: a layer-0 caster whose world matrix, instance matrix or deformation changed draws through the mover maps and leaves the cached levels, and returns to them after `staticAfterFrames` quiet frames; the cache redraws only the region it left
|
|
3188
3222
|
* @constraint `trackCaster(object)` is the override that pins an object as a mover for good (it enables layer `VIRTUAL_SHADOW_MOVER_LAYER` on the object and its descendants), and `pinStatic(object)` opts an object out of detection; tracking or untracking refreshes only that object's region
|
|
3189
3223
|
* @override bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults
|
|
3224
|
+
* @override setFocus(point) centres every window on a subject (a third-person hero) instead of the eye, so an orbiting eye moves no shadow; setFocus(undefined) hands them back
|
|
3190
3225
|
* @override followViewFocus: false keeps eye follow; receiverPlaneBias: false uses only authored bias
|
|
3191
3226
|
* @override minWindowAspect: below 1, a level is as high as `sin(sun elevation)` times its width, never under this, so a low sun's floor shadows keep the texel density of a high sun's; the default 1 keeps square levels
|
|
3192
3227
|
* @example
|
|
@@ -3223,6 +3258,12 @@ declare class VirtualShadowNode extends ShadowBaseNode {
|
|
|
3223
3258
|
* callers that already update this tracker still invalidate the affected cached levels.
|
|
3224
3259
|
*/
|
|
3225
3260
|
readonly tracker: ShadowInvalidationTracker;
|
|
3261
|
+
/** Core startup cover: drain all due levels without steady-state invalidation delays. */
|
|
3262
|
+
startupCovered: boolean;
|
|
3263
|
+
/** Three's type flag; core's startup gate reads it so the game loop never imports this class. */
|
|
3264
|
+
readonly isVirtualShadowNode = true;
|
|
3265
|
+
/** Every map is present and no requested/delayed invalidation remains. */
|
|
3266
|
+
get settled(): boolean;
|
|
3226
3267
|
constructor(light: DirectionalLight, options?: IVirtualShadowOptions);
|
|
3227
3268
|
/** The per-frame counters, as of the last `updateBefore`. */
|
|
3228
3269
|
get stats(): IVirtualShadowStats;
|
|
@@ -3265,74 +3306,20 @@ declare class VirtualShadowNode extends ShadowBaseNode {
|
|
|
3265
3306
|
invalidateRegion(bounds: IBoundsLike & {
|
|
3266
3307
|
admission?: boolean;
|
|
3267
3308
|
}, admission?: boolean): void;
|
|
3309
|
+
/**
|
|
3310
|
+
* Centre every clip window on `point` instead of the camera's eye, or on the eye again with
|
|
3311
|
+
* `undefined`. The point is the view's subject: a third-person hero, an orbit pivot. Level
|
|
3312
|
+
* selection, blend bands and window pans then depend on the subject alone, so a camera that turns
|
|
3313
|
+
* around it (its eye travels the arm's whole circle) moves no shadow edge and re-renders no page.
|
|
3314
|
+
* Unreal does the same for a view target (UE 5.8.3: VirtualShadowMapClipmap.cpp:256-295 moves the
|
|
3315
|
+
* clipmap WorldOrigin onto it). Call it whenever the subject moves; an unchanged point costs one
|
|
3316
|
+
* comparison. The point is copied, so a live `position` can be passed every frame.
|
|
3317
|
+
*/
|
|
3318
|
+
setFocus(point: IVector3Like | undefined): void;
|
|
3268
3319
|
setup(builder: NodeBuilder): Node | null | undefined;
|
|
3269
3320
|
updateBefore(frame: NodeFrame): undefined;
|
|
3270
3321
|
dispose(): void;
|
|
3271
3322
|
}
|
|
3272
|
-
/**
|
|
3273
|
-
* Parse a `TN_VIRTUAL_SHADOW` console line back into its complete stats, or `undefined`.
|
|
3274
|
-
*
|
|
3275
|
-
* @situation inspect virtual shadow cache and mover counters from a renderer log
|
|
3276
|
-
* @constraint non-marker lines and markers with incomplete or non-numeric stats return `undefined`
|
|
3277
|
-
* @example
|
|
3278
|
-
* const stats = readVirtualShadowMarker(line);
|
|
3279
|
-
* if (stats !== undefined) console.log(stats.reuseRatio);
|
|
3280
|
-
*/
|
|
3281
|
-
declare function readVirtualShadowMarker(line: string): IVirtualShadowStats | undefined;
|
|
3282
|
-
/**
|
|
3283
|
-
* One frame's shadow passes on the owned engine with the spot and point light maps apart from the
|
|
3284
|
-
* sun's (PRD-650). The sun's draws and the lamps' add up to every shadow draw the renderer submitted.
|
|
3285
|
-
*/
|
|
3286
|
-
interface ILampShadowStats {
|
|
3287
|
-
readonly frame: number;
|
|
3288
|
-
readonly shadowDraws: number;
|
|
3289
|
-
/** The sun's maps: its virtual levels or its plain map. `gpuMs` is -1 until a GPU sample resolves. */
|
|
3290
|
-
readonly sun: {
|
|
3291
|
-
readonly draws: number;
|
|
3292
|
-
readonly gpuMs: number;
|
|
3293
|
-
};
|
|
3294
|
-
/** The lamp maps the frame redrew (a cube's six faces are one), their draws, and their GPU time. */
|
|
3295
|
-
readonly lamps: {
|
|
3296
|
-
readonly redraws: number;
|
|
3297
|
-
readonly draws: number;
|
|
3298
|
-
readonly gpuMs: number;
|
|
3299
|
-
};
|
|
3300
|
-
}
|
|
3301
|
-
declare const LAMP_SHADOW_MARKER = "TN_LAMP_SHADOW";
|
|
3302
|
-
interface ILampShadowCounters {
|
|
3303
|
-
readonly lampRedraws: number;
|
|
3304
|
-
readonly lampDraws: number;
|
|
3305
|
-
readonly shadowDraws: number;
|
|
3306
|
-
readonly sunGpuMs: number;
|
|
3307
|
-
readonly lampGpuMs: number;
|
|
3308
|
-
}
|
|
3309
|
-
/**
|
|
3310
|
-
* The `TN_LAMP_SHADOW` line for the renderer's last frame, or `undefined` on a renderer that keeps
|
|
3311
|
-
* no lamp counters (three's own).
|
|
3312
|
-
*
|
|
3313
|
-
* @situation log lamp shadow redraws and GPU time apart from the sun's on the owned engine
|
|
3314
|
-
* @constraint counters that do not add up to the frame's shadow draws throw TN_LAMP_SHADOW_INVALID
|
|
3315
|
-
* @example
|
|
3316
|
-
* const line = lampShadowMarker(renderer, frame);
|
|
3317
|
-
* if (line !== undefined) console.info(line);
|
|
3318
|
-
*/
|
|
3319
|
-
declare function lampShadowMarker(renderer: {
|
|
3320
|
-
readonly info?: {
|
|
3321
|
-
readonly engine?: {
|
|
3322
|
-
readonly shadows?: ILampShadowCounters;
|
|
3323
|
-
};
|
|
3324
|
-
};
|
|
3325
|
-
}, frame: number): string | undefined;
|
|
3326
|
-
/**
|
|
3327
|
-
* Parse a `TN_LAMP_SHADOW` line back into its stats, or `undefined`.
|
|
3328
|
-
*
|
|
3329
|
-
* @situation count lamp shadow redraws from a renderer log, for example a moving-caster run
|
|
3330
|
-
* @constraint non-marker lines and markers whose sun and lamp draws do not add up return `undefined`
|
|
3331
|
-
* @example
|
|
3332
|
-
* const stats = readLampShadowMarker(line);
|
|
3333
|
-
* if (stats !== undefined) console.log(stats.lamps.redraws);
|
|
3334
|
-
*/
|
|
3335
|
-
declare function readLampShadowMarker(line: string): ILampShadowStats | undefined;
|
|
3336
3323
|
|
|
3337
3324
|
declare module "three" {
|
|
3338
3325
|
interface Material {
|
|
@@ -3461,9 +3448,10 @@ declare function addFoliageBackLight(material: Material, backIrradiance: Node<"v
|
|
|
3461
3448
|
declare module "three" {
|
|
3462
3449
|
interface Material {
|
|
3463
3450
|
/**
|
|
3464
|
-
* Unreal's Substrate
|
|
3465
|
-
* standard or physical material with EON where three shades Lambert
|
|
3466
|
-
*
|
|
3451
|
+
* Unreal's Substrate slab as a fresh project compiles it (PRD-653, PRD-632): direct light shades the diffuse lobe
|
|
3452
|
+
* of a standard or physical material with EON where three shades Lambert, with no energy conservation (the diffuse
|
|
3453
|
+
* keeps the light three's Fresnel takes, the specular has no multi-scattering weight). The default is off.
|
|
3454
|
+
* Indirect light stays three's, and a material changed after its first draw needs `needsUpdate`.
|
|
3467
3455
|
*/
|
|
3468
3456
|
roughDiffuse?: boolean;
|
|
3469
3457
|
}
|
|
@@ -3568,617 +3556,6 @@ declare class Daylight extends Group implements IComputeDriven$1 {
|
|
|
3568
3556
|
detach(): void;
|
|
3569
3557
|
}
|
|
3570
3558
|
|
|
3571
|
-
interface IFilmicCurve {
|
|
3572
|
-
readonly slope: number;
|
|
3573
|
-
readonly toe: number;
|
|
3574
|
-
readonly shoulder: number;
|
|
3575
|
-
readonly blackClip: number;
|
|
3576
|
-
readonly whiteClip: number;
|
|
3577
|
-
readonly blueCorrection: number;
|
|
3578
|
-
/**
|
|
3579
|
-
* Unreal's "Expand Gamut" (1 in a fresh project, `Engine/Source/Runtime/Engine/Private/Scene.cpp:437`): bright,
|
|
3580
|
-
* saturated colour is pushed toward a wider gamut before the blue correction and the curve. 0 turns it off.
|
|
3581
|
-
* Unreal's linear EXR frames are taken after this step (`Engine/Shaders/Private/PostProcessCombineLUTs.usf`,
|
|
3582
|
-
* the expansion runs before the output-device branches), so a curve applied to an Unreal EXR needs 0 here.
|
|
3583
|
-
*/
|
|
3584
|
-
readonly expandGamut: number;
|
|
3585
|
-
/**
|
|
3586
|
-
* The ACES reference rendering's glow, which Unreal keeps in its filmic curve (`Engine/Shaders/Private/TonemapCommon.ush`):
|
|
3587
|
-
* dark, saturated colour gets up to 5% brighter. 1 is Unreal's amount, 0 turns it off.
|
|
3588
|
-
*/
|
|
3589
|
-
readonly glow: number;
|
|
3590
|
-
/**
|
|
3591
|
-
* The ACES reference rendering's red modifier, also in Unreal's filmic curve: the red of a saturated red is pulled
|
|
3592
|
-
* toward a dark pivot, up to 18%. 1 is Unreal's amount, 0 turns it off.
|
|
3593
|
-
*/
|
|
3594
|
-
readonly redModifier: number;
|
|
3595
|
-
/**
|
|
3596
|
-
* Output dither in 8-bit steps: triangular grain added to the display colour before the backbuffer rounds it.
|
|
3597
|
-
* Unreal 5.8.3 uses one step for an 8-bit backbuffer, so a dim gradient reads as grain of one level instead of
|
|
3598
|
-
* contour bands. 0 turns it off. Only the tone-mapping node dithers; `filmicToneMap()` stays noise-free.
|
|
3599
|
-
*/
|
|
3600
|
-
readonly dither: number;
|
|
3601
|
-
/**
|
|
3602
|
-
* The largest scene-linear value, after exposure, that one channel can hold when the colour goes into Unreal's
|
|
3603
|
-
* colour LUT (the top of its 14-stop log shaper, `Engine/Shaders/Private/GammaCorrectionCommon.ush`: `LogToLin(1)`
|
|
3604
|
-
* minus `LogToLin(0)`). A channel above it is clipped there, so the sun disc and a hot emitter lose their hue
|
|
3605
|
-
* earlier than an unbounded curve would. 0, the default, leaves the channel unbounded; pass `LUT_CLIP` for Unreal's.
|
|
3606
|
-
*/
|
|
3607
|
-
readonly lutClip: number;
|
|
3608
|
-
}
|
|
3609
|
-
/** Red, green, blue and a master factor, as Unreal's colour grading panel shows each control. */
|
|
3610
|
-
type Vec4$1 = readonly [number, number, number, number];
|
|
3611
|
-
/** One set of Unreal's colour grading controls. */
|
|
3612
|
-
interface IGradeControls {
|
|
3613
|
-
readonly saturation: Vec4$1;
|
|
3614
|
-
readonly contrast: Vec4$1;
|
|
3615
|
-
readonly gamma: Vec4$1;
|
|
3616
|
-
readonly gain: Vec4$1;
|
|
3617
|
-
readonly offset: Vec4$1;
|
|
3618
|
-
}
|
|
3619
|
-
/**
|
|
3620
|
-
* Unreal's colour grading and white balance, run in the combined LUT before the film curve
|
|
3621
|
-
* (`Engine/Shaders/Private/PostProcessCombineLUTs.usf:88-140` and `:369-403`; defaults in
|
|
3622
|
-
* `Engine/Source/Runtime/Engine/Private/Scene.cpp:405-433`). Every default below is Unreal's, and at the
|
|
3623
|
-
* defaults none of it costs a shader instruction.
|
|
3624
|
-
*/
|
|
3625
|
-
interface IColorGrade {
|
|
3626
|
-
/** Kelvin, 1500 to 15000. 6500 with tint 0 is a no-op. */
|
|
3627
|
-
readonly whiteTemp: number;
|
|
3628
|
-
/** -1 to 1 along the isotherm. */
|
|
3629
|
-
readonly whiteTint: number;
|
|
3630
|
-
/**
|
|
3631
|
-
* `"whiteBalance"`: the temperature is the light the scene was lit by, and it turns neutral.
|
|
3632
|
-
* `"colorTemperature"`: neutral turns into that temperature.
|
|
3633
|
-
*/
|
|
3634
|
-
readonly temperatureMode: "whiteBalance" | "colorTemperature";
|
|
3635
|
-
/** 1 is the full film curve, 0 the graded colour with no curve. */
|
|
3636
|
-
readonly toneCurveAmount: number;
|
|
3637
|
-
/** Applied to every pixel, and combined with each range below. */
|
|
3638
|
-
readonly global: IGradeControls;
|
|
3639
|
-
readonly shadows: IGradeControls;
|
|
3640
|
-
readonly midtones: IGradeControls;
|
|
3641
|
-
readonly highlights: IGradeControls;
|
|
3642
|
-
/** Luma (AP1) up to which the shadows range has full weight, fading out by here. */
|
|
3643
|
-
readonly shadowsMax: number;
|
|
3644
|
-
/** Luma where the highlights range starts and where it has full weight. */
|
|
3645
|
-
readonly highlightsMin: number;
|
|
3646
|
-
readonly highlightsMax: number;
|
|
3647
|
-
}
|
|
3648
|
-
type RangeName = "global" | "shadows" | "midtones" | "highlights";
|
|
3649
|
-
/** What a game passes: any field, and any control of a range. */
|
|
3650
|
-
type ColorGradeOptions = {
|
|
3651
|
-
readonly [K in keyof IColorGrade]?: K extends RangeName ? Partial<IGradeControls> : IColorGrade[K];
|
|
3652
|
-
};
|
|
3653
|
-
/**
|
|
3654
|
-
* Registers the curve with a WebGPU renderer and returns the tone-mapping constant to assign.
|
|
3655
|
-
* A renderer without a node library (the WebGL fallback) keeps ACES and says so.
|
|
3656
|
-
*/
|
|
3657
|
-
declare function installFilmicToneMapping(raw: unknown, c?: IFilmicCurve, grade?: IColorGrade): number | undefined;
|
|
3658
|
-
|
|
3659
|
-
interface IExposureSettings {
|
|
3660
|
-
enabled: boolean;
|
|
3661
|
-
/** Middle-grey target; increase to brighten the metered subject. */
|
|
3662
|
-
key: number;
|
|
3663
|
-
/** Exposure limits in stops. Expand only if the scene needs more range. */
|
|
3664
|
-
minStops: number;
|
|
3665
|
-
maxStops: number;
|
|
3666
|
-
/**
|
|
3667
|
-
* Percent of metered weight, dark to bright, ignored at each end of the histogram.
|
|
3668
|
-
* Raise highPercent's gap (lower it) when a large bright backdrop still sets the exposure.
|
|
3669
|
-
*/
|
|
3670
|
-
lowPercent: number;
|
|
3671
|
-
highPercent: number;
|
|
3672
|
-
/** Exponential response per second in log2 space. Up opens the eye; down squints. */
|
|
3673
|
-
rateUp: number;
|
|
3674
|
-
rateDown: number;
|
|
3675
|
-
/** Stop error where cut acceleration begins / reaches its authored maximum. */
|
|
3676
|
-
snapLo: number;
|
|
3677
|
-
snapHi: number;
|
|
3678
|
-
snapGain: number;
|
|
3679
|
-
/**
|
|
3680
|
-
* Seed for reset(value). The first frame and reset() without a value adopt the measured target.
|
|
3681
|
-
*/
|
|
3682
|
-
initialExposure: number;
|
|
3683
|
-
settleStops: number;
|
|
3684
|
-
/**
|
|
3685
|
-
* Limit catch-up after a suspended frame, avoiding an unrequested cut. A frame the renderer's
|
|
3686
|
-
* gate declined is not a suspension: the drawn frame already spans that time, so it is spent.
|
|
3687
|
-
*/
|
|
3688
|
-
maxDelta: number;
|
|
3689
|
-
/** Readback/marker cadence in seconds. Metering still runs on every drawn frame. */
|
|
3690
|
-
reportInterval: number;
|
|
3691
|
-
}
|
|
3692
|
-
declare const exposureSettings: Readonly<IExposureSettings>;
|
|
3693
|
-
|
|
3694
|
-
type ColourTexture = TextureNode;
|
|
3695
|
-
type Meter = (colour: Node<"vec4">, uv: Node<"vec2">) => Node<"vec2">;
|
|
3696
|
-
type Decode = (mean: Node<"float">) => Node<"float">;
|
|
3697
|
-
|
|
3698
|
-
/** Owns scratch targets only. Never draws the world or installs another output transform. */
|
|
3699
|
-
declare class AutoExposureNode extends Node<"float"> {
|
|
3700
|
-
#private;
|
|
3701
|
-
static get type(): string;
|
|
3702
|
-
readonly input: ColourTexture;
|
|
3703
|
-
readonly settings: Readonly<IExposureSettings>;
|
|
3704
|
-
constructor(input: ColourTexture, settings: IExposureSettings, constantExposure: number, meter?: Meter, decode?: Decode);
|
|
3705
|
-
setup(builder: NodeBuilder): Node<"float">;
|
|
3706
|
-
get exposureNode(): Node<"float">;
|
|
3707
|
-
reset(exposure?: number): void;
|
|
3708
|
-
setEnabled(enabled: boolean): void;
|
|
3709
|
-
/**
|
|
3710
|
-
* Exposure compensation in stops over the metered key, live: Unreal's AutoExposureBias
|
|
3711
|
-
* (UE 5.8.3: Engine/Source/Runtime/Engine/Classes/Engine/Scene.h:1933), which post-process
|
|
3712
|
-
* volumes blend at run time. Unreal applies 2^bias outside the smoothing
|
|
3713
|
-
* (Engine/Shaders/Private/PostProcessEyeAdaptation.usf:179); here it moves the goal, so a change
|
|
3714
|
-
* adapts at `rateUp`/`rateDown` and the reported exposure includes it.
|
|
3715
|
-
*/
|
|
3716
|
-
setExposureBias(stops: number): void;
|
|
3717
|
-
getObservation(): Record<string, unknown>;
|
|
3718
|
-
updateBefore(frame: NodeFrame): undefined;
|
|
3719
|
-
dispose(): void;
|
|
3720
|
-
}
|
|
3721
|
-
|
|
3722
|
-
/** Godot's `Viewport.screen_space_aa`: which post-process antialiasing smooths the frame's edges. */
|
|
3723
|
-
type ScreenSpaceAA = "smaa" | "fxaa" | "disabled";
|
|
3724
|
-
/**
|
|
3725
|
-
* Godot's `Environment.tonemap_mode`: the modes Three.js ships, plus `filmic`, the Unreal 5
|
|
3726
|
-
* default curve written in `tonemap.ts`.
|
|
3727
|
-
*/
|
|
3728
|
-
type TonemapMode = "aces" | "agx" | "filmic" | "neutral";
|
|
3729
|
-
/**
|
|
3730
|
-
* SSGI sample budget. The three tiers are the presets SSGINode's own documentation
|
|
3731
|
-
* recommends for the temporally-filtered case, not numbers invented here. An unknown
|
|
3732
|
-
* tier throws rather than quietly becoming the default.
|
|
3733
|
-
*/
|
|
3734
|
-
type SsgiQuality = "low" | "medium" | "high" | "epic";
|
|
3735
|
-
interface IWorldEnvironmentOptions {
|
|
3736
|
-
/** World-pass MSAA samples. Omit to inherit the renderer; 0 leaves post AA in charge. */
|
|
3737
|
-
readonly samples?: number;
|
|
3738
|
-
/**
|
|
3739
|
-
* How bounce light reaches a pixel, Unreal's `r.Lumen.FinalGatherMethod` by the quality tier's name
|
|
3740
|
-
* (`giPreset`). The screen-space gather runs only for `screenProbeGather`; the world cache is
|
|
3741
|
-
* installed by the scene (`giCache.ts`) for `irradianceField` and `screenProbeGather`. Omit it and
|
|
3742
|
-
* the harness layer decides.
|
|
3743
|
-
*/
|
|
3744
|
-
readonly finalGatherMethod?: "none" | "irradianceField" | "screenProbeGather";
|
|
3745
|
-
/** Screen-space indirect diffuse light. Godot calls this `ssil_enabled`. */
|
|
3746
|
-
readonly ssgiEnabled?: boolean;
|
|
3747
|
-
readonly ssgiQuality?: SsgiQuality;
|
|
3748
|
-
/** How much of the gathered indirect light reaches the frame. Godot's `ssil_intensity`. */
|
|
3749
|
-
readonly ssgiIntensity?: number;
|
|
3750
|
-
/** How far, in world units, indirect light is gathered from. Room scale, not contact scale. */
|
|
3751
|
-
readonly ssgiRadius?: number;
|
|
3752
|
-
/** Screen-space reflections. Godot's `ssr_enabled`. */
|
|
3753
|
-
readonly ssrEnabled?: boolean;
|
|
3754
|
-
/**
|
|
3755
|
-
* How far, in world units, a reflection ray is traced.
|
|
3756
|
-
*
|
|
3757
|
-
* `SSRNode` defaults this to **1**, which is one metre. On any scene larger than a
|
|
3758
|
-
* tabletop that reads as "screen-space reflections are on and do nothing" — the ray
|
|
3759
|
-
* terminates before it reaches the thing that should be standing in the floor.
|
|
3760
|
-
*/
|
|
3761
|
-
readonly ssrMaxDistance?: number;
|
|
3762
|
-
/**
|
|
3763
|
-
* Fraction of the display resolution the reflection is traced at.
|
|
3764
|
-
*
|
|
3765
|
-
* A reflection in a rough surface carries almost no high-frequency detail, so tracing it
|
|
3766
|
-
* at half resolution costs a quarter of the rays and is very hard to see in the result.
|
|
3767
|
-
*/
|
|
3768
|
-
readonly ssrResolutionScale?: number;
|
|
3769
|
-
/**
|
|
3770
|
-
* The most steps one reflection ray marches. Defaults to Unreal's count for the render chain
|
|
3771
|
-
* tier (`RENDER_CHAIN_TIERS`: 32 on high, 16 on medium, 8 on low). Fewer steps cost less and
|
|
3772
|
-
* step over thin objects sooner.
|
|
3773
|
-
*/
|
|
3774
|
-
readonly ssrMaxSteps?: number;
|
|
3775
|
-
/** Spatial denoise over the SSGI result. Off is noisier and cheaper. */
|
|
3776
|
-
readonly denoiseEnabled?: boolean;
|
|
3777
|
-
/** The SSGI denoise's reach in gather pixels; omit for DenoiseNode's 5. A half-resolution gather wants more. */
|
|
3778
|
-
readonly ssgiDenoiseRadius?: number;
|
|
3779
|
-
/**
|
|
3780
|
-
* Gather the SSGI with screen probes (one per 16 x 16 pixels, an 8 x 8 octahedron of rays each) instead of per-pixel
|
|
3781
|
-
* rays: Unreal's ScreenProbeGather at its Epic settings (PRD-640). Owned engine only; elsewhere the per-pixel gather runs.
|
|
3782
|
-
*/
|
|
3783
|
-
readonly ssgiScreenProbes?: boolean;
|
|
3784
|
-
/** Shows one lighting term alone (`GIVisualize`); `off` draws the finished frame. Needs the gather (`ssgiEnabled`). */
|
|
3785
|
-
readonly giVisualize?: GIVisualizeMode;
|
|
3786
|
-
/** Screen probes only: 0 keeps every probe's rays on the same octahedron, 1 (default) offsets them per probe. */
|
|
3787
|
-
readonly ssgiProbeJitter?: number;
|
|
3788
|
-
/** Screen probes only: rays on a side of each probe's octahedron. Omit for 8 (Unreal's real-time Epic; its cinematic setting is 16). */
|
|
3789
|
-
readonly ssgiProbeRays?: number;
|
|
3790
|
-
/** Screen probes only, diagnosis: 1 draws the probes' weight and trust, 2 the sign of the gathered delta. */
|
|
3791
|
-
readonly ssgiProbeDebug?: number;
|
|
3792
|
-
/**
|
|
3793
|
-
* Diagnosis, owned engine only: label one pass group as the `SSGI` GPU stage and leave the others in the frame, so
|
|
3794
|
-
* `info.engine.gpuStages.SSGI` times that group alone (`trace`, `filter`, `gather` of the screen probes, or the chain's
|
|
3795
|
-
* `denoise`). Omit to time every GI pass.
|
|
3796
|
-
*/
|
|
3797
|
-
readonly ssgiTimedPass?: "trace" | "filter" | "gather" | "denoise";
|
|
3798
|
-
/**
|
|
3799
|
-
* Denoise passes over the SSGI gather, each turning the tap pattern by its index. The default is the render chain
|
|
3800
|
-
* tier's `denoiseIterations` (high 3, medium 2, low 1): one pass left the sunlit room's walls grainy at `high`.
|
|
3801
|
-
*/
|
|
3802
|
-
readonly giDenoisePasses?: number;
|
|
3803
|
-
/** Raymarched shafts. Needs `godraysLight`, and that light must cast shadows. */
|
|
3804
|
-
readonly godraysEnabled?: boolean;
|
|
3805
|
-
/** How dense the participating medium is. Higher is foggier — and the whole frame brighter. */
|
|
3806
|
-
readonly godraysDensity?: number;
|
|
3807
|
-
/**
|
|
3808
|
-
* Haze below this value is discarded instead of added to the frame.
|
|
3809
|
-
*
|
|
3810
|
-
* Without it the pass is a uniform brightener rather than a shaft renderer: it returns a
|
|
3811
|
-
* non-zero value for nearly every pixel, and that "something" is tiny in linear space and
|
|
3812
|
-
* enormous after the tone curve, which lifts shadows hardest. Subtracting a floor keeps
|
|
3813
|
-
* the air inside a real beam and discards the ambient lift.
|
|
3814
|
-
*/
|
|
3815
|
-
readonly godraysFloor?: number;
|
|
3816
|
-
/** Multiplier applied after the floor, so beams can be bright without the haze returning. */
|
|
3817
|
-
readonly godraysIntensity?: number;
|
|
3818
|
-
/**
|
|
3819
|
-
* Raymarch steps per pixel. `GodraysNode` defaults to 60.
|
|
3820
|
-
*
|
|
3821
|
-
* Every step is a shadow-map sample, so this multiplies directly into the cost of the
|
|
3822
|
-
* whole pass. The pass jitters its sample positions, so a lower count trades a hard shaft
|
|
3823
|
-
* edge for a slightly noisier one rather than for banding — which the denoiser then
|
|
3824
|
-
* largely absorbs.
|
|
3825
|
-
*/
|
|
3826
|
-
readonly godraysSteps?: number;
|
|
3827
|
-
/**
|
|
3828
|
-
* Ceiling on shaft brightness.
|
|
3829
|
-
*
|
|
3830
|
-
* This is also the single strongest control over how bright the *whole* scene looks: the
|
|
3831
|
-
* pass adds its accumulated illumination to every pixel, not only to the pixels inside a
|
|
3832
|
-
* visible beam, so raising it raises the shadow floor of the entire frame.
|
|
3833
|
-
*/
|
|
3834
|
-
readonly godraysMaxDensity?: number;
|
|
3835
|
-
/**
|
|
3836
|
-
* Ground-truth ambient occlusion, at contact scale. Godot's `ssao_enabled`.
|
|
3837
|
-
*
|
|
3838
|
-
* Deliberately a *second* occlusion term next to the one SSGI already produces. SSGI's AO
|
|
3839
|
-
* is gathered over `ssgiRadius` — metres — the right scale for "this hall is enclosed"
|
|
3840
|
-
* and the wrong one for "this foot is standing on this floor". This pass runs at a radius
|
|
3841
|
-
* of centimetres and multiplies on top.
|
|
3842
|
-
*/
|
|
3843
|
-
readonly gtaoEnabled?: boolean;
|
|
3844
|
-
/**
|
|
3845
|
-
* Occlusion gather radius in world units, a named override. Left out, the radius follows Unreal's rule
|
|
3846
|
-
* instead: a fixed reach on the screen (`gtaoReachPx`), so a contact is as wide at any distance.
|
|
3847
|
-
*/
|
|
3848
|
-
readonly gtaoRadius?: number;
|
|
3849
|
-
/** Screen reach of the occlusion in pixels at the display height when `gtaoRadius` is not set. Unreal's is 32. */
|
|
3850
|
-
readonly gtaoReachPx?: number;
|
|
3851
|
-
/** Exponent on the occlusion term: higher is a darker, tighter contact. */
|
|
3852
|
-
readonly gtaoScale?: number;
|
|
3853
|
-
/** Directions sampled per pixel. Cost is linear in this. */
|
|
3854
|
-
readonly gtaoSamples?: number;
|
|
3855
|
-
/** Spacing of the samples along a direction: 1 is even, 2 packs them near the pixel, as Unreal's horizon search does. */
|
|
3856
|
-
readonly gtaoDistanceExponent?: number;
|
|
3857
|
-
/** 0 weighs every sample alike, 1 (the node's default) weighs far samples less. */
|
|
3858
|
-
readonly gtaoDistanceFalloff?: number;
|
|
3859
|
-
/** Depth difference in world units beyond which a sample is no occluder. */
|
|
3860
|
-
readonly gtaoThickness?: number;
|
|
3861
|
-
/** The occlusion denoise's reach in pixels (DenoiseNode's 5 when omitted); 0 leaves the occlusion raw. */
|
|
3862
|
-
readonly gtaoDenoiseRadius?: number;
|
|
3863
|
-
/**
|
|
3864
|
-
* The albedo cap of the occlusion's multi-bounce: pale surfaces keep more of the light a crease blocks. Unreal's is
|
|
3865
|
-
* 0.5 (`MaxMultibounceAlbedo`); 0 leaves the occlusion as GTAO computed it. Applies where the cache holds the
|
|
3866
|
-
* indirect light.
|
|
3867
|
-
*/
|
|
3868
|
-
readonly gtaoMultiBounceAlbedo?: number;
|
|
3869
|
-
/**
|
|
3870
|
-
* Where the cache holds the indirect light, only that share takes the occlusion (Unreal's AO darkens indirect light
|
|
3871
|
-
* only). `false` is the named override: the whole frame takes the occlusion, as an engine without a cache does.
|
|
3872
|
-
*/
|
|
3873
|
-
readonly gtaoIndirectOnly?: boolean;
|
|
3874
|
-
/** Fraction of display resolution the occlusion is traced at. */
|
|
3875
|
-
readonly gtaoResolutionScale?: number;
|
|
3876
|
-
/**
|
|
3877
|
-
* The fraction of the frame SSGI actually gathers at. Half by default.
|
|
3878
|
-
*
|
|
3879
|
-
* `GTAONode` and `SSRNode` both carry a `resolutionScale` of their own; **`SSGINode` does not**,
|
|
3880
|
-
* and its `setSize` passes width and height straight into its render target with no factor. So
|
|
3881
|
-
* screen-space GI — a low-frequency effect every production renderer gathers at half or quarter
|
|
3882
|
-
* res — was the only stage in this chain running at full resolution, and it cost accordingly.
|
|
3883
|
-
*
|
|
3884
|
-
* Measured on a 46,190-instance forest at 1600x900 on an RTX 2080, with the resolution scaler
|
|
3885
|
-
* left on auto so the engine's own verdict is part of the result:
|
|
3886
|
-
*
|
|
3887
|
-
* fps still/walk scale it settled on interior median dead shadow
|
|
3888
|
-
* full res 38.0 / 47.2 0.44 704x396 0.0299 19.19%
|
|
3889
|
-
* off 60.0 / 60.0 0.61 976x549 0.0987 4.54%
|
|
3890
|
-
* half res 59.8 / 60.0 0.72 1152x648 0.0301 18.58%
|
|
3891
|
-
*
|
|
3892
|
-
* Half res is better than both: it holds the budget like switching SSGI off, keeps the look
|
|
3893
|
-
* within noise of full res, and produces the *sharpest* frame of the three — because the budget
|
|
3894
|
-
* it hands back is spent by the scaler on pixels rather than on a gather nobody can see at full
|
|
3895
|
-
* rate. Full-res SSGI was not buying quality, it was trading it.
|
|
3896
|
-
*
|
|
3897
|
-
* Fixed without touching three: `setSize` is public and the pass drives the node through it with
|
|
3898
|
-
* the full frame size, so the instance is wrapped to hand it a smaller one. The node's own maths
|
|
3899
|
-
* reads the `_resolution` uniform that `setSize` writes, so it stays self-consistent, and the
|
|
3900
|
-
* result is sampled by UV rather than by texel — which is what makes the upsample free and is
|
|
3901
|
-
* exactly the mechanism `GTAONode` uses internally.
|
|
3902
|
-
*/
|
|
3903
|
-
readonly ssgiResolutionScale?: number;
|
|
3904
|
-
/**
|
|
3905
|
-
* Contrast-adaptive sharpening (RCAS) over the finished frame.
|
|
3906
|
-
*
|
|
3907
|
-
* Everything upstream of it blurs: the GI gather is denoised, the reflection is traced at
|
|
3908
|
-
* reduced resolution and roughness-blurred. Each is worth its softness on its own and the
|
|
3909
|
-
* sum is a frame with no micro-detail left. RCAS is contrast-adaptive, so it puts the
|
|
3910
|
-
* edges back without ringing the soft areas.
|
|
3911
|
-
*/
|
|
3912
|
-
readonly sharpenEnabled?: boolean;
|
|
3913
|
-
/** RCAS sharpness. **0 is maximum sharpening and 2 is none** — it is a radius, not a gain. */
|
|
3914
|
-
readonly sharpenStrength?: number;
|
|
3915
|
-
/** Unreal's VignetteIntensity (Scene.cpp default 0.4), the cosine-fourth law. Zero disables it. */
|
|
3916
|
-
readonly vignetteAmount?: number;
|
|
3917
|
-
/** Unreal's default motion blur on the velocity the render chain provisions (harness overlay). */
|
|
3918
|
-
readonly motionBlurEnabled?: boolean;
|
|
3919
|
-
/**
|
|
3920
|
-
* Post-process antialiasing, run last. Godot's `Viewport.screen_space_aa`. Default `"smaa"`.
|
|
3921
|
-
*
|
|
3922
|
-
* Not optional in practice: the chain renders `pass(scene, camera)` single-sampled, so the moment
|
|
3923
|
-
* any stage runs, the renderer's own multisampling no longer reaches the frame and every edge
|
|
3924
|
-
* stairsteps — the single loudest "this is a prototype" signal in a frame. It is requested only
|
|
3925
|
-
* when some other stage (or a `baseColour`) installs a chain; with nothing installed the renderer
|
|
3926
|
-
* draws straight to the canvas with its own MSAA and this would be paying twice.
|
|
3927
|
-
*/
|
|
3928
|
-
readonly screenSpaceAA?: ScreenSpaceAA;
|
|
3929
|
-
/**
|
|
3930
|
-
* Temporal antialiasing, Unreal's default method (`r.AntiAliasingMethod` 4, temporal super resolution). Default `false`
|
|
3931
|
-
* here, and `true` in the `high` and `medium` tiers of `quality.ts`.
|
|
3932
|
-
*
|
|
3933
|
-
* The engine jitters the camera by a sub-pixel offset every frame, draws each pixel's motion, and blends the frames
|
|
3934
|
-
* before it into this one. The `traa` stage resolves the finished frame, after the screen-space stages (occlusion,
|
|
3935
|
-
* global illumination, reflections) and ahead of blur, bloom and the grade, so their edges are smoothed with the rest.
|
|
3936
|
-
* It replaces `screenSpaceAA` while it runs: Unreal runs one method too. It runs on the owned engine only. On
|
|
3937
|
-
* `engine: "threejs"` and on a fallback renderer this option is refused with a reason in the applied report and
|
|
3938
|
-
* `screenSpaceAA` stays in charge. Read `debug().temporal` for the live frame, history and jitter.
|
|
3939
|
-
*/
|
|
3940
|
-
readonly temporalAA?: boolean;
|
|
3941
|
-
/** Godot's `glow_enabled`. */
|
|
3942
|
-
readonly bloomEnabled?: boolean;
|
|
3943
|
-
readonly bloomStrength?: number;
|
|
3944
|
-
/** How far a bright pixel bleeds, as a fraction of the screen. */
|
|
3945
|
-
readonly bloomRadius?: number;
|
|
3946
|
-
/** Luminance a pixel must exceed before it blooms at all. */
|
|
3947
|
-
readonly bloomThreshold?: number;
|
|
3948
|
-
/**
|
|
3949
|
-
* Which of this kit's authored stages to run.
|
|
3950
|
-
*
|
|
3951
|
-
* Separate from the graph below, and not for tidiness: the chain has to know whether anything
|
|
3952
|
-
* was requested at all before the scene pass exists — with nothing requested it sets an
|
|
3953
|
-
* exposure and returns, and no pass is ever built. So the request is a static decision the kit
|
|
3954
|
-
* makes from its own config, and only the graph needs the pass.
|
|
3955
|
-
*/
|
|
3956
|
-
readonly authoredStageNames?: readonly string[];
|
|
3957
|
-
/**
|
|
3958
|
-
* This kit's own stages, composed after the built-ins.
|
|
3959
|
-
*
|
|
3960
|
-
* A factory because an authored stage needs the two things only this file can produce: the
|
|
3961
|
-
* scene pass's depth texture node, which does not exist until the pass is built, and the
|
|
3962
|
-
* resolved tier. It returns the complete graph — including stages left dormant this frame — so
|
|
3963
|
-
* that an anchor like `watercolor after kuwahara` keeps naming a stage that exists.
|
|
3964
|
-
*
|
|
3965
|
-
* Naming specific stages here instead — an `outlineEnabled`, a `kuwaharaRadius` — is what put
|
|
3966
|
-
* one kit's look inside the plumbing every kit copies verbatim, which
|
|
3967
|
-
* `shared-render-sources.spec.ts` exists to refuse.
|
|
3968
|
-
*/
|
|
3969
|
-
readonly authoredStages?: (context: IWorldEnvironmentStageContext) => readonly ChainStage[];
|
|
3970
|
-
/** Quality tier passed to the measured chain; the quality module owns this value. */
|
|
3971
|
-
readonly renderChainTier?: ChainTier;
|
|
3972
|
-
readonly tonemapMode?: TonemapMode;
|
|
3973
|
-
/**
|
|
3974
|
-
* The numbers of the `"filmic"` curve, any field of `IFilmicCurve` (slope, toe, shoulder, black clip, white
|
|
3975
|
-
* clip, blue correction, expand gamut, glow, red modifier, dither, lutClip). Unreal 5.8.3's project defaults
|
|
3976
|
-
* apply to every field left out. Only `tonemapMode: "filmic"` reads it; any other mode with this set throws.
|
|
3977
|
-
*/
|
|
3978
|
-
readonly filmicCurve?: Partial<IFilmicCurve>;
|
|
3979
|
-
/**
|
|
3980
|
-
* Unreal's colour grade and white balance for `"filmic"`: saturation, contrast, gamma, gain and offset
|
|
3981
|
-
* (`[red, green, blue, master]`) for the whole frame and for `shadows`, `midtones` and `highlights`, the
|
|
3982
|
-
* luma limits, `whiteTemp` and `whiteTint` in Kelvin and -1 to 1, and `toneCurveAmount`. Left out, the grade
|
|
3983
|
-
* is neutral and costs no shader instruction. Only `tonemapMode: "filmic"` reads it.
|
|
3984
|
-
*/
|
|
3985
|
-
readonly colorGrade?: ColorGradeOptions;
|
|
3986
|
-
/**
|
|
3987
|
-
* Scene-referred exposure: multiplied into the scene pass **before** the tone curve, so
|
|
3988
|
-
* the GI gather, reflections and bloom threshold all see the exposed image and the bloom
|
|
3989
|
-
* threshold means the same thing at any exposure.
|
|
3990
|
-
*
|
|
3991
|
-
* `renderer.toneMappingExposure` is live too (measured on three@0.185.1 — see
|
|
3992
|
-
* `docs/verification/exposure-ab-2026-08-30.md`), and applies at the same point in the
|
|
3993
|
-
* graph, but only when no output node is installed. When every stage here is off, this
|
|
3994
|
-
* class falls back to that scalar; when any stage runs, this multiply is the shutter.
|
|
3995
|
-
*/
|
|
3996
|
-
readonly exposure?: number;
|
|
3997
|
-
/** Cost opt-in. False retains the direct constant-exposure path. */
|
|
3998
|
-
readonly autoExposureEnabled?: boolean;
|
|
3999
|
-
/** Unreal's bilateral local exposure on top of the automatic exposure (harness overlay). */
|
|
4000
|
-
readonly localExposureEnabled?: boolean;
|
|
4001
|
-
/** Unreal's standard bloom in place of the stock bloom stage (harness overlay). */
|
|
4002
|
-
readonly unrealBloomEnabled?: boolean;
|
|
4003
|
-
/** Editable game policy; disabled application still measures when cost is opted in. */
|
|
4004
|
-
readonly exposurePolicy?: Readonly<IExposureSettings>;
|
|
4005
|
-
}
|
|
4006
|
-
interface IWorldEnvironmentTarget {
|
|
4007
|
-
/** The directional light godrays are raymarched against. Required only by `godraysEnabled`. */
|
|
4008
|
-
readonly godraysLight?: DirectionalLight;
|
|
4009
|
-
/**
|
|
4010
|
-
* Composes the colour the chain starts from, given the scene pass it renders.
|
|
4011
|
-
*
|
|
4012
|
-
* The chain builds `pass(scene, camera)` itself, so a game that composes something onto the
|
|
4013
|
-
* beauty pass before any stage runs — aerial perspective, read against that pass's own view-Z,
|
|
4014
|
-
* is the one in these templates — has nowhere else to put it. The node returned here is the
|
|
4015
|
-
* game's; the chain only decides where it is spliced in, which is first, ahead of exposure and
|
|
4016
|
-
* every stage.
|
|
4017
|
-
*/
|
|
4018
|
-
readonly baseColour?: (scenePass: ReturnType<typeof pass>) => Node<"vec4">;
|
|
4019
|
-
/**
|
|
4020
|
-
* The scene's static triangles, for the `ssr` stage: a smooth surface (roughness under the trace's
|
|
4021
|
-
* `maxRoughnessToTrace`) then reflects what its ray hits in the scene, as Unreal's Lumen reflections do,
|
|
4022
|
-
* not only what the screen drew. Build it after the static scene exists; omit it and the stage marches the screen.
|
|
4023
|
-
* @alias Lumen reflections, hit lighting, reflection rays
|
|
4024
|
-
*/
|
|
4025
|
-
readonly reflectionTrace?: TracedReflections;
|
|
4026
|
-
}
|
|
4027
|
-
type ResolutionSubrectView = {
|
|
4028
|
-
readonly viewFraction: Vector2;
|
|
4029
|
-
readonly halfTexel: Vector2;
|
|
4030
|
-
};
|
|
4031
|
-
/**
|
|
4032
|
-
* The scene pass's depth texture, as the pass itself types it.
|
|
4033
|
-
*
|
|
4034
|
-
* Named through `pass()` rather than written out because the addon's return type is the only
|
|
4035
|
-
* honest spelling of it, and a hand-written alias here would drift the first time three changes it.
|
|
4036
|
-
*/
|
|
4037
|
-
type DepthTextureNode = ReturnType<ReturnType<typeof pass>["getTextureNode"]>;
|
|
4038
|
-
type ChainTier = "high" | "medium" | "low" | "off";
|
|
4039
|
-
type ChainContext = {
|
|
4040
|
-
readonly tier: ChainTier;
|
|
4041
|
-
readonly resolutionSubrect?: ResolutionSubrectView;
|
|
4042
|
-
/**
|
|
4043
|
-
* The sampled velocity texture, present only when this chain request provisioned one.
|
|
4044
|
-
*
|
|
4045
|
-
* Distinct from the accessor TRAANode wants: the chain passes the texture here and installs the
|
|
4046
|
-
* accessor on the graph separately, so a stage that handed this node over as the accessor would
|
|
4047
|
-
* sample a texture that no fragment stage writes.
|
|
4048
|
-
*/
|
|
4049
|
-
readonly velocityNode?: Node;
|
|
4050
|
-
};
|
|
4051
|
-
/**
|
|
4052
|
-
* What a kit's `authoredStages` factory is handed. The depth node is the scene pass's, so a
|
|
4053
|
-
* stage that reads depth gets the same texture the built-in stages read rather than its own.
|
|
4054
|
-
*/
|
|
4055
|
-
interface IWorldEnvironmentStageContext {
|
|
4056
|
-
readonly depthNode: DepthTextureNode;
|
|
4057
|
-
readonly tier: ChainTier;
|
|
4058
|
-
/** The camera the scene pass renders with, which is the one a temporal stage must jitter. */
|
|
4059
|
-
readonly camera: Camera;
|
|
4060
|
-
}
|
|
4061
|
-
type ChainStage = {
|
|
4062
|
-
readonly name: string;
|
|
4063
|
-
readonly supportsResolutionSubrect?: boolean;
|
|
4064
|
-
readonly before?: string;
|
|
4065
|
-
readonly after?: string;
|
|
4066
|
-
/**
|
|
4067
|
-
* This stage reads display-referred colour — tone-mapped and sRGB-encoded — so the chain
|
|
4068
|
-
* installs the graph with the renderer's automatic output transform switched off and the stage
|
|
4069
|
-
* applies that transform itself (`renderOutput` from `three/tsl`).
|
|
4070
|
-
*
|
|
4071
|
-
* For effects authored against the picture rather than against light: a `.cube` table, an
|
|
4072
|
-
* sRGB-space edge filter. Such a stage runs last and may not declare an anchor, and the chain
|
|
4073
|
-
* only hands the renderer its transform back when the stage was actually refused.
|
|
4074
|
-
*/
|
|
4075
|
-
readonly afterOutputTransform?: boolean;
|
|
4076
|
-
readonly available?: (context: ChainContext) => boolean | string;
|
|
4077
|
-
readonly dispose?: () => void;
|
|
4078
|
-
readonly minimumTier?: ChainTier;
|
|
4079
|
-
/**
|
|
4080
|
-
* A temporal stage's completed rejection measurement. Its shape is the engine's velocity
|
|
4081
|
-
* contract, restated here so this file keeps importing nothing, and it is asked once per frame
|
|
4082
|
-
* after rendering. A stage that has not built, or has nothing landed yet, answers `undefined` —
|
|
4083
|
-
* which the chain reports as absent rather than as zero.
|
|
4084
|
-
*/
|
|
4085
|
-
readonly rejectionMeasurement?: () => {
|
|
4086
|
-
frame: number;
|
|
4087
|
-
rejectionFraction: number;
|
|
4088
|
-
} | undefined;
|
|
4089
|
-
/** The chain plumbing is stage-agnostic, so it names the node it carries `unknown`. */
|
|
4090
|
-
readonly build: (input: unknown, context: ChainContext) => unknown;
|
|
4091
|
-
};
|
|
4092
|
-
type OutputInstallation = {
|
|
4093
|
-
isCurrent(): boolean;
|
|
4094
|
-
dispose(): void;
|
|
4095
|
-
};
|
|
4096
|
-
type ResolutionSubrectTarget = {
|
|
4097
|
-
setSize(width: number, height: number, depth?: number): void;
|
|
4098
|
-
};
|
|
4099
|
-
type ResolutionSubrectController = {
|
|
4100
|
-
readonly active?: boolean;
|
|
4101
|
-
readonly view?: ResolutionSubrectView;
|
|
4102
|
-
retain(node: ResolutionSubrectTarget, targets: readonly RenderTarget[]): void;
|
|
4103
|
-
release(node: ResolutionSubrectTarget): void;
|
|
4104
|
-
textureView(texture: Texture): ResolutionSubrectView | undefined;
|
|
4105
|
-
dispose(): void;
|
|
4106
|
-
};
|
|
4107
|
-
type OutputSetter = ((node: unknown, worldPass?: unknown) => void) | ((node: unknown, worldPass?: unknown) => OutputInstallation);
|
|
4108
|
-
type OutputRenderer = {
|
|
4109
|
-
kind: string;
|
|
4110
|
-
raw: unknown;
|
|
4111
|
-
createResolutionSubrect?: () => ResolutionSubrectController;
|
|
4112
|
-
/**
|
|
4113
|
-
* Installs a node graph directly. Only reached when a `baseColour` is composed and every
|
|
4114
|
-
* stage is off: the chain installs nothing for an empty stage list, and dropping the game's
|
|
4115
|
-
* own composition on the floor would be the silent no-op this class exists to prevent.
|
|
4116
|
-
*/
|
|
4117
|
-
setOutputNode?: OutputSetter;
|
|
4118
|
-
/** Legacy node-only clear. The returned receipt distinguishes same-node reinstalls. */
|
|
4119
|
-
clearOutputNode?: (expectedNode?: unknown) => void;
|
|
4120
|
-
createRenderChain?: (options: {
|
|
4121
|
-
input?: unknown;
|
|
4122
|
-
worldPass?: unknown;
|
|
4123
|
-
request?: {
|
|
4124
|
-
stages?: readonly string[];
|
|
4125
|
-
tier?: ChainContext["tier"];
|
|
4126
|
-
/**
|
|
4127
|
-
* The scene pass that owns the shared velocity output, for a temporal stage to read. Its
|
|
4128
|
-
* shape is the engine's velocity contract, restated here so this file keeps importing
|
|
4129
|
-
* nothing: `pass(scene, camera)` returns exactly this.
|
|
4130
|
-
*/
|
|
4131
|
-
velocity?: {
|
|
4132
|
-
pass?: ReturnType<typeof pass>;
|
|
4133
|
-
/** How a host whose scene pass owns the velocity output provides it; the chain's MRT route is the default. */
|
|
4134
|
-
provision?: {
|
|
4135
|
-
texture(scenePass: ReturnType<typeof pass>): Node;
|
|
4136
|
-
attach<T>(node: T, source: unknown): T;
|
|
4137
|
-
};
|
|
4138
|
-
rejectionMeasurement?: () => {
|
|
4139
|
-
frame: number;
|
|
4140
|
-
rejectionFraction: number;
|
|
4141
|
-
} | undefined;
|
|
4142
|
-
};
|
|
4143
|
-
};
|
|
4144
|
-
stages?: readonly ChainStage[];
|
|
4145
|
-
resolutionSubrect?: ResolutionSubrectController;
|
|
4146
|
-
}) => {
|
|
4147
|
-
applied: {
|
|
4148
|
-
dropped: readonly {
|
|
4149
|
-
name: string;
|
|
4150
|
-
reason: string;
|
|
4151
|
-
}[];
|
|
4152
|
-
stages: readonly string[];
|
|
4153
|
-
};
|
|
4154
|
-
dispose(): void;
|
|
4155
|
-
};
|
|
4156
|
-
};
|
|
4157
|
-
declare class WorldEnvironment {
|
|
4158
|
-
#private;
|
|
4159
|
-
/**
|
|
4160
|
-
* A scene with no options starts from the `high` quality tier, a fresh Unreal 5.8.3 project's look; the tier named by
|
|
4161
|
-
* `renderChainTier` ("medium" or "low") starts from that tier instead. An option you give always wins, and an
|
|
4162
|
-
* `undefined` one does not count as given.
|
|
4163
|
-
*/
|
|
4164
|
-
constructor(given?: IWorldEnvironmentOptions);
|
|
4165
|
-
/**
|
|
4166
|
-
* Installs the chain. Returns what actually ran — the same applied report the chain
|
|
4167
|
-
* printed — so a scene can assert on it instead of scraping the console.
|
|
4168
|
-
*/
|
|
4169
|
-
apply(renderer: OutputRenderer, scene: Scene, camera: Camera, target?: IWorldEnvironmentTarget): {
|
|
4170
|
-
dropped: readonly {
|
|
4171
|
-
name: string;
|
|
4172
|
-
reason: string;
|
|
4173
|
-
}[];
|
|
4174
|
-
stages: readonly string[];
|
|
4175
|
-
dispose?: () => void;
|
|
4176
|
-
exposure?: AutoExposureNode;
|
|
4177
|
-
/** The engine's live temporal state; present only while `temporalAA` runs. */
|
|
4178
|
-
temporalReport?: () => Record<string, unknown>;
|
|
4179
|
-
};
|
|
4180
|
-
}
|
|
4181
|
-
|
|
4182
3559
|
/**
|
|
4183
3560
|
* Diagnosis knobs of the calibration harness, kept out of the engine's own reading of the page URL: the harness sets
|
|
4184
3561
|
* them before it builds a `WorldEnvironment`, and a game never needs to. The defaults are the shipped look.
|
|
@@ -4190,99 +3567,12 @@ declare const lookDiagnostics: {
|
|
|
4190
3567
|
aaAlphaSqueezed: boolean;
|
|
4191
3568
|
/** Runs N denoise passes over the SSGI gather at any layer, for an A/B against the tier's count. */
|
|
4192
3569
|
denoisePasses: number | undefined;
|
|
4193
|
-
/** Turns
|
|
4194
|
-
|
|
3570
|
+
/** Turns off the film curve's 43.7 channel clip (on by default), the OFF arm of a paired capture. */
|
|
3571
|
+
lutClipOff: boolean;
|
|
4195
3572
|
/** Draws one GI term alone (PRD-646); needs the gather, so it applies at layer 7 and above. */
|
|
4196
3573
|
giVisualize: GIVisualizeMode;
|
|
4197
3574
|
};
|
|
4198
3575
|
|
|
4199
|
-
/**
|
|
4200
|
-
* This game's authored looks. GPU family picks the start; measured frame budgets refine it.
|
|
4201
|
-
* Edit these presets to change the look without changing the framework.
|
|
4202
|
-
*/
|
|
4203
|
-
type QualityTier = "low" | "medium" | "high";
|
|
4204
|
-
/**
|
|
4205
|
-
* Picks the tier: an explicit `tier` always wins, otherwise the platform decides.
|
|
4206
|
-
*
|
|
4207
|
-
* Fails closed. An unrecognised tier name throws with the value it was handed rather than
|
|
4208
|
-
* quietly rendering the default, because a silent fallback here looks exactly like a tier that
|
|
4209
|
-
* turned out to have no effect.
|
|
4210
|
-
*/
|
|
4211
|
-
declare function resolveQualityTier(request?: {
|
|
4212
|
-
readonly gpuClass?: string;
|
|
4213
|
-
readonly mobile?: boolean;
|
|
4214
|
-
readonly software?: boolean;
|
|
4215
|
-
readonly tier?: string;
|
|
4216
|
-
}): QualityTier;
|
|
4217
|
-
/**
|
|
4218
|
-
* Harness: the screen-space gather Unreal's L7 (Epic) is judged against: 32 rays a pixel at half resolution, denoised
|
|
4219
|
-
* over 16 gather pixels. A calibration tool, not a shipping tier (PRD-640 Phase 1: about 31 ms at 1080p). Every harness
|
|
4220
|
-
* scene that renders global illumination spreads it, so no scene falls back to the `high` preset's 2-slice gather.
|
|
4221
|
-
*/
|
|
4222
|
-
declare const EPIC_SSGI: IWorldEnvironmentOptions;
|
|
4223
|
-
/** The stages and strengths a tier turns on. Throws on a name that is not a tier. */
|
|
4224
|
-
declare function qualityPreset(tier: string): IWorldEnvironmentOptions;
|
|
4225
|
-
/**
|
|
4226
|
-
* Global illumination and shadow filtering per tier, named after Unreal's scalability levels
|
|
4227
|
-
* (Engine/Config/BaseScalability.ini, `[GlobalIlluminationQuality@0..3]` and `[ShadowQuality@0..3]`).
|
|
4228
|
-
* A fresh Unreal project runs Epic (3), so `high` is Epic; `medium` is level 1 and `low` is level 0.
|
|
4229
|
-
* Unreal's own level 2 (High) is not a ThreeNative tier: the three tiers are the three levels a
|
|
4230
|
-
* calibration scene is judged against (PRD-644, PRD-652).
|
|
4231
|
-
*/
|
|
4232
|
-
type FinalGatherMethod = "none" | "irradianceField" | "screenProbeGather";
|
|
4233
|
-
interface IGiTier {
|
|
4234
|
-
/**
|
|
4235
|
-
* How bounce light reaches a pixel. `none` is Unreal's Low: no diffuse GI, the sky light at 0.8.
|
|
4236
|
-
* `irradianceField` is Medium: world-space probes only (the baked cache here). `screenProbeGather`
|
|
4237
|
-
* is Epic: the screen-space gather over the same cache. The preset of the tier names it.
|
|
4238
|
-
*/
|
|
4239
|
-
readonly finalGatherMethod: FinalGatherMethod;
|
|
4240
|
-
/** Read-only report: the `sg.GlobalIlluminationQuality` this tier follows. */
|
|
4241
|
-
readonly globalIlluminationQuality: 0 | 1 | 3;
|
|
4242
|
-
/**
|
|
4243
|
-
* `r.DistanceFieldAO`: whether the scene's distance fields shadow the sky light. Unreal's Low turns it off, so
|
|
4244
|
-
* the sky light reaches the inside of a room unoccluded (measured on `sunlit-room`, PRD-644 `## Decisions`).
|
|
4245
|
-
*/
|
|
4246
|
-
readonly distanceFieldAO: boolean;
|
|
4247
|
-
/** `r.SkylightIntensityMultiplier`: Unreal suppresses the sky light to 0.8 at Low, where DFAO is off. */
|
|
4248
|
-
readonly skylightIntensityMultiplier: number;
|
|
4249
|
-
}
|
|
4250
|
-
/** The GI method and Unreal level of a tier. Throws on a name that is not a tier. */
|
|
4251
|
-
declare function giPreset(tier: string): IGiTier;
|
|
4252
|
-
interface IShadowFilter {
|
|
4253
|
-
readonly blockerSamples: number;
|
|
4254
|
-
readonly filterSamples: number;
|
|
4255
|
-
}
|
|
4256
|
-
interface IShadowTier {
|
|
4257
|
-
/** Read-only report: the `sg.ShadowQuality` this tier follows. */
|
|
4258
|
-
readonly shadowQuality: 0 | 1 | 3;
|
|
4259
|
-
/**
|
|
4260
|
-
* Whether the sun and the lamps cast dynamic shadows. Unreal draws none at `sg.ShadowQuality` 0
|
|
4261
|
-
* (`r.ShadowQuality=0`), measured on `penumbra-lab` (PRD-652 `## Decisions`), so `low` casts none.
|
|
4262
|
-
*/
|
|
4263
|
-
readonly castShadows: boolean;
|
|
4264
|
-
/**
|
|
4265
|
-
* The receiver filter taps of the sun and of every lamp: Unreal's directional and local ray counts
|
|
4266
|
-
* are equal at Medium and Epic, so one pair serves both.
|
|
4267
|
-
*/
|
|
4268
|
-
readonly filter: IShadowFilter;
|
|
4269
|
-
/** `r.Shadow.Virtual.ResolutionLodBiasDirectional`: -1 halves the finest sun level's texel. */
|
|
4270
|
-
readonly resolutionLodBiasDirectional: number;
|
|
4271
|
-
}
|
|
4272
|
-
/** The shadow filter and resolution bias of a tier. Throws on a name that is not a tier. */
|
|
4273
|
-
declare function shadowPreset(tier: string): IShadowTier;
|
|
4274
|
-
/** The tier tables as one object: `resolve` a start tier from a GPU class, `gi` and `shadow` settings of a tier. */
|
|
4275
|
-
declare const qualityTiers: {
|
|
4276
|
-
readonly resolutionScale: {
|
|
4277
|
-
readonly low: 1;
|
|
4278
|
-
readonly medium: 0.72;
|
|
4279
|
-
readonly high: 0.85;
|
|
4280
|
-
};
|
|
4281
|
-
readonly gi: typeof giPreset;
|
|
4282
|
-
readonly resolve: typeof resolveQualityTier;
|
|
4283
|
-
readonly shadow: typeof shadowPreset;
|
|
4284
|
-
};
|
|
4285
|
-
|
|
4286
3576
|
/** The renderer multiplier for an exposure value at ISO 100.
|
|
4287
3577
|
* @situation expose a frame lit in lux and nits with a physical camera exposure value
|
|
4288
3578
|
* @constraint ev100 must be finite; a unitless scene keeps its own multiplier instead
|
|
@@ -5941,14 +5231,6 @@ declare function boneLengths(root: Object3D): IBoneLengthSnapshot;
|
|
|
5941
5231
|
*/
|
|
5942
5232
|
declare function boneLengthDeviations(root: Object3D, bind: IBoneLengthSnapshot, options?: IBoneLengthDeviationsOptions): IBoneLengthDeviationReport;
|
|
5943
5233
|
|
|
5944
|
-
|
|
5945
|
-
* The version this library reports.
|
|
5946
|
-
*
|
|
5947
|
-
* It read `0.1.0` while the package published `0.2.0`, and `__tests__/build.spec.ts` asserted the
|
|
5948
|
-
* stale literal, so the test held the bug in place rather than catching it. A literal is
|
|
5949
|
-
* unavoidable here — core is bundled for browsers and cannot read `package.json` at runtime — so
|
|
5950
|
-
* the spec now asserts this equals the manifest instead of asserting a number somebody typed.
|
|
5951
|
-
*/
|
|
5952
|
-
declare const version = "0.3.11";
|
|
5234
|
+
declare const version = "0.3.13";
|
|
5953
5235
|
|
|
5954
|
-
export { ATLAS_PADDING, ATMOSPHERE_LUT_RESOLUTIONS, AnimationComposer, AnimationPlayer, Atmosphere, type AtmosphereDirection, AtmosphereLuts, type AtmosphereRgb,
|
|
5236
|
+
export { ATLAS_PADDING, ATMOSPHERE_LUT_RESOLUTIONS, AnimationComposer, AnimationPlayer, Atmosphere, type AtmosphereDirection, AtmosphereLuts, type AtmosphereRgb, Billboard3D, type BillboardLockAxis, BlendSpace1D, BlendSpace2D, BudgetLadder, type BudgetVerdict, ClusteredBatch, ClusteredMesh, DEV_GLOBAL_KEY, Daylight, type DevGlobal, ENVIRONMENT_TOO_SMALL_MARKER, FlightModel, FluidField2D, FluidParticles3D, FramePassKind, GIBudget, type GIMethod, GIVisualizeMode, GI_METHODS, GPUParticles3D, GPUSceneBVH, type GPUSceneBVHTraceFunction, GroundSnap, type IAddInSlicesOptions, type IAddInSlicesProgress, type IAddInSlicesReport, type IAircraftAirframe, type IAnimationComposerOptions, type IAnimationLayer, type IAnimationMask, type IAnimationMotionDelta, type IAnimationPlayOptions, type IAnimationPlayerOptions, type IAnimationRootMotionOptions, type IAnimationUpdateRateReport, type IAtmosphereLutResolution, type IAtmosphereLutResolutions, type IAtmosphereOptions, type IAtmosphereParameterPatch, type IAtmosphereParameters, type IAtmosphereScenePass, type IBillboard3DOptions, type IBoneContactReport, type IBoneLengthDeviation, type IBoneLengthDeviationReport, type IBoneLengthDeviationsOptions, type IBoneLengthSnapshot, type IBonePoseError, type IBudgetLadderOptions, type IBudgetWindow, type IClipBindingReport, type IClipCoverageReport, type IClipPoseErrorOptions, type IClipPoseErrorReport, type IClipPoseSubject, type IClipTrackBinding, type IClusterTable, type IClusteredBatchBuildOptions, type IClusteredBatchOptions, type IClusteredMeshOptions, type IClusteredPlacement, IComputeDriven$1 as IComputeDriven, type IDaylightOptions, type IDevTools, type IEmitParticleRequest, type IFlightAxes, type IFlightControls, type IFlightDeck, type IFlightEnvironment, type IFlightForces, type IFlightModelOptions, type IFlightModifiers, type IFlightQuaternion, type IFlightState, type IFlightVector3, type IFluidBounds, type IFluidCollider, type IFluidFieldOptions, type IFluidFieldSampler, type IFluidFieldVector2, type IFluidParticlesOptions, type IFluidParticlesStats, IFrameBudgetWindow, type IGIBudgetOptions, type IGIBudgetReport, type IGPUParticles3DOptions, type IGPUParticles3DRuntime, type IGPUParticles3DSpawnBuffers, type IGPUParticles3DSpawnRequest, type IGPUParticles3DStats, IGPUReadbackSample, type IGPUSceneBVHMaterialGroup, type IGPUSceneBVHOptions, IGamePluginHooks, IGamePluginRuntime, IGeometryCaptureReport, IGeometryCaptureRequest, type IGroundSnapOptions, type IInstancedBatchBuildOptions, type IInstancedBatchOptions, type IInstancedPlacement, type ILampShadowStats, type ILaunchFailure, type ILoadAllOptions, type ILoadAllProgress, type IMatrixWorldReport, type IMeasureThreePoseOptions, type IMergeByMaterialOptions, type IMergePart, type IMergePartsOptions, type INormaliseToMetresOptions, type IPathFollow3DOptions, type IPathFollow3DProjection, type IPathFollow3DSample, type IProbeVolumeBakeProgress, type IProbeVolumeCoefficient, type IProbeVolumeObservation, type IProbeVolumeOptions, type IRadianceCacheOptions, type IReplayOptions, type IReplayRecording, type IReplayRecordingSample, type IResolvedAtmosphereParameters, type IRippleFieldFlow, type IRippleFieldOptions, type ISceneShape, type ISceneWarning, type IShadowFilterBudgetOptions, type IShadowFilterReport, type ISkeletalMesh3DOptions, type ISkyCaptureOptions, type ISoftBody3DOptions, type ISoftBodyCollision, type ISolarPosition, type ISolarPositionInput, type ISourceAngleShadowInputs, type ISourceAngleShadowOptions, type ISpanProbeTarget, type ISpanSummary, type ISpanWindow, type ISpectralOceanCascade, type ISpectralOceanHeight, type ISpectralOceanOptions, type ISpriteAnimator3DOptions, type ISpriteFrame3D, IStageGpuReading, type IStaticTransformCensus, type IStrideReport, type ISurfaceCacheMaterial, type ISurfaceCacheOptions, type ISurfaceCacheReport, type ISurfaceCacheTexture, type ISurfaceLight, type ISurfaceLightsOptions, type IThreePoseBounds, type IThreePoseMeasurement, type ITracerPool3DOptions, type ITracerSpawnOptions, type IUnlitFoliageWarning, type IValidationReport, type IVirtualShadowOptions, type IVirtualShadowStats, type IWaterReflectionOptions, type IWaterSurfaceOptions, type IWaveFieldDomainWarp, type IWaveFieldGraphOptions, type IWaveFieldOptions, type IWaveFieldSample, type IWaveFieldWave, InstancedBatch, LAMP_SHADOW_MARKER, LUT_RESOLUTIONS, type LaunchFailureKind, type MatrixWorldMode, MatrixWorldPass, NEUTRAL_FLIGHT_MODIFIERS, type NormaliseAxis, OPACITY_IGNORED_MARKER, PROBE_VOLUME_MARKER, PathFollow3D, ProbeVolume, type ProbeVolumeDensity, RENDERLIST_VALIDATE_FLAG, RENDERLIST_VALIDATE_MARKER, RadianceCache, type Recording, RenderListValidator, type ReplayPointer, RippleField, SCENE_WARNING_MARKER, SHADOW_FILTER_TIERS, SHADOW_STAGES, SPANS, SPANS_FLAG, SPANS_MARKER, SPAN_COUNT, SPAN_NAMES, STATIC_TRANSFORM_MARKER, ShadowFilterBudget, type ShadowFilterTier, SkeletalMesh3D, SkyCapture, SkyCaptureSchedule, SoftBody3D, type SpanId, SpanRecorder, SpectralOcean, SpriteAnimator3D, type SpritePlaybackMode, SurfaceCache, SurfaceLights, type ThreePoseQuaternion, type ThreePoseVector, TracerPool3D, UNLIT_FOLIAGE_FIX, UNLIT_FOLIAGE_MARKER, VIRTUAL_SHADOW_CASTER_LAYER, VIRTUAL_SHADOW_MARKER, VIRTUAL_SHADOW_MOVER_LAYER, VIRTUAL_SHADOW_WIDE_CASTER_LAYER, VirtualShadowNode, WaterSurface3D, type WaveDirection, WaveField, addFoliageBackLight, addInSlices, addSpan, aerodynamicCoefficients, airDensity, aircraftMass, alwaysRender, attachToBone, attitudeAxes, beginSpan, boneContact, boneLengthDeviations, boneLengths, bvhIntersectFirstHit, clipBoneCoverage, clipPoseError, clipTrackBindings, createReplayDriver, debugFlag, describeSceneShape, describeSceneWarning, devGlobal, directionFromSolarPosition, directionalTransmittance, displayPeriodMs, endSpan, ev100FromCamera, ev100FromExposure, ev100FromLuminance, exposeDebug, exposureFromEv100, formatSceneWarning, formatSpansWindow, formatUnlitFoliageWarning, formatValidationReport, gearClearance, installSpanProbes, invalidateStatic, isStatic, lampPenumbraTangent, lampShadowMarker, loadAll, lookDiagnostics, markStatic, measureThreePose, mergeByMaterial, mergeParts, normaliseToMetres, onLaunchFailure, parseReplayRecording, penumbraUv, posedBounds, publishDevGlobal, rayStruct, readGIMarker, readLampShadowMarker, readProbeVolumeObservation, readShadowTierMarker, readVirtualShadowMarker, refreshStaticTransforms, renderListValidationRequested, renderTrapAudit, replay, resetStaticTransforms, resolveAtmosphereLutResolutions, resolveAtmosphereParameters, sceneWarning, setAttitude, setSpanRecorder, skeletonBones, softCircleDataTexture, solarPosition, solarPositionAt, sourceAngleShadowFilter, sourceRadiusShadowFilter, spanNow, spanRecorder, spansRequested, staticTransformCensus, thinCards, unlitFoliageWarning, unmarkStatic, updateAtmosphereParameters, updateClusteredMeshes, useRoughDiffuse, validateWorldMatrices, version, zenithTransmittance };
|