QRhiCommandBuffer Class Reference

\inmodule QtGui More...

#include <qrhi.h>

Inheritance diagram for QRhiCommandBuffer:

Collaboration diagram for QRhiCommandBuffer:

Public Types
enum	IndexFormat { IndexUInt16 , IndexUInt32 }
	Specifies the index data type. More...
enum	BeginPassFlag { ExternalContent = 0x01 , DoNotTrackResourcesForCompute = 0x02 }
	Flag values for QRhi::beginPass() More...
using	DynamicOffset = QPair<int, quint32>
	Synonym for QPair<int, quint32>.
using	VertexInput = QPair<QRhiBuffer *, quint32>
	Synonym for QPair<QRhiBuffer *, quint32>.
Public Types inherited from QRhiResource
enum	Type {   Buffer , Texture , Sampler , RenderBuffer ,   RenderPassDescriptor , SwapChainRenderTarget , TextureRenderTarget , ShaderResourceBindings ,   GraphicsPipeline , SwapChain , ComputePipeline , CommandBuffer }
	Specifies type of the resource. More...

Public Member Functions
QRhiResource::Type	resourceType () const override
void	resourceUpdate (QRhiResourceUpdateBatch *resourceUpdates)
	Sometimes committing resource updates is necessary or just more convenient without starting a render pass.
void	beginPass (QRhiRenderTarget *rt, const QColor &colorClearValue, const QRhiDepthStencilClearValue &depthStencilClearValue, QRhiResourceUpdateBatch *resourceUpdates=nullptr, BeginPassFlags flags={})
	Records starting a new render pass targeting the render target rt.
void	endPass (QRhiResourceUpdateBatch *resourceUpdates=nullptr)
	Records ending the current render pass.
void	setGraphicsPipeline (QRhiGraphicsPipeline *ps)
	Records setting a new graphics pipeline ps.
void	setShaderResources (QRhiShaderResourceBindings *srb=nullptr, int dynamicOffsetCount=0, const DynamicOffset *dynamicOffsets=nullptr)
	Records binding a set of shader resources, such as, uniform buffers or textures, that are made visible to one or more shader stages.
void	setVertexInput (int startBinding, int bindingCount, const VertexInput *bindings, QRhiBuffer *indexBuf=nullptr, quint32 indexOffset=0, IndexFormat indexFormat=IndexUInt16)
	Records vertex input bindings.
void	setViewport (const QRhiViewport &viewport)
	Records setting the active viewport rectangle specified in viewport.
void	setScissor (const QRhiScissor &scissor)
	Records setting the active scissor rectangle specified in scissor.
void	setBlendConstants (const QColor &c)
	Records setting the active blend constants to c.
void	setStencilRef (quint32 refValue)
	Records setting the active stencil reference value to refValue.
void	draw (quint32 vertexCount, quint32 instanceCount=1, quint32 firstVertex=0, quint32 firstInstance=0)
	Records a non-indexed draw.
void	drawIndexed (quint32 indexCount, quint32 instanceCount=1, quint32 firstIndex=0, qint32 vertexOffset=0, quint32 firstInstance=0)
	Records an indexed draw.
void	debugMarkBegin (const QByteArray &name)
	Records a named debug group on the command buffer with the specified name.
void	debugMarkEnd ()
	Records the end of a debug group.
void	debugMarkMsg (const QByteArray &msg)
	Inserts a debug message msg into the command stream.
void	beginComputePass (QRhiResourceUpdateBatch *resourceUpdates=nullptr, BeginPassFlags flags={})
	Records starting a new compute pass.
void	endComputePass (QRhiResourceUpdateBatch *resourceUpdates=nullptr)
	Records ending the current compute pass.
void	setComputePipeline (QRhiComputePipeline *ps)
	Records setting a new compute pipeline ps.
void	dispatch (int x, int y, int z)
	Records dispatching compute work items, with x, y, and z specifying the number of local workgroups in the corresponding dimension.
const QRhiNativeHandles *	nativeHandles ()
void	beginExternal ()
	To be called when the application before the application is about to enqueue commands to the current pass' command buffer by calling graphics API functions directly.
void	endExternal ()
	To be called once the externally added commands are recorded to the command buffer or context.
