QRhi Class

Dokumentation der Mitgliedsfunktionen

[noexcept] QRhi::~QRhi()

Destruktor. Zerstört das Backend und gibt die Ressourcen frei.

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

Registriert eine callback, die entweder aufgerufen wird, wenn QRhi zerstört wird, oder wenn runCleanup() aufgerufen wird.

Der Callback wird ausgeführt, wenn die Grafikressource noch verfügbar ist, so dass die Anwendung die Möglichkeit hat, QRhiResource Instanzen, die zu QRhi gehören, sauber freizugeben. Dies ist besonders nützlich für die Verwaltung der Lebensdauer von Ressourcen, die in Objekten vom Typ cache gespeichert sind, wo der Cache QRhiResources oder Objekte enthält, die QRhiResources enthalten.

Siehe auch runCleanup() und ~QRhi().

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

Dies ist eine überladene Funktion.

Registriert callback, um entweder aufgerufen zu werden, wenn QRhi zerstört wird oder wenn runCleanup() aufgerufen wird. Diese Überladung nimmt einen undurchsichtigen Zeiger, key, der verwendet wird, um sicherzustellen, dass ein gegebener Rückruf nur einmal registriert (und somit aufgerufen) wird.

Siehe auch removeCleanupCallback().

QRhi::Implementation QRhi::backend() const

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

const char *QRhi::backendName() const

Gibt den Backend-Typ als String für dieses QRhi zurück.

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

Gibt einen freundlichen Namen für das Backend impl zurück, normalerweise 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 Berechnungsdurchläufen.

flags kann auf bestimmte Sonderfälle hinweisen.

Das High-Level-Muster des Renderings in eine QWindow unter Verwendung einer Swapchain:

• Erstellen Sie eine Swapchain.
• Rufen Sie QRhiSwapChain::createOrResize() immer dann auf, wenn die Oberflächengröße anders ist als zuvor.
• Rufen Sie QRhiSwapChain::destroy() auf QPlatformSurfaceEvent::SurfaceAboutToBeDestroyed auf.
• Dann 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);

Bei Erfolg wird QRhi::FrameOpSuccess zurückgegeben, bei einem Fehler ein anderer Wert QRhi::FrameOpResult. Einige dieser Fehler sollten als weiche Fehler der Art "Versuchen Sie es später noch einmal" behandelt werden: Wenn QRhi::FrameOpSwapChainOutOfDate zurückgegeben wird, muss die Swapchain durch Aufruf von QRhiSwapChain::createOrResize() in der Größe verändert oder aktualisiert werden. Die Anwendung sollte dann versuchen, einen neuen Frame zu erzeugen. QRhi::FrameOpDeviceLost bedeutet, dass das Grafikgerät verloren ist, aber dies kann auch wiederhergestellt werden, indem alle Ressourcen, einschließlich QRhi selbst, freigegeben werden und dann alle Ressourcen neu erstellt werden. Siehe isDeviceLost() für weitere Informationen.

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 für die Aufzeichnung von Rendering-Befehlen in cb geeignet ist. flags wird verwendet, um bestimmte Sonderfälle anzuzeigen, genau wie bei beginFrame().

Rendering ohne Swapchain ist ebenfalls möglich. Der typische Anwendungsfall ist die Verwendung in Anwendungen außerhalb des Bildschirms, z. B. zum Erzeugen von Bildsequenzen durch Rendering und Rücklesen, ohne jemals ein Fenster anzuzeigen.

Die Verwendung in Onscreen-Anwendungen (also beginFrame, endFrame, beginOffscreenFrame, endOffscreenFrame, beginFrame, ...) ist ebenfalls möglich, reduziert aber die Parallelität und sollte daher nur selten eingesetzt werden.

