Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
|
\inmodule QtGui More...
#include <qshader.h>
Classes | |
struct | NativeShaderInfo |
\inmodule QtGui More... | |
struct | SeparateToCombinedImageSamplerMapping |
\inmodule QtGui More... | |
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 &, const QShader &) noexcept |
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 &, size_t) noexcept |
Returns the hash value for s, using seed to seed the calculation. | |
Q_GUI_EXPORT QDebug | operator<< (QDebug, const QShader &) |
Related Symbols | |
(Note that these are not member symbols.) | |
bool | operator== (const QShader &lhs, const QShader &rhs) noexcept |
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. | |
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 . | |
size_t | qHash (const QShader &s, size_t seed) noexcept |
Returns the hash value for s, using seed to seed the calculation. | |
\inmodule QtGui
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.
{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
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.\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
\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
\endlist
QShader::NativeResourceBindingMap = QMap<int, QPair<int, int> > |
Synonym for 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.
|
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.
\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 |
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 |
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 |
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.
Enumerator | |
---|---|
StandardShader | |
BatchableVertexShader | |
UInt16IndexedVertexAsComputeShader | |
UInt32IndexedVertexAsComputeShader | |
NonIndexedVertexAsComputeShader |
QShader::QShader | ( | ) |
Constructs a new, empty (and thus invalid) QShader instance.
Definition at line 255 of file qshader.cpp.
Referenced by fromSerialized().
QShader::QShader | ( | const QShader & | other | ) |
Constructs a copy of other.
Definition at line 274 of file qshader.cpp.
References QBasicAtomicInteger< T >::ref(), and QShaderPrivate::ref.
|
inlinenoexcept |
QShader::~QShader | ( | ) |
Destructor.
Definition at line 326 of file qshader.cpp.
References QBasicAtomicInteger< T >::deref(), and QShaderPrivate::ref.
QList< QShaderKey > QShader::availableShaders | ( | ) | const |
Definition at line 387 of file qshader.cpp.
References QMap< Key, T >::keys(), and QShaderPrivate::shaders.
QShaderDescription QShader::description | ( | ) | const |
Definition at line 370 of file qshader.cpp.
References QShaderPrivate::desc.
Referenced by addOpaqueDepthPrePassBindings(), QSSGRhiShaderPipeline::addStage(), and QGles2ComputePipeline::create().
void QShader::detach | ( | ) |
Definition at line 263 of file qshader.cpp.
References qAtomicDetach(), and QShaderPrivate.
Referenced by fromSerialized(), removeNativeShaderInfo(), removeResourceBindingMap(), removeSeparateToCombinedImageSamplerMappingList(), removeShader(), setDescription(), setNativeShaderInfo(), setResourceBindingMap(), setSeparateToCombinedImageSamplerMappingList(), setShader(), and setStage().
|
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
.
Definition at line 540 of file qshader.cpp.
References QShader(), QList< T >::append(), d, QShaderDescription::deserialize(), detach(), QShaderPrivate::get(), i, QMap< Key, T >::insert(), list, map, Q_ASSERT, QShaderPrivate::QSB_VERSION, QShaderPrivate::QSB_VERSION_WITH_BINARY_JSON, QShaderPrivate::QSB_VERSION_WITH_CBOR, QShaderPrivate::QSB_VERSION_WITHOUT_BINDINGS, QShaderPrivate::QSB_VERSION_WITHOUT_EXTENDED_STORAGE_BUFFER_INFO, QShaderPrivate::QSB_VERSION_WITHOUT_INPUT_OUTPUT_INTERFACE_BLOCKS, QShaderPrivate::QSB_VERSION_WITHOUT_NATIVE_SHADER_INFO, QShaderPrivate::QSB_VERSION_WITHOUT_SEPARATE_IMAGES_AND_SAMPLERS, QShaderPrivate::QSB_VERSION_WITHOUT_VAR_ARRAYDIMS, qUncompress(), qWarning, QIODeviceBase::ReadOnly, readShaderKey(), and QDataStream::setVersion().
Referenced by getShader(), getShader(), getShader(), QSGMaterialShaderPrivate::loadShader(), loadShaderFromFile(), main(), operator>>(), vfcGetShader(), and vwGetShader().
bool QShader::isValid | ( | ) | const |
Definition at line 343 of file qshader.cpp.
References QMap< Key, T >::isEmpty(), and QShaderPrivate::shaders.
Referenced by TextureCopy::TextureCopy(), QSSGShaderCache::compileForRhi(), QSGBatchRenderer::RhiVisualizer::prepareVisualize(), QSGRhiShaderLinker::reset(), QVideoWindowPrivate::setupGraphicsPipeline(), and updateTextures().
QShader::NativeResourceBindingMap QShader::nativeResourceBindingMap | ( | const QShaderKey & | key | ) | const |
Definition at line 1024 of file qshader.cpp.
References QShaderPrivate::bindings, and it.
Referenced by QD3D11ComputePipeline::create().
QShader::NativeShaderInfo QShader::nativeShaderInfo | ( | const QShaderKey & | key | ) | const |
\variable QShader::NativeShaderInfo::flags
\variable QShader::NativeShaderInfo::extraBufferBindings
Definition at line 1182 of file qshader.cpp.
References QMap< Key, T >::cend(), QMap< Key, T >::constFind(), it, and QShaderPrivate::nativeShaderInfoMap.
Assigns other to this object.
Move-assigns other to this QShader instance.
Definition at line 284 of file qshader.cpp.
References QBasicAtomicInteger< T >::deref(), other(), qAtomicAssign(), and QShaderPrivate::ref.
void QShader::removeNativeShaderInfo | ( | const QShaderKey & | key | ) |
Removes the native shader information for key.
Definition at line 1208 of file qshader.cpp.
References detach(), QMap< Key, T >::end(), QMap< Key, T >::erase(), QMap< Key, T >::find(), it, and QShaderPrivate::nativeShaderInfoMap.
void QShader::removeResourceBindingMap | ( | const QShaderKey & | key | ) |
Removes the native resource binding map for key.
Definition at line 1050 of file qshader.cpp.
References QShaderPrivate::bindings, detach(), and it.
void QShader::removeSeparateToCombinedImageSamplerMappingList | ( | const QShaderKey & | key | ) |
Removes the combined image sampler mapping list for key.
Definition at line 1131 of file qshader.cpp.
References QShaderPrivate::combinedImageMap, detach(), and it.
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 416 of file qshader.cpp.
References detach(), QMap< Key, T >::end(), QMap< Key, T >::erase(), QMap< Key, T >::find(), it, and QShaderPrivate::shaders.
QShader::SeparateToCombinedImageSamplerMappingList QShader::separateToCombinedImageSamplerMappingList | ( | const QShaderKey & | key | ) | const |
\variable QShader::SeparateToCombinedImageSamplerMapping::combinedSamplerName
\variable QShader::SeparateToCombinedImageSamplerMapping::textureBinding
\variable QShader::SeparateToCombinedImageSamplerMapping::samplerBinding
Definition at line 1104 of file qshader.cpp.
References QShaderPrivate::combinedImageMap, and it.
Referenced by QGles2ComputePipeline::create().
QByteArray QShader::serialized | ( | SerializedFormatVersion | version = SerializedFormatVersion::Latest | ) | const |
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.
Definition at line 450 of file qshader.cpp.
References QShaderPrivate::bindings, QMap< Key, T >::cbegin(), QList< T >::cbegin(), QSet< T >::cbegin(), QMap< Key, T >::cend(), QList< T >::cend(), QSet< T >::cend(), QShaderPrivate::combinedImageMap, QShaderPrivate::desc, it, list, map, QShaderPrivate::nativeShaderInfoMap, QByteArray(), qCompress(), QShaderPrivate::QSB_VERSION_WITHOUT_NATIVE_SHADER_INFO, QShaderPrivate::qtQsbVersion(), QShaderDescription::serialize(), QDataStream::setVersion(), QShaderPrivate::shaders, QMap< Key, T >::size(), QSet< T >::size(), QList< T >::size(), QShaderPrivate::stage, QMap< Key, T >::value(), QIODeviceBase::WriteOnly, and writeShaderKey().
void QShader::setDescription | ( | const QShaderDescription & | desc | ) |
Sets the reflection metadata to desc.
Definition at line 378 of file qshader.cpp.
References QShaderPrivate::desc, and detach().
void QShader::setNativeShaderInfo | ( | const QShaderKey & | key, |
const NativeShaderInfo & | info ) |
Stores the given native shader info associated with key.
Definition at line 1199 of file qshader.cpp.
References detach(), info, and QShaderPrivate::nativeShaderInfoMap.
void QShader::setResourceBindingMap | ( | const QShaderKey & | key, |
const NativeResourceBindingMap & | map ) |
Stores the given native resource binding map associated with key.
Definition at line 1041 of file qshader.cpp.
References QShaderPrivate::bindings, detach(), and map.
void QShader::setSeparateToCombinedImageSamplerMappingList | ( | const QShaderKey & | key, |
const SeparateToCombinedImageSamplerMappingList & | list ) |
Stores the given combined image sampler mapping list associated with key.
Definition at line 1121 of file qshader.cpp.
References QShaderPrivate::combinedImageMap, detach(), and list.
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 403 of file qshader.cpp.
References detach(), QShaderPrivate::shaders, and QMap< Key, T >::value().
Sets the pipeline stage.
Definition at line 359 of file qshader.cpp.
References detach(), stage(), and QShaderPrivate::stage.
QShaderCode QShader::shader | ( | const QShaderKey & | key | ) | const |
Definition at line 395 of file qshader.cpp.
References QShaderPrivate::shaders, and QMap< Key, T >::value().
Referenced by QGles2GraphicsPipeline::create(), QMetalGraphicsPipeline::create(), QVkGraphicsPipeline::create(), QMetalGraphicsPipeline::createVertexFragmentPipeline(), QSGMaterialShaderPrivate::shader(), and QSGRhiShaderEffectNode::syncMaterial().
QShader::Stage QShader::stage | ( | ) | const |
Definition at line 351 of file qshader.cpp.
References QShaderPrivate::stage, and VertexStage.
Referenced by setStage().
Swaps shader other with this shader. This operation is very fast and never fails.
Definition at line 124 of file qshader.h.
References d, other(), and qt_ptr_swap().
Definition at line 949 of file qshader.cpp.
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 779 of file qshader.cpp.
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 779 of file qshader.cpp.
|
friend |
Returns the hash value for s, using seed to seed the calculation.
Definition at line 803 of file qshader.cpp.
|
related |
Returns the hash value for s, using seed to seed the calculation.
Definition at line 803 of file qshader.cpp.
|
friend |