QRhiResourceUpdateBatch Class Reference

\inmodule QtGui More...

#include <qrhi.h>

Collaboration diagram for QRhiResourceUpdateBatch:

Public Member Functions
	~QRhiResourceUpdateBatch ()
void	release ()
void	merge (QRhiResourceUpdateBatch *other)
	Copies all queued operations from the other batch into this one.
bool	hasOptimalCapacity () const
void	updateDynamicBuffer (QRhiBuffer *buf, quint32 offset, quint32 size, const void *data)
	Enqueues updating a region of a QRhiBuffer buf created with the type QRhiBuffer::Dynamic.
void	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.
void	uploadStaticBuffer (QRhiBuffer *buf, const void *data)
	Enqueues updating the entire QRhiBuffer buf created with the type QRhiBuffer::Immutable or QRhiBuffer::Static.
void	readBackBuffer (QRhiBuffer *buf, quint32 offset, quint32 size, QRhiReadbackResult *result)
	Enqueues reading back a region of the QRhiBuffer buf.
void	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.
void	uploadTexture (QRhiTexture *tex, const QImage &image)
	Enqueues uploading the image data for mip level 0 of layer 0 of the texture tex.
void	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	readBackTexture (const QRhiReadbackDescription &rb, QRhiReadbackResult *result)
	Enqueues a texture-to-host copy operation as described by rb.
void	generateMips (QRhiTexture *tex)
	Enqueues a mipmap generation operation for the specified texture tex.

Friends
class	QRhiResourceUpdateBatchPrivate
class	QRhi

Detailed Description

\inmodule QtGui

Since

6.6

Records upload and copy type of operations.

With QRhi it is no longer possible to perform copy type of operations at arbitrary times. Instead, all such operations are recorded into batches that are then passed, most commonly, to QRhiCommandBuffer::beginPass(). What then happens under the hood is hidden from the application: the underlying implementations can defer and implement these operations in various different ways.

A resource update batch owns no graphics resources and does not perform any actual operations on its own. It should rather be viewed as a command buffer for update, upload, and copy type of commands.

To get an available, empty batch from the pool, call QRhi::nextResourceUpdateBatch().

Note

This is a RHI API with limited compatibility guarantees, see \l QRhi for details.

Definition at line 1693 of file qrhi.h.

Constructor & Destructor Documentation

~QRhiResourceUpdateBatch()

QRhiResourceUpdateBatch::~QRhiResourceUpdateBatch

(

)

Definition at line 8500 of file qrhi.cpp.

Member Function Documentation

copyTexture()

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.

Note

The source texture src must be created with QRhiTexture::UsedAsTransferSource.

The format of the textures must match. With most graphics APIs the data is copied as-is without any format conversions. If dst and src are created with different formats, unspecified issues may arise.

Definition at line 8718 of file qrhi.cpp.

References QRhiResourceUpdateBatchPrivate::activeTextureOpCount, QRhiResourceUpdateBatchPrivate::TextureOp::copy(), desc, and QRhiResourceUpdateBatchPrivate::textureOps.

Referenced by QSGRhiAtlasTexture::Texture::removedFromAtlas(), QQuick3DSceneRenderer::renderToRhiTexture(), and QSGRhiTextureGlyphCache::resizeTextureData().

Here is the call graph for this function:

Here is the caller graph for this function:

generateMips()

void QRhiResourceUpdateBatch::generateMips

(

QRhiTexture *

tex

)

Enqueues a mipmap generation operation for the specified texture tex.

Both 2D and cube textures are supported.

Note

The texture must be created with QRhiTexture::MipMapped and QRhiTexture::UsedWithGenerateMips.

Warning

QRhi cannot guarantee that mipmaps can be generated for all supported texture formats. For example, QRhiTexture::RGBA32F is not a filterable format in OpenGL ES 3.0 and Metal on iOS, and therefore the mipmap generation request may fail. RGBA8 and RGBA16F are typically filterable, so it is recommended to use these formats when mipmap generation is desired.

Definition at line 8812 of file qrhi.cpp.

