Material

Material

3D虚拟工厂在线体验

描述

THREE.Material 是 Three.js 中所有材质的基类，定义了物体表面的渲染属性（如颜色、纹理、光照响应、透明度和混合模式等），控制几何体在场景中的视觉表现。

构造函数 (Constructor)

构造函数	描述
Material()	创建一个通用材质对象

属性 (Properties)

属性	类型	默认值	描述
.alphaHash	Boolean	false	启用基于哈希的透明度（替代传统alpha混合）
.alphaTest	Float	0	Alpha测试阈值（0-1）
.alphaToCoverage	Boolean	false	启用MSAA抗锯齿的alpha覆盖
.blendAlpha	Float	0	混合时使用的固定alpha值
.blendColor	Color	0x000000	混合时使用的固定颜色值
.blendDst	Integer	OneMinusSrcAlphaFactor	混合目标因子
.blendDstAlpha	Integer	null	混合目标因子的alpha分量
.blendEquation	Integer	AddEquation	混合方程式
.blendEquationAlpha	Integer	null	混合方程式的alpha分量
.blending	Blending	NormalBlending	混合模式
.blendSrc	Integer	SrcAlphaFactor	混合源因子
.blendSrcAlpha	Integer	null	混合源因子的alpha分量
.clipIntersection	Boolean	false	剪裁平面是否仅剪裁交叉区域
.clippingPlanes	Array	null	自定义剪裁平面数组
.clipShadows	Boolean	false	是否对阴影应用剪裁
.colorWrite	Boolean	true	是否写入颜色缓冲区
.defines	Object	undefined	着色器自定义宏定义
.depthFunc	Integer	LessEqualDepth	深度测试比较函数
.depthTest	Boolean	true	是否启用深度测试
.depthWrite	Boolean	true	是否写入深度缓冲区
.forceSinglePass	Boolean	false	强制单通道渲染透明物体
.isMaterial	Boolean	true	只读标识符
.stencilWrite	Boolean	false	是否启用模板写入
.stencilWriteMask	Integer	0xFF	模板写入掩码
.stencilFunc	Integer	AlwaysStencilFunc	模板测试函数
.stencilRef	Integer	0	模板测试参考值
.stencilFuncMask	Integer	0xFF	模板测试掩码
.stencilFail	Integer	KeepStencilOp	模板测试失败操作
.stencilZFail	Integer	KeepStencilOp	模板通过但深度失败操作
.stencilZPass	Integer	KeepStencilOp	模板和深度都通过操作
.id	Integer	-	唯一标识符（自动生成）
.name	String	""	可读性名称
.needsUpdate	Boolean	false	标记需要重新编译材质
.opacity	Float	1.0	不透明度（0-1）
.polygonOffset	Boolean	false	是否启用多边形偏移
.polygonOffsetFactor	Integer	0	多边形偏移因子
.polygonOffsetUnits	Integer	0	多边形偏移单位
.precision	String	null	着色器精度覆盖
.premultipliedAlpha	Boolean	false	是否预乘alpha通道
.dithering	Boolean	false	是否启用颜色抖动
.shadowSide	Integer	null	阴影投射面设置
.side	Integer	FrontSide	渲染面设置
.toneMapped	Boolean	true	是否应用色调映射
.transparent	Boolean	false	是否为透明材质
.type	String	"Material"	材质类型标识
.uuid	String	-	唯一UUID（自动生成）
.version	Integer	0	更新计数器
.vertexColors	Boolean	false	是否使用顶点颜色
.visible	Boolean	true	是否可见
.userData	Object	{}	自定义数据存储对象

方法 (Methods)

方法	参数	返回值	描述
.clone()	-	Material	创建并返回材质副本
.copy(material)	material: Material	this	复制源材质属性
.dispose()	-	undefined	释放材质资源
.onBeforeCompile(shader, renderer)	shader: Shader, renderer: WebGLRenderer	undefined	着色器编译前回调
.onBeforeRender(...)	渲染相关参数	undefined	渲染前回调
.customProgramCacheKey()	-	String	返回着色器缓存键
.setValues(values)	values: Object	undefined	批量设置属性
.toJSON(meta)	meta: Object	Object	转换为JSON格式

材质类型 (Material Types)

• 基础材质 (Basic Materials)

材质类型	描述
LineBasicMaterial	线条基础材质（恒定宽度）
LineDashedMaterial	虚线材质（需指定虚线样式）
MeshBasicMaterial	不受光照影响的基础网格材质
PointsMaterial	点精灵/粒子系统专用材质

• 光照材质 (Light-Affected Materials)

