useMaterial

useMaterial 创建和管理 StandardMaterial，可应用到 Render。

用法

创建后赋给 Render，并动态更新：

演示

动态设置材质属性 - 查看代码

代码

material-example.jsx

// ↑ imports hidden
export const MaterialExample = () => {
    const materialProps = useControls(vars);
    const material = useMaterial({ 
      useMetalness: true,
      glossInvert: true,
      ...materialProps 
    });


    return (
      <Entity>
          <Render type="box" material={material} />
      </Entity>
    );
};

参数

配置对象与 StandardMaterial 属性接近。

参数

名称	类型与说明	默认值
userAttributes?	Map<any, any>	-
onUpdateShader?	UpdateShaderCallback | undefined 收集所有着色器生成器属性后、生成着色器代码前调用的自定义函数。接收根据当前材质和场景构建的设置对象，可修改并返回，返回值将替代原设置。适合为同一组对象基于同一材质生成不同着色器变体，例如使用材质纹理渲染深度或法线通道、使用简化着色器渲染反射通道。设置分为 StandardMaterialOptions 的通用标准材质选项与 LitShaderOptions 的光照选项。	-
shaderOptBuilder?	StandardMaterialOptionsBuilder	-
anisotropyMap?	Texture | null 材质各向异性贴图，默认 null。	-
anisotropyMapOffset?	[number, number] 控制各向异性贴图的二维偏移，各分量范围 0 到 1。	-
anisotropyMapRotation?	number 控制各向异性贴图的二维旋转，单位度。	-
anisotropyMapTiling?	[number, number] 控制各向异性贴图的二维平铺。	-
anisotropyMapUv?	number 各向异性贴图 UV 通道，有效范围 0 到 7。	-
aoMap?	Texture | null 主烘焙环境光遮蔽（AO）贴图，调制环境颜色，默认 null。	-
aoMapChannel?	string 主 AO 贴图使用的颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
aoMapOffset?	[number, number] 控制主 AO 贴图的二维偏移，各分量范围 0 到 1。	-
aoMapRotation?	number 控制主 AO 贴图的二维旋转，单位度。	-
aoMapTiling?	[number, number] 控制主 AO 贴图的二维平铺。	-
aoMapUv?	number 主 AO 贴图 UV 通道，有效范围 0 到 7。	-
aoDetailMap?	Texture | null 材质的细节烘焙 AO 贴图，默认 null，仅在主 AO 贴图非 null 时使用。	-
aoDetailMapChannel?	string 细节 AO 贴图颜色通道，可为 "r"、"g"、"b" 或 "a"，默认 "g"。	-
aoDetailMapOffset?	[number, number] 控制细节 AO 贴图的二维偏移，各分量范围 0 到 1。	-
aoDetailMapRotation?	number 控制细节 AO 贴图的二维旋转，单位度。	-
aoDetailMapTiling?	[number, number] 控制细节 AO 贴图的二维平铺。	-
aoDetailMapUv?	number 细节 AO 贴图 UV 通道，有效范围 0 到 7。	-
aoDetailMode?	string 主 AO 与细节 AO 贴图的混合方式：DETAILMODE_MUL 相乘；DETAILMODE_ADD 相加；DETAILMODE_SCREEN 为更柔和的相加；DETAILMODE_OVERLAY 按主颜色选择正片叠底或滤色；DETAILMODE_MIN 逐分量选择较暗值；DETAILMODE_MAX 逐分量选择较亮值。默认 DETAILMODE_MUL。	-
aoVertexColor?	boolean 使用网格顶点颜色作为 AO。若设置 aoMap，则与顶点颜色相乘。	-
aoVertexColorChannel?	string AO 使用的顶点颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
clearCoatGlossInvert?	boolean 反转清漆光泽度分量，默认 false。启用后将清漆光泽度属性视为粗糙度。	-
clearCoatGlossMap?	Texture | null 单通道清漆光泽度贴图，默认 null。若指定，则与归一化 clearCoatGloss 值及顶点颜色相乘。	-
clearCoatGlossMapChannel?	string 清漆光泽度贴图颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
clearCoatGlossMapOffset?	[number, number] 控制清漆光泽度贴图的二维偏移，各分量范围 0 到 1。	-
clearCoatGlossMapRotation?	number 控制清漆光泽度贴图的二维旋转，单位度。	-
clearCoatGlossMapTiling?	[number, number] 控制清漆光泽度贴图的二维平铺。	-
clearCoatGlossMapUv?	number 清漆光泽度贴图 UV 通道，有效范围 0 到 7。	-
clearCoatGlossVertexColor?	boolean 使用网格顶点颜色作为清漆光泽度。若设置 clearCoatGlossMap，则与顶点颜色相乘。	-
clearCoatGlossVertexColorChannel?	string 清漆光泽度使用的顶点颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
clearCoatMap?	Texture | null 单通道清漆强度贴图，默认 null。若指定，则与归一化 clearCoat 值及顶点颜色相乘。	-
clearCoatMapChannel?	string 清漆强度贴图颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
clearCoatMapOffset?	[number, number] 控制清漆强度贴图的二维偏移，各分量范围 0 到 1。	-
clearCoatMapRotation?	number 控制清漆强度贴图的二维旋转，单位度。	-
clearCoatMapTiling?	[number, number] 控制清漆强度贴图的二维平铺。	-
clearCoatMapUv?	number 清漆强度贴图 UV 通道，有效范围 0 到 7。	-
clearCoatNormalMap?	Texture | null 材质清漆法线贴图，默认 null，纹理必须包含归一化的切线空间法线。	-
clearCoatNormalMapOffset?	[number, number] 控制主清漆法线贴图的二维偏移，各分量范围 0 到 1。	-
clearCoatNormalMapRotation?	number 控制主清漆贴图的二维旋转，单位度。	-
clearCoatNormalMapTiling?	[number, number] 控制主清漆法线贴图的二维平铺。	-
clearCoatNormalMapUv?	number 清漆法线贴图 UV 通道，有效范围 0 到 7。	-
clearCoatVertexColor?	boolean 使用网格顶点颜色作为清漆强度。若设置 clearCoatMap，则与顶点颜色相乘。	-
clearCoatVertexColorChannel?	string 清漆强度使用的顶点颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
cubeMap?	Texture | null 材质的立方体环境贴图，默认 null。覆盖 sphereMap，并替代场景环境光照。	-
cubeMapProjection?	number cubeMap 投影类型：CUBEPROJ_NONE 将贴图视为无限远；CUBEPROJ_BOX 基于世界空间轴对齐包围盒进行盒投影。默认 CUBEPROJ_NONE。	-
diffuseDetailMap?	Texture | null 材质细节漫反射贴图，默认 null，仅在主漫反射贴图非 null 时使用。	-
diffuseDetailMapChannel?	string 细节漫反射贴图颜色通道，可为 "r"、"g"、"b"、"a"、"rgb" 或任意通道重排组合。	-
diffuseDetailMapOffset?	[number, number] 控制细节漫反射贴图的二维偏移，各分量范围 0 到 1。	-
diffuseDetailMapRotation?	number 控制细节漫反射贴图的二维旋转，单位度。	-
diffuseDetailMapTiling?	[number, number] 控制细节漫反射贴图的二维平铺。	-
diffuseDetailMapUv?	number 细节漫反射贴图 UV 通道，有效范围 0 到 7。	-
diffuseDetailMode?	string 主漫反射与细节漫反射贴图的混合方式：DETAILMODE_MUL 相乘；DETAILMODE_ADD 相加；DETAILMODE_SCREEN 为更柔和的相加；DETAILMODE_OVERLAY 按主颜色选择正片叠底或滤色；DETAILMODE_MIN 逐分量选择较暗值；DETAILMODE_MAX 逐分量选择较亮值。默认 DETAILMODE_MUL。	-
diffuseMap?	Texture | null 材质主漫反射贴图，默认 null。	-
diffuseMapChannel?	string 主漫反射贴图颜色通道，可为 "r"、"g"、"b"、"a"、"rgb" 或任意通道重排组合。	-
diffuseMapOffset?	[number, number] 控制主漫反射贴图的二维偏移，各分量范围 0 到 1。	-
diffuseMapRotation?	number 控制主漫反射贴图的二维旋转，单位度。	-
diffuseMapTiling?	[number, number] 控制主漫反射贴图的二维平铺。	-
diffuseMapUv?	number 主漫反射贴图 UV 通道，有效范围 0 到 7。	-
diffuseVertexColor?	boolean 将漫反射与网格顶点颜色相乘。	-
diffuseVertexColorChannel?	string 漫反射使用的顶点颜色通道，可为 "r"、"g"、"b"、"a"、"rgb" 或任意通道重排组合。	-
emissiveMap?	Texture | null 材质自发光贴图，默认 null，可使用 HDR。启用后自发光颜色与贴图纹素颜色相乘。由于默认自发光颜色为黑色，需先修改颜色才能看见贴图。	-
emissiveMapChannel?	string 自发光贴图颜色通道，可为 "r"、"g"、"b"、"a"、"rgb" 或任意通道重排组合。	-
emissiveMapOffset?	[number, number] 控制自发光贴图的二维偏移，各分量范围 0 到 1。	-
emissiveMapRotation?	number 控制自发光贴图的二维旋转，单位度。	-
emissiveMapTiling?	[number, number] 控制自发光贴图的二维平铺。	-
emissiveMapUv?	number 自发光贴图 UV 通道，有效范围 0 到 7。	-
emissiveVertexColor?	boolean 使用网格顶点颜色作为自发光。若设置 emissiveMap 或 emissive，则与顶点颜色相乘。	-
emissiveVertexColorChannel?	string 自发光使用的顶点颜色通道，可为 "r"、"g"、"b"、"a"、"rgb" 或任意通道重排组合。	-
enableGGXSpecular?	boolean 启用 GGX 镜面反射，并启用 anisotropyIntensity 参数以设置材质各向异性。	-
envAtlas?	Texture | null 预过滤环境光照图集，默认 null，覆盖 cubeMap 与 sphereMap，并替代场景环境光照。	-
fresnelModel?	number 定义菲涅耳效果公式。启用任一菲涅耳模型后，漫反射与反射按能量守恒方式组合；关闭时使用旧式非能量守恒组合。FRESNEL_NONE 无菲涅耳；FRESNEL_SCHLICK 为推荐的 Schlick 近似，以镜面反射颜色为参数。	-
glossInvert?	boolean 反转光泽度分量，默认 false。启用后将光泽度属性作为粗糙度处理。	-
glossMap?	Texture | null 光泽度贴图，默认 null。若指定，则与归一化光泽度值及顶点颜色相乘。	-
glossMapChannel?	string 光泽度贴图颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
glossMapOffset?	[number, number] 控制光泽度贴图的二维偏移，各分量范围 0 到 1。	-
glossMapRotation?	number 控制光泽度贴图的二维旋转，单位度。	-
glossMapTiling?	[number, number] 控制光泽度贴图的二维平铺。	-
glossMapUv?	number 光泽度贴图 UV 通道，有效范围 0 到 7。	-
glossVertexColor?	boolean 使用网格顶点颜色作为光泽度。若设置 glossMap，则与顶点颜色相乘。	-
glossVertexColorChannel?	string 光泽度使用的顶点颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
heightMap?	Texture | null 材质高度图，默认 null，用于随视角变化的视差效果。暗像素较低、亮像素较高，heightMapBase 选择原始几何体表面对应的高度值。建议与法线贴图结合。视差偏移会应用到材质所有其他贴图，因此高度图应使用相同平铺与偏移。	-
heightMapChannel?	string 高度图颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
heightMapOffset?	[number, number] 控制高度图二维偏移，各分量范围 0 到 1。	-
heightMapRotation?	number 控制高度图二维旋转，单位度。	-
heightMapTiling?	[number, number] 控制高度图二维平铺。	-
heightMapUv?	number 高度图 UV 通道，有效范围 0 到 7。	-
lightMap?	Texture | null 材质自定义光照贴图，默认 null，可为 HDR，包含预渲染的光照。若使用此材质的网格实例已有 Lightmapper 烘焙的独立光照贴图，则优先使用实例贴图。	-
lightMapChannel?	string 光照贴图颜色通道，可为 "r"、"g"、"b"、"a"、"rgb" 或任意通道重排组合。	-
lightMapOffset?	[number, number] 控制光照贴图二维偏移，各分量范围 0 到 1。	-
lightMapRotation?	number 控制光照贴图二维旋转，单位度。	-
lightMapTiling?	[number, number] 控制光照贴图二维平铺。	-
lightMapUv?	number 光照贴图 UV 通道，有效范围 0 到 7。	-
lightVertexColor?	boolean 使用烘焙顶点光照。若设置 lightMap，则与顶点颜色相乘。	-
lightVertexColorChannel?	string 烘焙光照使用的顶点颜色通道，可为 "r"、"g"、"b"、"a"、"rgb" 或任意通道重排组合。	-
metalnessMap?	Texture | null 单通道金属度贴图，默认 null。	-
metalnessMapChannel?	string 金属度贴图颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
metalnessMapOffset?	[number, number] 控制金属度贴图二维偏移，各分量范围 0 到 1。	-
metalnessMapRotation?	number 控制金属度贴图二维旋转，单位度。	-
metalnessMapTiling?	[number, number] 控制金属度贴图二维平铺。	-
metalnessMapUv?	number 金属度贴图 UV 通道，有效范围 0 到 7。	-
metalnessVertexColor?	boolean 使用网格顶点颜色作为金属度。若设置 metalnessMap，则与顶点颜色相乘。	-
metalnessVertexColorChannel?	string 金属度使用的顶点颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
normalDetailMap?	Texture | null 材质细节法线贴图，默认 null，仅在主法线贴图非 null 时使用。	-
normalDetailMapOffset?	[number, number] 控制细节法线贴图二维偏移，各分量范围 0 到 1。	-
normalDetailMapRotation?	number 控制细节法线贴图二维旋转，单位度。	-
normalDetailMapTiling?	[number, number] 控制细节法线贴图二维平铺。	-
normalDetailMapUv?	number 细节法线贴图 UV 通道，有效范围 0 到 7。	-
normalMap?	Texture | null 材质主法线贴图，默认 null，纹理必须包含归一化的切线空间法线。	-
normalMapOffset?	[number, number] 控制主法线贴图二维偏移，各分量范围 0 到 1。	-
normalMapRotation?	number 控制主法线贴图二维旋转，单位度。	-
normalMapTiling?	[number, number] 控制主法线贴图二维平铺。	-
normalMapUv?	number 主法线贴图 UV 通道，有效范围 0 到 7。	-
occludeDirect?	boolean AO 是否压暗方向光照，默认 false。	-
occludeSpecular?	number 使用环境光遮蔽压暗镜面反射与反射。这是近似处理，真实镜面遮蔽与视角有关，但通常优于完全没有。SPECOCC_NONE 无镜面遮蔽；SPECOCC_AO 直接使用 AO；SPECOCC_GLOSSDEPENDENT 根据材质光泽度与视角调整 AO 后遮蔽镜面反射。	-
opacityDither?	string 是否对不透明度进行抖动，实现无需 Alpha 混合的透明效果。DITHER_NONE 禁用；DITHER_BAYER2、BAYER4、BAYER8、BAYER16 分别使用 2、4、8、16 阶 Bayer 矩阵；DITHER_BLUENOISE 使用蓝噪声；DITHER_IGNNOISE 使用交错渐变噪声。默认 DITHER_NONE。	-
opacityShadowDither?	string 是否对阴影不透明度进行抖动，实现无需 Alpha 混合的透明阴影。DITHER_NONE 禁用；DITHER_BAYER2、BAYER4、BAYER8、BAYER16 分别使用 2、4、8、16 阶 Bayer 矩阵；DITHER_BLUENOISE 使用蓝噪声；DITHER_IGNNOISE 使用交错渐变噪声。默认 DITHER_NONE。	-
opacityFadesSpecular?	boolean 是否使用 opacity 淡出镜面反射与反射，默认 true。false 时使用 alphaFade 淡出材质。	-
opacityMap?	Texture | null 材质不透明度贴图，默认 null。	-
opacityMapChannel?	string 不透明度贴图颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
opacityMapOffset?	[number, number] 控制不透明度贴图二维偏移，各分量范围 0 到 1。	-
opacityMapRotation?	number 控制不透明度贴图二维旋转，单位度。	-
opacityMapTiling?	[number, number] 控制不透明度贴图二维平铺。	-
opacityMapUv?	number 不透明度贴图 UV 通道，有效范围 0 到 7。	-
opacityVertexColor?	boolean 使用网格顶点颜色作为不透明度。若设置 opacityMap，则与顶点颜色相乘。	-
opacityVertexColorChannel?	string 不透明度使用的顶点颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
pixelSnap?	boolean 渲染时将顶点对齐到像素坐标，适合像素精确的二维图形。	-
shadowCatcher?	boolean 启用时，将累积的方向阴影值在线性空间中作为颜色输出。	-
specularMap?	Texture | null 材质镜面反射贴图，默认 null。	-
specularMapChannel?	string 镜面反射贴图颜色通道，可为 "r"、"g"、"b"、"a"、"rgb" 或任意通道重排组合。	-
specularMapOffset?	[number, number] 控制镜面反射贴图二维偏移，各分量范围 0 到 1。	-
specularMapRotation?	number 控制镜面反射贴图二维旋转，单位度。	-
specularMapTiling?	[number, number] 控制镜面反射贴图二维平铺。	-
specularMapUv?	number 镜面反射贴图 UV 通道，有效范围 0 到 7。	-
specularVertexColor?	boolean 将镜面反射与网格顶点颜色相乘。	-
specularVertexColorChannel?	string 镜面反射使用的顶点颜色通道，可为 "r"、"g"、"b"、"a"、"rgb" 或任意通道重排组合。	-
specularityFactorMap?	Texture | null 以纹理表示的镜面反射强度因子，默认 null。	-
specularityFactorMapChannel?	string 镜面反射强度因子纹理的采样通道，默认 a。	-
specularityFactorMapOffset?	[number, number] 控制镜面反射强度因子贴图二维偏移，各分量范围 0 到 1。	-
specularityFactorMapRotation?	number 控制镜面反射强度因子贴图二维旋转，单位度。	-
specularityFactorMapTiling?	[number, number] 控制镜面反射强度因子贴图二维平铺。	-
specularityFactorMapUv?	number 镜面反射强度因子贴图 UV 通道，有效范围 0 到 7。	-
useSheen?	boolean 启用或禁用绒光镜面效果。	-
sheenMap?	Texture | null 材质绒光微结构颜色贴图，默认 null。	-
sheenMapChannel?	string 绒光贴图颜色通道，可为 "r"、"g"、"b"、"a"、"rgb" 或任意通道重排组合。	-
sheenMapOffset?	[number, number] 控制绒光贴图二维偏移，各分量范围 0 到 1。	-
sheenMapRotation?	number 控制绒光贴图二维旋转，单位度。	-
sheenMapTiling?	[number, number] 控制绒光贴图二维平铺。	-
sheenMapUv?	number 绒光贴图 UV 通道，有效范围 0 到 7。	-
sheenVertexColor?	boolean 使用网格顶点颜色作为绒光。若设置绒光贴图或绒光着色，则与顶点颜色相乘。	-
sheenVertexColorChannel?	string 绒光使用的顶点颜色通道，可为 "r"、"g"、"b"、"a"、"rgb" 或任意通道重排组合。	-
sphereMap?	Texture | null 材质球形环境贴图，默认 null，替代场景环境光照。	-
twoSidedLighting?	boolean 为背面计算正确法线及相应光照。	-
useFog?	boolean 应用场景设置中的雾效。	-
useTonemap?	boolean 应用 CameraComponent#toneMapping 配置的色调映射，默认 true。	-
useLighting?	boolean 应用光照。	-
useMetalness?	boolean 使用金属度属性替代镜面反射工作流。启用后，漫反射颜色也用于决定镜面反射，替代独立镜面贴图以节省空间。metalness 为 0 时像素是电介质，漫反射正常使用；为 1 时完全金属，漫反射颜色改用作镜面反射颜色。	-
useMetalnessSpecularColor?	boolean 启用金属度时，用镜面贴图对镜面反射着色。	-
useSkybox?	boolean 将场景天空盒用作预过滤环境贴图。	-
diffuse?	string 设置或获取材质漫反射颜色，以 sRGB 的 RGB 三分量表示，各分量范围 0 到 1。定义基本表面颜色，即反照率。	-
emissive?	string 设置或获取材质自发光颜色，以 sRGB 的 RGB 三分量表示，各分量范围 0 到 1。最终自发光为该颜色乘以 StandardMaterial#emissiveIntensity，若有自发光贴图还会与其相乘。	-
emissiveIntensity?	number 设置或获取自发光颜色倍率，默认 1。	-
ambient?	string 材质环境颜色，使用 sRGB 的 RGB 三分量，各分量范围 0 到 1。可获取此颜色。	-
specular?	string 材质镜面反射颜色，使用 sRGB 的 RGB 三分量，各分量范围 0 到 1。定义表面反射颜色，影响镜面强度和色调。可获取此颜色。	-
sheen?	string 绒光织物微纤维结构的镜面反射颜色，使用 sRGB 的 RGB 三分量，各分量范围 0 到 1。可获取材质绒光颜色。	-
attenuation?	string 折射材质衰减颜色，使用 sRGB，仅在 useDynamicRefraction 启用时使用。可获取此颜色。	-
specularityFactor?	number 镜面强度因子，用于加权菲涅耳与镜面反射，默认 1.0。可获取此因子。	-
sheenGloss?	number 绒光织物微纤维结构的光泽度，范围 0 到 1。可获取此值。	-
gloss?	number 材质光泽度，0 为粗糙，1 为光滑。glTF 导入材质启用 StandardMaterial#glossInvert，此时 gloss 表示粗糙度，0 为光滑、1 为粗糙。可获取此值。	-
aoIntensity?	number 环境光遮蔽强度，默认 1。可获取材质 AO 强度。	-
heightMapBase?	number 原始几何体表面对应的高度图值，范围 0 到 1，默认 0.5。高于基准部分凸出，低于部分凹入。设为 1 表示仅向内雕刻，0 表示仅向外抬高。两种视差模式均使用该值。可获取高度基准。	-
parallaxSamples?	number parallaxMode 为 PARALLAX_OCCLUSION 时，沿视线射线采样高度图的最大次数，默认 16。视线越接近表面法线，射线位移越小，使用的采样越少。对 PARALLAX_OFFSET 无效。可获取最大采样数。	-
parallaxShadowSamples?	number 沿每盏平行光方向采样高度图的最大次数，用于浮雕自阴影，0 禁用，默认 0。通过沿光线步进累积高度场高出光线的距离并按距离加权，产生软阴影；增加采样让半影更平滑，而非更早退出。仅作用于平行光且 parallaxMode 为 PARALLAX_OCCLUSION。可获取最大采样数。	-
opacity?	number 材质不透明度，范围 0 到 1，0 完全透明，1 完全不透明。半透明还需将 Material#blendType 设为 BLEND_NORMAL、BLEND_ADDITIVE 等混合模式。多数半透明对象应将 depthWrite 设为 false，否则可能完全遮挡后方对象。可获取不透明度。	-
alphaFade?	number opacityFadesSpecular 为 false 时用于淡出材质，可获取 alphaFade。	-
bumpiness?	number 材质凹凸强度，缩放主法线贴图。通常范围 0 到 1，分别表示无凹凸与完整凹凸，也可设为 2 等值增强效果。可获取此值。	-
normalDetailMapBumpiness?	number 材质细节凹凸强度，缩放细节法线贴图。通常范围 0 到 1，也可设为 2 等值增强效果。可获取此值。	-
reflectivity?	number 环境贴图强度，可获取材质环境贴图强度。	-
occludeSpecularIntensity?	number 控制镜面遮蔽可见程度，可获取镜面遮蔽强度。	-
refraction?	number 定义折射可见程度，材质可以折射用于反射的同一立方体贴图。可获取折射量。	-
refractionIndex?	number 定义折射比，即扭曲程度，计算为 outerIor / surfaceIor，分别是对象外介质与自身表面折射率。通常外部为空气，outerIor 约为 1，因此使用 1.0 / surfaceIor。可获取此值。	-
dispersion?	number 穿过体积时颜色角度分离即色差的强度，默认 0，表示无色散。可获取材质色散。	-
thickness?	number 介质厚度，仅在 useDynamicRefraction 启用时使用，单位为基础单位，并随对象尺寸缩放。可获取此厚度。	-
metalness?	number 定义表面金属程度，从 0（电介质）到 1（金属）。可获取材质金属度。	-
anisotropyIntensity?	number 定义各向异性强度，要求 enableGGXSpecular=true。0 为各向同性，数值增大到最大 1 时镜面各向异性逐渐增强。可获取此强度。	-
clearCoat?	number 定义清漆层强度，范围 0 到 1，0 禁用清漆层，默认 0。可获取此强度。	-
clearCoatGloss?	number 定义清漆层光泽度，从 0（粗糙）到 1（镜面）。可获取此值。	-
clearCoatBumpiness?	number 清漆层凹凸强度，缩放主清漆法线贴图。通常为 0 到 1，也可用 2 等值强化凹凸。可获取此值。	-
iridescence?	number 定义虹彩层强度，范围 0 到 1，仅在 useIridescence 启用时使用。0 禁用，若有 iridescenceMap 则与该值相乘，默认 0。可获取此强度。	-
iridescenceRefractionIndex?	number 虹彩薄膜折射率，影响颜色相位偏移，原理见 https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_materials_iridescence 。可获取此值。	-
iridescenceThicknessMin?	number 虹彩层最小厚度，仅在使用虹彩厚度贴图时有效，单位纳米。可获取此值。	-
iridescenceThicknessMax?	number 虹彩层最大厚度，未定义厚度贴图时作为基础厚度，单位纳米。可获取此值。	-
anisotropyRotation?	number 定义各向异性旋转角度，单位度。可获取此值。	-
attenuationDistance?	number 定义介质光吸收速率的距离，仅在 useDynamicRefraction 启用时使用。可获取衰减距离。	-
heightMapFactor?	number 高度图倍率，默认 1，影响视差强度。1 最多将纹理偏移 UV 地块的 5%，常用范围 0 到 2。可获取此因子。	-
alphaDither?	number 不透明度抖动所用 Alpha，范围 [0, 1]，独立于继续驱动 Alpha 混合的 opacity。因此材质可同时以不同强度混合与抖动，例如相机靠近玻璃时用抖动淡出并保留玻璃混合外观。仅在 opacityDither 或 opacityShadowDither 启用抖动模式时有效。设为 1.0 可在运行时关闭抖动而不改模式，0.0 完全丢弃。为向后兼容，从未赋值时使用 opacity，与旧行为一致。可获取此值。	-
cubeMapProjectionBox?	BoundingBox | null 设置 cubeMap 盒投影的世界空间轴对齐包围盒，null 表示无盒。仅在 cubeMapProjection 为 CUBEPROJ_BOX 时使用，传入包围盒会复制到材质。获取时返回包围盒或 null，修改其中心或半尺寸后调用 StandardMaterial#update 应用。	-
userId?	string 用户可为材质指定的唯一 ID，引擎内部不使用，可自行赋予任意用途。默认为空字符串。	-
id?	number	-
parameters?	{}	-
alphaToCoverage?	boolean 启用或禁用 Alpha 覆盖率。硬件抗锯齿开启时可实现有限的顺序无关透明，质量取决于当前目标的 MSAA 采样数，适合柔化 Alpha 裁剪边缘，不推荐大面积半透明表面，无需启用混合。要求多重采样目标，单采样时静默忽略。WebGPU 还要求第一个颜色附件使用带 Alpha 的可混合格式，否则也忽略；CameraFrame 默认 HDR 格式 PIXELFORMAT_111110F 没有 Alpha。	-
cull?	number 控制按面相对视点方向剔除三角形：CULLFACE_NONE 不剔除；CULLFACE_BACK 剔除背面；CULLFACE_FRONT 剔除正面。默认 CULLFACE_BACK。	-
frontFace?	number 通过顶点绕序定义多边形正反面。FRONTFACE_CW 为顺时针，FRONTFACE_CCW 为逆时针，默认 FRONTFACE_CCW。	-
stencilFront?	StencilParameters | null 正面模板参数，默认 null。	-
stencilBack?	StencilParameters | null 背面模板参数，默认 null。	-
flatShading?	boolean 启用或禁用平面着色，默认 false。启用时使用片元所在三角形的几何法线而非插值顶点法线，产生分面外观，也支持蒙皮和形变。几何法线按 Material#frontFace 的绕序定向，与正确制作的顶点法线一致，因此 cull、frontFace、twoSidedLighting 与平滑着色保持相同行为。StandardMaterial 和 LitMaterial 自动支持；ShaderMaterial 只添加 FLAT_SHADING 定义，需自定义代码处理，可用 flatNormalPS 代码块的 getFlatNormal： ```javascript #include "flatNormalPS" ... #ifdef FLAT_SHADING vec3 normal = getFlatNormal(worldPos); #else vec3 normal = normalize(interpolatedNormal); #endif ``` 与其他材质属性相同，修改后调用 Material#update。可获取平面着色状态。	-
shaderChunksVersion?	string 设置或获取着色器代码块版本，应为当前引擎主版本与次版本字符串，例如 v2.8.1 使用 "2.8"。自定义代码块应指定最新支持版本。未来引擎不再支持时会警告，此时应更新代码块格式并相应调整版本。	-
alphaTest?	number 设置或获取 Alpha 测试参考值。Alpha 小于 alphaTest 的片元会被丢弃，不写入当前渲染目标。默认 0，全部通过。	-
depthBias?	number 设置或获取输出深度值偏移，适用于避免贴花深度冲突。通常用小负值，例如 -0.1，使网格略靠近相机。	-
slopeDepthBias?	number 设置或获取基于三角形相对相机斜率的输出深度偏移。	-
redWrite?	boolean 设置或获取是否向当前渲染目标颜色缓冲区写入红色通道，默认 true；false 时不写入红色分量。	-
greenWrite?	boolean 设置或获取是否向当前渲染目标颜色缓冲区写入绿色通道，默认 true；false 时不写入绿色分量。	-
blueWrite?	boolean 设置或获取是否向当前渲染目标颜色缓冲区写入蓝色通道，默认 true；false 时不写入蓝色分量。	-
alphaWrite?	boolean 设置或获取是否向当前渲染目标颜色缓冲区写入 Alpha 通道，默认 true；false 时不写入 Alpha。	-
blendState?	Readonly<BlendState> 设置或获取材质混合状态，控制片元输出写入当前目标时如何混合。覆盖 blendType，提供更精细控制。更新透明度与排序状态时使用 setter。	-
blendType?	number 设置或获取材质混合模式，默认 BLEND_NONE。BLEND_SUBTRACTIVE 从目标减去源颜色；BLEND_ADDITIVE 相加；BLEND_NORMAL 常规半透明，相当于源 SRC_ALPHA、目标 ONE_MINUS_SRC_ALPHA；BLEND_NONE 禁用；BLEND_PREMULTIPLIED 类似 NORMAL，但源已乘 Alpha；BLEND_MULTIPLICATIVE 相乘；BLEND_ADDITIVEALPHA 先将源 RGB 乘 Alpha 再相加；BLEND_MULTIPLICATIVE2X 相乘后乘 2；BLEND_SCREEN 为更柔和的叠加；BLEND_MIN 取较小颜色；BLEND_MAX 取较大颜色。	-
depthState?	DepthState 设置或获取深度状态，也可分别用 depthTest、depthFunc 和 depthWrite 配置。	-
depthTest?	boolean 设置或获取是否启用深度测试，默认 true。启用时只有通过测试的片元才写入当前目标；禁用时不考虑深度缓冲区。与 depthFunc 的关系见 DepthState#test，深度写入由 depthWrite 独立控制。	-
depthFunc?	number 设置或获取深度比较函数，默认 FUNC_LESSEQUAL。FUNC_NEVER 永不绘制；FUNC_LESS 新深度小于缓冲区时绘制；FUNC_EQUAL 相等；FUNC_LESSEQUAL 小于等于；FUNC_GREATER 大于；FUNC_NOTEQUAL 不等；FUNC_GREATEREQUAL 大于等于；FUNC_ALWAYS 始终绘制。	-
depthWrite?	boolean 设置或获取是否向当前渲染目标的深度缓冲区写入片元深度，默认 true。false 时不写深度。	-

