\inmodule QtGui More...

#include <qshader.h>

Collaboration diagram for QShader:

Classes
struct	NativeShaderInfo
	\inmodule QtGui More...
struct	SeparateToCombinedImageSamplerMapping
	\inmodule QtGui More...

Public Types
enum	Stage { VertexStage = 0 , TessellationControlStage , TessellationEvaluationStage , GeometryStage , FragmentStage , ComputeStage }
	Describes the stage of the graphics pipeline the shader is suitable for. More...
enum	Source { SpirvShader = 0 , GlslShader , HlslShader , DxbcShader , MslShader , DxilShader , MetalLibShader , WgslShader }
	Describes what kind of shader code an entry contains. More...
enum	Variant { StandardShader = 0 , BatchableVertexShader , UInt16IndexedVertexAsComputeShader , UInt32IndexedVertexAsComputeShader , NonIndexedVertexAsComputeShader , HdrCapableFragmentShader }
	Describes what kind of shader code an entry contains. More...
enum class	SerializedFormatVersion { Latest = 0 , Qt_6_5 , Qt_6_4 }
	Describes the desired output format when serializing the QShader. More...
using	NativeResourceBindingMap = QMap<int, std::pair<int, int>>
	Synonym for QMap<int, std::pair<int, int>>.
using	SeparateToCombinedImageSamplerMappingList = QList<SeparateToCombinedImageSamplerMapping>
	Synonym for QList<QShader::SeparateToCombinedImageSamplerMapping>.

Public Member Functions
	QShader ()
	Constructs a new, empty (and thus invalid) QShader instance.
	QShader (const QShader &other)
	Constructs a copy of other.
QShader &	operator= (const QShader &other)
	Assigns other to this object.
	QShader (QShader &&other) noexcept
	~QShader ()
	Destructor.
void	swap (QShader &other) noexcept
void	detach ()
bool	isValid () const
Stage	stage () const
void	setStage (Stage stage)
	Sets the pipeline stage.
QShaderDescription	description () const
void	setDescription (const QShaderDescription &desc)
	Sets the reflection metadata to desc.
QList< QShaderKey >	availableShaders () const
QShaderCode	shader (const QShaderKey &key) const
void	setShader (const QShaderKey &key, const QShaderCode &shader)
	Stores the source or binary shader code for a given shader version specified by key.
void	removeShader (const QShaderKey &key)
	Removes the source or binary shader code for a given key.
QByteArray	serialized (SerializedFormatVersion version=SerializedFormatVersion::Latest) const
NativeResourceBindingMap	nativeResourceBindingMap (const QShaderKey &key) const
void	setResourceBindingMap (const QShaderKey &key, const NativeResourceBindingMap &map)
	Stores the given native resource binding map associated with key.
void	removeResourceBindingMap (const QShaderKey &key)
	Removes the native resource binding map for key.
SeparateToCombinedImageSamplerMappingList	separateToCombinedImageSamplerMappingList (const QShaderKey &key) const
	\variable QShader::SeparateToCombinedImageSamplerMapping::combinedSamplerName
void	setSeparateToCombinedImageSamplerMappingList (const QShaderKey &key, const SeparateToCombinedImageSamplerMappingList &list)
	Stores the given combined image sampler mapping list associated with key.
void	removeSeparateToCombinedImageSamplerMappingList (const QShaderKey &key)
	Removes the combined image sampler mapping list for key.
NativeShaderInfo	nativeShaderInfo (const QShaderKey &key) const
	\variable QShader::NativeShaderInfo::flags
void	setNativeShaderInfo (const QShaderKey &key, const NativeShaderInfo &info)
	Stores the given native shader info associated with key.
void	removeNativeShaderInfo (const QShaderKey &key)
	Removes the native shader information for key.

Static Public Member Functions
static QShader	fromSerialized (const QByteArray &data)
	Creates a new QShader instance from the given data.

