Back to Qt.io
Contact Us Blog Download Qt
本页内容

DefaultMaterial QML Type

允许您使用镜面反射/光泽度工作流为 3D 对象定义材质。更多内容...

Import Statement: import QtQuick3D
Inherits:

Material

Status: Deprecated since 6.4

自 QtQuick3D 6.4 起，此类型已弃用。我们强烈建议不要在新代码中使用它。

属性

详细说明

建议改用PrincipledMaterial 或SpecularGlossyMaterial 。

警告：此 材质仅出于兼容性考虑而提供，不应在新代码中使用。建议使用SpecularGlossyMaterial 通过“镜面反射/光泽度”工作流创建材质，或使用PrincipledMaterial 通过“金属度/粗糙度”工作流创建材质。

在场景中渲染模型之前，必须为其附加至少一种材质，以描述网格的着色方式。DefaultMaterial 是一种易于使用的材质，允许您使用镜面反射/光泽度类型工作流来描述材质。该材质具有合理的默认设置，无需更改任何属性即可用于模型的着色。

镜面反射/光泽度工作流

“默认材质”（DefaultMaterial）提供了一种基于镜面反射/光泽度工作流创建材质的方法。该材质的主要属性通过“镜面反射强度”（specular ）、“镜面反射百分比”（roughness ）以及“镜面反射阈值”（diffuse color ）属性进行控制。

镜面反射

specular reflectivity 描述了物体表面的镜面反射量和颜色。对于反射性材质，其主要颜色贡献来自该属性。

光泽度（粗糙度）

表面的光泽度取决于其表面是光滑还是不规则。光滑表面的光反射会比粗糙表面更强烈，而粗糙表面的光反射则会更分散。在“默认”材质中，材质的光泽度通过roughness 属性进行控制。

漫反射颜色

diffuse color 属性描述了材质的基本颜色，与PrincipledMaterial 的基色不同，漫反射色不包含任何关于材质反射率的信息。然而，对于反射性表面，漫反射色应设置为黑色调，这样才能让镜面反射色发挥作用。

属性文档

blendMode : enumeration

此属性决定了渲染后的模型颜色与背景颜色如何融合。

常量描述
DefaultMaterial.SourceOver默认混合模式。不透明对象会遮挡其后方的对象。对于使用此材质的模型，此默认模式本身并不能保证渲染管道中会进行 Alpha 混合，而是将该决定取决于以下几个因素： 如果对象和材质的总不透明度为1.0 ，且材质中没有包含半透明像素的纹理贴图，则该模型将被视为不透明，这意味着它将与其他不透明对象一起，在启用深度测试和深度写入的情况下进行渲染，且禁用混合。 否则，该模型将被视为半透明，在不透明物体之后渲染，并与其他半透明物体一起，根据其中心点到摄像机的距离，按从后到前的顺序进行渲染，同时启用阿尔法混合。
DefaultMaterial.Screen颜色采用反转乘法进行混合，从而产生更浅的结果。这种混合模式与渲染顺序无关；如果您在使用半不透明物体时，因面或模型的排序不同而出现闪烁现象，使用“屏幕混合”是消除闪烁的一种方法。
DefaultMaterial.Multiply颜色采用“乘法”模式进行混合，产生较暗的效果。此混合模式同样与渲染顺序无关。

另请参阅 Qt Quick 3D 架构。

bumpAmount : real

此属性控制“bumpMap ”或“normalMap ”的模拟位移量。默认值为0 ，这将禁用凹凸效果。取值范围为[0, 1]。

bumpMap : Texture

此属性定义了一张灰度纹理，用于模拟材质表面上的精细几何位移。较亮的像素表示凸起区域。该效果的强度由“bumpAmount ”属性控制。

注意：凹凸 贴图不会影响模型的轮廓。

diffuseColor : color

此属性用于确定材质的漫反射颜色（反照率）。将漫反射颜色设置为黑色，将生成一种纯镜面反射材质（例如金属或镜子）。

diffuseLightWrap : real

此属性用于确定半透明贴图的光线环绕范围。值为 0 时，光线不会进行任何环绕；值为 1 时，光线将环绕物体一周。

diffuseMap : Texture

此属性用于定义要应用于材质的纹理。如果使用具有透明度的纹理，系统还会将阿尔法通道作为不透明度贴图应用。

emissiveFactor : vector3d

此属性决定该材质的自发光颜色。如果设置了发光贴图，则 x、y 和 z 分量将分别作为纹理中 R、G 和 B 通道的系数（乘数）。 默认值为 (0, 0, 0)，表示完全没有自发光效果。

注意：将 lightingMode设置 为DefaultMaterial.NoLighting 时，发光因子对场景不产生任何影响。

emissiveMap : Texture

此属性用于设置一个 RGB 纹理，以指定发光颜色的亮度。

另请参阅 emissiveFactor 。

fresnelPower : real

该属性可减少正向反射（直接观察表面时），同时保持掠射角下的反射效果。默认值为0 ，这将禁用菲涅尔效应。

indexOfRefraction : real

此属性控制哪些反射角度会受到fresnelPower 的影响。默认值为1.45 。该值必须大于或等于1.0 。

注意： 目前世界上尚无任何 已知材料的折射率远大于3.0 。

lighting : enumeration

此属性用于定义生成该材质时采用哪种照明方法。

默认值为DefaultMaterial.FragmentLighting

使用“DefaultMaterial.FragmentLighting ”时，系统会针对每个渲染像素计算漫反射和镜面反射光照。某些效果（例如菲涅尔效果或凹凸贴图）需要启用“DefaultMaterial.FragmentLighting ”才能正常工作。

使用“DefaultMaterial.NoLighting ”时，不会计算任何光照。此模式（不出所料）速度非常快，在使用无需光照着色的图像贴图时非常有效。

