QShader Class
Contains multiple versions of a shader translated to multiple shading languages, together with reflection metadata. More...
| Header: | #include <QShader> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui)target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| Since: | Qt 6.6 |
- List of all members, including inherited members
- QShader is part of Rendering in 3D.
Public Types
| struct | NativeShaderInfo |
| struct | SeparateToCombinedImageSamplerMapping |
| NativeResourceBindingMap | |
| SeparateToCombinedImageSamplerMappingList | |
| enum class | SerializedFormatVersion { Latest, Qt_6_5, Qt_6_4 } |
| enum | Source { SpirvShader, GlslShader, HlslShader, DxbcShader, MslShader, …, WgslShader } |
| enum | Stage { VertexStage, TessellationControlStage, TessellationEvaluationStage, GeometryStage, FragmentStage, ComputeStage } |
| enum | Variant { StandardShader, BatchableVertexShader, UInt16IndexedVertexAsComputeShader, UInt32IndexedVertexAsComputeShader, NonIndexedVertexAsComputeShader } |
Public Functions
| QShader() | |
| QShader(const QShader &other) | |
(since 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 |
(since 6.7) void | swap(QShader &other) |
(since 6.7) QShader & | operator=(QShader &&other) |
| QShader & | operator=(const QShader &other) |
Static Public Members
| QShader | fromSerialized(const QByteArray &data) |
Related Non-Members
| 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) |
Detailed Description
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.
Warning: 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:
- Generate the contents offline, during build time or earlier, using the
qsbcommand 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. - Generate at run time via QShaderBaker. This is an expensive operation, but allows applications to use user-provided or dynamically generated shader source strings.
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
- the source or byte code for any of the shading language versions that are included in the QShader,
- the name of the entry point for the shader,
- the reflection metadata containing a description of the shader's inputs, outputs and resources like uniform blocks. This is essential when an application or framework needs to discover the inputs of a shader at runtime due to not having advance knowledge of the vertex attributes or the layout of the uniform buffers used by the shader.
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)
- SPIR-V 1.0 bytecode suitable for Vulkan 1.0 or newer
- GLSL/ES 100 source code suitable for OpenGL ES 2.0 or newer
- GLSL 120 source code suitable for OpenGL 2.1 or newer
- HLSL Shader Model 5.0 source code or the corresponding DXBC bytecode suitable for Direct3D 11/12
- Metal Shading Language 1.2 source code or the corresponding bytecode suitable for Metal 1.2 or newer
See also QShaderBaker.
Member Type Documentation
[alias] QShader::NativeResourceBindingMap
Synonym for 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.
Note: 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
Synonym for QList<QShader::SeparateToCombinedImageSamplerMapping>.
enum class QShader::SerializedFormatVersion
Describes the desired output format when serializing the QShader.
The default value for the version argument of serialized() is 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.
Note: 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.
| Constant | Value | Description |
|---|---|---|
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 |
enum QShader::Source
Describes what kind of shader code an entry contains.
| Constant | Value | Description |
|---|---|---|
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 |
enum QShader::Stage
Describes the stage of the graphics pipeline the shader is suitable for.
| Constant | Value | Description |
|---|---|---|
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 |
enum QShader::Variant
Describes what kind of shader code an entry contains.
| Constant | Value | Description |
|---|---|---|
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. |
Member Function Documentation
QShader::QShader()
Constructs a new, empty (and thus invalid) QShader instance.
QShader::QShader(const QShader &other)
Constructs a copy of other.
[noexcept, since 6.7] QShader::QShader(QShader &&other)
Move-constructs a new QShader from other.
Note: 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.
This function was introduced in Qt 6.7.
[noexcept] QShader::~QShader()
Destructor.
QList<QShaderKey> QShader::availableShaders() const
Returns the list of available shader versions
QShaderDescription QShader::description() const
Returns the reflection metadata for the shader.
See also setDescription().
[static] QShader QShader::fromSerialized(const QByteArray &data)
Creates a new QShader instance from the given data.
If data cannot be deserialized successfully, the result is a default constructed QShader for which isValid() returns false.
See also serialized().
bool QShader::isValid() const
Returns true if the QShader contains at least one shader version.
QShader::NativeResourceBindingMap QShader::nativeResourceBindingMap(const QShaderKey &key) const
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).
QShader::NativeShaderInfo QShader::nativeShaderInfo(const QShaderKey &key) const
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.
See also setNativeShaderInfo().
void QShader::removeNativeShaderInfo(const QShaderKey &key)
Removes the native shader information for key.
void QShader::removeResourceBindingMap(const QShaderKey &key)
Removes the native resource binding map for key.
void QShader::removeSeparateToCombinedImageSamplerMappingList(const QShaderKey &key)
Removes the combined image sampler mapping list for key.
void QShader::removeShader(const QShaderKey &key)
Removes the source or binary shader code for a given key. Does nothing when not found.
QShader::SeparateToCombinedImageSamplerMappingList QShader::separateToCombinedImageSamplerMappingList(const QShaderKey &key) const
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.
See also setSeparateToCombinedImageSamplerMappingList().
QByteArray QShader::serialized(QShader::SerializedFormatVersion version = SerializedFormatVersion::Latest) const
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.
See also fromSerialized().
void QShader::setDescription(const QShaderDescription &desc)
Sets the reflection metadata to desc.
See also description().
void QShader::setNativeShaderInfo(const QShaderKey &key, const QShader::NativeShaderInfo &info)
Stores the given native shader info associated with key.
See also nativeShaderInfo().
void QShader::setResourceBindingMap(const QShaderKey &key, const QShader::NativeResourceBindingMap &map)
Stores the given native resource binding map associated with key.
See also nativeResourceBindingMap().
void QShader::setSeparateToCombinedImageSamplerMappingList(const QShaderKey &key, const QShader::SeparateToCombinedImageSamplerMappingList &list)
Stores the given combined image sampler mapping list associated with key.
See also separateToCombinedImageSamplerMappingList().
void QShader::setShader(const QShaderKey &key, const QShaderCode &shader)
Stores the source or binary shader code for a given shader version specified by key.
See also shader().
void QShader::setStage(QShader::Stage stage)
Sets the pipeline stage.
See also stage().
QShaderCode QShader::shader(const QShaderKey &key) const
Returns the source or binary code for a given shader version specified by key.
See also setShader().
QShader::Stage QShader::stage() const
Returns the pipeline stage the shader is meant for.
See also setStage().
[noexcept, since 6.7] void QShader::swap(QShader &other)
Swaps shader other with this shader. This operation is very fast and never fails.
This function was introduced in Qt 6.7.
[noexcept, since 6.7] QShader &QShader::operator=(QShader &&other)
Move-assigns other to this QShader instance.
Note: 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.
This function was introduced in Qt 6.7.
QShader &QShader::operator=(const QShader &other)
Assigns other to this object.
Related Non-Members
[noexcept] size_t qHash(const QShader &s, size_t seed = 0)
Returns the hash value for s, using seed to seed the calculation.
[noexcept] bool operator!=(const QShader &lhs, const QShader &rhs)
Returns false if the values in the two QShader objects lhs and rhs are equal; otherwise returns true.
[noexcept] bool operator==(const QShader &lhs, const QShader &rhs)
Returns true if the two QShader objects lhs and rhs are equal, meaning they are for the same stage with matching sets of shader source or binary code.