Threejs 材质 API

以下是 Three.js Material（材质基类） 的完整中文说明：

---

概述
Material 是所有材质的抽象基类，定义了物体外观的渲染方式。其属性与方法具有渲染器无关性，可在不同渲染器之间复用。

---

构造函数

Material()

创建一个通用材质基类（通常不直接实例化）。

---

核心属性（所有材质继承的通用属性）

1. 透明度与混合

属性	类型	描述
.alphaHash	Boolean	启用哈希透明（替代 .transparent 或 .alphaTest），通过随机阈值实现无排序问题的透明近似。会引入噪点，可用 TAARenderPass 降噪。默认 false。
.alphaTest	Float	透明度测试阈值（范围 0-1），低于此值的像素不渲染。默认 0。
.alphaToCoverage	Boolean	启用 Alpha to Coverage（需开启 MSAA 抗锯齿）。优化裁剪边缘和 alphaTest 锯齿。默认 false。
.transparent	Boolean	是否启用透明度（需配合 .opacity 使用）。透明物体在非透明物体之后渲染。默认 false。
.opacity	Float	不透明度（0 全透明，1 不透明）。若未启用 .transparent，仅影响颜色不透明度。默认 1。

2. 混合模式

属性	类型	描述
.blending	Integer	混合模式（如 THREE.NormalBlending）。需设为 CustomBlending 才能使用自定义混合参数。默认 NormalBlending。
.blendSrc	Integer	源混合因子（如 THREE.SrcAlphaFactor）。默认 SrcAlphaFactor。
.blendDst	Integer	目标混合因子（如 THREE.OneMinusSrcAlphaFactor）。默认 OneMinusSrcAlphaFactor。
.blendEquation	Integer	混合方程（如 THREE.AddEquation）。默认 AddEquation。
.blendColor	Color	常量混合颜色（仅用于 ConstantColor 混合模式）。默认 0x000000。
.blendAlpha	Float	常量混合 Alpha（仅用于 ConstantAlpha 混合模式）。默认 0。

3. 深度与模板测试

属性	类型	描述
.depthTest	Boolean	是否启用深度测试。禁用时同时禁用深度写入。默认 true。
.depthWrite	Boolean	是否写入深度缓冲（禁用可用于 2D 叠加层）。默认 true。
.depthFunc	Integer	深度比较函数（如 THREE.LessEqualDepth）。默认 LessEqualDepth。
.stencilWrite	Boolean	是否启用模板测试/写入。默认 false。
.stencilFunc	Integer	模板比较函数（如 THREE.AlwaysStencilFunc）。默认 AlwaysStencilFunc。
.stencilRef	Integer	模板参考值。默认 0。

4. 多边形偏移

属性	类型	描述
.polygonOffset	Boolean	是否启用多边形偏移（解决深度冲突）。默认 false。
.polygonOffsetFactor	Float	偏移因子。默认 0。
.polygonOffsetUnits	Float	偏移单位。默认 0。

5. 渲染控制

属性	类型	描述
.side	Integer	面渲染模式：THREE.FrontSide（默认）、THREE.BackSide、THREE.DoubleSide。
.shadowSide	Integer	阴影投射面（覆盖 .side 设置）。默认 null。
.colorWrite	Boolean	是否写入颜色缓冲（可用于创建遮挡物）。默认 true。
.dithering	Boolean	启用颜色抖动减少色带。默认 false。
.toneMapped	Boolean	是否受渲染器色调映射影响。默认 true。
.visible	Boolean	是否可见。默认 true。

6. 高级配置

属性	类型	描述
.defines	Object	自定义着色器宏定义（如 { MY_DEFINE: 1 }）。
.precision	String	覆盖渲染器精度（"highp"/"mediump"/"lowp"）。默认 null。
.forceSinglePass	Boolean	强制双面透明物体单通道渲染（解决植被等性能问题）。默认 false。

7. 标识与元数据

属性	类型	描述
.name	String	材质名称（非唯一）。默认空字符串。
.uuid	String	唯一标识符（自动生成）。
.userData	Object	用户自定义数据存储对象。默认 {}。
.version	Integer	材质更新计数器（.needsUpdate 触发时递增）。

---

核心方法

1. 生命周期管理

方法	描述
.clone()	返回材质副本（浅拷贝纹理）。
.copy(material)	复制其他材质的属性到当前材质。
.dispose()	释放 GPU 资源（需手动调用）。

2. 着色器扩展

方法	描述
.onBeforeCompile(shader, renderer)	着色器编译前回调（可修改着色器代码）。
.customProgramCacheKey()	返回着色器缓存标识（需配合 onBeforeCompile 使用）。

3. 渲染钩子

方法	描述
.onBeforeRender(renderer, scene, camera, geometry, object, group)	材质渲染前回调（每帧执行）。

4. 序列化

方法	描述
.toJSON(meta)	将材质转换为 JSON 格式（含纹理等元数据）。

---

代码示例

// 创建自定义材质（禁用深度写入，启用混合）
const material = new THREE.MeshBasicMaterial({
  color: 0xff0000,
  transparent: true,
  opacity: 0.5,
  depthWrite: false,
  blending: THREE.CustomBlending,
  blendSrc: THREE.SrcAlphaFactor,
  blendDst: THREE.OneMinusSrcAlphaFactor
});

// 克隆材质
const clonedMaterial = material.clone();

// 释放资源
material.dispose();

---

注意事项

1. 性能优化：禁用 .depthWrite 和 .colorWrite 可优化 2D 叠加层渲染。
2. 透明排序：透明物体按渲染顺序（renderOrder）排序，可能产生视觉问题。
3. 模板测试：需开启 WebGLRenderer.localClippingEnabled 才能使用自定义裁剪平面。
4. 着色器扩展：onBeforeCompile 是高级功能，建议优先使用 NodeMaterial 系统（WebGPU 方向）。

源码位置：src/materials/Material.js