Offscreen-Frames erlauben es der CPU nicht, einen weiteren Frame zu erzeugen, während die GPU noch den vorherigen verarbeitet. Dies hat den Nebeneffekt, dass die Ergebnisse garantiert zur Verfügung stehen, sobald endOffscreenFrame() zurückkehrt, wenn Readbacks geplant sind. Das ist bei Frames, die auf eine Swapchain abzielen, nicht der Fall: Hier wird die GPU potenziell besser ausgenutzt, aber die Arbeit mit Readback-Operationen erfordert von der Anwendung mehr Sorgfalt, 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, die verwendet werden kann, um Anwendungen die Verwendung von OpenGL-gezielten Scheitelpunktdaten und perspektivischen Projektionsmatrizen zu ermöglichen (wie z.B. die, die von QMatrix4x4::perspective() erzeugt werden), unabhängig vom aktiven QRhi Backend.

In einem typischen Renderer können, sobald this_matrix * mvp anstelle von mvp verwendet wird, Scheitelpunktdaten mit Y nach oben und Ansichtsfenster mit Tiefenbereich 0 - 1 verwendet werden, ohne zu berücksichtigen, welches Backend (und damit Grafik-API) zur Laufzeit verwendet wird. Auf diese Weise können Verzweigungen, die auf isYUpInNDC() und isClipDepthZeroToOne() basieren, vermieden werden (obwohl eine solche Logik bei der Implementierung bestimmter fortgeschrittener Grafiktechniken dennoch erforderlich sein kann).

Siehe diese Seite für eine Diskussion des Themas aus der Sicht von Vulkan.

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

Gibt eine neue QRhi -Instanz mit einem Backend für die durch impl angegebene Grafik-API mit dem angegebenen flags zurück. Gibt nullptr zurück, wenn die Funktion fehlschlägt.

params muss auf eine Instanz einer der Backend-spezifischen Unterklassen von QRhiInitParams verweisen, z. B. QRhiVulkanInitParams, QRhiMetalInitParams, QRhiD3D11InitParams, QRhiD3D12InitParams, QRhiGles2InitParams. Siehe diese Klassen für Beispiele zur Erstellung einer QRhi.

QRhi Die Funktion create() implementiert von Haus aus keine Fallback-Logik: Wenn die angegebene API nicht initialisiert werden kann, schlägt create() fehl und die Backends geben Warnungen in der Debug-Ausgabe aus. Die Clients von QRhi, z. B. Qt Quick, können jedoch zusätzliche Logik bereitstellen, die je nach Plattform einen Rückgriff auf eine andere als die angeforderte API ermöglicht. Wenn die Absicht nur darin besteht, zu testen, ob die Initialisierung erfolgreich ist, wenn man create() zu einem späteren Zeitpunkt aufruft, ist es vorzuziehen, probe() anstelle von create() zu verwenden, weil mit einigen Backends probing in einer leichtgewichtigeren Art und Weise implementiert werden kann, im Gegensatz zu create(), das eine vollständige Initialisierung der Infrastruktur durchführt und verschwenderisch ist, wenn diese QRhi Instanz dann sofort weggeworfen wird.

importDevice erlaubt die Verwendung eines bereits existierenden Grafikgeräts, ohne dass QRhi ein eigenes Gerät erstellt. Wenn nicht null, muss dieser Parameter auf eine Instanz einer der Unterklassen von QRhiNativeHandles zeigen: QRhiVulkanNativeHandles, QRhiD3D11NativeHandles, QRhiD3D12NativeHandles, QRhiMetalNativeHandles, QRhiGles2NativeHandles. Die genauen Details und die Semantik hängen vom Backand und der zugrunde liegenden Grafik-API ab.

Siehe auch probe().

int QRhi::currentFrameSlot() const

Gibt den aktuellen Frame-Slot-Index während der Aufnahme eines Frames zurück. Nicht spezifiziert, wenn der Aufruf außerhalb eines aktiven Frames erfolgt (d.h. wenn isRecordingFrame() false ist).

