QRhiGraphicsPipeline Class

Graphics pipeline state resource. More...

Header: #include <QRhiGraphicsPipeline>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui
Since: Qt 6.6
Inherits: QRhiResource

Public Types

struct StencilOpState
struct TargetBlend
enum BlendFactor { Zero, One, SrcColor, OneMinusSrcColor, DstColor, …, OneMinusSrc1Alpha }
enum BlendOp { Add, Subtract, ReverseSubtract, Min, Max }
flags ColorMask
enum ColorMaskComponent { R, G, B, A }
enum CompareOp { Never, Less, Equal, LessOrEqual, Greater, …, Always }
enum CullMode { None, Front, Back }
enum Flag { UsesBlendConstants, UsesStencilRef, UsesScissor, CompileShadersWithDebugInfo }
flags Flags
enum FrontFace { CCW, CW }
enum PolygonMode { Fill, Line }
enum StencilOp { StencilZero, Keep, Replace, IncrementAndClamp, DecrementAndClamp, …, DecrementAndWrap }
enum Topology { Triangles, TriangleStrip, TriangleFan, Lines, LineStrip, …, Patches }

Public Functions

const QRhiShaderStage *cbeginShaderStages() const
const QRhiGraphicsPipeline::TargetBlend *cbeginTargetBlends() const
const QRhiShaderStage *cendShaderStages() const
const QRhiGraphicsPipeline::TargetBlend *cendTargetBlends() const
virtual bool create() = 0
QRhiGraphicsPipeline::CullMode cullMode() const
int depthBias() const
QRhiGraphicsPipeline::CompareOp depthOp() const
QRhiGraphicsPipeline::Flags flags() const
QRhiGraphicsPipeline::FrontFace frontFace() const
bool hasDepthTest() const
bool hasDepthWrite() const
bool hasStencilTest() const
float lineWidth() const
int patchControlPointCount() const
QRhiGraphicsPipeline::PolygonMode polygonMode() const
QRhiRenderPassDescriptor *renderPassDescriptor() const
int sampleCount() const
void setCullMode(QRhiGraphicsPipeline::CullMode mode)
void setDepthBias(int bias)
void setDepthOp(QRhiGraphicsPipeline::CompareOp op)
void setDepthTest(bool enable)
void setDepthWrite(bool enable)
void setFlags(QRhiGraphicsPipeline::Flags f)
void setFrontFace(QRhiGraphicsPipeline::FrontFace f)
void setLineWidth(float width)
void setPatchControlPointCount(int count)
void setPolygonMode(QRhiGraphicsPipeline::PolygonMode mode)
void setRenderPassDescriptor(QRhiRenderPassDescriptor *desc)
void setSampleCount(int s)
void setShaderResourceBindings(QRhiShaderResourceBindings *srb)
void setShaderStages(std::initializer_list<QRhiShaderStage> list)
void setShaderStages(InputIterator first, InputIterator last)
void setSlopeScaledDepthBias(float bias)
void setStencilBack(const QRhiGraphicsPipeline::StencilOpState &state)
void setStencilFront(const QRhiGraphicsPipeline::StencilOpState &state)
void setStencilReadMask(quint32 mask)
void setStencilTest(bool enable)
void setStencilWriteMask(quint32 mask)
void setTargetBlends(std::initializer_list<TargetBlend> list)
void setTargetBlends(InputIterator first, InputIterator last)
void setTopology(QRhiGraphicsPipeline::Topology t)
void setVertexInputLayout(const QRhiVertexInputLayout &layout)
QRhiShaderResourceBindings *shaderResourceBindings() const
const QRhiShaderStage *shaderStageAt(qsizetype index) const
qsizetype shaderStageCount() const
float slopeScaledDepthBias() const
QRhiGraphicsPipeline::StencilOpState stencilBack() const
QRhiGraphicsPipeline::StencilOpState stencilFront() const
quint32 stencilReadMask() const
quint32 stencilWriteMask() const
const QRhiGraphicsPipeline::TargetBlend *targetBlendAt(qsizetype index) const
qsizetype targetBlendCount() const
QRhiGraphicsPipeline::Topology topology() const
QRhiVertexInputLayout vertexInputLayout() const

Reimplemented Public Functions

virtual QRhiResource::Type resourceType() const override

Detailed Description

Represents a graphics pipeline. What exactly this map to in the underlying native graphics API, varies. Where there is a concept of pipeline objects, for example with Vulkan, the QRhi backend will create such an object upon calling create(). Elsewhere, for example with OpenGL, the QRhiGraphicsPipeline may merely collect the various state, and create()'s main task is to set up the corresponding shader program, but deferring looking at any of the requested state to a later point.

