Back to Details

threejs-procedural-materials

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Procedural Materials

程序化材质

Build a cause graph, not a collection of channel effects:
text
stable coordinates -> structural causes -> identity weights
  -> causal modifiers -> filtered microstructure
  -> NodeMaterial PBR slots -> final-image owner
Use 
MeshStandardNodeMaterial
for standard opaque/emissive PBR and 
MeshPhysicalNodeMaterial
only when its extra lobes or transport properties are part of the surface. Keep Three.js lighting, environment, shadows, and energy handling by assigning node slots instead of replacing the whole fragment output.
For multi-system scenes, 
$threejs-choose-skills
is an optional coordinator. Fields own shared scalar/vector causes, geometry owns silhouettes, water owns surface/transport, and the final-image pipeline owns tone mapping and display conversion. Consume each dynamic or cross-system cause with declared units, coordinate/frame convention, producer and consumer owners, revision, spatial/temporal support and filter, validity domain, error bound, update cadence, and staleness rule. A visual material state does not become another simulation owner.
Initialize and gate the renderer before allocating storage, dispatching compute-written cause maps, or compiling storage-backed material branches:
js
await renderer.init();
if (renderer.backend.isWebGPUBackend !== true) {
  throw new Error('Native WebGPU is required for procedural material GPU branches.');
}
const { features, limits } = renderer.backend.device;
Select sampled/storage bindings, writable formats, and filtering from those initialized features and limits.
构建因果图，而非通道效果的集合：
text
稳定坐标 -> 结构因果因子 -> 标识权重
  -> 因果修正器 -> 过滤后的微结构
  -> NodeMaterial PBR插槽 -> 最终图像所有者
对于标准不透明/发光PBR，使用
MeshStandardNodeMaterial
；仅当额外的lobe或传输属性属于表面特性时，才使用
MeshPhysicalNodeMaterial
。通过分配节点插槽而非替换整个片段输出，保留Three.js的光照、环境、阴影和能量处理机制。
对于多系统场景，
$threejs-choose-skills
是可选的协调器。字段拥有共享标量/矢量因果因子，几何体拥有轮廓，水体拥有表面/传输属性，最终图像管线拥有色调映射和显示转换。使用每个动态或跨系统因果因子时，需声明单位、坐标/坐标系约定、生产者和消费者所有者、版本、空间/时间支持与过滤、有效域、误差范围、更新节奏和过期规则。视觉材质状态不会成为另一个模拟的所有者。
在分配存储、调度计算写入的因果因子贴图或编译基于存储的材质分支之前，初始化并验证渲染器：
js
await renderer.init();
if (renderer.backend.isWebGPUBackend !== true) {
  throw new Error('Native WebGPU is required for procedural material GPU branches.');
}
const { features, limits } = renderer.backend.device;
从已初始化的特性和限制中选择采样/存储绑定、可写入格式和过滤方式。

1. Freeze coordinates, causes, and identities

1. 固定坐标、因果因子和标识

Choose UV, object, world, radial, or generated-texture space from the physical or authored cause. Record scale in meters or declared art units. Mixing spaces is valid only for distinct causes, such as world-height wetness over object-space grain.
Define normalized material identity weights and a response bundle per identity:
text
linear base reflectance
roughness alpha and metal/dielectric endpoint
resolved height/normal spectrum plus removed variance
causal modifiers such as wetness, wear, heat, or coverage
semantic/material ID and diagnostic color
All channels use the same filtered weights. Hard semantic eligibility remains separate from visible blend width. Blend 
alpha=roughness^2
, then recover roughness with 
sqrt(alpha)
when one GGX lobe approximates a subpixel mixture.
When terrain or seabed is involved, read substrate and water ownership before wiring coast distance, wetness, shallow-water, foam, or caustics.
This step is complete when every PBR channel traces to named causes and identity weights in one coordinate/scale contract, with a hard semantic fallback for any zero-weight region.
从物理或预设的因果因子中选择UV、对象、世界、径向或生成纹理空间。记录以米或声明的美术单位为基准的缩放比例。仅当因果因子不同时（例如世界高度的湿润度叠加对象空间的纹理颗粒），才允许混合空间。
定义归一化的材质标识权重，以及每个标识对应的响应集合：
text
线性基础反射率
粗糙度alpha值和金属/电介质端点
解析后的高度/法线光谱及移除的方差
湿润度、磨损、热度或覆盖率等因果修正器
语义/材质ID和诊断颜色
所有通道使用相同的过滤权重。硬语义资格与可见混合宽度保持分离。混合时使用
alpha=roughness^2
，当单个GGX lobe近似子像素混合时，通过
sqrt(alpha)
恢复粗糙度。
当地形或海床相关时，在连接海岸距离、湿润度、浅水区、泡沫或焦散效果之前，请阅读 基底与水体所有权。
当每个PBR通道都能追溯到单一坐标/缩放约定下的命名因果因子和标识权重，且任何零权重区域都有硬语义回退方案时，此步骤完成。

