QRhi Class

Dokumentation der Member-Funktionen

[noexcept] QRhi::~QRhi()

Destruktor. Löscht das Backend und gibt Ressourcen frei.

void QRhi::addCleanupCallback(const QRhi::CleanupCallback &callback)

Registriert eine ` callback `-Instanz, die aufgerufen wird, wenn die ` QRhi `-Instanz zerstört wird.

Der Callback wird ausgeführt, solange die Grafikressource noch verfügbar ist. Dies bietet der Anwendung die Möglichkeit, „ QRhiResource “-Instanzen, die zum „ QRhi “ gehören, ordnungsgemäß freizugeben. Dies ist besonders nützlich für die Verwaltung der Lebensdauer von Ressourcen, die in Objekten vom Typ „ cache “ gespeichert sind, wobei der Cache „QRhiResources“ oder Objekte enthält, die „QRhiResources“ enthalten.

Siehe auch ~QRhi().

void QRhi::addCleanupCallback(const void *key, const QRhi::CleanupCallback &callback)

Registriert „ callback “, damit diese Funktion aufgerufen wird, wenn „ QRhi “ zerstört wird. Diese Überladung nimmt einen undurchsichtigen Zeiger „ key “ entgegen, der sicherstellt, dass ein bestimmter Callback nur einmal registriert (und somit aufgerufen) wird.

Siehe auch ` removeCleanupCallback()`.

QRhi::Implementation QRhi::backend() const

Gibt den Backend-Typ für dieses „ QRhi “ zurück.

const char *QRhi::backendName() const

Gibt den Backend-Typ als Zeichenfolge für diese ` QRhi` zurück.

[static] const char *QRhi::backendName(QRhi::Implementation impl)

Gibt einen beschreibenden Namen für das Backend „ impl “ zurück, in der Regel den Namen der verwendeten 3D-API.

QRhi::FrameOpResult QRhi::beginFrame(QRhiSwapChain *swapChain, QRhi::BeginFrameFlags flags = {})

Startet einen neuen Frame, der auf den nächsten verfügbaren Puffer von „ swapChain “ abzielt.

Ein Frame besteht aus Ressourcenaktualisierungen und einem oder mehreren Render- und Rechen-Durchläufen.

flags kann bestimmte Sonderfälle angeben.

Das allgemeine Schema für das Rendern in eine „ QWindow “ mithilfe einer Swapchain:

• Erstellen Sie eine Swapchain.
• Rufen Sie ` QRhiSwapChain::createOrResize()` auf, sobald sich die Oberflächengröße gegenüber zuvor geändert hat.
• Rufen Sie „ QRhiSwapChain::destroy()“ auf „ QPlatformSurfaceEvent::SurfaceAboutToBeDestroyed “ auf.
• Anschließend bei jedem Frame:

  beginFrame(sc);
  updates = nextResourceUpdateBatch();
  updates->...
  QRhiCommandBuffer *cb = sc->currentFrameCommandBuffer();
  cb->beginPass(sc->currentFrameRenderTarget(), colorClear, dsClear, updates);
  ...
  cb->endPass();
  ... // more passes as necessary
  endFrame(sc);

Gibt bei Erfolg ` QRhi::FrameOpSuccess ` zurück, bei einem Fehler einen anderen Wert von ` QRhi::FrameOpResult `. Einige dieser Fehler sollten als „weiche“ Fehler behandelt werden, bei denen es heißt: „Später erneut versuchen“: Wenn ` QRhi::FrameOpSwapChainOutOfDate ` zurückgegeben wird, muss die Swapchain durch Aufruf von ` QRhiSwapChain::createOrResize()` in der Größe angepasst oder aktualisiert werden. Die Anwendung sollte dann versuchen, einen neuen Frame zu generieren. „ QRhi::FrameOpDeviceLost “ bedeutet, dass das Grafikgerät verloren gegangen ist; dies lässt sich jedoch möglicherweise beheben, indem alle Ressourcen, einschließlich des „ QRhi “ selbst, freigegeben und anschließend alle Ressourcen neu erstellt werden. Weitere Informationen finden Sie unter „ isDeviceLost()“.

Siehe auch endFrame(), beginOffscreenFrame() und isDeviceLost().

QRhi::FrameOpResult QRhi::beginOffscreenFrame(QRhiCommandBuffer **cb, QRhi::BeginFrameFlags flags = {})

Startet einen neuen Offscreen-Frame. Stellt einen Befehlspuffer bereit, der sich zur Aufzeichnung von Rendering-Befehlen in „ cb “ eignet. „ flags “ wird verwendet, um bestimmte Sonderfälle anzugeben, genau wie bei „ beginFrame()“.

Das Rendern ohne Swapchain ist ebenfalls möglich. Ein typischer Anwendungsfall ist der Einsatz in vollständig Offscreen-basierten Anwendungen, z. B. zur Erzeugung von Bildsequenzen durch Rendern und Zurücklesen, ohne jemals ein Fenster anzuzeigen.

Die Verwendung in On-Screen-Anwendungen (also „ beginFrame “, „ endFrame “, „beginOffscreenFrame“, „ endOffscreenFrame “, „ beginFrame “, …) ist ebenfalls möglich.

Wenn ein Readback über ` texture ` oder ` buffer ` geplant wurde, verhindern Offscreen-Frames, dass die CPU möglicherweise einen weiteren Frame generiert, während die GPU noch den vorherigen verarbeitet. Dies hat den Nebeneffekt, dass bei geplanten Readbacks die Ergebnisse garantiert verfügbar sind, sobald ` endOffscreenFrame()` zurückkehrt. Bei Frames, die auf eine Swapchain abzielen, ist dies nicht der Fall: Dort wird die GPU potenziell besser ausgelastet, doch die Arbeit mit Readback-Operationen erfordert mehr Sorgfalt seitens der Anwendung, da endFrame() – im Gegensatz zu endOffscreenFrame() – nicht garantiert, dass die Ergebnisse des Readbacks zu diesem Zeitpunkt verfügbar sind.

Das Grundgerüst für das Rendern eines Frames ohne Swapchain und das anschließende Zurücklesen des Frame-Inhalts könnte wie folgt aussehen:

