PySide6.QtGui.QShader¶

class QShader¶

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

Details

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:

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

See also

QShaderBaker

Added in version 6.6.

Synopsis¶

Methods¶

def __init__()
def availableShaders()
def isValid()
def nativeResourceBindingMap()
def __ne__()
def __eq__()
def removeNativeShaderInfo()
def removeResourceBindingMap()
def removeSeparateToCombinedImageSamplerMappingList()
def removeShader()
def serialized()
def setResourceBindingMap()
def setShader()
def setStage()
def shader()
def stage()
def swap()

Static functions¶

def fromSerialized()

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

class Stage¶

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

Constant

Description

QShader.VertexStage

Vertex shader

QShader.TessellationControlStage

Tessellation control (hull) shader

QShader.TessellationEvaluationStage

Tessellation evaluation (domain) shader

QShader.GeometryStage

Geometry shader

QShader.FragmentStage

Fragment (pixel) shader

QShader.ComputeStage

Compute shader

Constant	Description
QShader.VertexStage	Vertex shader
QShader.TessellationControlStage	Tessellation control (hull) shader
QShader.TessellationEvaluationStage	Tessellation evaluation (domain) shader
QShader.GeometryStage	Geometry shader
QShader.FragmentStage	Fragment (pixel) shader
QShader.ComputeStage	Compute shader

class Source¶

Describes what kind of shader code an entry contains.

Constant

Description

QShader.SpirvShader

SPIR-V

QShader.GlslShader

GLSL

QShader.HlslShader

HLSL

QShader.DxbcShader

Direct3D bytecode (HLSL compiled by fxc)

QShader.MslShader

Metal Shading Language

QShader.DxilShader

Direct3D bytecode (HLSL compiled by dxc)

QShader.MetalLibShader

Pre-compiled Metal bytecode

QShader.WgslShader

WGSL

Constant	Description
QShader.SpirvShader	SPIR-V
QShader.GlslShader	GLSL
QShader.HlslShader	HLSL
QShader.DxbcShader	Direct3D bytecode (HLSL compiled by `fxc`)
QShader.MslShader	Metal Shading Language
QShader.DxilShader	Direct3D bytecode (HLSL compiled by `dxc`)
QShader.MetalLibShader	Pre-compiled Metal bytecode
QShader.WgslShader	WGSL

class Variant¶

Describes what kind of shader code an entry contains.

Constant

Description

QShader.StandardShader

The normal, unmodified version of the shader code.

QShader.BatchableVertexShader

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

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

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

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

QShader.HdrCapableFragmentShader

A fragment shader rewritten to support high dynamic range rendering in a Qt Quick scenegraph.

Constant	Description
QShader.StandardShader	The normal, unmodified version of the shader code.
QShader.BatchableVertexShader	Vertex shader rewritten to be suitable for Qt Quick scenegraph batching.
QShader.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.
QShader.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.
QShader.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.
QShader.HdrCapableFragmentShader	A fragment shader rewritten to support high dynamic range rendering in a Qt Quick scenegraph.

class SerializedFormatVersion¶

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.

Constant	Description
QShader.SerializedFormatVersion.Latest	The current Qt version
QShader.SerializedFormatVersion.Qt_6_5	Qt 6.5
QShader.SerializedFormatVersion.Qt_6_4	Qt 6.4

__init__()¶

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

__init__(other)

Parameters:: other – QShader

Constructs a copy of other.

availableShaders()¶

Return type:: .list of QShaderKey

Returns the list of available shader versions

static fromSerialized(data)¶

Parameters:: data – QByteArray
Return type:: QShader

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.