QShader Class
Enthält mehrere Versionen eines Shaders, die in mehrere Shading-Sprachen übersetzt wurden, zusammen mit Reflexions-Metadaten. Mehr...
| Kopfzeile: | #include <QShader> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui)target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| Since: | Qt 6.6 |
- Liste aller Mitglieder, einschließlich geerbter Mitglieder
- QShader ist Teil von Rendering in 3D.
Ö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 } |
Ö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) |
Detaillierte Beschreibung
QShader ist der Einstiegspunkt zu Shader-Code in der Grafik-API-agnostischen Qt-Welt. Anstatt GLSL-Shader-Quellen zu verwenden, wie es mit Qt 5.x üblich war, nehmen neue Grafiksysteme mit Backends für mehrere Grafik-APIs, wie Vulkan, Metal, Direct3D und OpenGL, QShader als Eingabe, wenn ein Shader spezifiziert werden muss.
Warnung: Die QRhi Familie von Klassen im Qt Gui Modul, einschließlich QShader und QShaderDescription, bieten begrenzte Kompatibilitätsgarantien. Es gibt keine Quell- oder Binärkompatibilitätsgarantien für diese Klassen, was bedeutet, dass die API nur mit der Qt-Version funktioniert, mit der die Anwendung entwickelt wurde. Quellcode-inkompatible Änderungen sollen jedoch auf ein Minimum beschränkt werden und werden nur in kleineren Versionen (6.7, 6.8 usw.) vorgenommen. Um diese Klassen in einer Anwendung zu verwenden, verlinken Sie auf Qt::GuiPrivate (wenn Sie CMake verwenden) und fügen Sie die Header mit dem Präfix rhi ein, zum Beispiel #include <rhi/qshader.h>.
Eine QShader-Instanz ist leer und daher standardmäßig ungültig. Um eine brauchbare Instanz zu erhalten, gibt es zwei typische Methoden:
- Erzeugen Sie den Inhalt offline, während der Build-Zeit oder früher, mit dem
qsbKommandozeilen-Tool. Das Ergebnis ist eine Binärdatei, die mit der Anwendung ausgeliefert, über QIODevice::readAll() gelesen und dann über fromSerialized() deserialisiert wird. Weitere Informationen finden Sie unter QShaderBaker. - Generieren Sie zur Laufzeit über QShaderBaker. Dies ist ein kostspieliger Vorgang, ermöglicht es aber Anwendungen, vom Benutzer bereitgestellte oder dynamisch generierte Shader-Quellstrings zu verwenden.
Wenn es zusammen mit dem Qt Rendering Hardware Interface und seinen Klassen, wie QRhiGraphicsPipeline, verwendet wird, ist keine weitere Aktion von Seiten der Anwendung notwendig, da diese Klassen darauf vorbereitet sind, einen QShader zu konsumieren, wann immer ein Shader für eine bestimmte Stufe der Grafikpipeline angegeben werden muss.
Alternativ dazu können Anwendungen auf
- den Quell- oder Bytecode für eine der Shading-Sprachversionen, die im QShader enthalten sind,
- den Namen des Einstiegspunkts für den Shader,
- die Reflexions-Metadaten, die eine Beschreibung der Eingänge, Ausgänge und Ressourcen des Shaders wie einheitliche Blöcke enthalten. Dies ist von wesentlicher Bedeutung, wenn eine Anwendung oder ein Framework die Eingänge eines Shaders zur Laufzeit ermitteln muss, weil die Vertex-Attribute oder das Layout der vom Shader verwendeten einheitlichen Puffer nicht bekannt sind.
QShader macht keine Annahmen über die Shading-Sprache, die als Quelle für die Generierung der verschiedenen Versionen und Varianten, die in ihm enthalten sind, verwendet wurde.
QShader verwendet implizites Sharing ähnlich wie viele Qt-Kerntypen und kann daher als Wert zurückgegeben oder übergeben werden. Detach geschieht implizit beim Aufruf eines Setters.
Als Referenz erwartet ein typisches, portables QRhi, dass ein QShader, der für alle seine Backends geeignet ist, mindestens das Folgende enthält. (dies schließt die Unterstützung für Kernprofil-OpenGL-Kontexte aus, fügen Sie dafür GLSL 150 oder neuer hinzu)
- SPIR-V 1.0 Bytecode geeignet für Vulkan 1.0 oder neuer
- GLSL/ES 100 Quellcode geeignet für OpenGL ES 2.0 oder neuer
- 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.
Member Type Dokumentation
[alias] QShader::NativeResourceBindingMap
Synonym für QMap<int, QPair<int, int>>.
Das Ressourcenbindungsmodell QRhi basiert auf SPIR-V. Das bedeutet, dass einheitliche Puffer, Speicherpuffer, kombinierte Bildsampler und Speicherbilder einen gemeinsamen Bindungspunktraum nutzen. Es wird erwartet, dass die Bindungsnummern in QShaderDescription und QRhiShaderResourceBinding mit dem Layout-Qualifier binding im Vulkan-kompatiblen GLSL-Shader übereinstimmen.
Andere Grafik-APIs als Vulkan verwenden möglicherweise ein Ressourcenbindungsmodell, das nicht vollständig mit diesem kompatibel ist. Der Generator des aus SPIR-V übersetzten Shader-Codes kann sich aus verschiedenen Gründen dafür entscheiden, die SPIR-V-Bindungsqualifikatoren nicht zu berücksichtigen. Dies ist z. B. beim Metal-Backend von SPIRV-Cross der Fall. Auch wenn eine automatische, implizite Übersetzung meist möglich ist (z. B. durch Verwendung von SPIR-V-Bindungspunkten als HLSL-Ressourcenregister-Indizes), kann die Zuweisung von Ressourcenbindungen ohne Beschränkung durch die SPIR-V-Bindungspunkte zu besseren Ergebnissen führen.
Aus diesem Grund kann QShader eine zusätzliche Map bereitstellen, die beschreibt, was der native Bindungspunkt für eine bestimmte SPIR-V-Bindung ist. Von den QRhi Backends, für die dies relevant ist, wird erwartet, dass sie diese Karte gegebenenfalls automatisch verwenden. Der Wert ist ein Paar, da kombinierte Bild-Sampler in einigen Schattierungssprachen 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 -1 sein, falls es keine aktive Bindung für die Ressource im Shader gibt. (Die Map ist immer vollständig, d. h. es gibt einen Eintrag für alle deklarierten Uniform-Blöcke, Speicherblöcke, Bildobjekte und kombinierten Sampler, aber der Wert ist -1 für diejenigen, die nicht tatsächlich in den Shader-Funktionen referenziert werden.
[alias] QShader::SeparateToCombinedImageSamplerMappingList
Synonym für QList<QShader::SeparateToCombinedImageSamplerMapping>.
enum class QShader::SerializedFormatVersion
Beschreibt das gewünschte Ausgabeformat bei der Serialisierung der QShader.
Der Standardwert für das Argument version von serialized() ist Latest. Dies ist in den allermeisten Fällen ausreichend. Die Angabe eines anderen Wertes ist nur dann erforderlich, wenn die Absicht besteht, serialisierte Daten zu erzeugen, die von früheren Qt-Versionen geladen werden können. Zum Beispiel verwendet das Werkzeug qsb diese Enum-Werte, wenn das Kommandozeilen-Argument --qsbversion angegeben wird.
Hinweis: Die Ausrichtung auf frühere Versionen führt dazu, dass bestimmte Funktionen mit dem generierten Asset nicht mehr funktionieren. Dies ist kein Problem, wenn das Asset mit der angegebenen, älteren Qt-Version verwendet wird, da diese Qt-Version nicht über die neueren Funktionen in neueren Qt-Versionen verfügt, die sich auf zusätzliche Daten stützen, die im QShader und im serialisierten Datenstrom erzeugt werden, kann aber zu einem Problem werden, wenn das generierte Asset dann 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 von 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 | Tessellierungssteuerung (Hüllenshader) Shader |
QShader::TessellationEvaluationStage | 2 | Tesselierungsauswertung (Domäne) Shader |
QShader::GeometryStage | 3 | Geometrie-Shader |
QShader::FragmentStage | 4 | Fragment-Shader (Pixel-Shader) |
QShader::ComputeStage | 5 | Berechnungs-Shader |
enum QShader::Variant
Beschreibt, welche Art von Shader-Code ein Eintrag enthält.
| Konstante | Wert | Beschreibung |
|---|---|---|
QShader::StandardShader | 0 | Die normale, unmodifizierte Version des Shader-Codes. |
QShader::BatchableVertexShader | 1 | Vertex-Shader, der umgeschrieben wurde, um für Qt Quick scenegraph batching geeignet zu sein. |
QShader::UInt16IndexedVertexAsComputeShader | 2 | Ein Vertex-Shader, der für die Verwendung in einer Metal-Pipeline mit Tesselation in Kombination mit indizierten Zeichenaufrufen gedacht ist, die Indexdaten aus einem uint16-Indexpuffer beziehen. Zur Unterstützung der Metal-Tessellation-Pipeline wird der Vertex-Shader in einen Compute-Shader übersetzt, der von der Verwendung des Indexpuffers in den Draw-Aufrufen abhängig sein kann (z. B. wenn der Shader gl_VertexIndex verwendet), daher sind drei spezielle Varianten erforderlich. |
QShader::UInt32IndexedVertexAsComputeShader | 3 | Ein Vertex-Shader, der in einer Metal-Pipeline mit Tessellation in Kombination mit indizierten Zeichenaufrufen verwendet werden soll, die Indexdaten aus einem uint32-Indexpuffer beziehen. Zur Unterstützung der Metal-Tessellation-Pipeline wird der Vertex-Shader in einen Compute-Shader übersetzt, der von der Verwendung des Indexpuffers in den Draw-Aufrufen abhängig sein kann (z. B. wenn der Shader gl_VertexIndex verwendet), daher sind drei spezielle Varianten erforderlich. |
QShader::NonIndexedVertexAsComputeShader | 4 | Ein Vertex-Shader, der in einer Metal-Pipeline mit Tessellation in Kombination mit nicht-indizierten Zeichenaufrufen verwendet werden soll. Zur Unterstützung der Metal-Tessellation-Pipeline wird der Vertex-Shader in einen Compute-Shader übersetzt, der von der Verwendung des Indexpuffers in den Draw-Aufrufen abhängig sein kann (z. B. wenn der Shader gl_VertexIndex verwendet), weshalb drei spezielle Varianten erforderlich sind. |
Dokumentation der Mitgliedsfunktionen
QShader::QShader()
Konstruiert eine neue, leere (und damit ungültige) QShader-Instanz.
QShader::QShader(const QShader &other)
Konstruiert eine Kopie von other.
[noexcept, since 6.7] QShader::QShader(QShader &&other)
Move-konstruiert einen neuen QShader aus other.
Hinweis: Das verschobene Objekt other wird in einen teilweise gebildeten Zustand versetzt, in dem die einzigen gültigen Operationen Zerstörung und Zuweisung eines neuen Wertes sind.
Diese Funktion wurde in Qt 6.7 eingeführt.
[noexcept] QShader::~QShader()
Zerstörer.
QList<QShaderKey> QShader::availableShaders() const
Gibt die Liste der verfügbaren Shader-Versionen zurück
QShaderDescription QShader::description() const
Gibt die Reflexions-Metadaten für den Shader zurück.
Siehe auch setDescription().
[static] QShader QShader::fromSerialized(const QByteArray &data)
Erzeugt eine neue QShader Instanz aus der angegebenen data.
Wenn data nicht erfolgreich deserialisiert werden kann, ist das Ergebnis ein standardmäßig konstruiertes QShader, für das isValid() false zurückgibt.
Siehe auch serialized().
bool QShader::isValid() const
Gibt true zurück, wenn die Seite QShader mindestens eine Shader-Version enthält.
QShader::NativeResourceBindingMap QShader::nativeResourceBindingMap(const QShaderKey &key) const
Gibt die native Bindungszuordnung für key zurück. Die Zuordnung ist leer, wenn für key keine Zuordnung verfügbar ist (z. B. weil die Zuordnung nicht für die von key beschriebene API und Schattierungssprache gilt).
QShader::NativeShaderInfo QShader::nativeShaderInfo(const QShaderKey &key) const
Gibt die native Shader-Info-Struktur für key zurück, oder ein leeres Objekt, wenn keine Daten für key verfügbar sind, z. B. weil ein solches Mapping 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 Resource Binding Map für key.
void QShader::removeSeparateToCombinedImageSamplerMappingList(const QShaderKey &key)
Entfernt die kombinierte Bildsampler-Zuordnungsliste für key.
void QShader::removeShader(const QShaderKey &key)
Entfernt den Quell- oder Binär-Shader-Code für einen bestimmten key. Tut nichts, wenn er nicht gefunden wird.
QShader::SeparateToCombinedImageSamplerMappingList QShader::separateToCombinedImageSamplerMappingList(const QShaderKey &key) const
Liefert die kombinierte Image-Sampler-Zuordnungsliste für key, oder eine leere Liste, wenn keine Daten für key verfügbar sind, z. B. weil eine solche Zuordnung für die Schattierungssprache nicht anwendbar ist.
Siehe auch setSeparateToCombinedImageSamplerMappingList().
QByteArray QShader::serialized(QShader::SerializedFormatVersion version = SerializedFormatVersion::Latest) const
Gibt eine serialisierte Binärversion aller in QShader enthaltenen Daten zurück, die sich zum Schreiben in Dateien oder andere E/A-Geräte eignet.
Standardmäßig wird das neueste Serialisierungsformat verwendet. Verwenden Sie den Parameter version zur Serialisierung für eine kompatible Qt-Version. Nur wenn bekannt ist, dass der erzeugte Datenstrom mit einer älteren Qt-Version kompatibel gemacht werden muss, und zwar auf Kosten der Inkompatibilität mit Funktionen, die seit dieser Qt-Version eingeführt wurden, sollte ein anderer Wert (zum Beispiel Qt_6_5 für Qt 6.5) verwendet werden.
Siehe auch fromSerialized().
void QShader::setDescription(const QShaderDescription &desc)
Setzt die Reflection-Metadaten auf desc.
Siehe auch description().
void QShader::setNativeShaderInfo(const QShaderKey &key, const QShader::NativeShaderInfo &info)
Speichert den angegebenen nativen Shader info, der mit key verbunden ist.
Siehe auch nativeShaderInfo().
void QShader::setResourceBindingMap(const QShaderKey &key, const QShader::NativeResourceBindingMap &map)
Speichert die angegebene native Ressourcenbindung map in Verbindung mit key.
Siehe auch nativeResourceBindingMap().
void QShader::setSeparateToCombinedImageSamplerMappingList(const QShaderKey &key, const QShader::SeparateToCombinedImageSamplerMappingList &list)
Speichert die angegebene kombinierte Bild-Sampler-Zuordnung list, die mit key verbunden ist.
Siehe auch separateToCombinedImageSamplerMappingList().
void QShader::setShader(const QShaderKey &key, const QShaderCode &shader)
Speichert den Quell- oder Binärcode shader für eine bestimmte Shader-Version, die durch key angegeben wird.
Siehe auch shader().
void QShader::setStage(QShader::Stage stage)
Legt die 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 Pipelinestufe zurück, für die der Shader bestimmt ist.
Siehe auch setStage().
[noexcept, since 6.7] void QShader::swap(QShader &other)
Tauscht diesen Shader mit other aus. Dieser Vorgang ist sehr schnell und schlägt nie fehl.
Diese Funktion wurde in Qt 6.7 eingeführt.
[noexcept, since 6.7] QShader &QShader::operator=(QShader &&other)
Verschieben - weist other dieser QShader Instanz zu.
Hinweis: Das verschobene Objekt other wird in einen teilweise gebildeten Zustand versetzt, in dem die einzigen gültigen Operationen Zerstörung und Zuweisung eines neuen Wertes sind.
Diese Funktion wurde in Qt 6.7 eingeführt.
QShader &QShader::operator=(const QShader &other)
Weist diesem Objekt other zu.
Verwandte 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 Objekten QShader lhs und rhs gleich sind; andernfalls wird true zurückgegeben.
[noexcept] bool operator==(const QShader &lhs, const QShader &rhs)
Gibt true zurück, wenn die beiden Objekte QShader lhs und rhs gleich sind, d. h., sie sind für dieselbe Stufe mit übereinstimmenden Sätzen von Shader-Quell- oder Binärcode.
© 2025 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.