References QRhiResourceUpdateBatchPrivate::activeTextureOpCount, QRhiResourceUpdateBatchPrivate::TextureOp::genMips(), and QRhiResourceUpdateBatchPrivate::textureOps.

Referenced by QSGPlainTexture::commitTextureOperations(), QSSGReflectionMapEntry::renderMips(), and ScreenMapPass::renderPass().

Here is the call graph for this function:

Here is the caller graph for this function:

hasOptimalCapacity()

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 \l{QRhiCommandBuffer::resourceUpdate()}{submitting the batch} and \l{QRhi::nextResourceUpdateBatch()}{starting a new one} when this function returns false.

Definition at line 8571 of file qrhi.cpp.

References QRhiResourceUpdateBatchPrivate::hasOptimalCapacity().

Here is the call graph for this function:

merge()

void QRhiResourceUpdateBatch::merge

(

QRhiResourceUpdateBatch *

other

)

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

Note

other may no longer contain valid data after the merge operation, and must not be submitted, but it will still need to be released by calling release().

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

Definition at line 8553 of file qrhi.cpp.

References QRhiResourceUpdateBatchPrivate::merge(), and other().

Referenced by QSGRhiDistanceFieldGlyphCache::commitResourceUpdates(), and QSGRhiTextureGlyphCache::commitResourceUpdates().

Here is the call graph for this function:

Here is the caller graph for this function:

readBackBuffer()

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.

Note

Reading buffers with a usage different than QRhiBuffer::UniformBuffer is supported only when the QRhi::ReadBackNonUniformBuffer feature is reported as supported.

The asynchronous readback is guaranteed to have completed when one of the following conditions is met: \l{QRhi::finish()}{finish()} has been called; or, at least N frames have been \l{QRhi::endFrame()}{submitted}, including the frame that issued the readback operation, and the \l{QRhi::beginFrame()}{recording of a new frame} has been started, where N is the \l{QRhi::resourceLimit()}{resource limit value} returned for QRhi::MaxAsyncReadbackFrames.

See also

readBackTexture(), QRhi::isFeatureSupported(), QRhi::resourceLimit()

Definition at line 8665 of file qrhi.cpp.

References QRhiResourceUpdateBatchPrivate::activeBufferOpCount, QRhiResourceUpdateBatchPrivate::bufferOps, and QRhiResourceUpdateBatchPrivate::BufferOp::read().

Here is the call graph for this function:

readBackTexture()

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

Note

The texture must be created with QRhiTexture::UsedAsTransferSource.

Multisample textures cannot be read back.

The readback returns raw byte data, in order to allow the applications to interpret it in any way they see fit. Be aware of the blending settings of rendering code: if the blending is set up to rely on premultiplied alpha, the results of the readback must also be interpreted as Premultiplied.

When interpreting the resulting raw data, be aware that the readback happens with a byte ordered format. A \l{QRhiTexture::RGBA8}{RGBA8} texture maps therefore to byte ordered QImage formats, such as, QImage::Format_RGBA8888.

The asynchronous readback is guaranteed to have completed when one of the following conditions is met: \l{QRhi::finish()}{finish()} has been called; or, at least N frames have been \l{QRhi::endFrame()}{submitted}, including the frame that issued the readback operation, and the \l{QRhi::beginFrame()}{recording of a new frame} has been started, where N is the \l{QRhi::resourceLimit()}{resource limit value} returned for QRhi::MaxAsyncReadbackFrames.

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(), QRhi::resourceLimit()

Definition at line 8788 of file qrhi.cpp.

References QRhiResourceUpdateBatchPrivate::activeTextureOpCount, QRhiResourceUpdateBatchPrivate::TextureOp::read(), and QRhiResourceUpdateBatchPrivate::textureOps.

Referenced by QSGRhiSupport::grabAndBlockInCurrentFrame(), QQuickWidgetPrivate::grabFramebuffer(), main(), renderToKTXFileInternal(), and QSGRhiLayer::toImage().

Here is the call graph for this function:

Here is the caller graph for this function:

release()

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().

Note

QRhiResourceUpdateBatch instances must never by deleted by applications.

Definition at line 8514 of file qrhi.cpp.

References QRhiResourceUpdateBatchPrivate::free().