材质类型	描述
MeshLambertMaterial	基于朗伯模型的漫反射材质
MeshPhongMaterial	包含镜面高光的Phong光照材质
MeshStandardMaterial	基于物理的渲染(PBR)标准材质
MeshPhysicalMaterial	标准材质的扩展（支持更多PBR特性）
MeshToonMaterial	卡通风格渐变着色材质

• 特殊用途材质 (Special Purpose Materials)

材质类型	描述
MeshDepthMaterial	深度缓冲材质（用于深度可视化）
MeshDistanceMaterial	距离场材质（用于阴影计算等）
MeshMatcapMaterial	使用matcap贴图的材质
MeshNormalMaterial	法线可视化材质
ShadowMaterial	阴影捕捉专用材质
SpriteMaterial	精灵/公告牌专用材质

• 着色器材质 (Shader Materials)

材质类型	描述
ShaderMaterial	自定义着色器材质（带Three.js内置变量）
RawShaderMaterial	完全自定义的着色器材质（无预设变量）

常量参考

类别	常量	描述
面渲染(Material.side)	THREE.FrontSide	只渲染正面（默认值）
	THREE.BackSide	只渲染反面
	THREE.DoubleSide	正反面都渲染
混合模式（Material.blending）	THREE.NoBlending	无混合
	THREE.NormalBlending	正常混合（默认值）
	THREE.AdditiveBlending	加法混合
	THREE.SubtractiveBlending	减法混合
	THREE.MultiplyBlending	乘法混合
	THREE.CustomBlending	自定义混合（需设置自定义混合方程）
深度模式（Material.depthFunc）	THREE.NeverDepth	永远不返回true
	THREE.AlwaysDepth	总是返回true
	THREE.LessDepth	输入像素Z-depth < 缓冲器Z-depth时返回true
	THREE.LessEqualDepth	输入像素Z-depth ≤ 缓冲器Z-depth时返回true（默认值）
	THREE.GreaterEqualDepth	输入像素Z-depth ≥ 缓冲器Z-depth时返回true
	THREE.GreaterDepth	输入像素Z-depth > 缓冲器Z-depth时返回true
	THREE.NotEqualDepth	输入像素Z-depth ≠ 缓冲器Z-depth时返回true
纹理混合模式 .combine(仅适用于 MeshBasicMaterial MeshLambertMaterial MeshPhongMaterial)	THREE.MultiplyOperation(默认)	乘法操作,环境贴图颜色 × 物体表面颜色 （使表面变暗，模拟基础反射）
	THREE.MixOperation	混合操作,使用 reflectivity 属性混合环境贴图和表面颜色 公式：mixColor = envColor * reflectivity + surfaceColor * (1-reflectivity)
	THREE.AddOperation	加法操作,环境贴图颜色 + 物体表面颜色 （使表面变亮，适合发光效果）
模板函数（Material.stencilFunc）	THREE.NeverStencilFunc	永远不通过
	THREE.LessStencilFunc	模板基准值 < 当前模板值时通过
	THREE.EqualStencilFunc	模板基准值 = 当前模板值时通过
	THREE.LessEqualStencilFunc	模板基准值 ≤ 当前模板值时通过
	THREE.GreaterStencilFunc	模板基准值 > 当前模板值时通过
	THREE.NotEqualStencilFunc	模板基准值 ≠ 当前模板值时通过
	THREE.GreaterEqualStencilFunc	模板基准值 ≥ 当前模板值时通过
	THREE.AlwaysStencilFunc	总是通过（默认值）
模板操作（.stencilOp/.stencilRef）	THREE.ZeroStencilOp	将模板值设置为0
	THREE.KeepStencilOp	保持当前模板值不变（默认值）
	THREE.ReplaceStencilOp	用模板基准值替换当前模板值
	THREE.IncrementStencilOp	当前模板值+1（最大255）
	THREE.DecrementStencilOp	当前模板值-1（最小0）
	THREE.IncrementWrapStencilOp	当前模板值+1（超过255则归0）
	THREE.DecrementWrapStencilOp	当前模板值-1（低于0则设为255）
	THREE.InvertStencilOp	按位反转当前模板值
GLSL版本（Material.glslVersion）	THREE.GLSL1	GLSL 1.0版本
	THREE.GLSL3	GLSL 3.0版本

示例

// 创建红色半透明材质
const material = new THREE.MeshStandardMaterial({
  color: 0xff0000,
  transparent: true,
  opacity: 0.7,
  side: THREE.DoubleSide
});

// 应用到球体
const sphere = new THREE.Mesh(
  new THREE.SphereGeometry(1, 32, 32),
  material
);
scene.add(sphere);