本页内容

QShader Class

包含一个着色器的多个版本,这些版本已被翻译成多种着色语言,并附有反射元数据。更多内容...

标题: #include <qshader.h>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui
自: Qt 6.6

公共类型

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, HdrCapableFragmentShader }

公共函数

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)

详细说明

在与图形 API 无关的 Qt 环境中,QShader 是着色器代码的入口点。 与 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 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 以外的图形 API 可能采用与之不完全兼容的资源绑定模型。从 SPIR-V 翻译而来的着色器代码生成器可能会出于各种原因,选择不考虑 SPIR-V 绑定限定符。例如,SPIRV-Cross 的 Metal 后端便是如此。 此外,即使在大多数情况下可以进行自动的隐式转换(例如,将 SPIR-V 绑定点用作 HLSL 资源寄存器索引),但不受 SPIR-V 绑定点限制地分配资源绑定往往能获得更好的结果。

因此,QShader 可能提供一个额外的映射,用于描述给定SPIR-V绑定的本机绑定点。 与此相关的QRhi 后端应酌情自动使用此映射。该值是一个元组,因为在某些着色语言中,组合图像采样器可能会映射到两个本机资源(一个纹理和一个采样器)。在这种情况下,第二个值指的是采样器。

注意: 如果着色器中该资源没有有效的绑定,则本机绑定值 可能为 -1。 (例如,声明了一个uniform块,但在着色器代码中未被使用)该映射始终是完整的,这意味着所有声明的uniform块、存储块、图像对象和组合采样器都有对应的条目,但对于那些在着色器函数中实际上未被引用的条目,其值将为-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::Latest0当前的 Qt 版本
QShader::SerializedFormatVersion::Qt_6_51Qt 6.5
QShader::SerializedFormatVersion::Qt_6_42Qt 6.4

enum QShader::Source

描述参赛作品包含何种着色器代码。

常量值描述
QShader::SpirvShader0SPIR-V
QShader::GlslShader1GLSL
QShader::HlslShader2HLSL
QShader::DxbcShader3Direct3D 字节码(由fxc 编译的 HLSL)
QShader::MslShader4Metal着色语言
QShader::DxilShader5Direct3D 字节码(由dxc 编译的 HLSL)
QShader::MetalLibShader6预编译的 Metal 字节码
QShader::WgslShader7WGSL

enum QShader::Stage

描述了该着色器适用于图形处理管道的哪个阶段。

常量值描述
QShader::VertexStage0顶点着色器
QShader::TessellationControlStage1细分控制(外壳)着色器
QShader::TessellationEvaluationStage2细分评估(域)着色器
QShader::GeometryStage3几何着色器
QShader::FragmentStage4片段(像素)着色器
QShader::ComputeStage5计算着色器

enum QShader::Variant

描述参赛作品包含何种着色器代码。

常量值描述
QShader::StandardShader0未修改的原始着色器代码。
QShader::BatchableVertexShader1为适应Qt Quick 场景图批处理而重写的顶点着色器。
QShader::UInt16IndexedVertexAsComputeShader2一款专为在 Metal 管道中配合细分技术使用的顶点着色器,该着色器需与从 uint16 索引缓冲区获取索引数据的索引绘制调用结合使用。 为了支持 Metal 细分管道,顶点着色器被转换为计算着色器,该计算着色器可能依赖于绘制调用中索引缓冲区的使用情况(例如,如果着色器使用 gl_VertexIndex),因此需要三个专门的变体。
QShader::UInt32IndexedVertexAsComputeShader3一个顶点着色器,旨在用于包含曲面细分且结合了从 uint32 索引缓冲区获取索引数据的索引绘制调用的 Metal 管道中。 为了支持 Metal 细分管道,顶点着色器会被转换为计算着色器,该计算着色器可能取决于绘制调用中索引缓冲区的使用情况(例如,如果着色器使用 gl_VertexIndex),因此需要三个专用变体。
QShader::NonIndexedVertexAsComputeShader4一种顶点着色器,旨在用于包含曲面细分且结合非索引绘制调用的 Metal 管道。 为了支持 Metal 细分管道,顶点着色器被转换为计算着色器,该着色器可能取决于绘制调用中索引缓冲区的使用情况(例如,如果着色器使用 gl_VertexIndex),因此需要三个专门的变体。
QShader::HdrCapableFragmentShader (since Qt 6.10)5一个经过重写以支持在Qt Quick 场景图中进行高动态范围渲染的片段着色器。

成员函数文档

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 。

警告:着色器 包(包括文件系统中的.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设备。

默认情况下使用最新的序列化格式。若需针对特定兼容性版本的 Qt 进行序列化,请使用 `version ` 参数。 仅当已知生成的数据流必须与较旧的 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 实例。

注意: 被移出的对象 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 。

© 2026 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.