Referenced by QSGDefaultRenderContext::resetGlyphCacheResources().

Here is the call graph for this function:

Here is the caller graph for this function:

updateDynamicBuffer()

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.

Note

If host writes are involved, which is the case with updateDynamicBuffer() typically as such buffers are backed by host visible memory with most backends, they may accumulate within a frame. Thus pass 1 reading a region changed by a batch passed to pass 2 may see the changes specified in pass 2's update batch.

QRhi transparently manages double buffering in order to prevent stalling the graphics pipeline. The fact that a QRhiBuffer may have multiple native buffer objects underneath can be safely ignored when using the QRhi and QRhiResourceUpdateBatch.

Definition at line 8595 of file qrhi.cpp.

References QRhiResourceUpdateBatchPrivate::activeBufferOpCount, QRhiResourceUpdateBatchPrivate::bufferOps, QRhiResourceUpdateBatchPrivate::BufferOp::changeToDynamicUpdate(), and QRhiResourceUpdateBatchPrivate::BufferOp::dynamicUpdate().

Referenced by main(), QSSGSubsetRenderable::prepareInstancing(), QVideoWindowPrivate::render(), QSSGReflectionMapEntry::renderMips(), QQuick3DSceneRenderer::renderToRhiTexture(), and updateMatrix3x3().

Here is the call graph for this function:

Here is the caller graph for this function:

uploadStaticBuffer() [1/2]

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

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

Definition at line 8630 of file qrhi.cpp.

References QRhiResourceUpdateBatchPrivate::activeBufferOpCount, QRhiResourceUpdateBatchPrivate::bufferOps, QRhiResourceUpdateBatchPrivate::BufferOp::changeToStaticUpload(), and QRhiResourceUpdateBatchPrivate::BufferOp::staticUpload().

Here is the call graph for this function:

uploadStaticBuffer() [2/2]

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.

Definition at line 8615 of file qrhi.cpp.

References QRhiResourceUpdateBatchPrivate::activeBufferOpCount, QRhiResourceUpdateBatchPrivate::bufferOps, QRhiResourceUpdateBatchPrivate::BufferOp::changeToStaticUpload(), and QRhiResourceUpdateBatchPrivate::BufferOp::staticUpload().

Referenced by main(), QSSGDebugDrawSystem::prepareGeometry(), and QVideoWindowPrivate::render().

Here is the call graph for this function:

Here is the caller graph for this function:

uploadTexture() [1/2]

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.

Definition at line 8700 of file qrhi.cpp.

References uploadTexture().

Here is the call graph for this function:

uploadTexture() [2/2]

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.

Definition at line 8681 of file qrhi.cpp.

References QRhiResourceUpdateBatchPrivate::activeTextureOpCount, desc, QRhiResourceUpdateBatchPrivate::textureOps, and QRhiResourceUpdateBatchPrivate::TextureOp::upload().

Referenced by QSGCompressedTexture::commitTextureOperations(), QSGPlainTexture::commitTextureOperations(), QSSGRhiContext::dummyTexture(), QSGRhiTextureGlyphCache::endFillTexture(), QSGCompressedAtlasTexture::Atlas::enqueueTextureUpload(), QSGRhiAtlasTexture::Atlas::enqueueTextureUpload(), QSSGParticleRenderer::prepareParticlesForModel(), QSGRhiTextureGlyphCache::resizeTextureData(), QSSGParticleRenderer::rhiPrepareRenderable(), QSGRhiDistanceFieldGlyphCache::storeGlyphs(), QVideoWindowPrivate::updateSubtitle(), QVideoTextureHelper::updateTextureWithMap(), and uploadTexture().

Here is the call graph for this function:

Here is the caller graph for this function:

Friends And Related Symbol Documentation

QRhi

friend class QRhi

friend

Definition at line 1718 of file qrhi.h.

QRhiResourceUpdateBatchPrivate

friend class QRhiResourceUpdateBatchPrivate

friend

Definition at line 1717 of file qrhi.h.

---

The documentation for this class was generated from the following files:

• qtbase/src/gui/rhi/qrhi.h
• qtbase/src/gui/rhi/qrhi.cpp