As with all QRhiResource subclasses, the two-phased initialization pattern applies: setting any values via the setters, for example setDepthTest(), is only effective after calling create(). Avoid changing any values once the QRhiGraphicsPipeline has been initialized via create(). To change some state, set the new value and call create() again. However, that will effectively release all underlying native resources and create new ones. As a result, it may be a heavy, expensive operation. Rather, prefer creating multiple pipelines with the different states, and switch between them when recording the render pass.

Note: Setting the shader stages is mandatory. There must be at least one stage, and there must be a vertex stage.

Note: Setting the shader resource bindings is mandatory. The referenced QRhiShaderResourceBindings must already have create() called on it by the time create() is called. Associating with a QRhiShaderResourceBindings that has no bindings is also valid, as long as no shader in any stage expects any resources. Using a QRhiShaderResourceBindings object that does not specify any actual resources (i.e., the buffers, textures, etc. for the binding points are set to nullptr) is valid as well, as long as a layout-compatible QRhiShaderResourceBindings, that specifies resources for all the bindings, is going to be set via setShaderResources() when recording the render pass.

Note: Setting the render pass descriptor is mandatory. To obtain a QRhiRenderPassDescriptor that can be passed to setRenderPassDescriptor(), use either QRhiTextureRenderTarget::newCompatibleRenderPassDescriptor() or QRhiSwapChain::newCompatibleRenderPassDescriptor().

Note: Setting the vertex input layout is mandatory.

Note: sampleCount() defaults to 1 and must match the sample count of the render target's color and depth stencil attachments.

Note: The depth test, depth write, and stencil test are disabled by default. The face culling mode defaults to no culling.

Note: stencilReadMask() and stencilWriteMask() apply to both faces. They both default to 0xFF.

Example usage

All settings of a graphics pipeline have defaults which might be suitable to many applications. Therefore a minimal example of creating a graphics pipeline could be the following. This assumes that the vertex shader takes a single vec3 position input at the input location 0. With the QRhiShaderResourceBindings and QRhiRenderPassDescriptor objects, plus the QShader collections for the vertex and fragment stages, a pipeline could be created like this:

QRhiShaderResourceBindings *srb;
QRhiRenderPassDescriptor *rpDesc;
QShader vs, fs;
// ...

QRhiVertexInputLayout inputLayout;
inputLayout.setBindings({ { 3 * sizeof(float) } });
inputLayout.setAttributes({ { 0, 0, QRhiVertexInputAttribute::Float3, 0 } });

QRhiGraphicsPipeline *ps = rhi->newGraphicsPipeline();
ps->setShaderStages({ { QRhiShaderStage::Vertex, vs }, { QRhiShaderStage::Fragment, fs } });
if (!ps->create()) { error(); }

The above code creates a pipeline object that uses the defaults for many settings and states. For example, it will use a Triangles topology, no backface culling, blending is disabled but color write is enabled for all four channels, depth test/write are disabled, stencil operations are disabled.

Note: This is a RHI API with limited compatibility guarantees, see QRhi for details.

See also QRhiCommandBuffer and QRhi.

Member Type Documentation

enum QRhiGraphicsPipeline::BlendFactor

Specifies the blend factor


enum QRhiGraphicsPipeline::BlendOp

Specifies the blend operation


enum QRhiGraphicsPipeline::ColorMaskComponent
flags QRhiGraphicsPipeline::ColorMask

Flag values for specifying the color write mask

QRhiGraphicsPipeline::R1 << 0
QRhiGraphicsPipeline::G1 << 1
QRhiGraphicsPipeline::B1 << 2
QRhiGraphicsPipeline::A1 << 3

The ColorMask type is a typedef for QFlags<ColorMaskComponent>. It stores an OR combination of ColorMaskComponent values.

enum QRhiGraphicsPipeline::CompareOp

Specifies the depth or stencil comparison function

QRhiGraphicsPipeline::Less1(default for depth)
QRhiGraphicsPipeline::Always7(default for stencil)

enum QRhiGraphicsPipeline::CullMode

Specifies the culling mode

QRhiGraphicsPipeline::None0No culling (default)
QRhiGraphicsPipeline::Front1Cull front faces
QRhiGraphicsPipeline::Back2Cull back faces

enum QRhiGraphicsPipeline::Flag
flags QRhiGraphicsPipeline::Flags

Flag values for describing the dynamic state of the pipeline, and other options. The viewport is always dynamic.

