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

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)
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.

ConstantValue
QShaderDescription::PositionBuiltin0
QShaderDescription::PointSizeBuiltin1
QShaderDescription::ClipDistanceBuiltin3
QShaderDescription::CullDistanceBuiltin4
QShaderDescription::VertexIdBuiltin5
QShaderDescription::InstanceIdBuiltin6
QShaderDescription::PrimitiveIdBuiltin7
QShaderDescription::InvocationIdBuiltin8
QShaderDescription::LayerBuiltin9
QShaderDescription::ViewportIndexBuiltin10
QShaderDescription::TessLevelOuterBuiltin11
QShaderDescription::TessLevelInnerBuiltin12
QShaderDescription::TessCoordBuiltin13
QShaderDescription::PatchVerticesBuiltin14
QShaderDescription::FragCoordBuiltin15
QShaderDescription::PointCoordBuiltin16
QShaderDescription::FrontFacingBuiltin17
QShaderDescription::SampleIdBuiltin18
QShaderDescription::SamplePositionBuiltin19
QShaderDescription::SampleMaskBuiltin20
QShaderDescription::FragDepthBuiltin22
QShaderDescription::NumWorkGroupsBuiltin24
QShaderDescription::WorkgroupSizeBuiltin25
QShaderDescription::WorkgroupIdBuiltin26
QShaderDescription::LocalInvocationIdBuiltin27
QShaderDescription::GlobalInvocationIdBuiltin28
QShaderDescription::LocalInvocationIndexBuiltin29
QShaderDescription::VertexIndexBuiltin42
QShaderDescription::InstanceIndexBuiltin43

enum QShaderDescription::ImageFlag
flags QShaderDescription::ImageFlags

Image flags.

ConstantValue
QShaderDescription::ReadOnlyImage1 << 0
QShaderDescription::WriteOnlyImage1 << 1

The ImageFlags type is a typedef for QFlags<ImageFlag>. It stores an OR combination of ImageFlag values.

enum QShaderDescription::ImageFormat

Image format.

ConstantValue
QShaderDescription::ImageFormatUnknown0
QShaderDescription::ImageFormatRgba32f1
QShaderDescription::ImageFormatRgba16f2
QShaderDescription::ImageFormatR32f3
QShaderDescription::ImageFormatRgba84
QShaderDescription::ImageFormatRgba8Snorm5
QShaderDescription::ImageFormatRg32f6
QShaderDescription::ImageFormatRg16f7
QShaderDescription::ImageFormatR11fG11fB10f8
QShaderDescription::ImageFormatR16f9
QShaderDescription::ImageFormatRgba1610
QShaderDescription::ImageFormatRgb10A211
QShaderDescription::ImageFormatRg1612
QShaderDescription::ImageFormatRg813
QShaderDescription::ImageFormatR1614
QShaderDescription::ImageFormatR815
QShaderDescription::ImageFormatRgba16Snorm16
QShaderDescription::ImageFormatRg16Snorm17
QShaderDescription::ImageFormatRg8Snorm18
QShaderDescription::ImageFormatR16Snorm19
QShaderDescription::ImageFormatR8Snorm20
QShaderDescription::ImageFormatRgba32i21
QShaderDescription::ImageFormatRgba16i22
QShaderDescription::ImageFormatRgba8i23
QShaderDescription::ImageFormatR32i24
QShaderDescription::ImageFormatRg32i25
QShaderDescription::ImageFormatRg16i26
QShaderDescription::ImageFormatRg8i27
QShaderDescription::ImageFormatR16i28
QShaderDescription::ImageFormatR8i29
QShaderDescription::ImageFormatRgba32ui30
QShaderDescription::ImageFormatRgba16ui31
QShaderDescription::ImageFormatRgba8ui32
QShaderDescription::ImageFormatR32ui33
QShaderDescription::ImageFormatRgb10a2ui34
QShaderDescription::ImageFormatRg32ui35
QShaderDescription::ImageFormatRg16ui36
QShaderDescription::ImageFormatRg8ui37
QShaderDescription::ImageFormatR16ui38
QShaderDescription::ImageFormatR8ui39

