threejs-procedural-geometry

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Procedural Geometry

程序化几何

Treat geometry generation as a compiler: select the representation, freeze semantic regions and error bounds, compute exact capacity, emit topology and render attributes, then validate both. Meaning belongs to generator inputs; allocation, topology, groups, updates, and disposal belong to the writer.
For multi-system work,
$threejs-choose-skills
is an optional coordinator. Fields own continuous causes, materials own PBR response, motion owns deformation state, and this skill owns rendered topology. When geometry supplies another system, publish stable units, coordinate/frame convention, producer and consumer owners, revision, support, validity domain, error bound, and update phase independently of render LOD and draw indices.
将几何生成视为编译过程:选择表示形式,冻结语义区域和误差边界,计算精确容量,输出拓扑结构和渲染属性,然后进行验证。含义由生成器输入决定;分配、拓扑、分组、更新和销毁由写入器负责。
对于多系统协作,
$threejs-choose-skills
是可选的协调器。字段管理连续动因,材质管理PBR响应,运动管理变形状态,而本技能负责渲染拓扑结构。当几何为其他系统提供数据时,需独立于渲染LOD和绘制索引,发布稳定单元、坐标/坐标系约定、生产者和消费者所有者、版本、支持范围、有效域、误差边界以及更新阶段。

1. Select the representation before allocation

1. 分配前选择表示形式

Choose from the observable and update pattern:
ContractRepresentation
one unique authored surface with material regionsindexed
BufferGeometry
with groups
many same-material objects with varied topology
BatchedMesh
many repeats with identical topology
InstancedMesh
GPU-owned transforms or visibility with identical topologymatrix-free instanced geometry plus storage-backed state
hot visibility compaction with stable bucketsstorage data plus indirect draw commands
continuous single-valued reliefindexed adaptive grid, quadtree, or clipmap with a seam policy
hard terraces, cliffs, or topology-bearing bandscontour-derived caps plus explicit walls/band meshes
visible overhangs or cavesbounded volumetric meshing after memory/topology gates pass
In r185 WebGPU,
BatchedMesh
manages geometry and culling but the backend still iterates visible multi-draw entries; it is not evidence of one native draw.
InstancedMesh
is valid only for identical topology.
This step is complete when one representation owns each surface/object class, its culling and update unit is named, and no triangle or buffer has been emitted.
从可观测模式和更新模式中选择:
约定表示形式
带有材质区域的单一独特创作表面带分组的索引
BufferGeometry
多个材质相同但拓扑不同的对象
BatchedMesh
多个拓扑完全相同的重复对象
InstancedMesh
拓扑相同且由GPU管理变换或可见性无矩阵实例化几何加存储支持的状态
稳定分组下的可见性动态压缩存储数据加间接绘制命令
连续单值浮雕带接缝策略的索引自适应网格、四叉树或裁剪映射
硬质阶地、悬崖或承载拓扑的条带等高线生成的顶盖加显式墙体/条带网格
可见悬挑或洞穴通过内存/拓扑限制后的有界体素网格
在r185版本的WebGPU中,
BatchedMesh
管理几何和剔除,但后端仍会遍历可见的多绘制条目;这并不代表是一次原生绘制。
InstancedMesh
仅适用于拓扑完全相同的场景。
当每个表面/对象类别都对应一种表示形式,其剔除和更新单元已命名,且尚未输出任何三角形或缓冲区时,此步骤完成。

2. Freeze semantics and error contracts

2. 冻结语义和误差约定

Record coordinate frames, semantic dimensions, named regions, material slots, smoothing groups, UV charts, hard boundaries, topology identities, LOD view envelope, and resource owner. Gate each LOD with a conservative error bound in physical render-target pixels at the actual target size and an unjittered view. Include the complete support and error of geometry, active displacement or deformation, filtering, and reconstruction. Use the exact camera projection or, for a perspective approximation, the nearest valid positive view depth; accept the LOD only when the projected bound is at or below that view's declared threshold. Give each view separate enter/exit thresholds with hysteresis and a minimum dwell, and keep both transition levels resident until the transition finishes. Triangle ratios are supporting counts, not an error bound.
For contour-driven work, consume one versioned field source. Read contour topology and terrain compilation before extracting a shoreline, terrace, band, cliff, or region with holes.
When placement, picking, or measurement anchors must survive LOD or rebuilds, read semantic anchors and LOD bindings before decimation.
This step is complete when every intended face belongs to a semantic region, material slot, smoothing group, UV chart, topology identity, and projected-error gate, and every required anchor has a stable source/topology identity and LOD binding policy.
记录坐标系、语义维度、命名区域、材质插槽、平滑组、UV图表、硬边界、拓扑标识、LOD视口范围以及资源所有者。为每个LOD设置保守误差边界,该边界基于实际目标尺寸和无抖动视图下的物理渲染目标像素。包含几何、活动位移或变形、过滤和重建的完整支持范围和误差。使用精确的相机投影,或者对于透视近似,使用最近的有效正视图深度;仅当投影边界等于或低于该视图声明的阈值时,才接受该LOD。为每个视图设置带有迟滞效应和最小停留时间的独立进入/退出阈值,并在过渡完成前保留两个过渡层级。三角形比例是辅助计数,而非误差边界。
对于等高线驱动的工作,使用一个版本化的字段源。在提取海岸线、阶地、条带、悬崖或带孔洞区域之前,请阅读等高线拓扑与地形编译。
当放置、拾取或测量锚点必须在LOD或重建后保留时,请在简化前阅读语义锚点与LOD绑定。
当每个预期面都属于一个语义区域、材质插槽、平滑组、UV图表、拓扑标识和投影误差限制,且每个所需锚点都有稳定的源/拓扑标识和LOD绑定策略时,此步骤完成。