Bei Backends wie Vulkan oder Metal liegt es in der Verantwortung des QRhi Backends, zu blockieren, wenn ein neuer Frame gestartet wird und die CPU bereits FramesInFlight - 1 Frames vor der GPU liegt (weil der in Frame Nr. current - FramesInFlight übermittelte Befehlspuffer noch nicht abgeschlossen ist).

Ressourcen, die sich von Frame zu Frame ändern können (z. B. das native Pufferobjekt, das ein QRhiBuffer mit dem Typ QRhiBuffer::Dynamic unterstützt), existieren in mehreren Versionen, so dass jeder Frame, der übermittelt werden kann, während ein vorheriger noch verarbeitet wird, mit seiner eigenen Kopie arbeitet, wodurch die Notwendigkeit vermieden wird, die Pipeline bei der Vorbereitung des Frames anzuhalten. (Der Inhalt einer Ressource, die möglicherweise noch in der GPU verwendet wird, sollte nicht angetastet werden, aber einfach immer zu warten, bis das vorherige Bild fertig ist, würde die GPU-Auslastung und letztlich die Leistung und Effizienz verringern).

Vom Konzept her ähnelt dies in gewisser Weise den Copy-on-Write-Schemata, die von einigen C++-Containern und anderen Typen verwendet werden. Es kann auch dem ähneln, was eine OpenGL- oder Direct 3D 11-Implementierung intern für bestimmte Arten von Objekten durchführt.

In der Praxis wird eine solche doppelte (oder dreifache) Pufferung von Ressourcen in den Backends von Vulkan, Metal und ähnlichen QRhi realisiert, indem eine feste Anzahl von nativen Ressourcen (z. B. VkBuffer) slots hinter einem QRhiResource liegt. Diese können dann durch einen Frame-Slot-Index indiziert werden, der mit 0, 1, ..., FramesInFlight-1 läuft, und dann herumgewickelt werden.

All dies wird für die Benutzer von QRhi transparent gehandhabt. Anwendungen, die das Rendering direkt in die Grafik-API integrieren, möchten jedoch möglicherweise eine ähnliche doppelte oder dreifache Pufferung ihrer eigenen Grafikressourcen durchführen. Das lässt sich am einfachsten erreichen, wenn man die Werte für die maximale Anzahl von Frames während des Fluges (abrufbar über resourceLimit()) und den aktuellen Frame-(Slot-)Index (zurückgegeben von dieser Funktion) kennt.

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

QRhiDriverInfo QRhi::driverInfo() const

Gibt Metadaten für das von dieser erfolgreich initialisierten QRhi -Instanz verwendete Grafikgerät zurück.

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

Beendet, überträgt und präsentiert einen Frame, der im letzten beginFrame() auf swapChain begonnen wurde.

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

flags kann optional verwendet werden, um das Verhalten auf bestimmte Weise zu ändern. Die Übergabe von QRhi::SkipPresent überspringt das Einreihen in die Warteschlange des Present-Befehls oder den Aufruf von swapBuffers.

Gibt bei Erfolg QRhi::FrameOpSuccess oder bei einem Fehler einen anderen Wert QRhi::FrameOpResult zurück. Einige dieser Fehler sollten als weiche Fehler der Art "Versuchen Sie es später noch einmal" behandelt werden: Wenn QRhi::FrameOpSwapChainOutOfDate zurückgegeben wird, muss die Swapchain durch Aufruf von QRhiSwapChain::createOrResize() in der Größe verändert oder aktualisiert werden. Die Anwendung sollte dann versuchen, einen neuen Frame zu erzeugen. QRhi::FrameOpDeviceLost bedeutet, dass das Grafikgerät verloren ist, aber dies kann auch wiederhergestellt werden, indem alle Ressourcen, einschließlich QRhi selbst, freigegeben werden und dann alle Ressourcen neu erstellt werden. Siehe isDeviceLost() für weitere Informationen.

Siehe auch beginFrame() und isDeviceLost().

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

Beendet, übergibt und wartet auf den Offscreen-Frame.

flags wird derzeit nicht verwendet.

Siehe auch beginOffscreenFrame().

