QShaderDescription 类

描述着色器接口。 更多...

头文件 #include <QShaderDescription>
CMakefind_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmakeQT += gui
Qt 6.6

公共类型

(since 6.6) structBlockVariable
(since 6.6) structBuiltinVariable
(since 6.6) structInOutVariable
(since 6.6) structPushConstantBlock
(since 6.6) structStorageBlock
(since 6.6) structUniformBlock
enumBuiltinType { PositionBuiltin, PointSizeBuiltin, ClipDistanceBuiltin, CullDistanceBuiltin, VertexIdBuiltin, …, InstanceIndexBuiltin }
enumImageFlag { ReadOnlyImage, WriteOnlyImage }
flagsImageFlags
enumImageFormat { ImageFormatUnknown, ImageFormatRgba32f, ImageFormatRgba16f, ImageFormatR32f, ImageFormatRgba8, …, ImageFormatR8ui }
enumQualifierFlag { QualifierReadOnly, QualifierWriteOnly, QualifierCoherent, QualifierVolatile, QualifierRestrict }
flagsQualifierFlags
enumTessellationMode { UnknownTessellationMode, TrianglesTessellationMode, QuadTessellationMode, IsolineTessellationMode }
enumTessellationPartitioning { UnknownTessellationPartitioning, EqualTessellationPartitioning, FractionalEvenTessellationPartitioning, FractionalOddTessellationPartitioning }
enumTessellationWindingOrder { UnknownTessellationWindingOrder, CwTessellationWindingOrder, CcwTessellationWindingOrder }
enumVariableType { 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
boolisValid() const
QList<QShaderDescription::BuiltinVariable>outputBuiltinVariables() const
QList<QShaderDescription::InOutVariable>outputVariables() const
QList<QShaderDescription::PushConstantBlock>pushConstantBlocks() const
voidserialize(QDataStream *stream, int version) const
QList<QShaderDescription::StorageBlock>storageBlocks() const
QList<QShaderDescription::InOutVariable>storageImages() const
QShaderDescription::TessellationModetessellationMode() const
uinttessellationOutputVertexCount() const
QShaderDescription::TessellationPartitioningtessellationPartitioning() const
QShaderDescription::TessellationWindingOrdertessellationWindingOrder() const
QByteArraytoJson() const
QList<QShaderDescription::UniformBlock>uniformBlocks() const
QShaderDescription &operator=(const QShaderDescription &other)

静态公共成员

QShaderDescriptiondeserialize(QDataStream *stream, int version)
booloperator==(const QShaderDescription &lhs, const QShaderDescription &rhs)

详细信息

注意:Qt Gui模块中的QRhi类家族(包括QShader和QShaderDescription),提供有限的兼容性保证。对于这些类没有任何源代码或二进制兼容性保证,这意味着API仅保证与开发应用时使用的Qt版本兼容。源代码不兼容的变更目标是尽可能保持最小,并且仅在次版本中(6.7、6.8等)进行修改。为了在应用中使用这些类,链接到Qt::GuiPrivate(如果使用CMake),并包含以rhi前缀的头部,例如,#include <rhi/qshaderdescription.h>.

着色器通常有一组输入和输出。例如,顶点着色器有多种输入变量,并可能使用一个或多个统一缓冲区来访问由应用提供的数据(例如模型视图矩阵)。片阶段着色器从顶点阶段接收数据(在简单设置中)并且也可能依赖于统一缓冲区、图像和采样器中的数据。

当涉及到顶点输入和统一缓冲区的布局(成员的名字是什么?大小、偏移等)时,应用和框架可能需要在运行时动态地发现这些信息。当着色器不是内置的,而是由外部实体(如用户)提供时,这种情况很常见。

现代和精简的图形API可能不再提供在运行时查询着色器反射信息的方法。因此,此类数据现在由QShaderBaker自动生成,并作为每个QShader的QShaderDescription对象提供。

示例

以下是一个顶点着色器的例子

#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;
}

这个着色器有两个输入:position位于位置0,数据类型为vec4,以及位于位置1的color,数据类型为vec3。它有一个输出:v_color,尽管这对于应用来说通常并不重要。更重要的是,绑定0中有一个大小为68字节的统一缓冲区,其中包含两个成员,一个偏移量为0的4x4矩阵mvp和一个偏移量为64的浮点数opacity

