QQuick3DTextureData Class

用于定义自定义纹理数据的基类。更多...

Header:	`#include <QQuick3DTextureData>`
Since:	Qt 6.0
In QML:	TextureData
Inherits:	QQuick3DObject

所有成员的列表，包括继承的成员

公共类型

enum	Format { None, RGBA8, RGBA16F, RGBA32F, RGBE8, …, ASTC_12x12 }

公共函数

int	depth() const
QQuick3DTextureData::Format	format() const
bool	hasTransparency() const
void	setDepth(int depth)
void	setFormat(QQuick3DTextureData::Format format)
void	setHasTransparency(bool hasTransparency)
void	setSize(const QSize &size)
void	setTextureData(const QByteArray &data)
QSize	size() const
const QByteArray	textureData() const

详细说明

QQuick3DTextureData 类可用于为Qt Quick 3D 场景中的Texture 指定自定义纹理数据。

虽然并非严格必要，但通常的做法是继承自该类。随后通过将其注册到类型系统中，将子类暴露给 QML。这样，Texture 的textureData 属性即可设置为引用该已注册类型的实例。

实现示例：

class CustomTextureData : public QQuick3DTextureData
{
    Q_OBJECT
    ... properties ...

public:
    CustomTextureData() { regenerateTextureData(); }

    void setProperty(...)
    {
        // Change relevant internal data.
        // ...

        // Update the texture data
        regenerateTextureData();

        // Finally, trigger an update. This is relevant in case nothing else
        // is changed in the scene; this way we make sure a new frame will
        // be rendered
        update();
    }
private:
    void regenerateTextureData()
    {
        QByteArray textureData;
        textureData = generateTextureData();
        setTextureData(textureData);
        setSize(QSize(256, 256));
        setFormat(QQuick3DTextureData::Format::RGBA8)
        setHasTransparency(true);
    }
};

该类随后可作为 QML 类型进行注册，并配合 `Texture` 使用。

在 Qt 5 中，类型注册是通过 `qmlRegisterType` 实现的：

qmlRegisterType<MyCustomTextureData>("Example", 1, 0, "MyCustomTextureData");

在 Qt 6 中，默认做法是借助构建系统进行自动注册。现在，.pro 文件无需调用qmlRegisterType ，而是可以包含以下内容：

CONFIG += qmltypes
QML_IMPORT_NAME = Example
QML_IMPORT_MAJOR_VERSION = 1

使用 CMake 时，自动注册是默认行为，因此除了基本的 QML 模块配置外，无需进行特殊设置：

qt_add_qml_module(application
    URI Example
    VERSION 1.0
)

类实现中应添加QML_NAMED_ELEMENT ：

class CustomTextureData : public QQuick3DTextureData
{
    Q_OBJECT
    QML_NAMED_ELEMENT(MyCustomTextureData)
    ...
};

随后，QML 代码即可使用该自定义类型：

import Example 1.0

Model {
    source: "#Cube"
    materials: [
        DefaultMaterial {
            diffuseMap: diffuseMapCustomTexture
        }
    ]
    Texture {
        id: diffuseMapCustomTexture
        textureData: MyCustomTextureData { }
    }
}

成员类型文档

enum QQuick3DTextureData::Format

返回在textureData 属性中指定的纹理数据的颜色格式。

