threejs-procedural-fields

程序化场

先编写一个确定性场数据包，再针对各着色器阶段和使用方进行适配。坐标、种子、成因、导数和输出含义属于场；片元采样足迹、顶点 LOD、存储和诊断属于使用方适配器。

对于涉及多个系统的工作，$threejs-choose-skills 是可选的协调器。材质负责 PBR 响应，几何体负责拓扑，水体负责自由表面状态，最终图像技能负责色调映射和输出转换。发布每个跨系统场输出时，应注明单位、坐标／参考系约定、生产方和使用方负责人、修订版本、空间／时间支持范围及滤波器、有效域、误差界限、更新频率和过时规则。将 GPU 资源布局和渲染 LOD 保留在使用方适配器内部。

1. 固定场契约

实现前记录：

coordinate domain and units
seed owner, hash/noise family, and wrapping convention
primary fields -> derived causes -> named outputs
consumer, filter, precision, update cadence, and validity per output
direct-versus-bake decision inputs
debug view and invalidation key per output

根据成因选择坐标：地形和天气使用世界／瓦片局部坐标，行星使用未变形的径向物理坐标，装饰使用对象／局部坐标，或使用声明的生成纹理域。对于大型域，应先使用整数瓦片加局部浮点数（或其他拆分表示），以避免 f32 相位误差改变场。

当每个输出都有唯一的坐标／种子负责人、单位、使用方、滤波器、精度、更新规则、无效状态和诊断方式时，此步骤即告完成。

2. 编写一个可移植至各阶段的核心

使用确定性的 TSL Fn 实现共享成因。核心应避免依赖仅适用于片元的导数、顶点相机策略、存储布局和分派状态。使用 .toVar() 或等效的局部变量，只计算一次常用中间结果；如果不同输出可能会重复构建相同的扭曲、哈希或倍频链，请检查生成的 WGSL。

使用 WebGPURenderer，并在 await renderer.init() 后验证 renderer.backend.isWebGPUBackend === true。renderer.compute() 会提交常规计算工作。在 r185 中，computeAsync() 会先初始化再入队，但它不是 GPU 完成栅栏。要确保 CPU 可见的完成状态，需要等待映射／回读或队列完成 Promise；仅设置时间戳查询既不能证明工作已完成，也不能证明其成本。

将对奇偶一致性至关重要的种子保留为 u32，而非 f32。在位重解释前，将取整后的格点坐标限制在 i32 范围内。对坐标仅应用一次域扭曲，将其雅可比矩阵传播到解析梯度中；球面扭曲应保持切向，再进行归一化。

在实现整数格点 CPU／TSL 奇偶一致性分支前，请阅读规范的奇偶一致性核心。其中展示了有符号 i32 范围限制、使用 Math.imul／TSL uint 的回绕哈希、精确的高 24 位归一化，以及一个共享的 .toVar() 数据包，但没有规定场频谱。CPU 调用方在 valid === false 时拒绝结果；TSL 调用方则在使用哈希／值之前，将 valid 节点传入显式掩码、选择操作或无效状态诊断。

当所有使用方都调用同一成因图、每个共享中间结果在每次调用中仅计算一次，且每项阶段限制都隔离在适配器中时，此步骤即告完成。

3. 选择直接求值或存储

比较一个摊销周期：

Tdirect = sum_i(Q_i * E_i)

Tbake = (D * (E_bake + Wstore) + Tdispatch + Tmips) / U
      + sum_i(Q_i * (S_i + B_i / BW_effective))

Q_i 是消费者 i 的实际工作负载；片段工作负载根据分辨率、覆盖率、MSAA/辅助调用和过度绘制进行测量或建模。D 是脏纹素数，U 是复用帧数，其余项来自受控目标测量。在满足延迟、内存和误差门限的前提下，选择成本较低的路径。仅读取次数或倍频程数不足以作为决策依据。

烘焙时，只将坐标、精度、滤波方式、更新周期和消费者局部性相同的通道打包。使用独立的存储和采样用法作用域；如果更新时要读取并写入同一逻辑字段，则使用乒乓缓冲。RGBAFormat + HalfFloatType 是可移植的 r185 rgba16float 可写基线（8 B/texel）。较窄或 float32 格式以及滤波功能，须根据实际 WebGPU 特性进行门控。存储局部值或归一化值，而非较大的绝对坐标。

在添加 StorageTexture、mip 链、脏瓦片更新器或类别 ID 纹理之前，请阅读 存储、精度和失效处理。

满足以下条件后，此步骤即告完成：所选表示具有经过测量的成本输入、确切的字节数和同时存活的资源生命周期、已传播的逐通道误差，以及负责创建、更新、失效处理和释放的明确所有者。

4. 为每个消费者滤波，并仅在需要时添加 CPU 一致性实现

对于后变形足迹 J' 和频带的有效支持频率 f_support，使用

q = f_support * sigmaMax(J')

并要求 q <= 0.5 cycles/sample。应在达到此界限前进行淡出或预滤波，并将移除的斜率/法线能量转移至材质的方差/粗糙度路径。几何位移也必须满足其网格采样界限。片段导数仅适用于导数一致的片段适配器；顶点和计算着色器用户则需要解析、符号式、外部提供的足迹或存储的导数。

仅在用于几何体/离线生成、预计算原生层级或一致性证据时，才创建 CPU 移植版本。它应导入与 TSL 相同的常量、种子环绕、归一化和重映射。分别比较直接 f32、采样/插值和存储/量化误差；阈值判定应使用保护带，而非全局图像容差。

当字段驱动位移、分类、存储样本或 CPU 消费者时，请阅读 滤波与一致性。

满足以下条件后，此步骤即告完成：每个启用的频带都通过相应的屏幕/网格足迹门限，并且每项 CPU/存储比较都说明误差来源、界限和阈值行为。

5. 接入消费者、失效处理和诊断

使用 NodeMaterial 插槽或几何体／计算输入，不要重新创建成因。 数据字段使用 NoColorSpace。颜色纹理声明其实际传递函数和原色：编码后的 sRGB 使用 SRGBColorSpace，线性 sRGB HDR 使用 LinearSRGBColorSpace；其他编码则显式转换。在唯一的输出归属方完成之前，HDR 工作缓冲区保持线性。

当种子、坐标、算法、源数据、编码或接受的值发生变化时，字段版本随之变化。将该版本传播到依赖它的 mip、等高线、锚点、缓存和诊断数据。静态字段只构建一次，低频字段按节奏更新，已编辑字段使脏区域及所有滤波器／导数光晕失效，且所有资源都必须有负责释放的归属方。帧关键型消费者留在 GPU 上，或使用显式的异步镜像；诊断数据可在渲染循环之外读回。

公开源坐标、每个成因／频带、导数或坐标系、打包通道、选定的 mip／足迹、有效性、直接值与存储值之间的误差，以及最终消费者结果。当视图共享场景渲染通道时，使用 mrt()。

对于度量有符号距离、海岸线、沿岸剖面、排水或驱动等高线的分类，请先阅读度量有符号距离与海岸分析。

当更改任一字段输入都会使所有依赖消费者失效，诊断数据会公开所有已命名输出和失败状态，并且针对相同契约的重建会产生相同的值和标识时，此步骤即告完成。

完成标准

当一个可跨阶段移植的成因图能够说明每个输出；直接计算／烘焙和滤波选择均有证据支撑；在存在这些分支时，CPU、存储和阈值误差均明确；所有跨系统消费者都能收到带版本且单位已声明的有效数据；并且坐标、标识、mip、脏区域和资源在重建、LOD、调整大小和释放过程中保持稳定时，字段系统即告完成。