Back to Qt.io
Contact Us Blog Download Qt

QRhiTextureUploadDescription Class

描述纹理上传操作。更多

头文件： #include <rhi/qrhi.h>
CMake： find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::GuiPrivate)
qmake： QT += gui-private
自Qt 6.6

公共函数

QRhiTextureUploadDescription()
QRhiTextureUploadDescription(const QRhiTextureUploadEntry &entry)
QRhiTextureUploadDescription(std::initializer_list<QRhiTextureUploadEntry> list)
const QRhiTextureUploadEntry *cbeginEntries() const
const QRhiTextureUploadEntry *cendEntries() const
const QRhiTextureUploadEntry *entryAt(qsizetype index) const
qsizetype entryCount() const
void setEntries(std::initializer_list<QRhiTextureUploadEntry> list)
void setEntries(InputIterator first, InputIterator last)

详细说明

与QRhiResourceUpdateBatch::uploadTexture() 一起使用。该函数有两个变体：一个接收QImage ，另一个接收 QRhiTextureUploadDescription。前者是一个便捷版本，内部创建了一个 QRhiTextureUploadDescription，其中包含一张针对 0 层 0 级的图像。

举例说明一个常见的简单案例，即希望将QImage 的内容上传到具有匹配像素尺寸的QRhiTexture ：

QImage image(256, 256, QImage::Format_RGBA8888);
image.fill(Qt::green); // or could use a QPainter targeting image
QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(256, 256));
texture->create();
QRhiResourceUpdateBatch *u = rhi->nextResourceUpdateBatch();
u->uploadTexture(texture, image);

如果涉及立方体贴图、预生成的 mip 图像、压缩纹理或部分上传，应用程序将不得不使用该类。

QRhiTextureUploadDescription 还可以指定批量上传，这在生成地图集或字形缓存纹理时非常有用：它支持对同一子资源（指同一图层和级别）的多个部分上传，而且根据后端和底层图形 API 的不同，如果批量上传到同一个 QRhiTextureUploadDescription 中，效率会更高，而不是对每个上传都发出单独的uploadTexture() 命令。

注意： 立方体贴图的六个面都有一个图层，顺序为 +X、-X、+Y、-Y、+Z、-Z。

例如，指定立方体贴图的面可以如下所示：

QImage faces[6];
// ...
QVarLengthArray<QRhiTextureUploadEntry, 6> entries;
for (int i = 0; i < 6; ++i)
  entries.append(QRhiTextureUploadEntry(i, 0, faces[i]));
QRhiTextureUploadDescription desc;
desc.setEntries(entries.cbegin(), entries.cend());
resourceUpdates->uploadTexture(texture, desc);

另一个为压缩纹理指定 mip 图像的例子：

QList<QRhiTextureUploadEntry> entries;
const int mipCount = rhi->mipLevelsForSize(compressedTexture->pixelSize());
for (int level = 0; level < mipCount; ++level) {
    const QByteArray compressedDataForLevel = ..
    entries.append(QRhiTextureUploadEntry(0, level, compressedDataForLevel));
}
QRhiTextureUploadDescription desc;
desc.setEntries(entries.cbegin(), entries.cend());
resourceUpdates->uploadTexture(compressedTexture, desc);

对于针对同一子资源的部分上传，建议尽可能将它们批量合并为一个上传请求：

QRhiTextureSubresourceUploadDescription subresDesc(image);
subresDesc.setSourceSize(QSize(10, 10));
subResDesc.setDestinationTopLeft(QPoint(50, 40));
QRhiTextureUploadEntry entry(0, 0, subresDesc); // layer 0, level 0

QRhiTextureSubresourceUploadDescription subresDesc2(image);
subresDesc2.setSourceSize(QSize(30, 40));
subResDesc2.setDestinationTopLeft(QPoint(100, 200));
QRhiTextureUploadEntry entry2(0, 0, subresDesc2); // layer 0, level 0, i.e. same subresource

QRhiTextureUploadDescription desc({ entry, entry2});
resourceUpdates->uploadTexture(texture, desc);

注意： 这是一个兼容性保证有限的 RHI API，详情请参见QRhi 。

另请参阅 QRhiResourceUpdateBatch 。

成员函数文档

[constexpr noexcept] QRhiTextureUploadDescription::QRhiTextureUploadDescription()

构建一个空的纹理上传描述。

QRhiTextureUploadDescription::QRhiTextureUploadDescription(const QRhiTextureUploadEntry &entry)

构建一个纹理上传描述，其中包含一个由entry 描述的单一子资源上传。

QRhiTextureUploadDescription::QRhiTextureUploadDescription(std::initializer_list<QRhiTextureUploadEntry> list)

用指定的list 条目构建纹理上传描述。

注意： list 也可以包含多个具有相同层和级别的QRhiTextureUploadEntry 元素。当这些上传是部分上传时，即其子资源描述的源尺寸或图像小于子资源尺寸时，这样做是有意义的，而且比发布单独的 uploadTexture() 更有效率。

const QRhiTextureUploadEntry *QRhiTextureUploadDescription::cbeginEntries() const

返回指向条目列表中第一个条目的常量迭代器。

const QRhiTextureUploadEntry *QRhiTextureUploadDescription::cendEntries() const

返回一个常量迭代器，指向条目列表中的最后一个条目。

const QRhiTextureUploadEntry *QRhiTextureUploadDescription::entryAt(qsizetype index) const

返回index 中的条目。

qsizetype QRhiTextureUploadDescription::entryCount() const

返回条目数。

void QRhiTextureUploadDescription::setEntries(std::initializer_list<QRhiTextureUploadEntry> list)

设置list 条目。

template <typename InputIterator> void QRhiTextureUploadDescription::setEntries(InputIterator first, InputIterator last)

使用迭代器first 和last 设置条目列表。

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