QRhi::FrameOpResult QRhi::finish()

Wartet auf den Abschluss aller Arbeiten in der Grafikwarteschlange (sofern zutreffend) und führt dann alle aufgeschobenen Vorgänge aus, wie z. B. den Abschluss von Rücklesungen und Ressourcenfreigaben. Kann innerhalb und außerhalb eines Frames aufgerufen werden, jedoch nicht innerhalb eines Passes. Innerhalb eines Frames bedeutet dies, dass die Arbeit am Befehlspuffer abgeschlossen wird.

bool QRhi::isClipDepthZeroToOne() const

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

In der Praxis ist dies false nur für OpenGL, da OpenGL einen Post-Projection-Tiefenbereich von [-1, 1] verwendet. (nicht zu verwechseln mit der NDC-zu-Fenster-Zuordnung, die von glDepthRange() gesteuert wird, die einen Bereich von [0, 1] verwendet, es sei denn, sie wird von QRhiViewport überschrieben.) In einigen OpenGL-Versionen könnte 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 kleiner als 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 beginFrame(), endFrame() oder QRhiSwapChain::createOrResize() erkannt, je nach Backend und den zugrunde liegenden nativen APIs. Am gebräuchlichsten ist endFrame(), da dort die Präsentation stattfindet. Bei einigen Backends kann QRhiSwapChain::createOrResize() auch aufgrund eines Geräteausfalls fehlschlagen. Daher wird diese Funktion als generische Möglichkeit bereitgestellt, um zu prüfen, ob ein Geräteverlust durch eine frühere Operation erkannt wurde.

Wenn das Gerät verloren gegangen ist, sollten keine weiteren Operationen über QRhi durchgeführt werden. Stattdessen sollten alle QRhi -Ressourcen freigegeben werden, gefolgt von der Zerstörung von QRhi. Anschließend kann versucht werden, ein neues QRhi zu erstellen. Ist dies erfolgreich, müssen alle Grafikressourcen neu initialisiert werden. Wenn nicht, versuchen Sie es später noch einmal, wiederholt.

Während einfache Anwendungen sich nicht um einen Geräteverlust kümmern müssen, kann ein Geräteverlust auf den gängigen Desktop-Plattformen aus verschiedenen Gründen auftreten, z. B. durch physisches Trennen des Grafikadapters, Deaktivieren des Geräts oder des Treibers, Deinstallieren oder Aktualisieren des Grafiktreibers oder aufgrund von Fehlern, die zu einem Reset des Grafikgeräts führen. Einige dieser Gründe können auch unter ganz normalen Umständen auftreten, z.B. ist die Aktualisierung des Grafiktreibers auf eine neuere Version eine übliche Aufgabe, die jederzeit während der Ausführung einer Qt-Anwendung erfolgen kann. Die Benutzer können sehr wohl erwarten, dass die Anwendungen dies überstehen, selbst wenn die Anwendung aktiv eine API wie OpenGL oder Direct3D verwendet.

Von den Qt-eigenen Frameworks, die auf QRhi aufbauen, wie z.B. Qt Quick, kann erwartet werden, dass sie mit einem Geräteverlust umgehen und entsprechende Maßnahmen ergreifen. Wenn die Daten für Grafikressourcen, wie Texturen und Puffer, auf der CPU-Seite noch verfügbar sind, wird ein solches Ereignis auf der Anwendungsebene möglicherweise gar nicht bemerkt, 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, Geräteverlustsituationen selbst zu überprüfen und zu behandeln.

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 es einen aktiven Frame gibt, d. h. es gab einen beginFrame() (oder beginOffscreenFrame()), dem noch kein endFrame() (oder endOffscreenFrame()) entspricht.

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 modifiziert durch flags 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 die zugrunde liegende Grafik-API die Y-Achse in Framebuffern und Bildern nach oben zeigt.

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

bool QRhi::isYUpInNDC() const

