纹理 QML 类型

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

导入声明import QtQuick3D
继承自

Object3D

继承

CubeMapTexture

属性

详细描述

纹理在技术上是指像素数组（1D、2D 或 3D）及其相关设置，例如缩放和放大过滤器，缩放和 UV 变换。

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

尽管 Texture 本身始终表示二维纹理，但也可以通过 Texture 的子类获取其他类型的纹理。例如，要创建具有 6 个面的立方体贴图纹理，请使用 CubeMapTexture 类型。

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

注意：材质可以使用多个纹理来实现3D场景中与光交互动画。它可以表示几何体表面每个texel的颜色，还可以表示表面的其他属性。例如，“法线贴图”可以表示表面每个texel的法线偏差，仿照表面更细致的细节（如裂缝或凹凸）的光照交互。请参阅原则性材质示例了解具有多个纹理贴图的材质演示。

纹理对象可以由以下方式提供图像数据：

以下示例将图像“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轴方向通常不同。因此，这种Texture相对于源设置为常规图像文件的Texture可能会显示“颠倒”。为了解决这个问题，任何符合条件的Texture都会得到隐含的UV变换，就好像flipV属性被设置为true一样。如果不希望这样，请将此属性设置为false。

注意：此属性在 Texture 与 DefaultMaterial 或 PrincipledMaterial 结合使用时有效。自定义材质提供了它自己的着色器代码，因此配置此属性所定义的变换将被忽略，且由提供应用程序着色器的代码实现。

此属性自Qt 6.2起引入。

另请参阅：flipV。


flipU : bool

该属性设置是否使用水平翻转的纹理坐标。

默认值是false。

注意：此属性在 Texture 与 DefaultMaterial 或 PrincipledMaterial 结合使用时有效。自定义材质提供了它自己的着色器代码，因此配置此属性所定义的变换将被忽略，且由提供应用程序着色器的代码实现。

另请参阅：flipV。


flipV : bool

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

默认值是false。

注意：此属性在 Texture 与 DefaultMaterial 或 PrincipledMaterial 结合使用时有效。自定义材质提供了它自己的着色器代码，因此配置此属性所定义的变换将被忽略，且由提供应用程序着色器的代码实现。

另请参阅：flipU。


generateMipmaps : bool

此属性确定是否为那些自身不提供米配级别的纹理生成米配图。使用米配图与米配过滤相结合，在从远处查看纹理时，与不使用它们相比，可以提供更好的视觉效果，但可能会带来性能成本（包括初始化图像期间和渲染过程中的性能成本）。

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

注意：为了使用生成的米配图，需要设置一个mipFilter模式。

注意：当纹理内容基于由sourceItem属性引用的Qt Quick项目时，此属性不适用。由于性能影响，无法为动态纹理生成米配图。因此，对于这类纹理，此属性的值将被忽略。

另请参阅：mipFilter。


indexUV : int

此属性设置此纹理使用的UV坐标索引。由于当前QtQuick3D支持2个UV集合（0或1），该值将饱和到该范围。

默认值为0。


magFilter : enumeration

此属性确定在纹理“放大”，即在屏幕空间中一个像素覆盖一个或多个texel时如何采样纹理。

默认值是Texture.Linear。

常量描述
Texture.Nearest使用最接近的texel的值。
Texture.Linear取四个最接近的texel，并进行双线性插值。

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

另请参阅：minFilter和mipFilter。


mappingMode : enumeration

此属性定义在采样此纹理时使用哪种映射方法。

常量描述
Texture.UV默认值。适用于基础颜色、漫反射、不透明度和大多数其他纹理映射。执行标准的UV映射。除非UV坐标被转换和动画化，否则图像的同一部分始终出现在同一个顶点上。
Texture.Environment用于高光反射，这会将图像投影到材质上，好像它被反射一样。将此模式用于其他类型的纹理映射将提供镜像效果。
Texture.LightProbe这是用于光探针的HDRI球映射的默认值。此模式对于与lightProbe属性关联的Texture对象无需手动设置，因为它会被自动推导。

minFilter : enumeration

此属性确定在纹理“缩小”，即在屏幕空间中一个像素覆盖一个或多个texel时如何采样纹理。

默认值是Texture.Linear。

常量描述
Texture.Nearest使用最接近的texel的值。
Texture.Linear取四个最接近的texel，并进行双线性插值。

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

另请参阅：magFilter和mipFilter。


mipFilter : enumeration

此属性确定当texel覆盖的像素少于一个时，如何采样纹理米配图。

默认值是Texture.None。

常量描述
Texture.None禁用米配采样。
Texture.Nearest使用米配图并采样最接近的texel的值。
Texture.Linear使用米配图并插值多个texel值。

注意：此属性对于没有米配图的Texture对象没有作用。

另请参阅 minFilter 和 magFilter。


pivotU : float

此属性设置用于将旋转应用于 rotationUV 时使用的基点 U 位置。

默认值为 0.0。

注意：此属性在 Texture 与 DefaultMaterial 或 PrincipledMaterial 结合使用时有效。自定义材质提供了它自己的着色器代码，因此配置此属性所定义的变换将被忽略，且由提供应用程序着色器的代码实现。

另请参阅 rotationUV。


pivotV : float

此属性设置用于将旋转应用于 rotationUV 时使用的基点 V 位置。

默认值为 0.0。

注意：此属性在 Texture 与 DefaultMaterial 或 PrincipledMaterial 结合使用时有效。自定义材质提供了它自己的着色器代码，因此配置此属性所定义的变换将被忽略，且由提供应用程序着色器的代码实现。

