QRhiResourceUpdateBatch Class

成员函数文档

void QRhiResourceUpdateBatch::copyTexture(QRhiTexture *dst, QRhiTexture *src, const QRhiTextureCopyDescription &desc = QRhiTextureCopyDescription())

将纹理到纹理的复制操作从src 排入队列，目标为dst ，具体说明参见desc 。

void QRhiResourceUpdateBatch::generateMips(QRhiTexture *tex)

将指定纹理tex 的 Mipmap 生成操作加入队列。

支持 2D 和立方体纹理。当报告支持QRhi::OneDimensionalTextureMipmaps 或QRhi::ThreeDimensionalTextureMipmaps 功能时，分别支持 1D 和 3D 纹理。

bool QRhiResourceUpdateBatch::hasOptimalCapacity() const

在排入此批处理的缓冲区和纹理操作数量低于合理阈值之前，该函数返回 true。

当添加到该批处理中的缓冲区和/或纹理操作数量已达到或即将达到一定限制时，返回值为 false。此后该批处理仍可正常运行，但可能需要分配额外的内存。 因此，当渲染器在准备帧时将大量缓冲区和纹理更新收集到单个批处理中，且本函数返回 false 时，建议考虑使用submitting the batch 和starting a new one 。

void QRhiResourceUpdateBatch::merge(QRhiResourceUpdateBatch *other)

将other 批处理中所有已排队的操作复制到此批处理中。

这提供了一种便捷的模式：在初始化步骤中已知的资源更新会被收集到一个批处理中，随后在稍后开始首次渲染遍时，该批处理会被合并到另一个批处理中：

void init()
{
    initialUpdates = rhi->nextResourceUpdateBatch();
    initialUpdates->uploadStaticBuffer(vbuf, vertexData);
    initialUpdates->uploadStaticBuffer(ibuf, indexData);
    // ...
}

void render()
{
    QRhiResourceUpdateBatch *resUpdates = rhi->nextResourceUpdateBatch();
    if (initialUpdates) {
        resUpdates->merge(initialUpdates);
        initialUpdates->release();
        initialUpdates = nullptr;
    }
    // resUpdates->updateDynamicBuffer(...);
    cb->beginPass(rt, clearCol, clearDs, resUpdates);
}

void QRhiResourceUpdateBatch::readBackBuffer(QRhiBuffer *buf, quint32 offset, quint32 size, QRhiReadbackResult *result)

将QRhiBuffer buf 中某个区域的读回操作加入队列。该区域的大小由size 以字节为单位指定，offset 表示开始读取的偏移量（以字节为单位）。

读回操作是异步的。result 包含一个回调函数，该函数将在操作完成时被调用。数据存储在QRhiReadbackResult::data 中。操作成功完成后，QByteArray 的大小将等于size 。若操作失败，QByteArray 将为空。

另请参阅 readBackTexture()、QRhi::isFeatureSupported()，以及QRhi::resourceLimit()。

void QRhiResourceUpdateBatch::readBackTexture(const QRhiReadbackDescription &rb, QRhiReadbackResult *result)

将纹理到主机的复制操作加入队列，具体说明参见rb 。

通常情况下，rb 会指定一个QRhiTexture 作为源。但是，当当前帧中的交换链是通过QRhiSwapChain::UsedAsTransferSource 创建时，它也可以作为读回操作的源。为此，请在rb 中将纹理设置为 null。

与其他操作不同，此处的结果需要由应用程序进行处理。因此，result 不仅提供数据，还提供一个回调函数，因为批量操作本质上是异步的：

rhi->beginFrame(swapchain);
cb->beginPass(swapchain->currentFrameRenderTarget(), colorClear, dsClear);
// ...
QRhiReadbackResult *rbResult = new QRhiReadbackResult;
rbResult->completed = [rbResult] {
    {
        const QImage::Format fmt = QImage::Format_RGBA8888_Premultiplied; // fits QRhiTexture::RGBA8
        const uchar *p = reinterpret_cast<const uchar *>(rbResult->data.constData());
        QImage image(p, rbResult->pixelSize.width(), rbResult->pixelSize.height(), fmt);
        image.save("result.png");
    }
    delete rbResult;
};
QRhiResourceUpdateBatch *u = nextResourceUpdateBatch();
QRhiReadbackDescription rb; // no texture -> uses the current backbuffer of sc
u->readBackTexture(rb, rbResult);
cb->endPass(u);
rhi->endFrame(swapchain);