常量	值	描述
`QQuick3DTextureData::None`	`0`	颜色格式未定义
`QQuick3DTextureData::RGBA8`	`1`	颜色格式被视为 R、G、B 和 alpha 通道中的 8 位整数。
`QQuick3DTextureData::RGBA16F`	`2`	颜色格式在 R、G、B 和 alpha 通道中被视为 16 位浮点数。
`QQuick3DTextureData::RGBA32F`	`3`	颜色格式在 R、G、B 和 alpha 通道中被视为 32 位浮点数。
`QQuick3DTextureData::RGBE8`	`4`	该颜色格式被视为 R、G 和 B 通道中的 8 位尾数以及 8 位共享指数。
`QQuick3DTextureData::R8`	`5`	该颜色格式在 R 通道中被视为 8 位整数。
`QQuick3DTextureData::R16`	`6`	该颜色格式在 R 通道中被视为 16 位整数。
`QQuick3DTextureData::R16F`	`7`	该颜色格式在 R 通道中被视为 16 位浮点数。
`QQuick3DTextureData::R32F`	`8`	该颜色格式被视为 R 通道为 32 位浮点数。
`QQuick3DTextureData::BC1`	`9`	该颜色格式被视为具有 R、G、B 和 alpha 通道的 BC1 压缩格式。
`QQuick3DTextureData::BC2`	`10`	该颜色格式被视为具有 R、G、B 和 alpha 通道的 BC2 压缩格式。
`QQuick3DTextureData::BC3`	`11`	该颜色格式被视为具有 R、G、B 和 alpha 通道的 BC3 压缩格式。
`QQuick3DTextureData::BC4`	`12`	该颜色格式被视为具有一个颜色通道的 BC4 压缩格式。
`QQuick3DTextureData::BC5`	`13`	该颜色格式被视为具有两个颜色通道的 BC5 压缩格式。
`QQuick3DTextureData::BC6H`	`14`	该颜色格式被视为具有三个高动态范围颜色通道的 BC6H 压缩格式。
`QQuick3DTextureData::BC7`	`15`	该颜色格式被视为具有 R、G、B 和 alpha 通道的 BC7 压缩格式。
`QQuick3DTextureData::DXT1_RGBA`	`16`	该颜色格式被视为具有 R、G、B 和 alpha 通道的 DXT1 压缩格式。
`QQuick3DTextureData::DXT1_RGB`	`17`	该颜色格式被视为具有 R、G 和 B 通道的 DXT1 压缩格式。
`QQuick3DTextureData::DXT3_RGBA`	`18`	该颜色格式被视为具有 R、G、B 和 alpha 通道的 DXT3 压缩格式。
`QQuick3DTextureData::DXT5_RGBA`	`19`	该颜色格式被视为具有 R、G、B 和 alpha 通道的 DXT5 压缩格式。
`QQuick3DTextureData::ETC2_RGB8`	`20`	该颜色格式被视为适用于 RGB888 数据的 ETC2 压缩格式
`QQuick3DTextureData::ETC2_RGB8A1`	`21`	该颜色格式被视为适用于 RGBA 数据的 ETC2 压缩格式，其中 alpha 为 1 位。
`QQuick3DTextureData::ETC2_RGBA8`	`22`	该颜色格式被视为包含 RGBA8888 数据的 ETC2 压缩格式。
`QQuick3DTextureData::ASTC_4x4`	`23`	该颜色格式被视为具有 4x4 块占用空间的 ASTC 压缩格式。
`QQuick3DTextureData::ASTC_5x4`	`24`	该颜色格式被视为具有 5x4 块占用空间的 ASTC 压缩格式。
`QQuick3DTextureData::ASTC_5x5`	`25`	该颜色格式被视为具有 5x5 块占用空间的 ASTC 压缩格式。
`QQuick3DTextureData::ASTC_6x5`	`26`	该颜色格式被视为具有 6x5 块占用空间的 ASTC 压缩格式。
`QQuick3DTextureData::ASTC_6x6`	`27`	该颜色格式被视为具有 6x6 块占用的 ASTC 压缩格式。
`QQuick3DTextureData::ASTC_8x5`	`28`	该颜色格式被视为具有 8x5 块占用的 ASTC 压缩格式。
`QQuick3DTextureData::ASTC_8x6`	`29`	该颜色格式被视为具有 8x6 块占用空间的 ASTC 压缩格式。
`QQuick3DTextureData::ASTC_8x8`	`30`	该颜色格式被视为具有 8x8 块占用空间的 ASTC 压缩格式。
`QQuick3DTextureData::ASTC_10x5`	`31`	该颜色格式被视为具有 10x5 块占用空间的 ASTC 压缩格式。
`QQuick3DTextureData::ASTC_10x6`	`32`	该颜色格式被视为具有 10x6 块占用空间的 ASTC 压缩格式。
`QQuick3DTextureData::ASTC_10x8`	`33`	该颜色格式被视为具有 10x8 块占用空间的 ASTC 压缩格式。
`QQuick3DTextureData::ASTC_10x10`	`34`	该颜色格式被视为具有 10x10 块占用空间的 ASTC 压缩格式。
`QQuick3DTextureData::ASTC_12x10`	`35`	该颜色格式被视为具有 12x10 块占位面积的 ASTC 压缩格式。
`QQuick3DTextureData::ASTC_12x12`	`36`	该颜色格式被视为具有 12x12 块占用空间的 ASTC 压缩格式。注意：除 `RGBA8`外，并非所有格式都在运行时受到支持，因为这取决于所使用的后端以及所使用的硬件。注意： `RGBE` 在内部以`RGBA8` 表示，但在用作光探针（lightProbe）或天空盒（skybox）纹理时，将其解释为上述描述的形式。注意：使用值`None` 时，系统将默认采用`RGBA8`

成员函数文档

int QQuick3DTextureData::depth() const

返回纹理数据的像素深度。

另请参阅 setDepth()。

QQuick3DTextureData::Format QQuick3DTextureData::format() const

返回纹理数据的格式。

另请参阅 setFormat()。

bool QQuick3DTextureData::hasTransparency() const

如果纹理数据具有透明度，则返回true 。

默认值为 `false`。

另请参阅 setHasTransparency()。

void QQuick3DTextureData::setDepth(int depth)

设置纹理数据的深度（depth ）单位为像素。将深度设置为大于0，表示该纹理将被作为3D纹理处理。

另请参阅 depth()。

void QQuick3DTextureData::setFormat(QQuick3DTextureData::Format format)

设置纹理数据的format 。

默认格式为 /c RGBA8

另请参阅 format()。

void QQuick3DTextureData::setHasTransparency(bool hasTransparency)

如果纹理数据包含具有非不透明值的有效Alpha通道，请将hasTransparency 设置为true。

引擎将此作为一项优化措施，以便对于支持 alpha 通道的格式，无需逐个检查每个值是否为非不透明值。

另请参阅 hasTransparency()。

void QQuick3DTextureData::setSize(const QSize &size)

将纹理数据的size 设置为像素单位。

另请参阅 size()。

void QQuick3DTextureData::setTextureData(const QByteArray &data)

设置纹理数据。data 的内容必须符合size 和format 中的规范，因为后端会尝试将该数据上传并作为指定大小和格式的纹理使用；若存在任何偏差，结果可能导致纹理渲染错误，甚至可能引发程序崩溃。

另请参阅 textureData()。

QSize QQuick3DTextureData::size() const

返回纹理数据的像素大小。

另请参阅 setSize()。

const QByteArray QQuick3DTextureData::textureData() const

返回由该项定义的当前纹理数据。

另请参阅 setTextureData()。

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