Gibt true zurück, wenn die zugrunde liegende Grafik-API die Y-Achse in ihrem normalisierten Gerätekoordinatensystem nach oben zeigt.

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

bool QRhi::makeThreadLocalNativeContextCurrent()

Bei OpenGL wird dadurch der OpenGL-Kontext auf dem aktuellen Thread aktuell. Die Funktion hat keinen Effekt mit anderen Backends.

Der Aufruf dieser Funktion ist typischerweise in Qt-Framework-Code relevant, wenn man sicherstellen muss, dass externer OpenGL-Code, der von der Anwendung bereitgestellt wird, weiterhin wie zuvor mit direkter Verwendung von OpenGL laufen kann, solange QRhi das OpenGL-Backend verwendet.

Gibt false zurück, wenn der Vorgang fehlgeschlagen ist, ähnlich wie QOpenGLContext::makeCurrent(). Wenn die Operation fehlgeschlagen ist, kann isDeviceLost() aufgerufen werden, um festzustellen, ob ein Kontextverlust vorlag. Eine solche Prüfung ist äquivalent zur Prüfung mit QOpenGLContext::isValid().

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

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

Gibt die Anzahl der mip-Ebenen für eine bestimmte size zurück.

const QRhiNativeHandles *QRhi::nativeHandles()

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

Cast auf QRhiVulkanNativeHandles, QRhiD3D11NativeHandles, QRhiD3D12NativeHandles, QRhiGles2NativeHandles oder QRhiMetalNativeHandles je nach Bedarf.

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

Gibt einen neuen Puffer mit den angegebenen 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 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 die Speicherung des Renderbuffers 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)

Liefert einen neuen Sampler mit dem angegebenen Vergrößerungsfilter magFilter, dem Verkleinerungsfilter minFilter, dem Mipmapping-Modus mipmapMode und den Adressierungsmodi (Wrap) addressU, addressV und addressW.

Siehe auch QRhiResource::destroy().

QRhiShaderResourceBindings *QRhi::newShaderResourceBindings()

Gibt eine neue Shader-Ressourcenbindungs-Sammlungsressource zurück.

Siehe auch QRhiResource::destroy().

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 format, pixelSize, sampleCount und flags zurück.

Bei einem 1D-Textur-Array muss QRhiTexture::OneDimensional in flags gesetzt sein. Diese Funktion setzt implizit dieses Flag, wenn die pixelSize Höhe 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 format, width, height, depth, sampleCount und flags zurück.

Diese Überladung ist für 3D-Texturen geeignet, da sie die Angabe von depth ermöglicht. Eine 3D-Textur muss QRhiTexture::ThreeDimensional in flags gesetzt haben, aber mit dieser Überladung kann das weggelassen werden, weil das Flag implizit gesetzt wird, wenn 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 0 sind.

Dies ist eine überladene Funktion.

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 format, arraySize, pixelSize, sampleCount und flags zurück.

Mit dieser Funktion wird QRhiTexture::TextureArray implizit in flags gesetzt.

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

Siehe auch newTexture().

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

Liefert ein neues Textur-Rendering-Ziel mit der Farbe und den Tiefen-/Schablonenanhängen, die in desc angegeben sind, und mit dem angegebenen flags.

Siehe auch QRhiResource::destroy().

QRhiResourceUpdateBatch *QRhi::nextResourceUpdateBatch()

Gibt einen verfügbaren, leeren Stapel zurück, in dem Kopiervorgänge aufgezeichnet werden können.

Da sie nicht an einen aufzuzeichnenden Frame gebunden ist, ist beispielsweise die folgende Sequenz gültig:

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 Datenblob mit Daten zurück, die von QRhiGraphicsPipeline und QRhiComputePipeline während der Lebensdauer dieses QRhi erfolgreich erstellt wurden.

Durch das Speichern und anschließende erneute Laden der Cache-Daten in späteren Durchläufen derselben Anwendung können die Pipeline- und Shader-Erstellungszeiten potenziell reduziert werden. Was genau der Cache und seine serialisierte Version enthält, ist nicht spezifiziert, ist immer spezifisch für das verwendete Backend und in einigen Fällen auch abhängig von der jeweiligen Implementierung der Grafik-API.

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

