QShaderDescription Class
Describes the interface of a shader. More...
Header: | #include <QShaderDescription> |
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
- QShaderDescription is part of Rendering in 3D.
Public Types
(since 6.6) struct | BlockVariable |
(since 6.6) struct | BuiltinVariable |
(since 6.6) struct | InOutVariable |
(since 6.6) struct | PushConstantBlock |
(since 6.6) struct | StorageBlock |
(since 6.6) struct | UniformBlock |
enum | BuiltinType { PositionBuiltin, PointSizeBuiltin, ClipDistanceBuiltin, CullDistanceBuiltin, VertexIdBuiltin, …, InstanceIndexBuiltin } |
enum | ImageFlag { ReadOnlyImage, WriteOnlyImage } |
flags | ImageFlags |
enum | ImageFormat { ImageFormatUnknown, ImageFormatRgba32f, ImageFormatRgba16f, ImageFormatR32f, ImageFormatRgba8, …, ImageFormatR8ui } |
enum | QualifierFlag { QualifierReadOnly, QualifierWriteOnly, QualifierCoherent, QualifierVolatile, QualifierRestrict } |
flags | QualifierFlags |
enum | TessellationMode { UnknownTessellationMode, TrianglesTessellationMode, QuadTessellationMode, IsolineTessellationMode } |
enum | TessellationPartitioning { UnknownTessellationPartitioning, EqualTessellationPartitioning, FractionalEvenTessellationPartitioning, FractionalOddTessellationPartitioning } |
enum | TessellationWindingOrder { UnknownTessellationWindingOrder, CwTessellationWindingOrder, CcwTessellationWindingOrder } |
enum | VariableType { Unknown, Float, Vec2, Vec3, Vec4, …, Half4 } |
Public Functions
QShaderDescription() | |
QShaderDescription(const QShaderDescription &other) | |
~QShaderDescription() | |
QList<QShaderDescription::InOutVariable> | combinedImageSamplers() const |
std::array<uint, 3> | computeShaderLocalSize() const |
QList<QShaderDescription::BuiltinVariable> | inputBuiltinVariables() const |
QList<QShaderDescription::InOutVariable> | inputVariables() const |
bool | isValid() const |
QList<QShaderDescription::BuiltinVariable> | outputBuiltinVariables() const |
QList<QShaderDescription::InOutVariable> | outputVariables() const |
QList<QShaderDescription::PushConstantBlock> | pushConstantBlocks() const |
void | serialize(QDataStream *stream, int version) const |
QList<QShaderDescription::StorageBlock> | storageBlocks() const |
QList<QShaderDescription::InOutVariable> | storageImages() const |
QShaderDescription::TessellationMode | tessellationMode() const |
uint | tessellationOutputVertexCount() const |
QShaderDescription::TessellationPartitioning | tessellationPartitioning() const |
QShaderDescription::TessellationWindingOrder | tessellationWindingOrder() const |
QByteArray | toJson() const |
QList<QShaderDescription::UniformBlock> | uniformBlocks() const |
QShaderDescription & | operator=(const QShaderDescription &other) |
Static Public Members
QShaderDescription | deserialize(QDataStream *stream, int version) |
Related Non-Members
bool | operator==(const QShaderDescription &lhs, const QShaderDescription &rhs) |
Detailed Description
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/qshaderdescription.h>
.
A shader typically has a set of inputs and outputs. A vertex shader for example has a number of input variables and may use one or more uniform buffers to access data (e.g. a modelview matrix) provided by the application. The shader for the fragment stage receives data from the vertex stage (in a simple setup) and may also rely on data from uniform buffers, images, and samplers.
When it comes to vertex inputs and the layout of the uniform buffers (what are the names of the members? what is there size, offset, and so on), applications and frameworks may need to discover this dynamically at run time. This is typical when the shader is not built-in but provided by an external entity, like the user.
Modern and lean graphics APIs may no longer provide a way to query shader reflection information at run time. Therefore, such data is now automatically generated by QShaderBaker and is provided as a QShaderDescription object for each and every QShader.
Example
Take the following vertex shader:
#version 440 layout(location = 0) in vec4 position; layout(location = 1) in vec3 color; layout(location = 0) out vec3 v_color; layout(std140, binding = 0) uniform buf { mat4 mvp; float opacity; } ubuf; void main() { v_color = color; gl_Position = ubuf.mvp * position; }
This shader has two inputs: position
at location 0 with a type of vec4
, and color
at location 1 with a type of vec3
. It has one output: v_color
, although this is typically not interesting for applications. What is more important, there is a uniform block at binding 0 with a size of 68 bytes and two members, a 4x4 matrix named mvp
at offset 0, and a float opacity
at offset 64.
All this is described by a QShaderDescription object. QShaderDescription can be serialized to JSON and to a binary format via QDataStream, and can be deserialized from this binary format. In practice this is rarely needed since QShader takes care of the associated QShaderDescription automatically, but if the QShaderDescription of the above shader would be written out as JSON (like it is done by the qsb
tool's -d
option), it would look like the following:
{ "inputs": [ { "location": 1, "name": "color", "type": "vec3" }, { "location": 0, "name": "position", "type": "vec4" } ], "outputs": [ { "location": 0, "name": "v_color", "type": "vec3" } ], "uniformBlocks": [ { "binding": 0, "blockName": "buf", "members": [ { "matrixStride": 16, "name": "mvp", "offset": 0, "size": 64, "type": "mat4" }, { "name": "opacity", "offset": 64, "size": 4, "type": "float" } ], "set": 0, "size": 68, "structName": "ubuf" } ] }
The C++ API allows accessing a data structure like the above. For simplicity the inner structs only contain public data members, also considering that their layout is unlikely to change in the future.
See also QShaderBaker and QShader.
Member Type Documentation
enum QShaderDescription::BuiltinType
Built-in variable type.
Constant | Value |
---|---|
QShaderDescription::PositionBuiltin | 0 |
QShaderDescription::PointSizeBuiltin | 1 |
QShaderDescription::ClipDistanceBuiltin | 3 |
QShaderDescription::CullDistanceBuiltin | 4 |
QShaderDescription::VertexIdBuiltin | 5 |
QShaderDescription::InstanceIdBuiltin | 6 |
QShaderDescription::PrimitiveIdBuiltin | 7 |
QShaderDescription::InvocationIdBuiltin | 8 |
QShaderDescription::LayerBuiltin | 9 |
QShaderDescription::ViewportIndexBuiltin | 10 |
QShaderDescription::TessLevelOuterBuiltin | 11 |
QShaderDescription::TessLevelInnerBuiltin | 12 |
QShaderDescription::TessCoordBuiltin | 13 |
QShaderDescription::PatchVerticesBuiltin | 14 |
QShaderDescription::FragCoordBuiltin | 15 |
QShaderDescription::PointCoordBuiltin | 16 |
QShaderDescription::FrontFacingBuiltin | 17 |
QShaderDescription::SampleIdBuiltin | 18 |
QShaderDescription::SamplePositionBuiltin | 19 |
QShaderDescription::SampleMaskBuiltin | 20 |
QShaderDescription::FragDepthBuiltin | 22 |
QShaderDescription::NumWorkGroupsBuiltin | 24 |
QShaderDescription::WorkgroupSizeBuiltin | 25 |
QShaderDescription::WorkgroupIdBuiltin | 26 |
QShaderDescription::LocalInvocationIdBuiltin | 27 |
QShaderDescription::GlobalInvocationIdBuiltin | 28 |
QShaderDescription::LocalInvocationIndexBuiltin | 29 |
QShaderDescription::VertexIndexBuiltin | 42 |
QShaderDescription::InstanceIndexBuiltin | 43 |
enum QShaderDescription::ImageFlag
flags QShaderDescription::ImageFlags
Image flags.
Constant | Value |
---|---|
QShaderDescription::ReadOnlyImage | 1 << 0 |
QShaderDescription::WriteOnlyImage | 1 << 1 |
The ImageFlags type is a typedef for QFlags<ImageFlag>. It stores an OR combination of ImageFlag values.
enum QShaderDescription::ImageFormat
Image format.
Constant | Value |
---|---|
QShaderDescription::ImageFormatUnknown | 0 |
QShaderDescription::ImageFormatRgba32f | 1 |
QShaderDescription::ImageFormatRgba16f | 2 |
QShaderDescription::ImageFormatR32f | 3 |
QShaderDescription::ImageFormatRgba8 | 4 |
QShaderDescription::ImageFormatRgba8Snorm | 5 |
QShaderDescription::ImageFormatRg32f | 6 |
QShaderDescription::ImageFormatRg16f | 7 |
QShaderDescription::ImageFormatR11fG11fB10f | 8 |
QShaderDescription::ImageFormatR16f | 9 |
QShaderDescription::ImageFormatRgba16 | 10 |
QShaderDescription::ImageFormatRgb10A2 | 11 |
QShaderDescription::ImageFormatRg16 | 12 |
QShaderDescription::ImageFormatRg8 | 13 |
QShaderDescription::ImageFormatR16 | 14 |
QShaderDescription::ImageFormatR8 | 15 |
QShaderDescription::ImageFormatRgba16Snorm | 16 |
QShaderDescription::ImageFormatRg16Snorm | 17 |
QShaderDescription::ImageFormatRg8Snorm | 18 |
QShaderDescription::ImageFormatR16Snorm | 19 |
QShaderDescription::ImageFormatR8Snorm | 20 |
QShaderDescription::ImageFormatRgba32i | 21 |
QShaderDescription::ImageFormatRgba16i | 22 |
QShaderDescription::ImageFormatRgba8i | 23 |
QShaderDescription::ImageFormatR32i | 24 |
QShaderDescription::ImageFormatRg32i | 25 |
QShaderDescription::ImageFormatRg16i | 26 |
QShaderDescription::ImageFormatRg8i | 27 |
QShaderDescription::ImageFormatR16i | 28 |
QShaderDescription::ImageFormatR8i | 29 |
QShaderDescription::ImageFormatRgba32ui | 30 |
QShaderDescription::ImageFormatRgba16ui | 31 |
QShaderDescription::ImageFormatRgba8ui | 32 |
QShaderDescription::ImageFormatR32ui | 33 |
QShaderDescription::ImageFormatRgb10a2ui | 34 |
QShaderDescription::ImageFormatRg32ui | 35 |
QShaderDescription::ImageFormatRg16ui | 36 |
QShaderDescription::ImageFormatRg8ui | 37 |
QShaderDescription::ImageFormatR16ui | 38 |
QShaderDescription::ImageFormatR8ui | 39 |
enum QShaderDescription::QualifierFlag
flags QShaderDescription::QualifierFlags
Qualifier flags.
Constant | Value |
---|---|
QShaderDescription::QualifierReadOnly | 1 << 0 |
QShaderDescription::QualifierWriteOnly | 1 << 1 |
QShaderDescription::QualifierCoherent | 1 << 2 |
QShaderDescription::QualifierVolatile | 1 << 3 |
QShaderDescription::QualifierRestrict | 1 << 4 |
The QualifierFlags type is a typedef for QFlags<QualifierFlag>. It stores an OR combination of QualifierFlag values.
enum QShaderDescription::TessellationMode
Constant | Value |
---|---|
QShaderDescription::UnknownTessellationMode | 0 |
QShaderDescription::TrianglesTessellationMode | 1 |
QShaderDescription::QuadTessellationMode | 2 |
QShaderDescription::IsolineTessellationMode | 3 |
enum QShaderDescription::TessellationPartitioning
Constant | Value |
---|---|
QShaderDescription::UnknownTessellationPartitioning | 0 |
QShaderDescription::EqualTessellationPartitioning | 1 |
QShaderDescription::FractionalEvenTessellationPartitioning | 2 |
QShaderDescription::FractionalOddTessellationPartitioning | 3 |
enum QShaderDescription::TessellationWindingOrder
Constant | Value |
---|---|
QShaderDescription::UnknownTessellationWindingOrder | 0 |
QShaderDescription::CwTessellationWindingOrder | 1 |
QShaderDescription::CcwTessellationWindingOrder | 2 |
enum QShaderDescription::VariableType
Represents the type of a variable or block member.
Constant | Value | Description |
---|---|---|
QShaderDescription::Unknown | 0 | |
QShaderDescription::Float | 1 | |
QShaderDescription::Vec2 | 2 | |
QShaderDescription::Vec3 | 3 | |
QShaderDescription::Vec4 | 4 | |
QShaderDescription::Mat2 | 5 | |
QShaderDescription::Mat2x3 | 6 | |
QShaderDescription::Mat2x4 | 7 | |
QShaderDescription::Mat3 | 8 | |
QShaderDescription::Mat3x2 | 9 | |
QShaderDescription::Mat3x4 | 10 | |
QShaderDescription::Mat4 | 11 | |
QShaderDescription::Mat4x2 | 12 | |
QShaderDescription::Mat4x3 | 13 | |
QShaderDescription::Int | 14 | |
QShaderDescription::Int2 | 15 | |
QShaderDescription::Int3 | 16 | |
QShaderDescription::Int4 | 17 | |
QShaderDescription::Uint | 18 | |
QShaderDescription::Uint2 | 19 | |
QShaderDescription::Uint3 | 20 | |
QShaderDescription::Uint4 | 21 | |
QShaderDescription::Bool | 22 | |
QShaderDescription::Bool2 | 23 | |
QShaderDescription::Bool3 | 24 | |
QShaderDescription::Bool4 | 25 | |
QShaderDescription::Double | 26 | |
QShaderDescription::Double2 | 27 | |
QShaderDescription::Double3 | 28 | |
QShaderDescription::Double4 | 29 | |
QShaderDescription::DMat2 | 30 | |
QShaderDescription::DMat2x3 | 31 | |
QShaderDescription::DMat2x4 | 32 | |
QShaderDescription::DMat3 | 33 | |
QShaderDescription::DMat3x2 | 34 | |
QShaderDescription::DMat3x4 | 35 | |
QShaderDescription::DMat4 | 36 | |
QShaderDescription::DMat4x2 | 37 | |
QShaderDescription::DMat4x3 | 38 | |
QShaderDescription::Sampler1D | 39 | |
QShaderDescription::Sampler2D | 40 | |
QShaderDescription::Sampler2DMS | 41 | |
QShaderDescription::Sampler3D | 42 | |
QShaderDescription::SamplerCube | 43 | |
QShaderDescription::Sampler1DArray | 44 | |
QShaderDescription::Sampler2DArray | 45 | |
QShaderDescription::Sampler2DMSArray | 46 | |
QShaderDescription::Sampler3DArray | 47 | |
QShaderDescription::SamplerCubeArray | 48 | |
QShaderDescription::SamplerRect | 49 | |
QShaderDescription::SamplerBuffer | 50 | |
QShaderDescription::SamplerExternalOES | 51 | |
QShaderDescription::Sampler | 52 | For separate samplers. |
QShaderDescription::Image1D | 53 | |
QShaderDescription::Image2D | 54 | |
QShaderDescription::Image2DMS | 55 | |
QShaderDescription::Image3D | 56 | |
QShaderDescription::ImageCube | 57 | |
QShaderDescription::Image1DArray | 58 | |
QShaderDescription::Image2DArray | 59 | |
QShaderDescription::Image2DMSArray | 60 | |
QShaderDescription::Image3DArray | 61 | |
QShaderDescription::ImageCubeArray | 62 | |
QShaderDescription::ImageRect | 63 | |
QShaderDescription::ImageBuffer | 64 | |
QShaderDescription::Struct | 65 | |
QShaderDescription::Half | 66 | |
QShaderDescription::Half2 | 67 | |
QShaderDescription::Half3 | 68 | |
QShaderDescription::Half4 | 69 |
Member Function Documentation
QShaderDescription::QShaderDescription()
Constructs a new, empty QShaderDescription.
Note: Being empty implies that isValid() returns false
for the newly constructed instance.
QShaderDescription::QShaderDescription(const QShaderDescription &other)
Constructs a copy of other.
[noexcept]
QShaderDescription::~QShaderDescription()
Destructor.
QList<QShaderDescription::InOutVariable> QShaderDescription::combinedImageSamplers() const
Returns the list of combined image samplers
With GLSL/Vulkan shaders as source a layout(binding = 1) uniform sampler2D tex;
uniform generates the following: (shown as textual JSON here)
"combinedImageSamplers": [ { "binding": 1, "name": "tex", "set": 0, "type": "sampler2D" } ]
This does not mean that other language versions of the shader must also use a combined image sampler, especially considering that the concept may not exist everywhere. For instance, a HLSL version will likely just use a Texture2D and SamplerState object with registers t1 and s1, respectively.
std::array<uint, 3> QShaderDescription::computeShaderLocalSize() const
Returns the local size of a compute shader.
For example, for a compute shader with the following declaration the function returns { 256, 16, 1}.
layout(local_size_x = 256, local_size_y = 16, local_size_z = 1) in;
[static]
QShaderDescription QShaderDescription::deserialize(QDataStream *stream, int version)
Returns a new QShaderDescription loaded from stream. version specifies the qsb version.
See also serialize().
QList<QShaderDescription::BuiltinVariable> QShaderDescription::inputBuiltinVariables() const
Returns the list of active builtins used as input. For example, a tessellation evaluation shader reading the value of gl_TessCoord and gl_Position will have TessCoordBuiltin and PositionBuiltin listed here.
QList<QShaderDescription::InOutVariable> QShaderDescription::inputVariables() const
Returns the list of input variables. This includes vertex inputs (sometimes called attributes) for the vertex stage, and inputs for other stages (sometimes called varyings).
bool QShaderDescription::isValid() const
Returns true if the QShaderDescription contains at least one entry in one of the variable and block lists.
QList<QShaderDescription::BuiltinVariable> QShaderDescription::outputBuiltinVariables() const
Returns the list of active built-in variables used as input. For example, a vertex shader will very often have PositionBuiltin as an output built-in.
QList<QShaderDescription::InOutVariable> QShaderDescription::outputVariables() const
Returns the list of output variables.
QList<QShaderDescription::PushConstantBlock> QShaderDescription::pushConstantBlocks() const
Returns the list of push constant blocks.
Note: Avoid relying on push constant blocks for shaders that are to be used in combination with the Qt Rendering Hardware Interface since that currently has no support for them.
void QShaderDescription::serialize(QDataStream *stream, int version) const
Serializes this QShaderDescription to stream. version specifies the qsb version.
See also deserialize() and toJson().
QList<QShaderDescription::StorageBlock> QShaderDescription::storageBlocks() const
Returns the list of shader storage blocks.
For example, with GLSL/Vulkan shaders as source, the declaration
struct Stuff { vec2 a; vec2 b; }; layout(std140, binding = 0) buffer StuffSsbo { vec4 whatever; Stuff stuff[]; } buf;
generates the following: (shown as textual JSON here)
"storageBlocks": [ { "binding": 0, "blockName": "StuffSsbo", "instanceName": "buf", "knownSize": 16, "runtimeArrayStride": 16 "members": [ { "name": "whatever", "offset": 0, "size": 16, "type": "vec4" }, { "arrayDims": [ 0 ], "name": "stuff", "offset": 16, "size": 0, "structMembers": [ { "name": "a", "offset": 0, "size": 8, "type": "vec2" }, { "name": "b", "offset": 8, "size": 8, "type": "vec2" } ], "type": "struct" } ], "set": 0 } ]
Note: The size of the last member in the storage block is undefined. This shows up as size
0 and an array dimension of [0]
. The storage block's knownSize
excludes the size of the last member since that will only be known at run time. The stride in bytes between array items for a last member with undefined array size is runtimeArrayStride
. This value is determined according to the specified buffer memory layout standard (std140, std430) rules.
Note: SSBOs are not available with some graphics APIs, such as, OpenGL 2.x or OpenGL ES older than 3.1.
QList<QShaderDescription::InOutVariable> QShaderDescription::storageImages() const
Returns the list of image variables.
These will likely occur in compute shaders. For example, layout (binding = 0, rgba8) uniform readonly image2D inputImage;
generates the following: (shown as textual JSON here)
"storageImages": [ { "binding": 0, "imageFormat": "rgba8", "name": "inputImage", "set": 0, "type": "image2D" } ]
Note: Separate image objects are not compatible with some graphics APIs, such as, OpenGL 2.x or OpenGL ES older than 3.1.
QShaderDescription::TessellationMode QShaderDescription::tessellationMode() const
Returns the tessellation execution mode for a tessellation control or evaluation shader.
When not set, the returned value is UnknownTessellationMode.
For example, for a tessellation evaluation shader with the following declaration the function returns TrianglesTessellationMode.
layout(triangles) in;
uint QShaderDescription::tessellationOutputVertexCount() const
Returns the number of output vertices.
For example, for a tessellation control shader with the following declaration the function returns 3.
layout(vertices = 3) out;
QShaderDescription::TessellationPartitioning QShaderDescription::tessellationPartitioning() const
Returns the tessellation partitioning mode for a tessellation control or evaluation shader.
When not set, the returned value is UnknownTessellationPartitioning.
For example, for a tessellation evaluation shader with the following declaration the function returns FractionalOddTessellationPartitioning.
layout(triangles, fractional_odd_spacing, ccw) in;
QShaderDescription::TessellationWindingOrder QShaderDescription::tessellationWindingOrder() const
Returns the tessellation winding order for a tessellation control or evaluation shader.
When not set, the returned value is UnknownTessellationWindingOrder.
For example, for a tessellation evaluation shader with the following declaration the function returns CcwTessellationWindingOrder.
layout(triangles, fractional_odd_spacing, ccw) in;
QByteArray QShaderDescription::toJson() const
Returns a serialized JSON text version of the data.
Note: There is no deserialization method provided for JSON text.
See also serialize().
QList<QShaderDescription::UniformBlock> QShaderDescription::uniformBlocks() const
Returns the list of uniform blocks.
QShaderDescription &QShaderDescription::operator=(const QShaderDescription &other)
Assigns other to this object.
Related Non-Members
[noexcept]
bool operator==(const QShaderDescription &lhs, const QShaderDescription &rhs)
Returns true
if the two QShaderDescription objects lhs and rhs are equal.
© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.