QRhiReadbackResult rbResult;
QRhiCommandBuffer *cb;
rhi->beginOffscreenFrame(&cb);
cb->beginPass(rt, colorClear, dsClear);
// ...
u = nextResourceUpdateBatch();
u->readBackTexture(rb, &rbResult);
cb->endPass(u);
rhi->endOffscreenFrame();
// image data available in rbResult

Siehe auch endOffscreenFrame() und beginFrame().

QMatrix4x4 QRhi::clipSpaceCorrMatrix() const

Gibt eine Matrix zurück, mit der Anwendungen weiterhin OpenGL-spezifische Vertexdaten und perspektivische Projektionsmatrizen (wie beispielsweise die von QMatrix4x4::perspective() generierten) verwenden können, unabhängig vom aktiven Backend von QRhi.

In einem typischen Renderer können, sobald this_matrix * mvp anstelle von lediglich mvp verwendet wird, Vertex-Daten mit Y-Achse nach oben und Viewports mit einem Tiefenbereich von 0 bis 1 verwendet werden, ohne dass berücksichtigt werden muss, welches Backend (und damit welche Grafik-API) zur Laufzeit zum Einsatz kommt. Auf diese Weise lassen sich Verzweigungen auf Basis von ` isYUpInNDC()` und ` isClipDepthZeroToOne()` vermeiden (auch wenn eine solche Logik bei der Implementierung bestimmter fortgeschrittener Grafiktechniken dennoch erforderlich werden kann).

Auf dieser Seite finden Sie eine Erörterung des Themas aus der Perspektive von Vulkan.

[static] QRhi *QRhi::create(QRhi::Implementation impl, QRhiInitParams *params, QRhi::Flags flags, QRhiNativeHandles *importDevice, QRhiAdapter *adapter)

Gibt eine neue Instanz von ` QRhi ` zurück, deren Backend für die durch ` impl ` angegebene Grafik-API die angegebene ` flags` verwendet. Gibt ` nullptr ` zurück, wenn die Funktion fehlschlägt.

params muss auf eine Instanz einer der backend-spezifischen Unterklassen von ` QRhiInitParams` verweisen, wie beispielsweise ` QRhiVulkanInitParams`, ` QRhiMetalInitParams`, ` QRhiD3D11InitParams`, ` QRhiD3D12InitParams` oder ` QRhiGles2InitParams`. Beispiele zum Erstellen eines ` QRhi` finden Sie in den Beschreibungen dieser Klassen.

QRhi Implementiert grundsätzlich keine Fallback-Logik: Wenn die angegebene API nicht initialisiert werden kann, schlägt `create()` fehl, wobei die Backends Warnungen in der Debug-Ausgabe ausgeben. Die Clients von ` QRhi`, zum Beispiel ` Qt Quick`, können jedoch je nach Plattform zusätzliche Logik bereitstellen, die einen Fallback auf eine andere als die angeforderte API ermöglicht. Wenn lediglich geprüft werden soll, ob die Initialisierung beim späteren Aufruf von `create()` erfolgreich wäre, ist es vorzuziehen, ` probe()` anstelle von `create()` zu verwenden, da bei einigen Backends das Abfragen auf eine schlankere Weise implementiert werden kann als bei `create()`, das eine vollständige Initialisierung der Infrastruktur durchführt und verschwenderisch ist, wenn diese ` QRhi `-Instanz anschließend sofort verworfen wird.

importDevice Ermöglicht die Verwendung eines bereits vorhandenen Grafikgeräts, ohne dass QRhi ein eigenes erstellt. Wenn dieser Parameter nicht null ist, muss er auf eine Instanz einer der Unterklassen von QRhiNativeHandles verweisen: QRhiVulkanNativeHandles, QRhiD3D11NativeHandles, QRhiD3D12NativeHandles, QRhiMetalNativeHandles, QRhiGles2NativeHandles. Die genauen Details und die Semantik hängen vom Backend und der zugrunde liegenden Grafik-API ab.

Die Angabe eines „ QRhiAdapter “ in „ adapter “ bietet eine transparente, API-übergreifende Alternative zur Übergabe eines „ VkPhysicalDevice “ über „ QRhiVulkanNativeHandles “ oder einer Adapter-LUID über „ QRhiD3D12NativeHandles “. Die Eigentumsrechte an „ adapter “ werden nicht übernommen. Weitere Informationen zu diesem Ansatz finden Sie unter „ enumerateAdapters()“.

Siehe auch probe().

[static] QRhi *QRhi::create(QRhi::Implementation impl, QRhiInitParams *params, QRhi::Flags flags = {}, QRhiNativeHandles *importDevice = nullptr)

Entspricht create(impl, params, flags, importDevice, nullptr).

int QRhi::currentFrameSlot() const

Gibt während der Aufzeichnung eines Frames den aktuellen Frame-Slot-Index zurück. Der Wert ist nicht definiert, wenn die Funktion außerhalb eines aktiven Frames aufgerufen wird (d. h. wenn isRecordingFrame() auf „ false “ gesetzt ist).

Bei Backends wie Vulkan oder Metal liegt es in der Verantwortung des „ QRhi “-Backends, bei jedem Start eines neuen Frames zu blockieren, wenn festgestellt wird, dass die CPU der GPU bereits FramesInFlight - 1 Frames voraus ist (da der im Frame Nr. current – FramesInFlight übermittelte Befehlspuffer noch nicht abgeschlossen ist).

Ressourcen, die sich zwischen den Frames tendenziell ändern (wie beispielsweise das native Pufferobjekt, das einem QRhiBuffer vom Typ QRhiBuffer::Dynamic zugrunde liegt), existieren in mehreren Versionen, sodass jeder Frame – der übermittelt werden kann, während ein vorheriger noch verarbeitet wird – mit einer eigenen Kopie arbeitet. Dadurch wird vermieden, dass die Pipeline bei der Vorbereitung des Frames angehalten werden muss. (Der Inhalt einer Ressource, die möglicherweise noch auf der GPU genutzt wird, sollte nicht verändert werden; jedoch würde ein ständiges Warten auf den Abschluss des vorherigen Frames die GPU-Auslastung und letztlich die Leistung und Effizienz verringern.)