double	lastCompletedGpuTime ()
Public Member Functions inherited from QRhiResource
virtual	~QRhiResource ()
	Destructor.
virtual void	destroy ()=0
	Releases (or requests deferred releasing of) the underlying native graphics resources.
void	deleteLater ()
	When called without a frame being recorded, this function is equivalent to deleting the object.
QByteArray	name () const
void	setName (const QByteArray &name)
	Sets a name for the object.
quint64	globalResourceId () const
QRhi *	rhi () const

Protected Member Functions
	QRhiCommandBuffer (QRhiImplementation *rhi)
Protected Member Functions inherited from QRhiResource
	QRhiResource (QRhiImplementation *rhi)

Additional Inherited Members
Protected Attributes inherited from QRhiResource
QRhiImplementation *	m_rhi = nullptr
quint64	m_id
QByteArray	m_objectName

Detailed Description

\inmodule QtGui

Since

6.6

Command buffer resource.

Not creatable by applications at the moment. The only ways to obtain a valid QRhiCommandBuffer are to get it from the targeted swapchain via QRhiSwapChain::currentFrameCommandBuffer(), or, in case of rendering completely offscreen, initializing one via QRhi::beginOffscreenFrame().

Note

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

Definition at line 1650 of file qrhi.h.

Member Typedef Documentation

DynamicOffset

QRhiCommandBuffer::DynamicOffset = QPair<int, quint32>

Synonym for QPair<int, quint32>.

The first entry is the binding, the second is the offset in the buffer.

Definition at line 1676 of file qrhi.h.

VertexInput

QRhiCommandBuffer::VertexInput = QPair<QRhiBuffer *, quint32>

Synonym for QPair<QRhiBuffer *, quint32>.

The second entry is an offset in the buffer specified by the first.

Definition at line 1680 of file qrhi.h.

Member Enumeration Documentation

BeginPassFlag

enum QRhiCommandBuffer::BeginPassFlag

Flag values for QRhi::beginPass()

\value ExternalContent Specifies that there will be a call to QRhiCommandBuffer::beginExternal() in this pass. Some backends, Vulkan in particular, will fail if this flag is not set and beginExternal() is still called.

\value DoNotTrackResourcesForCompute Specifies that there is no need to track resources used in this pass if the only purpose of such tracking is to generate barriers for compute. Implies that there are no compute passes in the frame. This is an optimization hint that may be taken into account by certain backends, OpenGL in particular, allowing them to skip certain operations. When this flag is set for a render pass in a frame, calling \l{QRhiCommandBuffer::beginComputePass()}{beginComputePass()} in that frame may lead to unexpected behavior, depending on the resource dependencies between the render and compute passes.

Enumerator
ExternalContent
DoNotTrackResourcesForCompute

Definition at line 1658 of file qrhi.h.

IndexFormat

enum QRhiCommandBuffer::IndexFormat

Specifies the index data type.

\value IndexUInt16 Unsigned 16-bit (quint16) \value IndexUInt32 Unsigned 32-bit (quint32)

Enumerator
IndexUInt16
IndexUInt32

Definition at line 1653 of file qrhi.h.

Constructor & Destructor Documentation

QRhiCommandBuffer()

QRhiCommandBuffer::QRhiCommandBuffer ( QRhiImplementation * rhi )

protected

Definition at line 7979 of file qrhi.cpp.

Member Function Documentation

beginComputePass()

void QRhiCommandBuffer::beginComputePass	(	QRhiResourceUpdateBatch *	resourceUpdates = nullptr,
		BeginPassFlags	flags = {} )

Records starting a new compute pass.

resourceUpdates, when not null, specifies a resource update batch that is to be committed and then released.

Note

Do not assume that any state or resource bindings persist between passes.

A compute pass can record setComputePipeline(), setShaderResources(), and dispatch() calls, not graphics ones. General functionality, such as, debug markers and beginExternal() is available both in render and compute passes.

Compute is only available when the \l{QRhi::Compute}{Compute} feature is reported as supported.

flags is not currently used.

Definition at line 9798 of file qrhi.cpp.

References QRhiImplementation::beginComputePass(), and QRhiResource::m_rhi.

Here is the call graph for this function:

beginExternal()

void QRhiCommandBuffer::beginExternal

