- Qt 6.9
- Qt GUI
- C++ Classes
- QShaderDescription
- Qt 6.9.3 Reference Documentation

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