Back to Qt.io
Contact Us Blog Download Qt

QRhiTextureRenderTargetDescription Class

Beschreibt die Farbe und die Tiefe oder die Tiefen-/Schablonenanhänge eines Renderingziels. 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

QRhiTextureRenderTargetDescription()
QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment)
QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment, QRhiRenderBuffer *depthStencilBuffer)
QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment, QRhiTexture *depthTexture)
const QRhiColorAttachment *cbeginColorAttachments() const
const QRhiColorAttachment *cendColorAttachments() const
const QRhiColorAttachment *colorAttachmentAt(qsizetype index) const
qsizetype colorAttachmentCount() const
(since 6.8) QRhiTexture *depthResolveTexture() const
QRhiRenderBuffer *depthStencilBuffer() const
QRhiTexture *depthTexture() const
void setColorAttachments(std::initializer_list<QRhiColorAttachment> list)
void setColorAttachments(InputIterator first, InputIterator last)
(since 6.8) void setDepthResolveTexture(QRhiTexture *tex)
void setDepthStencilBuffer(QRhiRenderBuffer *renderBuffer)
void setDepthTexture(QRhiTexture *texture)

Detaillierte Beschreibung

Ein Textur-Rendertarget hat null oder mehr Texturen als Farbanhänge, null oder einen Renderbuffer als kombinierten Tiefen-/Schablonenpuffer oder null oder eine Textur als Tiefenpuffer.

Hinweis: depthStencilBuffer() und depthTexture() können nicht beide gesetzt werden (können nicht gleichzeitig ungleich Null sein).

Schauen wir uns einige Anwendungsbeispiele in Kombination mit QRhiTextureRenderTarget an.

Dank der Konstruktoren ist es einfach, eine Textur (und keinen Tiefen-/Schablonenpuffer) als Ziel zu verwenden:

QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(256, 256), 1, QRhiTexture::RenderTarget);
texture->create();
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ texture }));

Im Folgenden wird ein Textur-Rendering-Ziel erstellt, das auf die Mip-Ebene #2 einer Textur ausgerichtet ist:

QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(512, 512), 1, QRhiTexture::RenderTarget | QRhiTexture::MipMapped);
texture->create();
QRhiColorAttachment colorAtt(texture);
colorAtt.setLevel(2);
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ colorAtt });

Ein weiteres Beispiel, diesmal zum Rendern in eine Tiefentextur:

QRhiTexture *shadowMap = rhi->newTexture(QRhiTexture::D32F, QSize(1024, 1024), 1, QRhiTexture::RenderTarget);
shadowMap->create();
QRhiTextureRenderTargetDescription rtDesc;
rtDesc.setDepthTexture(shadowMap);
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget(rtDesc);

Ein sehr häufiger Fall, bei dem eine Textur als Farbattachment und ein Renderbuffer als Tiefe/Schablone verwendet wird, um Tiefenprüfungen zu ermöglichen:

QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(512, 512), 1, QRhiTexture::RenderTarget);
texture->create();
QRhiRenderBuffer *depthStencil = rhi->newRenderBuffer(QRhiRenderBuffer::DepthStencil, QSize(512, 512));
depthStencil->create();
QRhiTextureRenderTargetDescription rtDesc({ texture }, depthStencil);
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget(rtDesc);

Um schließlich Multisample-Rendering auf portable Weise zu ermöglichen (und damit auch OpenGL ES 3.0 zu unterstützen), wird ein QRhiRenderBuffer als (Multisample-)Farbpuffer verwendet und dann in eine reguläre (Nicht-Multisample-)2D-Textur aufgelöst. Um eine Tiefenprüfung zu ermöglichen, wird auch ein Tiefenschablonenpuffer verwendet, der ebenfalls die gleiche Anzahl von Samples verwenden muss:

QRhiRenderBuffer *colorBuffer = rhi->newRenderBuffer(QRhiRenderBuffer::Color, QSize(512, 512), 4); // 4x MSAA
colorBuffer->create();
QRhiRenderBuffer *depthStencil = rhi->newRenderBuffer(QRhiRenderBuffer::DepthStencil, QSize(512, 512), 4);
depthStencil->create();
QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(512, 512), 1, QRhiTexture::RenderTarget);
texture->create();
QRhiColorAttachment colorAtt(colorBuffer);
colorAtt.setResolveTexture(texture);
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ colorAtt, depthStencil });

