PySide6.QtGui.QRhiGraphicsPipeline¶

class QRhiGraphicsPipeline¶

Graphics pipeline state resource. More…

Added in version 6.6.

Synopsis¶

Methods¶

def cbeginShaderStages()
def cbeginTargetBlends()
def cendShaderStages()
def cendTargetBlends()
def cullMode()
def depthBias()
def depthOp()
def flags()
def frontFace()
def hasDepthTest()
def hasDepthWrite()
def hasStencilTest()
def lineWidth()
def multiViewCount()
def patchControlPointCount()
def polygonMode()
def renderPassDescriptor()
def sampleCount()
def setCullMode()
def setDepthBias()
def setDepthOp()
def setDepthTest()
def setDepthWrite()
def setFlags()
def setFrontFace()
def setLineWidth()
def setMultiViewCount()
def setPatchControlPointCount()
def setPolygonMode()
def setRenderPassDescriptor()
def setSampleCount()
def setShaderResourceBindings()
def setShaderStages()
def setSlopeScaledDepthBias()
def setStencilBack()
def setStencilFront()
def setStencilReadMask()
def setStencilTest()
def setStencilWriteMask()
def setTargetBlends()
def setTopology()
def setVertexInputLayout()
def shaderResourceBindings()
def shaderStageAt()
def shaderStageCount()
def slopeScaledDepthBias()
def stencilBack()
def stencilFront()
def stencilReadMask()
def stencilWriteMask()
def targetBlendAt()
def targetBlendCount()
def topology()
def vertexInputLayout()

Virtual methods¶

def create()

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

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 None) 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 newCompatibleRenderPassDescriptor() or 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 } });
ps->setVertexInputLayout(inputLayout);
ps->setShaderResourceBindings(srb);
ps->setRenderPassDescriptor(rpDesc);
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 QRhi

class Flag¶

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

Constant

Description

QRhiGraphicsPipeline.UsesBlendConstants

Indicates that a blend color constant will be set via setBlendConstants()

QRhiGraphicsPipeline.UsesStencilRef

Indicates that a stencil reference value will be set via setStencilRef()

QRhiGraphicsPipeline.UsesScissor

Indicates that a scissor rectangle will be set via setScissor()

QRhiGraphicsPipeline.CompileShadersWithDebugInfo

Requests 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.

QRhiGraphicsPipeline.UsesShadingRate

Indicates that a per-draw (per-pipeline) shading rate value will be set via setShadingRate() . Not specifying this flag and still calling setShadingRate() may lead to varying, unexpected results depending on the underlying graphics API.

Constant	Description
QRhiGraphicsPipeline.UsesBlendConstants	Indicates that a blend color constant will be set via `setBlendConstants()`
QRhiGraphicsPipeline.UsesStencilRef	Indicates that a stencil reference value will be set via `setStencilRef()`
QRhiGraphicsPipeline.UsesScissor	Indicates that a scissor rectangle will be set via `setScissor()`
QRhiGraphicsPipeline.CompileShadersWithDebugInfo	Requests 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.
QRhiGraphicsPipeline.UsesShadingRate	Indicates that a per-draw (per-pipeline) shading rate value will be set via `setShadingRate()` . Not specifying this flag and still calling setShadingRate() may lead to varying, unexpected results depending on the underlying graphics API.

class Topology¶

Specifies the primitive topology

Constant

Description

QRhiGraphicsPipeline.Triangles

(default)

QRhiGraphicsPipeline.TriangleStrip

QRhiGraphicsPipeline.TriangleFan

(only available if TriangleFanTopology is supported)

QRhiGraphicsPipeline.Lines

QRhiGraphicsPipeline.LineStrip

QRhiGraphicsPipeline.Points

QRhiGraphicsPipeline.Patches

(only available if Tessellation is supported, and requires the tessellation stages to be present in the pipeline)

Constant	Description
QRhiGraphicsPipeline.Triangles	(default)
QRhiGraphicsPipeline.TriangleStrip
QRhiGraphicsPipeline.TriangleFan	(only available if `TriangleFanTopology` is supported)
QRhiGraphicsPipeline.Lines
QRhiGraphicsPipeline.LineStrip
QRhiGraphicsPipeline.Points
QRhiGraphicsPipeline.Patches	(only available if `Tessellation` is supported, and requires the tessellation stages to be present in the pipeline)

class CullMode¶

Specifies the culling mode

Constant

Description

QRhiGraphicsPipeline.None_

No culling (default)

QRhiGraphicsPipeline.Front

Cull front faces

QRhiGraphicsPipeline.Back

Cull back faces

Constant	Description
QRhiGraphicsPipeline.None_	No culling (default)
QRhiGraphicsPipeline.Front	Cull front faces
QRhiGraphicsPipeline.Back	Cull back faces

class FrontFace¶

Specifies the front face winding order

Constant

Description

QRhiGraphicsPipeline.CCW

Counter clockwise (default)

QRhiGraphicsPipeline.CW

Clockwise