2. Select the mapping from defect and cost

2. 根据缺陷与成本选择映射方式

Choose in this order:
  1. UVs when seams and texel-density distortion pass.
  2. Texture arrays when layers share dimensions, format, mips, color semantics, and sampler policy.
  3. Atlas when array constraints fail and mip-safe gutters are owned.
  4. One-/two-axis projection for a dominant direction or top/side split.
  5. Triplanar only when no cheaper parameterization preserves scale.
  6. Stochastic tiling only when repetition, rather than parameterization, is the observed defect.
Count bindings and executed samples separately. Installed r185 
triplanarTexture()
performs three projected samples per bound texture and uses absolute-normal weights; it does not reorient tangent-space normals or provide stochastic tiling. Arrays/atlases reduce bindings, not sample count.
Read mapping and filtering before using an atlas, texture array, triplanar mapping, or stochastic tiling.
This step is complete when the selected mapping solves the observed defect, every texture's color/data semantics and mip policy are explicit, and compiled binding/sample counts fit the target pipeline with measured value for added taps.
按以下顺序选择：
  1. 当接缝和纹理像素密度畸变符合要求时，使用UV。
  2. 当图层共享尺寸、格式、mipmap、颜色语义和采样器策略时，使用纹理数组。
  3. 当数组约束不满足且拥有mipmap安全的 gutter 时，使用图集。
  4. 针对主导方向或上下拆分场景，使用单/双轴投影。
  5. 仅当无更廉价的参数化方式能保留缩放比例时，使用三平面映射。
  6. 仅当重复而非参数化是可观测缺陷时，使用随机平铺。
分别统计绑定数量和执行的采样次数。已集成的r185版本
triplanarTexture()
对每个绑定纹理执行三次投影采样，并使用绝对法线权重；它不会重新定向切线空间法线或提供随机平铺。数组/图集减少的是绑定数量，而非采样次数。
在使用图集、纹理数组、三平面映射或随机平铺之前，请阅读 映射与过滤。
当所选映射解决了可观测缺陷、每个纹理的颜色/数据语义和mipmap策略明确，且编译后的绑定/采样次数符合目标管线并能衡量额外采样的价值时，此步骤完成。

3. Wire shared causes into NodeMaterial slots

3. 将共享因果因子接入NodeMaterial插槽