3. Compute exact capacity, then emit

3. 计算精确容量,然后输出

Count render vertices after all required duplication and count indices before allocation:
text
vertexCount = smooth vertices + hard-edge duplicates + UV seams
            + material-boundary duplicates + caps and explicit boundaries
indexCount = 3 * triangleCount
Allocate typed arrays once. Use
Uint16Array
only when the highest referenced vertex is at most
65535
; otherwise use
Uint32Array
. Emit through a small writer surface such as:
text
addVertex, addTriangle, addQuad
duplicateForBoundary
startSmoothingGroup, startUvChart, addGroup
finishGeometry
Every index belongs to exactly one nonoverlapping group with a stable material index.
finishGeometry
asserts the planned and written counts match.
This step is complete when allocation equals the planned capacity exactly, every emitted index is owned by one group, and overflow or unfilled capacity is an explicit error.
在分配前计算所有必要复制后的渲染顶点数量和索引数量:
text
vertexCount = 平滑顶点 + 硬边重复顶点 + UV接缝重复顶点
            + 材质边界重复顶点 + 顶盖和显式边界顶点
indexCount = 3 * triangleCount
一次性分配类型化数组。仅当引用的最高顶点数不超过
65535
时使用
Uint16Array
;否则使用
Uint32Array
。通过小型写入器接口输出,例如:
text
addVertex, addTriangle, addQuad
duplicateForBoundary
startSmoothingGroup, startUvChart, addGroup
finishGeometry
每个索引都属于一个唯一的非重叠分组,且该分组具有稳定的材质索引。
finishGeometry
会验证计划数量与写入数量是否匹配。
当分配容量与计划容量完全相等,每个输出的索引都属于一个分组,且溢出或未填满容量被视为显式错误时,此步骤完成。

4. Close topology, normals, UVs, and frames

4. 闭合拓扑、法线、UV和坐标系

Keep topological identity separate from render-vertex identity. Render vertices duplicate at hard normals, material boundaries, UV seams, and mirrored tangent spaces while topological edges still prove adjacency and closure.
Use analytic normals/tangents where the generator owns a parameterization.
computeVertexNormals()
is for deliberately smooth shared-vertex regions. For normal-map parity, await
MikkTSpace.ready
before
computeMikkTSpaceTangents(...)
; r185 de-indexes indexed geometry, so recompute counts, groups, bounds, and bytes for that distinct representation.
Production UVs express physical distance or declared repeats; normalized local parameters belong in a separate debug attribute. Profile and branch sweeps use a rotation-minimizing parallel-transport frame with an explicit antiparallel fallback and closed-loop holonomy correction.
Read profile sweeps and transported frames when emitting along a curve.
This step is complete when topology closes at every undeclared boundary, normals/tangents match semantic boundaries, UV density is stable across LOD, and transported frames remain continuous through zero curvature and inflections.
将拓扑标识与渲染顶点标识分开。在硬法线、材质边界、UV接缝和镜像切线空间处复制渲染顶点,而拓扑边仍需证明邻接性和闭合性。
在生成器拥有参数化的情况下,使用解析法线/切线。
computeVertexNormals()
用于刻意平滑的共享顶点区域。为了与法线贴图保持一致,在调用
computeMikkTSpaceTangents(...)
前需等待
MikkTSpace.ready
;r185版本会对索引几何进行去索引处理,因此需要为该独特表示形式重新计算数量、分组、边界和字节数。
生产环境的UV表示物理距离或声明的重复次数;归一化的局部参数应放在单独的调试属性中。轮廓和分支扫掠使用旋转最小化并行传输坐标系,并带有显式反平行回退和闭环完整校正。
当沿曲线输出时,请阅读轮廓扫掠与传输坐标系。
当拓扑在所有未声明的边界处闭合,法线/切线与语义边界匹配,UV密度在LOD间保持稳定,且传输坐标系在零曲率和拐点处保持连续时,此步骤完成。

5. Wire batching and updates

5. 配置批处理和更新