所有这些都可以由一个QShaderDescription对象来描述。QShaderDescription可以通过QDataStream序列化为JSON格式和二进制格式,也可以从这种二进制格式反序列化出来。在实际情况中,这很少需要,因为QShader会自动处理关联的QShaderDescription,但如果上述着色器的QShaderDescription被写入为JSON格式(比如通过qsb工具的-d选项),它将如下所示

{
    "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"
        }
    ]
}

C++ API允许访问上述类似的数据结构。为了简单起见,内部的结构只包含公共数据成员,也考虑到它们的位置不太可能在将来改变。

另请参阅 QShaderBakerQShader

成员类型文档

枚举 QShaderDescription::BuiltinType

内置变量类型。

常量
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

枚举 QShaderDescription::ImageFlag
QShaderDescription::ImageFlags 标志 QShaderDescription::ImageFlags

图像标志。

常量
QShaderDescription::ReadOnlyImage1 << 0
QShaderDescription::WriteOnlyImage1 << 1

ImageFlag 类型是 QFlags 的typedef。它存储了 ImageFlag 值的 OR 组合。

枚举 QShaderDescription::ImageFormat

图像格式。

常量
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

枚举 QShaderDescription::QualifierFlag
QShaderDescription::QualifierFlags 标志 QShaderDescription::QualifierFlags

限定符标志。

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

QualifierFlags 类型是 QFlags<QualifierFlag> 的 typedef。它存储了QualifierFlag值的 OR 组合。

enum QShaderDescription::TessellationMode

常量
QShaderDescription::UnknownTessellationMode0
QShaderDescription::TrianglesTessellationMode1
QShaderDescription::QuadTessellationMode2
QShaderDescription::IsolineTessellationMode3

enum QShaderDescription::TessellationPartitioning

常量
QShaderDescription::UnknownTessellationPartitioning0
QShaderDescription::EqualTessellationPartitioning1
QShaderDescription::FractionalEvenTessellationPartitioning2
QShaderDescription::FractionalOddTessellationPartitioning3

enum QShaderDescription::TessellationWindingOrder

常量
QShaderDescription::UnknownTessellationWindingOrder0
QShaderDescription::CwTessellationWindingOrder1
QShaderDescription::CcwTessellationWindingOrder2

enum QShaderDescription::VariableType

表示变量的类型或块成员的类型。

常量描述
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::Sampler52用于独立的采样器。
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 

成员函数文档

QShaderDescription::QShaderDescription()

构造一个新的、空的 QShaderDescription。

注意:为空意味着对于新构造的实例,isValid() 返回 false

QShaderDescription::QShaderDescription(const QShaderDescription &other)

构造 other 的副本。

[noexcept] QShaderDescription::~QShaderDescription()

析构函数。

QList<QShaderDescription::InOutVariable> QShaderDescription::combinedImageSamplers() const

返回组合图像采样器的列表

使用GLSL/Vulkan着色器作为源代码时,一个 layout(binding = 1) uniform sampler2D tex; 常量生成以下内容:(以文本JSON格式显示)

"combinedImageSamplers": [
     {
         "binding": 1,
         "name": "tex",
         "set": 0,
         "type": "sampler2D"
     }
 ]

这并不意味着其他语言的版本也必须使用组合图像采样器,尤其是在这个概念可能不存在的环境中。例如,一个HSLL版本可能只会使用Texture2D和SamplerState对象,分别称为寄存器t1和s1。

std::array<uint, 3> QShaderDescription::computeShaderLocalSize() const

返回计算着色器的本地大小。

例如,对于以下声明的计算着色器,该函数返回{ 256, 16, 1}。

layout(local_size_x = 256, local_size_y = 16, local_size_z = 1) in;

[静态] QShaderDescription QShaderDescription::deserialize(QDataStream *stream, int version)

stream返回一个新的QShaderDescriptionversion指定qsb版本。

另请参阅序列化

QList<QShaderDescription::BuiltinVariable> QShaderDescription::inputBuiltinVariables() const

返回作为输入使用的活动内置列表。例如,一个读取gl_TessCoord和gl_Position值的光栅化评估着色器将在这里列出

QList<QShaderDescription::InOutVariable> QShaderDescription::inputVariables() const

返回输入变量的列表。这包括顶点阶段的顶点输入(有时称为属性),以及其他阶段的输入(有时称为变元)。

bool QShaderDescription::isValid() const

如果QShaderDescription包含变量列表中的一个条目,则返回true。

QList<QShaderDescription::BuiltinVariable> QShaderDescription::outputBuiltinVariables() const