Konzeptionell ähnelt dies in gewisser Weise den „Copy-on-Write“-Verfahren, die von einigen C++-Containern und anderen Typen verwendet werden. Es könnte auch dem ähneln, was eine OpenGL- oder Direct 3D 11-Implementierung intern für bestimmte Objekttypen durchführt.

In der Praxis wird eine solche doppelte (oder dreifache) Pufferung von Ressourcen in den Backends von Vulkan, Metal und ähnlichen „ QRhi “-Backends dadurch realisiert, dass hinter einem „ QRhiResource “ eine feste Anzahl nativer Ressourcen (wie z. B. VkBuffer) slots bereitgestellt wird. Diese können dann durch einen Frame-Slot-Index indiziert werden, der von 0, 1, …, FramesInFlight-1 verläuft und dann wieder von vorne beginnt.

All dies wird für die Nutzer von QRhi transparent verwaltet. Anwendungen, die das Rendering direkt über die Grafik-API integrieren, möchten jedoch möglicherweise eine ähnliche Doppel- oder Dreifachpufferung ihrer eigenen Grafikressourcen durchführen. Dies lässt sich am einfachsten erreichen, indem man die Werte für die maximale Anzahl an in Bearbeitung befindlichen Frames (abrufbar über ` resourceLimit()`) und den aktuellen Frame- (Slot-)Index (von dieser Funktion zurückgegeben) kennt.

Siehe auch isRecordingFrame(), beginFrame() und endFrame().

QRhiDriverInfo QRhi::driverInfo() const

Gibt Metadaten für das Grafikgerät zurück, das von dieser erfolgreich initialisierten „ QRhi “-Instanz verwendet wird.

QRhi::FrameOpResult QRhi::endFrame(QRhiSwapChain *swapChain, QRhi::EndFrameFlags flags = {})

Beendet, übergibt und präsentiert einen Frame, der im letzten Aufruf von ` beginFrame()` auf ` swapChain` gestartet wurde.

Die doppelte (oder dreifache) Pufferung wird intern von „ QRhiSwapChain “ und „ QRhi “ verwaltet.

flags kann optional verwendet werden, um das Verhalten in bestimmter Weise zu ändern. Durch die Übergabe von ` QRhi::SkipPresent ` wird das Einreihen des `Present`-Befehls oder der Aufruf von `swapBuffers` übersprungen.

Gibt bei Erfolg QRhi::FrameOpSuccess zurück, bei einem Fehler einen anderen Wert von QRhi::FrameOpResult. Einige dieser Fehler sollten als „weiche“ Fehler vom Typ „Später erneut versuchen“ behandelt werden: Wenn QRhi::FrameOpSwapChainOutOfDate zurückgegeben wird, muss die Swapchain durch den Aufruf von QRhiSwapChain::createOrResize() in der Größe angepasst oder aktualisiert werden. Die Anwendung sollte dann versuchen, einen neuen Frame zu generieren. „ QRhi::FrameOpDeviceLost “ bedeutet, dass das Grafikgerät verloren gegangen ist; dies lässt sich jedoch möglicherweise beheben, indem alle Ressourcen, einschließlich der „ QRhi “ selbst, freigegeben und anschließend alle Ressourcen neu erstellt werden. Weitere Informationen finden Sie unter „ isDeviceLost()“.

Siehe auch beginFrame() und isDeviceLost().

QRhi::FrameOpResult QRhi::endOffscreenFrame(QRhi::EndFrameFlags flags = {})

Beendet den Vorgang, übermittelt die Daten und wartet gegebenenfalls auf den Offscreen-Frame.

Im Gegensatz zu „ endFrame()“ blockiert diese Funktion und wartet auf den Abschluss der GPU-seitigen Arbeit, wenn aktive Puffer- oder Textur-Readbacks vorliegen.

flags wird derzeit nicht verwendet.

Siehe auch ` beginOffscreenFrame()`.

[static, since 6.10] QRhi::AdapterList QRhi::enumerateAdapters(QRhi::Implementation impl, QRhiInitParams *params, QRhiNativeHandles *nativeHandles = nullptr)

Gibt die Liste der vorhandenen Adapter (physische Geräte) zurück oder eine leere Liste, wenn diese Steuerungsmöglichkeit bei der angegebenen Grafik-API nicht verfügbar ist.

Bei Backends, bei denen eine solche Steuerungsmöglichkeit nicht verfügbar ist, ist die zurückgegebene Liste immer leer. Eine leere Liste bedeutet daher nicht, dass sich keine Grafikgeräte im System befinden, sondern dass keine detaillierte Steuerung hinsichtlich der Auswahl des zu verwendenden Geräts möglich ist.

Bei Backends für Direct 3D 11, Direct 3D 12 und Vulkan ist davon auszugehen, dass sie die Aufzählung von Adaptern vollständig unterstützen. Bei anderen Backends ist dies möglicherweise nicht der Fall. Das Backend wird durch ` impl` angegeben. Ein von dieser Funktion zurückgegebenes ` QRhiAdapter ` darf nur in einem Aufruf von ` create()` mit demselben ` impl` verwendet werden. Einige zugrunde liegende APIs können weitere Einschränkungen aufweisen; insbesondere bei Vulkan ist das ` QRhiAdapter ` auf das ` QVulkanInstance ` festgelegt (`VkInstance`).

Vom Aufrufer wird erwartet, dass er die Objekte „ QRhiAdapter “ in der Liste löscht. Abgesehen von der Abfrage von „ info()“ besteht der einzige Zweck dieser Objekte darin, an „ create()“ oder die entsprechenden Funktionen in höheren Schichten wie „ Qt Quick “ übergeben zu werden.

Der folgende, speziell für Vulkan geschriebene Codeausschnitt zeigt, wie man die verfügbaren physikalischen Geräte auflistet und die Erstellung eines „ QRhi “ für das ausgewählte Gerät anfordert. Dies entspricht in der Praxis der Übergabe eines „ VkPhysicalDevice “ über ein „ QRhiVulkanNativeHandles “ an „ create()“, erfordert jedoch auf der Anwendungsseite weniger API-spezifischen Code:

QRhiVulkanInitParams initParams;
initParams.inst = &vulkanInstance;
QRhi::AdapterList adapters = QRhi::enumerateAdapters(QRhi::Vulkan, &initParams);
QRhiAdapter*chosenAdapter = nullptr;
for (QRhiAdapter*adapter: adapters) {
    if (looksGood(adapter->info())) {
        chosenAdapter = adapter;
        break;
    }
}
QRhi*rhi = QRhi::create(QRhi::Vulkan, &initParams, {}, nullptr, chosenAdapter);
qDeleteAll(adapters);

Die Übergabe von ` params ` ist aufgrund der Konzeption einiger der zugrunde liegenden Grafik-APIs erforderlich. Insbesondere bei Vulkan muss die ` QVulkanInstance ` angegeben werden, da ohne diese keine Aufzählung möglich ist. Andere Felder im backend-spezifischen ` params ` werden von dieser Funktion nicht tatsächlich verwendet.

nativeHandles ist optional. Wenn es angegeben wird, muss es sich um ein gültiges ` QRhiD3D11NativeHandles`, ` QRhiD3D12NativeHandles` oder ` QRhiVulkanNativeHandles` handeln, ähnlich wie bei ` create()`. Im Gegensatz zu ` create()` werden jedoch nur die Felder für das physische Gerät (im Fall von Vulkan) oder die Adapter-LUID (im Fall von D3D) verwendet; alle anderen Felder werden ignoriert. Dies kann genutzt werden, um die Ergebnisse auf einen bestimmten Adapter zu beschränken. Die zurückgegebene Liste enthält in diesem Fall 1 oder 0 Elemente.

Beachten Sie, dass die Implementierung der Funktion `looksGood()` im vorherigen Codeausschnitt keine plattformspezifische Filterung auf Basis der tatsächlichen Adapter- bzw. physischen Geräte-Identität durchführen kann, wie beispielsweise die Adapter-LUID unter Windows oder das `VkPhysicalDevice` bei Vulkan. Dies liegt daran, dass ` QRhiDriverInfo ` keine plattformspezifischen Daten enthält. Verwenden Sie stattdessen ` nativeHandles `, um die Ergebnisse bereits innerhalb von `enumerateAdapters()` gefiltert zu erhalten.

Die folgenden beiden Codeausschnitte, die Direct 3D 12 als Beispiel verwenden, sind in der Praxis gleichwertig:

// „enumerateAdapters“-basierter Ansatz ab Qt 6.10
QRhiD3D12InitParams initParams;
QRhiD3D12NativeHandles nativeHandles;
nativeHandles.adapterLuidLow = luid.LowPart; // LUID wurde von irgendwoher abgerufen, nun an Qt übergeben
nativeHandles.adapterLuidHigh = luid.HighPart;
QRhi::AdapterList adapters = QRhi::enumerateAdapters(QRhi::D3D12, &initParams, &nativeHandles);
if (adapters.isEmpty()) { qWarning(„Der angeforderte Adapter wurde nicht gefunden“); }
QRhi*rhi = QRhi::create(QRhi::D3D12, &initParams, {}, nullptr, adapters[0]);
qDeleteAll(adapters);

// traditional approach, more lightweight
QRhiD3D12InitParams initParams;
QRhiD3D12NativeHandles nativeHandles;
nativeHandles.adapterLuidLow = luid.LowPart; // retrieved a LUID from somewhere, now pass it on to Qt
nativeHandles.adapterLuidHigh = luid.HighPart;
QRhi *rhi = QRhi::create(QRhi::D3D12, &initParams, {}, &nativeHandles, nullptr);

Diese Funktion wurde in Qt 6.10 eingeführt.

Siehe auch „ create()“.

QRhi::FrameOpResult QRhi::finish()

Wartet, bis alle Aufgaben in der Grafikwarteschlange (sofern vorhanden) abgeschlossen sind, und führt anschließend alle zurückgestellten Operationen aus, wie z. B. das Abschließen von Readbacks und das Freigeben von Ressourcen. Kann innerhalb und außerhalb eines Frames aufgerufen werden, jedoch nicht innerhalb eines Passes. Innerhalb eines Frames bedeutet dies, dass alle Aufgaben im Befehlspuffer übermittelt werden.

bool QRhi::isClipDepthZeroToOne() const

Gibt „ true “ zurück, wenn die zugrunde liegende Grafik-API im Clip-Raum den Tiefenbereich [0, 1] verwendet.

false In der Praxis gilt dies nur für OpenGL, da OpenGL einen Tiefenbereich von [-1, 1] nach der Projektion verwendet. (Nicht zu verwechseln mit der durch `glDepthRange()` gesteuerten NDC-zu-Fenster-Zuordnung, die einen Bereich von [0, 1] verwendet, sofern dies nicht durch die ` QRhiViewport` überschrieben wird.) In einigen OpenGL-Versionen konnte glClipControl() verwendet werden, um dies zu ändern, aber das OpenGL-Backend von QRhi verwendet diese Funktion nicht, da sie in OpenGL ES oder OpenGL-Versionen unter 4.5 nicht verfügbar ist.

bool QRhi::isDeviceLost() const

Gibt „true“ zurück, wenn das Grafikgerät verloren gegangen ist.

Der Verlust des Geräts wird in der Regel in den Funktionen „ beginFrame()“, „ endFrame()“ oder „ QRhiSwapChain::createOrResize()“ erkannt, abhängig vom Backend und den zugrunde liegenden nativen APIs. Am häufigsten ist „ endFrame()“, da dort die Darstellung erfolgt. Bei einigen Backends kann auch „ QRhiSwapChain::createOrResize()“ aufgrund eines Geräteverlusts fehlschlagen. Daher wird diese Funktion als generische Möglichkeit bereitgestellt, um zu prüfen, ob bei einem vorherigen Vorgang ein Geräteverlust erkannt wurde.

Wenn das Gerät verloren gegangen ist, sollten keine weiteren Operationen über die ` QRhi` durchgeführt werden. Stattdessen sollten alle ` QRhi `-Ressourcen freigegeben und anschließend die ` QRhi` zerstört werden. Anschließend kann versucht werden, eine neue ` QRhi ` zu erstellen. Bei Erfolg müssen alle Grafikressourcen neu initialisiert werden. Ist dies nicht der Fall, versuchen Sie es später erneut – und wiederholen Sie den Vorgang so oft wie nötig.

