Docs/Qt Embedding
Qt6 QVulkanInstance In-process

Embedding Spectra in Qt6 Applications

Use Spectra's Vulkan rendering inside a QWindow via the QtRuntime bootstrap — full plotting power without GLFW or a separate window.

When to Use Qt Embedding

Qt6 integration path

In-process only — QtRuntime initializes Vulkan and drives frames from the Qt event loop.

Qt embed integration
More diagrams →
  • You already have a Qt6 desktop application and want Spectra plots inside it.
  • You need Spectra to share the application's main event loop and signals/slots.
  • You want a native Qt menu bar / dock layout around Spectra canvases.
For headless rendering without a window, see the Easy Embed Guide. For a C ABI embed surface (non-Qt host applications), see SPECTRA_BUILD_EMBED_SHARED=ON and include/spectra/embed.h.

Build Configuration

cmake -B build \
  -DSPECTRA_USE_QT=ON \
  -DSPECTRA_BUILD_QT_EXAMPLE=ON \
  -DCMAKE_BUILD_TYPE=Release
cmake --build build --target qt_embed_demo -j$(nproc)
./build/examples/qt_embed_demo
FlagPurpose
SPECTRA_USE_QTBuild the Qt adapter (src/adapters/qt/)
SPECTRA_BUILD_QT_EXAMPLEBuild qt_embed_demo (requires Qt6)

Minimal Integration

#include <QApplication>
#include <QVulkanInstance>
#include <spectra/adapters/qt/qt_runtime.hpp>
#include <spectra/figure.hpp>

int main(int argc, char** argv)
{
    QApplication app(argc, argv);

    spectra::adapters::qt::QtRuntime rt;
    rt.init();                           // VkInstance + VkDevice + Renderer

    // Create a QWindow with surfaceType = Qt::VulkanSurface and
    // assign rt.vulkan_instance() before show().
    QWindow* win = make_vulkan_window(rt);
    win->resize(1280, 800);
    win->show();

    spectra::Figure fig;
    rt.attach_window(win, win->width(), win->height());

    // Drive frames from a timer or QWindow::requestUpdate()
    QObject::connect(&timer, &QTimer::timeout, [&]() {
        rt.begin_frame();
        rt.render_figure(fig);
        rt.end_frame();
    });

    return app.exec();
}

The full working example is in examples/qt_embed_demo.cpp.

QtRuntime API Surface

MethodPurpose
init()Create VkInstance, VkDevice, and the shared Renderer.
vulkan_instance()Returns the QVulkanInstance* to assign to your QWindow.
attach_window(QWindow*, w, h)Create surface + swapchain for a Qt window.
resize_window(QWindow*, w, h)Recreate the swapchain on resize.
begin_frame() / render_figure(Figure&) / end_frame()Drive a frame from the Qt event loop.
shutdown()Tear down all Vulkan resources (idempotent).

Notes & Limitations

  • Qt embedding runs in inproc mode only — there is no daemon.
  • The Qt window owns input; Spectra's input handler is wired through QtSurfaceHost.
  • Multiple Qt windows are supported by calling attach_window() for each.
  • Wayland is supported via Qt's Vulkan integration; X11 is supported on Linux.

Related