threejs-procedural-geometry

程序化几何

将几何生成视为编译器：选择表示方式，冻结语义区域和误差界限，计算精确容量，生成拓扑和渲染属性，然后验证两者。含义属于生成器输入；分配、拓扑、组、更新和释放属于写入器。

对于多系统工作，$threejs-choose-skills 是可选的协调器。场负责连续成因，材质负责 PBR 响应，运动负责变形状态，而本技能负责渲染拓扑。当几何为其他系统提供数据时，应独立于渲染 LOD 和绘制索引，发布稳定单位、坐标系／帧约定、生产者和消费者所有者、版本、支持范围、有效域、误差界限及更新阶段。

1. 在分配前选择表示方式

根据可观察内容和更新模式进行选择：

契约	表示方式
一个具有材质区域的独特创作曲面	带组的索引式 BufferGeometry
多个拓扑各异但使用相同材质的对象	BatchedMesh
多个拓扑相同的重复对象	InstancedMesh
具有相同拓扑、由 GPU 管理变换或可见性的对象	无矩阵实例化几何体加上由存储缓冲支持的状态
使用稳定分桶进行高频可见性压缩	存储数据加间接绘制命令
连续的单值起伏表面	具有接缝策略的索引式自适应网格、四叉树或裁剪贴图
硬阶地、悬崖或带有拓扑的带状区域	基于轮廓提取的封顶面加显式墙面／带状网格
可见的悬挑或洞穴	通过内存／拓扑门槛后进行有界体积网格化

在 r185 WebGPU 中，BatchedMesh 管理几何体和剔除，但后端仍会遍历可见的多重绘制条目；这不能证明它只进行一次原生绘制。InstancedMesh 仅适用于拓扑相同的对象。

当每个曲面／对象类别都由一种表示方式负责、其剔除和更新单位均已明确，且尚未生成任何三角形或缓冲区时，此步骤即告完成。

2. 冻结语义和误差契约

记录坐标系、语义维度、命名区域、材质槽、平滑组、UV 图表、硬边界、拓扑标识、LOD 视图范围和资源所有者。为每个 LOD 设置保守误差界限，按实际目标尺寸和未抖动视图，以物理渲染目标像素为单位计算。纳入几何体、活动位移或变形、滤波和重建的完整支持范围和误差。使用精确的相机投影；如果采用透视近似，则使用最近的有效正视图深度；只有当投影误差界限不超过该视图声明的阈值时，才接受此 LOD。为每个视图分别设置带滞回的进入／退出阈值以及最短驻留时间，并让两个过渡级别在过渡完成前保持驻留。三角形比例只是辅助计数，不能作为误差界限。

对于由轮廓驱动的工作，应使用同一个带版本的场源。在提取海岸线、阶地、带状区域、悬崖或带孔洞的区域之前，请阅读轮廓拓扑与地形编译。

当放置、拾取或测量锚点必须在 LOD 变化或重建后保持有效时，请在简化之前阅读语义锚点与 LOD 绑定。

当每个预期面都属于某个语义区域、材质槽、平滑组、UV 图表、拓扑标识和投影误差门槛，并且每个必需锚点都有稳定的源／拓扑标识和 LOD 绑定策略时，此步骤即告完成。

3. 精确计算容量，然后写入

完成所有必要的顶点复制后，统计渲染顶点；分配前统计索引：

vertexCount = unique (topological vertex, boundary domain, attribute values) tuples
indexCount = 3 * triangleCount

重叠的拆分原因只计一次；仅有材质槽时，不必复制属性相同的顶点。分配前验证容量计算安全且不超过内存限制。在固定的 r185 路径中，索引不超过 65534 时使用 Uint16Array，否则显式使用 Uint32Array：其上传适配器会将 Uint16 索引中的 65535 改写为重启哨兵值，并扩宽缓冲区。应单独核算实际上传的宽度与 CPU 数组的宽度。通过简洁的写入器接口写入，例如：

addVertex, addTriangle, addQuad
duplicateForBoundary
startSmoothingGroup, startUvChart, addGroup
finishGeometry

每个索引都恰好属于一个不重叠的组，且该组的材质索引稳定。finishGeometry 会断言规划数量与实际写入数量一致。

当分配容量与规划容量完全相等、每个写入的索引都归属于一个组，且溢出或容量未填满都会显式报错时，此步骤即告完成。

4. 完善拓扑、法线、UV 和坐标系

将拓扑身份与渲染顶点身份分开。渲染顶点会在硬法线、材质边界、UV 接缝和镜像切线空间处复制，而拓扑边仍用于证明邻接关系和闭合性。