Hinweis: Wenn die Multisample-Auflösung aktiviert ist, werden die Multisample-Daten möglicherweise gar nicht ausgegeben. Das bedeutet, dass die Multisample-Textur in einem Farbanhang nicht nachträglich mit Shadern für Sampling (oder andere Zwecke) verwendet werden darf, wenn eine Resolve-Textur gesetzt ist, da der Multisample-Farbpuffer lediglich ein Zwischenspeicher ist, der auf einigen GPU-Architekturen überhaupt keine Daten zurückgeschrieben bekommt. Siehe PreserveColorContents für weitere Details.

Hinweis: Wenn Sie setDepthTexture() und nicht setDepthStencilBuffer() verwenden und die Tiefen-(Stencil-)Daten anschließend nicht von Interesse sind, setzen Sie das DoNotStoreDepthStencilContents-Flag auf QRhiTextureRenderTarget. Damit können Sie der zugrunde liegenden 3D-API mitteilen, dass die Tiefen-/Stencil-Daten verworfen werden können, was möglicherweise zu einer besseren Leistung bei gekachelten GPU-Architekturen führt. Wenn der Tiefen-/Stencil-Puffer ein QRhiRenderBuffer ist (und auch für die Multisample-Farbtextur, siehe vorherige Anmerkung), ist dies implizit, aber bei einem Tiefen-/Stencil-Puffer QRhiTexture muss die Absicht explizit angegeben werden. Standardmäßig geht QRhi davon aus, dass die Daten von Interesse sind (z. B. wird die Tiefentextur anschließend in einem Shader gesampelt).

Hinweis: Dies ist eine RHI-API mit begrenzten Kompatibilitätsgarantien, siehe QRhi für Details.

Siehe auch QRhiColorAttachment und QRhiTextureRenderTarget.

Dokumentation der Mitgliedsfunktionen

[constexpr noexcept] QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription()

Konstruiert eine leere Textur-Rendering-Zielbeschreibung.

QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment)

Konstruiert eine Textur-Rendering-Zielbeschreibung mit einem durch colorAttachment beschriebenen Anhang.

QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment, QRhiRenderBuffer *depthStencilBuffer)

Konstruiert eine Textur-Rendering-Zielbeschreibung mit zwei Anhängen, einem Farbanhang, der durch colorAttachment beschrieben wird, und einem Tiefen-/Schablonenanhang mit depthStencilBuffer.

QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment, QRhiTexture *depthTexture)

Konstruiert eine Textur-Rendering-Zielbeschreibung mit zwei Anhängen, einem Farbanhang, der durch colorAttachment beschrieben wird, und einem Tiefenanhang mit depthTexture.

Hinweis: depthTexture muss ein geeignetes Format haben, z. B. QRhiTexture::D16 oder QRhiTexture::D32F.

const QRhiColorAttachment *QRhiTextureRenderTargetDescription::cbeginColorAttachments() const

Gibt einen konstanten Iterator zurück, der auf das erste Element in der Anhangsliste zeigt.

const QRhiColorAttachment *QRhiTextureRenderTargetDescription::cendColorAttachments() const

Gibt einen konstanten Iterator zurück, der direkt auf das letzte Element in der Anhangsliste zeigt.

const QRhiColorAttachment *QRhiTextureRenderTargetDescription::colorAttachmentAt(qsizetype index) const

Gibt den Farbanhang unter der angegebenen index zurück.

qsizetype QRhiTextureRenderTargetDescription::colorAttachmentCount() const

Gibt die Anzahl der aktuell eingestellten Farbzuordnungen zurück.

[since 6.8] QRhiTexture *QRhiTextureRenderTargetDescription::depthResolveTexture() const

Gibt die Textur zurück, in die eine Multisample-Tiefen- (oder Tiefen-Stencil-) Textur (oder ein Textur-Array) aufgelöst ist. nullptr wenn es keine gibt, was der häufigste Fall ist.

Diese Funktion wurde in Qt 6.8 eingeführt.

Siehe auch setDepthResolveTexture(), QRhiColorAttachment::resolveTexture(), und depthTexture().

QRhiRenderBuffer *QRhiTextureRenderTargetDescription::depthStencilBuffer() const

