Contains multiple versions of a shader translated to multiple shading languages, together with reflection metadata. 更多...
| 头： | #include <QShader> |
| CMake: |
find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| Since: | Qt 6.6 |
| struct | NativeShaderInfo |
| struct | SeparateToCombinedImageSamplerMapping |
| NativeResourceBindingMap | |
| SeparateToCombinedImageSamplerMappingList | |
| enum class | SerializedFormatVersion { Latest, Qt_6_5, Qt_6_4 } |
| enum | 源 { SpirvShader, GlslShader, HlslShader, DxbcShader, MslShader, …, WgslShader } |
| enum | Stage { VertexStage, TessellationControlStage, TessellationEvaluationStage, GeometryStage, FragmentStage, ComputeStage } |
| enum | Variant { StandardShader, BatchableVertexShader, UInt16IndexedVertexAsComputeShader, UInt32IndexedVertexAsComputeShader, NonIndexedVertexAsComputeShader } |
| QShader () | |
| QShader (const QShader & other ) | |
(从 6.7 起)
|
QShader (QShader && other ) |
| ~QShader () | |
| QList<QShaderKey> | availableShaders () const |
| QShaderDescription | description () const |
| bool | isValid () const |
| QShader::NativeResourceBindingMap | nativeResourceBindingMap (const QShaderKey & key ) const |
| QShader::NativeShaderInfo | nativeShaderInfo (const QShaderKey & key ) const |
| void | removeNativeShaderInfo (const QShaderKey & key ) |
| void | removeResourceBindingMap (const QShaderKey & key ) |
| void | removeSeparateToCombinedImageSamplerMappingList (const QShaderKey & key ) |
| void | removeShader (const QShaderKey & key ) |
| QShader::SeparateToCombinedImageSamplerMappingList | separateToCombinedImageSamplerMappingList (const QShaderKey & key ) const |
| QByteArray | serialized (QShader::SerializedFormatVersion version = SerializedFormatVersion::Latest) const |
| void | setDescription (const QShaderDescription & desc ) |
| void | setNativeShaderInfo (const QShaderKey & key , const QShader::NativeShaderInfo & info ) |
| void | setResourceBindingMap (const QShaderKey & key , const QShader::NativeResourceBindingMap & map ) |
| void | setSeparateToCombinedImageSamplerMappingList (const QShaderKey & key , const QShader::SeparateToCombinedImageSamplerMappingList & list ) |
| void | setShader (const QShaderKey & key , const QShaderCode & shader ) |
| void | setStage (QShader::Stage stage ) |
| QShaderCode | shader (const QShaderKey & key ) const |
| QShader::Stage | stage () const |
(从 6.7 起)
void
|
swap (QShader & other ) |
| QShader & | operator= (const QShader & other ) |
(从 6.7 起)
QShader &
|
operator= (QShader && other ) |
| QShader | fromSerialized (const QByteArray & data ) |
| size_t | qHash (const QShader & s , size_t seed = 0) |
| bool | operator!= (const QShader & lhs , const QShader & rhs ) |
| bool | operator== (const QShader & lhs , const QShader & rhs ) |
QShader is the entry point to shader code in the graphics API agnostic Qt world. Instead of using GLSL shader sources, as was the custom with Qt 5.x, new graphics systems with backends for multiple graphics APIs, such as, Vulkan, Metal, Direct3D, and OpenGL, take QShader as their input whenever a shader needs to be specified.
警告：
The
QRhi
family of classes in the Qt Gui module, including QShader and
QShaderDescription
, offer limited compatibility guarantees. There are no source or binary compatibility guarantees for these classes, meaning the API is only guaranteed to work with the Qt version the application was developed against. Source incompatible changes are however aimed to be kept at a minimum and will only be made in minor releases (6.7, 6.8, and so on). To use these classes in an application, link to
Qt::GuiPrivate
(if using CMake), and include the headers with the
rhi
prefix, for example
#include <rhi/qshader.h>
.
A QShader instance is empty and thus invalid by default. To get a useful instance, the two typical methods are:
qsb
command line tool. The result is a binary file that is shipped with the application, read via
QIODevice::readAll
(), and then deserialized via
fromSerialized
(). For more information, see
QShaderBaker
.
When used together with the Qt Rendering Hardware Interface and its classes, like QRhiGraphicsPipeline , no further action is needed from the application's side as these classes are prepared to consume a QShader whenever a shader needs to be specified for a given stage of the graphics pipeline.
Alternatively, applications can access
QShader makes no assumption about the shading language that was used as the source for generating the various versions and variants that are included in it.
QShader uses implicit sharing similarly to many core Qt types, and so can be returned or passed by value. Detach happens implicitly when calling a setter.
For reference, a typical, portable QRhi expects that a QShader suitable for all its backends contains at least the following. (this excludes support for core profile OpenGL contexts, add GLSL 150 or newer for that)
另请参阅 QShaderBaker .
[alias]
QShader::
NativeResourceBindingMap
同义词 QMap <int, QPair <int, int>>.
The resource binding model
QRhi
assumes is based on SPIR-V. This means that uniform buffers, storage buffers, combined image samplers, and storage images share a common binding point space. The binding numbers in
QShaderDescription
and
QRhiShaderResourceBinding
are expected to match the
binding
layout qualifier in the Vulkan-compatible GLSL shader.
Graphics APIs other than Vulkan may use a resource binding model that is not fully compatible with this. The generator of the shader code translated from SPIR-V may choose not to take the SPIR-V binding qualifiers into account, for various reasons. This is the case with the Metal backend of SPIRV-Cross, for example. In addition, even when an automatic, implicit translation is mostly possible (e.g. by using SPIR-V binding points as HLSL resource register indices), assigning resource bindings without being constrained by the SPIR-V binding points can lead to better results.
Therefore, a QShader may expose an additional map that describes what the native binding point for a given SPIR-V binding is. The QRhi backends, for which this is relevant, are expected to use this map automatically, as appropriate. The value is a pair, because combined image samplers may map to two native resources (a texture and a sampler) in some shading languages. In that case the second value refers to the sampler.
注意： The native binding may be -1, in case there is no active binding for the resource in the shader. (for example, there is a uniform block declared, but it is not used in the shader code) The map is always complete, meaning there is an entry for all declared uniform blocks, storage blocks, image objects, and combined samplers, but the value will be -1 for those that are not actually referenced in the shader functions.
[alias]
QShader::
SeparateToCombinedImageSamplerMappingList
同义词 QList < QShader::SeparateToCombinedImageSamplerMapping >.
Describes the desired output format when serializing the QShader .
The default value for the
version
argument of
serialized
() 是
Latest
. This is sufficient in the vast majority of cases. Specifying another value is needed only when the intention is to generate serialized data that can be loaded by earlier Qt versions. For example, the
qsb
tool uses these enum values when the
--qsbversion
command-line argument is given.
注意： Targeting earlier versions will make certain features disfunctional with the generated asset. This is not an issue when using the asset with the specified, older Qt version, given that that Qt version does not have the newer features in newer Qt versions that rely on additional data generated in the QShader and the serialized data stream, but may become a problem if the generated asset is then used with a newer Qt version.
| 常量 | 值 | 描述 |
|---|---|---|
QShader::SerializedFormatVersion::Latest
|
0
|
The current Qt version |
QShader::SerializedFormatVersion::Qt_6_5
|
1
|
Qt 6.5 |
QShader::SerializedFormatVersion::Qt_6_4
|
2
|
Qt 6.4 |
Describes what kind of shader code an entry contains.
| 常量 | 值 | 描述 |
|---|---|---|
QShader::SpirvShader
|
0
|
SPIR-V |
QShader::GlslShader
|
1
|
GLSL |
QShader::HlslShader
|
2
|
HLSL |
QShader::DxbcShader
|
3
|
Direct3D bytecode (HLSL compiled by
fxc
)
|
QShader::MslShader
|
4
|
Metal Shading Language |
QShader::DxilShader
|
5
|
Direct3D bytecode (HLSL compiled by
dxc
)
|
QShader::MetalLibShader
|
6
|
Pre-compiled Metal bytecode |
QShader::WgslShader
|
7
|
WGSL |
Describes the stage of the graphics pipeline the shader is suitable for.
| 常量 | 值 | 描述 |
|---|---|---|
QShader::VertexStage
|
0
|
Vertex shader |
QShader::TessellationControlStage
|
1
|
Tessellation control (hull) shader |
QShader::TessellationEvaluationStage
|
2
|
Tessellation evaluation (domain) shader |
QShader::GeometryStage
|
3
|
Geometry shader |
QShader::FragmentStage
|
4
|
Fragment (pixel) shader |
QShader::ComputeStage
|
5
|
Compute shader |
Describes what kind of shader code an entry contains.
| 常量 | 值 | 描述 |
|---|---|---|
QShader::StandardShader
|
0
|
The normal, unmodified version of the shader code. |
QShader::BatchableVertexShader
|
1
|
Vertex shader rewritten to be suitable for Qt Quick scenegraph batching. |
QShader::UInt16IndexedVertexAsComputeShader
|
2
|
A vertex shader meant to be used in a Metal pipeline with tessellation in combination with indexed draw calls sourcing index data from a uint16 index buffer. To support the Metal tessellation pipeline, the vertex shader is translated to a compute shader that may be dependent on the index buffer usage in the draw calls (e.g. if the shader is using gl_VertexIndex), hence the need for three dedicated variants. |
QShader::UInt32IndexedVertexAsComputeShader
|
3
|
A vertex shader meant to be used in a Metal pipeline with tessellation in combination with indexed draw calls sourcing index data from a uint32 index buffer. To support the Metal tessellation pipeline, the vertex shader is translated to a compute shader that may be dependent on the index buffer usage in the draw calls (e.g. if the shader is using gl_VertexIndex), hence the need for three dedicated variants. |
QShader::NonIndexedVertexAsComputeShader
|
4
|
A vertex shader meant to be used in a Metal pipeline with tessellation in combination with non-indexed draw calls. To support the Metal tessellation pipeline, the vertex shader is translated to a compute shader that may be dependent on the index buffer usage in the draw calls (e.g. if the shader is using gl_VertexIndex), hence the need for three dedicated variants. |
Constructs a new, empty (and thus invalid) QShader instance.
构造副本为 other .
[noexcept, since 6.7]
QShader::
QShader
(
QShader
&&
other
)
Move-constructs a new QShader from other .
注意： The moved-from object other is placed in a partially-formed state, in which the only valid operations are destruction and assignment of a new value.
该函数在 Qt 6.7 引入。
[noexcept]
QShader::
~QShader
()
析构函数。
Returns the list of available shader versions
Returns the reflection metadata for the shader.
另请参阅 setDescription ().
[static]
QShader
QShader::
fromSerialized
(const
QByteArray
&
data
)
创建新的 QShader instance from the given data .
若
data
cannot be deserialized successfully, the result is a default constructed
QShader
其中
isValid
() 返回
false
.
另请参阅 serialized ().
返回 true 若 QShader contains at least one shader version.
Returns the native binding map for key . The map is empty if no mapping is available for key (for example, because the map is not applicable for the API and shading language described by key ).
Returns the native shader info struct for key , or an empty object if there is no data available for key , for example because such a mapping is not applicable for the shading language or the shader stage.
另请参阅 setNativeShaderInfo ().
Removes the native shader information for key .
Removes the native resource binding map for key .
Removes the combined image sampler mapping list for key .
Removes the source or binary shader code for a given key . Does nothing when not found.
Returns the combined image sampler mapping list for key , or an empty list if there is no data available for key , for example because such a mapping is not applicable for the shading language.
另请参阅 setSeparateToCombinedImageSamplerMappingList ().
Returns a serialized binary version of all the data held by the QShader , suitable for writing to files or other I/O devices.
By default the latest serialization format is used. Use version parameter to serialize for a compatibility Qt version. Only when it is known that the generated data stream must be made compatible with an older Qt version at the expense of making it incompatible with features introduced since that Qt version, should another value (for example, Qt_6_5 for Qt 6.5) be used.
另请参阅 fromSerialized ().
Sets the reflection metadata to desc .
另请参阅 description ().
Stores the given native shader info associated with key .
另请参阅 nativeShaderInfo ().
Stores the given native resource binding map associated with key .
另请参阅 nativeResourceBindingMap ().
Stores the given combined image sampler mapping list associated with key .
另请参阅 separateToCombinedImageSamplerMappingList ().
Stores the source or binary shader code for a given shader version specified by key .
另请参阅 shader ().
Sets the pipeline stage .
另请参阅 stage ().
Returns the source or binary code for a given shader version specified by key .
另请参阅 setShader ().
Returns the pipeline stage the shader is meant for.
另请参阅 setStage ().
[noexcept, since 6.7]
void
QShader::
swap
(
QShader
&
other
)
Swaps shader other with this shader. This operation is very fast and never fails.
该函数在 Qt 6.7 引入。
赋值 other 到此对象。
[noexcept, since 6.7]
QShader
&QShader::
operator=
(
QShader
&&
other
)
移动赋值 other 到此 QShader 实例。
注意： The moved-from object other is placed in a partially-formed state, in which the only valid operations are destruction and assignment of a new value.
该函数在 Qt 6.7 引入。
[noexcept]
size_t
qHash
(const
QShader
&
s
,
size_t
seed
= 0)
返回哈希值为 s ，使用 seed 做计算种子。
[noexcept]
bool
operator!=
(const
QShader
&
lhs
, const
QShader
&
rhs
)
返回
false
if the values in the two
QShader
对象
lhs
and
rhs
相等；否则返回
true
.
[noexcept]
bool
operator==
(const
QShader
&
lhs
, const
QShader
&
rhs
)
返回
true
若两
QShader
对象
lhs
and
rhs
are equal, meaning they are for the same stage with matching sets of shader source or binary code.