如果生成器掌握参数化方式，则使用解析法线/切线。computeVertexNormals() 适用于刻意保持顶点共享的平滑区域。为确保法线贴图一致性，先等待 MikkTSpace.ready，再调用 computeMikkTSpaceTangents(...)；r185 会对索引几何体取消索引，因此需针对这种不同的表示方式重新计算数量、组、边界和字节数。此转换无法保留所有语义元数据、活动绘制范围以及属性类型/用法，需在转换之外保留这些信息。应在发布到 GPU 前完成转换。

生产用 UV 表示物理距离或声明的重复次数；归一化的局部参数应置于单独的调试属性中。轮廓扫掠和分支扫掠使用旋转最小化的平行传输坐标系，并显式处理反平行情况及闭环整体扭转修正。

沿曲线写入时，请阅读轮廓扫掠和平行传输坐标系。

当所有未声明边界处的拓扑都闭合、法线/切线符合语义边界、UV 密度在不同 LOD 间保持稳定，并且平行传输坐标系在零曲率和拐点处保持连续时，此步骤即告完成。

5. 线框批处理与更新

在分配 GPU 所有的存储或间接命令之前，初始化并检查渲染器：

await renderer.init();
if (renderer.backend.isWebGPUBackend !== true) {
  throw new Error('Native WebGPU is required for geometry storage and indirect draws.');
}

编译前，根据已初始化设备的限制检查所选存储绑定和缓冲区用法。

在首次渲染前设置属性 usage。如果布局编译、光线投射、边界计算、序列化或恢复仍会读取实时属性数组，就要保留这些数组；释放生成器中间数据是独立操作。动态区段会保留尚未消费的 addUpdateRange() 分量区间，直到适配器上传这些区间。空区间表示完整上传，而非无需处理。在 r185 中，即使版本未变，DynamicDrawUsage 也会触发上传；间歇性编辑则使用由版本驱动的用法，并设置 needsUpdate。重新计算受影响的边界。容量、项目大小或用法模型发生变化时，应将所属几何体替换为经过验证的资源代次，并明确回收上一个代次。

当计算着色器拥有实例状态时，应在使用该状态的渲染之前提交计算，并确保变换只有一个所有者。GPU 变换需要为每个视图中的变形实例域计算边界；基础网格边界和 CPU 光线投射无法观察仅存储于 GPU 存储中的变形。在 r185 中，computeAsync() 不是 GPU 完成栅栏。间接命令使用 CPU 已知的字节偏移和稳定的同质分桶；着色器屏蔽并不等同于可见性压缩。

添加批处理容器、逐帧变更、存储状态或间接绘制之前，请先阅读 批处理、动态更新和间接绘制。

当每个可变字节区间、调度、绘制项、包围体和释放点都只有一个所有者，且所声称的剔除结果中不存在隐藏工作时，此步骤即告完成。

6. 验证拓扑和渲染几何体

在渲染复制之前验证拓扑标识，再验证最终的 BufferGeometry：

• 闭合、简单、嵌套的轮廓环，以及已声明的开放边界；
• 每条内部拓扑边恰有两个方向相反的邻接面；
• 无 T 形连接、重复面、蝴蝶结或意外的非流形边；
• 属性值均为有限值，索引在范围内，三角形无退化，绕序正确；
• 法线为单位长度，切线手性正确，UV 物理密度正确，组覆盖完整，边界包含每个顶点；
• 受保护特征和拓扑在每个 LOD 及混合 LOD 接缝中均保持不变；
• 锚点源 ID 和拓扑 ID 保持稳定，具有逐 LOD 绑定和排除修订版本，并且在重建和 LOD 变化过程中，位置与帧误差有界；
• 在声称达到性能目标时，精确记录常驻/上传字节数、绘制/后端项、更新区间以及持续目标耗时。

诊断信息应展示拓扑 ID 与渲染 ID、边界、绕序、法线、切线、UV 密度、材质组、LOD/接缝误差、批次标识和脏区间。

当每个语义区域均通过拓扑、属性、LOD、组、边界、字节数、生命周期以及所声称的性能门槛（包括活动分支所选的对抗性轮廓和帧情况）时，此步骤即告完成。

完成

当表示先于分配、精确容量等于生成数据量、语义拓扑在渲染复制、批处理、更新和 LOD 中均得以保留、每个索引和可变字节都只有一个所有者，且最终网格通过拓扑、属性、投影误差、资源和生命周期检查时，几何系统即告完成。