Back to Qt.io
Contact Us Blog Download Qt

Texture QML Type

定义用于 3D 场景的纹理。更多

Import Statement: import QtQuick3D
Inherits:

Object3D

Inherited By:

CubeMapTexture

属性

详细说明

从技术上讲，纹理是指任何像素阵列（一维、二维或三维）及其相关设置，如缩小和放大过滤器、缩放和 UV 变换。

Qt Quick 3D 中的纹理类型表示二维图像。它通常用于映射/环绕三维几何体，以模拟无法在三维中有效建模的额外细节。它还可用于模拟其他照明效果，如反射。

虽然 Texture 本身总是表示二维纹理，但也可以通过 Texture 的子类来表示其他类型的纹理。例如，要创建具有 6 个面的立方体贴图纹理，可使用CubeMapTexture 类型。

在渲染几何体时，其表面上的每个位置都将通过转换和插值为网格顶点设置的 UV 坐标（纹理坐标），转换到纹理中的相应位置。然后，用于渲染活动材质的片段着色器程序通常会在给定坐标处对材质纹理进行采样，并在光照计算中使用采样数据。

注： 材质可使用多个纹理，以在 3D 场景中实现所需的光影互动。它可以表示几何体表面上每个像素的颜色，也可以表示表面的其他属性。例如，"法线贴图 "可以表示表面上每个像素与几何体法线的偏差，从而模拟光线与表面裂缝或凹凸等细部的交互作用。有关具有多个纹理贴图的材质演示，请参阅原理材质示例。

纹理对象可通过以下方式获取图像数据

下面的示例将图像 "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。

注意： 当纹理与 DefaultMaterial 或PrincipledMaterial 结合使用时，该属性才有效。Custom materials 提供了自己的着色器代码，因此像该属性配置的转换将被忽略，由应用程序提供的着色器代码来实现。

另请参阅 flipV 。


flipV : bool

此属性设置垂直翻转纹理坐标的使用。

默认值为 false。

注： 该属性在纹理与 DefaultMaterial（默认材质）或PrincipledMaterial 结合使用时有效。Custom materials 提供自己的着色器代码，因此像该属性配置的这种变换将被忽略，由应用程序提供的着色器代码来实现。

另请参阅 flipU 。


generateMipmaps : bool

此属性决定是否为本身不提供 mipmap 级别的纹理生成 mipmap。与不使用 mipmap 滤波的渲染相比，使用 mipmap 和 mip 滤波可在远距离查看纹理时获得更好的视觉质量，但这可能需要付出性能代价（在初始化图像和渲染过程中）。

默认情况下，此属性设置为 false。

注： 要使用生成的 mipmaps，必须设置mipFilter 模式。

注： 当纹理内容基于sourceItem 属性引用的Qt Quick 项目时，此属性不适用。由于对性能的影响，为动态纹理生成 Mipmap 是不可行的。因此，此类纹理将忽略此属性的值。

另请参阅 mipFilter 。


indexUV : int

此属性设置此纹理使用的 UV 坐标索引。由于QtQuick3D 目前支持 2 个 UV 设置（0 或 1），因此该值将在一定范围内饱和。

默认值为 0。


magFilter : enumeration

该属性决定纹理在 "放大"（即纹理在屏幕空间中覆盖超过一个像素）时的采样方式。

默认值为Texture.Linear 。

常数说明
Texture.Nearest使用最近的像素值。
Texture.Linear取最近的四个色元并对其进行双线性插值。

注意： 此处使用Texture.None 将默认为Texture.Linear 。

另请参阅 minFilter 和mipFilter 。


mappingMode : enumeration

该属性定义了对该纹理进行采样时使用的映射方法。

常数说明
Texture.UV默认值。适用于基色、漫反射、不透明度和大多数其他纹理贴图。执行标准 UV 贴图。图像的相同部分将始终显示在相同的顶点上，除非 UV 坐标经过变换和动画处理。
Texture.Environment用于specular reflection 时，图像会被投射到材质上，就像被反射一样。对其他类型的纹理贴图使用该模式可产生镜像效果。
Texture.LightProbe默认用于光探测器使用的 HDRI 球形贴图。与lightProbe 属性关联的纹理对象无需手动设置此模式，因为它会自动隐含。