QRhiGraphicsPipeline::UsesBlendConstants1 << 0Indicates that a blend color constant will be set via QRhiCommandBuffer::setBlendConstants()
QRhiGraphicsPipeline::UsesStencilRef1 << 1Indicates that a stencil reference value will be set via QRhiCommandBuffer::setStencilRef()
QRhiGraphicsPipeline::UsesScissor1 << 2Indicates that a scissor rectangle will be set via QRhiCommandBuffer::setScissor()
QRhiGraphicsPipeline::CompileShadersWithDebugInfo1 << 3Requests compiling shaders with debug information enabled. This is relevant only when runtime shader compilation from source code is involved, and only when the underlying infrastructure supports this. With concrete examples, this is not relevant with Vulkan and SPIR-V, because the GLSL-to-SPIR-V compilation does not happen at run time. On the other hand, consider Direct3D and HLSL, where there are multiple options: when the QShader packages ship with pre-compiled bytecode (DXBC), debug information is to be requested through the tool that generates the .qsb file, similarly to the case of Vulkan and SPIR-V. However, when having HLSL source code in the pre- or runtime-generated QShader packages, the first phase of compilation (HLSL source to intermediate format) happens at run time too, with this flag taken into account. Debug information is relevant in particular with tools like RenderDoc since it allows seeing the original source code when investigating the pipeline and when performing vertex or fragment shader debugging.

The Flags type is a typedef for QFlags<Flag>. It stores an OR combination of Flag values.

enum QRhiGraphicsPipeline::FrontFace

Specifies the front face winding order

QRhiGraphicsPipeline::CCW0Counter clockwise (default)

enum QRhiGraphicsPipeline::PolygonMode

Specifies the polygon rasterization mode

Polygon Mode (Triangle Fill Mode in Metal, Fill Mode in D3D) specifies the fill mode used when rasterizing polygons. Polygons may be drawn as solids (Fill), or as a wire mesh (Line).

Support for non-fill polygon modes is optional and is indicated by the QRhi::NonFillPolygonMode feature. With OpenGL ES and some Vulkan implementations the feature will likely be reported as unsupported, which then means values other than Fill cannot be used.

QRhiGraphicsPipeline::Fill0The interior of the polygon is filled (default)
QRhiGraphicsPipeline::Line1Boundary edges of the polygon are drawn as line segments.

enum QRhiGraphicsPipeline::StencilOp

Specifies the stencil operation


enum QRhiGraphicsPipeline::Topology

Specifies the primitive topology

QRhiGraphicsPipeline::TriangleFan2(only available if QRhi::TriangleFanTopology is supported)
QRhiGraphicsPipeline::Patches6(only available if QRhi::Tessellation is supported, and requires the tessellation stages to be present in the pipeline)

Member Function Documentation

const QRhiShaderStage *QRhiGraphicsPipeline::cbeginShaderStages() const

Returns a const iterator pointing to the first item in the shader stage list.

const QRhiGraphicsPipeline::TargetBlend *QRhiGraphicsPipeline::cbeginTargetBlends() const

Returns a const iterator pointing to the first item in the render target blend setting list.

const QRhiShaderStage *QRhiGraphicsPipeline::cendShaderStages() const

Returns a const iterator pointing just after the last item in the shader stage list.

const QRhiGraphicsPipeline::TargetBlend *QRhiGraphicsPipeline::cendTargetBlends() const

Returns a const iterator pointing just after the last item in the render target blend setting list.

[pure virtual] bool QRhiGraphicsPipeline::create()

Creates the corresponding native graphics resources. If there are already resources present due to an earlier create() with no corresponding destroy(), then destroy() is called implicitly first.

Returns true when successful, false when a graphics operation failed. Regardless of the return value, calling destroy() is always safe.

Note: This may be, depending on the underlying graphics API, an expensive operation, especially when shaders get compiled/optimized from source or from an intermediate bytecode format to the GPU's own instruction set. Where applicable, the QRhi backend automatically sets up the relevant non-persistent facilities to accelerate this, for example the Vulkan backend automatically creates a VkPipelineCache to improve data reuse during the lifetime of the application.

Note: Drivers may also employ various persistent (disk-based) caching strategies for shader and pipeline data, which is hidden to and is outside of Qt's control. In some cases, depending on the graphics API and the QRhi backend, there are facilities within QRhi for manually managing such a cache, allowing the retrieval of a serializable blob that can then be reloaded in the future runs of the application to ensure faster pipeline creation times. See QRhi::pipelineCacheData() and QRhi::setPipelineCacheData() for details. Note also that when working with a QRhi instance managed by a higher level Qt framework, such as Qt Quick, it is possible that such disk-based caching is taken care of automatically, for example QQuickWindow uses a disk-based pipeline cache by default (which comes in addition to any driver-level caching).

