QShader Class

Contains multiple versions of a shader translated to multiple shading languages, together with reflection metadata. 更多...

头：	#include <QShader>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake:	QT += gui
Since:	Qt 6.6

所有成员列表，包括继承成员
QShader is part of 3D 渲染 .

公共类型

struct	NativeShaderInfo
struct	SeparateToCombinedImageSamplerMapping
	NativeResourceBindingMap
	SeparateToCombinedImageSamplerMappingList
enum class	SerializedFormatVersion { Latest, Qt_6_5, Qt_6_4 }
enum	源 { 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 )
	~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
QShader &	operator= (const QShader & other )

静态公共成员

QShader

fromSerialized (const QByteArray & data )

size_t	qHash (const QShader & s , size_t seed = 0)
bool	operator!= (const QShader & lhs , const QShader & rhs )
bool	operator== (const QShader & lhs , const QShader & rhs )

详细描述

QShader is the entry point to shader code in the graphics API agnostic Qt world. Instead of using GLSL shader sources, as was the custom with Qt 5.x, new graphics systems with backends for multiple graphics APIs, such as, Vulkan, Metal, Direct3D, and OpenGL, take QShader as their input whenever a shader needs to be specified.

警告： 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/qshader.h> .

A QShader instance is empty and thus invalid by default. To get a useful instance, the two typical methods are:

Generate the contents offline, during build time or earlier, using the qsb command line tool. The result is a binary file that is shipped with the application, read via QIODevice::readAll (), and then deserialized via fromSerialized (). For more information, see QShaderBaker .
Generate at run time via QShaderBaker . This is an expensive operation, but allows applications to use user-provided or dynamically generated shader source strings.

When used together with the Qt Rendering Hardware Interface and its classes, like QRhiGraphicsPipeline , no further action is needed from the application's side as these classes are prepared to consume a QShader whenever a shader needs to be specified for a given stage of the graphics pipeline.

Alternatively, applications can access

the source or byte code for any of the shading language versions that are included in the QShader,
the name of the entry point for the shader,
the reflection metadata containing a description of the shader's inputs, outputs and resources like uniform blocks. This is essential when an application or framework needs to discover the inputs of a shader at runtime due to not having advance knowledge of the vertex attributes or the layout of the uniform buffers used by the shader.

QShader makes no assumption about the shading language that was used as the source for generating the various versions and variants that are included in it.

QShader uses implicit sharing similarly to many core Qt types, and so can be returned or passed by value. Detach happens implicitly when calling a setter.

For reference, a typical, portable QRhi expects that a QShader suitable for all its backends contains at least the following. (this excludes support for core profile OpenGL contexts, add GLSL 150 or newer for that)

SPIR-V 1.0 bytecode suitable for Vulkan 1.0 or newer
GLSL/ES 100 source code suitable for OpenGL ES 2.0 or newer
GLSL 120 source code suitable for OpenGL 2.1 or newer
HLSL Shader Model 5.0 source code or the corresponding DXBC bytecode suitable for Direct3D 11/12
Metal Shading Language 1.2 source code or the corresponding bytecode suitable for Metal 1.2 or newer

另请参阅 QShaderBaker .

成员类型文档编制

`[alias]` QShader:: NativeResourceBindingMap

同义词 QMap <int, QPair <int, int>>.

The resource binding model QRhi assumes is based on SPIR-V. This means that uniform buffers, storage buffers, combined image samplers, and storage images share a common binding point space. The binding numbers in QShaderDescription and QRhiShaderResourceBinding are expected to match the binding layout qualifier in the Vulkan-compatible GLSL shader.

Graphics APIs other than Vulkan may use a resource binding model that is not fully compatible with this. The generator of the shader code translated from SPIR-V may choose not to take the SPIR-V binding qualifiers into account, for various reasons. This is the case with the Metal backend of SPIRV-Cross, for example. In addition, even when an automatic, implicit translation is mostly possible (e.g. by using SPIR-V binding points as HLSL resource register indices), assigning resource bindings without being constrained by the SPIR-V binding points can lead to better results.

