Texture QML Type
定义用于 3D 场景的纹理。更多...
| Import Statement: | import QtQuick3D |
| Inherits: | |
| Inherited By: |
属性
- autoOrientation : bool
(since 6.2) - flipU : bool
- flipV : bool
- generateMipmaps : bool
- indexUV : int
- magFilter : enumeration
- mappingMode : enumeration
- minFilter : enumeration
- mipFilter : enumeration
- pivotU : real
- pivotV : real
- positionU : real
- positionV : real
- rotationUV : real
- scaleU : real
- scaleV : real
- source : url
- sourceItem : Item
- textureData : TextureData
- textureProvider : RenderExtension
(since 6.7) - tilingModeDepth : enumeration
- tilingModeHorizontal : enumeration
- tilingModeVertical : enumeration
详细说明
从技术上讲，纹理是指任何像素数组（1D、2D 或 3D）及其相关设置，例如缩小和放大滤波器、缩放以及 UV 变换。
Qt Quick 3D 中的Texture类型表示一幅二维图像。它通常用于映射到三维几何体或包裹在三维几何体上，以模拟无法在3D中高效建模的额外细节。它还可以用于模拟其他光照效果，例如反射。
虽然 Texture 本身始终代表一个 2D 纹理，但通过 Texture 的子类也可以使用其他类型的纹理。例如，要创建一个具有 6 个面的立方体贴图，请使用CubeMapTexture 类型。
在渲染几何体时，会通过变换和插值网格顶点上已设置的 UV 坐标（纹理坐标），将表面上的每个位置映射到纹理中的对应位置。 随后，用于渲染活动材质的片段着色器程序通常会在给定坐标处采样该材质的纹理，并将采样数据用于其光照计算中。
注意：一种 材质可以使用多个纹理，以在 3D 场景中实现与光线所需的交互。它不仅可以表示几何体表面上每个纹素的颜色，还可以表示表面的其他属性。 例如，“法线贴图”可以表示表面上每个纹素相对于几何体法线的偏差，从而模拟光线与表面细微细节（如裂缝或凸起）的交互。请参阅“原理性材质”示例，了解具有多个纹理贴图的材质的演示。
纹理对象可从以下来源获取图像数据：
- 通过source 属性从图像或纹理文件获取，
- 通过sourceItem 属性，从Qt Quick 的Item 获取数据，
- 或者将textureData 属性设置为TextureData 项的子类，以定义自定义纹理内容。
以下示例将图像“madewithqt.png”映射到默认球体网格上，并调整 UV 坐标以使图像在球体表面上平铺显示。
Model {
source: "#Sphere"
materials: [ PrincipledMaterial {
baseColorMap: Texture {
source: "madewithqt.png"
scaleU: 4.0
scaleV: 4.0
}
}
]
}结果如下所示：
| 原始图像 | 映射到球体上 |
|---|---|
|
|
另请参阅 Qt Quick 3D - 程序化纹理示例。
属性文档
autoOrientation : bool [since 6.2]
此属性用于确定是否对通常需要进行纹理变换（例如翻转 V 纹理坐标）的纹理自动应用该变换。
默认情况下，此属性设置为 true。
某些类型的纹理数据，例如通过source 属性从.ktx或.pkm文件加载的压缩纹理，或者通过sourceItem 属性渲染Qt Quick 场景生成的纹理，与从.png或.jpg等图像文件加载的纹理相比，Y轴方向通常不同。 因此，与源设置为常规图像文件的纹理相比，此类纹理会显得“上下颠倒”。为解决此问题，符合条件的纹理将自动应用隐式 UV 变换，效果如同将flipV 属性设置为 true 一样。若不希望出现此效果，请将该属性设置为 false。
注意： 当纹理与 DefaultMaterial 或PrincipledMaterial 结合使用时，此 属性才生效。Custom materials 提供其专有的着色器代码，因此由该属性配置的变换将被忽略，具体实现取决于应用程序提供的着色器代码。
该属性在 Qt 6.2 中引入。
另请参阅 flipV 。
flipU : bool
此属性用于设置是否使用水平翻转的纹理坐标。
默认值为 false。
注意： 当“纹理”（Texture）与“默认材质”（DefaultMaterial）或“自定义材质”（PrincipledMaterial ）结合使用时，此属性才 生效。“自定义材质”（Custom materials ）提供自己的着色器代码，因此由该属性配置的变换将被忽略，具体实现取决于应用程序提供的着色器代码。
另请参阅 flipV 。
flipV : bool
此属性用于设置是否使用垂直翻转的纹理坐标。
默认值为 false。
注意： 当“纹理”与“默认材质”（DefaultMaterial）或“自定义材质”（PrincipledMaterial ）结合使用时，此属性 才生效。Custom materials 会提供自己的着色器代码，因此由该属性配置的变换将被忽略，具体实现取决于应用程序提供的着色器代码。
另请参阅 flipU 。
generateMipmaps : bool
此属性用于确定是否为未自行提供Mipmap级别的纹理生成Mipmap。与不使用Mipmap的情况相比，结合使用Mipmap和Mip过滤可在远距离观察纹理时提供更好的视觉质量，但这可能会带来性能开销（包括图像初始化时和渲染过程中）。
默认情况下，此属性设置为 false。
注意：必须 设置mipFilter 模式，生成的Mipmap才能被使用。
注意： 当纹理内容基于由sourceItem 属性引用的Qt Quick 项时，此 属性不适用。由于会影响性能，无法为动态纹理生成Mipmap。因此，对于此类纹理，此属性的值将被忽略。
另请参阅 mipFilter 。
indexUV : int
此属性用于设置该纹理所使用的 UV 坐标索引。由于QtQuick3D 目前支持 2 组 UV（0 或 1），因此该值将被限制在该范围内。
默认值为 0。
magFilter : enumeration
该属性决定了纹理在“放大”时（即一个纹素覆盖屏幕空间中的多个像素）的采样方式。
默认值为Texture.Linear 。
| 常量 | 描述 |
|---|---|
Texture.Nearest | 使用距离最近的纹理像素的值。 |
Texture.Linear | 取四个最近的纹理像素，并对它们进行双线性插值。 注意： 在此处使用 |
mappingMode : enumeration
此属性用于定义在采样该纹理时应使用哪种映射方法。
| 常量 | 描述 |
|---|---|
Texture.UV | 默认值。适用于基础颜色、漫反射、不透明度以及大多数其他纹理贴图。执行标准 UV 映射。除非对 UV 坐标进行变换和动画处理，否则图像的同一部分将始终显示在同一顶点上。 |
Texture.Environment | 用于“specular reflection ”时，会将图像投影到材质上，仿佛其被反射一般。若对其他类型的纹理贴图使用此模式，则会产生镜像效果。 |
Texture.LightProbe | 这是光探针所用 HDRI 球面贴图的默认模式。对于关联了“lightProbe ”属性的纹理对象，无需手动设置此模式，因为该模式会自动启用。 |
minFilter : enumeration
该属性决定了当纹理被“缩小”时（即一个纹素在屏幕空间中覆盖的范围小于一个像素）如何进行采样。
默认值为Texture.Linear 。
| 常量 | 描述 |
|---|---|
Texture.Nearest | 使用最近的纹素的值。 |
Texture.Linear | 取四个最接近的纹素，并对它们进行双线性插值。 注意： 在此处使用 |
mipFilter : enumeration
该属性决定了当一个纹理像素（texel）覆盖的范围小于一个像素时，如何对纹理的MIP贴图进行采样。
默认值为Texture.None 。
| 常量 | 描述 |
|---|---|
Texture.None | 禁用 Mipmap 采样。 |
Texture.Nearest | 使用 Mipmap 并采样最近的纹素值。 |
Texture.Linear | 使用 Mipmap 并插值多个纹素值。 注意： 对于没有Mipmap的纹理，此 属性将不起作用。 |
pivotU : real
此属性用于设置枢轴点 U 坐标，该坐标在应用rotationUV 时会被用到。
默认值为 0.0。
注意： 当纹理与 DefaultMaterial 或PrincipledMaterial 结合使用时，此 属性才生效。Custom materials 提供自己的着色器代码，因此此类属性配置的变换将被忽略，具体实现取决于应用程序提供的着色器代码。
另请参阅 rotationUV 。
pivotV : real
此属性用于设置枢轴的 V 位置，该位置在应用rotationUV 时会被用到。
默认值为 0.0。
注意： 当纹理与 DefaultMaterial 或PrincipledMaterial 结合使用时，此属性 才生效。Custom materials 提供自己的着色器代码，因此此属性所配置的变换将被忽略，具体实现取决于应用程序提供的着色器代码。
另请参阅 pivotU 和rotationUV 。
positionU : real
此属性将 U 坐标的映射从左向右偏移。
默认值为 0.0。
注意： 当“纹理”与“默认材质”（DefaultMaterial）或“自定义材质”（PrincipledMaterial ）结合使用时，此属性 才生效。Custom materials 会提供自己的着色器代码，因此由该属性配置的变换将被忽略，具体实现取决于应用程序提供的着色器代码。
另请参阅 positionV 。
positionV : real
此属性将 V 坐标映射从底部偏移到顶部。
默认值为 0.0。
注意： 无论运行时使用何种图形 API， Qt Quick 3D 都使用 OpenGL 风格的顶点数据。因此，UV 位置(0, 0) 指的是图像数据的左下角。
注意： 当 Texture 与 DefaultMaterial 或PrincipledMaterial 结合使用时，此属性 才生效。Custom materials 提供自己的着色器代码，因此由此属性配置的变换将被忽略，具体实现取决于应用程序提供的着色器代码。
另请参阅 positionU 。
rotationUV : real
此属性可围绕枢轴点旋转纹理。该属性使用欧拉角进行定义，正值表示顺时针旋转。
默认值为 0.0。
注意： 当“纹理”（Texture）与“默认材质”（DefaultMaterial）或“自定义材质”（PrincipledMaterial ）结合使用时，此属性才 生效。“自定义材质”（Custom materials ）提供其专有的着色器代码，因此由该属性配置的变换将被忽略，具体实现取决于应用程序提供的着色器代码。
scaleU : real
此属性定义了在将纹理映射到网格的 UV 坐标时，如何缩放 U 纹理坐标。
在使用水平平铺时对 U 值进行缩放，将决定纹理从左到右重复的次数。
默认值为 1.0。
注意： 当“纹理”与“默认材质”（DefaultMaterial）或“自定义材质”（PrincipledMaterial ）结合使用时，此属性才 生效。“自定义材质”（Custom materials ）提供自己的着色器代码，因此此类属性所配置的变换将被忽略，具体实现取决于应用程序提供的着色器代码。
另请参阅 tilingModeHorizontal 。
scaleV : real
此属性定义了在将 V 纹理坐标映射到网格的 UV 坐标时，如何对 V 纹理坐标进行缩放。
在使用垂直平铺时对 V 值进行缩放，将决定纹理从下到上重复的次数。
默认值为 1.0。
注意： 当“纹理”与“默认材质”（DefaultMaterial）或“自定义材质”（PrincipledMaterial ）结合使用时，此属性才 生效。“自定义材质”（Custom materials ）提供自己的着色器代码，因此由该属性配置的变换将被忽略，具体实现取决于应用程序提供的着色器代码。
另请参阅 tilingModeVertical 。
source : url
该属性存储了包含纹理所用数据的图像或纹理文件的位置。
该属性是一个 URL，其规则与其他源属性相同，例如Image.source 。对于 Texture，仅支持qrc 和file 方案。若未指定方案且值为相对路径，则默认以组件（即.qml 文件）的位置为基准。
源文件可以采用任何常规图像文件格式supported by Qt 。此外，Texture 支持与 QtQuick::Image 相同的compressed texture file types 。
注意： 从 .png 或 .jpg 等图像文件中读取的纹理 数据，会将纹理中的像素行按Qt Quick 3D 渲染引擎定义的顺序进行存储。当源文件是纹理数据（可能经过压缩）的容器时，此类转换无法在像素数据层面上进行。 例如 .ktx 或 .pkm 文件。相反，Texture 会在片段着色器代码中隐式启用垂直翻转，以获得相同的屏幕显示效果。此行为由autoOrientation 属性控制，如有需要，可以将其禁用。
注意：某些 纹理压缩工具可能会对图像数据应用自动垂直镜像（翻转）处理。在现代工具中，这通常是一个可选设置。 了解资源预处理管道中使用的设置非常重要，因为纹理意外翻转（从而导致对象贴图错误）的根本原因可能在于资源本身，而超出应用程序和渲染引擎的控制范围。当资源需要时，应用程序可以自行设置 `flipV ` 属性。
另请参阅 sourceItem 、textureData 、autoOrientation 以及flipV 。
sourceItem : Item
该属性定义了一个将用作纹理源的“项”。使用此属性可将任何 2DQt Quick 内容作为纹理源，方法是将该项渲染为离屏图层。
如果该项是texture provider ，则不会使用额外的纹理。
如果设置了此属性，则source 的值将被忽略。一个Texture应使用一种方法提供图像数据，并且仅设置source、sourceItem或textureData 中的一个。
注意：目前 ，只有当用户每次只能与一个 sourceItem 实例交互时，输入事件才会转发给用作纹理源的 Item。 换言之：虽然可以在多个 Texture 之间共享同一个 Item，但无法同时对多个 Texture 上的同一项进行多点触控交互。因此，若需操作其中的交互式项，最好为每个 Texture 实例使用独立的 2D 子场景实例。
注意： 强烈不建议在被多个窗口引用的纹理中使用 此属性。这包括通过 `View3D::importScene` 的使用。由于此属性创建的源纹理仅可被一个渲染线程访问，因此尝试在多个 `QQuickWindow ` 实例之间共享它将会失败，除非使用 `Qt Quick ` 的 `basic ` 渲染循环代替默认的 `threaded ` 渲染循环。 有关Qt Quick 渲染循环的更多信息，请参阅Qt Quick Scene Graph。
注意： 包含Qt Quick 离屏渲染通道结果的纹理，其 Y 轴方向实际上会与通过 source 属性接收内容的纹理不同。 当与 DefaultMaterial 或PrincipledMaterial 结合使用时，这对应用程序而言是完全透明的，因为只要autoOrientation 属性设置为 true，必要的 UV 变换就会自动应用，因此无论纹理的来源如何，都不需要采取任何进一步的行动。 然而，在开发custom materials 时，着色器代码作者在采样纹理和处理 UV 坐标时需要牢记这一点。
另请参阅 source 、textureData 以及autoOrientation 。
textureData : TextureData
该属性保存对TextureData 组件的引用，该组件定义了原始纹理数据的内容和属性。
如果使用了此属性，则将忽略 `source ` 的值。一个 `Texture` 应使用一种方法提供图像数据，并且仅设置 `source`、`sourceItem` 或 `textureData` 中的一个。
另请参阅 source 、sourceItem 以及Qt Quick 3D - 过程纹理示例。
textureProvider : RenderExtension [since 6.7]
该属性存储了RenderExtension ，它将提供QRhiTexture ，该 将由该项使用。
注意： 由RenderExtension 创建的纹理需要通过registering 向引擎提供。
该属性于 Qt 6.7 中引入。
另请参阅 TextureProviderExtension 、RenderExtension 和QSSGRenderExtensionHelpers 。
tilingModeDepth : enumeration
该属性控制当 Z 缩放值大于 1 时纹理的映射方式。
默认情况下，此属性设置为“Texture.Repeat ”。
| 常量 | 描述 |
|---|---|
Texture.ClampToEdge | 纹理不会平铺，而是使用边缘处的值。 |
Texture.MirroredRepeat | 纹理会沿 Z 轴重复并镜像。 |
Texture.Repeat | 纹理沿 Z 轴重复。 |
tilingModeHorizontal : enumeration
控制当 U 缩放值大于 1 时纹理的映射方式。
默认情况下，此属性设置为Texture.Repeat 。
| 常量 | 描述 |
|---|---|
Texture.ClampToEdge | 纹理不会平铺，而是使用边缘处的值。 |
Texture.MirroredRepeat | 纹理沿 X 轴重复并镜像。 |
Texture.Repeat | 纹理沿 X 轴重复。 |
另请参阅 scaleU 。
tilingModeVertical : enumeration
当 V 缩放值大于 1 时，此属性控制纹理的映射方式。
默认情况下，此属性的设置为Texture.Repeat 。
| 常量 | 描述 |
|---|---|
Texture.ClampToEdge | 纹理不会平铺，而是使用边缘处的值。 |
Texture.MirroredRepeat | 纹理沿 Y 轴重复并镜像。 |
Texture.Repeat | 纹理沿 Y 轴重复。 |
另请参阅 scaleV 。
© 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.