Während einfache Anwendungen den Verlust eines Geräts möglicherweise ignorieren, kann es auf den gängigen Desktop-Plattformen aus verschiedenen Gründen zu einem Geräteverlust kommen, darunter das physische Trennen der Grafikkarte, das Deaktivieren des Geräts oder des Treibers, die Deinstallation oder Aktualisierung des Grafiktreibers oder Fehler, die zu einem Reset des Grafikgeräts führen. Einige dieser Ereignisse können auch unter völlig normalen Umständen auftreten; so ist beispielsweise die Aktualisierung des Grafiktreibers auf eine neuere Version eine gängige Aufgabe, die jederzeit während der Ausführung einer Qt-Anwendung stattfinden kann. Benutzer erwarten durchaus, dass Anwendungen dies überstehen, selbst wenn die Anwendung aktiv eine API wie OpenGL oder Direct3D nutzt.

Von den Qt-eigenen Frameworks, die auf QRhi aufbauen, wie beispielsweise Qt Quick, kann erwartet werden, dass sie den Verlust eines Geräts verarbeiten und geeignete Maßnahmen ergreifen. Sind die Daten für Grafikressourcen wie Texturen und Puffer auf der CPU-Seite noch verfügbar, ist ein solches Ereignis auf Anwendungsebene möglicherweise gar nicht wahrnehmbar, da die Grafikressourcen dann nahtlos neu initialisiert werden können. Von Anwendungen und Bibliotheken, die direkt mit QRhi arbeiten, wird jedoch erwartet, dass sie darauf vorbereitet sind, Situationen eines Geräteverlusts selbst zu prüfen und zu bewältigen.

bool QRhi::isFeatureSupported(QRhi::Feature feature) const

Gibt „ true “ zurück, wenn die angegebene „ feature “ unterstützt wird

bool QRhi::isRecordingFrame() const

Gibt „true“ zurück, wenn ein aktiver Frame vorhanden ist, d. h., wenn ein Aufruf von „ beginFrame()“ (oder „ beginOffscreenFrame()“) erfolgte, ohne dass bisher ein entsprechender Aufruf von „ endFrame()“ (oder „ endOffscreenFrame()“) stattgefunden hat.

Siehe auch currentFrameSlot(), beginFrame() und endFrame().

bool QRhi::isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags = {}) const

Gibt „ true “ zurück, wenn die angegebene Textur format, die durch flags modifiziert wurde, unterstützt wird.

Die Abfrage wird sowohl für unkomprimierte als auch für komprimierte Formate unterstützt.

bool QRhi::isYUpInFramebuffer() const

Gibt „ true “ zurück, wenn bei der zugrunde liegenden Grafik-API die Y-Achse in Framebuffern und Bildern nach oben zeigt.

In der Praxis ist dies nur für OpenGL der Wert „ true “.

bool QRhi::isYUpInNDC() const

Gibt „ true “ zurück, wenn die zugrunde liegende Grafik-API in ihrem normalisierten Gerätekordinatensystem die Y-Achse nach oben ausrichtet.

In der Praxis ist dies nur für Vulkan der Fall: ` false `.

bool QRhi::makeThreadLocalNativeContextCurrent()

Bei OpenGL wird dadurch der OpenGL-Kontext im aktuellen Thread als aktueller festgelegt. Bei anderen Backends hat die Funktion keine Auswirkung.

Der Aufruf dieser Funktion ist typischerweise im Qt-Framework-Code relevant, wenn sichergestellt werden muss, dass externer OpenGL-Code, der von der Anwendung bereitgestellt wird, weiterhin wie zuvor bei direkter Nutzung von OpenGL ausgeführt werden kann, solange der ` QRhi ` das OpenGL-Backend verwendet.

Gibt bei einem Fehler „false“ zurück, ähnlich wie „ QOpenGLContext::makeCurrent()“. Wenn der Vorgang fehlgeschlagen ist, kann „ isDeviceLost()“ aufgerufen werden, um festzustellen, ob ein Kontextverlust vorliegt. Eine solche Überprüfung entspricht der Überprüfung über „ QOpenGLContext::isValid()“.

Siehe auch QOpenGLContext::makeCurrent() und QOpenGLContext::isValid().

[static] int QRhi::mipLevelsForSize(const QSize &size)

Gibt die Anzahl der Mip-Stufen für eine bestimmte „ size “ zurück.

const QRhiNativeHandles *QRhi::nativeHandles()

Gibt einen Zeiger auf die backend-spezifische Sammlung nativer Objekte für das Gerät, den Kontext und ähnliche vom Backend verwendete Konzepte zurück.

Wandeln Sie den Zeiger je nach Bedarf in „ QRhiVulkanNativeHandles “, „ QRhiD3D11NativeHandles “, „ QRhiD3D12NativeHandles “, „ QRhiGles2NativeHandles “ oder „ QRhiMetalNativeHandles “ um.

QRhiBuffer *QRhi::newBuffer(QRhiBuffer::Type type, QRhiBuffer::UsageFlags usage, quint32 size)

Gibt einen neuen Puffer mit den angegebenen Werten für „ type “, „ usage “ und „ size “ zurück.

Siehe auch QRhiResource::destroy().

QRhiComputePipeline *QRhi::newComputePipeline()

Gibt eine neue Compute-Pipeline-Ressource zurück.

Siehe auch „ QRhiResource::destroy“ ().

QRhiGraphicsPipeline *QRhi::newGraphicsPipeline()

Gibt eine neue Grafik-Pipeline-Ressource zurück.

Siehe auch „ QRhiResource::destroy()“.

QRhiRenderBuffer *QRhi::newRenderBuffer(QRhiRenderBuffer::Type type, const QSize &pixelSize, int sampleCount = 1, QRhiRenderBuffer::Flags flags = {}, QRhiTexture::Format backingFormatHint = QRhiTexture::UnknownFormat)

Gibt einen neuen Renderbuffer mit den angegebenen Werten für „ type “, „ pixelSize “, „ sampleCount “ und „ flags “ zurück.

Wenn „ backingFormatHint “ auf ein anderes Texturformat als „ QRhiTexture::UnknownFormat “ gesetzt ist, kann es vom Backend verwendet werden, um zu entscheiden, welches Format für den Speicher hinter dem Renderbuffer verwendet werden soll.