Therefore, a QShader may expose an additional map that describes what the native binding point for a given SPIR-V binding is. The QRhi backends, for which this is relevant, are expected to use this map automatically, as appropriate. The value is a pair, because combined image samplers may map to two native resources (a texture and a sampler) in some shading languages. In that case the second value refers to the sampler.

注意： The native binding may be -1, in case there is no active binding for the resource in the shader. (for example, there is a uniform block declared, but it is not used in the shader code) The map is always complete, meaning there is an entry for all declared uniform blocks, storage blocks, image objects, and combined samplers, but the value will be -1 for those that are not actually referenced in the shader functions.

`[alias]` QShader:: SeparateToCombinedImageSamplerMappingList

同义词 QList < QShader::SeparateToCombinedImageSamplerMapping >.

enum class QShader:: SerializedFormatVersion

Describes the desired output format when serializing the QShader .

The default value for the version argument of serialized () 是 Latest . This is sufficient in the vast majority of cases. Specifying another value is needed only when the intention is to generate serialized data that can be loaded by earlier Qt versions. For example, the qsb tool uses these enum values when the --qsbversion command-line argument is given.

注意： Targeting earlier versions will make certain features disfunctional with the generated asset. This is not an issue when using the asset with the specified, older Qt version, given that that Qt version does not have the newer features in newer Qt versions that rely on additional data generated in the QShader and the serialized data stream, but may become a problem if the generated asset is then used with a newer Qt version.

常量	值	描述
`QShader::SerializedFormatVersion::Latest`	`0`	The current Qt version
`QShader::SerializedFormatVersion::Qt_6_5`	`1`	Qt 6.5
`QShader::SerializedFormatVersion::Qt_6_4`	`2`	Qt 6.4

enum QShader:: 源

Describes what kind of shader code an entry contains.

常量	值	描述
`QShader::SpirvShader`	`0`	SPIR-V
`QShader::GlslShader`	`1`	GLSL
`QShader::HlslShader`	`2`	HLSL
`QShader::DxbcShader`	`3`	Direct3D bytecode (HLSL compiled by `fxc` )
`QShader::MslShader`	`4`	Metal Shading Language
`QShader::DxilShader`	`5`	Direct3D bytecode (HLSL compiled by `dxc` )
`QShader::MetalLibShader`	`6`	Pre-compiled Metal bytecode
`QShader::WgslShader`	`7`	WGSL

enum QShader:: Stage

Describes the stage of the graphics pipeline the shader is suitable for.

常量	值	描述
`QShader::VertexStage`	`0`	Vertex shader
`QShader::TessellationControlStage`	`1`	Tessellation control (hull) shader
`QShader::TessellationEvaluationStage`	`2`	Tessellation evaluation (domain) shader
`QShader::GeometryStage`	`3`	Geometry shader
`QShader::FragmentStage`	`4`	Fragment (pixel) shader
`QShader::ComputeStage`	`5`	Compute shader

enum QShader:: Variant

Describes what kind of shader code an entry contains.

常量	值	描述
`QShader::StandardShader`	`0`	The normal, unmodified version of the shader code.
`QShader::BatchableVertexShader`	`1`	Vertex shader rewritten to be suitable for Qt Quick scenegraph batching.
`QShader::UInt16IndexedVertexAsComputeShader`	`2`	A vertex shader meant to be used in a Metal pipeline with tessellation in combination with indexed draw calls sourcing index data from a uint16 index buffer. To support the Metal tessellation pipeline, the vertex shader is translated to a compute shader that may be dependent on the index buffer usage in the draw calls (e.g. if the shader is using gl_VertexIndex), hence the need for three dedicated variants.
`QShader::UInt32IndexedVertexAsComputeShader`	`3`	A vertex shader meant to be used in a Metal pipeline with tessellation in combination with indexed draw calls sourcing index data from a uint32 index buffer. To support the Metal tessellation pipeline, the vertex shader is translated to a compute shader that may be dependent on the index buffer usage in the draw calls (e.g. if the shader is using gl_VertexIndex), hence the need for three dedicated variants.
`QShader::NonIndexedVertexAsComputeShader`	`4`	A vertex shader meant to be used in a Metal pipeline with tessellation in combination with non-indexed draw calls. To support the Metal tessellation pipeline, the vertex shader is translated to a compute shader that may be dependent on the index buffer usage in the draw calls (e.g. if the shader is using gl_VertexIndex), hence the need for three dedicated variants.