enum QShaderDescription::QualifierFlag
flags QShaderDescription::QualifierFlags

Qualifier flags.

ConstantValue
QShaderDescription::QualifierReadOnly1 << 0
QShaderDescription::QualifierWriteOnly1 << 1
QShaderDescription::QualifierCoherent1 << 2
QShaderDescription::QualifierVolatile1 << 3
QShaderDescription::QualifierRestrict1 << 4

The QualifierFlags type is a typedef for QFlags<QualifierFlag>. It stores an OR combination of QualifierFlag values.

enum QShaderDescription::TessellationMode

ConstantValue
QShaderDescription::UnknownTessellationMode0
QShaderDescription::TrianglesTessellationMode1
QShaderDescription::QuadTessellationMode2
QShaderDescription::IsolineTessellationMode3

enum QShaderDescription::TessellationPartitioning

ConstantValue
QShaderDescription::UnknownTessellationPartitioning0
QShaderDescription::EqualTessellationPartitioning1
QShaderDescription::FractionalEvenTessellationPartitioning2
QShaderDescription::FractionalOddTessellationPartitioning3

enum QShaderDescription::TessellationWindingOrder

ConstantValue
QShaderDescription::UnknownTessellationWindingOrder0
QShaderDescription::CwTessellationWindingOrder1
QShaderDescription::CcwTessellationWindingOrder2

enum QShaderDescription::VariableType

Represents the type of a variable or block member.

ConstantValueDescription
QShaderDescription::Unknown0 
QShaderDescription::Float1 
QShaderDescription::Vec22 
QShaderDescription::Vec33 
QShaderDescription::Vec44 
QShaderDescription::Mat25 
QShaderDescription::Mat2x36 
QShaderDescription::Mat2x47 
QShaderDescription::Mat38 
QShaderDescription::Mat3x29 
QShaderDescription::Mat3x410 
QShaderDescription::Mat411 
QShaderDescription::Mat4x212 
QShaderDescription::Mat4x313 
QShaderDescription::Int14 
QShaderDescription::Int215 
QShaderDescription::Int316 
QShaderDescription::Int417 
QShaderDescription::Uint18 
QShaderDescription::Uint219 
QShaderDescription::Uint320 
QShaderDescription::Uint421 
QShaderDescription::Bool22 
QShaderDescription::Bool223 
QShaderDescription::Bool324 
QShaderDescription::Bool425 
QShaderDescription::Double26 
QShaderDescription::Double227 
QShaderDescription::Double328 
QShaderDescription::Double429 
QShaderDescription::DMat230 
QShaderDescription::DMat2x331 
QShaderDescription::DMat2x432 
QShaderDescription::DMat333 
QShaderDescription::DMat3x234 
QShaderDescription::DMat3x435 
QShaderDescription::DMat436 
QShaderDescription::DMat4x237 
QShaderDescription::DMat4x338 
QShaderDescription::Sampler1D39 
QShaderDescription::Sampler2D40 
QShaderDescription::Sampler2DMS41 
QShaderDescription::Sampler3D42 
QShaderDescription::SamplerCube43 
QShaderDescription::Sampler1DArray44 
QShaderDescription::Sampler2DArray45 
QShaderDescription::Sampler2DMSArray46 
QShaderDescription::Sampler3DArray47 
QShaderDescription::SamplerCubeArray48 
QShaderDescription::SamplerRect49 
QShaderDescription::SamplerBuffer50 
QShaderDescription::SamplerExternalOES51 
QShaderDescription::Sampler52For separate samplers.
QShaderDescription::Image1D53 
QShaderDescription::Image2D54 
QShaderDescription::Image2DMS55 
QShaderDescription::Image3D56 
QShaderDescription::ImageCube57 
QShaderDescription::Image1DArray58 
QShaderDescription::Image2DArray59 
QShaderDescription::Image2DMSArray60 
QShaderDescription::Image3DArray61 
QShaderDescription::ImageCubeArray62 
QShaderDescription::ImageRect63 
QShaderDescription::ImageBuffer64 
QShaderDescription::Struct65 
QShaderDescription::Half66 
QShaderDescription::Half267 
QShaderDescription::Half368 
QShaderDescription::Half469 

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.