QRhiSwapChain Class

void init()
{
    sc = rhi->newSwapChain();
    ds = rhi->newRenderBuffer(QRhiRenderBuffer::DepthStencil,
                              QSize(), // no need to set the size here due to UsedWithSwapChainOnly
                              1,
                              QRhiRenderBuffer::UsedWithSwapChainOnly);
    sc->setWindow(window);
    sc->setDepthStencil(ds);
    rp = sc->newCompatibleRenderPassDescriptor();
    sc->setRenderPassDescriptor(rp);
    resizeSwapChain();
}

void resizeSwapChain()
{
    hasSwapChain = sc->createOrResize();
}

void render()
{
    if (!hasSwapChain || notExposed)
        return;

    if (sc->currentPixelSize() != sc->surfacePixelSize() || newlyExposed) {
        resizeSwapChain();
        if (!hasSwapChain)
            return;
        newlyExposed = false;
    }

    rhi->beginFrame(sc);
    // ...
    rhi->endFrame(sc);
}

void releaseSwapChain()
{
    if (hasSwapChain) {
        sc->destroy();
        hasSwapChain = false;
    }
}

// assuming Window is our QWindow subclass
bool Window::event(QEvent *e)
{
    switch (e->type()) {
    case QEvent::UpdateRequest: // for QWindow::requestUpdate()
        render();
        break;
    case QEvent::PlatformSurface:
        if (static_cast<QPlatformSurfaceEvent *>(e)->surfaceEventType() == QPlatformSurfaceEvent::SurfaceAboutToBeDestroyed)
            releaseSwapChain();
        break;
    default:
        break;
    }
    return QWindow::event(e);
}

void Window::exposeEvent(QExposeEvent *)
{
    // initialize and start rendering when the window becomes usable for graphics purposes
    if (isExposed() && !running) {
        running = true;
        init();
    }

    // stop pushing frames when not exposed or size becomes 0
    if ((!isExposed() || (hasSwapChain && sc->surfacePixelSize().isEmpty())) && running)
        notExposed = true;

    // continue when exposed again and the surface has a valid size
    if (isExposed() && running && notExposed && !sc->surfacePixelSize().isEmpty()) {
        notExposed = false;
        newlyExposed = true;
    }

    if (isExposed() && !sc->surfacePixelSize().isEmpty())
        render();
}

Dokumentation der Mitgliedsfunktionen

[pure virtual] bool QRhiSwapChain::createOrResize()

Erstellt die Swapchain, falls dies noch nicht geschehen ist, und passt die Größe der Swapchain-Puffer an die aktuelle Größe der Zieloberfläche an. Rufen Sie diese Funktion immer dann auf, wenn sich die Größe der Zieloberfläche gegenüber zuvor geändert hat.

Gibt bei Erfolg ` true ` zurück, bei einem Fehler einer Grafikoperation ` false `. Unabhängig vom Rückgabewert ist der Aufruf von ` destroy()` immer sicher.

[pure virtual] QRhiCommandBuffer *QRhiSwapChain::currentFrameCommandBuffer()

Gibt einen Befehlspuffer zurück, in dem Rendering-Befehle und Ressourcenaktualisierungen innerhalb eines Blocks „ beginFrame – endFrame “ aufgezeichnet werden können, vorausgesetzt, beginFrame() wurde mit dieser Swapchain aufgerufen.

[pure virtual] QRhiRenderTarget *QRhiSwapChain::currentFrameRenderTarget()

Gibt ein Renderziel zurück, das mit `beginPass()` verwendet werden kann, um den aktuellen Backbuffer der Swapchain zu rendern. Nur gültig innerhalb eines Blocks aus ` QRhi::beginFrame()` – ` QRhi::endFrame()`, in dem `beginFrame()` mit dieser Swapchain aufgerufen wurde.

[virtual] QRhiRenderTarget *QRhiSwapChain::currentFrameRenderTarget(QRhiSwapChain::StereoTargetBuffer targetBuffer)

Gibt ein Renderziel zurück, das mit `beginPass()` verwendet werden kann, um in den linken oder rechten Backbuffer der Swapchain zu rendern. Diese Überladung sollte nur beim stereoskopischen Rendering verwendet werden, d. h. wenn die zugehörige ` QWindow ` durch zwei Farbpuffer gestützt wird – einen für jedes Auge – statt nur durch einen.