返回值

返回可赋给 Render 的 StandardMaterial。

名称	类型与说明	默认值
userAttributes	Map<any, any>	-
_specularIsBlack	any 上次更新时镜面反射颜色是否为黑色。	-
_textureSharing	any 上次更新时哪些已指定贴图共享纹理。	-
_sharingCheckedVersion	any 最近一次检查纹理共享时的纹理分配版本。	-
_mapTransforms	any 纹理变换分组状态。	-
onUpdateShader	UpdateShaderCallback | undefined 收集所有着色器生成器属性后、生成着色器代码前调用的自定义函数。接收根据当前材质和场景构建的设置对象，可修改并返回，返回值将替代原设置。适合为同一组对象基于同一材质生成不同着色器变体，例如使用材质纹理渲染深度或法线通道、使用简化着色器渲染反射通道。设置分为 StandardMaterialOptions 的通用标准材质选项与 LitShaderOptions 的光照选项。	-
_assetReferences	{}	-
_activeParams	Set<any>	-
shaderOptBuilder	StandardMaterialOptionsBuilder	-
reset	() => void	-
anisotropyMap	Texture | null 材质各向异性贴图，默认 null。	-
anisotropyMapOffset	Vec2 控制各向异性贴图的二维偏移，各分量范围 0 到 1。	-
anisotropyMapRotation	number 控制各向异性贴图的二维旋转，单位度。	-
anisotropyMapTiling	Vec2 控制各向异性贴图的二维平铺。	-
anisotropyMapUv	number 各向异性贴图 UV 通道，有效范围 0 到 7。	-
aoMap	Texture | null 主烘焙环境光遮蔽（AO）贴图，调制环境颜色，默认 null。	-
aoMapChannel	string 主 AO 贴图使用的颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
aoMapOffset	Vec2 控制主 AO 贴图的二维偏移，各分量范围 0 到 1。	-
aoMapRotation	number 控制主 AO 贴图的二维旋转，单位度。	-
aoMapTiling	Vec2 控制主 AO 贴图的二维平铺。	-
aoMapUv	number 主 AO 贴图 UV 通道，有效范围 0 到 7。	-
aoDetailMap	Texture | null 材质的细节烘焙 AO 贴图，默认 null，仅在主 AO 贴图非 null 时使用。	-
aoDetailMapChannel	string 细节 AO 贴图颜色通道，可为 "r"、"g"、"b" 或 "a"，默认 "g"。	-
aoDetailMapOffset	Vec2 控制细节 AO 贴图的二维偏移，各分量范围 0 到 1。	-
aoDetailMapRotation	number 控制细节 AO 贴图的二维旋转，单位度。	-
aoDetailMapTiling	Vec2 控制细节 AO 贴图的二维平铺。	-
aoDetailMapUv	number 细节 AO 贴图 UV 通道，有效范围 0 到 7。	-
aoDetailMode	string 主 AO 与细节 AO 贴图的混合方式：DETAILMODE_MUL 相乘；DETAILMODE_ADD 相加；DETAILMODE_SCREEN 为更柔和的相加；DETAILMODE_OVERLAY 按主颜色选择正片叠底或滤色；DETAILMODE_MIN 逐分量选择较暗值；DETAILMODE_MAX 逐分量选择较亮值。默认 DETAILMODE_MUL。	-
aoVertexColor	boolean 使用网格顶点颜色作为 AO。若设置 aoMap，则与顶点颜色相乘。	-
aoVertexColorChannel	string AO 使用的顶点颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
clearCoatGlossInvert	boolean 反转清漆光泽度分量，默认 false。启用后将清漆光泽度属性视为粗糙度。	-
clearCoatGlossMap	Texture | null 单通道清漆光泽度贴图，默认 null。若指定，则与归一化 clearCoatGloss 值及顶点颜色相乘。	-
clearCoatGlossMapChannel	string 清漆光泽度贴图颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
clearCoatGlossMapOffset	Vec2 控制清漆光泽度贴图的二维偏移，各分量范围 0 到 1。	-
clearCoatGlossMapRotation	number 控制清漆光泽度贴图的二维旋转，单位度。	-
clearCoatGlossMapTiling	Vec2 控制清漆光泽度贴图的二维平铺。	-
clearCoatGlossMapUv	number 清漆光泽度贴图 UV 通道，有效范围 0 到 7。	-
clearCoatGlossVertexColor	boolean 使用网格顶点颜色作为清漆光泽度。若设置 clearCoatGlossMap，则与顶点颜色相乘。	-
clearCoatGlossVertexColorChannel	string 清漆光泽度使用的顶点颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
clearCoatMap	Texture | null 单通道清漆强度贴图，默认 null。若指定，则与归一化 clearCoat 值及顶点颜色相乘。	-
clearCoatMapChannel	string 清漆强度贴图颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
clearCoatMapOffset	Vec2 控制清漆强度贴图的二维偏移，各分量范围 0 到 1。	-
clearCoatMapRotation	number 控制清漆强度贴图的二维旋转，单位度。	-
clearCoatMapTiling	Vec2 控制清漆强度贴图的二维平铺。	-
clearCoatMapUv	number 清漆强度贴图 UV 通道，有效范围 0 到 7。	-
clearCoatNormalMap	Texture | null 材质清漆法线贴图，默认 null，纹理必须包含归一化的切线空间法线。	-
clearCoatNormalMapOffset	Vec2 控制主清漆法线贴图的二维偏移，各分量范围 0 到 1。	-
clearCoatNormalMapRotation	number 控制主清漆贴图的二维旋转，单位度。	-
clearCoatNormalMapTiling	Vec2 控制主清漆法线贴图的二维平铺。	-
clearCoatNormalMapUv	number 清漆法线贴图 UV 通道，有效范围 0 到 7。	-
clearCoatVertexColor	boolean 使用网格顶点颜色作为清漆强度。若设置 clearCoatMap，则与顶点颜色相乘。	-
clearCoatVertexColorChannel	string 清漆强度使用的顶点颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
cubeMap	Texture | null 材质的立方体环境贴图，默认 null。覆盖 sphereMap，并替代场景环境光照。	-
cubeMapProjection	number cubeMap 投影类型：CUBEPROJ_NONE 将贴图视为无限远；CUBEPROJ_BOX 基于世界空间轴对齐包围盒进行盒投影。默认 CUBEPROJ_NONE。	-
diffuseDetailMap	Texture | null 材质细节漫反射贴图，默认 null，仅在主漫反射贴图非 null 时使用。	-
diffuseDetailMapChannel	string 细节漫反射贴图颜色通道，可为 "r"、"g"、"b"、"a"、"rgb" 或任意通道重排组合。	-
diffuseDetailMapOffset	Vec2 控制细节漫反射贴图的二维偏移，各分量范围 0 到 1。	-
diffuseDetailMapRotation	number 控制细节漫反射贴图的二维旋转，单位度。	-
diffuseDetailMapTiling	Vec2 控制细节漫反射贴图的二维平铺。	-
diffuseDetailMapUv	number 细节漫反射贴图 UV 通道，有效范围 0 到 7。	-
diffuseDetailMode	string 主漫反射与细节漫反射贴图的混合方式：DETAILMODE_MUL 相乘；DETAILMODE_ADD 相加；DETAILMODE_SCREEN 为更柔和的相加；DETAILMODE_OVERLAY 按主颜色选择正片叠底或滤色；DETAILMODE_MIN 逐分量选择较暗值；DETAILMODE_MAX 逐分量选择较亮值。默认 DETAILMODE_MUL。	-
diffuseMap	Texture | null 材质主漫反射贴图，默认 null。	-
diffuseMapChannel	string 主漫反射贴图颜色通道，可为 "r"、"g"、"b"、"a"、"rgb" 或任意通道重排组合。	-
diffuseMapOffset	Vec2 控制主漫反射贴图的二维偏移，各分量范围 0 到 1。	-
diffuseMapRotation	number 控制主漫反射贴图的二维旋转，单位度。	-
diffuseMapTiling	Vec2 控制主漫反射贴图的二维平铺。	-
diffuseMapUv	number 主漫反射贴图 UV 通道，有效范围 0 到 7。	-
diffuseVertexColor	boolean 将漫反射与网格顶点颜色相乘。	-
diffuseVertexColorChannel	string 漫反射使用的顶点颜色通道，可为 "r"、"g"、"b"、"a"、"rgb" 或任意通道重排组合。	-
emissiveMap	Texture | null 材质自发光贴图，默认 null，可使用 HDR。启用后自发光颜色与贴图纹素颜色相乘。由于默认自发光颜色为黑色，需先修改颜色才能看见贴图。	-
emissiveMapChannel	string 自发光贴图颜色通道，可为 "r"、"g"、"b"、"a"、"rgb" 或任意通道重排组合。	-
emissiveMapOffset	Vec2 控制自发光贴图的二维偏移，各分量范围 0 到 1。	-
emissiveMapRotation	number 控制自发光贴图的二维旋转，单位度。	-
emissiveMapTiling	Vec2 控制自发光贴图的二维平铺。	-
emissiveMapUv	number 自发光贴图 UV 通道，有效范围 0 到 7。	-
emissiveVertexColor	boolean 使用网格顶点颜色作为自发光。若设置 emissiveMap 或 emissive，则与顶点颜色相乘。	-
emissiveVertexColorChannel	string 自发光使用的顶点颜色通道，可为 "r"、"g"、"b"、"a"、"rgb" 或任意通道重排组合。	-
enableGGXSpecular	boolean 启用 GGX 镜面反射，并启用 anisotropyIntensity 参数以设置材质各向异性。	-
envAtlas	Texture | null 预过滤环境光照图集，默认 null，覆盖 cubeMap 与 sphereMap，并替代场景环境光照。	-
fresnelModel	number 定义菲涅耳效果公式。启用任一菲涅耳模型后，漫反射与反射按能量守恒方式组合；关闭时使用旧式非能量守恒组合。FRESNEL_NONE 无菲涅耳；FRESNEL_SCHLICK 为推荐的 Schlick 近似，以镜面反射颜色为参数。	-
glossInvert	boolean 反转光泽度分量，默认 false。启用后将光泽度属性作为粗糙度处理。	-
glossMap	Texture | null 光泽度贴图，默认 null。若指定，则与归一化光泽度值及顶点颜色相乘。	-
glossMapChannel	string 光泽度贴图颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
glossMapOffset	Vec2 控制光泽度贴图的二维偏移，各分量范围 0 到 1。	-
glossMapRotation	number 控制光泽度贴图的二维旋转，单位度。	-
glossMapTiling	Vec2 控制光泽度贴图的二维平铺。	-
glossMapUv	number 光泽度贴图 UV 通道，有效范围 0 到 7。	-
glossVertexColor	boolean 使用网格顶点颜色作为光泽度。若设置 glossMap，则与顶点颜色相乘。	-
glossVertexColorChannel	string 光泽度使用的顶点颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
heightMap	Texture | null 材质高度图，默认 null，用于随视角变化的视差效果。暗像素较低、亮像素较高，heightMapBase 选择原始几何体表面对应的高度值。建议与法线贴图结合。视差偏移会应用到材质所有其他贴图，因此高度图应使用相同平铺与偏移。	-
heightMapChannel	string 高度图颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
heightMapOffset	Vec2 控制高度图二维偏移，各分量范围 0 到 1。	-
heightMapRotation	number 控制高度图二维旋转，单位度。	-
heightMapTiling	Vec2 控制高度图二维平铺。	-
heightMapUv	number 高度图 UV 通道，有效范围 0 到 7。	-
lightMap	Texture | null 材质自定义光照贴图，默认 null，可为 HDR，包含预渲染的光照。若使用此材质的网格实例已有 Lightmapper 烘焙的独立光照贴图，则优先使用实例贴图。	-
lightMapChannel	string 光照贴图颜色通道，可为 "r"、"g"、"b"、"a"、"rgb" 或任意通道重排组合。	-
lightMapOffset	Vec2 控制光照贴图二维偏移，各分量范围 0 到 1。	-
lightMapRotation	number 控制光照贴图二维旋转，单位度。	-
lightMapTiling	Vec2 控制光照贴图二维平铺。	-
lightMapUv	number 光照贴图 UV 通道，有效范围 0 到 7。	-
lightVertexColor	boolean 使用烘焙顶点光照。若设置 lightMap，则与顶点颜色相乘。	-
lightVertexColorChannel	string 烘焙光照使用的顶点颜色通道，可为 "r"、"g"、"b"、"a"、"rgb" 或任意通道重排组合。	-
metalnessMap	Texture | null 单通道金属度贴图，默认 null。	-
metalnessMapChannel	string 金属度贴图颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
metalnessMapOffset	Vec2 控制金属度贴图二维偏移，各分量范围 0 到 1。	-
metalnessMapRotation	number 控制金属度贴图二维旋转，单位度。	-
metalnessMapTiling	Vec2 控制金属度贴图二维平铺。	-
metalnessMapUv	number 金属度贴图 UV 通道，有效范围 0 到 7。	-
metalnessVertexColor	boolean 使用网格顶点颜色作为金属度。若设置 metalnessMap，则与顶点颜色相乘。	-
metalnessVertexColorChannel	string 金属度使用的顶点颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
normalDetailMap	Texture | null 材质细节法线贴图，默认 null，仅在主法线贴图非 null 时使用。	-
normalDetailMapOffset	Vec2 控制细节法线贴图二维偏移，各分量范围 0 到 1。	-
normalDetailMapRotation	number 控制细节法线贴图二维旋转，单位度。	-
normalDetailMapTiling	Vec2 控制细节法线贴图二维平铺。	-
normalDetailMapUv	number 细节法线贴图 UV 通道，有效范围 0 到 7。	-
normalMap	Texture | null 材质主法线贴图，默认 null，纹理必须包含归一化的切线空间法线。	-
normalMapOffset	Vec2 控制主法线贴图二维偏移，各分量范围 0 到 1。	-
normalMapRotation	number 控制主法线贴图二维旋转，单位度。	-
normalMapTiling	Vec2 控制主法线贴图二维平铺。	-
normalMapUv	number 主法线贴图 UV 通道，有效范围 0 到 7。	-
occludeDirect	boolean AO 是否压暗方向光照，默认 false。	-
occludeSpecular	number 使用环境光遮蔽压暗镜面反射与反射。这是近似处理，真实镜面遮蔽与视角有关，但通常优于完全没有。SPECOCC_NONE 无镜面遮蔽；SPECOCC_AO 直接使用 AO；SPECOCC_GLOSSDEPENDENT 根据材质光泽度与视角调整 AO 后遮蔽镜面反射。	-
opacityDither	string 是否对不透明度进行抖动，实现无需 Alpha 混合的透明效果。DITHER_NONE 禁用；DITHER_BAYER2、BAYER4、BAYER8、BAYER16 分别使用 2、4、8、16 阶 Bayer 矩阵；DITHER_BLUENOISE 使用蓝噪声；DITHER_IGNNOISE 使用交错渐变噪声。默认 DITHER_NONE。	-
opacityShadowDither	string 是否对阴影不透明度进行抖动，实现无需 Alpha 混合的透明阴影。DITHER_NONE 禁用；DITHER_BAYER2、BAYER4、BAYER8、BAYER16 分别使用 2、4、8、16 阶 Bayer 矩阵；DITHER_BLUENOISE 使用蓝噪声；DITHER_IGNNOISE 使用交错渐变噪声。默认 DITHER_NONE。	-
opacityFadesSpecular	boolean 是否使用 opacity 淡出镜面反射与反射，默认 true。false 时使用 alphaFade 淡出材质。	-
opacityMap	Texture | null 材质不透明度贴图，默认 null。	-
opacityMapChannel	string 不透明度贴图颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
opacityMapOffset	Vec2 控制不透明度贴图二维偏移，各分量范围 0 到 1。	-
opacityMapRotation	number 控制不透明度贴图二维旋转，单位度。	-
opacityMapTiling	Vec2 控制不透明度贴图二维平铺。	-
opacityMapUv	number 不透明度贴图 UV 通道，有效范围 0 到 7。	-
opacityVertexColor	boolean 使用网格顶点颜色作为不透明度。若设置 opacityMap，则与顶点颜色相乘。	-
opacityVertexColorChannel	string 不透明度使用的顶点颜色通道，可为 "r"、"g"、"b" 或 "a"。	-
pixelSnap	boolean 渲染时将顶点对齐到像素坐标，适合像素精确的二维图形。	-
shadowCatcher	boolean 启用时，将累积的方向阴影值在线性空间中作为颜色输出。	-
specularMap	Texture | null 材质镜面反射贴图，默认 null。	-
specularMapChannel	string 镜面反射贴图颜色通道，可为 "r"、"g"、"b"、"a"、"rgb" 或任意通道重排组合。	-
specularMapOffset	Vec2 控制镜面反射贴图二维偏移，各分量范围 0 到 1。	-
specularMapRotation	number 控制镜面反射贴图二维旋转，单位度。	-
specularMapTiling	Vec2 控制镜面反射贴图二维平铺。	-
specularMapUv	number 镜面反射贴图 UV 通道，有效范围 0 到 7。	-
specularVertexColor	boolean 将镜面反射与网格顶点颜色相乘。	-
specularVertexColorChannel	string 镜面反射使用的顶点颜色通道，可为 "r"、"g"、"b"、"a"、"rgb" 或任意通道重排组合。	-
specularityFactorMap	Texture | null 以纹理表示的镜面反射强度因子，默认 null。	-
specularityFactorMapChannel	string 镜面反射强度因子纹理的采样通道，默认 a。	-
specularityFactorMapOffset	Vec2 控制镜面反射强度因子贴图二维偏移，各分量范围 0 到 1。	-
specularityFactorMapRotation	number 控制镜面反射强度因子贴图二维旋转，单位度。	-
specularityFactorMapTiling	Vec2 控制镜面反射强度因子贴图二维平铺。	-
specularityFactorMapUv	number 镜面反射强度因子贴图 UV 通道，有效范围 0 到 7。	-
useSheen	boolean 启用或禁用绒光镜面效果。	-
sheenMap	Texture | null 材质绒光微结构颜色贴图，默认 null。	-
sheenMapChannel	string 绒光贴图颜色通道，可为 "r"、"g"、"b"、"a"、"rgb" 或任意通道重排组合。	-
sheenMapOffset	Vec2 控制绒光贴图二维偏移，各分量范围 0 到 1。	-
sheenMapRotation	number 控制绒光贴图二维旋转，单位度。	-
sheenMapTiling	Vec2 控制绒光贴图二维平铺。	-
sheenMapUv	number 绒光贴图 UV 通道，有效范围 0 到 7。	-
sheenVertexColor	boolean 使用网格顶点颜色作为绒光。若设置绒光贴图或绒光着色，则与顶点颜色相乘。	-
sheenVertexColorChannel	string 绒光使用的顶点颜色通道，可为 "r"、"g"、"b"、"a"、"rgb" 或任意通道重排组合。	-
sphereMap	Texture | null 材质球形环境贴图，默认 null，替代场景环境光照。	-
twoSidedLighting	boolean 为背面计算正确法线及相应光照。	-
useFog	boolean 应用场景设置中的雾效。	-
useTonemap	boolean 应用 CameraComponent#toneMapping 配置的色调映射，默认 true。	-
useLighting	boolean 应用光照。	-
useMetalness	boolean 使用金属度属性替代镜面反射工作流。启用后，漫反射颜色也用于决定镜面反射，替代独立镜面贴图以节省空间。metalness 为 0 时像素是电介质，漫反射正常使用；为 1 时完全金属，漫反射颜色改用作镜面反射颜色。	-
useMetalnessSpecularColor	boolean 启用金属度时，用镜面贴图对镜面反射着色。	-
useSkybox	boolean 将场景天空盒用作预过滤环境贴图。	-
_collectUnappliedChanges	any 记录已修改但尚未调用 update 的贴图属性名称，用于未应用修改的调试警告。	-
diffuse	Color 设置或获取材质漫反射颜色，以 sRGB 的 RGB 三分量表示，各分量范围 0 到 1。定义基本表面颜色，即反照率。	-
emissive	Color 设置或获取材质自发光颜色，以 sRGB 的 RGB 三分量表示，各分量范围 0 到 1。最终自发光为该颜色乘以 StandardMaterial#emissiveIntensity，若有自发光贴图还会与其相乘。	-
emissiveIntensity	number 设置或获取自发光颜色倍率，默认 1。	-
_emissiveIntensity	any	-
ambient	Color 材质环境颜色，使用 sRGB 的 RGB 三分量，各分量范围 0 到 1。可获取此颜色。	-
specular	Color 材质镜面反射颜色，使用 sRGB 的 RGB 三分量，各分量范围 0 到 1。定义表面反射颜色，影响镜面强度和色调。可获取此颜色。	-
sheen	Color 绒光织物微纤维结构的镜面反射颜色，使用 sRGB 的 RGB 三分量，各分量范围 0 到 1。可获取材质绒光颜色。	-
attenuation	Color 折射材质衰减颜色，使用 sRGB，仅在 useDynamicRefraction 启用时使用。可获取此颜色。	-
specularityFactor	number 镜面强度因子，用于加权菲涅耳与镜面反射，默认 1.0。可获取此因子。	-
_specularityFactor	any	-
sheenGloss	number 绒光织物微纤维结构的光泽度，范围 0 到 1。可获取此值。	-
_sheenGloss	any	-
gloss	number 材质光泽度，0 为粗糙，1 为光滑。glTF 导入材质启用 StandardMaterial#glossInvert，此时 gloss 表示粗糙度，0 为光滑、1 为粗糙。可获取此值。	-
_gloss	any	-
aoIntensity	number 环境光遮蔽强度，默认 1。可获取材质 AO 强度。	-
_aoIntensity	any	-
heightMapBase	number 原始几何体表面对应的高度图值，范围 0 到 1，默认 0.5。高于基准部分凸出，低于部分凹入。设为 1 表示仅向内雕刻，0 表示仅向外抬高。两种视差模式均使用该值。可获取高度基准。	-
_heightMapBase	any	-
parallaxSamples	number parallaxMode 为 PARALLAX_OCCLUSION 时，沿视线射线采样高度图的最大次数，默认 16。视线越接近表面法线，射线位移越小，使用的采样越少。对 PARALLAX_OFFSET 无效。可获取最大采样数。	-
_parallaxSamples	any	-
parallaxShadowSamples	number 沿每盏平行光方向采样高度图的最大次数，用于浮雕自阴影，0 禁用，默认 0。通过沿光线步进累积高度场高出光线的距离并按距离加权，产生软阴影；增加采样让半影更平滑，而非更早退出。仅作用于平行光且 parallaxMode 为 PARALLAX_OCCLUSION。可获取最大采样数。	-
_parallaxShadowSamples	any	-
opacity	number 材质不透明度，范围 0 到 1，0 完全透明，1 完全不透明。半透明还需将 Material#blendType 设为 BLEND_NORMAL、BLEND_ADDITIVE 等混合模式。多数半透明对象应将 depthWrite 设为 false，否则可能完全遮挡后方对象。可获取不透明度。	-
_opacity	any	-
alphaFade	number opacityFadesSpecular 为 false 时用于淡出材质，可获取 alphaFade。	-
_alphaFade	any	-
bumpiness	number 材质凹凸强度，缩放主法线贴图。通常范围 0 到 1，分别表示无凹凸与完整凹凸，也可设为 2 等值增强效果。可获取此值。	-
_bumpiness	any	-
normalDetailMapBumpiness	number 材质细节凹凸强度，缩放细节法线贴图。通常范围 0 到 1，也可设为 2 等值增强效果。可获取此值。	-
_normalDetailMapBumpiness	any	-
reflectivity	number 环境贴图强度，可获取材质环境贴图强度。	-
_reflectivity	any	-
occludeSpecularIntensity	number 控制镜面遮蔽可见程度，可获取镜面遮蔽强度。	-
_occludeSpecularIntensity	any	-
refraction	number 定义折射可见程度，材质可以折射用于反射的同一立方体贴图。可获取折射量。	-
_refraction	any	-
refractionIndex	number 定义折射比，即扭曲程度，计算为 outerIor / surfaceIor，分别是对象外介质与自身表面折射率。通常外部为空气，outerIor 约为 1，因此使用 1.0 / surfaceIor。可获取此值。	-
_refractionIndex	any	-
dispersion	number 穿过体积时颜色角度分离即色差的强度，默认 0，表示无色散。可获取材质色散。	-
_dispersion	any	-
thickness	number 介质厚度，仅在 useDynamicRefraction 启用时使用，单位为基础单位，并随对象尺寸缩放。可获取此厚度。	-
_thickness	any	-
metalness	number 定义表面金属程度，从 0（电介质）到 1（金属）。可获取材质金属度。	-
_metalness	any	-
anisotropyIntensity	number 定义各向异性强度，要求 enableGGXSpecular=true。0 为各向同性，数值增大到最大 1 时镜面各向异性逐渐增强。可获取此强度。	-
_anisotropyIntensity	any	-
clearCoat	number 定义清漆层强度，范围 0 到 1，0 禁用清漆层，默认 0。可获取此强度。	-
_clearCoat	any	-
clearCoatGloss	number 定义清漆层光泽度，从 0（粗糙）到 1（镜面）。可获取此值。	-
_clearCoatGloss	any	-
clearCoatBumpiness	number 清漆层凹凸强度，缩放主清漆法线贴图。通常为 0 到 1，也可用 2 等值强化凹凸。可获取此值。	-
_clearCoatBumpiness	any	-
iridescence	number 定义虹彩层强度，范围 0 到 1，仅在 useIridescence 启用时使用。0 禁用，若有 iridescenceMap 则与该值相乘，默认 0。可获取此强度。	-
_iridescence	any	-
iridescenceRefractionIndex	number 虹彩薄膜折射率，影响颜色相位偏移，原理见 https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_materials_iridescence 。可获取此值。	-
_iridescenceRefractionIndex	any	-
iridescenceThicknessMin	number 虹彩层最小厚度，仅在使用虹彩厚度贴图时有效，单位纳米。可获取此值。	-
_iridescenceThicknessMin	any	-
iridescenceThicknessMax	number 虹彩层最大厚度，未定义厚度贴图时作为基础厚度，单位纳米。可获取此值。	-
_iridescenceThicknessMax	any	-
anisotropyRotation	number 定义各向异性旋转角度，单位度。可获取此值。	-
_anisotropyRotation	any	-
attenuationDistance	number 定义介质光吸收速率的距离，仅在 useDynamicRefraction 启用时使用。可获取衰减距离。	-
_attenuationDistance	any	-
heightMapFactor	number 高度图倍率，默认 1，影响视差强度。1 最多将纹理偏移 UV 地块的 5%，常用范围 0 到 2。可获取此因子。	-
_heightMapFactor	any	-
alphaDither	number 不透明度抖动所用 Alpha，范围 [0, 1]，独立于继续驱动 Alpha 混合的 opacity。因此材质可同时以不同强度混合与抖动，例如相机靠近玻璃时用抖动淡出并保留玻璃混合外观。仅在 opacityDither 或 opacityShadowDither 启用抖动模式时有效。设为 1.0 可在运行时关闭抖动而不改模式，0.0 完全丢弃。为向后兼容，从未赋值时使用 opacity，与旧行为一致。可获取此值。	-
_alphaDither	any	-
cubeMapProjectionBox	BoundingBox | null 设置 cubeMap 盒投影的世界空间轴对齐包围盒，null 表示无盒。仅在 cubeMapProjection 为 CUBEPROJ_BOX 时使用，传入包围盒会复制到材质。获取时返回包围盒或 null，修改其中心或半尺寸后调用 StandardMaterial#update 应用。	-
_cubeMapProjectionBox	BoundingBox	-
copy	(source: StandardMaterial) => StandardMaterial 复制 StandardMaterial。	-
_getMapTransformId	any 返回纹理贴图所属的变换组。	-
setAttribute	(name: string, semantic: string) => void 为材质设置顶点着色器属性。	-
_setParameter	(name: any, value: any) => void	-
_processParameters	any 用上次更新以来发布的参数替换旧参数集合，并删除不再存在的参数。	-
_updateMap	(p: any) => void	-
meshInstances	any 引用此材质的网格实例。	-
name	string 材质名称。	-
userId	string 用户可为材质指定的唯一 ID，引擎内部不使用，可自行赋予任意用途。默认为空字符串。	-
id	number	-
_definesDirty	boolean	-
_definesKey	any Material#defines 的缓存内容键，需要重算时为 null。空定义集缓存为 ""，因此 null 明确表示脏状态。	-
parameters	{}	-
_alphaTest	any	-
alphaToCoverage	boolean 启用或禁用 Alpha 覆盖率。硬件抗锯齿开启时可实现有限的顺序无关透明，质量取决于当前目标的 MSAA 采样数，适合柔化 Alpha 裁剪边缘，不推荐大面积半透明表面，无需启用混合。要求多重采样目标，单采样时静默忽略。WebGPU 还要求第一个颜色附件使用带 Alpha 的可混合格式，否则也忽略；CameraFrame 默认 HDR 格式 PIXELFORMAT_111110F 没有 Alpha。	-
_sceneTexturesWrite	any 显式指定的 sceneTexturesWrite，undefined 表示根据透明度推导。	-
cull	number 控制按面相对视点方向剔除三角形：CULLFACE_NONE 不剔除；CULLFACE_BACK 剔除背面；CULLFACE_FRONT 剔除正面。默认 CULLFACE_BACK。	-
frontFace	number 通过顶点绕序定义多边形正反面。FRONTFACE_CW 为顺时针，FRONTFACE_CCW 为逆时针，默认 FRONTFACE_CCW。	-
stencilFront	StencilParameters | null 正面模板参数，默认 null。	-
stencilBack	StencilParameters | null 背面模板参数，默认 null。	-
_shaderChunks	any	-
_oldChunks	{}	-
_dirtyShader	boolean	-
flatShading	boolean 启用或禁用平面着色，默认 false。启用时使用片元所在三角形的几何法线而非插值顶点法线，产生分面外观，也支持蒙皮和形变。几何法线按 Material#frontFace 的绕序定向，与正确制作的顶点法线一致，因此 cull、frontFace、twoSidedLighting 与平滑着色保持相同行为。StandardMaterial 和 LitMaterial 自动支持；ShaderMaterial 只添加 FLAT_SHADING 定义，需自定义代码处理，可用 flatNormalPS 代码块的 getFlatNormal： ```javascript #include "flatNormalPS" ... #ifdef FLAT_SHADING vec3 normal = getFlatNormal(worldPos); #else vec3 normal = normalize(interpolatedNormal); #endif ``` 与其他材质属性相同，修改后调用 Material#update。可获取平面着色状态。	-
getShaderChunks	(shaderLanguage?: string | undefined) => ShaderChunkMap 返回材质指定着色语言的自定义代码块对象，用于构建最终 GLSL 或 WGSL 着色器，也可通过 #include "ChunkName" 引用。WebGL 直接使用 GLSL；WebGPU 优先使用 WGSL，若仅提供 GLSL 则先生成后转译为 WGSL，效率较低。为加快编译，应为全部目标平台提供代码块。以下示例同时覆盖 GLSL 与 WGSL 的自发光代码块： ```javascript material.getShaderChunks(SHADERLANGUAGE_GLSL).set('emissivePS', ` void getEmission() { dEmission = vec3(1.0, 0.0, 1.0); } `); material.getShaderChunks(SHADERLANGUAGE_WGSL).set('emissivePS', ` fn getEmission() { dEmission = vec3f(1.0, 0.0, 1.0); } `); // call update to apply the changes material.update(); ```	-
shaderChunksVersion	string 设置或获取着色器代码块版本，应为当前引擎主版本与次版本字符串，例如 v2.8.1 使用 "2.8"。自定义代码块应指定最新支持版本。未来引擎不再支持时会警告，此时应更新代码块格式并相应调整版本。	-
alphaTest	number 设置或获取 Alpha 测试参考值。Alpha 小于 alphaTest 的片元会被丢弃，不写入当前渲染目标。默认 0，全部通过。	-
depthBias	number 设置或获取输出深度值偏移，适用于避免贴花深度冲突。通常用小负值，例如 -0.1，使网格略靠近相机。	-
slopeDepthBias	number 设置或获取基于三角形相对相机斜率的输出深度偏移。	-
_shaderVersion	number	-
_scene	any	-
_updateVersion	any Material#update 时递增，让内部使用方检测变化而无需消耗共享脏状态。	-
_preparedVersion	any Material#prepareForRender 最近处理的更新版本。	-
_modifiedProperties	any 公共值已变化但尚未写入 uniform 缓冲区的类型化属性，首次使用时分配。	-
_mutableProperties	any 按属性保存 getter 返回的聚合类型值快照，update 时比较以检测原地修改，首次使用时分配。	-
_uniformBuffer	any 存储类型化属性的 uniform 缓冲区，首次准备渲染时创建。没有类型化属性的材质为 null。	-
_uniformBufferBindGroup	any 持有材质 uniform 缓冲区的绑定组。	-
_layout	any 创建 uniform 缓冲区与绑定组使用的布局，材质首次渲染前为 null。	-
_resolvedTextureVersion	any 最近一次解析布局时对应的纹理分配版本。	-
_uniformDataVersion	any 每次将类型化属性写入 uniform 缓冲区存储时递增。	-
_uniformUploadedVersion	any 最近上传到 GPU 的 uniform 数据版本。	-
_layoutVersion	any 材质类型化属性集合或纹理集合变化导致布局替换时递增，使网格实例重新分类参数。布局不变的材质保持常量。	-
_layoutDirty	any uniform 缓冲区创建后，材质 uniform 集合发生变化时为 true，下一次准备时重新获取布局。	-
_markLayoutDirty	() => void 将材质布局标为已变化，下次准备时重新获取；若布局不同则替换 uniform 缓冲区与绑定组。	-
redWrite	boolean 设置或获取是否向当前渲染目标颜色缓冲区写入红色通道，默认 true；false 时不写入红色分量。	-
greenWrite	boolean 设置或获取是否向当前渲染目标颜色缓冲区写入绿色通道，默认 true；false 时不写入绿色分量。	-
blueWrite	boolean 设置或获取是否向当前渲染目标颜色缓冲区写入蓝色通道，默认 true；false 时不写入蓝色分量。	-
alphaWrite	boolean 设置或获取是否向当前渲染目标颜色缓冲区写入 Alpha 通道，默认 true；false 时不写入 Alpha。	-
transparent	boolean	-
_updateTransparency	() => void	-
blendState	Readonly<BlendState> 设置或获取材质混合状态，控制片元输出写入当前目标时如何混合。覆盖 blendType，提供更精细控制。更新透明度与排序状态时使用 setter。	-
blendType	number 设置或获取材质混合模式，默认 BLEND_NONE。BLEND_SUBTRACTIVE 从目标减去源颜色；BLEND_ADDITIVE 相加；BLEND_NORMAL 常规半透明，相当于源 SRC_ALPHA、目标 ONE_MINUS_SRC_ALPHA；BLEND_NONE 禁用；BLEND_PREMULTIPLIED 类似 NORMAL，但源已乘 Alpha；BLEND_MULTIPLICATIVE 相乘；BLEND_ADDITIVEALPHA 先将源 RGB 乘 Alpha 再相加；BLEND_MULTIPLICATIVE2X 相乘后乘 2；BLEND_SCREEN 为更柔和的叠加；BLEND_MIN 取较小颜色；BLEND_MAX 取较大颜色。	-
depthState	DepthState 设置或获取深度状态，也可分别用 depthTest、depthFunc 和 depthWrite 配置。	-
depthTest	boolean 设置或获取是否启用深度测试，默认 true。启用时只有通过测试的片元才写入当前目标；禁用时不考虑深度缓冲区。与 depthFunc 的关系见 DepthState#test，深度写入由 depthWrite 独立控制。	-
depthFunc	number 设置或获取深度比较函数，默认 FUNC_LESSEQUAL。FUNC_NEVER 永不绘制；FUNC_LESS 新深度小于缓冲区时绘制；FUNC_EQUAL 相等；FUNC_LESSEQUAL 小于等于；FUNC_GREATER 大于；FUNC_NOTEQUAL 不等；FUNC_GREATEREQUAL 大于等于；FUNC_ALWAYS 始终绘制。	-
depthWrite	boolean 设置或获取是否向当前渲染目标的深度缓冲区写入片元深度，默认 true。false 时不写深度。	-
clone	() => StandardMaterial 克隆材质。	-
_updateMeshInstanceKeys	() => void	-
_clearVariantsIfDirty	any	-
updateUniforms	(device: any, scene: any) => void	-
_markPropertyModified	(property: MaterialProperty) => void 记录类型化属性公共值已变化，在下一次 Material#update 时写入 uniform 缓冲区。	-
_markPropertyMutable	(property: MaterialProperty, value: object) => void 记录 getter 已暴露类型化属性的聚合值，以便下次 Material#update 检测返回对象的原地修改。仅首次暴露时分配快照。	-
_updateProperties	any 处理类型化属性变化：检测暴露值的原地修改，并将修改值转换到 uniform 缓冲区存储。缓冲区创建前变化保持待处理，创建时写入。由 Material#update 执行，渲染器不处理，因此修改后未调用 update 不会生效，调试构建会报告。	-
_prepareUniformBuffer	any 首次使用时创建材质 uniform 缓冲区与绑定组，数据变化时上传缓冲区。	-
_debugWarnedUnapplied	boolean	-
update	() => void 应用材质属性修改，修改后应调用此方法确保生效。如果属性变化需要不同着色器变体、材质 getShaderChunks 代码块变化、全局 ShaderChunks.get 代码块变化或材质 defines 变化，会清除缓存变体并按需重新编译。不会立即编译，而是在 forward、shadow、pick 等通道实际需要时生成。修改全局代码块后，每个需要反映变化的材质都必须调用 update()。	-
clearParameters	() => void	-
getParameters	() => {}	-
clearVariants	() => void	-
getParameter	(name: string) => object 获取材质指定的着色器参数。	-
_setParameterSimple	(name: any, data: any) => void	-
setParameter	(name: string, data: number | Texture | number[] | ArrayBufferView<ArrayBufferLike> | StorageBuffer) => void 为材质设置着色器参数。	-
deleteParameter	(name: string) => void 删除材质着色器参数。	-
_setScopeParameter	any	-
setDefine	(name: string, value: string | boolean | undefined) => void 添加或移除材质宏定义，可用于启用或禁用着色器代码部分。	-
getDefine	(name: string) => boolean 材质启用指定宏定义时返回 true，否则 false。	-
destroy	() => void 从场景移除此材质；若无其他材质使用相应着色器，还可能释放着色器内存。	-