Siehe auch QRhiResource::destroy().

QRhiSampler *QRhi::newSampler(QRhiSampler::Filter magFilter, QRhiSampler::Filter minFilter, QRhiSampler::Filter mipmapMode, QRhiSampler::AddressMode addressU, QRhiSampler::AddressMode addressV, QRhiSampler::AddressMode addressW = QRhiSampler::Repeat)

Gibt einen neuen Sampler mit dem angegebenen Vergrößerungsfilter magFilter, dem Verkleinerungsfilter minFilter, dem Mipmapping-Modus mipmapMode sowie den Adressierungs- (Wrap-)Modi addressU, addressV und addressW zurück.

Siehe auch ` QRhiResource::destroy()`.

QRhiShaderResourceBindings *QRhi::newShaderResourceBindings()

Gibt eine neue Shader-Ressourcen-Bindungs-Sammlungsressource zurück.

Siehe auch „ QRhiResource::destroy()“.

[since 6.9] QRhiShadingRateMap *QRhi::newShadingRateMap()

Gibt ein neues Shading-Rate-Map-Objekt zurück.

Diese Funktion wurde in Qt 6.9 eingeführt.

QRhiSwapChain *QRhi::newSwapChain()

Gibt eine neue Swapchain zurück.

Siehe auch QRhiResource::destroy() und QRhiSwapChain::createOrResize().

QRhiTexture *QRhi::newTexture(QRhiTexture::Format format, const QSize &pixelSize, int sampleCount = 1, QRhiTexture::Flags flags = {})

Gibt eine neue 1D- oder 2D-Textur mit den angegebenen Werten für „ format “, „ pixelSize “, „ sampleCount “ und „ flags “ zurück.

Bei einer 1D-Textur muss das Flag „ QRhiTexture::OneDimensional “ in „ flags “ gesetzt sein. Diese Funktion setzt dieses Flag implizit, wenn die Höhe von „ pixelSize “ 0 ist.

Siehe auch ` QRhiResource::destroy()`.

QRhiTexture *QRhi::newTexture(QRhiTexture::Format format, int width, int height, int depth, int sampleCount = 1, QRhiTexture::Flags flags = {})

Gibt eine neue 1D-, 2D- oder 3D-Textur mit den angegebenen Werten für „ format “, „ width “, „ height “, „ depth “, „ sampleCount “ und „ flags “ zurück.

Diese Überladung eignet sich für 3D-Texturen, da sie die Angabe von „ depth “ ermöglicht. Bei einer 3D-Textur muss „ QRhiTexture::ThreeDimensional “ in „ flags “ gesetzt sein; bei Verwendung dieser Überladung kann dies jedoch weggelassen werden, da das Flag implizit gesetzt wird, sobald „ depth “ größer als 0 ist. Für 1D-, 2D- und Würfeltexturen sollte „ depth “ auf 0 gesetzt werden.

Bei einer 1D-Textur muss „ QRhiTexture::OneDimensional “ in „ flags “ gesetzt sein. Diese Überladung setzt dieses Flag implizit, wenn sowohl „ height “ als auch „ depth “ den Wert 0 haben.

QRhiTexture *QRhi::newTextureArray(QRhiTexture::Format format, int arraySize, const QSize &pixelSize, int sampleCount = 1, QRhiTexture::Flags flags = {})

Gibt ein neues 1D- oder 2D-Textur-Array mit den angegebenen Werten für „ format “, „ arraySize “, „ pixelSize “, „ sampleCount “ und „ flags “ zurück.

Diese Funktion legt „ QRhiTexture::TextureArray “ implizit in „ flags “ fest.

Bei einem 1D-Textur-Array muss „ QRhiTexture::OneDimensional “ in „ flags “ gesetzt sein. Diese Funktion setzt dieses Flag implizit, wenn die Höhe von „ pixelSize “ 0 ist.

Siehe auch ` newTexture()`.

QRhiTextureRenderTarget *QRhi::newTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc, QRhiTextureRenderTarget::Flags flags = {})

Gibt ein neues Textur-Renderziel zurück, dessen Farb- und Tiefen-/Stencil-Anhänge in ` desc` angegeben sind und das die angegebene ` flags` enthält.

Siehe auch QRhiResource::destroy().

QRhiResourceUpdateBatch *QRhi::nextResourceUpdateBatch()

Gibt einen verfügbaren, leeren Batch zurück, in dem Operationen vom Typ „Kopie“ protokolliert werden können.

Da keine Bindung an einen aufgezeichneten Frame besteht, ist beispielsweise die folgende Abfolge zulässig:

rhi->beginFrame(swapchain);
QRhiResourceUpdateBatch *u = rhi->nextResourceUpdateBatch();
u->uploadStaticBuffer(buf, data);
// ... do not commit the batch
rhi->endFrame();
// u stays valid (assuming buf stays valid as well)
rhi->beginFrame(swapchain);
swapchain->currentFrameCommandBuffer()->resourceUpdate(u);
// ... draw with buf
rhi->endFrame();

QByteArray QRhi::pipelineCacheData()

Gibt einen binären Daten-Blob zurück, der Daten enthält, die von den während der Laufzeit dieses QRhi erfolgreich erstellten QRhiGraphicsPipeline und QRhiComputePipeline gesammelt wurden.

Durch das Speichern und anschließende Neuladen der Cache-Daten bei nachfolgenden Ausführungen derselben Anwendung lassen sich die Erstellungszeiten für Pipelines und Shader potenziell verkürzen. Was genau der Cache und seine serialisierte Version enthalten, ist nicht festgelegt, hängt immer vom verwendeten Backend ab und ist in einigen Fällen auch von der jeweiligen Implementierung der Grafik-API abhängig.

Wenn das „ PipelineCacheDataLoadSave “ als nicht unterstützt gemeldet wird, ist das zurückgegebene „ QByteArray “ leer.

Wurde das Flag „ EnablePipelineCacheDataSave “ beim Aufruf von ` create()` nicht angegeben, kann das zurückgegebene ` QByteArray ` leer sein, selbst wenn die Funktion „ PipelineCacheDataLoadSave “ unterstützt wird.