minFilter : enumeration

该属性决定纹理在 "最小化"（即一个像素在屏幕空间中的覆盖面积小于一个像素）时的采样方式。

默认值为Texture.Linear 。

常数说明
Texture.Nearest使用最近的像素值。
Texture.Linear取最近的四个像素点进行双线性插值。

注意： 此处使用Texture.None 将默认为Texture.Linear 。

另请参阅 magFilter 和mipFilter 。


mipFilter : enumeration

该属性决定了当一个纹理像素覆盖不到一个像素时，如何对纹理 mipmaps 进行采样。

默认值为Texture.None 。

常数说明
Texture.None禁用 mipmap 采样。
Texture.Nearest使用 mipmapping 并采样最接近的像素值。
Texture.Linear使用 mipmapping 并在多个纹理值之间进行内插。

注意： 此属性对没有 mipmap 的纹理没有影响。

另请参阅 minFilter 和magFilter 。


pivotU : real

此属性设置 U 轴心位置，在应用rotationUV 时使用。

默认值为 0.0。

注： 当纹理与 DefaultMaterial 或PrincipledMaterial 结合使用时，此属性才会生效。Custom materials 提供了自己的着色器代码，因此诸如此属性配置的变换将被忽略，由应用程序提供的着色器代码来实现。

另请参阅 rotationUV 。


pivotV : real

此属性设置应用rotationUV 时使用的 V 轴心位置。

默认值为 0.0。

注： 该属性在纹理与默认材质（DefaultMaterial）或PrincipledMaterial 结合使用时有效。Custom materials 提供了自己的着色器代码，因此像该属性配置的这种变换将被忽略，由应用程序提供的着色器代码来实现。

另请参阅 pivotU 和rotationUV 。


positionU : real

该属性从左到右偏移 U 坐标映射。

默认值为 0.0。

注： 该属性在纹理与 DefaultMaterial（默认材质）或PrincipledMaterial 结合使用时有效。Custom materials 提供自己的着色器代码，因此像该属性配置的变换将被忽略，由应用程序提供的着色器代码来实现。

另请参阅 positionV 。


positionV : real

该属性从下往上偏移 V 坐标映射。

默认值为 0.0。

注： Qt Quick 3D 使用 OpenGL 风格顶点数据，与运行时使用的图形 API 无关。因此，UV 位置(0, 0) 指的是图像数据的左下角。

注： 当纹理与 DefaultMaterial 或PrincipledMaterial 结合使用时，此属性才会生效。Custom materials 提供了自己的着色器代码，因此像此属性配置的变换将被忽略，由应用程序提供的着色器代码来实现。

另请参阅 positionU 。


rotationUV : real

该属性可使纹理围绕支点旋转。它使用欧拉角定义，正值为顺时针旋转。

默认值为 0.0。

注： 该属性在纹理与 DefaultMaterial（默认材质）或PrincipledMaterial 结合使用时有效。Custom materials 提供自己的着色器代码，因此像该属性配置的这种变换将被忽略，由应用程序提供的着色器代码来实现。

另请参阅 pivotU 和pivotV 。


scaleU : real

该属性定义了在映射到网格的 UV 坐标时如何缩放 U 纹理坐标。

使用水平平铺时 U 值的缩放将定义纹理从左到右重复的次数。

默认值为 1.0。

注： 当纹理与默认材质（DefaultMaterial）或PrincipledMaterial 结合使用时，此属性才会生效。Custom materials 提供了自己的着色器代码，因此像此属性配置的转换将被忽略，由应用程序提供的着色器代码来实现。

另请参阅 tilingModeHorizontal 。


scaleV : real

该属性定义了在映射到网格的 UV 坐标时如何缩放 V 纹理坐标。

在使用垂直平铺时，缩放 V 值将定义纹理从下到上重复的次数。

默认值为 1.0。