更多示例

高级属性

完整属性见 StandardMaterial。

import { useMaterial } from '@playcanvas/react/hooks'

function AdvancedMaterial() {
  const material = useMaterial({
    diffuse: 'purple',
    opacity: 0.9,
    metalness: 0.3,
    roughness: 0.4,
    emissive: 'yellow',
    emissiveIntensity: 0.2,
    specular: 'white',
    shininess: 50,
    reflectivity: 0.8,
    clearCoat: 0.5,
    clearCoatRoughness: 0.1
  })
  
  return <Render type="box" material={material} />
}

纹理材质

用 useTexture 加载纹理。

import { useMaterial } from '@playcanvas/react/hooks'
import { useTexture } from '@playcanvas/react/hooks'

function TexturedMaterialExample() {
  const { asset: diffuseMap } = useTexture('diffuse.jpg')
  const { asset: normalMap } = useTexture('normal.jpg')
  const { asset: roughnessMap } = useTexture('roughness.jpg')
  
  const material = useMaterial({
    diffuseMap: diffuseMap?.resource,
    normalMap: normalMap?.resource,
    roughnessMap: roughnessMap?.resource,
    diffuse: 'white',
    metalness: 0.5,
    roughness: 0.5
  })
  
  return <Render type="box" material={material} />
}

共享材质

多个 Render 可以共享同一材质：

import { useMaterial } from '@playcanvas/react/hooks'

function SharedMaterial() {
  const material = useMaterial({
    diffuse: 'orange',
    metalness: 0.7,
    roughness: 0.3
  })
  
  return (
    <div>
      <Render type="box" material={material} />
      <Render type="sphere" material={material} />
      <Render type="cylinder" material={material} />
    </div>
  )
}

相关内容

• useTexture：加载纹理。
• Render：使用材质。
• StandardMaterial API：完整参考。