Wenn stereoskopisches Rendering nicht unterstützt wird, ist der Rückgabewert das Standard-Renderziel. Es wird von allen Hardware-Backends mit Ausnahme von Metal in Kombination mit ` QSurfaceFormat::StereoBuffers` unterstützt, vorausgesetzt, es wird vom Grafik- und Anzeigetreiber-Stack zur Laufzeit unterstützt. Die Backends „Metal“ und „Null“ geben bei dieser Überladung das Standard-Renderziel zurück.

QSize QRhiSwapChain::currentPixelSize() const

Gibt die Größe zurück, mit der die Swapchain zuletzt erfolgreich erstellt wurde. Verwenden Sie diese Angabe, um zu entscheiden, ob ` createOrResize()` erneut aufgerufen werden muss: Wenn ` currentPixelSize() != surfacePixelSize() ` ist, muss die Swapchain in ihrer Größe angepasst werden.

Zwar entspricht der Wert in vielen Fällen dem von ` QWindow::size() * QWindow::devicePixelRatio()`, doch ist nicht garantiert, dass die von ` QWindow` gemeldete Größe auf allen Plattformen und bei allen Implementierungen der Grafik-API korrekt ist. Die Verwendung dieser Funktion wird daher dringend empfohlen, wann immer die Abmessungen der Ausgabeebene oder -fläche in Pixeln ermittelt werden müssen.

Dies hat zudem den zusätzlichen Vorteil, dass potenzielle Datenkonflikte vermieden werden, wenn „ QRhi “ in einem dedizierten Rendering-Thread verwendet wird, da der Aufruf von „ QWindow “-Funktionen, die möglicherweise auf im Hauptthread aktualisierte Daten zugreifen, vermieden wird.

Siehe auch surfacePixelSize().

QRhiRenderBuffer *QRhiSwapChain::depthStencil() const

Gibt den aktuell zugeordneten Renderbuffer für Depth-Stencil zurück.

Siehe auch „ setDepthStencil()“.

QRhiSwapChain::Flags QRhiSwapChain::flags() const

Gibt die aktuell gesetzten Flags zurück.

Siehe auch setFlags().

QRhiSwapChain::Format QRhiSwapChain::format() const

Gibt das aktuell eingestellte Format zurück.

Siehe auch „ setFormat()“.

[virtual] QRhiSwapChainHdrInfo QRhiSwapChain::hdrInfo()

Gibt die HDR-Informationen für das zugehörige Display zurück.

Gehen Sie nicht davon aus, dass dies ein ressourcenschonender Vorgang ist. Je nach Plattform führt diese Funktion verschiedene Plattformabfragen durch, die sich auf die Leistung auswirken können.

Siehe auch QRhiSwapChainHdrInfo.

[pure virtual] bool QRhiSwapChain::isFormatSupported(QRhiSwapChain::Format f)

Gibt „true“ zurück, wenn das angegebene Swapchain-Format f unterstützt wird. SDR wird immer unterstützt.

Diese Funktion wird hauptsächlich dazu verwendet, sie vor dem ersten Aufruf von ` createOrResize()` zu rufen, nachdem das Fenster bereits festgelegt wurde. Dies ermöglicht es den ` QRhi `-Backends, plattform- oder Fenstersystemspezifische Abfragen durchzuführen, um festzustellen, ob das Fenster (und der Bildschirm, auf dem es sich befindet) in der Lage ist, echte HDR-Ausgabe im angegebenen Format zu liefern.

Wenn das Format als unterstützt gemeldet wird, rufen Sie ` setFormat()` auf, um das angeforderte Format festzulegen, und rufen Sie anschließend ` createOrResize()` auf. Beachten Sie jedoch die damit verbundenen Konsequenzen: Die erfolgreiche Anforderung eines HDR-Formats bedeutet, dass Sie sich mit einem anderen Farbraum auseinandersetzen müssen, möglicherweise eine Weißpegelkorrektur für nicht-HDR-fähige Inhalte vornehmen, Tonemapping-Methoden anpassen, die Einstellungen für Offscreen-Renderziele anpassen müssen usw.

Siehe auch setFormat().

[pure virtual] QRhiRenderPassDescriptor *QRhiSwapChain::newCompatibleRenderPassDescriptor()

Gibt ein neues ` QRhiRenderPassDescriptor ` zurück, das mit dieser Swapchain kompatibel ist.

Der zurückgegebene Wert wird auf zwei Arten verwendet: Er kann an die Funktionen ` setRenderPassDescriptor()` und ` QRhiGraphicsPipeline::setRenderPassDescriptor()` übergeben werden. Ein Render-Pass-Deskriptor beschreibt die Anhänge (Farbe, Tiefe/Stencil) sowie das Lade-/Speicherverhalten, das durch die Funktion ` flags()` beeinflusst werden kann. Ein ` QRhiGraphicsPipeline ` kann nur in Kombination mit einer Swapchain verwendet werden, für die ` compatible ` QRhiRenderPassDescriptor festgelegt ist.