成员函数文档编制

QShader:: QShader ()

Constructs a new, empty (and thus invalid) QShader instance.

QShader:: QShader (const QShader & other )

构造副本为 other .

`[noexcept]` QShader:: ~QShader ()

析构函数。

QList < QShaderKey > QShader:: availableShaders () const

Returns the list of available shader versions

QShaderDescription QShader:: description () const

Returns the reflection metadata for the shader.

另请参阅 setDescription ().

`[static]` QShader QShader:: fromSerialized (const QByteArray & data )

创建新的 QShader instance from the given data .

若 data cannot be deserialized successfully, the result is a default constructed QShader 其中 isValid () 返回 false .

另请参阅 serialized ().

bool QShader:: isValid () const

返回 true 若 QShader contains at least one shader version.

QShader::NativeResourceBindingMap QShader:: nativeResourceBindingMap (const QShaderKey & key ) const

Returns the native binding map for key . The map is empty if no mapping is available for key (for example, because the map is not applicable for the API and shading language described by key ).

QShader::NativeShaderInfo QShader:: nativeShaderInfo (const QShaderKey & key ) const

Returns the native shader info struct for key , or an empty object if there is no data available for key , for example because such a mapping is not applicable for the shading language or the shader stage.

另请参阅 setNativeShaderInfo ().

void QShader:: removeNativeShaderInfo (const QShaderKey & key )

Removes the native shader information for key .

void QShader:: removeResourceBindingMap (const QShaderKey & key )

Removes the native resource binding map for key .

void QShader:: removeSeparateToCombinedImageSamplerMappingList (const QShaderKey & key )

Removes the combined image sampler mapping list for key .

void QShader:: removeShader (const QShaderKey & key )

Removes the source or binary shader code for a given key . Does nothing when not found.

QShader::SeparateToCombinedImageSamplerMappingList QShader:: separateToCombinedImageSamplerMappingList (const QShaderKey & key ) const

Returns the combined image sampler mapping list for key , or an empty list if there is no data available for key , for example because such a mapping is not applicable for the shading language.

另请参阅 setSeparateToCombinedImageSamplerMappingList ().

QByteArray QShader:: serialized ( QShader::SerializedFormatVersion version = SerializedFormatVersion::Latest) const

Returns a serialized binary version of all the data held by the QShader , suitable for writing to files or other I/O devices.

By default the latest serialization format is used. Use version parameter to serialize for a compatibility Qt version. Only when it is known that the generated data stream must be made compatible with an older Qt version at the expense of making it incompatible with features introduced since that Qt version, should another value (for example, Qt_6_5 for Qt 6.5) be used.

另请参阅 fromSerialized ().

void QShader:: setDescription (const QShaderDescription & desc )

Sets the reflection metadata to desc .

另请参阅 description ().

void QShader:: setNativeShaderInfo (const QShaderKey & key , const QShader::NativeShaderInfo & info )

Stores the given native shader info associated with key .

另请参阅 nativeShaderInfo ().

void QShader:: setResourceBindingMap (const QShaderKey & key , const QShader::NativeResourceBindingMap & map )

Stores the given native resource binding map associated with key .

另请参阅 nativeResourceBindingMap ().

void QShader:: setSeparateToCombinedImageSamplerMappingList (const QShaderKey & key , const QShader::SeparateToCombinedImageSamplerMappingList & list )

Stores the given combined image sampler mapping list associated with key .

另请参阅 separateToCombinedImageSamplerMappingList ().

void QShader:: setShader (const QShaderKey & key , const QShaderCode & shader )

Stores the source or binary shader code for a given shader version specified by key .

另请参阅 shader ().

void QShader:: setStage ( QShader::Stage stage )

Sets the pipeline stage .

另请参阅 stage ().

QShaderCode QShader:: shader (const QShaderKey & key ) const

Returns the source or binary code for a given shader version specified by key .

另请参阅 setShader ().

QShader::Stage QShader:: stage () const

Returns the pipeline stage the shader is meant for.

另请参阅 setStage ().

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

赋值 other 到此对象。