常量描述
DefaultMaterial.NoLighting不计算任何光照。
DefaultMaterial.FragmentLighting计算每个片段的光照。

lineWidth : real

当几何体使用“线”或“线带”作为基元类型时，该属性决定所渲染线条的宽度。默认值为 1.0。在渲染其他类型的几何体（例如三角面网）时，该属性不适用。

警告： 根据底层图形 API 的不同，运行时可能不支持 1 以外的线宽 。在此情况下，更改线宽的请求将被忽略。例如，以下任何一种情况都不可能支持宽线：Direct3D、Metal 以及采用核心配置文件的 OpenGL 上下文。

注意：与 大多数其他材质属性不同， 线宽在底层会被“烘焙”到图形管道对象中，这与blendMode 类似。因此，更改该值将导致必须创建一个新的管道对象；如果该属性频繁被更改为多种不同的值，随着时间的推移，这可能会带来较高的开销（包括性能和资源消耗）。 例如，虽然可以对该属性进行动画处理，但应尽量避免。

normalMap : Texture

此属性定义了一张用于模拟材质表面精细几何位移的RGB图像。RGB通道分别表示X、Y、Z方向的法线偏差。该效果的强度由bumpAmount 属性控制。

注意：法线 贴图不会影响模型的轮廓。

opacity : real

此属性仅降低该材质的透明度，与模型本身无关。默认值为1.0 。取值范围为[0.0, 1.0]。

opacityChannel : enumeration

此属性定义了用于从opacityMap 读取不透明度值的纹理通道。默认值为Material.A 。

常量描述
Material.R从纹理的R通道读取值。
Material.G从纹理的 R 通道读取值。
Material.B从纹理的 B 通道读取值。
Material.A从纹理的 A 通道读取值。

opacityMap : Texture

此属性定义了一种纹理，用于针对材质的不同部分以不同的方式控制不透明度。

pointSize : real

当几何体使用“点”作为原始类型时，此属性用于确定渲染出的点的大小。默认值为 1.0。在渲染其他类型的几何体（例如三角网格）时，此属性不适用。

警告： 根据底层图形 API 的不同，运行时可能不支持 1 以外的点 大小。例如，在 Direct 3D 中，设置 1 以外的大小将无效。

roughnessChannel : enumeration

此属性定义了用于从roughnessMap 读取粗糙度值的纹理通道。默认值为Material.R 。

常量描述
Material.R从纹理的R通道读取值。
Material.G从纹理的 G 通道读取值。
Material.B从纹理的 B 通道读取值。
Material.A从纹理的 A 通道读取值。

roughnessMap : Texture

此属性定义了一种纹理，用于控制材质的镜面粗糙度。如果纹理包含多个通道（RGBA），则可通过roughnessChannel 属性设置正确的通道。

specularAmount : real

此属性控制镜面反射强度（高光和反射）。默认值为0 ，即禁用镜面反射。取值范围为[0.0, 1.0]。

注意：此 属性不会影响specularReflectionMap ，但会影响场景中SceneEnvironment::lightProbe 产生的反射量。

注意：除非 您的网格分辨率很高，否则 可能需要使用DefaultMaterial.FragmentLighting 来获得场景光源产生的良好镜面高光。

specularMap : Texture

此属性定义了一个 RGB 纹理，用于调节材质表面上高光的效果强度和颜色。这些值将与specularAmount 相乘。

specularModel : enumeration

此属性用于确定场景中灯光的镜面高光采用哪些函数进行计算。

常量描述
DefaultMaterial.Default镜面照明使用默认照明模型。
DefaultMaterial.KGGX镜面照明使用 GGX 照明模型。

specularReflectionMap : Texture

此属性用于设置材质中用于镜面高光的纹理。

这通常用于实现环境映射：当模型旋转时，该贴图会呈现出仿佛从环境中反射而来的效果。要使该功能按预期工作，需将该纹理的mappingMode 属性设置为Texture.Environment。镜面反射贴图是一种以相对较低的计算成本轻松实现高质量视觉效果的简便方法。

注意：将 light probe 与SceneEnvironment关联 （从而依赖基于图像的照明），可以实现类似的环境反射效果。然而，光探针在概念上有所不同，且在性能方面可能是更耗资源的解决方案。 每种方法都有其特定的用途，具体应根据实际情况决定采用哪种方案。在“纹理”属性设置方面，specularReflectionMap 具有优势，因为它没有限制，并支持所有类型的纹理，包括那些通过sourceItem 从Qt Quick 子场景获取数据的纹理。

注意：清晰的 图像会使材质看起来非常光亮；图像越模糊，材质看起来就越柔和。

另请参阅 Texture::mappingMode 。

specularRoughness : real

此属性控制由光源生成的镜面高光的大小，以及反射的整体清晰度。数值越大，粗糙度越高，镜面高光会变得越柔和，反射也会越模糊。取值范围为 [0.0, 1.0]。默认值为 0。

specularTint : color

此属性定义了用于调整镜面反射的颜色。若不希望产生效果，请使用白色

translucencyChannel : enumeration

此属性定义了用于从translucencyMap 读取半透明值的纹理通道。默认值为Material.A 。

常量描述
Material.R从纹理的 R 通道读取数值。
Material.G从纹理的 G 通道读取值。
Material.B从纹理的 B 通道读取值。
Material.A从纹理的 A 通道读取值。

translucencyMap : Texture

此属性定义了一个灰度纹理，用于控制有多少光线能从材质背面透过。

translucentFalloff : real

此属性根据物体法线与光源之间的角度，定义半透明度的衰减程度。

vertexColorsEnabled : bool

启用此属性后，材质将使用网格的顶点颜色。这些颜色将与为该材质指定的其他颜色相乘。

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.