注： 当纹理与默认材质（DefaultMaterial）或PrincipledMaterial 结合使用时，此属性才会生效。Custom materials 提供了自己的着色器代码，因此像此属性配置的转换将被忽略，由应用程序提供的着色器代码来实现。

另请参阅 tilingModeVertical 。


source : url

该属性保存包含纹理所用数据的图像或纹理文件的位置。

该属性是一个 URL，其规则与其他源属性（如Image.source ）相同。对于纹理，只支持qrc 和file 方案。如果不存在方案，且值为相对路径，则假定为相对于组件（即.qml 文件）的位置。

源文件可以是任何常规图像文件格式supported by Qt 。此外，Texture 支持与 QtQuick::Image 相同的compressed texture file types 。

注： 从 .png 或 .jpg 等图像文件读取纹理数据时，需要按照Qt Quick 3D 渲染引擎定义的顺序存储纹理中的像素行。当源文件是一个纹理数据（可能是压缩的）容器时，这种转换无法在像素数据级别上进行。例如 .ktx 或 .pkm 文件。相反，"纹理 "会在片段着色器代码中隐含启用垂直翻转，以获得相同的屏幕效果。这由autoOrientation 属性控制，如果需要，也可以禁用。

注： 某些纹理压缩工具可能会对图像数据应用自动垂直镜像（翻转）。在现代工具中，这通常是一种选择性设置。了解资产调节管道中使用的设置非常重要，因为意外翻转的纹理，从而导致对象纹理不正确，其根本原因可能在资产本身，而不在应用程序和渲染引擎的控制范围内。如果资产需要，应用程序可以自行设置flipV 属性。

另请参阅 sourceItem,textureData,autoOrientation 和flipV 。


sourceItem : Item

该属性定义了用作纹理来源的 Item。使用该属性可以将任何 2DQt Quick 内容作为纹理源使用，方法是将该项目渲染为屏幕外图层。

如果项目是texture provider ，则不会使用额外的纹理。

如果设置了此属性，则source 的值将被忽略。纹理应使用一种方法提供图像数据，并只设置 source、sourceItem 或textureData 中的一种。

注意： 目前，只有当用户每次只能与一个 sourceItem 实例交互时，输入事件才会被转发到用作纹理源的 Item。换句话说：您可以在多个纹理之间共享同一个 Item，但这样就无法同时在多个纹理上与同一个 Item 进行多点触控交互。因此，如果您希望在每个纹理实例中操作互动项目，最好为每个纹理实例使用一个单独的 2D 子场景实例。

注意： 强烈不建议在从多个窗口引用的纹理中使用此属性。这包括通过View3D::importScene 使用。由于该属性创建的源纹理只能由一个渲染线程访问，因此在多个QQuickWindow 实例之间共享该纹理的尝试将会失败，除非使用Qt Quick 的basic 渲染循环而不是默认的threaded 循环。有关Qt Quick 渲染循环的更多信息，请参阅Qt Quick 场景图。

注： 包含Qt Quick 屏幕外渲染传递结果的纹理，其 Y 轴方向实际上与通过源属性接收其内容的纹理不同。当与 DefaultMaterial 或PrincipledMaterial 结合使用时，这对应用程序来说是透明的，因为只要autoOrientation 属性设置为 true，就会自动应用必要的 UV 变换，因此无论纹理的来源如何，都不需要进一步的操作。不过，在开发custom materials 时，着色器代码作者在对纹理进行采样和处理 UV 坐标时需要注意这一点。

另请参阅 source 、textureData 和autoOrientation 。


textureData： TextureData

该属性包含对TextureData 组件的引用，该组件定义了原始纹理数据的内容和属性。

如果使用此属性，source 的值将被忽略。纹理应使用一种方法提供图像数据，并只设置 source、sourceItem 或 textureData 中的一种。

另请参阅 source 、sourceItem 和Qt Quick 3D - 程序纹理示例。


textureProvider : RenderExtension [since 6.7]

此属性包含RenderExtension ，它将提供此项目将使用的QRhiTexture 。

注： 由RenderExtension 创建的纹理需要通过registering 与引擎一起使用。

此属性在 Qt 6.7 中引入。

另请参阅 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 。


© 2025 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.