Wenn das Kennzeichen EnablePipelineCacheDataSave beim Aufruf von create() nicht angegeben wurde, kann das zurückgegebene QByteArray leer sein, auch wenn das Merkmal PipelineCacheDataLoadSave unterstützt wird.

Wenn die zurückgegebenen Daten nicht leer sind, sind sie immer spezifisch für die Qt-Version und das QRhi Backend. Darüber hinaus besteht in einigen Fällen eine starke Abhängigkeit vom Grafikgerät und der genauen Treiberversion. QRhi kümmert sich um das Hinzufügen der entsprechenden Header und Schutzmaßnahmen, die sicherstellen, dass die Daten immer sicher an setPipelineCacheData() übergeben werden können.

Siehe EnablePipelineCacheDataSave für weitere Einzelheiten zu dieser Funktion.

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

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

Gibt true zurück, wenn zu erwarten ist, dass create() erfolgreich ist, wenn die angegebenen impl und params aufgerufen werden.

Für einige Backends ist dies gleichbedeutend mit dem Aufruf von create(), der Überprüfung des Rückgabewerts und der anschließenden Zerstörung des resultierenden QRhi.

Für andere, insbesondere mit Metal, kann es eine spezielle Probing-Implementierung geben, die das Testen in einer leichtgewichtigeren Weise erlaubt, ohne die Debug-Ausgabe mit Warnungen bei Fehlern zu verschmutzen.

Siehe auch create().

void QRhi::releaseCachedResources()

Versucht, Ressourcen in den Caches des Backends freizugeben. Dies kann sowohl CPU- als auch GPU-Ressourcen umfassen. Nur Speicher und Ressourcen, die automatisch wiederhergestellt werden können, sind im Anwendungsbereich. Wenn zum Beispiel die Backend-Implementierung QRhiGraphicsPipeline einen Cache mit Shader-Kompilierungsergebnissen unterhält, 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 ressourcenbeschränkten Umgebungen sinnvoll, in denen ab einem bestimmten Punkt eine minimale Ressourcennutzung auf Kosten der Leistung gewährleistet werden muss.

void QRhi::removeCleanupCallback(const void *key)

Deregistriert den Callback mit key. Wenn kein Cleanup-Callback mit key registriert wurde, führt die Funktion nichts aus. Ohne Schlüssel registrierte Rückrufe 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 erwartet, dass die Werte von den Backends bei der Initialisierung abgefragt werden, d. h. der Aufruf dieser Funktion ist eine einfache Operation.

void QRhi::runCleanup()

Ruft alle registrierten Aufräumfunktionen auf. Die Liste der Aufräum-Callbacks wird dann geleert. Normalerweise geschieht dies durch das Zerstören von QRhi automatisch, aber manchmal kann es nützlich sein, die Bereinigung auszulösen, um alle zwischengespeicherten, nicht-essentiellen Ressourcen freizugeben.

Siehe auch addCleanupCallback().

void QRhi::setPipelineCacheData(const QByteArray &data)

Lädt data in den Pipeline-Cache, falls zutreffend.

Wenn PipelineCacheDataLoadSave als nicht unterstützt gemeldet wird, ist der Aufruf der Funktion sicher, hat aber keine Wirkung.

Der von pipelineCacheData() zurückgegebene Blob ist immer spezifisch für die Qt-Version, das QRhi -Backend und in einigen Fällen auch für das Grafikgerät und eine bestimmte Version des Grafiktreibers. QRhi kümmert sich um das Hinzufügen der entsprechenden Header und Schutzmaßnahmen, die sicherstellen, dass die Daten immer sicher an diese Funktion übergeben werden können. Wenn es eine Nichtübereinstimmung gibt, 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 wird sicher ignoriert.

