QShader Class
Contains multiple versions of a shader translated to multiple shading languages, together with reflection metadata. More...
| Header: | #include <QShader> |
| qmake: | QT += rhi |
| Since: | Qt 5.14 |
Public Types
| enum | Source { SpirvShader, GlslShader, HlslShader, DxbcShader, ..., MetalLibShader } |
| enum | Stage { VertexStage, TessellationControlStage, TessellationEvaluationStage, GeometryStage, FragmentStage, ComputeStage } |
| enum | Variant { StandardShader, BatchableVertexShader } |
Public Functions
| QShader() | |
| ~QShader() | |
| QVector<QShaderKey> | availableShaders() const |
| int | description() const |
| bool | isValid() const |
| void | removeShader(const QShaderKey &key) |
| QByteArray | serialized() const |
| void | setDescription(const int &desc) |
| void | setShader(const QShaderKey &key, const QShaderCode &shader) |
| void | setStage(QShader::Stage stage) |
| QShaderCode | shader(const QShaderKey &key) const |
| QShader::Stage | stage() const |
Static Public Members
| QShader | fromSerialized(const QByteArray &data) |
Related Non-Members
| uint | qHash(const QShader &s, uint seed = 0) |
| bool | operator!=(const QShader &lhs, const QShader &rhs) |
| bool | operator==(const QShader &lhs, const QShader &rhs) |
Detailed Description
Contains multiple versions of a shader translated to multiple shading languages, together with reflection metadata.
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.
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, QRhi expects that a QShader suitable for all its backends contains at least the following:
- 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
- HLSL Shader Model 5.0 source code or the corresponding DXBC bytecode suitable for Direct3D 11
- Metal Shading Language 1.2 source code or the corresponding bytecode suitable for Metal
See also QShaderBaker.
Member Type Documentation
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 |
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. |
Property Documentation
Member Function Documentation
QShader::QShader()
Constructs a new, empty (and thus invalid) QShader instance.
QShader::~QShader()
Destructor.
QVector<QShaderKey> QShader::availableShaders() const
Returns the list of available shader versions
int 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.
See also serialized().
bool QShader::isValid() const
Returns true if the QShader contains at least one shader version.
void QShader::removeShader(const QShaderKey &key)
Removes the source or binary shader code for a given key. Does nothing when not found.
QByteArray QShader::serialized() const
Returns a serialized binary version of all the data held by the QShader, suitable for writing to files or other I/O devices.
See also fromSerialized().
void QShader::setDescription(const int &desc)
See also description().
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().
Member Variable Documentation
Related Non-Members
uint qHash(const QShader &s, uint seed = 0)
Returns the hash value for s, using seed to seed the calculation.
bool operator!=(const QShader &lhs, const QShader &rhs)
Returns false if the values in the two QShader objects a and b are equal; otherwise returns true.
bool operator==(const QShader &lhs, const QShader &rhs)
Returns true if the two QShader objects a and b are equal, meaning they are for the same stage with matching sets of shader source or binary code.