QShader 类
包含多个版本的着色器，这些着色器被翻译成多种着色语言，并带有反射元数据。更多信息...
| 头文件 | #include <QShader> |
| CMake | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake | QT += gui |
| 自 | Qt 6.6 |
- 所有成员列表，包括继承成员
- QShader 是 3D 绘制的一部分。3D 绘制.
公共类型
| struct | NativeShaderInfo |
| struct | SeparateToCombinedImageSamplerMapping |
| NativeResourceBindingMap | |
| SeparateToCombinedImageSamplerMappingList | |
| enum class | SerializedFormatVersion { Latest, Qt_6_5, Qt_6_4 } |
| enum | Source { SpirvShader, GlslShader, HlslShader, DxbcShader, MslShader, …, WgslShader } |
| enum | Stage { VertexStage, TessellationControlStage, TessellationEvaluationStage, GeometryStage, FragmentStage, ComputeStage } |
| enum | Variant { StandardShader, BatchableVertexShader, UInt16IndexedVertexAsComputeShader, UInt32IndexedVertexAsComputeShader, NonIndexedVertexAsComputeShader } |
公共函数
| QShader() | |
| QShader(const QShader &other) | |
(since 6.7) | QShader(QShader &&other) |
| ~QShader() | |
| QList<QShaderKey> | availableShaders() const |
| QShaderDescription | description() const |
| bool | isValid() const |
| QShader::NativeResourceBindingMap | nativeResourceBindingMap(const QShaderKey &key) const |
| QShader::NativeShaderInfo | nativeShaderInfo(const QShaderKey &key) const |
| void | removeNativeShaderInfo(const QShaderKey &key) |
| void | removeResourceBindingMap(const QShaderKey &key) |
| void | removeSeparateToCombinedImageSamplerMappingList(const QShaderKey &key) |
| void | removeShader(const QShaderKey &key) |
| QShader::SeparateToCombinedImageSamplerMappingList | separateToCombinedImageSamplerMappingList(const QShaderKey &key) const |
| QByteArray | serialized(QShader::SerializedFormatVersion version = SerializedFormatVersion::Latest) const |
| void | setDescription(const QShaderDescription &desc) |
| void | setNativeShaderInfo(const QShaderKey &key, const QShader::NativeShaderInfo &info) |
| void | setResourceBindingMap(const QShaderKey &key, const QShader::NativeResourceBindingMap &map) |
| void | setSeparateToCombinedImageSamplerMappingList(const QShaderKey &key, const QShader::SeparateToCombinedImageSamplerMappingList &list) |
| void | setShader(const QShaderKey &key, const QShaderCode &shader) |
| void | setStage(QShader::Stage 阶段) |
| QShaderCode | shader(const QShaderKey &key) const |
| QShader::Stage | stage() const |
(since 6.7) void | swap(QShader &其他) |
| QShader & | operator=(const QShader &其他) |
(since 6.7) QShader & | operator=(QShader &&其他) |
静态公开成员
| QShader | fromSerialized(const QByteArray &数据) |
相关非成员
| size_t | qHash(const QShader &访问, size_t 种子 = 0) |
| bool | operator!=(const QShader &lhs, const QShader &rhs) |
| bool | operator==(const QShader &lhs, const QShader &rhs) |
详细说明
QShader 是在图形 API 不可知 Qt 世界中着色器代码的入口点。与 Qt 5.x 一直以来的做法不同，新的具有针对多个图形 API 后端的图形系统（例如，Vulkan、Metal、Direct3D 和 OpenGL）将 QShader 作为其输入，每当需要指定着色器时。
注意：Qt Gui 模块中的 QRhi 类族，包括 QShader 和 QShaderDescription，提供有限的兼容性保证。这些类没有任何源或二进制兼容性保证，这意味着 API 只保证与开发应用程序时使用的 Qt 版本兼容。但是，目的是尽可能减少源不兼容的更改，并且仅在次要版本（6.7、6.8 等等）中进行修改。要在应用程序中使用这些类，请链接到 Qt::GuiPrivate（如果使用 CMake），并使用 rhi 前缀包含头文件，例如 #include <rhi/qshader.h>。
QShader 实例默认为空，因此是无效的。要获取一个有用的实例，有两种典型的方法
- 在构建时间或更早时候使用
qsb命令行工具离线生成内容。结果是与应用程序一起分发的二进制文件，通过 QIODevice::readAll() 读取，然后通过 fromSerialized() 反序列化。有关更多信息，请参阅 QShaderBaker。 - 通过 QShaderBaker 在运行时生成。这是一项昂贵的操作，但允许应用程序使用用户提供的或动态生成的着色器源代码字符串。
当与 Qt 渲染硬件接口及其类（如 QRhiGraphicsPipeline）一起使用时，无需从应用程序方面执行任何进一步的操作，因为这些类已准备好在任何需要为图形管道的给定阶段指定着色器时消耗 QShader。
或者，应用程序可以访问
- QShader 中包含的任何着色语言版本的源或字节码
- 着色器入口点的名称
- 反射元数据，包含对着色器输入、输出和资源（如统一块）的描述。当应用程序或框架因没有先知顶点属性或着色器使用的统一缓冲区的布局，需要在运行时发现着色器的输入时，这是必不可少的。
QShader 对用于生成其包含的各种版本和变体的着色语言没有假设。
QShader 使用与许多核心 Qt 类型类似的隐式共享，因此可以通过值返回或传递。在调用设置器时，分离操作会隐式发生。
为了参考，一个典型的、可移植的 QRhi 预期一个适用于其所有后端的双语QShader至少包含以下内容。（这不包括对核心配置文件OpenGL上下文的支持，添加GLSL 150或更新的版本）
- 适用于 Vulkan 1.0 或更高版本的 SPIR-V 1.0 字节码
- 适用于 OpenGL ES 2.0 或更高版本的 GLSL/ES 100 源代码
- 适用于 OpenGL 2.1 或更高版本的 GLSL 120 源代码
- 适用于 Direct3D 11/12 的 HLSL Shader Model 5.0 源代码或相应的 DXBC 字节码
- 适用于 Metal 1.2 或更高版本的 Metal Shading Language 1.2 源代码或相应的字节码
另请参阅 QShaderBaker。
成员类型文档
[别名] QShader::NativeResourceBindingMap
是 QMap<int, QPair<int, int>> 的同义词。
资源绑定模型 QRhi 假设基于 SPIR-V。这意味着均匀缓冲区、存储缓冲区、组合图像采样器和存储图像共享一个公共绑定点空间。在 QShaderDescription 和 QRhiShaderResourceBinding 中的绑定数字应与 Vulkan 兼容的 GLSL 着色器中的 binding 布局限定符匹配。
除了 Vulkan 之外，其他图形API可能会使用与这种模式不完全兼容的资源绑定模型。将 SPIR-V 转换为着色器代码的生成器可能出于各种原因而选择不考虑 SPIR-V 绑定限定符。例如，SPIRV-Cross的 Metal后端就是这样。此外，即使在大多数情况下自动隐式转换（例如通过使用 SPIR-V 绑定点作为 HLSL 资源注册索引）基本上是可能的，不受到 SPIR-V 绑定点的约束来分配资源绑定可能会产生更好的结果。
因此，一个 QShader 可以公开一个额外的映射，该映射描述给定 SPIR-V 绑定的本地绑定点。对于此相关信息，QRhi 后端期望自动使用此映射。值是一个对，因为组合图像采样器可能在某些着色语言中映射到两个本地资源（一个纹理和一个采样器）。在这种情况下，第二个值指向采样器。
注意：如果着色器中未对资源进行活动的绑定，则本地绑定可能为 -1。（例如，声明了一个均匀块，但在着色器代码中没有使用它）此映射始终完整，这意味着该映射涵盖了所有声明的统一块、存储块、图像对象和组合采样器，但那些在实际的着色器函数中没有引用的值将为 -1。
[别名] QShader::SeparateToCombinedImageSamplerMappingList
是 QList<QShader::SeparateToCombinedImageSamplerMapping> 的同义词。
enum class QShader::SerializedFormatVersion
描述了序列化 QShader 时的期望输出格式。
serialized() 的 version 参数的默认值是 Latest。在绝大多数情况下，这已经足够。只有在意图生成可由早期Qt版本加载的序列化数据时，才需要指定其他值。例如，当提供 --qsbversion 命令行参数时，qsb 工具使用这些枚举值。
注意：针对旧版本会有一定的功能无法正常使用。这在使用指定旧版本的 Qt 时不是问题，因为该 Qt 版本没有在新版本中依赖额外在 QShader 和序列化数据流中生成的新功能，但如果生成的资源随后使用 newer Qt 版本，则可能会出现问题。
| 常量 | 值 | 描述 |
|---|---|---|
QShader::SerializedFormatVersion::Latest | 0 | 当前 Qt 版本 |
QShader::SerializedFormatVersion::Qt_6_5 | 1 | Qt 6.5 |
QShader::SerializedFormatVersion::Qt_6_4 | 2 | Qt 6.4 |
枚举 QShader::Source
描述了条目包含的着色器代码类型。
| 常量 | 值 | 描述 |
|---|---|---|
QShader::SpirvShader | 0 | SPIR-V |
QShader::GlslShader | 1 | GLSL |
QShader::HlslShader | 2 | HLSL |
QShader::DxbcShader | 3 | Direct3D 字节码（由 fxc 编译的 HLSL） |
QShader::MslShader | 4 | Metal 着色语言 |
QShader::DxilShader | 5 | Direct3D 字节码（由 dxc 编译的 HLSL） |
QShader::MetalLibShader | 6 | 预编译的 Metal 字节码 |
QShader::WgslShader | 7 | WGSL |
枚举 QShader::Stage
描述着色器适合的图形管道阶段。
| 常量 | 值 | 描述 |
|---|---|---|
QShader::VertexStage | 0 | 顶点着色器 |
QShader::TessellationControlStage | 1 | 着色器控制（hull）着色器 |
QShader::TessellationEvaluationStage | 2 | 着色器评估（domain）着色器 |
QShader::GeometryStage | 3 | 几何着色器 |
QShader::FragmentStage | 4 | 片段（像素）着色器 |
QShader::ComputeStage | 5 | 计算着色器 |
枚举 QShader::Variant
描述了条目包含的着色器代码类型。
| 常量 | 值 | 描述 |
|---|---|---|
QShader::StandardShader | 0 | 着色器代码的正常、未修改版本。 |
QShader::BatchableVertexShader | 1 | 顶点着色器重写为适合 Qt Quick 场景图批处理。 |
QShader::UInt16IndexedVertexAsComputeShader | 2 | 一个顶点着色器，旨在与索引绘制调用一起用于 Metal 管道中的曲面细分。为了支持 Metal 曲面细分管道，顶点着色器被翻译成可能依赖于绘制调用中索引缓冲区使用情况（例如，如果着色器使用了 gl_VertexIndex）的计算着色器，因此需要三个专用变体。 |
QShader::UInt32IndexedVertexAsComputeShader | 3 | 一个顶点着色器，旨在与索引绘制调用一起用于 Metal 管道中的曲面细分。为了支持 Metal 曲面细分管道，顶点着色器被翻译成可能依赖于绘制调用中索引缓冲区使用情况（例如，如果着色器使用了 gl_VertexIndex）的计算着色器，因此需要三个专用变体。 |
QShader::NonIndexedVertexAsComputeShader | 4 | 一个顶点着色器，旨在与非索引绘制调用一起用于 Metal 管道中的曲面细分。为了支持 Metal 曲面细分管道，顶点着色器被翻译成可能依赖于绘制调用中索引缓冲区使用情况（例如，如果着色器使用了 gl_VertexIndex）的计算着色器，因此需要三个专用变体。 |
成员函数文档
QShader::QShader()
构造一个新的、空的（因此无效的）QShader 实例。
QShader::QShader(const QShader &other)
构造 other 的副本。
[noexcept, since 6.7] QShader::QShader(QShader &&other)
从other中移动构造一个新QShader。
注意：被移动的对象other将被置于一个半构造状态，此时唯一有效的操作是析构和为新值赋值。
此函数是在Qt 6.7中引入的。
[noexcept] QShader::~QShader()
析构函数。
QList<QShaderKey> QShader::availableShaders() const
返回可用的着色器版本的列表
QShaderDescription QShader::description() const
返回着色器的反射元数据。
另请参阅：setDescription()。
[static] QShader QShader::fromSerialized(const QByteArray &data)
从给定的data创建一个新的QShader实例。
如果data无法成功反序列化，则结果是一个默认构造的QShader，其isValid()返回false。
另请参阅：serialized()。
bool QShader::isValid() const
如果QShader中包含至少一个着色器版本，则返回true。
QShader::NativeResourceBindingMap QShader::nativeResourceBindingMap(const QShaderKey &key) const
返回key的本地绑定映射。如果为key没有可用的映射（例如，因为映射对该API和由key描述的着色语言不适用），则该映射为空。
QShader::NativeShaderInfo QShader::nativeShaderInfo(const QShaderKey &key) const
返回key的本地着色器信息结构，或者在为key没有可用数据的情况下（例如，因为此类映射不适用于着色语言或着色器阶段），返回一个空对象。
另请参阅：setNativeShaderInfo()。
void QShader::removeNativeShaderInfo(const QShaderKey &key)
移除key的本地着色器信息。
void QShader::removeResourceBindingMap(const QShaderKey &key)
移除key的本地资源绑定映射。
void QShader::removeSeparateToCombinedImageSamplerMappingList(const QShaderKey &key)
移除key的合并不规则图像采样器映射列表。
void QShader::removeShader(const QShaderKey &key)
删除指定 key 对应的着色器源代码或二进制代码。未找到时无操作。
QShader::SeparateToCombinedImageSamplerMappingList QShader::separateToCombinedImageSamplerMappingList(const QShaderKey &key) const
返回与 key 对应的合并图像采样器映射列表，如果 key 没有数据（例如，此类映射不适适用于着色器语言），则返回空列表。
另请参阅 setSeparateToCombinedImageSamplerMappingList().
QByteArray QShader::serialized(QShader::SerializedFormatVersion version = SerializedFormatVersion::Latest) const
返回包含所有着色器数据的序列化二进制版本，适用于写入文件或其他I/O设备。
默认使用最新的序列化格式。使用 version 参数对与兼容性Qt版本进行序列化。只有当已知生成的数据流必须与较老版本的Qt兼容（以牺牲与该Qt版本后引入的功能的兼容性为代价）时，才应使用另一个值（例如，Qt_6_5用于Qt 6.5）。
另请参阅 fromSerialized().
void QShader::setDescription(const QShaderDescription &desc)
将反射元数据设置为 desc。
另请参阅 description().
void QShader::setNativeShaderInfo(const QShaderKey &key, const QShader::NativeShaderInfo &info)
存储与 key 相关的本地着色器 info。
另请参阅 nativeShaderInfo().
void QShader::setResourceBindingMap(const QShaderKey &key, const QShader::NativeResourceBindingMap &map)
存储与 key 相关的本地资源绑定 map。
另请参阅 nativeResourceBindingMap().
void QShader::setSeparateToCombinedImageSamplerMappingList(const QShaderKey &key, const QShader::SeparateToCombinedImageSamplerMappingList &list)
存储与 key 相关的合并图像采样器映射 list。
另请参阅 separateToCombinedImageSamplerMappingList().
void QShader::setShader(const QShaderKey &key, const QShaderCode &shader)
存储指定版本的着色器shader的源代码或二进制代码。
另请参阅shader。
void QShader::setStage(QShader::Stage stage)
设置管线stage。
另请参阅stage。
QShaderCode QShader::shader(const QShaderKey &key) const
返回指定版本的着色器shader的源代码或二进制代码。
另请参阅setShader。
QShader::Stage QShader::stage() const
返回着色器针对的管线阶段。
另请参阅setStage。
[noexcept, since 6.7] void QShader::swap(QShader &other)
将着色器other与此着色器交换。此操作非常快速，永远不会失败。
此函数是在Qt 6.7中引入的。
QShader &QShader::operator=(const QShader &other)
将other赋值给此对象。
[noexcept, since 6.7] QShader &QShader::operator=(QShader &&other)
移动赋值other到此QShader实例。
注意：被移动的对象other将被置于一个半构造状态，此时唯一有效的操作是析构和为新值赋值。
此函数是在Qt 6.7中引入的。
相关的非成员函数
[noexcept] size_t qHash(const QShader &s, size_t seed = 0)
返回s的哈希值，使用seed来初始化计算。
[noexcept] bool operator!=(const QShader &lhs, const QShader &rhs)
如果两个QShader对象lhs和rhs的值相等，则返回false；否则返回true。
[noexcept] bool operator==(const QShader &lhs, const QShader &rhs)
如果两个QShader对象lhs和rhs相等，返回true，意味着它们是同一阶段且有匹配的着色器源或二进制代码集。
© 2024 The Qt Company Ltd. 本文档中包含的贡献文档的版权属于各自所有者。提供的文档是根据自由软件基金会发布的GNU自由文档许可证（版本1.3）的条款许可的。Qt及其相应标志在芬兰和/或其他国家/地区是The Qt Company Ltd. 的商标。商标。所有其他商标均为各自所有者所有。