Gibt den Renderbuffer zurück, der als Tiefenschablonenpuffer verwendet wird, oder nullptr, wenn keiner gesetzt wurde.

Siehe auch setDepthStencilBuffer().

QRhiTexture *QRhiTextureRenderTargetDescription::depthTexture() const

Gibt die aktuell referenzierte Tiefentextur zurück, oder nullptr, wenn keine festgelegt wurde.

Siehe auch setDepthTexture().

void QRhiTextureRenderTargetDescription::setColorAttachments(std::initializer_list<QRhiColorAttachment> list)

Legt die list von Farbanhängen fest.

template <typename InputIterator> void QRhiTextureRenderTargetDescription::setColorAttachments(InputIterator first, InputIterator last)

Legt die Liste der Farbanhänge über die Iteratoren first und last fest.

[since 6.8] void QRhiTextureRenderTargetDescription::setDepthResolveTexture(QRhiTexture *tex)

Setzt die tiefenauflösende Textur (oder Tiefenschablone) tex.

tex wird erwartet, dass es sich um eine 2D-Textur oder ein 2D-Textur-Array mit einem Format handelt, das der über setDepthTexture() festgelegten Textur entspricht.

Hinweis: Das Auflösen von Tiefen- (oder Tiefenschablonen-) Daten funktioniert nur, wenn das Feature ResolveDepthStencil zur Laufzeit als unterstützt gemeldet wird. Die Unterstützung für die Auflösung von Tiefenschablonen ist bei den Grafik-APIs nicht durchgängig verfügbar. Entwürfe, die von einer unbedingten Verfügbarkeit der Tiefenschablonenauflösung ausgehen, sind daher nicht portierbar und sollten vermieden werden.

Hinweis: Als zusätzliche Einschränkung, insbesondere für OpenGL ES, kann das Setzen einer tiefenauflösenden Textur nur in Kombination mit setDepthTexture() funktionieren, nicht mit setDepthStencilBuffer().

Diese Funktion wurde in Qt 6.8 eingeführt.

Siehe auch depthResolveTexture(), QRhiColorAttachment::setResolveTexture(), und setDepthTexture().

void QRhiTextureRenderTargetDescription::setDepthStencilBuffer(QRhiRenderBuffer *renderBuffer)

Legt die renderBuffer für depth-stencil fest. Nicht obligatorisch, z. B. wenn in den Grafikpipelines in einem der Rendering-Durchläufe für dieses Rendering-Ziel keine tiefenbezogenen Test-/Schreib- oder Stencil-Funktionen verwendet werden, kann dieser Wert auf nullptr gesetzt bleiben.

Hinweis: depthStencilBuffer() und depthTexture() können nicht gleichzeitig festgelegt werden (können nicht gleichzeitig ungültig sein).

Die Verwendung eines QRhiRenderBuffer über einem 2D QRhiTexture als Tiefen- oder Tiefen/Schablonenpuffer ist sehr üblich und wird für Anwendungen empfohlen. Die Verwendung von QRhiTexture und damit setDepthTexture() wird relevant, wenn auf die Tiefendaten später zugegriffen werden soll (z. B. in einem Shader) oder wenn multiview rendering beteiligt ist (weil die Tiefentextur dann ein Textur-Array sein muss).

Siehe auch depthStencilBuffer() und setDepthTexture().

void QRhiTextureRenderTargetDescription::setDepthTexture(QRhiTexture *texture)

Setzt die texture für Tiefenschablone. Dies ist eine Alternative zu setDepthStencilBuffer(), bei der anstelle von QRhiRenderBuffer ein QRhiTexture mit einem geeigneten Typ (z. B. QRhiTexture::D32F) angegeben wird.

Hinweis: depthStencilBuffer() und depthTexture() können nicht beide gesetzt werden (können nicht gleichzeitig ungleich Null sein).

texture kann entweder eine 2D-Textur oder ein 2D-Textur-Array sein (wenn Textur-Arrays unterstützt werden). Die Angabe eines Textur-Arrays ist insbesondere bei multiview rendering relevant.

Hinweis: Wenn texture ein Format mit einer Schablonenkomponente ist, wie z. B. QRhiTexture::D24S8, dient es auch als Schablonenpuffer.

Siehe auch depthTexture() und setDepthStencilBuffer().

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