Describes the interface of a shader. 更多...
| 头： | #include <QShaderDescription> |
| CMake: |
find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| Since: | Qt 6.6 |
| struct | BlockVariable |
| struct | BuiltinVariable |
| struct | InOutVariable |
| struct | PushConstantBlock |
| struct | StorageBlock |
| 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 } |
| 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 ) |
| QShaderDescription | deserialize (QDataStream * stream , int version ) |
| bool | operator== (const QShaderDescription & lhs , const QShaderDescription & rhs ) |
警告：
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 .
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:
位置
at location 0 with a type of
vec4
，和
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.
另请参阅 QShaderBaker and QShader .
Built-in variable type.
| 常量 | 值 |
|---|---|
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
|
Image flags.
| 常量 | 值 |
|---|---|
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.
Image format.
| 常量 | 值 |
|---|---|
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
|
Qualifier flags.
| 常量 | 值 |
|---|---|
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.
| 常量 | 值 |
|---|---|
QShaderDescription::UnknownTessellationMode
|
0
|
QShaderDescription::TrianglesTessellationMode
|
1
|
QShaderDescription::QuadTessellationMode
|
2
|
QShaderDescription::IsolineTessellationMode
|
3
|
| 常量 | 值 |
|---|---|
QShaderDescription::UnknownTessellationPartitioning
|
0
|
QShaderDescription::EqualTessellationPartitioning
|
1
|
QShaderDescription::FractionalEvenTessellationPartitioning
|
2
|
QShaderDescription::FractionalOddTessellationPartitioning
|
3
|
| 常量 | 值 |
|---|---|
QShaderDescription::UnknownTessellationWindingOrder
|
0
|
QShaderDescription::CwTessellationWindingOrder
|
1
|
QShaderDescription::CcwTessellationWindingOrder
|
2
|
Represents the type of a variable or block member.
| 常量 | 值 | 描述 |
|---|---|---|
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
|
Constructs a new, empty QShaderDescription.
注意：
Being empty implies that
isValid
() 返回
false
for the newly constructed instance.
构造副本为 other .
[noexcept]
QShaderDescription::
~QShaderDescription
()
析构函数。
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.
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
)
返回新的 QShaderDescription loaded from stream . version specifies the qsb version.
另请参阅 serialize ().
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.
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).
返回 true 若 QShaderDescription contains at least one entry in one of the variable and block lists.
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.
Returns the list of output variables.
Returns the list of push constant blocks.
注意： 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.
Serializes this QShaderDescription to stream . version specifies the qsb version.
另请参阅 deserialize () 和 toJson ().
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
} ]
注意：
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.
注意： SSBOs are not available with some graphics APIs, such as, OpenGL 2.x or OpenGL ES older than 3.1.
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"
}
]
注意： Separate image objects are not compatible with some graphics APIs, such as, OpenGL 2.x or OpenGL ES older than 3.1.
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;
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;
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;
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;
Returns a serialized JSON text version of the data.
注意： There is no deserialization method provided for JSON text.
另请参阅 serialize ().
Returns the list of uniform blocks.
赋值 other 到此对象。
[noexcept]
bool
operator==
(const
QShaderDescription
&
lhs
, const
QShaderDescription
&
rhs
)
返回
true
若两
QShaderDescription
对象
lhs
and
rhs
相等。