QRhiColorAttachment Class
Beschreibt das einzelne Farbattachment eines Rendering-Ziels. Mehr...
| Kopfzeile: | #include <rhi/qrhi.h> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui)target_link_libraries(mytarget PRIVATE Qt6::GuiPrivate) |
| qmake: | QT += gui-private |
| Since: | Qt 6.6 |
Öffentliche Funktionen
| QRhiColorAttachment() | |
| QRhiColorAttachment(QRhiRenderBuffer *renderBuffer) | |
| QRhiColorAttachment(QRhiTexture *texture) | |
| int | layer() const |
| int | level() const |
(since 6.7) int | multiViewCount() const |
| QRhiRenderBuffer * | renderBuffer() const |
| int | resolveLayer() const |
| int | resolveLevel() const |
| QRhiTexture * | resolveTexture() const |
| void | setLayer(int layer) |
| void | setLevel(int level) |
(since 6.7) void | setMultiViewCount(int count) |
| void | setRenderBuffer(QRhiRenderBuffer *rb) |
| void | setResolveLayer(int layer) |
| void | setResolveLevel(int level) |
| void | setResolveTexture(QRhiTexture *tex) |
| void | setTexture(QRhiTexture *tex) |
| QRhiTexture * | texture() const |
Detaillierte Beschreibung
Ein Farbattachment ist entweder ein QRhiTexture oder ein QRhiRenderBuffer. Ersteres, d.h. wenn texture() gesetzt ist, wird in den meisten Fällen verwendet. QRhiColorAttachment wird häufig in Kombination mit QRhiTextureRenderTargetDescription verwendet.
Hinweis: texture() und renderBuffer() können nicht gleichzeitig gesetzt werden (d. h. nicht null sein).
Das Setzen von renderBuffer wird nur empfohlen, wenn Multisampling erforderlich ist. Sich auf QRhi::MultisampleRenderBuffer zu verlassen ist in der Praxis eine bessere Wahl als QRhi::MultisampleTexture, da ersteres in mehr Laufzeitkonfigurationen verfügbar ist (z.B. wenn es auf OpenGL ES 3.0 läuft, das keine Unterstützung für Multisample-Texturen hat, aber Multisample-Renderbuffer unterstützt).
Wenn eine Nicht-Multisample-Textur angepeilt wird, geben layer() und level() die angepeilte Ebene (Flächenindex 0-5 für Cubemaps) und Mip-Ebene an. Bei 3D-Texturen gibt layer() das Slice (ein 2D-Bild innerhalb der 3D-Textur) an, in das gerendert werden soll. Bei Textur-Arrays ist layer() der Array-Index.
Wenn texture() oder renderBuffer() Multisample ist, kann resolveTexture() optional gesetzt werden. Wenn diese Option gesetzt ist, werden die Samples am Ende des Rendervorgangs automatisch in diese (nicht-multisample) Textur aufgelöst. Wenn in einen Multisample-Renderbuffer gerendert wird, ist dies die einzige Möglichkeit, aufgelösten Nicht-Multisample-Inhalt aus diesem zu erhalten. Multisample-Texturen erlauben Sampling in Shadern, so dass dies für sie nur eine Option ist.
Hinweis: Wenn das Auflösen aktiviert ist, werden die Multisample-Daten möglicherweise gar nicht ausgeschrieben. Das bedeutet, dass die Multisample texture() nicht nachträglich mit Shadern für Sampling verwendet werden darf, wenn resolveTexture() eingestellt ist.
Hinweis: Dies ist eine RHI-API mit begrenzten Kompatibilitätsgarantien, siehe QRhi für Details.
Siehe auch QRhiTextureRenderTargetDescription.
Dokumentation der Mitgliedsfunktionen
[constexpr noexcept] QRhiColorAttachment::QRhiColorAttachment()
Konstruiert eine leere Beschreibung des Farbanhangs.
QRhiColorAttachment::QRhiColorAttachment(QRhiRenderBuffer *renderBuffer)
Konstruiert eine Beschreibung eines Farbanhangs, die renderBuffer als den zugehörigen Farbpuffer angibt.
QRhiColorAttachment::QRhiColorAttachment(QRhiTexture *texture)
Konstruiert eine Beschreibung eines Farbanhangs, die texture als den zugehörigen Farbpuffer angibt.
int QRhiColorAttachment::layer() const
Gibt den Ebenenindex zurück (Cubemap-Fläche oder Array-Ebene). Standardmäßig 0.
Siehe auch setLayer().
int QRhiColorAttachment::level() const
Gibt den Mip-Level zurück. Standardmäßig 0.
Siehe auch setLevel().
[since 6.7] int QRhiColorAttachment::multiViewCount() const
Gibt die aktuell eingestellte Anzahl von Ansichten zurück. Der Standardwert ist 0, was bedeutet, dass das Rendering-Ziel mit diesem Farbattachment nicht für das Multiview-Rendering verwendet wird.
Diese Funktion wurde in Qt 6.7 eingeführt.
Siehe auch setMultiViewCount().
QRhiRenderBuffer *QRhiColorAttachment::renderBuffer() const
Gibt den Renderbuffer zurück, auf den diese Anhangsbeschreibung verweist, oder nullptr, wenn es keinen gibt.
In der Praxis ist die Verknüpfung eines QRhiRenderBuffer mit einem QRhiColorAttachment am sinnvollsten, wenn ein Multisample-Rendering über einen Multisample-Renderbuffer color eingerichtet wird, der dann am Ende des Rendering-Durchgangs in eine Nicht-Multisample-Textur aufgelöst wird.
Siehe auch setRenderBuffer().
int QRhiColorAttachment::resolveLayer() const
Gibt die aktuell eingestellte Auflösungs-Texturebene zurück. Der Standardwert ist 0.
Siehe auch setResolveLayer().
int QRhiColorAttachment::resolveLevel() const
Gibt den aktuell eingestellten Mip-Level der aufgelösten Textur zurück. Der Standardwert ist 0.
Siehe auch setResolveLevel().
QRhiTexture *QRhiColorAttachment::resolveTexture() const
Gibt die Auflösungs-Textur zurück, auf die diese Anhangsbeschreibung verweist, oder nullptr, wenn es keine gibt.
Das Setzen einer nicht-null Texturauflösung ist anwendbar, wenn der Anhang auf eine Multisample-Textur oder einen Renderbuffer verweist. Die QRhiTexture in resolveTexture() ist dann eine nicht-multisample 2D-Textur (oder ein Textur-Array) mit der gleichen Größe (aber einer Sampleanzahl von 1). Der Multisample-Inhalt wird am Ende eines jeden Rendering-Durchgangs automatisch in diese Textur aufgelöst.
Siehe auch setResolveTexture().
void QRhiColorAttachment::setLayer(int layer)
Setzt den Index layer.
Siehe auch layer().
void QRhiColorAttachment::setLevel(int level)
Setzt den mip level.
Siehe auch level().
[since 6.7] void QRhiColorAttachment::setMultiViewCount(int count)
Legt die Ansicht count fest. Ein Wert größer als 1 bedeutet, dass das Rendering-Ziel mit dieser Farbzuordnung für das Multiview-Rendering verwendet wird. Der Standardwert ist 0. Werte kleiner als 2 bedeuten kein Multiview-Rendering.
Wenn count auf 2 oder höher gesetzt ist, muss das Farbattachment mit einem 2D-Textur-Array verbunden sein. layer() und multiViewCount() definieren zusammen den Bereich der Textur-Array-Elemente, die während des Multiview-Renderings angesprochen werden.
Wenn layer beispielsweise 0 und multiViewCount 2 ist, muss das Textur-Array 2 (oder mehr) Elemente haben, und das Multiview-Rendering wird auf die Elemente 0 und 1 abzielen. Die Variable gl_ViewIndex in den Shadern hat dann einen Wert von 0 oder 1, wobei die Ansicht 0 dem Textur-Array-Element 0 und die Ansicht 1 dem Array-Element 1 entspricht.
Hinweis: Die Einstellung eines count größer als 1, die Verwendung eines Textur-Arrays als texture() und der Aufruf von beginPass() auf einem QRhiTextureRenderTarget mit diesem Farbanhang impliziert Multiview-Rendering für den gesamten Rendering-Durchgang. multiViewCount() sollte nicht gesetzt werden, es sei denn, Multiview-Rendering ist gewünscht. Multiview kann nicht mit anderen Texturtypen als 2D-Texturarrays verwendet werden. (obwohl 3D-Texturen je nach Grafik-API und Backend funktionieren können; Anwendungen sollten sich jedoch nicht darauf verlassen und nur 2D-Textur-Arrays als Rendering-Ziele für Multiview-Rendering verwenden)
Siehe GL_OVR_multiview für weitere Details zum Multiview-Rendering. Bitte beachten Sie, dass Qt auch GL_OVR_multiview2 benötigt, wenn es unter OpenGL (ES) läuft.
Multiview-Rendering ist nur verfügbar, wenn die Funktion MultiView von isFeatureSupported() als unterstützt gemeldet wird.
Hinweis: Um die Portabilität zu gewährleisten, sollten Sie sich der Einschränkungen bewusst sein, die beim Multiview-Rendering mit einigen Grafik-APIs bestehen. Es wird empfohlen, dass Multiview-Rendering-Passes sich nicht auf eines der Features verlassen, die GL_OVR_multiview als nicht unterstützt deklariert. Die einzige Ausnahme sind Shader-Stage-Ausgaben, die nicht von gl_Position, sondern von gl_ViewIndex abhängen: auf diese kann man sich verlassen (sogar mit OpenGL), da QRhi niemals Multiview als unterstützt meldet, wenn nicht auch GL_OVR_multiview2 vorhanden ist.
Hinweis: Multiview-Rendering wird nicht in Kombination mit Tessellation oder Geometrie-Shadern unterstützt, auch wenn einige Implementierungen einiger Grafik-APIs dies erlauben können.
Diese Funktion wurde in Qt 6.7 eingeführt.
Siehe auch multiViewCount().
void QRhiColorAttachment::setRenderBuffer(QRhiRenderBuffer *rb)
Setzt den Renderbuffer rb.
Hinweis: texture() und renderBuffer() können nicht gleichzeitig gesetzt werden (d.h. nicht null sein).
Siehe auch renderBuffer().
void QRhiColorAttachment::setResolveLayer(int layer)
Legt die zu verwendende Auflösungstextur layer fest.
Siehe auch resolveLayer().
void QRhiColorAttachment::setResolveLevel(int level)
Legt die zu verwendende Auflösung der Textur mip level fest.
Siehe auch resolveLevel().
void QRhiColorAttachment::setResolveTexture(QRhiTexture *tex)
Setzt die aufzulösende Textur tex.
tex wird erwartet, dass es sich um eine 2D-Textur oder ein 2D-Textur-Array handelt. In beiden Fällen zielt die Auflösung auf eine einzelne Mip-Ebene einer einzelnen Schicht (Array-Element) von tex. Die Mip-Ebene und die Array-Schicht werden durch resolveLevel() und resolveLayer() angegeben.
Eine Ausnahme ist multiview: Wenn das Farbattachment mit einem Textur-Array verbunden ist und Multiview aktiviert ist, muss die aufzulösende Textur ebenfalls ein Textur-Array mit genügend Elementen für alle Ansichten sein. In diesem Fall werden alle Elemente, die Ansichten entsprechen, automatisch aufgelöst; das Verhalten ist ähnlich dem folgenden Pseudocode:
for (i = 0; i < multiViewCount(); ++i)
resolve texture's layer() + i into resolveTexture's resolveLayer() + iDas Einstellen einer Nicht-Multisample-Textur zur automatischen Auflösung einer Multisample-Textur oder eines Renderbuffers am Ende des Rendering-Durchlaufs ist der Arbeit mit Multisample-Texturen (und dem Nicht-Einstellen einer Resolve-Textur) oft vorzuziehen, weil dadurch die Notwendigkeit vermieden wird, spezielle Fragment-Shader zu schreiben, die ausschließlich mit Multisample-Texturen arbeiten (sampler2DMS, texelFetch, usw.), und stattdessen derselbe Shader verwendet werden kann, wie wenn die Textur des Attachments nicht von vornherein multisampled wäre. Dies geht auf Kosten einer zusätzlichen Ressource (der nicht gemischten Textur tex).
Siehe auch resolveTexture().
void QRhiColorAttachment::setTexture(QRhiTexture *tex)
Setzt die Textur tex.
Hinweis: texture() und renderBuffer() können nicht beide gesetzt werden (nicht gleichzeitig null sein).
Siehe auch texture().
QRhiTexture *QRhiColorAttachment::texture() const
Gibt die Textur zurück, auf die sich diese Anhangsbeschreibung bezieht, oder nullptr, wenn es keine gibt.
Siehe auch setTexture().
© 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.
