QRhiSwapChain Class

Detailed Description

Swapchain resource.

A swapchain enables presenting rendering results to a surface. A swapchain is typically backed by a set of color buffers. Of these, one is displayed at a time.

Below is a typical pattern for creating and managing a swapchain and some associated resources in order to render onto a QWindow:

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

  void resizeSwapChain()
  {
      const QSize outputSize = sc->surfacePixelSize();
      ds->setPixelSize(outputSize);
      ds->build();
      hasSwapChain = sc->buildOrResize();
  }

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

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

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

Avoid relying on QWindow resize events to resize swapchains, especially considering that surface sizes may not always fully match the QWindow reported dimensions. The safe, cross-platform approach is to do the check via surfacePixelSize() whenever starting a new frame.

Releasing the swapchain must happen while the QWindow and the underlying native window is fully up and running. Building on the previous example:

  void releaseSwapChain()
  {
      if (hasSwapChain) {
          sc->release();
          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);
  }

Initializing the swapchain and starting to render the first frame cannot start at any time. The safe, cross-platform approach is to rely on expose events. QExposeEvent is a loosely specified event that is sent whenever a window gets mapped, obscured, and resized, depending on the platform.

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

Once the rendering has started, a simple way to request a new frame is QWindow::requestUpdate(). While on some platforms this is merely a small timer, on others it has a specific implementation: for instance on macOS or iOS it may be backed by CVDisplayLink. The example above is already prepared for update requests by handling QEvent::UpdateRequest.

While acting as a QRhiRenderTarget, QRhiSwapChain also manages a QRhiCommandBuffer. Calling QRhi::endFrame() submits the recorded commands and also enqueues a present request. The default behavior is to do this with a swap interval of 1, meaning synchronizing to the display's vertical refresh is enabled. Thus the rendering thread calling beginFrame() and endFrame() will get throttled to vsync. On some backends this can be disabled by passing QRhiSwapChain:NoVSync in flags().

Multisampling (MSAA) is handled transparently to the applications when requested via setSampleCount(). Where applicable, QRhiSwapChain will take care of creating additional color buffers and issuing a multisample resolve command at the end of a frame. For OpenGL, it is necessary to request the appropriate sample count also via QSurfaceFormat, by calling QSurfaceFormat::setDefaultFormat() before initializing the QRhi.