Sind die zurückgegebenen Daten nicht leer, sind sie stets spezifisch für die Qt-Version und das „ QRhi “-Backend. Zudem besteht in manchen Fällen eine starke Abhängigkeit vom Grafikgerät und der genau verwendeten Treiberversion. ` QRhi ` sorgt für das Hinzufügen der entsprechenden Header und Sicherheitsvorkehrungen, die gewährleisten, dass die Daten stets sicher an ` setPipelineCacheData()` übergeben werden können; daher wird der Versuch, Daten aus einem Lauf mit einer anderen Treiberversion zu laden, sicher und reibungslos abgewickelt.

Weitere Details zu dieser Funktion finden Sie unter EnablePipelineCacheDataSave.

Siehe auch setPipelineCacheData(), create() und isFeatureSupported().

[static] bool QRhi::probe(QRhi::Implementation impl, QRhiInitParams *params)

Gibt „true“ zurück, wenn davon ausgegangen werden kann, dass der Aufruf von ` create()` erfolgreich ist, wenn die angegebenen ` impl ` und ` params` aufgerufen werden.

Bei einigen Backends entspricht dies dem Aufruf von ` create()`, der Überprüfung des Rückgabewerts und dem anschließenden Löschen des resultierenden ` QRhi`.

Bei anderen, insbesondere bei Metal, gibt es möglicherweise eine spezielle Prüfimplementierung, die ein leichteres Testen ermöglicht, ohne die Debug-Ausgabe bei Fehlern mit Warnungen zu überladen.

Siehe auch ` create()`.

void QRhi::releaseCachedResources()

Versucht, Ressourcen in den Caches des Backends freizugeben. Dies kann sowohl CPU- als auch GPU-Ressourcen umfassen. Es werden nur Speicher und Ressourcen berücksichtigt, die automatisch neu erstellt werden können. Wenn beispielsweise die Implementierung von „ QRhiGraphicsPipeline “ im Backend einen Cache mit den Ergebnissen der Shader-Kompilierung verwaltet, führt der Aufruf dieser Funktion dazu, dass dieser Cache geleert wird, wodurch möglicherweise Speicher und Grafikressourcen freigegeben werden.

Der Aufruf dieser Funktion ist in Umgebungen mit begrenzten Ressourcen sinnvoll, in denen ab einem bestimmten Punkt ein minimaler Ressourcenverbrauch auf Kosten der Leistung gewährleistet werden muss.

void QRhi::removeCleanupCallback(const void *key)

Hebt die Registrierung des Callbacks mit „ key “ auf. Wenn kein Cleanup-Callback mit „ key “ registriert wurde, führt die Funktion keine Aktion aus. Callbacks, die ohne Schlüssel registriert wurden, können nicht entfernt werden.

Siehe auch addCleanupCallback().

int QRhi::resourceLimit(QRhi::ResourceLimit limit) const

Gibt den Wert für die angegebene Ressource limit zurück.

Es wird davon ausgegangen, dass die Werte bei der Initialisierung von den Backends abgefragt werden, sodass der Aufruf dieser Funktion nur einen geringen Aufwand darstellt.

void QRhi::setPipelineCacheData(const QByteArray &data)

Lädt „ data “ in den Pipeline-Cache, sofern zutreffend.

Wenn „ PipelineCacheDataLoadSave “ als nicht unterstützt gemeldet wird, kann die Funktion gefahrlos aufgerufen werden, hat jedoch keine Auswirkung.

Der von ` pipelineCacheData()` zurückgegebene Blob ist immer spezifisch für die Qt-Version, das „ QRhi “-Backend und in manchen Fällen auch für das Grafikgerät sowie eine bestimmte Version des Grafiktreibers. ` QRhi ` sorgt für das Hinzufügen des entsprechenden Headers und für Sicherheitsvorkehrungen, die gewährleisten, dass die Daten stets sicher an diese Funktion übergeben werden können. Bei einer Nichtübereinstimmung, z. B. weil der Treiber auf eine neuere Version aktualisiert wurde oder weil die Daten von einem anderen „ QRhi “-Backend generiert wurden, wird eine Warnung ausgegeben und „ data “ sicher ignoriert.

Bei Vulkan entspricht dies direkt dem `VkPipelineCache`. Der Aufruf dieser Funktion erstellt ein neues Vulkan-Pipeline-Cache-Objekt, dessen Anfangsdaten aus ` data` stammen. Das Pipeline-Cache-Objekt wird dann von allen nachfolgend erstellten ` QRhiGraphicsPipeline `- und ` QRhiComputePipeline `-Objekten verwendet, wodurch die Erstellung der Pipeline potenziell beschleunigt wird.

Bei anderen APIs gibt es keinen eigentlichen Pipeline-Cache, jedoch stellen sie möglicherweise einen Cache mit Bytecode aus Shader-Kompilierungen (D3D) oder Programm-Binärdateien (OpenGL) bereit. In Anwendungen, die zur Laufzeit zahlreiche Shader-Kompilierungen aus dem Quellcode durchführen, kann dies bei nachfolgenden Durchläufen zu einer erheblichen Leistungssteigerung führen, wenn der „Pipeline-Cache“ mithilfe dieser Funktion aus einem früheren Durchlauf vorab befüllt wurde.

Weitere Details zu dieser Funktion finden Sie unter EnablePipelineCacheDataSave.

Siehe auch ` pipelineCacheData()` und ` isFeatureSupported()`.

[since 6.9] void QRhi::setQueueSubmitParams(QRhiNativeHandles *params)

In Verbindung mit Backends und Grafik-APIs, sofern zutreffend, ermöglicht diese Funktion die Übergabe zusätzlicher Argumente bei der nächsten Übermittlung von Befehlen an die Grafikbefehlswarteschlange.