Friends
struct	QShaderPrivate
Q_GUI_EXPORT bool	operator== (const QShader &lhs, const QShader &rhs)
	Returns `true` if the two QShader objects lhs and rhs are equal, meaning they are for the same stage with matching sets of shader source or binary code.
Q_GUI_EXPORT size_t	qHash (const QShader &s, size_t seed=0)
Q_GUI_EXPORT QDebug	operator<< (QDebug dbg, const QShader &bs)

Related Symbols
(Note that these are not member symbols.)
bool	operator!= (const QShader &lhs, const QShader &rhs)
	Returns `false` if the values in the two QShader objects lhs and rhs are equal; otherwise returns `true`.

Detailed Description

\inmodule QtGui

Since: 6.6

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

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.

Warning: 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:

\list

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.

\endlist

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

\list

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.

\endlist

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)

\list

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

\endlist

See also: QShaderBaker

Definition at line 80 of file qshader.h.

Member Typedef Documentation

◆ NativeResourceBindingMap

using QShader::NativeResourceBindingMap = QMap<int, std::pair<int, int>>

Synonym for QMap<int, std::pair<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.

Note: 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.

Definition at line 144 of file qshader.h.

◆ SeparateToCombinedImageSamplerMappingList

using QShader::SeparateToCombinedImageSamplerMappingList = QList<SeparateToCombinedImageSamplerMapping>

Synonym for QList<QShader::SeparateToCombinedImageSamplerMapping>.

Definition at line 154 of file qshader.h.

Member Enumeration Documentation

◆ SerializedFormatVersion

enum class QShader::SerializedFormatVersion

strong

Describes the desired output format when serializing the QShader.

The default value for the version argument of serialized() is 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.

Note: 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.

\value Latest The current Qt version \value Qt_6_5 Qt 6.5 \value Qt_6_4 Qt 6.4

Enumerator
Latest
Qt_6_5
Qt_6_4

Definition at line 112 of file qshader.h.

◆ Source

enum QShader::Source

Describes what kind of shader code an entry contains.

\value SpirvShader SPIR-V \value GlslShader GLSL \value HlslShader HLSL \value DxbcShader Direct3D bytecode (HLSL compiled by fxc) \value MslShader Metal Shading Language \value DxilShader Direct3D bytecode (HLSL compiled by dxc) \value MetalLibShader Pre-compiled Metal bytecode \value WgslShader WGSL

Enumerator
SpirvShader
GlslShader
HlslShader
DxbcShader
MslShader
DxilShader
MetalLibShader
WgslShader

Definition at line 92 of file qshader.h.

◆ Stage

enum QShader::Stage

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

\value VertexStage Vertex shader \value TessellationControlStage Tessellation control (hull) shader \value TessellationEvaluationStage Tessellation evaluation (domain) shader \value GeometryStage Geometry shader \value FragmentStage Fragment (pixel) shader \value ComputeStage Compute shader

Enumerator
VertexStage
TessellationControlStage
TessellationEvaluationStage
GeometryStage
FragmentStage
ComputeStage

Definition at line 83 of file qshader.h.

◆ Variant

enum QShader::Variant

Describes what kind of shader code an entry contains.

\value StandardShader The normal, unmodified version of the shader code.

\value BatchableVertexShader Vertex shader rewritten to be suitable for Qt Quick scenegraph batching.

\value UInt16IndexedVertexAsComputeShader 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.

\value UInt32IndexedVertexAsComputeShader 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.

\value NonIndexedVertexAsComputeShader 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.

\value [since 6.10] HdrCapableFragmentShader A fragment shader rewritten to support high dynamic range rendering in a Qt Quick scenegraph.

Enumerator
StandardShader
BatchableVertexShader
UInt16IndexedVertexAsComputeShader
UInt32IndexedVertexAsComputeShader
NonIndexedVertexAsComputeShader
HdrCapableFragmentShader

Definition at line 103 of file qshader.h.