返回用作输入的活跃内置变量列表。例如,一个非常常用的顶点着色器将会将作为输出内置。

QList<QShaderDescription::InOutVariable> QShaderDescription::outputVariables() const

返回输出变量的列表。

QList<QShaderDescription::PushConstantBlock> QShaderDescription::pushConstantBlocks() const

返回推送常量块的列表。

注意:避免在要将Qt渲染硬件接口一起使用的着色器中依靠推送常量块,因为目前没有对其的支持。

void QShaderDescription::serialize(QDataStream *stream, int version) const

将此QShaderDescription序列化到streamversion指定qsb版本。

另请参阅deserialize() 和 toJson

QList<QShaderDescription::StorageBlock> QShaderDescription::storageBlocks() const

返回着色器存储块列表。

例如,对于GLSL/Vulkan着色器作为源代码,声明

struct Stuff {
    vec2 a;
    vec2 b;
};
layout(std140, binding = 0) buffer StuffSsbo {
    vec4 whatever;
    Stuff stuff[];
} buf;

生成以下内容:(此处以文本JSON的形式展示)

"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
} ]

注意:存储块中最后一个成员的大小未定义。这显示为size 0和数组维度为[0]。由于最后一个成员的大小将只在运行时才知道,所以knownSize不包括最后一个成员的大小。最后一个成员具有未定义数组大小的数组项之间的字节数为runtimeArrayStride。此值根据指定的缓冲区内存布局标准(std140、std430)的规则确定。

注意:一些图形API不支持SSBOs,例如,OpenGL 2.x 或 OpenGL ES 3.1 之前的版本。

QList<QShaderDescription::InOutVariable> QShaderDescription::storageImages() const

返回图像变量列表。

这些变量可能出现在计算着色器中。例如,layout (binding = 0, rgba8) uniform readonly image2D inputImage;生成以下内容:(此处以文本JSON的形式展示)

"storageImages": [
     {
         "binding": 0,
         "imageFormat": "rgba8",
         "name": "inputImage",
         "set": 0,
         "type": "image2D"
     }
 ]

注意:与某些图形API不兼容,例如OpenGL 2.x或OpenGL ES 3.1之前的版本,不能使用单独的图像对象。

Q ShaderDescription :: TessellationMode QShaderDescription::tessellationMode() const

返回用于着色器细分或评估着色器的细分执行模式。

如果没有设置,返回的值是 UnknownTessellationMode

例如,对于以下声明的细分评估着色器,该函数返回 TrianglesTessellationMode

layout(triangles) in;

uint QShaderDescription::tessellationOutputVertexCount() const

返回输出顶点的数量。

例如,对于以下声明的细分控制着色器,该函数返回 3。

layout(vertices = 3) out;

Q ShaderDescription :: TessellationPartitioning QShaderDescription::tessellationPartitioning() const

返回用于细分控制或评估着色器的细分分区模式。

如果没有设置,返回值是 UnknownTessellationPartitioning

例如,对于以下声明的细分评估着色器,该函数返回 FractionalOddTessellationPartitioning

layout(triangles, fractional_odd_spacing, ccw) in;

Q ShaderDescription :: TessellationWindingOrder QShaderDescription::tessellationWindingOrder() const

返回用于细分控制或评估着色器的细分接线顺序。

如果没有设置,返回值是 UnknownTessellationWindingOrder

例如,对于一个具有以下声明的镶嵌评估着色器,该函数返回CcwTessellationWindingOrder

layout(triangles, fractional_odd_spacing, ccw) in;

QByteArray QShaderDescription::toJson() const

返回数据的序列化JSON文本版本。

注意:没有提供JSON文本的反序列化方法。

另请参阅序列化

QList<QShaderDescription::UniformBlock> QShaderDescription::uniformBlocks() const

返回统一块列表。

QShaderDescription &QShaderDescription::operator=(const QShaderDescription &other)

other分配给此对象。

相关非成员函数

[noexcept] bool operator==(const QShaderDescription &lhs, const QShaderDescription &rhs)

如果两个QShaderDescription对象 lhsrhs 相等,则返回true

© 2024 The Qt Company Ltd. 本文档中的文档贡献归各自所有者所有。本机构提供的文档是根据自由软件基金会发布的GNU自由文档许可版本1.3的条款颁发的。Qt和相应的标志是芬兰及其它国家的商标,归The Qt Company Ltd.所有。其他所有商标归各自所有者所有。