QShader Class
Enthält mehrere Versionen eines Shaders, die in verschiedene Shading-Sprachen übersetzt wurden, zusammen mit Metadaten zur Reflexion. Mehr...
| Header: | #include <qshader.h> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| Seit: | Qt 6.6 |
- Liste aller Mitglieder, einschließlich geerbter Mitglieder
- QShader ist Teil von „3D-Rendering“ und „Implizit gemeinsam genutzte Klassen“.
Öffentliche Typen
| 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 } |
Öffentliche Funktionen
| 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) |
Statische öffentliche Mitglieder
| QShader | fromSerialized(const QByteArray &data) |
Verwandte Nicht-Mitglieder
| 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) |
Ausführliche Beschreibung
QShader ist der Einstiegspunkt für Shader-Code in der grafik-API-unabhängigen Qt-Welt. Anstelle der Verwendung von GLSL-Shader-Quelldateien, wie es bei Qt 5.x üblich war, nutzen neue Grafiksysteme mit Backends für mehrere Grafik-APIs – wie beispielsweise Vulkan, Metal, Direct3D und OpenGL – QShader als Eingabe, wann immer ein Shader festgelegt werden muss.
Warnung: Die Klassenfamilie „ QRhi “ im Qt GUI-Modul, einschließlich QShader und QShaderDescription, bietet nur eingeschränkte Kompatibilitätsgarantien. Für diese Klassen gibt es keine Garantie für Quellcode- oder Binärkompatibilität, was bedeutet, dass die API nur mit der Qt-Version garantiert funktioniert, auf deren Grundlage die Anwendung entwickelt wurde. Quellinkompatible Änderungen sollen jedoch auf ein Minimum beschränkt bleiben und werden nur in Minor-Releases (6.7, 6.8 usw.) vorgenommen. Um diese Klassen in einer Anwendung zu verwenden, verknüpfen Sie mit „ Qt::GuiPrivate “ (bei Verwendung von CMake) und binden Sie die Header mit dem Präfix „ rhi “ ein, zum Beispiel „ #include <rhi/qshader.h> “.
Eine QShader-Instanz ist standardmäßig leer und somit ungültig. Um eine brauchbare Instanz zu erhalten, gibt es zwei gängige Methoden:
- Generieren Sie den Inhalt offline, während der Erstellungsphase oder noch früher, mithilfe des Befehlszeilentools „
qsb“. Das Ergebnis ist eine Binärdatei, die mit der Anwendung ausgeliefert wird, über „ QIODevice::readAll()“ eingelesen und anschließend über „ fromSerialized()“ deserialisiert wird. Weitere Informationen finden Sie unter QShaderBaker. - Generierung zur Laufzeit über ` QShaderBaker`. Dies ist ein rechenintensiver Vorgang, ermöglicht es Anwendungen jedoch, vom Benutzer bereitgestellte oder dynamisch generierte Shader-Quelltextzeichenfolgen zu verwenden.
Bei Verwendung zusammen mit der Qt-Rendering-Hardware-Schnittstelle und deren Klassen, wie z. B. ` QRhiGraphicsPipeline`, sind seitens der Anwendung keine weiteren Maßnahmen erforderlich, da diese Klassen darauf ausgelegt sind, einen `QShader` zu verarbeiten, sobald für eine bestimmte Stufe der Grafikpipeline ein Shader angegeben werden muss.
Alternativ können Anwendungen auf
- auf den Quell- oder Bytecode für jede der im QShader enthaltenen Shading-Sprachversionen sowie
- den Namen des Einstiegspunkts für den Shader,
- die Reflection-Metadaten, die eine Beschreibung der Eingaben, Ausgaben und Ressourcen des Shaders wie z. B. Uniform-Blöcke enthalten. Dies ist unerlässlich, wenn eine Anwendung oder ein Framework die Eingaben eines Shaders zur Laufzeit ermitteln muss, da keine Vorabkenntnisse über die Vertex-Attribute oder das Layout der vom Shader verwendeten Uniform-Puffer vorliegen.
QShader trifft keine Annahmen hinsichtlich der Shading-Sprache, die als Quelle für die Generierung der verschiedenen darin enthaltenen Versionen und Varianten diente.
QShader nutzt implizites Sharing ähnlich wie viele Typen aus Qt Core und kann daher als Wert zurückgegeben oder übergeben werden. Die Entkopplung erfolgt implizit beim Aufruf eines Setters.
Als Referenz: Ein typischer, portabler „ QRhi “ erwartet, dass ein für alle seine Backends geeigneter QShader mindestens die folgenden Elemente enthält. (Dies schließt die Unterstützung für OpenGL-Kontexte des Core-Profils aus; füge hierfür GLSL 150 oder neuer hinzu.)
- SPIR-V 1.0-Bytecode, der für Vulkan 1.0 oder neuer geeignet ist
- GLSL/ES 100-Quellcode, der für OpenGL ES 2.0 oder neuer geeignet ist
- GLSL 120-Quellcode, geeignet für OpenGL 2.1 oder neuer
- HLSL-Shader-Model-5.0-Quellcode oder der entsprechende DXBC-Bytecode, geeignet für Direct3D 11/12
- Metal Shading Language 1.2-Quellcode oder der entsprechende Bytecode, geeignet für Metal 1.2 oder neuer
Siehe auch QShaderBaker.
Dokumentation zu Mitgliedstypen
[alias] QShader::NativeResourceBindingMap
Synonym für QMap<int, std::pair<int, int>>.
Das von „ QRhi “ zugrunde gelegte Ressourcenbindungsmodell basiert auf SPIR-V. Das bedeutet, dass Uniform-Buffer, Speicher-Buffer, kombinierte Bild-Sampler und Speicherbilder einen gemeinsamen Bindungspunktbereich teilen. Es wird erwartet, dass die Bindungsnummern in QShaderDescription und QRhiShaderResourceBinding mit dem Layout-Qualifizierer „ binding “ im Vulkan-kompatiblen GLSL-Shader übereinstimmen.
Andere Grafik-APIs als Vulkan verwenden möglicherweise ein Ressourcenbindungsmodell, das damit nicht vollständig kompatibel ist. Der Generator des aus SPIR-V übersetzten Shader-Codes kann aus verschiedenen Gründen entscheiden, die SPIR-V-Bindungskennzeichen nicht zu berücksichtigen. Dies ist beispielsweise beim Metal-Backend von SPIRV-Cross der Fall. Darüber hinaus kann die Zuweisung von Ressourcenbindungen ohne die Einschränkungen durch die SPIR-V-Bindungspunkte zu besseren Ergebnissen führen, selbst wenn eine automatische, implizite Übersetzung größtenteils möglich ist (z. B. durch die Verwendung von SPIR-V-Bindungspunkten als HLSL-Ressourcenregisterindizes).
Daher kann ein „ QShader “ eine zusätzliche Zuordnung bereitstellen, die beschreibt, welcher native Bindungspunkt einer bestimmten SPIR-V-Bindung entspricht. Von den „ QRhi “-Backends, für die dies relevant ist, wird erwartet, dass sie diese Zuordnung gegebenenfalls automatisch verwenden. Der Wert ist ein Paar, da kombinierte Bild-Sampler in einigen Shading-Sprachen auf zwei native Ressourcen (eine Textur und einen Sampler) abgebildet werden können. In diesem Fall bezieht sich der zweite Wert auf den Sampler.
Hinweis: Die native Bindung kann den Wert -1 annehmen, falls im Shader keine aktive Bindung für die Ressource vorhanden ist. (Beispiel: Es ist ein Uniform-Block deklariert, der jedoch im Shader-Code nicht verwendet wird.) Die Zuordnung ist immer vollständig, d. h., es gibt einen Eintrag für alle deklarierten Uniform-Blöcke, Speicherblöcke, Bildobjekte und kombinierten Sampler; der Wert beträgt jedoch -1 für diejenigen, auf die in den Shader-Funktionen nicht tatsächlich verwiesen wird.
[alias] QShader::SeparateToCombinedImageSamplerMappingList
Synonym für „ QList “ <QShader::SeparateToCombinedImageSamplerMapping>.
enum class QShader::SerializedFormatVersion
Beschreibt das gewünschte Ausgabeformat bei der Serialisierung des „ QShader “.
Der Standardwert für das Argument „ version “ von „ serialized()“ lautet „ Latest “. Dies ist in den allermeisten Fällen ausreichend. Die Angabe eines anderen Werts ist nur erforderlich, wenn serialisierte Daten generiert werden sollen, die von früheren Qt-Versionen geladen werden können. Beispielsweise verwendet das Tool „ qsb “ diese Enum-Werte, wenn das Befehlszeilenargument „ --qsbversion “ angegeben wird.
Hinweis: Bei der Ausrichtung auf frühere Versionen funktionieren bestimmte Funktionen des generierten Assets nicht mehr. Dies stellt kein Problem dar, wenn das Asset mit der angegebenen, älteren Qt-Version verwendet wird, vorausgesetzt, diese Qt-Version verfügt nicht über die neueren Funktionen, die in neueren Qt-Versionen enthalten sind und auf zusätzlichen Daten basieren, die im „ QShader “ und im serialisierten Datenstrom generiert werden. Es kann jedoch zu Problemen kommen, wenn das generierte Asset anschließend mit einer neueren Qt-Version verwendet wird.
| Konstante | Wert | Beschreibung |
|---|---|---|
QShader::SerializedFormatVersion::Latest | 0 | Die aktuelle Qt-Version |
QShader::SerializedFormatVersion::Qt_6_5 | 1 | Qt 6.5 |
QShader::SerializedFormatVersion::Qt_6_4 | 2 | Qt 6.4 |
enum QShader::Source
Beschreibt, welche Art von Shader-Code ein Eintrag enthält.
| Konstante | Wert | Beschreibung |
|---|---|---|
QShader::SpirvShader | 0 | SPIR-V |
QShader::GlslShader | 1 | GLSL |
QShader::HlslShader | 2 | HLSL |
QShader::DxbcShader | 3 | Direct3D-Bytecode (HLSL, kompiliert mit fxc) |
QShader::MslShader | 4 | Metal Shading Language |
QShader::DxilShader | 5 | Direct3D-Bytecode (HLSL, kompiliert von dxc) |
QShader::MetalLibShader | 6 | Vorkompilierter Metal-Bytecode |
QShader::WgslShader | 7 | WGSL |
enum QShader::Stage
Beschreibt die Stufe der Grafikpipeline, für die der Shader geeignet ist.
| Konstante | Wert | Beschreibung |
|---|---|---|
QShader::VertexStage | 0 | Vertex-Shader |
QShader::TessellationControlStage | 1 | Tessellationssteuerungs- (Hull-)Shader |
QShader::TessellationEvaluationStage | 2 | Tessellationsauswertungs-Shader (Domain) |
QShader::GeometryStage | 3 | Geometrie-Shader |
QShader::FragmentStage | 4 | Fragment- (Pixel-)Shader |
QShader::ComputeStage | 5 | Compute-Shader |
enum QShader::Variant
Beschreibt, welche Art von Shader-Code ein Eintrag enthält.
| Konstante | Wert | Beschreibung |
|---|---|---|
QShader::StandardShader | 0 | Die normale, unveränderte Version des Shader-Codes. |
QShader::BatchableVertexShader | 1 | Vertex-Shader, der für das „ Qt Quick “-Scenegraph-Batching umgeschrieben wurde. |
QShader::UInt16IndexedVertexAsComputeShader | 2 | Ein Vertex-Shader, der für den Einsatz in einer Metal-Pipeline mit Tessellation in Kombination mit indizierten Draw-Calls vorgesehen ist, bei denen die Indexdaten aus einem uint16-Indexpuffer bezogen werden. Zur Unterstützung der Metal-Tessellations-Pipeline wird der Vertex-Shader in einen Compute-Shader übersetzt, der von der Verwendung des Indexpuffers in den Draw-Calls abhängig sein kann (z. B. wenn der Shader gl_VertexIndex verwendet), weshalb drei spezielle Varianten erforderlich sind. |
QShader::UInt32IndexedVertexAsComputeShader | 3 | Ein Vertex-Shader, der für den Einsatz in einer Metal-Pipeline mit Tessellation in Kombination mit indizierten Draw-Calls vorgesehen ist, wobei die Indexdaten aus einem uint32-Indexpuffer bezogen werden. Zur Unterstützung der Metal-Tessellationspipeline wird der Vertex-Shader in einen Compute-Shader übersetzt, der möglicherweise von der Verwendung des Indexpuffers in den Draw-Calls abhängt (z. B. wenn der Shader `gl_VertexIndex` verwendet), weshalb drei spezielle Varianten erforderlich sind. |
QShader::NonIndexedVertexAsComputeShader | 4 | Ein Vertex-Shader, der für den Einsatz in einer Metal-Pipeline mit Tessellation in Kombination mit nicht indizierten Draw-Calls vorgesehen ist. Zur Unterstützung der Metal-Tessellations-Pipeline wird der Vertex-Shader in einen Compute-Shader übersetzt, der möglicherweise von der Verwendung des Indexpuffers in den Draw-Calls abhängt (z. B. wenn der Shader `gl_VertexIndex` verwendet), weshalb drei spezielle Varianten erforderlich sind. |
QShader::HdrCapableFragmentShader (since Qt 6.10) | 5 | Ein Fragment-Shader, der umgeschrieben wurde, um High-Dynamic-Range-Rendering in einer „ Qt Quick “-Szenengrafik zu unterstützen. |
Dokumentation der Member-Funktionen
QShader::QShader()
Erstellt eine neue, leere (und somit ungültige) QShader-Instanz.
QShader::QShader(const QShader &other)
Erstellt eine Kopie von „ other “.
[noexcept, since 6.7] QShader::QShader(QShader &&other)
Erstellt einen neuen QShader aus „ other “ mithilfe von „move“.
Hinweis: Das verschobene Objekt ` other ` befindet sich in einem teilweise initialisierten Zustand, in dem die einzigen zulässigen Operationen die Zerstörung und die Zuweisung eines neuen Werts sind.
Diese Funktion wurde in Qt 6.7 eingeführt.
[noexcept] QShader::~QShader()
Destruktor.
QList<QShaderKey> QShader::availableShaders() const
Gibt die Liste der verfügbaren Shader-Versionen zurück
QShaderDescription QShader::description() const
Gibt die Reflexionsmetadaten für den Shader zurück.
Siehe auch „ setDescription()“.
[static] QShader QShader::fromSerialized(const QByteArray &data)
Erstellt eine neue Instanz von ` QShader ` aus dem angegebenen ` data`.
Wenn „ data “ nicht erfolgreich deserialisiert werden kann, ist das Ergebnis ein standardmäßig initialisiertes „ QShader “, für das „ isValid()“ den Wert „ false “ zurückgibt.
Warnung: Shader-Pakete , einschließlich „ .qsb “-Dateien im Dateisystem, gelten als vertrauenswürdige Inhalte. Anwendungsentwicklern wird empfohlen, die möglichen Auswirkungen sorgfältig abzuwägen, bevor sie das Laden von benutzerbereitgestellten Inhalten zulassen, die nicht Teil der Anwendung sind.
Siehe auch serialized().
bool QShader::isValid() const
Gibt „true“ zurück, wenn die „ QShader “ mindestens eine Shader-Version enthält.
QShader::NativeResourceBindingMap QShader::nativeResourceBindingMap(const QShaderKey &key) const
Gibt die native Zuordnungstabelle für key zurück. Die Tabelle ist leer, wenn für key keine Zuordnung verfügbar ist (beispielsweise, weil die Tabelle nicht auf die unter key beschriebene API und Shading-Sprache anwendbar ist).
QShader::NativeShaderInfo QShader::nativeShaderInfo(const QShaderKey &key) const
Gibt die native Shader-Info-Struktur für „ key “ zurück oder ein leeres Objekt, wenn für „ key “ keine Daten verfügbar sind, beispielsweise weil eine solche Zuordnung für die Shading-Sprache oder die Shader-Stufe nicht anwendbar ist.
Siehe auch setNativeShaderInfo().
void QShader::removeNativeShaderInfo(const QShaderKey &key)
Entfernt die nativen Shader-Informationen für „ key “.
void QShader::removeResourceBindingMap(const QShaderKey &key)
Entfernt die native Ressourcen-Zuordnung für key.
void QShader::removeSeparateToCombinedImageSamplerMappingList(const QShaderKey &key)
Entfernt die Zuordnungsliste für den kombinierten Bild-Sampler für „ key “.
void QShader::removeShader(const QShaderKey &key)
Entfernt den Quell- oder Binär-Shader-Code für ein bestimmtes ` key`. Führt keine Aktion aus, wenn nichts gefunden wird.
QShader::SeparateToCombinedImageSamplerMappingList QShader::separateToCombinedImageSamplerMappingList(const QShaderKey &key) const
Gibt die kombinierte Bild-Sampler-Zuordnungsliste für „ key “ zurück oder eine leere Liste, wenn keine Daten für „ key “ verfügbar sind, beispielsweise weil eine solche Zuordnung für die Shading-Sprache nicht anwendbar ist.
Siehe auch ` setSeparateToCombinedImageSamplerMappingList()`.
QByteArray QShader::serialized(QShader::SerializedFormatVersion version = SerializedFormatVersion::Latest) const
Gibt eine serialisierte binäre Version aller vom ` QShader` verwalteten Daten zurück, die sich zum Schreiben in Dateien oder auf andere E/A-Geräte eignet.
Standardmäßig wird das neueste Serialisierungsformat verwendet. Verwenden Sie den Parameter „ version “, um die Serialisierung für eine bestimmte Qt-Version durchzuführen. Nur wenn bekannt ist, dass der generierte Datenstrom mit einer älteren Qt-Version kompatibel sein muss – auch wenn dies auf Kosten der Kompatibilität mit Funktionen geht, die seit dieser Qt-Version eingeführt wurden –, sollte ein anderer Wert (z. B. ` Qt_6_5 ` für Qt 6.5) verwendet werden.
Siehe auch ` fromSerialized()`.
void QShader::setDescription(const QShaderDescription &desc)
Setzt die Metadaten der Reflexion auf „ desc “.
Siehe auch description().
void QShader::setNativeShaderInfo(const QShaderKey &key, const QShader::NativeShaderInfo &info)
Speichert die angegebene native Shader- info, die mit key verknüpft ist.
Siehe auch ` nativeShaderInfo()`.
void QShader::setResourceBindingMap(const QShaderKey &key, const QShader::NativeResourceBindingMap &map)
Speichert die angegebene native Ressourcenbindung „ map “, die mit „ key “ verknüpft ist.
Siehe auch nativeResourceBindingMap().
void QShader::setSeparateToCombinedImageSamplerMappingList(const QShaderKey &key, const QShader::SeparateToCombinedImageSamplerMappingList &list)
Speichert die angegebene Zuordnung des kombinierten Bild-Samplers list, die mit key verknüpft ist.
Siehe auch separateToCombinedImageSamplerMappingList().
void QShader::setShader(const QShaderKey &key, const QShaderCode &shader)
Speichert den Quell- oder Binär shader -Code für eine bestimmte Shader-Version, die durch key angegeben wird.
Siehe auch ` shader()`.
void QShader::setStage(QShader::Stage stage)
Legt den Pipeline- stage fest.
Siehe auch stage().
QShaderCode QShader::shader(const QShaderKey &key) const
Gibt den Quell- oder Binärcode für eine bestimmte Shader-Version zurück, die durch ` key` angegeben wird.
Siehe auch setShader().
QShader::Stage QShader::stage() const
Gibt die Pipeline-Stufe zurück, für die der Shader vorgesehen ist.
Siehe auch „ setStage()“.
[noexcept, since 6.7] void QShader::swap(QShader &other)
Ersetzt diesen Shader durch „ other “. Dieser Vorgang ist sehr schnell und schlägt niemals fehl.
Diese Funktion wurde in Qt 6.7 eingeführt.
[noexcept, since 6.7] QShader &QShader::operator=(QShader &&other)
Weist „ other “ dieser Instanz von „ QShader “ zu.
Hinweis: Das verschobene Objekt other befindet sich in einem teilweise initialisierten Zustand, in dem die einzigen zulässigen Operationen die Zerstörung und die Zuweisung eines neuen Werts sind.
Diese Funktion wurde in Qt 6.7 eingeführt.
QShader &QShader::operator=(const QShader &other)
Weist diesem Objekt „ other “ zu.
Zugehörige Nicht-Mitglieder
[noexcept] size_t qHash(const QShader &key, size_t seed = 0)
Gibt den Hash-Wert für key zurück, wobei seed als Startwert für die Berechnung verwendet wird.
[noexcept] bool operator!=(const QShader &lhs, const QShader &rhs)
Gibt „ false “ zurück, wenn die Werte in den beiden „ QShader “-Objekten „ lhs “ und „ rhs “ identisch sind; andernfalls wird „ true “ zurückgegeben.
[noexcept] bool operator==(const QShader &lhs, const QShader &rhs)
Gibt „ true “ zurück, wenn die beiden „ QShader “-Objekte „ lhs “ und „ rhs “ gleich sind, d. h. wenn sie sich auf dieselbe Stage beziehen und übereinstimmende Sätze von Shader-Quell- oder Binärcode enthalten.
© 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.
