threejs-dynamic-surface-effects

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

State-Transition Dynamic Surface Effects

状态转换动态表面效果

Own viewport-locked appearance history and its composite. Route world/object residue to

$threejs-particles-trails-and-effects

, weather accumulation to

$threejs-rain-snow-and-wet-surfaces

, bounded water to

$threejs-water-optics

, and shared full-frame output decisions to

$threejs-image-pipeline

When temperature, phase, loading, wetness, contact, or weather drives the appearance, close this local handoff before step 1:

name the physical quantity and units, producer frame/origin, transform and origin generations, and projection into screen UV;
name the source interval, cadence, sample phase, immutable producer/version, and renderer consumer;
declare support/filter, validity, staleness, error, and missing-signal policy;
bind the GPU resource generation, producing and consuming passes, and completion dependency;
keep the physical source read-only and give screen history its own appearance version; reset it on incompatible clock, origin, transform, projection, or resource-generation changes.

Invoke

$threejs-choose-skills

when feedback or additional system owners are required. The physical owner retains authority; screen-UV history remains renderer-owned appearance state. Then read external appearance signals for local projection and reset rules.

拥有视口锁定的外观历史及其合成效果。将世界/对象残留效果路由至

$threejs-particles-trails-and-effects

，天气累积效果路由至

$threejs-rain-snow-and-wet-surfaces

，边界水域效果路由至

$threejs-water-optics

，并将共享全帧输出决策路由至

$threejs-image-pipeline

。

当温度、物相、加载状态、湿润度、接触或天气因素驱动外观变化时，请在步骤1前完成以下本地交接：

定义物理量及其单位、生成帧/原点、变换与原点世代，以及向屏幕UV的投影方式；
定义源区间、节奏、采样相位、不可变生成器/版本，以及渲染器消费者；
声明支持/过滤规则、有效性、过期策略、错误处理及缺失信号应对方案；
绑定GPU资源世代、生成与消耗通道，以及完成依赖关系；
保持物理源为只读状态，为屏幕历史分配独立的外观版本；当时钟、原点、变换、投影或资源世代发生不兼容变化时，重置屏幕历史。

当需要反馈或额外系统所有者时，调用

$threejs-choose-skills

。物理源所有者保留控制权；屏幕UV历史始终属于渲染器所有的外观状态。随后阅读外部外观信号以了解本地投影和重置规则。

Process

流程

1. Define the state transition and ownership

1. 定义状态转换与所有权

Write one contract for:

each history channel and its dimensionless meaning;
the screen-space event shape, timestamp, pressure/strength, and UV origin;
evolution terms such as decay, deposition, diffusion, or no change;
the state clock, suspension/seek policy, and reset dependencies;
the one history writer, composite consumer, and final output owner;
any external physical signal and the decorative overlay kept separate from it.

For touch/frost history, a useful split is visible coverage in

and a smoother tilt/refraction response in

;

G/B

remain unused or explicitly diagnostic. The step is complete when every channel has one equation, writer, unit domain, clock, and consumer.

为以下内容编写一份契约：

每个历史通道及其无量纲含义；
屏幕空间事件的形状、时间戳、压力/强度，以及UV原点；
演化项，如衰减、沉积、扩散或无变化；
状态时钟、暂停/查找策略，以及重置依赖项；
唯一的历史写入者、合成消费者和最终输出所有者；
任何外部物理信号，以及与之分离的装饰性叠加层。

对于触摸/霜冻历史，一种实用的拆分方式是：将可见覆盖率存储在

通道，将更平滑的倾斜/折射响应存储在

通道；

G/B

通道留空或专门用于诊断。当每个通道都有对应的方程、写入者、单位域、时钟和消费者时，此步骤完成。

2. Select update topology

2. 选择更新拓扑

Choose from the state transition rather than the visual theme:

Transition	Update topology
Decay, diffusion, or forcing changes most texels	Full-field ping-pong compute
Deposits are sparse and untouched texels are invariant	Event bounds or dirty tiles
Sparse state also decays	Timestamped tiles with analytic catch-up on every visible/filter sample, or materialize every visible tile
Many events overlap	Bin events to tiles; bound/compact lists or rasterize one aggregate deposit field
State and inputs are unchanged	Idle: retain history and dispatch nothing

Diffusion uses a full field or halo-expanded active domain. Read update topologies for overlap cost and diffusion stability. The step is complete when untouched texels evolve exactly as the chosen model requires and idle frames schedule no state work.

根据状态转换而非视觉主题进行选择：

转换类型	更新拓扑
衰减、扩散或强制改变多数纹理像素	全屏乒乓计算
沉积稀疏且未触及的纹理像素保持不变	事件边界或脏瓦片
稀疏状态同时存在衰减	带时间戳的瓦片，在每个可见/过滤样本上进行解析性追更，或实例化所有可见瓦片
大量事件重叠	将事件分箱到瓦片；绑定/压缩列表或光栅化一个聚合沉积场
状态与输入无变化	空闲：保留历史且不调度任何任务