Initialize and gate the renderer before allocating GPU-owned storage or indirect commands:
js
await renderer.init();
if (renderer.backend.isWebGPUBackend !== true) {
  throw new Error('Native WebGPU is required for geometry storage and indirect draws.');
}
Check the selected storage bindings and buffer usage against the initialized device limits before compilation.
Set attribute
usage
before first render. Static geometry uploads once and may release CPU arrays only when no rebuild requires them. Dynamic sections use
addUpdateRange()
in component units,
needsUpdate
, and targeted bounds recomputation. Capacity, item size, or usage-model changes rebuild the owning attribute/geometry rather than mutating its contract.
When compute owns instance state, submit compute before the consuming render and keep one transform owner. In r185,
computeAsync()
is not a GPU-completion fence. Indirect commands use CPU-known byte offsets and stable homogeneous buckets; shader masking is not visibility compaction.
Read batching, dynamic updates, and indirect draws before adding a batch container, per-frame mutation, storage state, or indirect draw.
This step is complete when each mutable byte range, dispatch, draw entry, bounding volume, and disposal point has one owner and hidden work is absent from the claimed culling result.
在分配GPU所有的存储或间接命令之前,初始化并验证渲染器:
js
await renderer.init();
if (renderer.backend.isWebGPUBackend !== true) {
  throw new Error('Native WebGPU is required for geometry storage and indirect draws.');
}
在编译前检查所选的存储绑定和缓冲区使用情况是否符合初始化后的设备限制。
在首次渲染前设置属性
usage
。静态几何仅上传一次,且仅当无需重建时才可释放CPU数组。动态部分使用组件单元的
addUpdateRange()
、
needsUpdate
和针对性的边界重新计算。容量、项大小或使用模型的变化会重建所属的属性/几何,而非修改其约定。
当计算模块管理实例状态时,需在消费渲染之前提交计算,并保持一个变换所有者。在r185版本中,
computeAsync()
并非GPU完成围栏。间接命令使用CPU已知的字节偏移和稳定的均匀分组;着色器遮罩不属于可见性压缩。
在添加批处理容器、每帧突变、存储状态或间接绘制之前,请阅读批处理、动态更新与间接绘制。
当每个可变字节范围、调度、绘制条目、包围体和销毁点都有一个所有者,且声明的剔除结果中不存在隐藏工作时,此步骤完成。

6. Validate topology and render geometry

6. 验证拓扑和渲染几何

Validate topological identities before render duplication, then the final
BufferGeometry
:
  • closed/simple/nested contour loops and declared open boundaries;
  • two oppositely oriented incident faces per interior topological edge;
  • no T-junctions, duplicate faces, bow-ties, or unintended non-manifold edges;
  • finite attributes, in-range indices, nondegenerate triangles, and winding;
  • unit normals, tangent handedness, physical UV density, group coverage, and bounds containing every vertex;
  • protected features and topology through every LOD and mixed-LOD seam;
  • stable anchor source/topology IDs, per-LOD bindings, exclusion revisions, and bounded position/frame error through rebuild and LOD changes;
  • exact resident/upload bytes, draw/backend entries, update ranges, and sustained target timing where performance is claimed.
Diagnostics expose topological versus render IDs, boundaries, winding, normals, tangents, UV density, material groups, LOD/seam error, batch identity, and dirty ranges.
This step is complete when every semantic region passes topology, attribute, LOD, group, bounds, byte, lifecycle, and claimed performance gates, including adversarial contour and frame cases selected by the active branches.
在渲染复制前验证拓扑标识,然后验证最终的
BufferGeometry
:
  • 闭合/简单/嵌套的等高线环和声明的开放边界;
  • 每个内部拓扑边对应两个方向相反的相邻面;
  • 无T型连接、重复面、蝴蝶结或意外的非流形边;
  • 属性有限、索引在范围内、三角形非退化且 winding 正确;
  • 法线单位化、切线手性正确、UV密度符合物理规律、分组覆盖完整,且包围体包含所有顶点;
  • 在所有LOD和混合LOD接缝处保留受保护的特征和拓扑;
  • 稳定的锚点源/拓扑ID、每个LOD的绑定、排除版本,以及在重建和LOD变化期间位置/坐标系误差有界;
  • 精确的驻留/上传字节数、绘制/后端条目、更新范围,以及在性能声明处持续达到目标时序。
诊断信息会暴露拓扑ID与渲染ID的对比、边界、winding、法线、切线、UV密度、材质分组、LOD/接缝误差、批处理标识和脏范围。
当每个语义区域都通过拓扑、属性、LOD、分组、边界、字节、生命周期和声明的性能检查,包括活动分支选择的极端等高线和坐标系案例时,此步骤完成。

Completion

完成

The geometry system is complete when representation precedes allocation; exact capacity equals emitted data; semantic topology survives render duplication, batching, updates, and LOD; every index and mutable byte has one owner; and the final mesh passes topology, attribute, projected-error, resource, and lifecycle checks.
当表示形式先于分配;精确容量与输出数据相等;语义拓扑在渲染复制、批处理、更新和LOD中得以保留;每个索引和可变字节都有一个所有者;且最终网格通过拓扑、属性、投影误差、资源和生命周期检查时,几何系统即完成。