QShader Class
包含翻译成多种着色语言的着色器的多个版本，以及反射元数据。更多
| 头文件： | #include <QShader> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Gui)target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake： | QT += gui |
| 自 | Qt 6.6 |
- 所有成员（包括继承成员）的列表
- QShader 是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 stage) |
| QShaderCode | shader(const QShaderKey &key) const |
| QShader::Stage | stage() const |
(since 6.7) void | swap(QShader &other) |
(since 6.7) QShader & | operator=(QShader &&other) |
| QShader & | operator=(const QShader &other) |
静态公共成员
| QShader | fromSerialized(const QByteArray &data) |
相关非成员
| size_t | qHash(const QShader &key, size_t seed = 0) |
| bool | operator!=(const QShader &lhs, const QShader &rhs) |
| bool | operator==(const QShader &lhs, const QShader &rhs) |
详细说明
QShader 是图形 API 无关的 Qt 世界中着色器代码的入口。与 Qt 5.x 习惯使用的 GLSL 着色器源不同，带有多个图形 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 渲染硬件接口（Qt Rendering Hardware Interface）及其类（如QRhiGraphicsPipeline ）一起使用时，应用程序无需进一步操作，因为只要需要为图形流水线的特定阶段指定着色器，这些类就会准备好消耗 QShader。
或者，应用程序可以访问
- QShader 中包含的任何着色语言版本的源代码或字节码、
- 着色器入口点的名称、
- 包含着色器输入、输出和统一块等资源描述的反射元数据。当应用程序或框架由于事先不知道顶点属性或着色器使用的统一缓冲区布局而需要在运行时发现着色器的输入时，这一点至关重要。
QShader 并不假定用于生成各种版本和变体的着色语言的来源。
QShader 与许多 Qt Core 类型类似使用隐式共享，因此可以通过值返回或传递。在调用设置器时，会隐式地发生分离。
作为参考，一个典型的、可移植的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 着色模型 5.0 源代码或相应的 DXBC 字节代码
- 适用于 Metal 1.2 或更新版本的 Metal 着色语言 1.2 源代码或相应的字节码
另请参见 QShaderBaker 。
成员类型文档
[alias] QShader::NativeResourceBindingMap
QMap<int, std::pair<int,int>>的同义词。
QRhi 假设的资源绑定模型基于 SPIR-V。这意味着统一缓冲区、存储缓冲区、组合图像采样器和存储图像共享一个共同的绑定点空间。QShaderDescription 和QRhiShaderResourceBinding 中的绑定编号应与兼容 Vulkan 的 GLSL 着色器中的binding 布局限定符相匹配。
Vulkan 以外的图形应用程序接口可能使用与此不完全兼容的资源绑定模型。由于各种原因，从 SPIR-V 翻译而来的着色器代码生成器可能会选择不考虑 SPIR-V 绑定限定符。例如，SPIRV-Cross 的 Metal 后端就属于这种情况。此外，即使在大多数情况下可以进行自动隐式翻译（例如，将 SPIR-V 绑定点用作 HLSL 资源寄存器索引），在分配资源绑定时不受 SPIR-V 绑定点的限制也能获得更好的结果。
因此，QShader 可以公开一个额外的映射，描述特定 SPIR-V 绑定点的本地绑定点。与此相关的QRhi 后端应根据情况自动使用该映射。该值是一对，因为在某些着色语言中，组合图像采样器可能会映射到两个本地资源（纹理和采样器）。在这种情况下，第二个值指的是采样器。
注意： 如果着色器中的资源没有活动绑定，则原生绑定值可能为-1。(该映射总是完整的，这意味着所有已声明的统一块、存储块、图像对象和组合采样器都有一个条目，但对于着色器函数中未实际引用的资源，其值将为-1。
[alias] QShader::SeparateToCombinedImageSamplerMappingList
QList<QShader::SeparateToCombinedImageSamplerMapping> 的同义词。
enum class QShader::SerializedFormatVersion
描述QShader 序列化时所需的输出格式。
serialized() 的version 参数默认值为Latest 。这在绝大多数情况下已经足够。只有当希望生成的序列化数据能被早期 Qt 版本加载时，才需要指定其他值。例如，当给出--qsbversion 命令行参数时，qsb 工具会使用这些枚举值。
注意： 以早期版本为目标会使生成资产的某些功能失效。在指定的旧 Qt 版本中使用该资产时，这并不是一个问题，因为该 Qt 版本不具备较新 Qt 版本中依赖QShader 和序列化数据流中生成的额外数据的较新功能，但如果在较新 Qt 版本中使用生成的资产，这可能会成为一个问题。
| 常量 | 值 | 说明 |
|---|---|---|
QShader::SerializedFormatVersion::Latest | 0 | 当前 Qt 版本 |
QShader::SerializedFormatVersion::Qt_6_5 | 1 | Qt 6.5 |
QShader::SerializedFormatVersion::Qt_6_4 | 2 | Qt 6.4 |
enum QShader::Source
描述条目包含的着色器代码类型。
| 常量 | 值 | 描述 |
|---|---|---|
QShader::SpirvShader | 0 | SPIR-V |
QShader::GlslShader | 1 | GLSL |
QShader::HlslShader | 2 | HLSL |
QShader::DxbcShader | 3 | Direct3D 字节码（HLSL 由fxc 编译 ) |
QShader::MslShader | 4 | 金属着色语言 |
QShader::DxilShader | 5 | Direct3D 字节码（HLSL 编译：dxc) |
QShader::MetalLibShader | 6 | 预编译的金属字节码 |
QShader::WgslShader | 7 | WGSL |
enum QShader::Stage
描述着色器适用于图形流水线的哪个阶段。
| 常量 | 值 | 描述 |
|---|---|---|
QShader::VertexStage | 0 | 顶点着色器 |
QShader::TessellationControlStage | 1 | 细分控制（体）着色器 |
QShader::TessellationEvaluationStage | 2 | 细分评估（域）着色器 |
QShader::GeometryStage | 3 | 几何着色器 |
QShader::FragmentStage | 4 | 片段（像素）着色器 |
QShader::ComputeStage | 5 | 计算着色器 |
enum QShader::Variant
描述条目包含的着色器代码类型。
| 常量 | 值 | 描述 |
|---|---|---|
QShader::StandardShader | 0 | 着色器代码的正常、未修改版本。 |
QShader::BatchableVertexShader | 1 | 顶点着色器已重写，适用于Qt Quick 场景图批处理。 |
QShader::UInt16IndexedVertexAsComputeShader | 2 | 顶点着色器可用于具有细分功能的 Metal 管道，并结合从 uint16 索引缓冲区获取索引数据的索引绘制调用。为支持 Metal 细分流水线，顶点着色器被转换为计算着色器，而计算着色器可能取决于绘制调用中索引缓冲区的使用情况（例如，如果着色器使用 gl_VertexIndex），因此需要三个专用变体。 |
QShader::UInt32IndexedVertexAsComputeShader | 3 | 顶点着色器，用于在 Metal 管道中结合细分和索引绘制调用使用，索引数据来自 uint32 索引缓冲区。为支持 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。
注意： moved-from 对象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 。
警告： 着色器包（包括文件系统中的.qsb 文件）被假定为可信内容。建议应用程序开发人员在允许加载非应用程序一部分的用户提供内容之前，仔细考虑其潜在影响。
另请参阅 serialized().
bool QShader::isValid() const
如果QShader 至少包含一个着色器版本，则返回 true。
QShader::NativeResourceBindingMap QShader::nativeResourceBindingMap(const QShaderKey &key) const
返回key 的本地绑定映射。如果key 没有映射，则映射为空（例如，因为映射不适用于key 所描述的 API 和着色语言）。
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
返回QShader 保存的所有数据的序列化二进制版本，适合写入文件或其他 I/O 设备。
默认情况下使用最新的序列化格式。使用version 参数可为兼容的 Qt XML 版本进行序列化。只有当知道生成的数据流必须与较旧的 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)
存储key 指定的着色器版本的源代码或二进制shader 代码。
另请参阅 shader() 。
void QShader::setStage(QShader::Stage stage)
设置管道stage 。
另请参见 stage() 。
QShaderCode QShader::shader(const QShaderKey &key) const
返回key 指定的着色器版本的源代码或二进制代码。
另请参见 setShader() 。
QShader::Stage QShader::stage() const
返回着色器的流水线阶段。
另请参阅 setStage().
[noexcept, since 6.7] void QShader::swap(QShader &other)
将此着色器与other 互换。此操作速度非常快，而且从未出现过故障。
此功能在 Qt 6.7 中引入。
[noexcept, since 6.7] QShader &QShader::operator=(QShader &&other)
移动--将other 赋值给此QShader 实例。
注意： moved-from 对象other 处于部分形成状态，在这种状态下，唯一有效的操作是销毁和赋新值。
此函数在 Qt 6.7 中引入。
QShader &QShader::operator=(const QShader &other)
为该对象指定other 。
相关非会员
[noexcept] size_t qHash(const QShader &key, size_t seed = 0)
返回key 的哈希值，使用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 ，这意味着它们属于同一阶段，着色器源代码或二进制代码集匹配。
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