Constructor & Destructor Documentation

◆ QShader() [1/3]

QShader::QShader ( )

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

Definition at line 262 of file qshader.cpp.

◆ QShader() [2/3]

QShader::QShader ( const QShader & other )

Constructs a copy of other.

Definition at line 281 of file qshader.cpp.

◆ QShader() [3/3]

QShader::QShader ( QShader && other )

inlinenoexcept

Since: 6.7

Move-constructs a new QShader from other.

Note: The moved-from object other is placed in a partially-formed state, in which the only valid operations are destruction and assignment of a new value.

Definition at line 121 of file qshader.h.

◆ ~QShader()

QShader::~QShader ( )

Destructor.

Definition at line 333 of file qshader.cpp.

Member Function Documentation

◆ availableShaders()

QList< QShaderKey > QShader::availableShaders ( ) const

Returns: the list of available shader versions

Definition at line 392 of file qshader.cpp.

◆ description()

QShaderDescription QShader::description ( ) const

Returns: the reflection metadata for the shader.

Definition at line 375 of file qshader.cpp.

◆ detach()

void QShader::detach ( )

Definition at line 270 of file qshader.cpp.

◆ fromSerialized()

QShader QShader::fromSerialized ( const QByteArray & data )

static

Creates a new QShader instance from the given data.

If data cannot be deserialized successfully, the result is a default constructed QShader for which isValid() returns false.

Warning: Shader packages, including {.qsb} files in the filesystem, are assumed to be trusted content. Application developers are advised to carefully consider the potential implications before allowing the loading of user-provided content that is not part of the application.

See also: serialized()

Definition at line 550 of file qshader.cpp.

◆ isValid()

bool QShader::isValid ( ) const

Returns: true if the QShader contains at least one shader version.

Definition at line 348 of file qshader.cpp.

◆ nativeResourceBindingMap()

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).

Definition at line 1031 of file qshader.cpp.

◆ nativeShaderInfo()

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

\variable QShader::NativeShaderInfo::flags

\variable QShader::NativeShaderInfo::extraBufferBindings

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.

Definition at line 1189 of file qshader.cpp.

◆ operator=()

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

Assigns other to this object.

Since: 6.7

Move-assigns other to this QShader instance.

Note: The moved-from object other is placed in a partially-formed state, in which the only valid operations are destruction and assignment of a new value.

Definition at line 291 of file qshader.cpp.

◆ removeNativeShaderInfo()

void QShader::removeNativeShaderInfo ( const QShaderKey & key )

Removes the native shader information for key.

Definition at line 1215 of file qshader.cpp.

◆ removeResourceBindingMap()

void QShader::removeResourceBindingMap ( const QShaderKey & key )

Removes the native resource binding map for key.

Definition at line 1057 of file qshader.cpp.

◆ removeSeparateToCombinedImageSamplerMappingList()

void QShader::removeSeparateToCombinedImageSamplerMappingList ( const QShaderKey & key )

Removes the combined image sampler mapping list for key.

Definition at line 1138 of file qshader.cpp.

◆ removeShader()

void QShader::removeShader ( const QShaderKey & key )

Removes the source or binary shader code for a given key.

Does nothing when not found.

Definition at line 421 of file qshader.cpp.

◆ separateToCombinedImageSamplerMappingList()

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

\variable QShader::SeparateToCombinedImageSamplerMapping::combinedSamplerName

\variable QShader::SeparateToCombinedImageSamplerMapping::textureBinding

\variable QShader::SeparateToCombinedImageSamplerMapping::samplerBinding

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.

Definition at line 1111 of file qshader.cpp.

◆ serialized()

QByteArray QShader::serialized ( 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, \l{SerializedFormatVersion}{Qt_6_5} for Qt 6.5) be used.

See also: fromSerialized()

Definition at line 455 of file qshader.cpp.

◆ setDescription()

void QShader::setDescription ( const QShaderDescription & desc )