QRhiGraphicsPipeline::CullMode QRhiGraphicsPipeline::cullMode() const

Returns the currently set face culling mode.

See also setCullMode().

int QRhiGraphicsPipeline::depthBias() const

Returns the currently set depth bias.

See also setDepthBias().

QRhiGraphicsPipeline::CompareOp QRhiGraphicsPipeline::depthOp() const

Returns the depth comparison function.

See also setDepthOp().

QRhiGraphicsPipeline::Flags QRhiGraphicsPipeline::flags() const

Returns the currently set flags.

See also setFlags().

QRhiGraphicsPipeline::FrontFace QRhiGraphicsPipeline::frontFace() const

Returns the currently set front face mode.

See also setFrontFace().

bool QRhiGraphicsPipeline::hasDepthTest() const

Returns true if depth testing is enabled.

bool QRhiGraphicsPipeline::hasDepthWrite() const

Returns true if depth write is enabled.

bool QRhiGraphicsPipeline::hasStencilTest() const

Returns true if stencil testing is enabled.

float QRhiGraphicsPipeline::lineWidth() const

Returns the currently set line width. The default is 1.0f.

See also setLineWidth().

int QRhiGraphicsPipeline::patchControlPointCount() const

Returns the currently set patch control point count.

See also setPatchControlPointCount().

QRhiGraphicsPipeline::PolygonMode QRhiGraphicsPipeline::polygonMode() const

Returns the polygon mode.

See also setPolygonMode().

QRhiRenderPassDescriptor *QRhiGraphicsPipeline::renderPassDescriptor() const

Returns the currently set QRhiRenderPassDescriptor.

See also setRenderPassDescriptor().

[override virtual] QRhiResource::Type QRhiGraphicsPipeline::resourceType() const

Reimplements: QRhiResource::resourceType() const.

Returns the resource type.

int QRhiGraphicsPipeline::sampleCount() const

Returns the currently set sample count. 1 means no multisample antialiasing.

See also setSampleCount().

void QRhiGraphicsPipeline::setCullMode(QRhiGraphicsPipeline::CullMode mode)

Sets the specified face culling mode.

See also cullMode().

void QRhiGraphicsPipeline::setDepthBias(int bias)

Sets the depth bias. The default value is 0.

See also depthBias().

void QRhiGraphicsPipeline::setDepthOp(QRhiGraphicsPipeline::CompareOp op)

Sets the depth comparison function op.

See also depthOp().

void QRhiGraphicsPipeline::setDepthTest(bool enable)

Enables or disables depth testing based on enable. Both depth test and the writing out of depth data are disabled by default.

See also hasDepthTest() and setDepthWrite().

void QRhiGraphicsPipeline::setDepthWrite(bool enable)

Controls the writing out of depth data into the depth buffer based on enable. By default this is disabled. Depth write is typically enabled together with the depth test.

Note: Enabling depth write without having depth testing enabled may not lead to the desired result, and should be avoided.

See also hasDepthWrite() and setDepthTest().

void QRhiGraphicsPipeline::setFlags(QRhiGraphicsPipeline::Flags f)

Sets the flags f.

See also flags().

void QRhiGraphicsPipeline::setFrontFace(QRhiGraphicsPipeline::FrontFace f)

Sets the front face mode f.

See also frontFace().

void QRhiGraphicsPipeline::setLineWidth(float width)

Sets the line width. If the QRhi::WideLines feature is reported as unsupported at runtime, values other than 1.0f are ignored.

See also lineWidth().

void QRhiGraphicsPipeline::setPatchControlPointCount(int count)

Sets the number of patch control points to count. The default value is 3. This is used only when the topology is set to Patches.

See also patchControlPointCount().

void QRhiGraphicsPipeline::setPolygonMode(QRhiGraphicsPipeline::PolygonMode mode)

Sets the polygon mode. The default is Fill.

See also polygonMode() and QRhi::NonFillPolygonMode.

void QRhiGraphicsPipeline::setRenderPassDescriptor(QRhiRenderPassDescriptor *desc)

Associates with the specified QRhiRenderPassDescriptor desc.

See also renderPassDescriptor().

void QRhiGraphicsPipeline::setSampleCount(int s)

Sets the sample count. Typical values for s are 1, 4, or 8. The pipeline must always be compatible with the render target, i.e. the sample counts must match.

See also sampleCount() and QRhi::supportedSampleCounts().

