Back to Qt.io
Contact Us Blog Download Qt
本页内容

QRhiTextureUploadDescription Class

描述了一项纹理上传操作。更多内容...

标题： #include <rhi/qrhi.h>
CMake： find_package(Qt6 REQUIRED COMPONENTS GuiPrivate)
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);

当涉及立方贴图、预生成的米普图、压缩纹理或部分上传时，应用程序必须改用此类。

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 default] QRhiTextureUploadDescription::QRhiTextureUploadDescription()

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

QRhiTextureUploadDescription::QRhiTextureUploadDescription(const QRhiTextureUploadEntry &entry)

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

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

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

注意： list 中 还可以包含多个具有相同图层（layer）和级别（level）的QRhiTextureUploadEntry 元素。当这些上传为部分上传时（即其子资源描述中的源大小或图像小于子资源尺寸），这种做法是有意义的，并且比分别调用 uploadTexture() 更高效。

const QRhiTextureUploadEntry *QRhiTextureUploadDescription::cbeginEntries() const

返回一个指向条目列表中第一个项目的 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 设置条目列表。

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