扩散使用全屏或光晕扩展的活动域。阅读更新拓扑了解重叠成本和扩散稳定性。当未触及的纹理像素完全按照所选模型演化，且空闲帧不调度任何状态任务时，此步骤完成。

3. Make time and event integration invariant

3. 确保时间与事件集成的不变性

Derive

dt

from two ordered samples on the same clock. Treat equal samples as zero elapsed time. A missing previous sample, reversal, seek, invalid mapping, or discontinuity follows the declared freeze, reset, analytic catch-up, or bounded-substep policy.

Rasterize timestamped pointer motion as swept capsules with aspect from the history texture. Integrate decay and saturating deposition together so a held pointer and a swept gesture converge independently of render-frame count. Subdivide event intervals only when their pressure or coverage variation exceeds the declared error gate.

Read dt-correct history before implementing decay, deposition, or diffusion. The step is complete when the same timed input yields equivalent history at 30, 60, and 120 Hz and a suspension does not silently discard elapsed evolution.

从同一时钟上的两个有序样本推导

dt

。将相同样本视为经过零时间。若缺少前一个样本、出现反转、查找、无效映射或不连续情况，则遵循已声明的冻结、重置、解析性追更或有界子步策略。

将带时间戳的指针运动光栅化为具有历史纹理宽高比的扫掠胶囊。将衰减和饱和沉积整合在一起，使按住指针和扫掠手势的效果独立于渲染帧数量收敛。仅当事件的压力或覆盖率变化超过已声明的误差阈值时，才对事件区间进行细分。

在实现衰减、沉积或扩散之前，阅读dt校正历史。当相同的定时输入在30、60和120 Hz下产生等效历史，且暂停不会静默丢弃已流逝的演化时，此步骤完成。

4. Allocate the ping-pong graph

4. 分配乒乓图

Use

WebGPURenderer

from

three/webgpu

, call

await renderer.init()

, and require

renderer.backend.isWebGPUBackend === true

for this canonical path. Route explicit WebGPU-unavailable teaching to

$threejs-compatibility-fallbacks

. Allocate two renderer-owned

StorageTexture

histories at the lowest measured extent/format that passes reconstruction and quantization tests. Keep history, scene color, blur intermediates, and static structure fields as separate resources.

Order the graph:

text

immutable external appearance signals + timestamped UI events
  -> write next history from previous history
  -> publish/swap the completed history generation
single scene pass
  -> optional separable blur at its owned reduced extent
  -> static structure + current history composite
  -> optional history-gated normal refraction
  -> one RenderPipeline output transform

Use

Fn().compute(...)

storageTexture()

, and

textureStore()

for history updates. Enqueue with

renderer.compute(...)

; r185

computeAsync()

is not a GPU-completion fence. Keep the steady path readback-free. Mark/rebuild the render graph when the output node, diagnostic route, resource extent/format, or quality branch changes.

Read resources and r185 execution before allocating or swapping textures. The step is complete when every pass reads a committed generation, no pass samples the texture it writes, and the scene is rendered once.

使用

three/webgpu

中的

WebGPURenderer

，调用

await renderer.init()

，并要求

renderer.backend.isWebGPUBackend === true

以遵循此标准路径。将WebGPU不可用的相关教学内容路由至

$threejs-compatibility-fallbacks

。分配两个由渲染器所有的

StorageTexture

历史纹理，采用通过重建和量化测试的最低测量范围/格式。将历史纹理、场景颜色、模糊中间产物和静态结构场作为独立资源保存。

对图进行排序：

text

不可变外部外观信号 + 带时间戳的UI事件
  -> 根据前一历史纹理写入下一历史纹理
  -> 发布/交换已完成的历史世代
单场景通道
  -> 可选：在其专属低分辨率下进行可分离模糊
  -> 静态结构 + 当前历史纹理合成
  -> 可选：基于历史的法线折射
  -> 单个RenderPipeline输出变换

使用

Fn().compute(...)

、

storageTexture()

和

textureStore()

进行历史纹理更新。通过

renderer.compute(...)

加入队列；r185版本的

computeAsync()

并非GPU完成栅栏。保持稳定路径无回读操作。当输出节点、诊断路由、资源范围/格式或质量分支发生变化时，标记/重建渲染图。

在分配或交换纹理之前，阅读资源与r185执行。当每个通道都读取已提交的世代，没有通道对自身写入的纹理进行采样，且场景仅渲染一次时，此步骤完成。

5. Compose blur, structure, and refraction

5. 合成模糊、结构与折射效果