(

)

To be called when the application before the application is about to enqueue commands to the current pass' command buffer by calling graphics API functions directly.

Note

This is only available when the intent was declared upfront in beginPass() or beginComputePass(). Therefore this function must only be called when the pass recording was started with specifying QRhiCommandBuffer::ExternalContent.

With Vulkan, Metal, or Direct3D 12 one can query the native command buffer or encoder objects via nativeHandles() and enqueue commands to them. With OpenGL or Direct3D 11 the (device) context can be retrieved from QRhi::nativeHandles(). However, this must never be done without ensuring the QRhiCommandBuffer's state stays up-to-date. Hence the requirement for wrapping any externally added command recording between beginExternal() and endExternal(). Conceptually this is the same as QPainter's \l{QPainter::beginNativePainting()}{beginNativePainting()} and \l{QPainter::endNativePainting()}{endNativePainting()} functions.

For OpenGL in particular, this function has an additional task: it makes sure the context is made current on the current thread.

Note

Once beginExternal() is called, no other render pass specific functions (set* or draw*) must be called on the QRhiCommandBuffer until endExternal().

Warning

Some backends may return a native command buffer object from QRhiCommandBuffer::nativeHandles() that is different from the primary one when inside a beginExternal() - endExternal() block. Therefore it is important to (re)query the native command buffer object after calling beginExternal(). In practical terms this means that with Vulkan for example the externally recorded Vulkan commands are placed onto a secondary command buffer (with VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT). nativeHandles() returns this secondary command buffer when called between begin/endExternal.

See also

endExternal(), nativeHandles()

Definition at line 9909 of file qrhi.cpp.

References QRhiImplementation::beginExternal(), and QRhiResource::m_rhi.

Here is the call graph for this function:

beginPass()

void QRhiCommandBuffer::beginPass	(	QRhiRenderTarget *	rt,
		const QColor &	colorClearValue,
		const QRhiDepthStencilClearValue &	depthStencilClearValue,
		QRhiResourceUpdateBatch *	resourceUpdates = nullptr,
		BeginPassFlags	flags = {} )

Records starting a new render pass targeting the render target rt.

resourceUpdates, when not null, specifies a resource update batch that is to be committed and then released.

The color and depth/stencil buffers of the render target are normally cleared. The clear values are specified in colorClearValue and depthStencilClearValue. The exception is when the render target was created with QRhiTextureRenderTarget::PreserveColorContents and/or QRhiTextureRenderTarget::PreserveDepthStencilContents. The clear values are ignored then.

Note

Enabling preserved color or depth contents leads to decreased performance depending on the underlying hardware. Mobile GPUs with tiled architecture benefit from not having to reload the previous contents into the tile buffer. Similarly, a QRhiTextureRenderTarget with a QRhiTexture as the depth buffer is less efficient than a QRhiRenderBuffer since using a depth texture triggers requiring writing the data out to it, while with renderbuffers this is not needed (as the API does not allow sampling or reading from a renderbuffer).

Do not assume that any state or resource bindings persist between passes.

The QRhiCommandBuffer's set and draw functions can only be called inside a pass. Also, with the exception of setGraphicsPipeline(), they expect to have a pipeline set already on the command buffer. Unspecified issues may arise otherwise, depending on the backend.

If rt is a QRhiTextureRenderTarget, beginPass() performs a check to see if the texture and renderbuffer objects referenced from the render target are up-to-date. This is similar to what setShaderResources() does for QRhiShaderResourceBindings. If any of the attachments had been rebuilt since QRhiTextureRenderTarget::create(), an implicit call to create() is made on rt. Therefore, if rt has a QRhiTexture color attachment texture, and one needs to make the texture a different size, the following is then valid:

QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ { texture } });
rt->create();
// ...
texture->setPixelSize(new_size);
texture->create();
cb->beginPass(rt, colorClear, dsClear); // this is ok, no explicit rt->create() is required before

flags allow controlling certain advanced functionality. One commonly used flag is ExternalContents. This should be specified whenever beginExternal() will be called within the pass started by this function.

See also

endPass(), BeginPassFlags

Definition at line 9443 of file qrhi.cpp.

References QRhiImplementation::beginPass(), and QRhiResource::m_rhi.

