QRhiResourceUpdateBatch Class

成员函数文档

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

如desc 所述，从src 向dst 中排队进行纹理到纹理的复制操作。

void QRhiResourceUpdateBatch::generateMips(QRhiTexture *tex)

为指定的纹理tex 查询 mipmap 生成操作。

支持二维和立方体纹理。

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 中将纹理设置为空。

与其他操作不同，这里的结果需要由应用程序处理。因此，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 层。级别和层由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::Dynamic 类型创建的QRhiBuffer buf 的一个区域。

区域由offset 和size 指定。要写入的实际字节由data 指定，而 必须至少有size 字节可用。一旦此函数返回，data 可以安全地销毁或更改。

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

排队更新以QRhiBuffer::Immutable 或QRhiBuffer::Static 类型创建的QRhiBuffer buf 的一个区域。

区域由offset 和size 指定。要写入的实际字节由data 指定，而 必须至少有size 字节可用。一旦此函数返回，data 可以安全地销毁或更改。

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

这是一个重载函数。

对以QRhiBuffer::Immutable 或QRhiBuffer::Static 类型创建的整个QRhiBuffer buf 进行排队更新。

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 。