Generate static crystalline/noise fields once at startup or when their extent or quality changes. Treat them as data with

NoColorSpace

. Use separable blur at a pass-owned reduced resolution and alpha-aware normalization when alpha participates. Build the composite and refraction as TSL nodes feeding

RenderPipeline.outputNode

Keep scene and working buffers linear/HDR until the single output conversion. Use screen-period uniforms as periods; derive texel dimensions from the actual resource. Gate refraction by structural coverage and current history, define normal wrap and source-edge behavior, and apply Fresnel in linear light.

Read composite and refraction when either branch is active. The step is complete when blur extent, texture domains, UV conventions, refraction bounds, and output conversion are each owned and visible in diagnostics.

在启动时或当范围/质量变化时，生成一次静态晶体/噪声场。将它们视为

NoColorSpace

的数据。在通道专属的低分辨率下使用可分离模糊，当alpha通道参与时使用alpha感知归一化。将合成效果和折射效果构建为TSL节点，输入至

RenderPipeline.outputNode

。

在完成单次输出转换前，保持场景和工作缓冲区为线性/HDR格式。使用屏幕周期统一变量作为周期；从实际资源推导纹理像素尺寸。通过结构覆盖率和当前历史纹理控制折射，定义法线环绕和源边缘行为，并在线性光下应用菲涅尔效应。

当任一分支处于活动状态时，阅读合成与折射。当模糊范围、纹理域、UV约定、折射边界和输出转换均有明确所有者且可在诊断中查看时，此步骤完成。

6. Close the lifecycle

6. 完成生命周期管理

Choose one resize policy: clear both histories, remap, or depth/camera-aware reprojection. Reset or reproject on incompatible clock, origin, transform, projection, resource generation, representation, or quality changes. Ordinary continuous source-version advances are sampled rather than reset.

On idle, retain persistent state and stop update work. On resume, apply the declared time policy before accepting new input. On disposal or device loss, invalidate the history generation and release both histories, blur/static resources, compute/pipeline nodes, and input/resize listeners; create a fresh generation before the next draw.

Read resize, reset, and disposal. The step is complete when resize, seek, quality change, idle/resume, disposal, and device loss each have an explicit state transition and resource result.

选择一种调整大小策略：清除两个历史纹理、重新映射，或基于深度/相机的重投影。当时钟、原点、变换、投影、资源世代、表示形式或质量发生不兼容变化时，重置或重投影。普通的连续源版本升级仅进行采样而非重置。

空闲时，保留持久状态并停止更新任务。恢复时，在接受新输入前应用已声明的时间策略。当销毁或设备丢失时，使历史世代失效并释放两个历史纹理、模糊/静态资源、计算/管线节点以及输入/调整大小监听器；在下次绘制前创建新的世代。

阅读调整大小、重置与销毁。当调整大小、查找、质量变化、空闲/恢复、销毁和设备丢失均有明确的状态转换和资源处理结果时，此步骤完成。

7. Prove state and presentation

7. 验证状态与呈现效果

Expose previous history, deposit, next history, dirty tiles/active texels, scene color, blur axes, static fields, pre/post-history mask, refraction offsets, final-without-refraction, and final. Add pause and single-step controls.

Measure event count, tile-list occupancy, dispatched texels, history and intermediate bytes, traffic lower bound, dispatch/draw timing, and whole-frame p50/p95. Scale by stopping idle work, choosing a valid sparse path, then reducing history/blur extent or precision after state-equivalence tests.

Read resource accounting and diagnostics and failure signatures. The skill is complete when timed inputs match across 30/60/120 Hz; full, sparse, and idle transitions behave as selected; ping-pong generations never alias; resize/reset/disposal controls pass; physical inputs remain read-only; the frame loop performs zero history readbacks; the scene renders once; output conversion has one owner; and the complete scene meets its named memory, traffic, and timing budget.

暴露前一历史纹理、沉积效果、下一历史纹理、脏瓦片/活动纹理像素、场景颜色、模糊轴、静态场、历史前后遮罩、折射偏移、无折射最终效果，以及最终效果。添加暂停和单步控制。

测量事件数量、瓦片列表占用率、调度的纹理像素数、历史和中间产物字节数、流量下限、调度/绘制时间，以及全帧p50/p95值。优化方式包括：停止空闲任务、选择有效的稀疏路径，然后在状态等效测试后降低历史/模糊范围或精度。

阅读资源统计和诊断与故障特征。当定时输入在30/60/120 Hz下表现一致；全屏、稀疏和空闲转换均按预期运行；乒乓世代从未出现混淆；调整大小/重置/销毁控制通过测试；物理输入保持只读；帧循环无历史纹理回读操作；场景仅渲染一次；输出转换有唯一所有者；且完整场景满足指定的内存、流量和时间预算时，此技能实现完成。