void QRhiGraphicsPipeline::setShaderResourceBindings(QRhiShaderResourceBindings *srb)

Associates with srb describing the resource binding layout and the resources (QRhiBuffer, QRhiTexture) themselves. The latter is optional, because only the layout matters during pipeline creation. Therefore, the srb passed in here can leave the actual buffer or texture objects unspecified (nullptr) as long as there is another, layout-compatible QRhiShaderResourceBindings bound via setShaderResources() before recording the draw calls.

See also shaderResourceBindings().

void QRhiGraphicsPipeline::setShaderStages(std::initializer_list<QRhiShaderStage> list)

Sets the list of shader stages.

template <typename InputIterator> void QRhiGraphicsPipeline::setShaderStages(InputIterator first, InputIterator last)

Sets the list of shader stages from the iterators first and last.

void QRhiGraphicsPipeline::setSlopeScaledDepthBias(float bias)

Sets the slope scaled depth bias. The default value is 0.

See also slopeScaledDepthBias().

void QRhiGraphicsPipeline::setStencilBack(const QRhiGraphicsPipeline::StencilOpState &state)

Sets the stencil test state for back faces.

See also stencilBack().

void QRhiGraphicsPipeline::setStencilFront(const QRhiGraphicsPipeline::StencilOpState &state)

Sets the stencil test state for front faces.

See also stencilFront().

void QRhiGraphicsPipeline::setStencilReadMask(quint32 mask)

Sets the stencil read mask. The default value is 0xFF.

See also stencilReadMask().

void QRhiGraphicsPipeline::setStencilTest(bool enable)

Enables or disables stencil tests based on enable. By default this is disabled.

See also hasStencilTest().

void QRhiGraphicsPipeline::setStencilWriteMask(quint32 mask)

Sets the stencil write mask. The default value is 0xFF.

See also stencilWriteMask().

void QRhiGraphicsPipeline::setTargetBlends(std::initializer_list<TargetBlend> list)

Sets the list of render target blend settings. This is a list because when multiple render targets are used (i.e., a QRhiTextureRenderTarget with more than one QRhiColorAttachment), there needs to be a TargetBlend structure per render target (color attachment).

By default there is one default-constructed TargetBlend set.

See also QRhi::MaxColorAttachments.

template <typename InputIterator> void QRhiGraphicsPipeline::setTargetBlends(InputIterator first, InputIterator last)

Sets the list of render target blend settings from the iterators first and last.

void QRhiGraphicsPipeline::setTopology(QRhiGraphicsPipeline::Topology t)

Sets the primitive topology t.

See also topology().

void QRhiGraphicsPipeline::setVertexInputLayout(const QRhiVertexInputLayout &layout)

Specifies the vertex input layout.

See also vertexInputLayout().

QRhiShaderResourceBindings *QRhiGraphicsPipeline::shaderResourceBindings() const

Returns the currently associated QRhiShaderResourceBindings object.

See also setShaderResourceBindings().

const QRhiShaderStage *QRhiGraphicsPipeline::shaderStageAt(qsizetype index) const

Returns the shader stage at the specified index.

qsizetype QRhiGraphicsPipeline::shaderStageCount() const

Returns the number of shader stages in this pipeline.

float QRhiGraphicsPipeline::slopeScaledDepthBias() const

Returns the currently set slope scaled depth bias.

See also setSlopeScaledDepthBias().

QRhiGraphicsPipeline::StencilOpState QRhiGraphicsPipeline::stencilBack() const

Returns the current stencil test state for back faces.

See also setStencilBack().

QRhiGraphicsPipeline::StencilOpState QRhiGraphicsPipeline::stencilFront() const

Returns the current stencil test state for front faces.

See also setStencilFront().

quint32 QRhiGraphicsPipeline::stencilReadMask() const

Returns the currrent stencil read mask.

See also setStencilReadMask().

quint32 QRhiGraphicsPipeline::stencilWriteMask() const

Returns the current stencil write mask.

See also setStencilWriteMask().

const QRhiGraphicsPipeline::TargetBlend *QRhiGraphicsPipeline::targetBlendAt(qsizetype index) const

Returns the render target blend setting at the specified index.

qsizetype QRhiGraphicsPipeline::targetBlendCount() const

Returns the number of render target blend settings.

QRhiGraphicsPipeline::Topology QRhiGraphicsPipeline::topology() const

Returns the currently set primitive topology.

See also setTopology().

QRhiVertexInputLayout QRhiGraphicsPipeline::vertexInputLayout() const

Returns the currently set vertex input layout specification.

See also setVertexInputLayout().

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.