Sets the reflection metadata to desc.

Definition at line 383 of file qshader.cpp.

◆ setNativeShaderInfo()

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

Stores the given native shader info associated with key.

See also: nativeShaderInfo()

Definition at line 1206 of file qshader.cpp.

◆ setResourceBindingMap()

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

Stores the given native resource binding map associated with key.

See also: nativeResourceBindingMap()

Definition at line 1048 of file qshader.cpp.

◆ setSeparateToCombinedImageSamplerMappingList()

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

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

See also: separateToCombinedImageSamplerMappingList()

Definition at line 1128 of file qshader.cpp.

◆ setShader()

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

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

Definition at line 408 of file qshader.cpp.

◆ setStage()

void QShader::setStage ( Stage stage )

Sets the pipeline stage.

Definition at line 364 of file qshader.cpp.

◆ shader()

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

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

Definition at line 400 of file qshader.cpp.

◆ stage()

QShader::Stage QShader::stage ( ) const

Returns: the pipeline stage the shader is meant for.

Definition at line 356 of file qshader.cpp.

◆ swap()

void QShader::swap ( QShader & other )

inlinenoexcept

Since: 6.7 \memberswap{shader}

Definition at line 125 of file qshader.h.

◆ operator!=()

bool operator!=	(	const QShader &	lhs,
		const QShader &	rhs )

Returns false if the values in the two QShader objects lhs and rhs are equal; otherwise returns true.

Definition at line 206 of file qshader.h.

◆ operator<<

Q_GUI_EXPORT QDebug operator<<	(	QDebug	dbg,
		const QShader &	bs )

friend

Definition at line 956 of file qshader.cpp.

◆ operator==

bool operator==	(	const QShader &	lhs,
		const QShader &	rhs )

friend

Returns true if the two QShader objects lhs and rhs are equal, meaning they are for the same stage with matching sets of shader source or binary code.

Definition at line 789 of file qshader.cpp.

◆ qHash

Q_GUI_EXPORT size_t qHash	(	const QShader &	s,
		size_t	seed = 0 )

friend

Definition at line 812 of file qshader.cpp.

◆ QShaderPrivate

friend struct QShaderPrivate

friend

Definition at line 170 of file qshader.h.

The documentation for this class was generated from the following files:

qtbase/src/gui/rhi/qshader.h (0b7b02cdb43a4d9a29eba5804b82461bed70a86c)
qtbase/src/gui/rhi/qshader.cpp (4b4e77a0869ce00c96acfc209cd827b39ffac7b0)

Classes

Public Types

Public Member Functions

Static Public Member Functions

Friends

Related Symbols

Detailed Description

Member Typedef Documentation

◆ NativeResourceBindingMap

◆ SeparateToCombinedImageSamplerMappingList

Member Enumeration Documentation

◆ SerializedFormatVersion

◆ Source

◆ Stage

◆ Variant

Constructor & Destructor Documentation

◆ QShader() [1/3]

◆ QShader() [2/3]

◆ QShader() [3/3]

◆ ~QShader()

Member Function Documentation

◆ availableShaders()

◆ description()

◆ detach()

◆ fromSerialized()

◆ isValid()

◆ nativeResourceBindingMap()

◆ nativeShaderInfo()

◆ operator=()

◆ removeNativeShaderInfo()

◆ removeResourceBindingMap()

◆ removeSeparateToCombinedImageSamplerMappingList()

◆ removeShader()

◆ separateToCombinedImageSamplerMappingList()

◆ serialized()

◆ setDescription()

◆ setNativeShaderInfo()

◆ setResourceBindingMap()

◆ setSeparateToCombinedImageSamplerMappingList()

◆ setShader()

◆ setStage()

◆ shader()

◆ stage()

◆ swap()

Friends And Related Symbol Documentation

◆ operator!=()

◆ operator<<

◆ operator==

◆ qHash

◆ QShaderPrivate