Bei Vulkan entspricht dies direkt dem VkPipelineCache. Der Aufruf dieser Funktion erstellt ein neues Vulkan-Pipeline-Cache-Objekt, dessen Anfangsdaten von 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 echten Pipeline-Cache, aber sie können einen Cache mit Bytecode aus Shader-Kompilierungen (D3D) oder Programmbinärdateien (OpenGL) bereitstellen. Bei Anwendungen, die zur Laufzeit viele Shader-Kompilierungen aus dem Quellcode durchführen, kann dies bei nachfolgenden Durchläufen zu einer erheblichen Verbesserung führen, wenn der "Pipeline-Cache" bei einem früheren Durchlauf mit dieser Funktion vorbesetzt wurde.

Siehe EnablePipelineCacheDataSave für weitere Details zu dieser Funktion.

Siehe auch pipelineCacheData() und isFeatureSupported().

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

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

QRhiStats QRhi::statistics() const

Sammelt und liefert Statistiken über das Timing und die Zuweisungen von Grafikressourcen.

Daten über Speicherzuweisungen sind nur bei einigen Backends verfügbar, bei denen solche Operationen unter der Kontrolle von Qt stehen. Bei Grafik-APIs, bei denen es keine Kontrolle auf unterer Ebene über Speicherzuweisungen gibt, wird dies nie unterstützt und alle relevanten Felder in den Ergebnissen sind 0.

Insbesondere bei Vulkan sind die Werte immer gültig und werden von 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, Deskriptor-Heaps usw.), wie von DXGI gemeldet.

Die Werte entsprechen allen verwendeten Speichertypen in Kombination. (d. h. Video + System im Falle einer diskreten GPU)

Zusätzliche Daten, wie z. B. die Gesamtzeit in Millisekunden, die für die Erstellung von Grafik- und Rechenpipelines aufgewendet wird (was in der Regel Shader-Kompilierung oder Cache-Lookups und potenziell teure Verarbeitung beinhaltet), sind bei den meisten Backends verfügbar.

QList<int> QRhi::supportedSampleCounts() const

Gibt die Liste der unterstützten Stichprobenzahlen zurück.

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

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

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

QThread *QRhi::thread() const

Gibt den Thread zurück, auf dem die Seite QRhi war initialized.

int QRhi::ubufAligned(int v) const

Gibt den Wert (in der Regel einen Offset) v zurück, der auf die einheitliche Pufferausrichtung ausgerichtet ist, die durch ubufAlignment() angegeben wird.

int QRhi::ubufAlignment() const

Gibt die minimale einheitliche Puffer-Offset-Ausrichtung in Bytes zurück. Dies ist normalerweise 256.

Der Versuch, eine einheitliche Pufferregion mit einem Offset zu binden, der nicht auf 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 spezifisch für das Backend und die Grafik-API 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 bei Rendering-Systemen mit mehreren Threads sinnvoll: Diese statische Funktion sollte im Gegensatz zu allen QRhi Operationen auf dem Haupt-Thread (GUI) aufgerufen und dann an den Thread übertragen werden, der mit QRhi und QRhiSwapChain arbeitet, und an die Swapchain weitergegeben werden. Dies ermöglicht plattformeigene Abfragen, die nur auf dem Haupt-Thread sicher aufgerufen werden können, z.B. die Abfrage des CAMetalLayers von einem NSView, und dann die Weitergabe der Daten an den QRhiSwapChain auf dem Rendering-Thread. Im Metal-Beispiel führt der Zugriff auf view.layer in einem dedizierten Rendering-Thread zu einer Warnung im Xcode Thread Checker. Mit dem Daten-Proxy-Mechanismus wird dies vermieden.

Wenn keine Threads involviert sind, ist das Generieren und Weitergeben von QRhiSwapChainProxyData nicht erforderlich: Backends sind garantiert in der Lage, alles abzufragen, was benötigt wird, und wenn alles auf dem Haupt-(Gui)-Thread läuft, sollte das ausreichend sein.