QRhiResourceUpdateBatch Class

Member Function Documentation

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

Enqueues a texture-to-texture copy operation from src into dst as described by desc.

void QRhiResourceUpdateBatch::generateMips(QRhiTexture *tex)

Enqueues a mipmap generation operation for the specified texture tex.

Both 2D and cube textures are supported.

bool QRhiResourceUpdateBatch::hasOptimalCapacity() const

Returns true until the number of buffer and texture operations enqueued onto this batch is below a reasonable limit.

The return value is false when the number of buffer and/or texture operations added to this batch have reached, or are about to reach, a certain limit. The batch is fully functional afterwards as well, but may need to allocate additional memory. Therefore, a renderer that collects lots of buffer and texture updates in a single batch when preparing a frame may want to consider submitting the batch and starting a new one when this function returns false.

void QRhiResourceUpdateBatch::merge(QRhiResourceUpdateBatch *other)

Copies all queued operations from the other batch into this one.

This allows for a convenient pattern where resource updates that are already known during the initialization step are collected into a batch that is then merged into another when starting to first render pass later on:

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)

Enqueues reading back a region of the QRhiBuffer buf. The size of the region is specified by size in bytes, offset is the offset in bytes to start reading from.

A readback is asynchronous. result contains a callback that is invoked when the operation has completed. The data is provided in QRhiReadbackResult::data. Upon successful completion that QByteArray will have a size equal to size. On failure the QByteArray will be empty.

See also readBackTexture(), QRhi::isFeatureSupported(), and QRhi::resourceLimit().

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

Enqueues a texture-to-host copy operation as described by rb.

Normally rb will specify a QRhiTexture as the source. However, when the swapchain in the current frame was created with QRhiSwapChain::UsedAsTransferSource, it can also be the source of the readback. For this, leave the texture set to null in rb.

Unlike other operations, the results here need to be processed by the application. Therefore, result provides not just the data but also a callback as operations on the batch are asynchronous by nature:

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);

A single readback operation copies one mip level of one layer (cubemap face or 3D slice or texture array element) at a time. The level and layer are specified by the respective fields in rb.

See also readBackBuffer() and QRhi::resourceLimit().

void QRhiResourceUpdateBatch::release()

Returns the batch to the pool. This should only be used when the batch is not passed to one of QRhiCommandBuffer::beginPass(), QRhiCommandBuffer::endPass(), or QRhiCommandBuffer::resourceUpdate() because these implicitly call destroy().

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

Enqueues updating a region of a QRhiBuffer buf created with the type QRhiBuffer::Dynamic.

The region is specified offset and size. The actual bytes to write are specified by data which must have at least size bytes available. data can safely be destroyed or changed once this function returns.

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

Enqueues updating a region of a QRhiBuffer buf created with the type QRhiBuffer::Immutable or QRhiBuffer::Static.

The region is specified offset and size. The actual bytes to write are specified by data which must have at least size bytes available. data can safely be destroyed or changed once this function returns.

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

This is an overloaded function.

Enqueues updating the entire QRhiBuffer buf created with the type QRhiBuffer::Immutable or QRhiBuffer::Static.

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

Enqueues uploading the image data for mip level 0 of layer 0 of the texture tex.

tex must have an uncompressed format. Its format must also be compatible with the QImage::format() of image. The source data is given in image.

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

Enqueues uploading the image data for one or more mip levels in one or more layers of the texture tex.

The details of the copy (source QImage or compressed texture data, regions, target layers and levels) are described in desc.