Referenced by QSGBatchRenderer::Renderer::beginRenderPass().

Here is the call graph for this function:

Here is the caller graph for this function:

debugMarkBegin()

void QRhiCommandBuffer::debugMarkBegin

(

const QByteArray &

name

)

Records a named debug group on the command buffer with the specified name.

This is shown in graphics debugging tools such as \l{https://renderdoc.org/}{RenderDoc} and \l{https://developer.apple.com/xcode/}{XCode}. The end of the grouping is indicated by debugMarkEnd().

Note

Ignored when QRhi::DebugMarkers are not supported or QRhi::EnableDebugMarkers is not set.

Can be called anywhere within the frame, both inside and outside of passes.

Definition at line 9746 of file qrhi.cpp.

References QRhiImplementation::debugMarkBegin(), and QRhiResource::m_rhi.

Here is the call graph for this function:

debugMarkEnd()

void QRhiCommandBuffer::debugMarkEnd

(

)

Records the end of a debug group.

Note

Ignored when QRhi::DebugMarkers are not supported or QRhi::EnableDebugMarkers is not set.

Can be called anywhere within the frame, both inside and outside of passes.

Definition at line 9759 of file qrhi.cpp.

References QRhiImplementation::debugMarkEnd(), and QRhiResource::m_rhi.

Here is the call graph for this function:

debugMarkMsg()

void QRhiCommandBuffer::debugMarkMsg

(

const QByteArray &

msg

)

Inserts a debug message msg into the command stream.

Note

Ignored when QRhi::DebugMarkers are not supported or QRhi::EnableDebugMarkers is not set.

With some backends debugMarkMsg() is only supported inside a pass and is ignored when called outside a pass. With others it is recorded anywhere within the frame.

Definition at line 9774 of file qrhi.cpp.

References QRhiImplementation::debugMarkMsg(), and QRhiResource::m_rhi.

Here is the call graph for this function:

dispatch()

void QRhiCommandBuffer::dispatch	(	int	x,
		int	y,
		int	z )

Records dispatching compute work items, with x, y, and z specifying the number of local workgroups in the corresponding dimension.

Note

This function can only be called inside a compute pass, meaning between a beginComputePass() and endComputePass() call.

x, y, and z must fit the limits from the underlying graphics API implementation at run time. The maximum values are typically 65535.

Watch out for possible limits on the local workgroup size as well. This is specified in the shader, for example: {layout(local_size_x = 16, local_size_y = 16) in;}. For example, with OpenGL the minimum value mandated by the specification for the number of invocations in a single local work group (the product of local_size_x, local_size_y, and local_size_z) is 1024, while with OpenGL ES (3.1) the value may be as low as 128. This means that the example given above may be rejected by some OpenGL ES implementations as the number of invocations is 256.

Definition at line 9851 of file qrhi.cpp.

References QRhiImplementation::dispatch(), and QRhiResource::m_rhi.

Here is the call graph for this function:

draw()

void QRhiCommandBuffer::draw	(	quint32	vertexCount,
		quint32	instanceCount = 1,
		quint32	firstVertex = 0,
		quint32	firstInstance = 0 )

Records a non-indexed draw.

The number of vertices is specified in vertexCount. For instanced drawing set instanceCount to a value other than 1. firstVertex is the index of the first vertex to draw. When drawing multiple instances, the first instance ID is specified by firstInstance.

Note

firstInstance may not be supported, and is ignored when the QRhi::BaseInstance feature is reported as not supported. The first ID is always 0 in that case.

This function can only be called inside a render pass, meaning between a beginPass() and endPass() call.

Definition at line 9688 of file qrhi.cpp.

References QRhiImplementation::draw(), instanceCount, and QRhiResource::m_rhi.

Referenced by QRhiMetal::draw().

Here is the call graph for this function:

Here is the caller graph for this function:

drawIndexed()

void QRhiCommandBuffer::drawIndexed	(	quint32	indexCount,
		quint32	instanceCount = 1,
		quint32	firstIndex = 0,
		qint32	vertexOffset = 0,
		quint32	firstInstance = 0 )

Records an indexed draw.

The number of vertices is specified in indexCount. firstIndex is the base index. The effective offset in the index buffer is given by {indexOffset + firstIndex * n} where n is 2 or 4 depending on the index element type. indexOffset is specified in setVertexInput().

Note

The effective offset in the index buffer must be 4 byte aligned with some backends (for example, Metal). With these backends the \l{QRhi::NonFourAlignedEffectiveIndexBufferOffset}{NonFourAlignedEffectiveIndexBufferOffset} feature will be reported as not-supported.

For instanced drawing set instanceCount to a value other than 1. When drawing multiple instances, the first instance ID is specified by firstInstance.

Note

firstInstance may not be supported, and is ignored when the QRhi::BaseInstance feature is reported as not supported. The first ID is always 0 in that case.

vertexOffset (also called {base vertex}) is a signed value that is added to the element index before indexing into the vertex buffer. Support for this is not always available, and the value is ignored when the feature QRhi::BaseVertex is reported as unsupported.

Note

This function can only be called inside a render pass, meaning between a beginPass() and endPass() call.

Definition at line 9725 of file qrhi.cpp.

References QRhiImplementation::drawIndexed(), instanceCount, and QRhiResource::m_rhi.

Here is the call graph for this function:

endComputePass()

void QRhiCommandBuffer::endComputePass

(

QRhiResourceUpdateBatch *

resourceUpdates = nullptr

)

Records ending the current compute pass.

resourceUpdates, when not null, specifies a resource update batch that is to be committed and then released.

Definition at line 9809 of file qrhi.cpp.

References QRhiImplementation::endComputePass(), and QRhiResource::m_rhi.

Here is the call graph for this function:

endExternal()

void QRhiCommandBuffer::endExternal

(

)

To be called once the externally added commands are recorded to the command buffer or context.

Note

All QRhiCommandBuffer state must be assumed as invalid after calling this function. Pipelines, vertex and index buffers, and other state must be set again if more draw calls are recorded after the external commands.

See also

beginExternal(), nativeHandles()

Definition at line 9924 of file qrhi.cpp.

References QRhiImplementation::endExternal(), and QRhiResource::m_rhi.

Here is the call graph for this function:

endPass()

void QRhiCommandBuffer::endPass

(

QRhiResourceUpdateBatch *

resourceUpdates = nullptr

)

Records ending the current render pass.

resourceUpdates, when not null, specifies a resource update batch that is to be committed and then released.

See also

beginPass()

Definition at line 9460 of file qrhi.cpp.

References QRhiImplementation::endPass(), and QRhiResource::m_rhi.

Referenced by QSGBatchRenderer::Renderer::endRenderPass().

Here is the call graph for this function:

Here is the caller graph for this function:

lastCompletedGpuTime()

double QRhiCommandBuffer::lastCompletedGpuTime

(

)

Returns

the last available timestamp, in seconds, when \l QRhi::EnableTimestamps was enabled when creating the QRhi. The value indicates the elapsed time on the GPU during the last completed frame.

Note

Do not expect results other than 0 when the QRhi::Timestamps feature is not reported as supported, or when QRhi::EnableTimestamps was not passed to QRhi::create(). There are exceptions to this, because with some graphics APIs (Metal) timings are available without having to perform extra operations (timestamp queries), but portable applications should always consciously opt-in to timestamp collection when they know it is needed, and call this function accordingly.

Care must be exercised with the interpretation of the value, as its precision and granularity is often not controlled by Qt, and depends on the underlying graphics API and its implementation. In particular, comparing the values between different graphics APIs and hardware is discouraged and may be meaningless.

When the frame was recorded with \l{QRhi::beginFrame()}{beginFrame()} and \l{QRhi::endFrame()}{endFrame()}, i.e., with a swapchain, the timing values will likely become available asynchronously. The returned value may therefore be 0 (e.g., for the first 1-2 frames) or the last known value referring to some previous frame. The value my also become 0 again under certain conditions, such as when resizing the window. It can be expected that the most up-to-date available value is retrieved in beginFrame() and becomes queriable via this function once beginFrame() returns.

Note

Do not assume that the value refers to the previous ({currently_recorded - 1}) frame. It may refer to {currently_recorded - 2} or {currently_recorded - 3} as well. The exact behavior may depend on the graphics API and its implementation.

On the other hand, with offscreen frames the returned value is up-to-date once \l{QRhi::endOffscreenFrame()}{endOffscreenFrame()} returns, because offscreen frames reduce GPU pipelining and wait the the commands to be complete.

Note

This means that, unlike with swapchain frames, with offscreen frames the returned value is guaranteed to refer to the frame that has just been submitted and completed. (assuming this function is called after endOffscreenFrame() but before the next beginOffscreenFrame())

Watch out for the consequences of GPU frequency scaling and GPU clock changes, depending on the platform. For example, on Windows the returned timing may vary in a quite wide range between frames with modern graphics cards, even when submitting frames with a similar, or the same workload. This is out of scope for Qt to control and solve, generally speaking. However, the D3D12 backend automatically calls \l{https://learn.microsoft.com/en-us/windows/win32/api/d3d12/nf-d3d12-id3d12device-setstablepowerstate}{ID3D12Device::SetStablePowerState()} whenever the environment variable QT_D3D_STABLE_POWER_STATE is set to a non-zero value. This can greatly stabilize the result. It can also have a non-insignificant effect on the CPU-side timings measured via QElapsedTimer for example, especially when offscreen frames are involved.

Note

Do not and never ship applications to production with QT_D3D_STABLE_POWER_STATE set. See the Windows API documentation for details.

See also

QRhi::Timestamps, QRhi::EnableTimestamps

Definition at line 9990 of file qrhi.cpp.

References QRhiImplementation::lastCompletedGpuTime(), and QRhiResource::m_rhi.

Here is the call graph for this function:

nativeHandles()

const QRhiNativeHandles * QRhiCommandBuffer::nativeHandles

(

)

Returns

a pointer to a backend-specific QRhiNativeHandles subclass, such as QRhiVulkanCommandBufferNativeHandles. The returned value is \nullptr when exposing the underlying native resources is not supported by, or not applicable to, the backend.

See also

QRhiVulkanCommandBufferNativeHandles, QRhiMetalCommandBufferNativeHandles, beginExternal(), endExternal()

Definition at line 9865 of file qrhi.cpp.

References QRhiResource::m_rhi, and QRhiImplementation::nativeHandles().

Here is the call graph for this function:

resourceType()

QRhiResource::Type QRhiCommandBuffer::resourceType ( ) const

overridevirtual

Returns

the resource type.

Implements QRhiResource.

Definition at line 7987 of file qrhi.cpp.

References QRhiResource::CommandBuffer.

resourceUpdate()

void QRhiCommandBuffer::resourceUpdate

(

QRhiResourceUpdateBatch *

resourceUpdates

)

Sometimes committing resource updates is necessary or just more convenient without starting a render pass.

Calling this function with resourceUpdates is an alternative to passing resourceUpdates to a beginPass() call (or endPass(), which would be typical in case of readbacks).

Note

Cannot be called inside a pass.

Definition at line 9384 of file qrhi.cpp.

References QRhiResource::m_rhi, and QRhiImplementation::resourceUpdate().

Referenced by addOpaqueDepthPrePassBindings(), QSSGRhiCubeRenderer::prepareCube(), QSSGLayerRenderData::prepareInstancing(), QSSGParticleRenderer::prepareParticlesForModel(), QSSGRhiQuadRenderer::prepareQuad(), QSGBatchRenderer::Renderer::prepareRenderPass(), QSGRhiAtlasTexture::Texture::removedFromAtlas(), QSSGCustomMaterialSystem::rhiPrepareRenderable(), QSSGParticleRenderer::rhiPrepareRenderable(), and rhiPrepareResourcesForShadowMap().

Here is the call graph for this function:

Here is the caller graph for this function:

setBlendConstants()

void QRhiCommandBuffer::setBlendConstants

(

const QColor &

c

)

Records setting the active blend constants to c.

This can only be called when the bound pipeline has QRhiGraphicsPipeline::UsesBlendConstants set.

Note

This function can only be called inside a render pass, meaning between a beginPass() and endPass() call.

Definition at line 9654 of file qrhi.cpp.

References QRhiResource::m_rhi, and QRhiImplementation::setBlendConstants().

Here is the call graph for this function:

setComputePipeline()

void QRhiCommandBuffer::setComputePipeline

(

QRhiComputePipeline *

ps

)

Records setting a new compute pipeline ps.

Note

This function must be called before recording setShaderResources() or dispatch() commands on the command buffer.

QRhi will optimize out unnecessary invocations within a pass, so therefore overoptimizing to avoid calls to this function is not necessary on the applications' side.

This function can only be called inside a compute pass, meaning between a beginComputePass() and endComputePass() call.

Definition at line 9827 of file qrhi.cpp.

References QRhiResource::m_rhi, and QRhiImplementation::setComputePipeline().

Here is the call graph for this function:

setGraphicsPipeline()

void QRhiCommandBuffer::setGraphicsPipeline

(

QRhiGraphicsPipeline *

ps

)

Records setting a new graphics pipeline ps.

Note

This function must be called before recording other set or draw commands on the command buffer.

QRhi will optimize out unnecessary invocations within a pass, so therefore overoptimizing to avoid calls to this function is not necessary on the applications' side.

This function can only be called inside a render pass, meaning between a beginPass() and endPass() call.

The new graphics pipeline ps must be a valid pointer.

Definition at line 9480 of file qrhi.cpp.

References QRhiResource::m_rhi, Q_ASSERT, and QRhiImplementation::setGraphicsPipeline().

Here is the call graph for this function:

setScissor()

void QRhiCommandBuffer::setScissor

(

const QRhiScissor &

scissor

)

Records setting the active scissor rectangle specified in scissor.

This can only be called when the bound pipeline has \l{QRhiGraphicsPipeline::UsesScissor}{UsesScissor} set. When the flag is set on the active pipeline, this function must be called because scissor testing will get enabled and so a scissor rectangle must be provided.

Note

QRhi assumes OpenGL-style viewport coordinates, meaning x and y are bottom-left.

This function can only be called inside a render pass, meaning between a beginPass() and endPass() call.

Definition at line 9640 of file qrhi.cpp.

References QRhiResource::m_rhi, and QRhiImplementation::setScissor().

Here is the call graph for this function:

setShaderResources()

void QRhiCommandBuffer::setShaderResources	(	QRhiShaderResourceBindings *	srb = nullptr,
		int	dynamicOffsetCount = 0,
		const DynamicOffset *	dynamicOffsets = nullptr )

Records binding a set of shader resources, such as, uniform buffers or textures, that are made visible to one or more shader stages.

srb can be null in which case the current graphics or compute pipeline's associated QRhiShaderResourceBindings is used. When srb is non-null, it must be \l{QRhiShaderResourceBindings::isLayoutCompatible()}{layout-compatible}, meaning the layout (number of bindings, the type and binding number of each binding) must fully match the QRhiShaderResourceBindings that was associated with the pipeline at the time of calling the pipeline's create().

There are cases when a seemingly unnecessary setShaderResources() call is mandatory: when rebuilding a resource referenced from srb, for example changing the size of a QRhiBuffer followed by a QRhiBuffer::create(), this is the place where associated native objects (such as descriptor sets in case of Vulkan) are updated to refer to the current native resources that back the QRhiBuffer, QRhiTexture, QRhiSampler objects referenced from srb. In this case setShaderResources() must be called even if srb is the same as in the last call.

When srb is not null, the QRhiShaderResourceBindings object the pipeline was built with in create() is guaranteed to be not accessed in any form. In fact, it does not need to be valid even at this point: destroying the pipeline's associated srb after create() and instead explicitly specifying another, \l{QRhiShaderResourceBindings::isLayoutCompatible()}{layout compatible} one in every setShaderResources() call is valid.

dynamicOffsets allows specifying buffer offsets for uniform buffers that were associated with srb via QRhiShaderResourceBinding::uniformBufferWithDynamicOffset(). This is different from providing the offset in the srb itself: dynamic offsets do not require building a new QRhiShaderResourceBindings for every different offset, can avoid writing the underlying descriptors (with backends where applicable), and so they may be more efficient. Each element of dynamicOffsets is a binding - offset pair. dynamicOffsetCount specifies the number of elements in dynamicOffsets.

Note

All offsets in dynamicOffsets must be byte aligned to the value returned from QRhi::ubufAlignment().

Some backends may limit the number of supported dynamic offsets. Avoid using a dynamicOffsetCount larger than 8.

QRhi will optimize out unnecessary invocations within a pass (taking the conditions described above into account), so therefore overoptimizing to avoid calls to this function is not necessary on the applications' side.

This function can only be called inside a render or compute pass, meaning between a beginPass() and endPass(), or beginComputePass() and endComputePass().

Definition at line 9538 of file qrhi.cpp.

References QRhiResource::m_rhi, and QRhiImplementation::setShaderResources().

Here is the call graph for this function:

setStencilRef()

void QRhiCommandBuffer::setStencilRef

(

quint32

refValue

)

Records setting the active stencil reference value to refValue.

This can only be called when the bound pipeline has QRhiGraphicsPipeline::UsesStencilRef set.

Note

This function can only be called inside a render pass, meaning between a beginPass() and endPass() call.

Definition at line 9668 of file qrhi.cpp.

References QRhiResource::m_rhi, and QRhiImplementation::setStencilRef().

Here is the call graph for this function:

setVertexInput()

void QRhiCommandBuffer::setVertexInput	(	int	startBinding,
		int	bindingCount,
		const VertexInput *	bindings,
		QRhiBuffer *	indexBuf = nullptr,
		quint32	indexOffset = 0,
		IndexFormat	indexFormat = IndexUInt16 )

Records vertex input bindings.

The index buffer used by subsequent drawIndexed() commands is specified by indexBuf, indexOffset, and indexFormat. indexBuf can be set to null when indexed drawing is not needed.

Vertex buffer bindings are batched. startBinding specifies the first binding number. The recorded command then binds each buffer from bindings to the binding point {startBinding + i} where i is the index in bindings. Each element in bindings specifies a QRhiBuffer and an offset.

Note

Some backends may limit the number of vertex buffer bindings. Avoid using a bindingCount larger than 8.

Superfluous vertex input and index changes in the same pass are ignored automatically with most backends and therefore applications do not need to overoptimize to avoid calls to this function.

Note

This function can only be called inside a render pass, meaning between a beginPass() and endPass() call.

As a simple example, take a vertex shader with two inputs:

\badcode layout(location = 0) in vec4 position; layout(location = 1) in vec3 color;

and assume we have the data available in interleaved format, using only 2 floats for position (so 5 floats per vertex: x, y, r, g, b). A QRhiGraphicsPipeline for this shader can then be created using the input layout:

QRhiVertexInputLayout inputLayout;
inputLayout.setBindings({
    { 5 * sizeof(float) }
});
inputLayout.setAttributes({
    { 0, 0, QRhiVertexInputAttribute::Float2, 0 },
    { 0, 1, QRhiVertexInputAttribute::Float3, 2 * sizeof(float) }
});

Here there is one buffer binding (binding number 0), with two inputs referencing it. When recording the pass, once the pipeline is set, the vertex bindings can be specified simply like the following, assuming vbuf is the QRhiBuffer with all the interleaved position+color data:

const QRhiCommandBuffer::VertexInput vbufBinding(vbuf, 0);
cb->setVertexInput(0, 1, &vbufBinding);

Definition at line 9600 of file qrhi.cpp.

References QRhiResource::m_rhi, and QRhiImplementation::setVertexInput().

Here is the call graph for this function:

setViewport()

void QRhiCommandBuffer::setViewport

(

const QRhiViewport &

viewport

)

Records setting the active viewport rectangle specified in viewport.

With backends where the underlying graphics API has scissoring always enabled, this function also sets the scissor to match the viewport whenever the active QRhiGraphicsPipeline does not have \l{QRhiGraphicsPipeline::UsesScissor}{UsesScissor} set.

Note

QRhi assumes OpenGL-style viewport coordinates, meaning x and y are bottom-left.

This function can only be called inside a render pass, meaning between a beginPass() and endPass() call.

Definition at line 9621 of file qrhi.cpp.

References QRhiResource::m_rhi, QRhiImplementation::setViewport(), and viewport().

Here is the call graph for this function:

---

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

• qtbase/src/gui/rhi/qrhi.h (e36c1a8d840ee47be0d4fbf8069fda536042a53c)
• qtbase/src/gui/rhi/qrhi.cpp (e36c1a8d840ee47be0d4fbf8069fda536042a53c)