Own only the slots required by the material:
text
colorNode             linear identity color and causal shifts
roughnessNode         identity alpha plus filtered modifiers
metalnessNode         conductor/dielectric identity
normalNode            normalMap, texture bump, or shared-height gradient
aoNode                local cavity/contact term
opacity/mask/alphaTest cutout or dissolve
emissiveNode          actual scene-linear emitted radiance
positionNode          visible local displacement
castShadowPositionNode matching caster displacement
castShadow/maskShadow matching cutout or dissolve
In r185, 
receivedShadowPositionNode
is a separate world-space receiver override; leave it unset unless that replacement is explicitly derived and validated. Visible and caster displacement share one local-space cause. Emission feeds the HDR material result; bloom and tone mapping remain downstream owners.
Data textures use 
NoColorSpace
; authored color textures use 
SRGBColorSpace
; scene-linear generated color remains linear. Keep one tone-map and output-conversion owner through 
RenderPipeline.outputColorTransform
or one 
renderOutput()
.
This step is complete when every owned slot has one cause, visible/shadow masks and displacement agree, color/data encodings are correct, and no material node duplicates final output conversion.
仅拥有材质所需的插槽：
text
colorNode             线性标识颜色和因果偏移
roughnessNode         标识alpha值加过滤后的修正器
metalnessNode         导体/电介质标识
normalNode            法线贴图、纹理凹凸或共享高度梯度
aoNode                局部空腔/接触项
opacity/mask/alphaTest  裁剪或溶解
emissiveNode          实际场景线性发射辐射
positionNode          可见局部位移
castShadowPositionNode  匹配投射阴影的位移
castShadow/maskShadow  匹配裁剪或溶解
在r185版本中，
receivedShadowPositionNode
是独立的世界空间接收者覆盖项；除非明确推导并验证了替换需求，否则保持未设置状态。可见位移与投射阴影位移共享同一个局部空间因果因子。发射效果输入HDR材质结果； bloom和色调映射属于下游所有者。
数据纹理使用
NoColorSpace
；预设颜色纹理使用
SRGBColorSpace
；场景线性生成的颜色保持线性。通过
RenderPipeline.outputColorTransform
或单个
renderOutput()
保持唯一的色调映射和输出转换所有者。
当每个拥有的插槽都对应一个因果因子、可见/阴影遮罩与位移一致、颜色/数据编码正确，且没有材质节点重复最终输出转换时，此步骤完成。

4. Filter microstructure and specular response

4. 过滤微结构和高光响应

Filter height/normal bands before perturbing the normal. Fragment surface gradients run in derivative-uniform control flow; vertex/compute displacement uses analytic or stored gradients. Preserve normal mean plus variance across mips instead of normalizing the mean and discarding its length.
Three.js r185 already adds geometric-normal variation in 
getRoughness()
. Custom specular AA adds only unresolved material-detail variance. Read derivative normals and specular AA before adding procedural bump, custom normal filtering, or roughness variance.
When a scalar procedural height supplies both normal detail and specular AA, read the filtered-height normal example. Supply its dimensionless 
footprintCyclesPerSample
from the full post-warp Jacobian spectral norm, physical support frequency in cycles per length unit, and positive band half-range around the supplied mean. 
heightHalfAmplitude
uses the same length unit as the surface. It keeps attenuation, removed slope variance, double-sided surface-gradient normal handling, and 
roughness^2
widening in one causal path.
This step is complete when all retained bands pass the projected footprint, removed slope/normal variance is accounted for exactly once, and a no-post close/mid/far comparison rejects distance-dependent sharpening and grazing sparkle.
在扰动法线之前过滤高度/法线波段。片段表面梯度在导数一致的控制流中运行；顶点/计算位移使用解析或存储的梯度。保留法线的均值和方差，而非归一化均值并丢弃其长度。
Three.js r185版本已在
getRoughness()
中添加了几何法线变化。自定义高光抗锯齿仅添加未解析的材质细节方差。在添加程序化凹凸、自定义法线过滤或粗糙度方差之前，请阅读 导数法线与高光抗锯齿。
当标量程序化高度同时提供法线细节和高光抗锯齿时，请阅读过滤高度法线示例。从完整的后变换雅可比谱范数、每长度单位的物理支持频率，以及提供均值周围的正波段半范围中提供无量纲的
footprintCyclesPerSample
。
heightHalfAmplitude
使用与表面相同的长度单位。它在单一因果路径中保留衰减、移除的斜率方差、双面表面梯度法线处理和
roughness^2
加宽效果。
当所有保留的波段都通过投影足迹验证、移除的斜率/法线方差被精确统计一次，且无后处理的近/中/远视图对比拒绝了距离相关的锐化和掠射闪光时，此步骤完成。

