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()

Erzeugt die Swapchain, falls noch nicht geschehen, und passt die Größe der Swapchain-Puffer an die aktuelle Größe der Zielfläche an. Rufen Sie diese Funktion immer dann auf, wenn die Größe der Zieloberfläche anders ist als zuvor.

Gibt bei Erfolg true zurück, bei einer fehlgeschlagenen 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 Ressourcen-Updates innerhalb eines beginFrame - endFrame Blocks aufgezeichnet werden können, vorausgesetzt beginFrame() wurde mit dieser Swapchain aufgerufen.

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

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

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

Gibt ein Rendering-Ziel zurück, das mit beginPass() verwendet werden kann, um in den linken oder rechten Backbuffer der Swapchain zu rendern. Diese Überladung sollte nur bei stereoskopischem Rendering verwendet werden, d.h. wenn die zugehörige QWindow von zwei Farbpuffern unterstützt wird, einem für jedes Auge, anstatt nur einem.

Wenn stereoskopisches Rendering nicht unterstützt wird, ist der Rückgabewert das Standardziel. 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. Metal- und Null-Backends geben das Standard-Rendering-Ziel von dieser Überladung zurück.

QSize QRhiSwapChain::currentPixelSize() const

Gibt die Größe zurück, mit der die Swapchain zuletzt erfolgreich erstellt wurde. Verwenden Sie dies, um zu entscheiden, ob createOrResize() erneut aufgerufen werden muss: Wenn currentPixelSize() != surfacePixelSize(), dann muss die Größe der Swapchain geändert werden.

Während der Wert in vielen Fällen derselbe ist wie QWindow::size() * QWindow::devicePixelRatio(), ist es nicht garantiert, dass die von QWindow gemeldete Größe auf allen Plattformen und Grafik-API-Implementierungen korrekt ist. Es wird daher dringend empfohlen, diese Funktion immer dann zu verwenden, wenn die Abmessungen der Ausgabeschicht oder -fläche in Pixeln angegeben werden müssen.

Dies hat auch den zusätzlichen Vorteil, dass potenzielle Data-Races vermieden werden, wenn QRhi auf einem dedizierten Rendering-Thread verwendet wird, da die Notwendigkeit, QWindow Funktionen aufzurufen, die dann möglicherweise auf Daten zugreifen, die auf dem Haupt-Thread aktualisiert wurden, 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 die zugehörige Anzeige zurück.

Gehen Sie nicht davon aus, dass dies ein billiger 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.

Die Hauptanwendung dieser Funktion besteht darin, sie vor dem ersten createOrResize() aufzurufen, nachdem das Fenster bereits gesetzt ist. 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 mit dem angegebenen Format zu leisten.

Wenn das Format als unterstützt gemeldet wird, rufen Sie setFormat() auf, um das angeforderte Format zu setzen, und rufen Sie createOrResize() auf. Seien Sie sich jedoch der Konsequenzen bewusst: Die erfolgreiche Anforderung eines HDR-Formats bedeutet, dass Sie sich mit einem anderen Farbraum auseinandersetzen müssen, möglicherweise eine Weißwertkorrektur für nicht HDR-fähige Inhalte vornehmen müssen, Tonemapping-Methoden anpassen müssen, Einstellungen für Rendering-Ziele außerhalb des Bildschirms vornehmen müssen usw.

Siehe auch setFormat().

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

Gibt eine neue QRhiRenderPassDescriptor zurück, die mit dieser Swapchain kompatibel ist.

Der zurückgegebene Wert wird auf zwei Arten verwendet: Er kann an setRenderPassDescriptor() und QRhiGraphicsPipeline::setRenderPassDescriptor() übergeben werden. Ein Renderpass-Deskriptor beschreibt die Anhänge (Farbe, Tiefe/Schablone) und das Lade-/Speicherverhalten, die von flags() beeinflusst werden können. 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 eingestellten Proxydaten 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

Reimplements: QRhiResource::resourceType() const.

Gibt den Ressourcentyp zurück.

int QRhiSwapChain::sampleCount() const

Gibt die aktuell eingestellte Sampleanzahl zurück. 1 bedeutet kein Multisample-Antialiasing.

Siehe auch setSampleCount().

void QRhiSwapChain::setDepthStencil(QRhiRenderBuffer *ds)

Setzt den Renderbuffer ds zur Verwendung als Tiefenschablonenpuffer.

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 es, Formate zu setzen, die von isFormatSupported() als nicht unterstützt gemeldet werden. Beachten Sie, dass die Unterstützung für ein bestimmtes Format vom Bildschirm abhängen kann, auf dem das zugehörige Fenster der Swapchain geöffnet ist. Auf einigen Plattformen, wie Windows und macOS, muss die HDR-Ausgabe in den Anzeigeeinstellungen aktiviert sein, damit sie funktioniert.

Siehe isFormatSupported(), QRhiSwapChainHdrInfo und Format für weitere Informationen zur HDR-Ausgabe.

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)

Assoziiert mit der QRhiRenderPassDescriptor desc .

Siehe auch renderPassDescriptor().

void QRhiSwapChain::setSampleCount(int samples)

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

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

void QRhiSwapChain::setWindow(QWindow *window)

Setzt die window.

Siehe auch window().

[pure virtual] QSize QRhiSwapChain::surfacePixelSize()

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

Siehe auch currentPixelSize().

QWindow *QRhiSwapChain::window() const

Gibt das aktuell eingestellte Fenster zurück.

Siehe auch setWindow().