Constant	Description
QRhiGraphicsPipeline.CCW	Counter clockwise (default)
QRhiGraphicsPipeline.CW	Clockwise

class ColorMaskComponent¶

(inherits enum.Flag) Flag values for specifying the color write mask

Constant

Description

QRhiGraphicsPipeline.R

QRhiGraphicsPipeline.G

QRhiGraphicsPipeline.B

QRhiGraphicsPipeline.A

Constant	Description
QRhiGraphicsPipeline.R
QRhiGraphicsPipeline.G
QRhiGraphicsPipeline.B
QRhiGraphicsPipeline.A

class BlendFactor¶

Specifies the blend factor

Constant

Description

QRhiGraphicsPipeline.Zero

QRhiGraphicsPipeline.One

QRhiGraphicsPipeline.SrcColor

QRhiGraphicsPipeline.OneMinusSrcColor

QRhiGraphicsPipeline.DstColor

QRhiGraphicsPipeline.OneMinusDstColor

QRhiGraphicsPipeline.SrcAlpha

QRhiGraphicsPipeline.OneMinusSrcAlpha

QRhiGraphicsPipeline.DstAlpha

QRhiGraphicsPipeline.OneMinusDstAlpha

QRhiGraphicsPipeline.ConstantColor

QRhiGraphicsPipeline.OneMinusConstantColor

QRhiGraphicsPipeline.ConstantAlpha

QRhiGraphicsPipeline.OneMinusConstantAlpha

QRhiGraphicsPipeline.SrcAlphaSaturate

QRhiGraphicsPipeline.Src1Color

QRhiGraphicsPipeline.OneMinusSrc1Color

QRhiGraphicsPipeline.Src1Alpha

QRhiGraphicsPipeline.OneMinusSrc1Alpha

Constant	Description
QRhiGraphicsPipeline.Zero
QRhiGraphicsPipeline.One
QRhiGraphicsPipeline.SrcColor
QRhiGraphicsPipeline.OneMinusSrcColor
QRhiGraphicsPipeline.DstColor
QRhiGraphicsPipeline.OneMinusDstColor
QRhiGraphicsPipeline.SrcAlpha
QRhiGraphicsPipeline.OneMinusSrcAlpha
QRhiGraphicsPipeline.DstAlpha
QRhiGraphicsPipeline.OneMinusDstAlpha
QRhiGraphicsPipeline.ConstantColor
QRhiGraphicsPipeline.OneMinusConstantColor
QRhiGraphicsPipeline.ConstantAlpha
QRhiGraphicsPipeline.OneMinusConstantAlpha
QRhiGraphicsPipeline.SrcAlphaSaturate
QRhiGraphicsPipeline.Src1Color
QRhiGraphicsPipeline.OneMinusSrc1Color
QRhiGraphicsPipeline.Src1Alpha
QRhiGraphicsPipeline.OneMinusSrc1Alpha

class BlendOp¶

Specifies the blend operation

Constant

Description

QRhiGraphicsPipeline.Add

QRhiGraphicsPipeline.Subtract

QRhiGraphicsPipeline.ReverseSubtract

QRhiGraphicsPipeline.Min

QRhiGraphicsPipeline.Max

Constant	Description
QRhiGraphicsPipeline.Add
QRhiGraphicsPipeline.Subtract
QRhiGraphicsPipeline.ReverseSubtract
QRhiGraphicsPipeline.Min
QRhiGraphicsPipeline.Max

class CompareOp¶

Specifies the depth or stencil comparison function

Constant

Description

QRhiGraphicsPipeline.Never

QRhiGraphicsPipeline.Less

(default for depth)

QRhiGraphicsPipeline.Equal

QRhiGraphicsPipeline.LessOrEqual

QRhiGraphicsPipeline.Greater

QRhiGraphicsPipeline.NotEqual

QRhiGraphicsPipeline.GreaterOrEqual

QRhiGraphicsPipeline.Always

(default for stencil)

Constant	Description
QRhiGraphicsPipeline.Never
QRhiGraphicsPipeline.Less	(default for depth)
QRhiGraphicsPipeline.Equal
QRhiGraphicsPipeline.LessOrEqual
QRhiGraphicsPipeline.Greater
QRhiGraphicsPipeline.NotEqual
QRhiGraphicsPipeline.GreaterOrEqual
QRhiGraphicsPipeline.Always	(default for stencil)

class StencilOp¶

Specifies the stencil operation

Constant

Description

QRhiGraphicsPipeline.StencilZero

QRhiGraphicsPipeline.Keep

(default)

QRhiGraphicsPipeline.Replace

QRhiGraphicsPipeline.IncrementAndClamp

QRhiGraphicsPipeline.DecrementAndClamp

QRhiGraphicsPipeline.Invert

QRhiGraphicsPipeline.IncrementAndWrap

QRhiGraphicsPipeline.DecrementAndWrap