单次读回操作每次复制一层中一个mip级（立方贴图面、3D切片或纹理数组元素）。mip级和层由rb 中的相应字段指定。

另请参阅 readBackBuffer() 和QRhi::resourceLimit()。

void QRhiResourceUpdateBatch::release()

将批处理归还至池中。此方法仅应在批处理未传递给QRhiCommandBuffer::beginPass()、QRhiCommandBuffer::endPass() 或QRhiCommandBuffer::resourceUpdate() 中的任意一个时使用，因为这些方法会隐式调用 destroy()。

void QRhiResourceUpdateBatch::updateDynamicBuffer(QRhiBuffer *buf, quint32 offset, quint32 size, const void *data)

将更新QRhiBuffer buf 中某个区域的操作加入队列，该区域由类型QRhiBuffer::Dynamic 创建。

该区域由offset 和size 指定。实际要写入的字节由data 指定，该区域必须至少有size 字节的可用空间。

data 该缓冲区已被复制，因此本函数返回后可安全地销毁或修改它。

[since 6.10] void QRhiResourceUpdateBatch::updateDynamicBuffer(QRhiBuffer *buf, quint32 offset, QByteArray data)

将更新QRhiBuffer buf 中某个区域的操作加入队列，该区域由类型QRhiBuffer::Dynamic 创建。

data 通过此重载，数据会被移入批处理中，而非被复制。

该函数于 Qt 6.10 中引入。

void QRhiResourceUpdateBatch::uploadStaticBuffer(QRhiBuffer *buf, quint32 offset, quint32 size, const void *data)

将更新QRhiBuffer buf 中某个区域的操作加入队列，该区域是使用类型QRhiBuffer::Immutable 或QRhiBuffer::Static 创建的。

该区域由offset 和size 指定。实际要写入的字节由data 指定，该区域必须至少有size 字节的可用空间。

data 该数组已被复制，因此在本函数返回后，可安全地销毁或修改该数组。

[since 6.10] void QRhiResourceUpdateBatch::uploadStaticBuffer(QRhiBuffer *buf, QByteArray data)

将更新整个QRhiBuffer buf 的操作加入队列，该 是通过类型QRhiBuffer::Immutable 或QRhiBuffer::Static 创建的。

data 使用此重载时，数据会被移入批处理，而非被复制。

data size 必须等于buf 的大小。

该函数在 Qt 6.10 中引入。

void QRhiResourceUpdateBatch::uploadStaticBuffer(QRhiBuffer *buf, const void *data)

将更新整个QRhiBuffer buf 的任务加入队列，该 由类型QRhiBuffer::Immutable 或QRhiBuffer::Static 创建。

[since 6.10] void QRhiResourceUpdateBatch::uploadStaticBuffer(QRhiBuffer *buf, quint32 offset, QByteArray data)

将更新QRhiBuffer buf 中某个区域的操作加入队列，该区域由类型QRhiBuffer::Immutable 或QRhiBuffer::Static 创建。

data 通过此重载，数据会被移入批处理中，而非被复制。

该函数在 Qt 6.10 中引入。

void QRhiResourceUpdateBatch::uploadTexture(QRhiTexture *tex, const QImage &image)

将纹理tex 的第 0 层第 0 级 MIP 级别的图像数据加入上传队列。

tex 必须为未压缩格式。其格式还必须与image 中的QImage::format() 兼容。源数据详见image 。

void QRhiResourceUpdateBatch::uploadTexture(QRhiTexture *tex, const QRhiTextureUploadDescription &desc)

将纹理tex 中一个或多个图层的一个或多个 MIP 级别的图像数据加入上传队列。

复制操作的详细信息（源QImage 或压缩纹理数据、区域、目标图层和级别）在desc 中有详细说明。