Insbesondere bei Vulkan ermöglicht dies die Übergabe einer Liste von Vulkan-Semaphor-Objekten an ` vkQueueSubmit() `, auf deren Signale gewartet und die signalisiert werden sollen. ` params ` muss dabei ein ` QRhiVulkanQueueSubmitParams` sein. Dies ist in bestimmten fortgeschrittenen Anwendungsfällen unerlässlich, beispielsweise bei der Ausführung nativer Vulkan-Aufrufe, bei denen auf `VkSemaphores` gewartet und diese signalisiert werden müssen, die vom benutzerdefinierten Vulkan-Rendering- oder Rechencode der Anwendung verwaltet werden. Darüber hinaus ermöglicht dies auch die Angabe zusätzlicher Semaphoren, auf die bei der nächsten „ vkQueuePresentKHR() “-Aufgabe gewartet werden soll.

Bei vielen anderen Backends ist die Implementierung dieser Funktion eine No-Op.

Diese Funktion wurde in Qt 6.9 eingeführt.

[static] QSize QRhi::sizeForMipLevel(int mipLevel, const QSize &baseLevelSize)

Gibt die Größe des Texturbildes für ein bestimmtes ` mipLevel` zurück, berechnet auf der Grundlage der in ` baseLevelSize` angegebenen Größe der Ebene 0.

QRhiStats QRhi::statistics() const

Erfasst und gibt Statistiken zu den Zugriffszeiten und der Zuweisung von Grafikressourcen zurück.

Daten zur Speicherzuweisung sind nur bei einigen Backends verfügbar, bei denen solche Vorgänge unter der Kontrolle von Qt stehen. Bei Grafik-APIs, bei denen keine Kontrolle auf niedrigerer Ebene über die Zuweisung von Speicherressourcen besteht, wird dies niemals unterstützt, und alle relevanten Felder in den Ergebnissen sind 0.

Insbesondere bei Vulkan sind die Werte stets gültig und werden aus der zugrunde liegenden Speicherzuweisungsbibliothek abgefragt. Dies gibt Aufschluss über den Speicherbedarf der aktiven Puffer und Texturen.

Das Gleiche gilt für Direct 3D 12. Zusätzlich zu den Statistiken der Speicherzuweisungsbibliothek enthält das Ergebnis hier auch ein Feld „ totalUsageBytes “, das die Gesamtgröße einschließlich zusätzlicher Ressourcen angibt, die nicht unter der Kontrolle der Speicherzuweisungsbibliothek stehen (Swapchain-Puffer, Descriptor-Heaps usw.), wie von DXGI gemeldet.

Die Werte entsprechen der Summe aller verwendeten Speichertypen (d. h. Grafik- und Systemspeicher im Falle einer diskreten GPU).

Zusätzliche Daten, wie beispielsweise die Gesamtzeit in Millisekunden, die für die Erstellung von Grafik- und Rechenpipelines aufgewendet wurde (was in der Regel Shader-Kompilierung oder Cache-Abfragen und potenziell rechenintensive Vorgänge umfasst), sind bei den meisten Backends verfügbar.

QList<int> QRhi::supportedSampleCounts() const

Gibt die Liste der unterstützten Sample-Zahlen zurück.

Ein typisches Beispiel wäre (1, 2, 4, 8).

Bei manchen Backends ist diese Liste der unterstützten Werte im Voraus festgelegt, während bei anderen die (physikalischen) Geräteeigenschaften angeben, was zur Laufzeit unterstützt wird.

Siehe auch QRhiRenderBuffer::setSampleCount(), QRhiTexture::setSampleCount(), QRhiGraphicsPipeline::setSampleCount() und QRhiSwapChain::setSampleCount().

[since 6.9] QList<QSize> QRhi::supportedShadingRates(int sampleCount) const

Gibt die Liste der unterstützten variablen Schattierungsraten für die angegebene „ sampleCount “ zurück.

1x1 wird immer unterstützt.

Diese Funktion wurde in Qt 6.9 eingeführt.

QThread *QRhi::thread() const

Gibt den Thread zurück, auf dem die Funktion „ QRhi “ aufgerufen wurde initialized.

int QRhi::ubufAligned(int v) const

Gibt den Wert (in der Regel einen Offset) „ v “ zurück, der an die durch „ ubufAlignment()“ angegebene einheitliche Pufferausrichtung angepasst ist.

int QRhi::ubufAlignment() const

Gibt den minimalen Offset für die Ausrichtung eines einheitlichen Puffers in Byte zurück. Dieser beträgt in der Regel 256.

Der Versuch, einen Bereich des einheitlichen Puffers mit einem Offset zu binden, der nicht an diesen Wert ausgerichtet ist, führt je nach Backend und der zugrunde liegenden Grafik-API zu Fehlern.

Siehe auch „ ubufAligned()“.

[static] QRhiSwapChainProxyData QRhi::updateSwapChainProxyData(QRhi::Implementation impl, QWindow *window)

Erzeugt und gibt eine ` QRhiSwapChainProxyData `-Struktur zurück, die undurchsichtige Daten enthält, die für das Backend und die Grafik-API spezifisch sind, die durch ` impl` angegeben werden. ` window ` ist die ` QWindow `, auf die eine Swapchain abzielt.

Die zurückgegebene Struktur kann an ` QRhiSwapChain::setProxyData()` übergeben werden. Dies ist in Rendering-Systemen mit Threads sinnvoll: Diese statische Funktion soll – im Gegensatz zu allen Operationen unter ` QRhi ` – im Haupt- (GUI-)Thread aufgerufen, anschließend an den Thread übertragen werden, der mit dem ` QRhi ` und dem ` QRhiSwapChain ` arbeitet, und schließlich an die Swapchain weitergeleitet werden. Dies ermöglicht native Plattformabfragen, deren Aufruf nur im Hauptthread sicher ist – beispielsweise die Abfrage des `CAMetalLayer` aus einer `NSView` –, sowie die anschließende Weitergabe der Daten an die ` QRhiSwapChain `, die im Rendering-Thread ausgeführt wird. Im Metal-Beispiel löst der Zugriff auf `view.layer` in einem dedizierten Rendering-Thread eine Warnung im Xcode-Thread-Checker aus. Mit dem Daten-Proxy-Mechanismus wird dies vermieden.

Wenn keine Threads beteiligt sind, ist das Erstellen und Weiterleiten des „ QRhiSwapChainProxyData “ nicht erforderlich: Es ist gewährleistet, dass Backends alles Notwendige selbst abfragen können, und wenn sich alles auf dem Haupt- (GUI-)Thread befindet, sollte dies ausreichen.