另请参阅 pivotU 和 rotationUV。


positionU : float

此属性偏移 U 坐标映射从左至右。

默认值为 0.0。

注意：此属性在 Texture 与 DefaultMaterial 或 PrincipledMaterial 结合使用时有效。自定义材质提供了它自己的着色器代码，因此配置此属性所定义的变换将被忽略，且由提供应用程序着色器的代码实现。

另请参阅 positionV。


positionV : float

此属性偏移 V 坐标映射从下至顶。

默认值为 0.0。

注意： Qt Quick 3D 使用 OpenGL 样式的顶点数据，无论运行时使用的图形 API 如何。因此，UV 位置 (0, 0) 指的是图像数据的左下角。

注意：此属性在 Texture 与 DefaultMaterial 或 PrincipledMaterial 结合使用时有效。自定义材质提供了它自己的着色器代码，因此配置此属性所定义的变换将被忽略，且由提供应用程序着色器的代码实现。

另请参阅 positionU。


rotationUV : float

此属性绕基点旋转纹理。这是使用欧拉角定义的，正值旋转为顺时针。

默认值为 0.0。

注意：此属性在 Texture 与 DefaultMaterial 或 PrincipledMaterial 结合使用时有效。自定义材质提供了它自己的着色器代码，因此配置此属性所定义的变换将被忽略，且由提供应用程序着色器的代码实现。

另请参阅 pivotU 和 pivotV。


scaleU : float

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

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

默认值为 1.0。

注意：此属性在 Texture 与 DefaultMaterial 或 PrincipledMaterial 结合使用时有效。自定义材质提供了它自己的着色器代码，因此配置此属性所定义的变换将被忽略，且由提供应用程序着色器的代码实现。

另请参阅 tilingModeHorizontal。


scaleV : float

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

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

默认值为 1.0。

注意：此属性在 Texture 与 DefaultMaterial 或 PrincipledMaterial 结合使用时有效。自定义材质提供了它自己的着色器代码，因此配置此属性所定义的变换将被忽略，且由提供应用程序着色器的代码实现。

另请参阅 tilingModeVertical。


source : url

此属性包含包含纹理使用的数据的图像或纹理文件的地址。

该属性是 URL，它遵循与其他源属性相同的规则，如 Image.source。对于 Texture，仅支持 qrc 和 file 方案。当不存在方案且值是相对路径时，它假定相对于组件的位置（即 .qml 文件的位置）。

源文件可以具有任何常规图像文件格式 Qt 支持。此外，Texture 支持与 QtQuick::Image 相同的 压缩纹理文件类型。

注意： 从如 .png 或 .jpg 等图像文件读取的纹理数据涉及到在纹理中按其定义的顺序存储像素行，由 Qt Quick 3D 渲染引擎定义。当源文件是包含 - 可能是压缩的 - 纹理数据的容器时，这些转换不能在像素数据级别发生。这些文件的示例有 .ktx 或 .pkm。取而代之的是，Texture 在片段着色器代码中隐式启用垂直翻转，以获得相同的屏幕效果。这由 autoOrientation 属性控制，并且可以禁用，如果需要的话。

注意： 一些纹理压缩工具可能会在图像数据上自动应用垂直镜像（翻转）。在现代工具中，这通常是一个可选设置。了解资产预处理管道中使用的设置很重要，因为出乎意料的纹理翻转及其导致的对象纹理错误，其根本原因可能在于资产本身，而这超出了应用程序和渲染引擎的控制。当资产需要时，应用程序可以始终自己设置flipV属性。

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


sourceItem : Item

此属性定义一个用作纹理源的Item。使用此属性允许任何2D Qt Quick内容通过渲染脱屏层作为纹理源来用作纹理源。

如果该项目是一个纹理提供者，则不会使用额外的纹理。

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

注意： 当前只有当用户一次只能与一个sourceItem实例进行交互时，才会将输入事件转发给用作纹理源的Item。换句话说：您可以在多个纹理之间共享相同的Item，但之后您不能同时与多个纹理上的同一项进行多触摸交互。因此，如果预期将在内部操纵交互式项，则最好为每个纹理实例使用一个单独的2D子场景实例。

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

注意： 包含Qt Quick脱屏渲染结果的纹理实际上将具有与通过source属性接收内容的纹理不同的Y轴方向。当与DefaultMaterial或PrincipledMaterial一起使用时，这完全对应用程序来说是透明的，因为只要设置autoOrientation属性为true，必要的UV转换就会自动应用，因此不需要采取任何进一步的行动，无论纹理是从何而来的。然而，当开发自定义材料时，需要在采样纹理和处理UV坐标时记住这一点。

另请参阅 source、textureData和autoOrientation。


textureData : TextureData

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

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

另请参阅 source、sourceItem 以及 Qt Quick 3D - Procedural Texture Example。


textureProvider : RenderExtension [since 6.7]

此属性包含将为此项提供 RenderExtension 的 QRhiTexture。

注意：由 RenderExtension 创建的纹理需要通过 注册 使其对引擎可用。

此属性自 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。


© 2024 The Qt Company Ltd. 本文档中的文档贡献归其各自的所有者所有。提供的文档受 GNU 自由文档许可证版本 1.3 的条款约束，由自由软件基金会发布。Qt 和相应的标志是 The Qt Company Ltd. 在芬兰和其他国家/地区的商标。所有其他商标均为其各自所有者的财产。