Graphics pipeline state resource. 更多...
头: | #include <QRhiGraphicsPipeline> |
CMake: |
find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui) |
qmake: | QT += gui |
Since: | Qt 6.6 |
继承: | QRhiResource |
(从 6.6 起)
struct
|
StencilOpState |
(从 6.6 起)
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 } |
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 |
(从 6.7 起)
int
|
multiViewCount () 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 ) |
(从 6.7 起)
void
|
setMultiViewCount (int count ) |
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<QRhiGraphicsPipeline::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 |
virtual QRhiResource::Type | resourceType () const override |
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.
注意: Setting the shader stages is mandatory. There must be at least one stage, and there must be a vertex stage.
注意:
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.
注意: Setting the render pass descriptor is mandatory. To obtain a QRhiRenderPassDescriptor that can be passed to setRenderPassDescriptor (), use either QRhiTextureRenderTarget::newCompatibleRenderPassDescriptor () 或 QRhiSwapChain::newCompatibleRenderPassDescriptor ().
注意: Setting the vertex input layout is mandatory.
注意: sampleCount () defaults to 1 and must match the sample count of the render target's color and depth stencil attachments.
注意: The depth test, depth write, and stencil test are disabled by default. The face culling mode defaults to no culling.
注意: stencilReadMask () 和 stencilWriteMask () apply to both faces. They both default to 0xFF.
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.
注意: This is a RHI API with limited compatibility guarantees, see QRhi 了解细节。
另请参阅 QRhiCommandBuffer and QRhi .
Specifies the blend factor
常量 | 值 |
---|---|
QRhiGraphicsPipeline::Zero
|
0
|
QRhiGraphicsPipeline::One
|
1
|
QRhiGraphicsPipeline::SrcColor
|
2
|
QRhiGraphicsPipeline::OneMinusSrcColor
|
3
|
QRhiGraphicsPipeline::DstColor
|
4
|
QRhiGraphicsPipeline::OneMinusDstColor
|
5
|
QRhiGraphicsPipeline::SrcAlpha
|
6
|
QRhiGraphicsPipeline::OneMinusSrcAlpha
|
7
|
QRhiGraphicsPipeline::DstAlpha
|
8
|
QRhiGraphicsPipeline::OneMinusDstAlpha
|
9
|
QRhiGraphicsPipeline::ConstantColor
|
10
|
QRhiGraphicsPipeline::OneMinusConstantColor
|
11
|
QRhiGraphicsPipeline::ConstantAlpha
|
12
|
QRhiGraphicsPipeline::OneMinusConstantAlpha
|
13
|
QRhiGraphicsPipeline::SrcAlphaSaturate
|
14
|
QRhiGraphicsPipeline::Src1Color
|
15
|
QRhiGraphicsPipeline::OneMinusSrc1Color
|
16
|
QRhiGraphicsPipeline::Src1Alpha
|
17
|
QRhiGraphicsPipeline::OneMinusSrc1Alpha
|
18
|
Specifies the blend operation
常量 | 值 |
---|---|
QRhiGraphicsPipeline::Add
|
0
|
QRhiGraphicsPipeline::Subtract
|
1
|
QRhiGraphicsPipeline::ReverseSubtract
|
2
|
QRhiGraphicsPipeline::Min
|
3
|
QRhiGraphicsPipeline::Max
|
4
|
Flag values for specifying the color write mask
常量 | 值 |
---|---|
QRhiGraphicsPipeline::R
|
1 << 0
|
QRhiGraphicsPipeline::G
|
1 << 1
|
QRhiGraphicsPipeline::B
|
1 << 2
|
QRhiGraphicsPipeline::A
|
1 << 3
|
The ColorMask type is a typedef for QFlags <ColorMaskComponent>. It stores an OR combination of ColorMaskComponent values.
Specifies the depth or stencil comparison function
常量 | 值 | 描述 |
---|---|---|
QRhiGraphicsPipeline::Never
|
0
|
|
QRhiGraphicsPipeline::Less
|
1
|
(default for depth) |
QRhiGraphicsPipeline::Equal
|
2
|
|
QRhiGraphicsPipeline::LessOrEqual
|
3
|
|
QRhiGraphicsPipeline::Greater
|
4
|
|
QRhiGraphicsPipeline::NotEqual
|
5
|
|
QRhiGraphicsPipeline::GreaterOrEqual
|
6
|
|
QRhiGraphicsPipeline::Always
|
7
|
(default for stencil) |
Specifies the culling mode
常量 | 值 | 描述 |
---|---|---|
QRhiGraphicsPipeline::None
|
0
|
No culling (default) |
QRhiGraphicsPipeline::Front
|
1
|
Cull front faces |
QRhiGraphicsPipeline::Back
|
2
|
Cull back faces |
Flag values for describing the dynamic state of the pipeline, and other options. The viewport is always dynamic.
常量 | 值 | 描述 |
---|---|---|
QRhiGraphicsPipeline::UsesBlendConstants
|
1 << 0
|
Indicates that a blend color constant will be set via QRhiCommandBuffer::setBlendConstants () |
QRhiGraphicsPipeline::UsesStencilRef
|
1 << 1
|
Indicates that a stencil reference value will be set via QRhiCommandBuffer::setStencilRef () |
QRhiGraphicsPipeline::UsesScissor
|
1 << 2
|
Indicates that a scissor rectangle will be set via QRhiCommandBuffer::setScissor () |
QRhiGraphicsPipeline::CompileShadersWithDebugInfo
|
1 << 3
|
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.
|
Flags 类型是 typedef 对于 QFlags <Flag>。它存储 Flag 值的 OR 组合。
Specifies the front face winding order
常量 | 值 | 描述 |
---|---|---|
QRhiGraphicsPipeline::CCW
|
0
|
Counter clockwise (default) |
QRhiGraphicsPipeline::CW
|
1
|
Clockwise |
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::Fill
|
0
|
The interior of the polygon is filled (default) |
QRhiGraphicsPipeline::Line
|
1
|
Boundary edges of the polygon are drawn as line segments. |
Specifies the stencil operation
常量 | 值 | 描述 |
---|---|---|
QRhiGraphicsPipeline::StencilZero
|
0
|
|
QRhiGraphicsPipeline::Keep
|
1
|
(默认) |
QRhiGraphicsPipeline::Replace
|
2
|
|
QRhiGraphicsPipeline::IncrementAndClamp
|
3
|
|
QRhiGraphicsPipeline::DecrementAndClamp
|
4
|
|
QRhiGraphicsPipeline::Invert
|
5
|
|
QRhiGraphicsPipeline::IncrementAndWrap
|
6
|
|
QRhiGraphicsPipeline::DecrementAndWrap
|
7
|
Specifies the primitive topology
常量 | 值 | 描述 |
---|---|---|
QRhiGraphicsPipeline::Triangles
|
0
|
(默认) |
QRhiGraphicsPipeline::TriangleStrip
|
1
|
|
QRhiGraphicsPipeline::TriangleFan
|
2
|
(only available if QRhi::TriangleFanTopology is supported) |
QRhiGraphicsPipeline::Lines
|
3
|
|
QRhiGraphicsPipeline::LineStrip
|
4
|
|
QRhiGraphicsPipeline::Points
|
5
|
|
QRhiGraphicsPipeline::Patches
|
6
|
(only available if QRhi::Tessellation is supported, and requires the tessellation stages to be present in the pipeline) |
Returns a const iterator pointing to the first item in the shader stage list.
Returns a const iterator pointing to the first item in the render target blend setting list.
Returns a const iterator pointing just after the last item in the shader stage list.
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 (),然后 destroy () is called implicitly first.
返回
true
when successful,
false
when a graphics operation failed. Regardless of the return value, calling
destroy
() is always safe.
注意:
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.
注意: 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 () 和 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).
Returns the currently set face culling mode.
另请参阅 setCullMode ().
Returns the currently set depth bias.
另请参阅 setDepthBias ().
Returns the depth comparison function.
另请参阅 setDepthOp ().
Returns the currently set flags.
另请参阅 setFlags ().
Returns the currently set front face mode.
另请参阅 setFrontFace ().
Returns true if depth testing is enabled.
Returns true if depth write is enabled.
Returns true if stencil testing is enabled.
Returns the currently set line width. The default is 1.0f.
另请参阅 setLineWidth ().
[since 6.7]
int
QRhiGraphicsPipeline::
multiViewCount
() const
Returns the view count. The default is 0, indicating no multiview rendering.
该函数在 Qt 6.7 引入。
另请参阅 setMultiViewCount ().
Returns the currently set patch control point count.
另请参阅 setPatchControlPointCount ().
Returns the polygon mode.
另请参阅 setPolygonMode ().
Returns the currently set QRhiRenderPassDescriptor .
另请参阅 setRenderPassDescriptor ().
[override virtual]
QRhiResource::Type
QRhiGraphicsPipeline::
resourceType
() const
重实现: QRhiResource::resourceType() const .
Returns the resource type.
Returns the currently set sample count. 1 means no multisample antialiasing.
另请参阅 setSampleCount ().
Sets the specified face culling mode .
另请参阅 cullMode ().
Sets the depth bias . The default value is 0.
另请参阅 depthBias ().
Sets the depth comparison function op .
另请参阅 depthOp ().
Enables or disables depth testing based on enable . Both depth test and the writing out of depth data are disabled by default.
另请参阅 hasDepthTest () 和 setDepthWrite ().
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.
注意: Enabling depth write without having depth testing enabled may not lead to the desired result, and should be avoided.
另请参阅 hasDepthWrite () 和 setDepthTest ().
Sets the flags f .
另请参阅 flags ().
Sets the front face mode f .
另请参阅 frontFace ().
设置行 width 。若 QRhi::WideLines feature is reported as unsupported at runtime, values other than 1.0f are ignored.
另请参阅 lineWidth ().
[since 6.7]
void
QRhiGraphicsPipeline::
setMultiViewCount
(
int
count
)
Sets the view count for multiview rendering. The default is 0, indicating no multiview rendering. count must be 2 or larger to trigger multiview rendering.
Multiview is only available when the MultiView feature is reported as supported. The render target must be a 2D texture array, and the color attachment for the render target must have the same count set.
见 QRhiColorAttachment::setMultiViewCount () for further details on multiview rendering.
该函数在 Qt 6.7 引入。
另请参阅 multiViewCount (), QRhi::MultiView ,和 QRhiColorAttachment::setMultiViewCount ().
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 .
另请参阅 patchControlPointCount ().
Sets the polygon mode . The default is Fill.
另请参阅 polygonMode () 和 QRhi::NonFillPolygonMode .
Associates with the specified QRhiRenderPassDescriptor desc .
另请参阅 renderPassDescriptor ().
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.
另请参阅 sampleCount () 和 QRhi::supportedSampleCounts ().
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.
另请参阅 shaderResourceBindings ().
设置 list of shader stages.
Sets the list of shader stages from the iterators first and last .
Sets the slope scaled depth bias . The default value is 0.
另请参阅 slopeScaledDepthBias ().
Sets the stencil test state for back faces.
另请参阅 stencilBack ().
Sets the stencil test state for front faces.
另请参阅 stencilFront ().
Sets the stencil read mask . The default value is 0xFF.
另请参阅 stencilReadMask ().
Enables or disables stencil tests based on enable . By default this is disabled.
另请参阅 hasStencilTest ().
Sets the stencil write mask . The default value is 0xFF.
另请参阅 stencilWriteMask ().
设置 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.
另请参阅 QRhi::MaxColorAttachments .
Sets the list of render target blend settings from the iterators first and last .
Sets the primitive topology t .
另请参阅 topology ().
Specifies the vertex input layout .
另请参阅 vertexInputLayout ().
Returns the currently associated QRhiShaderResourceBindings 对象。
另请参阅 setShaderResourceBindings ().
Returns the shader stage at the specified index .
Returns the number of shader stages in this pipeline.
Returns the currently set slope scaled depth bias.
另请参阅 setSlopeScaledDepthBias ().
Returns the current stencil test state for back faces.
另请参阅 setStencilBack ().
Returns the current stencil test state for front faces.
另请参阅 setStencilFront ().
Returns the currrent stencil read mask.
另请参阅 setStencilReadMask ().
Returns the current stencil write mask.
另请参阅 setStencilWriteMask ().
Returns the render target blend setting at the specified index .
Returns the number of render target blend settings.
Returns the currently set primitive topology.
另请参阅 setTopology ().
Returns the currently set vertex input layout specification.
另请参阅 setVertexInputLayout ().