5. Own dynamic and per-instance state

5. 管理动态和每实例状态

One material graph serves a batch. Static instance variation uses attributes; hot GPU-owned variation uses storage-backed instance data only when its measured update/access pattern wins. Dissolve, wetness, variant, or lifetime fields drive visible and shadow masks from the same stable object/world cause.
Cause maps use the procedural-fields direct-versus-bake gate. Static maps build once; dynamic maps update at their owner cadence and invalidate dependent mips. Compute submission precedes the consuming render. In r185, 
computeAsync()
is not a GPU-completion fence.
State generations remain immutable while referenced by a frame. Resize, material identity changes, coordinate changes, map encoding changes, and device loss invalidate their dependent history, bindings, and diagnostics. Every material, texture, storage resource, and generated variant has a disposal owner.
This step is complete when one owner advances each dynamic cause, each instance record has stable identity and reset behavior, and no per-object material clone or frame-critical CPU readback is needed.
单个材质图服务于一批实例。静态实例变化使用属性；仅当实测的更新/访问模式更优时，才使用基于存储的实例数据实现GPU托管的热更新变化。溶解、湿润度、变体或生命周期字段从相同的稳定对象/世界因果因子驱动可见和阴影遮罩。
因果因子贴图使用程序化字段的直接生成与烘焙开关。静态贴图仅构建一次；动态贴图按其所有者的节奏更新并使依赖的mipmap失效。计算提交先于消费渲染。在r185版本中，
computeAsync()
并非GPU完成 fence。
状态生成在被帧引用时保持不可变。调整大小、材质标识变化、坐标变化、贴图编码变化和设备丢失会使依赖的历史记录、绑定和诊断失效。每个材质、纹理、存储资源和生成的变体都有一个销毁所有者。
当每个动态因果因子都有一个所有者推进、每个实例记录都有稳定的标识和重置行为，且无需每个对象的材质克隆或帧关键的CPU回读时，此步骤完成。

6. Diagnose and verify

6. 诊断与验证

Expose coordinate mode/scale, identity weights and fallback, each structural cause, mapping weights/mip/gutter, binding and sample counts, roughness before and after AA, normal mean/variance, visible/caster parity, raw emission, no-post beauty, and final post result.
Verify close/mid/far and motion views; conductor/dielectric endpoints; atlas gutters under selected filtering; compiled stage limits; color-space flags; stable instance/shadow behavior; and target whole-frame timing/bytes when performance is claimed.
This step is complete when every PBR identity, mapping branch, filtered-normal branch, dynamic state, shadow path, color conversion, resource lifetime, and claimed target budget has direct diagnostic evidence.
暴露坐标模式/缩放比例、标识权重和回退方案、每个结构因果因子、映射权重/mipmap/gutter、绑定和采样次数、抗锯齿前后的粗糙度、法线均值/方差、可见/投射阴影一致性、原始发射效果、无后处理的美观度和最终后处理结果。
验证近/中/远视图和运动视图；导体/电介质端点；所选过滤下的图集gutter；编译阶段限制；颜色空间标志；稳定的实例/阴影行为；以及当宣称性能时的目标全帧时间/字节占用。
当每个PBR标识、映射分支、过滤法线分支、动态状态、阴影路径、颜色转换、资源生命周期和宣称的目标预算都有直接诊断证据时，此步骤完成。

Completion

完成标准

The material system is complete when one shared cause/identity graph feeds all owned PBR slots; mapping and filtering decisions are evidence-backed; material detail is stable across footprint and motion; dynamic state has one owner and reset path; and raw material output, shadows, post, and resource lifetimes agree.
当单个共享因果因子/标识图为所有拥有的PBR插槽提供数据；映射和过滤决策有证据支持；材质细节在足迹和运动中保持稳定；动态状态有一个所有者和重置路径；且原始材质输出、阴影、后处理和资源生命周期一致时，材质系统即完成。