Siehe auch createOrResize().

QRhiSwapChainProxyData QRhiSwapChain::proxyData() const

Gibt die aktuell festgelegten Proxy-Daten zurück.

Siehe auch „ setProxyData()“.

QRhiRenderPassDescriptor *QRhiSwapChain::renderPassDescriptor() const

Gibt das aktuell zugeordnete „ QRhiRenderPassDescriptor “-Objekt zurück.

Siehe auch setRenderPassDescriptor().

[override virtual] QRhiResource::Type QRhiSwapChain::resourceType() const

Implementiert neu: QRhiResource::resourceType() const.

Gibt den Ressourcentyp zurück.

int QRhiSwapChain::sampleCount() const

Gibt die aktuell eingestellte Sample-Anzahl zurück. Der Wert 1 bedeutet, dass kein Multisample-Antialiasing verwendet wird.

Siehe auch setSampleCount().

void QRhiSwapChain::setDepthStencil(QRhiRenderBuffer *ds)

Legt den Renderbuffer „ ds “ als Tiefen-Stencil-Puffer fest.

Siehe auch ` depthStencil()`.

void QRhiSwapChain::setFlags(QRhiSwapChain::Flags f)

Setzt die Flags „ f “.

Siehe auch „ flags()“.

void QRhiSwapChain::setFormat(QRhiSwapChain::Format f)

Legt das Format „ f “ fest.

Vermeiden Sie die Festlegung von Formaten, die von ` isFormatSupported()` als nicht unterstützt gemeldet werden. Beachten Sie, dass die Unterstützung für ein bestimmtes Format davon abhängen kann, auf welchem Bildschirm das der Swapchain zugeordnete Fenster geöffnet ist. Auf einigen Plattformen, wie z. B. Windows und macOS, muss die HDR-Ausgabe in den Anzeigeeinstellungen aktiviert sein, damit die HDR-Ausgabe funktioniert.

Weitere Informationen zur Ausgabe mit hohem Dynamikbereich finden Sie unter isFormatSupported(), QRhiSwapChainHdrInfo und Format.

Siehe auch format().

void QRhiSwapChain::setProxyData(const QRhiSwapChainProxyData &d)

Legt die Proxy-Daten d fest.

Siehe auch proxyData() und QRhi::updateSwapChainProxyData().

void QRhiSwapChain::setRenderPassDescriptor(QRhiRenderPassDescriptor *desc)

Arbeitet mit der „ QRhiRenderPassDescriptor “ zusammen desc.

Siehe auch renderPassDescriptor().

void QRhiSwapChain::setSampleCount(int samples)

Legt die Anzahl der Samples fest. Übliche Werte für „ samples “ sind 1 (kein MSAA), 4 (4x MSAA) oder 8 (8x MSAA).

Siehe auch „ sampleCount()“ und „ QRhi::supportedSampleCounts()“.

[since 6.9] void QRhiSwapChain::setShadingRateMap(QRhiShadingRateMap *map)

Wird mit dem angegebenen „ QRhiShadingRateMap “ verknüpft: map. Dies funktioniert nur, wenn die Funktion „ QRhi::VariableRateShadingMap “ als unterstützt gemeldet wird.

Wird zusätzlich QRhiCommandBuffer::setShadingRate() aufgerufen, wird für jede Kachel die höhere der beiden Shading-Raten verwendet. Derzeit gibt es keine Möglichkeit, das Verhalten des Kombinators zu steuern.

Diese Funktion wurde in Qt 6.9 eingeführt.

Siehe auch shadingRateMap().

void QRhiSwapChain::setWindow(QWindow *window)

Legt die Eigenschaft „ window “ fest.

Siehe auch window().

[since 6.9] QRhiShadingRateMap *QRhiSwapChain::shadingRateMap() const

Gibt den aktuell eingestellten Wert für „ QRhiShadingRateMap “ zurück. Standardmäßig ist dies „ nullptr “.

Diese Funktion wurde in Qt 6.9 eingeführt.

Siehe auch ` setShadingRateMap()`.

[pure virtual] QSize QRhiSwapChain::surfacePixelSize()

Gibt die Größe der dem Fenster zugeordneten Oberfläche oder Ebene zurück.

Siehe auch ` currentPixelSize()`.

QWindow *QRhiSwapChain::window() const

Gibt das aktuell eingestellte Fenster zurück.

Siehe auch „ setWindow()“.