Constant	Description
QRhiGraphicsPipeline.StencilZero
QRhiGraphicsPipeline.Keep	(default)
QRhiGraphicsPipeline.Replace
QRhiGraphicsPipeline.IncrementAndClamp
QRhiGraphicsPipeline.DecrementAndClamp
QRhiGraphicsPipeline.Invert
QRhiGraphicsPipeline.IncrementAndWrap
QRhiGraphicsPipeline.DecrementAndWrap

class 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 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.

Constant

Description

QRhiGraphicsPipeline.Fill

The interior of the polygon is filled (default)

QRhiGraphicsPipeline.Line

Boundary edges of the polygon are drawn as line segments.

Constant	Description
QRhiGraphicsPipeline.Fill	The interior of the polygon is filled (default)
QRhiGraphicsPipeline.Line	Boundary edges of the polygon are drawn as line segments.

PySide6.QtGui.QRhiGraphicsPipeline.m_flags¶

PySide6.QtGui.QRhiGraphicsPipeline.m_topology¶

PySide6.QtGui.QRhiGraphicsPipeline.m_cullMode¶

PySide6.QtGui.QRhiGraphicsPipeline.m_frontFace¶

PySide6.QtGui.QRhiGraphicsPipeline.m_depthTest¶

PySide6.QtGui.QRhiGraphicsPipeline.m_depthWrite¶

PySide6.QtGui.QRhiGraphicsPipeline.m_depthOp¶

PySide6.QtGui.QRhiGraphicsPipeline.m_stencilTest¶

PySide6.QtGui.QRhiGraphicsPipeline.m_stencilFront¶

PySide6.QtGui.QRhiGraphicsPipeline.m_stencilBack¶

PySide6.QtGui.QRhiGraphicsPipeline.m_stencilReadMask¶

PySide6.QtGui.QRhiGraphicsPipeline.m_stencilWriteMask¶

PySide6.QtGui.QRhiGraphicsPipeline.m_sampleCount¶

PySide6.QtGui.QRhiGraphicsPipeline.m_lineWidth¶

PySide6.QtGui.QRhiGraphicsPipeline.m_depthBias¶

PySide6.QtGui.QRhiGraphicsPipeline.m_slopeScaledDepthBias¶

PySide6.QtGui.QRhiGraphicsPipeline.m_patchControlPointCount¶

PySide6.QtGui.QRhiGraphicsPipeline.m_polygonMode¶

PySide6.QtGui.QRhiGraphicsPipeline.m_multiViewCount¶

PySide6.QtGui.QRhiGraphicsPipeline.m_vertexInputLayout¶

PySide6.QtGui.QRhiGraphicsPipeline.m_shaderResourceBindings¶

PySide6.QtGui.QRhiGraphicsPipeline.m_renderPassDesc¶

cbeginShaderStages()¶

Return type:: QRhiShaderStage

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

cbeginTargetBlends()¶

Return type:: TargetBlend

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

cendShaderStages()¶

Return type:: QRhiShaderStage

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

cendTargetBlends()¶

Return type:: TargetBlend

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

abstract create()¶

Return type:: bool

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

cullMode()¶

Return type:: CullMode

Returns the currently set face culling mode.

See also

setCullMode()

depthBias()¶

Return type:: int

Returns the currently set depth bias.

See also

setDepthBias()

depthOp()¶

Return type:: CompareOp

Returns the depth comparison function.

See also

setDepthOp()

flags()¶

Return type:: Combination of Flag

Returns the currently set flags.

See also

setFlags()

frontFace()¶

Return type:: FrontFace

Returns the currently set front face mode.

See also

setFrontFace()

hasDepthTest()¶

Return type:: bool

Returns true if depth testing is enabled.

hasDepthWrite()¶

Return type:: bool

Returns true if depth write is enabled.

hasStencilTest()¶

Return type:: bool

Returns true if stencil testing is enabled.

lineWidth()¶

Return type:: float

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

See also

setLineWidth()

multiViewCount()¶

Return type:: int

Returns the view count. The default is 0, indicating no multiview rendering.

See also

setMultiViewCount()

patchControlPointCount()¶

Return type:: int

Returns the currently set patch control point count.

See also

setPatchControlPointCount()

polygonMode()¶

Return type:: PolygonMode

Returns the polygon mode.

See also

setPolygonMode()

renderPassDescriptor()¶

Return type:: QRhiRenderPassDescriptor

Returns the currently set QRhiRenderPassDescriptor .

See also

setRenderPassDescriptor()

sampleCount()¶

Return type:: int

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

See also

setSampleCount()

setCullMode(mode)¶

Parameters:: mode – CullMode

Sets the specified face culling mode.

See also

cullMode()

setDepthBias(bias)¶

Parameters:: bias – int

Sets the depth bias. The default value is 0.

See also

depthBias()

setDepthOp(op)¶

Parameters:: op – CompareOp

Sets the depth comparison function op.

See also

depthOp()

setDepthTest(enable)¶

Parameters:: enable – bool

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

setDepthWrite(enable)¶

Parameters:: enable – bool

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.