@@ -286,6 +286,49 @@
    message(FATAL_ERROR "SUNSHINE_ENABLE_KWIN requires SUNSHINE_ENABLE_WAYLAND — KWin capture disabled")
endif()
# QEMU D-Bus display (capture = qemu)
set(QEMU_FOUND OFF)
if(${SUNSHINE_ENABLE_QEMU})
    pkg_check_modules(QEMU_GIO gio-2.0>=2.64 gio-unix-2.0>=2.64)
    find_program(GDBUS_CODEGEN_EXECUTABLE gdbus-codegen)
    if(QEMU_GIO_FOUND AND GDBUS_CODEGEN_EXECUTABLE)
        set(QEMU_FOUND ON)
    else()
        message(WARNING
                "QEMU D-Bus display capture disabled: it needs gio-2.0 >= 2.64, gio-unix-2.0 >= 2.64 and gdbus-codegen")
    endif()
endif()
if(QEMU_FOUND)
    set(QEMU_DBUS_XML "${CMAKE_SOURCE_DIR}/third-party/qemu-dbus-display/dbus-display1.xml")
    set(QEMU_DBUS_GENERATED_DIR "${CMAKE_BINARY_DIR}/generated-src/qemu")
    file(MAKE_DIRECTORY "${QEMU_DBUS_GENERATED_DIR}")
    # generated at configure time, like the wayland protocols; editing the XML re-runs cmake
    set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${QEMU_DBUS_XML}")
    execute_process(
            COMMAND "${GDBUS_CODEGEN_EXECUTABLE}"
            --glib-min-required 2.64
            --output-directory "${QEMU_DBUS_GENERATED_DIR}"
            --interface-prefix org.qemu.
            --c-namespace QemuDBus
            --generate-c-code dbus-display1
            "${QEMU_DBUS_XML}"
            RESULT_VARIABLE QEMU_DBUS_CODEGEN_RESULT)
    if(NOT QEMU_DBUS_CODEGEN_RESULT EQUAL 0)
        message(FATAL_ERROR "gdbus-codegen failed for ${QEMU_DBUS_XML}")
    endif()
    add_compile_definitions(SUNSHINE_BUILD_QEMU)
    list(APPEND PLATFORM_TARGET_FILES
            "${QEMU_DBUS_GENERATED_DIR}/dbus-display1.c"
            "${QEMU_DBUS_GENERATED_DIR}/dbus-display1.h"
            "${CMAKE_SOURCE_DIR}/src/platform/linux/qemu/capture.cpp"
            "${CMAKE_SOURCE_DIR}/src/platform/linux/qemu/frame_store.h"
            "${CMAKE_SOURCE_DIR}/src/platform/linux/qemu/frame_store.cpp"
            "${CMAKE_SOURCE_DIR}/src/platform/linux/qemu/session.h"
            "${CMAKE_SOURCE_DIR}/src/platform/linux/qemu/session.cpp")
endif()
if(NOT ${CUDA_FOUND}
        AND NOT ${LIBDRM_FOUND}
        AND NOT ${LIBVA_FOUND}

@@ -76,4 +76,6 @@
            "Enable KWin ScreenCast grab if available" ON)
    option(SUNSHINE_ENABLE_PORTAL
            "Enable XDG portal grab if available" ON)
    option(SUNSHINE_ENABLE_QEMU
            "Enable QEMU D-Bus display capture (capture = qemu) if available" ON)
endif()

@@ -2195,7 +2195,7 @@
            @endcode</td>
    </tr>
    <tr>
        <td rowspan="6">Choices</td>
        <td rowspan="7">Choices</td>
        <td>nvfbc</td>
        <td>Use NVIDIA Frame Buffer Capture to capture direct to GPU memory. This is usually the fastest method for
            NVIDIA cards. NvFBC does not have native Wayland support and does not work with XWayland.
@@ -2223,6 +2223,13 @@
            @note{Applies to FreeBSD and Linux only.}</td>
    </tr>
    <tr>
        <td>qemu</td>
        <td>Stream a QEMU virtual machine started with `-display dbus`, with no software in the guest.
            Select the bus with [qemu_dbus_address](#qemu_dbus_address) and the console with
            [output_name](#output_name). This method is never selected automatically.
            @note{Applies to Linux only.}</td>
    </tr>
    <tr>
        <td>ddx</td>
        <td>Use DirectX Desktop Duplication API to capture the display. This is well-supported on Windows machines.
            @note{Applies to Windows only.}</td>
@@ -2232,5 +2239,28 @@
        <td>(beta feature) Use Windows.Graphics.Capture to capture the display.
            @note{Applies to Windows only.}
            @attention{This capture method is not compatible with the Sunshine service.}</td>
    </tr>
</table>
### qemu_dbus_address
<table>
    <tr>
        <td>Description</td>
        <td colspan="2">
            D-Bus address of the bus that a QEMU VM's display is on. Only used when [capture](#capture) is `qemu`.
            Use the same address given to QEMU with `-display dbus,addr=`.
            @note{Applies to Linux only.}
        </td>
    </tr>
    <tr>
        <td>Default</td>
        <td colspan="2">Empty, which uses the session bus.</td>
    </tr>
    <tr>
        <td>Example</td>
        <td colspan="2">@code{}
            qemu_dbus_address = unix:path=/run/sunshine-qemu/vm0/bus.sock
            @endcode</td>
    </tr>
</table>

@@ -1,0 +1,111 @@
# Journal (fork-only, not upstreamable)
Working notes for the QEMU D-Bus backend. Keep out of the upstream series (#8).
## 2026-09-12 — Phase 0 (#2)
### Environment
- Host: Ubuntu 24.04.4 on WSL2 (kernel 6.18), 20 cores, `/dev/kvm` present, NVIDIA RTX 4090
  (Windows driver 610.88, exposed through `/dev/dxg` and `/usr/lib/wsl/lib`, which include
  `libcuda` and `libnvidia-encode`). CUDA toolkits 12.8 and 13.2 are in `/usr/local`.
- WSL2 has **no DRM render node** (`/dev/dri` is absent): no VAAPI, no GBM, and no DMABUF export.
  QEMU refuses `-device virtio-vga-gl -display dbus,gl=on` with "egl: no drm render node
  available". So the DMABUF zero-copy path (#3) can't run here; NVENC encoding of the shm path can.
  An earlier version of these notes wrongly said this host has no GPU because `/dev/dri` was missing.
- Toolchain: upstream needs **gcc-14** on Ubuntu 24.04 (`scripts/linux_build.sh` picks it;
  `src/platform/linux/kmsgrab.cpp` uses `std::ranges::to`). The default gcc 13 fails to build a
  clean upstream tree. Configure with `CC=gcc-14 CXX=g++-14`.
- CUDA isn't installed: configure with `-DCUDA_FAIL_ON_MISSING=OFF`.
- Distro QEMU is 8.2.2. Its D-Bus display has no `Listener.Unix.Map` and no
  `Listener.Unix.ScanoutDMABUF2` (checked the strings in `ui-dbus.so`), so it only sends
  `Scanout`/`Update` pixel copies. Built QEMU 11.1.1 from the release tarball into
  `~/.cache/sunshine-qemu/qemu-install` with
  `--target-list=x86_64-softmmu --enable-dbus-display --enable-kvm --enable-slirp --enable-opengl --enable-modules`.
### Baseline (clean upstream `dd7a1f7`, `SUNSHINE_ENABLE_QEMU=OFF`)
`xvfb-run -a cmake-build-noqemu/tests/test_sunshine`: 569 tests, 555 passed, 14 skipped,
**exit code 1**. The failure is `PlatformTestSuite::SetUpTestSuite` (`tests/tests_common.h:162`):
`platf::init()` logs "Unable to initialize capture method" on WSL2 (no KMS, portal interfaces
missing, X11 capture unavailable under Xvfb here). That makes the `MouseHIDTest`, audio and video
platform suites skip and the binary exit 1. Not caused by this work.
### Decisions and deviations from the issue text
- **Console selection uses Sunshine's existing `output_name`**, not a new `qemu_console` key.
  `platf::display_names()` returns the graphical console ids, so `output_name = 1` (or a label)
  selects a console exactly like it selects a monitor for other backends. One fewer config key for
  upstream review; an unknown name falls back to the first graphical console with a warning.
- **Bindings are generated at configure time** (`execute_process`, like `GEN_WAYLAND`), with the XML
  in `CMAKE_CONFIGURE_DEPENDS`. A build-time `add_custom_command` would not propagate to the
  `test_sunshine` target in `tests/` without extra custom targets.
- VM gone / listener closed / scanout size change all return `capture_e::reinit`. `video.cpp` then
  re-creates the display in a retry loop, so a VM restart doesn't end the stream.
- Frames are pushed only when QEMU reports damage; the encoder's minimum-FPS repeat covers static
  screens. `img_t::frame_timestamp` is the receipt time of the QEMU call, so Sunshine's existing
  `frame_processing_latency` (logged at debug and sent to Moonlight in each frame header) measures
  "listener callback receipt → packet out" for REQ-NFR-001.
- Connection setup and the listener handshake have a deadline (a watchdog cancels the
  `GCancellable`). Without it, a `qemu_dbus_address` that accepts but never authenticates hangs
  Sunshine forever.
- **Two GLib threads per session.** After replying to `RegisterListener`, QEMU makes *synchronous*
  calls on the new listener (property `GetAll`, `ScanoutMap`). With one thread, a second
  `RegisterListener` issued while QEMU waited on the first listener deadlocked both processes until
  the call timeout (found by `QemuSessionTest.SupportsMultipleListenersAndReregistration`). The bus
  thread makes blocking calls; listener connections are dispatched on a thread that never blocks on
  QEMU.
### Results
- Unit tests: 37 QEMU tests (session against a fake QEMU on a private dbus-daemon, frame store,
  capture, REQ-CMP-001 "never connects unless selected"), stable across `--gtest_repeat=5`.
- E2E (`tests/e2e/qemu/e2e_stream.sh`), KVM, software encoding:
  - QEMU 11.1.1, shared memory map path: PASS, quadrants `[253,0,0] [0,254,0] [0,0,254] [255,255,255]`.
  - QEMU 8.2.2 (distro), D-Bus message path: PASS, same colors.
  - Red check: the same harness against a Sunshine built without the backend fails at `launch`
    with HTTP 503 "Failed to initialize video capture/encoding".
- The harness was written after the capture spike rather than strictly first; the red check above
  is the evidence that it fails without the feature.
### REQ-NFR-001 measurements (host processing latency: QEMU call receipt → encoded frame sent)
Release build, gcc-14, 20-core host under WSL2, KVM, guest framebuffer 640x400 scaled by
Sunshine, ~330 samples per run over 18 s. NVENC runs use a CUDA build
(`-DCMAKE_CUDA_COMPILER=/usr/local/cuda-13.2/bin/nvcc`, `encoder = nvenc`, `h264_nvenc` with the
RAM→CUDA upload) on the RTX 4090.
| Transport (QEMU)                | Encoder         | Stream       | p50     | p95     |
|---------------------------------|-----------------|--------------|---------|---------|
| Shared memory map (11.1.1)      | NVENC           | 1920x1080@60 | 11.1 ms | 20.4 ms |
| D-Bus messages (8.2.2)          | NVENC           | 1920x1080@60 | 12.2 ms | 19.5 ms |
| Shared memory map (11.1.1)      | software x264   | 1920x1080@60 | 14.1 ms | 21.4 ms |
| D-Bus messages (8.2.2)          | software x264   | 1920x1080@60 | 14.1 ms | 21.1 ms |
| Shared memory map, Debug build  | software x264   | 1280x800@30  | 17.2 ms | 32.9 ms |
| D-Bus messages, Debug build     | software x264   | 1280x800@30  | 20.2 ms | 34.6 ms |
The transports tie because the guest framebuffer is small.
**Capture pacing dominates, not encoding.** The capture loop wakes on a fixed tick of one frame
interval (16.7 ms at 60 fps) and copies whatever damage arrived since the last tick. Damage lands
uniformly within the interval, so it waits 0–16.7 ms (p50 ≈ 8 ms, p95 ≈ 16 ms) before the copy.
Add ~3 ms for NVENC and that predicts p50 ≈ 11 ms and p95 ≈ 19–20 ms, which matches the
measurements. Hardware encoding only saves the 2–3 ms that x264 spends. Waking the capture thread on
damage (a condition variable with the next frame deadline as timeout) should remove most of the
wait. That belongs with the pacing work in #3.
The draft "p95 ≤ 10 ms on the DMABUF path" can't be measured here, because WSL2 has no DRM render
node for QEMU's GL display. It stays for #3 on native Linux.
Seen during encoder probing with the CUDA build, not caused by this backend: "cuda::cuda_t doesn't
support any format other than AV_PIX_FMT_NV12 and AV_PIX_FMT_YUV444P" (the RAM→CUDA upload rejects
10-bit probes, as it does for x11 capture). The 8-bit H.264 stream is unaffected.
### Observations for later phases
- Encoder probing creates many short-lived displays; `qemu::shared_session` only caches a
  `weak_ptr`, so each probe reconnects (~2-5 ms each). Cheap, but a short keep-alive would avoid it.
- `platf::init()` runs `verify_qemu()` at Sunshine startup, so QEMU must already own `org.qemu`
  when Sunshine starts. Relevant for the systemd/libvirt ordering in #6.
- In the E2E runs, PulseAudio isn't running ("Failed to create client: Daemon not running") and
  libvirtualhid gamepads are unavailable; video streaming is unaffected. #4 and #5 replace both.

@@ -780,6 +780,7 @@
    {},  // encoder
    {},  // adapter_name
    {},  // output_name
    {},  // qemu_dbus_address
    {
      video_t::dd_t::config_option_e::disabled,  // configuration_option
@@ -1698,6 +1699,7 @@
    string_f(vars, "encoder", video.encoder);
    string_f(vars, "adapter_name", video.adapter_name);
    string_f(vars, "output_name", video.output_name);
    string_f(vars, "qemu_dbus_address", video.qemu_dbus_address);
    generic_f(vars, "dd_configuration_option", video.dd.configuration_option, dd::config_option_from_view);
    generic_f(vars, "dd_resolution_option", video.dd.resolution_option, dd::resolution_option_from_view);

@@ -137,6 +137,7 @@
    std::string encoder;  ///< Encoder backend name selected by configuration.
    std::string adapter_name;  ///< Display adapter name selected in configuration.
    std::string output_name;  ///< Display output name selected in configuration.
    std::string qemu_dbus_address;  ///< D-Bus address of the bus QEMU's display is on; empty uses the session bus.
    /**
     * @brief Display-device integration settings.

@@ -1125,6 +1125,9 @@
#ifdef SUNSHINE_BUILD_PORTAL
      PORTAL,  ///< XDG PORTAL
#endif
#ifdef SUNSHINE_BUILD_QEMU
      QEMU,  ///< QEMU D-Bus display
#endif
      MAX_FLAGS  ///< The maximum number of flags
    };
  }  // namespace source
@@ -1205,10 +1208,21 @@
  }
#endif
#ifdef SUNSHINE_BUILD_QEMU
  std::vector<std::string> qemu_display_names();
  std::shared_ptr<display_t> qemu_display(mem_type_e hwdevice_type, const std::string &display_name, const video::config_t &config);
  bool verify_qemu();
#endif
  /**
   * @brief List display names accepted by the selected capture backend.
   */
  std::vector<std::string> display_names(mem_type_e hwdevice_type) {
#ifdef SUNSHINE_BUILD_QEMU
    if (sources[source::QEMU]) {
      return qemu_display_names();
    }
#endif
#ifdef SUNSHINE_BUILD_CUDA
    // display using NvFBC only supports mem_type_e::cuda
    if (sources[source::NVFBC] && hwdevice_type == mem_type_e::cuda) {
@@ -1275,6 +1289,13 @@
      drop_elevated_privileges(false);
    }
#ifdef SUNSHINE_BUILD_QEMU
    if (sources[source::QEMU]) {
      BOOST_LOG(info) << "Screencasting with QEMU D-Bus display"sv;
      return qemu_display(hwdevice_type, display_name, config);
    }
#endif
#ifdef SUNSHINE_BUILD_CUDA
    if (sources[source::NVFBC] && hwdevice_type == mem_type_e::cuda) {
      BOOST_LOG(info) << "Screencasting with NvFBC"sv;
@@ -1371,5 +1392,12 @@
#ifdef SUNSHINE_BUILD_KWIN
    if (((config::video.capture.empty() && sources.none()) || config::video.capture == "kwin") && verify_kwin()) {
      sources[source::KWIN] = true;
    }
#endif
#ifdef SUNSHINE_BUILD_QEMU
    // Only used when explicitly selected; a VM display is never auto-detected.
    if (config::video.capture == "qemu" && verify_qemu()) {
      sources[source::QEMU] = true;
    }
#endif

@@ -1,0 +1,270 @@
/**
 * @file src/platform/linux/qemu/capture.cpp
 * @brief Definitions for the QEMU D-Bus display capture backend (`capture = qemu`).
 */
// standard includes
#include <cstring>
#include <mutex>
// local includes
#include "frame_store.h"
#include "session.h"
#include "src/config.h"
#include "src/logging.h"
#include "src/platform/common.h"
#include "src/platform/linux/misc.h"
#include "src/video.h"
#ifdef SUNSHINE_BUILD_VAAPI
  #include "src/platform/linux/vaapi.h"
#endif
#ifdef SUNSHINE_BUILD_CUDA
  #include "src/platform/linux/cuda.h"
#endif
using namespace std::literals;
namespace qemu {
  /**
   * @brief System-memory image owned by the QEMU capture backend.
   */
  struct img_t: public platf::img_t {
    ~img_t() override {
      delete[] data;
      data = nullptr;
    }
  };
  /**
   * @brief Display backend that streams a QEMU console from shared memory scanouts.
   */
  class display_t: public platf::display_t {
  public:
    /**
     * @brief Create an uninitialized display.
     *
     * @param mem_type Memory type the encoder expects.
     */
    explicit display_t(platf::mem_type_e mem_type):
        mem_type {mem_type} {
    }
    /**
     * @brief Connect to QEMU, register a listener on the selected console, and wait for a frame.
     *
     * @param display_name Console id or label; empty selects the first graphical console.
     * @param config Stream configuration.
     * @return 0 on success, -1 on failure.
     */
    int init(const std::string &display_name, const ::video::config_t &config) {
      delay = ::video::capture_frame_interval(config);
      session = shared_session(config::video.qemu_dbus_address);
      if (!session) {
        return -1;
      }
      auto vm = session->vm();
      auto console = find_console(vm, display_name);
      if (!console) {
        BOOST_LOG(warning) << "qemu: console ["sv << display_name << "] not found, using the first graphical console"sv;
        console = find_console(vm, "");
      }
      if (!console) {
        BOOST_LOG(error) << "qemu: VM ["sv << vm.name << "] has no graphical console"sv;
        return -1;
      }
      store = std::make_shared<frame_store_t>();
      registration = session->register_listener(console->id, store);
      if (!registration) {
        return -1;
      }
      // QEMU sends the current surface right after registration
      if (store->wait_for_frame(2s)) {
        width = store->width();
        height = store->height();
      } else {
        BOOST_LOG(warning) << "qemu: no scanout received yet; using the console size"sv;
        width = (int) console->width;
        height = (int) console->height;
      }
      if (width <= 0 || height <= 0) {
        BOOST_LOG(error) << "qemu: console "sv << console->id << " has no size"sv;
        return -1;
      }
      env_width = width;
      env_height = height;
      logical_width = width;
      logical_height = height;
      env_logical_width = width;
      env_logical_height = height;
      BOOST_LOG(info) << "qemu: streaming VM ["sv << vm.name << "] console "sv << console->id << " ["sv << console->label << "] at "sv << width << 'x' << height;
      return 0;
    }
    platf::capture_e capture(const push_captured_image_cb_t &push_captured_image_cb, const pull_free_image_cb_t &pull_free_image_cb, bool *cursor) override {
      auto next_frame = std::chrono::steady_clock::now();
      sleep_overshoot_logger.reset();
      while (true) {
        platf::handle_pacing(next_frame, delay, sleep_overshoot_logger);
        std::shared_ptr<platf::img_t> img_out;
        auto status = snapshot(pull_free_image_cb, img_out);
        switch (status) {
          case platf::capture_e::reinit:
          case platf::capture_e::error:
          case platf::capture_e::interrupted:
            return status;
          case platf::capture_e::timeout:
            if (!push_captured_image_cb(std::move(img_out), false)) {
              return platf::capture_e::ok;
            }
            break;
          case platf::capture_e::ok:
            if (!push_captured_image_cb(std::move(img_out), true)) {
              return platf::capture_e::ok;
            }
            break;
          default:
            BOOST_LOG(error) << "Unrecognized capture status ["sv << (int) status << ']';
            return status;
        }
      }
    }
    /**
     * @brief Copy the latest frame if the guest changed it.
     *
     * @param pull_free_image_cb Callback providing an image to fill.
     * @param img_out Filled image on `ok`.
     * @return `ok` with a new frame, `timeout` when nothing changed, `reinit` when the size
     * changed or QEMU went away, or `interrupted`.
     */
    platf::capture_e snapshot(const pull_free_image_cb_t &pull_free_image_cb, std::shared_ptr<platf::img_t> &img_out) {
      if (!session->alive() || !store->connected() || store->width() != width || store->height() != height) {
        return platf::capture_e::reinit;
      }
      if (store->sequence() == copied_sequence) {
        return platf::capture_e::timeout;
      }
      if (!pull_free_image_cb(img_out)) {
        return platf::capture_e::interrupted;
      }
      std::chrono::steady_clock::time_point timestamp;
      switch (store->copy_if_newer(copied_sequence, width, height, img_out->data, timestamp)) {
        case frame_status_e::new_frame:
          img_out->frame_timestamp = timestamp;
          damage_to_capture_logger.first_point(timestamp);
          damage_to_capture_logger.second_point_now_and_log();
          return platf::capture_e::ok;
        case frame_status_e::unchanged:
          return platf::capture_e::timeout;
        case frame_status_e::size_changed:
        case frame_status_e::disconnected:
        default:
          return platf::capture_e::reinit;
      }
    }
    std::shared_ptr<platf::img_t> alloc_img() override {
      auto img = std::make_shared<qemu::img_t>();
      img->width = width;
      img->height = height;
      img->pixel_pitch = 4;
      img->row_pitch = img->pixel_pitch * width;
      img->data = new std::uint8_t[(std::size_t) height * img->row_pitch];
      return img;
    }
    int dummy_img(platf::img_t *img) override {
      if (!img) {
        return -1;
      }
      std::memset(img->data, 0, (std::size_t) img->height * img->row_pitch);
      return 0;
    }
    std::unique_ptr<platf::avcodec_encode_device_t> make_avcodec_encode_device(platf::pix_fmt_e pix_fmt) override {
#ifdef SUNSHINE_BUILD_VAAPI
      if (mem_type == platf::mem_type_e::vaapi) {
        return va::make_avcodec_encode_device(width, height, false);
      }
#endif
#ifdef SUNSHINE_BUILD_CUDA
      if (mem_type == platf::mem_type_e::cuda) {
        return cuda::make_avcodec_encode_device(width, height, false);
      }
#endif
      return std::make_unique<platf::avcodec_encode_device_t>();
    }
  private:
    platf::mem_type_e mem_type;  ///< Memory type the encoder expects.
    std::chrono::nanoseconds delay {};  ///< Capture interval for the client frame rate.
    std::shared_ptr<session_t> session;  ///< Session to the VM.
    std::shared_ptr<frame_store_t> store;  ///< Frame reconstructed from listener calls.
    std::unique_ptr<listener_registration_t> registration;  ///< Keeps the listener registered.
    std::uint64_t copied_sequence {0};  ///< Store sequence of the last copied frame.
    logging::time_delta_periodic_logger damage_to_capture_logger {debug, "qemu: damage received to frame captured"};  ///< Latency from QEMU's call to the capture copy.
  };
}  // namespace qemu
namespace platf {
  /**
   * @brief Check whether the QEMU backend was selected and QEMU is reachable.
   * @details Never connects unless `capture = qemu`, so other backends are unaffected.
   *
   * @return True when `capture = qemu` and a QEMU display was found.
   */
  bool verify_qemu() {
    if (config::video.capture != "qemu") {
      return false;
    }
    return qemu::shared_session(config::video.qemu_dbus_address) != nullptr;
  }
  /**
   * @brief List the graphical consoles of the VM.
   *
   * @return Console ids, or an empty list when QEMU is unreachable.
   */
  std::vector<std::string> qemu_display_names() {
    auto session = qemu::shared_session(config::video.qemu_dbus_address);
    if (!session) {
      return {};
    }
    auto names = qemu::graphic_console_names(session->vm());
    for (const auto &name : names) {
      BOOST_LOG(info) << "qemu: found console "sv << name;
    }
    return names;
  }
  /**
   * @brief Create a QEMU display capture backend.
   *
   * @param hwdevice_type Memory type the encoder expects.
   * @param display_name Console id or label.
   * @param config Stream configuration.
   * @return Display backend, or nullptr on failure.
   */
  std::shared_ptr<display_t> qemu_display(mem_type_e hwdevice_type, const std::string &display_name, const video::config_t &config) {
    if (hwdevice_type != mem_type_e::system && hwdevice_type != mem_type_e::vaapi && hwdevice_type != mem_type_e::cuda) {
      BOOST_LOG(error) << "qemu: could not initialize display with the given hw device type"sv;
      return nullptr;
    }
    auto display = std::make_shared<qemu::display_t>(hwdevice_type);
    if (display->init(display_name, config)) {
      return nullptr;
    }
    return display;
  }
}  // namespace platf

@@ -1,0 +1,287 @@
/**
 * @file src/platform/linux/qemu/frame_store.cpp
 * @brief Definitions for the shared-memory frame store of the QEMU capture backend.
 */
// class header include
#include "frame_store.h"
// standard includes
#include <algorithm>
#include <cstring>
// platform includes
#include <sys/mman.h>
#include <sys/stat.h>
// local includes
#include "src/logging.h"
using namespace std::literals;
namespace qemu {
  namespace {
    /**
     * @brief Report whether a pixman format is 32 bpp with red and blue swapped relative to BGRX.
     *
     * @param format Pixman format code.
     * @return True for `x8b8g8r8` and `a8b8g8r8`.
     */
    bool is_rgbx(std::uint32_t format) {
      return format == pixman_format::x8b8g8r8 || format == pixman_format::a8b8g8r8;
    }
    /**
     * @brief Report whether the frame store can convert a pixman format.
     *
     * @param format Pixman format code.
     * @return True for the supported 32 bpp formats.
     */
    bool is_supported(std::uint32_t format) {
      return format == pixman_format::x8r8g8b8 || format == pixman_format::a8r8g8b8 || is_rgbx(format);
    }
    /**
     * @brief Log an unsupported format once per format code.
     *
     * @param format Pixman format code.
     */
    void log_unsupported(std::uint32_t format) {
      static std::mutex logged_mutex;
      static std::vector<std::uint32_t> logged;
      std::lock_guard lock {logged_mutex};
      if (std::ranges::find(logged, format) == logged.end()) {
        logged.push_back(format);
        BOOST_LOG(warning) << "qemu: unsupported pixman format 0x"sv << std::hex << format << std::dec << "; ignoring scanout"sv;
      }
    }
    /**
     * @brief Check that a pixel buffer covers a rectangle.
     *
     * @param available Bytes available.
     * @param width Rectangle width.
     * @param height Rectangle height.
     * @param stride Bytes per row.
     * @return True when the buffer is large enough and the stride fits the width.
     */
    bool covers(std::size_t available, std::int64_t width, std::int64_t height, std::int64_t stride) {
      if (width <= 0 || height <= 0 || stride < width * 4) {
        return false;
      }
      return (std::size_t) (stride * (height - 1) + width * 4) <= available;
    }
  }  // namespace
  frame_store_t::~frame_store_t() {
    std::lock_guard lock {mutex};
    unmap_locked();
  }
  void frame_store_t::scanout(std::uint32_t width, std::uint32_t height, std::uint32_t stride, std::uint32_t format, std::span<const std::uint8_t> data) {
    if (!is_supported(format)) {
      log_unsupported(format);
      return;
    }
    if (!covers(data.size(), width, height, stride)) {
      BOOST_LOG(warning) << "qemu: scanout data doesn't cover "sv << width << 'x' << height << " with stride "sv << stride;
      return;
    }
    std::lock_guard lock {mutex};
    unmap_locked();
    resize_locked((int) width, (int) height);
    blit_locked(0, 0, (int) width, (int) height, data.data(), stride, format);
    touch_locked();
  }
  void frame_store_t::update(std::int32_t x, std::int32_t y, std::int32_t width, std::int32_t height, std::uint32_t stride, std::uint32_t format, std::span<const std::uint8_t> data) {
    if (!is_supported(format)) {
      log_unsupported(format);
      return;
    }
    if (!covers(data.size(), width, height, stride)) {
      BOOST_LOG(warning) << "qemu: update data doesn't cover "sv << width << 'x' << height << " with stride "sv << stride;
      return;
    }
    std::lock_guard lock {mutex};
    if (frame_width == 0 || map_addr) {
      return;
    }
    // clip the rectangle to the frame, skipping the source rows and columns that fall outside
    int x0 = std::max(x, 0);
    int y0 = std::max(y, 0);
    int x1 = std::min<std::int64_t>((std::int64_t) x + width, frame_width);
    int y1 = std::min<std::int64_t>((std::int64_t) y + height, frame_height);
    if (x0 >= x1 || y0 >= y1) {
      return;
    }
    auto src = data.data() + (std::size_t) (y0 - y) * stride + (std::size_t) (x0 - x) * 4;
    blit_locked(x0, y0, x1 - x0, y1 - y0, src, stride, format);
    touch_locked();
  }
  void frame_store_t::scanout_map(fd_t fd, std::uint32_t offset, std::uint32_t width, std::uint32_t height, std::uint32_t stride, std::uint32_t format) {
    if (fd.get() < 0) {
      BOOST_LOG(warning) << "qemu: ScanoutMap without a descriptor"sv;
      return;
    }
    if (!is_supported(format)) {
      log_unsupported(format);
      return;
    }
    struct stat st {};
    if (fstat(fd.get(), &st) != 0 || !covers(st.st_size > offset ? (std::size_t) st.st_size - offset : 0, width, height, stride)) {
      BOOST_LOG(warning) << "qemu: ScanoutMap descriptor doesn't cover "sv << width << 'x' << height << " at offset "sv << offset;
      return;
    }
    std::size_t size = (std::size_t) offset + (std::size_t) stride * height;
    size = std::min<std::size_t>(size, st.st_size);
    auto addr = mmap(nullptr, size, PROT_READ, MAP_SHARED, fd.get(), 0);
    if (addr == MAP_FAILED) {
      BOOST_LOG(warning) << "qemu: couldn't map scanout: "sv << std::strerror(errno);
      return;
    }
    std::lock_guard lock {mutex};
    unmap_locked();
    map_fd = std::move(fd);
    map_addr = (const std::uint8_t *) addr;
    map_size = size;
    map_offset = offset;
    map_stride = stride;
    map_format = format;
    resize_locked((int) width, (int) height);
    blit_locked(0, 0, (int) width, (int) height, map_addr + map_offset, map_stride, map_format);
    touch_locked();
  }
  void frame_store_t::update_map(std::int32_t x, std::int32_t y, std::int32_t width, std::int32_t height) {
    std::lock_guard lock {mutex};
    if (!map_addr) {
      return;
    }
    int x0 = std::max(x, 0);
    int y0 = std::max(y, 0);
    int x1 = std::min<std::int64_t>((std::int64_t) x + width, frame_width);
    int y1 = std::min<std::int64_t>((std::int64_t) y + height, frame_height);
    if (x0 >= x1 || y0 >= y1) {
      return;
    }
    auto src = map_addr + map_offset + (std::size_t) y0 * map_stride + (std::size_t) x0 * 4;
    blit_locked(x0, y0, x1 - x0, y1 - y0, src, map_stride, map_format);
    touch_locked();
  }
  void frame_store_t::disable() {
    std::lock_guard lock {mutex};
    std::ranges::fill(pixels, 0);
    if (frame_width > 0) {
      touch_locked();
    }
  }
  void frame_store_t::disconnected() {
    std::lock_guard lock {mutex};
    is_disconnected = true;
    frame_ready.notify_all();
  }
  bool frame_store_t::wait_for_frame(std::chrono::milliseconds timeout) {
    std::unique_lock lock {mutex};
    frame_ready.wait_for(lock, timeout, [this]() {
      return change_sequence > 0 || is_disconnected;
    });
    return change_sequence > 0 && !is_disconnected;
  }
  int frame_store_t::width() const {
    std::lock_guard lock {mutex};
    return frame_width;
  }
  int frame_store_t::height() const {
    std::lock_guard lock {mutex};
    return frame_height;
  }
  bool frame_store_t::connected() const {
    std::lock_guard lock {mutex};
    return !is_disconnected;
  }
  std::uint64_t frame_store_t::sequence() const {
    std::lock_guard lock {mutex};
    return change_sequence;
  }
  frame_status_e frame_store_t::copy_if_newer(std::uint64_t &last_sequence, int width, int height, std::uint8_t *dst, std::chrono::steady_clock::time_point &timestamp) {
    std::lock_guard lock {mutex};
    if (is_disconnected) {
      return frame_status_e::disconnected;
    }
    if (width != frame_width || height != frame_height) {
      return frame_status_e::size_changed;
    }
    if (change_sequence == last_sequence) {
      return frame_status_e::unchanged;
    }
    std::memcpy(dst, pixels.data(), pixels.size());
    last_sequence = change_sequence;
    timestamp = change_time;
    return frame_status_e::new_frame;
  }
  void frame_store_t::resize_locked(int new_width, int new_height) {
    const bool mapped = map_addr != nullptr;
    if (new_width != frame_width || new_height != frame_height || mapped != logged_mapped) {
      BOOST_LOG(info) << "qemu: scanout "sv << new_width << 'x' << new_height << (mapped ? " via shared memory map"sv : " via D-Bus messages"sv);
      logged_mapped = mapped;
    }
    frame_width = new_width;
    frame_height = new_height;
    pixels.assign((std::size_t) new_width * new_height * 4, 0);
  }
  void frame_store_t::blit_locked(int x, int y, int w, int h, const std::uint8_t *src, std::uint32_t src_stride, std::uint32_t format) {
    const auto dst_stride = (std::size_t) frame_width * 4;
    const bool swap = is_rgbx(format);
    for (int row = 0; row < h; ++row) {
      auto s = src + (std::size_t) row * src_stride;
      auto d = pixels.data() + (std::size_t) (y + row) * dst_stride + (std::size_t) x * 4;
      if (!swap) {
        std::memcpy(d, s, (std::size_t) w * 4);
        continue;
      }
      for (int col = 0; col < w; ++col, s += 4, d += 4) {
        d[0] = s[2];
        d[1] = s[1];
        d[2] = s[0];
        d[3] = s[3];
      }
    }
  }
  void frame_store_t::touch_locked() {
    change_sequence += 1;
    change_time = std::chrono::steady_clock::now();
    frame_ready.notify_all();
  }
  void frame_store_t::unmap_locked() {
    if (map_addr) {
      munmap((void *) map_addr, map_size);
      map_addr = nullptr;
      map_size = 0;
    }
    map_fd = fd_t {};
  }
}  // namespace qemu

@@ -1,0 +1,148 @@
/**
 * @file src/platform/linux/qemu/frame_store.h
 * @brief Declarations for the shared-memory frame store of the QEMU capture backend.
 */
#pragma once
// standard includes
#include <chrono>
#include <condition_variable>
#include <cstdint>
#include <mutex>
#include <optional>
#include <span>
#include <vector>
// local includes
#include "session.h"
namespace qemu {
  /**
   * @brief Result of polling the frame store for a new frame.
   */
  enum class frame_status_e {
    new_frame,  ///< A frame newer than the caller's sequence number was copied.
    unchanged,  ///< Nothing changed since the caller's sequence number.
    size_changed,  ///< The frame size differs from the caller's size.
    disconnected,  ///< QEMU closed the listener connection.
  };
  /**
   * @brief Reconstructs the guest framebuffer from QEMU listener calls.
   * @details Listener calls arrive on the session thread; the capture thread copies frames out. The
   * stored frame is always 4 bytes per pixel in B, G, R, X order with a stride of `4 * width`,
   * which is the layout Sunshine's system-memory images use.
   */
  class frame_store_t: public display_listener_t {
  public:
    frame_store_t() = default;
    ~frame_store_t() override;
    frame_store_t(const frame_store_t &) = delete;
    frame_store_t &operator=(const frame_store_t &) = delete;
    void scanout(std::uint32_t width, std::uint32_t height, std::uint32_t stride, std::uint32_t format, std::span<const std::uint8_t> data) override;
    void update(std::int32_t x, std::int32_t y, std::int32_t width, std::int32_t height, std::uint32_t stride, std::uint32_t format, std::span<const std::uint8_t> data) override;
    void scanout_map(fd_t fd, std::uint32_t offset, std::uint32_t width, std::uint32_t height, std::uint32_t stride, std::uint32_t format) override;
    void update_map(std::int32_t x, std::int32_t y, std::int32_t width, std::int32_t height) override;
    void disable() override;
    void disconnected() override;
    /**
     * @brief Wait until the first scanout arrived.
     *
     * @param timeout Maximum time to wait.
     * @return True when a frame is available.
     */
    bool wait_for_frame(std::chrono::milliseconds timeout);
    /**
     * @brief Current frame width.
     *
     * @return Width in pixels, 0 before the first scanout.
     */
    [[nodiscard]] int width() const;
    /**
     * @brief Current frame height.
     *
     * @return Height in pixels, 0 before the first scanout.
     */
    [[nodiscard]] int height() const;
    /**
     * @brief Report whether QEMU still has the listener connection open.
     *
     * @return False once QEMU closed the connection.
     */
    [[nodiscard]] bool connected() const;
    /**
     * @brief Sequence number of the latest change.
     *
     * @return Monotonic counter, 0 before the first scanout.
     */
    [[nodiscard]] std::uint64_t sequence() const;
    /**
     * @brief Copy the frame if it changed since the caller last copied it.
     *
     * @param last_sequence Sequence of the caller's last copy; updated on `new_frame`.
     * @param width Width of the destination buffer.
     * @param height Height of the destination buffer.
     * @param dst Destination with `4 * width` bytes per row.
     * @param timestamp Receipt time of the call that produced the copied frame; set on `new_frame`.
     * @return Poll result.
     */
    frame_status_e copy_if_newer(std::uint64_t &last_sequence, int width, int height, std::uint8_t *dst, std::chrono::steady_clock::time_point &timestamp);
  private:
    /**
     * @brief Resize the frame, logging size or transport changes.
     *
     * @param new_width New width in pixels.
     * @param new_height New height in pixels.
     */
    void resize_locked(int new_width, int new_height);
    /**
     * @brief Convert and copy a rectangle of source pixels into the frame.
     *
     * @param x Destination left edge.
     * @param y Destination top edge.
     * @param w Rectangle width.
     * @param h Rectangle height.
     * @param src Pointer to the top-left source pixel of the rectangle.
     * @param src_stride Source bytes per row.
     * @param format Source pixman format; must be supported.
     */
    void blit_locked(int x, int y, int w, int h, const std::uint8_t *src, std::uint32_t src_stride, std::uint32_t format);
    /**
     * @brief Mark the frame as changed now.
     */
    void touch_locked();
    /**
     * @brief Unmap the current shared memory scanout.
     */
    void unmap_locked();
    mutable std::mutex mutex;  ///< Guards all state below.
    std::condition_variable frame_ready;  ///< Signaled when a frame or disconnect arrives.
    std::vector<std::uint8_t> pixels;  ///< BGRX frame, `4 * frame_width` bytes per row.
    int frame_width {0};  ///< Frame width in pixels.
    int frame_height {0};  ///< Frame height in pixels.
    std::uint64_t change_sequence {0};  ///< Incremented on every change.
    std::chrono::steady_clock::time_point change_time;  ///< Receipt time of the latest change.
    bool is_disconnected {false};  ///< Whether QEMU closed the listener connection.
    bool logged_mapped {false};  ///< Whether the last logged scanout used the shared memory map.
    fd_t map_fd;  ///< Shared memory descriptor of the current map scanout.
    const std::uint8_t *map_addr {nullptr};  ///< Mapping of `map_fd`.
    std::size_t map_size {0};  ///< Length of the mapping.
    std::uint32_t map_offset {0};  ///< Offset of the first pixel in the mapping.
    std::uint32_t map_stride {0};  ///< Bytes per row in the mapping.
    std::uint32_t map_format {0};  ///< Pixman format of the mapping.
  };
}  // namespace qemu

@@ -1,0 +1,744 @@
/**
 * @file src/platform/linux/qemu/session.cpp
 * @brief Definitions for the QEMU D-Bus display session.
 */
// class header include
#include "session.h"
// standard includes
#include <algorithm>
#include <atomic>
#include <charconv>
#include <condition_variable>
#include <cstring>
#include <functional>
#include <future>
#include <map>
#include <mutex>
#include <thread>
#include <utility>
// platform includes
#include <gio/gio.h>
#include <gio/gunixfdlist.h>
#include <sys/socket.h>
#include <unistd.h>
// local includes
#include "src/logging.h"
// generated includes
extern "C" {
#include "qemu/dbus-display1.h"
}
using namespace std::literals;
namespace qemu {
  namespace {
    constexpr auto bus_name = "org.qemu";  ///< Well-known name QEMU owns on the bus.
    constexpr auto vm_path = "/org/qemu/Display1/VM";  ///< Object path of the VM interface.
    constexpr auto listener_path = "/org/qemu/Display1/Listener";  ///< Object path QEMU calls on the listener connection.
    constexpr auto unix_map_interface = "org.qemu.Display1.Listener.Unix.Map";  ///< Shared memory listener interface.
    /**
     * @brief Convert a NULL-terminated string vector to a vector of strings.
     *
     * @param strv String vector, may be null.
     * @return Copied strings.
     */
    std::vector<std::string> to_strings(const gchar *const *strv) {
      std::vector<std::string> result;
      for (auto it = strv; it && *it; ++it) {
        result.emplace_back(*it);
      }
      return result;
    }
    /**
     * @brief Read a string property that may be missing on old QEMU releases.
     *
     * @param value Property value, may be null.
     * @return The value, or an empty string.
     */
    std::string to_string(const gchar *value) {
      return value ? value : "";
    }
    /**
     * @brief Cancels a GCancellable when a deadline passes, for blocking GDBus calls without a timeout.
     * @details Connection setup and authentication have no timeout of their own; a socket that
     * accepts but never answers would block forever.
     */
    class deadline_t {
    public:
      /**
       * @brief Start the watchdog.
       *
       * @param timeout Time after which the cancellable is cancelled.
       */
      explicit deadline_t(std::chrono::milliseconds timeout):
          cancellable {g_cancellable_new()} {
        watchdog = std::thread([this, timeout]() {
          std::unique_lock lock {mutex};
          if (!finished.wait_for(lock, timeout, [this]() {
                return done;
              })) {
            g_cancellable_cancel(cancellable);
          }
        });
      }
      ~deadline_t() {
        {
          std::lock_guard lock {mutex};
          done = true;
        }
        finished.notify_all();
        watchdog.join();
        g_object_unref(cancellable);
      }
      deadline_t(const deadline_t &) = delete;
      deadline_t &operator=(const deadline_t &) = delete;
      GCancellable *cancellable;  ///< Cancelled when the deadline passes.
    private:
      std::mutex mutex;  ///< Guards `done`.
      std::condition_variable finished;  ///< Signaled when the guarded work finished.
      bool done {false};  ///< Whether the guarded work finished.
      std::thread watchdog;  ///< Thread waiting for the deadline.
    };
    /**
     * @brief Owns a GLib main context and the thread that runs it.
     */
    class loop_thread_t {
    public:
      loop_thread_t():
          context {g_main_context_new()},
          loop {g_main_loop_new(context, FALSE)} {
        thread = std::thread([this]() {
          g_main_context_push_thread_default(context);
          g_main_loop_run(loop);
          g_main_context_pop_thread_default(context);
        });
      }
      ~loop_thread_t() {
        post([this]() {
          g_main_loop_quit(loop);
        });
        thread.join();
        g_main_loop_unref(loop);
        g_main_context_unref(context);
      }
      loop_thread_t(const loop_thread_t &) = delete;
      loop_thread_t &operator=(const loop_thread_t &) = delete;
      /**
       * @brief Run a function on the loop thread and wait for it to finish.
       * @details Runs the function inline when called from the loop thread.
       *
       * @param fn Function to run.
       */
      void invoke(const std::function<void()> &fn) {
        if (g_main_context_is_owner(context)) {
          fn();
          return;
        }
        std::packaged_task<void()> task {fn};
        auto done = task.get_future();
        post([&task]() {
          task();
        });
        done.get();
      }
    private:
      /**
       * @brief Queue a function on the loop without waiting.
       *
       * @param fn Function to run; must outlive its execution.
       */
      void post(std::function<void()> fn) {
        auto source = g_idle_source_new();
        g_source_set_priority(source, G_PRIORITY_DEFAULT);
        g_source_set_callback(
          source,
          [](gpointer data) -> gboolean {
            (*(std::function<void()> *) data)();
            return G_SOURCE_REMOVE;
          },
          new std::function<void()> {std::move(fn)},
          [](gpointer data) {
            delete (std::function<void()> *) data;
          }
        );
        g_source_attach(source, context);
        g_source_unref(source);
      }
      GMainContext *context;  ///< Context owned by the loop thread.
      GMainLoop *loop;  ///< Loop running on the thread.
      std::thread thread;  ///< Thread running the loop.
    };
    class session_impl_t;
    /**
     * @brief Peer-to-peer listener connection registered on a console.
     */
    class listener_impl_t: public listener_registration_t {
    public:
      /**
       * @brief Create an unconnected registration.
       *
       * @param session Session that owns the loop thread.
       * @param listener Receiver for display calls.
       */
      listener_impl_t(std::shared_ptr<session_impl_t> session, std::shared_ptr<display_listener_t> listener);
      ~listener_impl_t() override;
      /**
       * @brief Complete the peer-to-peer handshake and export the listener objects.
       * @details Must run on the listener thread, right after `RegisterListener` returned.
       *
       * @param socket_fd Our end of the socket pair.
       * @param cancellable Cancels the handshake when the deadline passes.
       * @return True when the listener is exported.
       */
      bool start(fd_t socket_fd, GCancellable *cancellable);
    private:
      /**
       * @brief Unexport the listener objects and close the connection.
       * @details Must run on the listener thread.
       */
      void stop();
      static gboolean on_scanout(QemuDBusDisplay1Listener *object, GDBusMethodInvocation *invocation, guint width, guint height, guint stride, guint format, GVariant *data, gpointer self);
      static gboolean on_update(QemuDBusDisplay1Listener *object, GDBusMethodInvocation *invocation, gint x, gint y, gint width, gint height, guint stride, guint format, GVariant *data, gpointer self);
      static gboolean on_scanout_dmabuf(QemuDBusDisplay1Listener *object, GDBusMethodInvocation *invocation, GUnixFDList *fd_list, GVariant *dmabuf, guint width, guint height, guint stride, guint fourcc, guint64 modifier, gboolean y0_top, gpointer self);
      static gboolean on_update_dmabuf(QemuDBusDisplay1Listener *object, GDBusMethodInvocation *invocation, gint x, gint y, gint width, gint height, gpointer self);
      static gboolean on_disable(QemuDBusDisplay1Listener *object, GDBusMethodInvocation *invocation, gpointer self);
      static gboolean on_mouse_set(QemuDBusDisplay1Listener *object, GDBusMethodInvocation *invocation, gint x, gint y, gint on, gpointer self);
      static gboolean on_cursor_define(QemuDBusDisplay1Listener *object, GDBusMethodInvocation *invocation, gint width, gint height, gint hot_x, gint hot_y, GVariant *data, gpointer self);
      static gboolean on_scanout_map(QemuDBusDisplay1ListenerUnixMap *object, GDBusMethodInvocation *invocation, GUnixFDList *fd_list, GVariant *handle, guint offset, guint width, guint height, guint stride, guint format, gpointer self);
      static gboolean on_update_map(QemuDBusDisplay1ListenerUnixMap *object, GDBusMethodInvocation *invocation, gint x, gint y, gint width, gint height, gpointer self);
      static void on_closed(GDBusConnection *connection, gboolean remote_peer_vanished, GError *err, gpointer self);
      std::shared_ptr<session_impl_t> session;  ///< Keeps the loop thread alive while registered.
      std::shared_ptr<display_listener_t> listener;  ///< Receiver for display calls.
      GDBusConnection *connection {nullptr};  ///< Peer-to-peer connection to QEMU.
      QemuDBusDisplay1Listener *skeleton {nullptr};  ///< Exported Listener interface.
      QemuDBusDisplay1ListenerUnixMap *map_skeleton {nullptr};  ///< Exported Listener.Unix.Map interface.
      bool closed {false};  ///< Whether the peer closed the connection.
    };
    /**
     * @brief GDBus implementation of the session.
     */
    class session_impl_t: public session_t, public std::enable_shared_from_this<session_impl_t> {
    public:
      /**
       * @brief Create a session with its loop thread; call connect_bus() next.
       *
       * @param timeout Timeout applied to each D-Bus call.
       */
      explicit session_impl_t(std::chrono::milliseconds timeout):
          timeout {timeout},
          timeout_ms {(int) timeout.count()} {
      }
      ~session_impl_t() override {
        loop.invoke([this]() {
          disconnect_bus();
        });
      }
      /**
       * @brief Connect to the bus and read the VM and console properties.
       *
       * @param address Bus address, or empty for the session bus.
       * @return True when QEMU was found.
       */
      bool connect_bus(const std::string &address) {
        bool ok = false;
        deadline_t deadline {timeout};
        loop.invoke([&]() {
          ok = connect_bus_on_loop(address, deadline.cancellable);
          if (!ok) {
            disconnect_bus();
          }
        });
        return ok;
      }
      vm_info_t vm() const override {
        vm_info_t info;
        loop.invoke([&]() {
          info.name = to_string(qemu_dbus_display1_vm_get_name(vm_proxy));
          info.uuid = to_string(qemu_dbus_display1_vm_get_uuid(vm_proxy));
          for (const auto &[id, proxy] : console_proxies) {
            console_info_t console;
            console.id = id;
            console.label = to_string(qemu_dbus_display1_console_get_label(proxy));
            console.type = to_string(qemu_dbus_display1_console_get_type_(proxy));
            console.head = qemu_dbus_display1_console_get_head(proxy);
            console.width = qemu_dbus_display1_console_get_width(proxy);
            console.height = qemu_dbus_display1_console_get_height(proxy);
            console.interfaces = to_strings(qemu_dbus_display1_console_get_interfaces(proxy));
            info.consoles.emplace_back(std::move(console));
          }
        });
        return info;
      }
      bool alive() const override {
        return is_alive;
      }
      std::unique_ptr<listener_registration_t> register_listener(std::uint32_t console_id, std::shared_ptr<display_listener_t> listener) override {
        auto registration = std::make_unique<listener_impl_t>(shared_from_this(), std::move(listener));
        bool ok = false;
        deadline_t deadline {timeout};
        loop.invoke([&]() {
          ok = register_listener_on_loop(console_id, *registration, deadline.cancellable);
        });
        if (!ok) {
          return nullptr;
        }
        return registration;
      }
      /**
       * @brief Thread that owns the bus connection and makes blocking calls to QEMU.
       */
      mutable loop_thread_t loop;
      /**
       * @brief Thread that dispatches listener connections and never blocks on QEMU.
       * @details QEMU makes synchronous calls on a new listener (property fetch, ScanoutMap) right
       * after replying to RegisterListener. Answering them from the thread that may be blocked in
       * another RegisterListener would deadlock both processes until the call timeout.
       */
      loop_thread_t listener_loop;
    private:
      /**
       * @brief Connect and read properties; runs on the loop thread.
       *
       * @param address Bus address, or empty for the session bus.
       * @param cancellable Cancels blocking calls when the deadline passes.
       * @return True when QEMU was found.
       */
      bool connect_bus_on_loop(const std::string &address, GCancellable *cancellable) {
        GError *err = nullptr;
        std::string resolved = address;
        if (resolved.empty()) {
          auto session_address = g_dbus_address_get_for_bus_sync(G_BUS_TYPE_SESSION, cancellable, &err);
          if (!session_address) {
            BOOST_LOG(error) << "qemu: no session bus address: "sv << err->message;
            g_clear_error(&err);
            return false;
          }
          resolved = session_address;
          g_free(session_address);
        }
        connection = g_dbus_connection_new_for_address_sync(resolved.c_str(), (GDBusConnectionFlags) (G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT | G_DBUS_CONNECTION_FLAGS_MESSAGE_BUS_CONNECTION), nullptr, cancellable, &err);
        if (!connection) {
          BOOST_LOG(error) << "qemu: couldn't connect to D-Bus address ["sv << resolved << "]: "sv << err->message;
          g_clear_error(&err);
          return false;
        }
        g_dbus_connection_set_exit_on_close(connection, FALSE);
        closed_handler = g_signal_connect(connection, "closed", G_CALLBACK(&session_impl_t::on_bus_closed), this);
        vm_proxy = qemu_dbus_display1_vm_proxy_new_sync(connection, G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START, bus_name, vm_path, cancellable, &err);
        if (!vm_proxy) {
          BOOST_LOG(error) << "qemu: couldn't create VM proxy: "sv << err->message;
          g_clear_error(&err);
          return false;
        }
        g_dbus_proxy_set_default_timeout(G_DBUS_PROXY(vm_proxy), timeout_ms);
        auto owner = g_dbus_proxy_get_name_owner(G_DBUS_PROXY(vm_proxy));
        if (!owner) {
          BOOST_LOG(error) << "qemu: no QEMU owns ["sv << bus_name << "] on ["sv << resolved << ']';
          return false;
        }
        g_free(owner);
        auto ids = qemu_dbus_display1_vm_get_console_ids(vm_proxy);
        if (!ids) {
          BOOST_LOG(error) << "qemu: VM has no ConsoleIDs property; is -display dbus enabled?"sv;
          return false;
        }
        gsize count = 0;
        auto id_values = (const guint32 *) g_variant_get_fixed_array(ids, &count, sizeof(guint32));
        for (gsize i = 0; i < count; ++i) {
          auto path = "/org/qemu/Display1/Console_" + std::to_string(id_values[i]);
          auto proxy = qemu_dbus_display1_console_proxy_new_sync(connection, G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START, bus_name, path.c_str(), cancellable, &err);
          if (!proxy) {
            BOOST_LOG(warning) << "qemu: skipping console "sv << id_values[i] << ": "sv << err->message;
            g_clear_error(&err);
            continue;
          }
          g_dbus_proxy_set_default_timeout(G_DBUS_PROXY(proxy), timeout_ms);
          console_proxies.emplace_back(id_values[i], proxy);
        }
        name_watch = g_bus_watch_name_on_connection(connection, bus_name, G_BUS_NAME_WATCHER_FLAGS_NONE, nullptr, &session_impl_t::on_name_vanished, this, nullptr);
        BOOST_LOG(info) << "qemu: connected to VM ["sv << to_string(qemu_dbus_display1_vm_get_name(vm_proxy)) << "] with "sv << console_proxies.size() << " console(s)"sv;
        is_alive = true;
        return true;
      }
      /**
       * @brief Release every GDBus object; runs on the loop thread.
       */
      void disconnect_bus() {
        is_alive = false;
        if (name_watch) {
          g_bus_unwatch_name(name_watch);
          name_watch = 0;
        }
        for (auto &[id, proxy] : console_proxies) {
          g_object_unref(proxy);
        }
        console_proxies.clear();
        g_clear_object(&vm_proxy);
        if (connection) {
          g_signal_handler_disconnect(connection, closed_handler);
          g_dbus_connection_close_sync(connection, nullptr, nullptr);
          g_clear_object(&connection);
        }
      }
      /**
       * @brief Hand one end of a socket pair to `Console.RegisterListener`; runs on the loop thread.
       *
       * @param console_id Console to register on.
       * @param registration Registration to start on success.
       * @param cancellable Cancels blocking calls when the deadline passes.
       * @return True when the listener is registered.
       */
      bool register_listener_on_loop(std::uint32_t console_id, listener_impl_t &registration, GCancellable *cancellable) {
        auto it = std::ranges::find_if(console_proxies, [&](const auto &entry) {
          return entry.first == console_id;
        });
        if (it == console_proxies.end() || !is_alive) {
          BOOST_LOG(error) << "qemu: console "sv << console_id << " is not available"sv;
          return false;
        }
        int fds[2];
        if (socketpair(AF_UNIX, SOCK_STREAM | SOCK_CLOEXEC, 0, fds) != 0) {
          BOOST_LOG(error) << "qemu: socketpair failed: "sv << std::strerror(errno);
          return false;
        }
        fd_t ours {fds[0]};
        fd_t theirs {fds[1]};
        GError *err = nullptr;
        auto fd_list = g_unix_fd_list_new();
        auto index = g_unix_fd_list_append(fd_list, theirs.get(), &err);
        theirs = fd_t {};
        if (index < 0) {
          BOOST_LOG(error) << "qemu: couldn't attach listener socket: "sv << err->message;
          g_clear_error(&err);
          g_object_unref(fd_list);
          return false;
        }
        bool ok = qemu_dbus_display1_console_call_register_listener_sync(it->second, g_variant_new_handle(index), G_DBUS_CALL_FLAGS_NONE, timeout_ms, fd_list, nullptr, cancellable, &err);
        g_object_unref(fd_list);
        if (!ok) {
          BOOST_LOG(error) << "qemu: RegisterListener on console "sv << console_id << " failed: "sv << err->message;
          g_clear_error(&err);
          return false;
        }
        bool started = false;
        listener_loop.invoke([&]() {
          started = registration.start(std::move(ours), cancellable);
        });
        return started;
      }
      static void on_bus_closed(GDBusConnection *connection, gboolean remote_peer_vanished, GError *err, gpointer self) {
        BOOST_LOG(warning) << "qemu: D-Bus connection closed"sv;
        ((session_impl_t *) self)->is_alive = false;
      }
      static void on_name_vanished(GDBusConnection *connection, const gchar *name, gpointer self) {
        BOOST_LOG(warning) << "qemu: ["sv << name << "] vanished from the bus"sv;
        ((session_impl_t *) self)->is_alive = false;
      }
      std::chrono::milliseconds timeout;  ///< Deadline for connection setup and registration.
      int timeout_ms;  ///< Timeout applied to each D-Bus call.
      std::atomic<bool> is_alive {false};  ///< Whether QEMU is reachable.
      GDBusConnection *connection {nullptr};  ///< Bus connection.
      gulong closed_handler {0};  ///< Handler id of the connection's "closed" signal.
      guint name_watch {0};  ///< Watch on `org.qemu`.
      QemuDBusDisplay1VM *vm_proxy {nullptr};  ///< VM proxy.
      std::vector<std::pair<std::uint32_t, QemuDBusDisplay1Console *>> console_proxies;  ///< Console proxies in ConsoleIDs order.
    };
    listener_impl_t::listener_impl_t(std::shared_ptr<session_impl_t> session, std::shared_ptr<display_listener_t> listener):
        session {std::move(session)},
        listener {std::move(listener)} {
    }
    listener_impl_t::~listener_impl_t() {
      session->listener_loop.invoke([this]() {
        stop();
      });
    }
    bool listener_impl_t::start(fd_t socket_fd, GCancellable *cancellable) {
      GError *err = nullptr;
      auto socket = g_socket_new_from_fd(socket_fd.get(), &err);
      if (!socket) {
        BOOST_LOG(error) << "qemu: couldn't wrap listener socket: "sv << err->message;
        g_clear_error(&err);
        return false;
      }
      socket_fd.release();
      auto socket_connection = g_socket_connection_factory_create_connection(socket);
      g_object_unref(socket);
      // QEMU is the authentication server on this socket. Delay message processing so QEMU's first
      // calls (property fetch, ScanoutMap) queue until the listener objects are exported.
      connection = g_dbus_connection_new_sync(G_IO_STREAM(socket_connection), nullptr, (GDBusConnectionFlags) (G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT | G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING), nullptr, cancellable, &err);
      g_object_unref(socket_connection);
      if (!connection) {
        BOOST_LOG(error) << "qemu: listener handshake failed: "sv << err->message;
        g_clear_error(&err);
        return false;
      }
      g_dbus_connection_set_exit_on_close(connection, FALSE);
      skeleton = qemu_dbus_display1_listener_skeleton_new();
      const gchar *interfaces[] = {unix_map_interface, nullptr};
      qemu_dbus_display1_listener_set_interfaces(skeleton, interfaces);
      g_signal_connect(skeleton, "handle-scanout", G_CALLBACK(&listener_impl_t::on_scanout), this);
      g_signal_connect(skeleton, "handle-update", G_CALLBACK(&listener_impl_t::on_update), this);
      g_signal_connect(skeleton, "handle-scanout-dmabuf", G_CALLBACK(&listener_impl_t::on_scanout_dmabuf), this);
      g_signal_connect(skeleton, "handle-update-dmabuf", G_CALLBACK(&listener_impl_t::on_update_dmabuf), this);
      g_signal_connect(skeleton, "handle-disable", G_CALLBACK(&listener_impl_t::on_disable), this);
      g_signal_connect(skeleton, "handle-mouse-set", G_CALLBACK(&listener_impl_t::on_mouse_set), this);
      g_signal_connect(skeleton, "handle-cursor-define", G_CALLBACK(&listener_impl_t::on_cursor_define), this);
      map_skeleton = qemu_dbus_display1_listener_unix_map_skeleton_new();
      g_signal_connect(map_skeleton, "handle-scanout-map", G_CALLBACK(&listener_impl_t::on_scanout_map), this);
      g_signal_connect(map_skeleton, "handle-update-map", G_CALLBACK(&listener_impl_t::on_update_map), this);
      if (!g_dbus_interface_skeleton_export(G_DBUS_INTERFACE_SKELETON(skeleton), connection, listener_path, &err) || !g_dbus_interface_skeleton_export(G_DBUS_INTERFACE_SKELETON(map_skeleton), connection, listener_path, &err)) {
        BOOST_LOG(error) << "qemu: couldn't export listener: "sv << err->message;
        g_clear_error(&err);
        stop();
        return false;
      }
      g_signal_connect(connection, "closed", G_CALLBACK(&listener_impl_t::on_closed), this);
      g_dbus_connection_start_message_processing(connection);
      return true;
    }
    void listener_impl_t::stop() {
      if (skeleton) {
        g_signal_handlers_disconnect_by_data(skeleton, this);
        g_dbus_interface_skeleton_unexport(G_DBUS_INTERFACE_SKELETON(skeleton));
        g_clear_object(&skeleton);
      }
      if (map_skeleton) {
        g_signal_handlers_disconnect_by_data(map_skeleton, this);
        g_dbus_interface_skeleton_unexport(G_DBUS_INTERFACE_SKELETON(map_skeleton));
        g_clear_object(&map_skeleton);
      }
      if (connection) {
        g_signal_handlers_disconnect_by_data(connection, this);
        if (!closed) {
          g_dbus_connection_close_sync(connection, nullptr, nullptr);
        }
        g_clear_object(&connection);
      }
    }
    gboolean listener_impl_t::on_scanout(QemuDBusDisplay1Listener *object, GDBusMethodInvocation *invocation, guint width, guint height, guint stride, guint format, GVariant *data, gpointer self) {
      gsize size = 0;
      auto bytes = (const std::uint8_t *) g_variant_get_fixed_array(data, &size, 1);
      ((listener_impl_t *) self)->listener->scanout(width, height, stride, format, {bytes, size});
      qemu_dbus_display1_listener_complete_scanout(object, invocation);
      return TRUE;
    }
    gboolean listener_impl_t::on_update(QemuDBusDisplay1Listener *object, GDBusMethodInvocation *invocation, gint x, gint y, gint width, gint height, guint stride, guint format, GVariant *data, gpointer self) {
      gsize size = 0;
      auto bytes = (const std::uint8_t *) g_variant_get_fixed_array(data, &size, 1);
      ((listener_impl_t *) self)->listener->update(x, y, width, height, stride, format, {bytes, size});
      qemu_dbus_display1_listener_complete_update(object, invocation);
      return TRUE;
    }
    gboolean listener_impl_t::on_scanout_dmabuf(QemuDBusDisplay1Listener *object, GDBusMethodInvocation *invocation, GUnixFDList *fd_list, GVariant *dmabuf, guint width, guint height, guint stride, guint fourcc, guint64 modifier, gboolean y0_top, gpointer self) {
      // DMABUF scanouts need a GL display in QEMU and are handled by the vram capture path (REQ-CAP-003).
      static std::once_flag logged;
      std::call_once(logged, []() {
        BOOST_LOG(warning) << "qemu: ignoring DMABUF scanout; start QEMU without gl=on for shared memory capture"sv;
      });
      qemu_dbus_display1_listener_complete_scanout_dmabuf(object, invocation, nullptr);
      return TRUE;
    }
    gboolean listener_impl_t::on_update_dmabuf(QemuDBusDisplay1Listener *object, GDBusMethodInvocation *invocation, gint x, gint y, gint width, gint height, gpointer self) {
      qemu_dbus_display1_listener_complete_update_dmabuf(object, invocation);
      return TRUE;
    }
    gboolean listener_impl_t::on_disable(QemuDBusDisplay1Listener *object, GDBusMethodInvocation *invocation, gpointer self) {
      ((listener_impl_t *) self)->listener->disable();
      qemu_dbus_display1_listener_complete_disable(object, invocation);
      return TRUE;
    }
    gboolean listener_impl_t::on_mouse_set(QemuDBusDisplay1Listener *object, GDBusMethodInvocation *invocation, gint x, gint y, gint on, gpointer self) {
      ((listener_impl_t *) self)->listener->mouse_set(x, y, on != 0);
      qemu_dbus_display1_listener_complete_mouse_set(object, invocation);
      return TRUE;
    }
    gboolean listener_impl_t::on_cursor_define(QemuDBusDisplay1Listener *object, GDBusMethodInvocation *invocation, gint width, gint height, gint hot_x, gint hot_y, GVariant *data, gpointer self) {
      gsize size = 0;
      auto bytes = (const std::uint8_t *) g_variant_get_fixed_array(data, &size, 1);
      ((listener_impl_t *) self)->listener->cursor_define(width, height, hot_x, hot_y, {bytes, size});
      qemu_dbus_display1_listener_complete_cursor_define(object, invocation);
      return TRUE;
    }
    gboolean listener_impl_t::on_scanout_map(QemuDBusDisplay1ListenerUnixMap *object, GDBusMethodInvocation *invocation, GUnixFDList *fd_list, GVariant *handle, guint offset, guint width, guint height, guint stride, guint format, gpointer self) {
      GError *err = nullptr;
      int fd = fd_list ? g_unix_fd_list_get(fd_list, g_variant_get_handle(handle), &err) : -1;
      if (fd < 0) {
        BOOST_LOG(error) << "qemu: ScanoutMap without a valid descriptor"sv;
        if (err) {
          g_dbus_method_invocation_return_gerror(invocation, err);
          g_clear_error(&err);
        } else {
          g_dbus_method_invocation_return_error_literal(invocation, G_DBUS_ERROR, G_DBUS_ERROR_INVALID_ARGS, "missing descriptor");
        }
        return TRUE;
      }
      ((listener_impl_t *) self)->listener->scanout_map(fd_t {fd}, offset, width, height, stride, format);
      qemu_dbus_display1_listener_unix_map_complete_scanout_map(object, invocation, nullptr);
      return TRUE;
    }
    gboolean listener_impl_t::on_update_map(QemuDBusDisplay1ListenerUnixMap *object, GDBusMethodInvocation *invocation, gint x, gint y, gint width, gint height, gpointer self) {
      ((listener_impl_t *) self)->listener->update_map(x, y, width, height);
      qemu_dbus_display1_listener_unix_map_complete_update_map(object, invocation);
      return TRUE;
    }
    void listener_impl_t::on_closed(GDBusConnection *connection, gboolean remote_peer_vanished, GError *err, gpointer self) {
      auto registration = (listener_impl_t *) self;
      BOOST_LOG(info) << "qemu: display listener connection closed"sv;
      registration->closed = true;
      registration->listener->disconnected();
    }
  }  // namespace
  fd_t::fd_t(int fd):
      fd {fd} {
  }
  fd_t::fd_t(fd_t &&other) noexcept:
      fd {std::exchange(other.fd, -1)} {
  }
  fd_t &fd_t::operator=(fd_t &&other) noexcept {
    if (this != &other) {
      if (fd >= 0) {
        close(fd);
      }
      fd = std::exchange(other.fd, -1);
    }
    return *this;
  }
  fd_t::~fd_t() {
    if (fd >= 0) {
      close(fd);
    }
  }
  int fd_t::release() {
    return std::exchange(fd, -1);
  }
  std::shared_ptr<session_t> session_t::connect(const std::string &address, std::chrono::milliseconds timeout) {
    auto session = std::make_shared<session_impl_t>(timeout);
    if (!session->connect_bus(address)) {
      return nullptr;
    }
    return session;
  }
  std::shared_ptr<session_t> shared_session(const std::string &address) {
    static std::mutex mutex;
    static std::weak_ptr<session_t> cached;
    static std::string cached_address;
    std::lock_guard lock {mutex};
    if (auto session = cached.lock(); session && session->alive() && cached_address == address) {
      return session;
    }
    auto session = session_t::connect(address);
    cached = session;
    cached_address = address;
    return session;
  }
  std::optional<console_info_t> find_console(const vm_info_t &vm, std::string_view name) {
    if (name.empty()) {
      auto it = std::ranges::find_if(vm.consoles, &console_info_t::is_graphic);
      if (it == vm.consoles.end()) {
        return std::nullopt;
      }
      return *it;
    }
    std::uint32_t id = 0;
    auto [end, ec] = std::from_chars(name.data(), name.data() + name.size(), id);
    bool is_id = ec == std::errc {} && end == name.data() + name.size();
    auto it = std::ranges::find_if(vm.consoles, [&](const console_info_t &console) {
      return is_id ? console.id == id : console.label == name;
    });
    if (it == vm.consoles.end()) {
      return std::nullopt;
    }
    return *it;
  }
  std::vector<std::string> graphic_console_names(const vm_info_t &vm) {
    std::vector<std::string> names;
    for (const auto &console : vm.consoles) {
      if (console.is_graphic()) {
        names.emplace_back(std::to_string(console.id));
      }
    }
    return names;
  }
}  // namespace qemu

@@ -1,0 +1,286 @@
/**
 * @file src/platform/linux/qemu/session.h
 * @brief Declarations for the QEMU D-Bus display session.
 * @details The session connects to the D-Bus bus that a QEMU started with `-display dbus` owns
 * `org.qemu` on, discovers the VM consoles, and registers peer-to-peer display listeners. It only
 * depends on GLib/GIO and POSIX so it can be reused by other Unix hosts.
 */
#pragma once
// standard includes
#include <chrono>
#include <cstdint>
#include <memory>
#include <optional>
#include <span>
#include <string>
#include <string_view>
#include <vector>
namespace qemu {
  using namespace std::literals;
  /**
   * @brief Pixman format codes used by QEMU display scanouts.
   * @details Values follow pixman's `PIXMAN_FORMAT(bpp, type, a, r, g, b)` encoding. They are
   * defined here so the capture backend does not need to link against pixman.
   */
  namespace pixman_format {
    inline constexpr std::uint32_t x8r8g8b8 = 0x20020888;  ///< 32 bpp, B G R X byte order on little-endian hosts.
    inline constexpr std::uint32_t a8r8g8b8 = 0x20028888;  ///< 32 bpp, B G R A byte order on little-endian hosts.
    inline constexpr std::uint32_t x8b8g8r8 = 0x20030888;  ///< 32 bpp, R G B X byte order on little-endian hosts.
    inline constexpr std::uint32_t a8b8g8r8 = 0x20038888;  ///< 32 bpp, R G B A byte order on little-endian hosts.
  }  // namespace pixman_format
  /**
   * @brief Move-only owner of a POSIX file descriptor.
   */
  class fd_t {
  public:
    fd_t() = default;
    /**
     * @brief Take ownership of a file descriptor.
     *
     * @param fd File descriptor to own, or -1 for none.
     */
    explicit fd_t(int fd);
    /**
     * @brief Transfer ownership from another descriptor owner.
     *
     * @param other Owner to take the descriptor from.
     */
    fd_t(fd_t &&other) noexcept;
    /**
     * @brief Replace the owned descriptor with the one held by another owner.
     *
     * @param other Owner to take the descriptor from.
     * @return This owner.
     */
    fd_t &operator=(fd_t &&other) noexcept;
    fd_t(const fd_t &) = delete;
    fd_t &operator=(const fd_t &) = delete;
    ~fd_t();
    /**
     * @brief Access the owned descriptor without releasing it.
     *
     * @return The owned descriptor, or -1 when empty.
     */
    [[nodiscard]] int get() const {
      return fd;
    }
    /**
     * @brief Release ownership of the descriptor.
     *
     * @return The descriptor, which the caller must close.
     */
    int release();
  private:
    int fd {-1};  ///< Owned descriptor, or -1 when empty.
  };
  /**
   * @brief Snapshot of one QEMU console.
   */
  struct console_info_t {
    std::uint32_t id {0};  ///< Console id, as used in `/org/qemu/Display1/Console_<id>`.
    std::string label;  ///< User-friendly console name, for example "VGA".
    std::string type;  ///< Console type, "Graphic" or "Text".
    std::uint32_t head {0};  ///< Graphical device head number.
    std::uint32_t width {0};  ///< Console width in pixels.
    std::uint32_t height {0};  ///< Console height in pixels.
    std::vector<std::string> interfaces;  ///< Extra interfaces advertised by the console object.
    /**
     * @brief Report whether this console shows graphics.
     *
     * @return True when the console type is "Graphic".
     */
    [[nodiscard]] bool is_graphic() const {
      return type == "Graphic";
    }
  };
  /**
   * @brief Snapshot of the VM exported by QEMU.
   */
  struct vm_info_t {
    std::string name;  ///< VM name (`-name`).
    std::string uuid;  ///< VM UUID.
    std::vector<console_info_t> consoles;  ///< Consoles listed by `ConsoleIDs`, in QEMU order.
  };
  /**
   * @brief Receiver for the `org.qemu.Display1.Listener` calls QEMU makes.
   * @details All methods are invoked on the session's listener thread. Implementations must return
   * quickly and must not call back into the session synchronously from a different thread while
   * holding locks that the caller of the session may also take.
   */
  class display_listener_t {
  public:
    virtual ~display_listener_t() = default;
    /**
     * @brief Handle a full-frame scanout carried in the message.
     *
     * @param width Display width in pixels.
     * @param height Display height in pixels.
     * @param stride Bytes per row in `data`.
     * @param format Pixman format code of `data`.
     * @param data Pixel data, valid only for the duration of the call.
     */
    virtual void scanout(std::uint32_t width, std::uint32_t height, std::uint32_t stride, std::uint32_t format, std::span<const std::uint8_t> data) = 0;
    /**
     * @brief Handle a partial update carried in the message.
     *
     * @param x Left edge of the updated rectangle.
     * @param y Top edge of the updated rectangle.
     * @param width Width of the updated rectangle.
     * @param height Height of the updated rectangle.
     * @param stride Bytes per row in `data`.
     * @param format Pixman format code of `data`.
     * @param data Pixel data for the rectangle, valid only for the duration of the call.
     */
    virtual void update(std::int32_t x, std::int32_t y, std::int32_t width, std::int32_t height, std::uint32_t stride, std::uint32_t format, std::span<const std::uint8_t> data) = 0;
    /**
     * @brief Handle a scanout backed by shared memory.
     *
     * @param fd Shared memory descriptor; ownership moves to the listener.
     * @param offset Offset of the first pixel in the mapping, in bytes.
     * @param width Display width in pixels.
     * @param height Display height in pixels.
     * @param stride Bytes per row.
     * @param format Pixman format code.
     */
    virtual void scanout_map(fd_t fd, std::uint32_t offset, std::uint32_t width, std::uint32_t height, std::uint32_t stride, std::uint32_t format) = 0;
    /**
     * @brief Handle damage on the current shared memory scanout.
     *
     * @param x Left edge of the damaged rectangle.
     * @param y Top edge of the damaged rectangle.
     * @param width Width of the damaged rectangle.
     * @param height Height of the damaged rectangle.
     */
    virtual void update_map(std::int32_t x, std::int32_t y, std::int32_t width, std::int32_t height) = 0;
    /**
     * @brief Handle the display being turned off.
     */
    virtual void disable() = 0;
    /**
     * @brief Handle a cursor position or visibility change.
     *
     * @param x Cursor X position in pixels.
     * @param y Cursor Y position in pixels.
     * @param visible Whether the cursor is visible.
     */
    virtual void mouse_set(std::int32_t x, std::int32_t y, bool visible) {
    }
    /**
     * @brief Handle a new cursor shape.
     *
     * @param width Cursor width in pixels.
     * @param height Cursor height in pixels.
     * @param hot_x Hot-spot X position.
     * @param hot_y Hot-spot Y position.
     * @param data ARGB32 cursor pixels, valid only for the duration of the call.
     */
    virtual void cursor_define(std::int32_t width, std::int32_t height, std::int32_t hot_x, std::int32_t hot_y, std::span<const std::uint8_t> data) {
    }
    /**
     * @brief Handle the peer-to-peer connection to QEMU closing.
     * @details Called at most once. No other method is called afterwards.
     */
    virtual void disconnected() = 0;
  };
  /**
   * @brief Registration of a display listener; destroying it unregisters the listener.
   * @details After the destructor returns, no method of the listener is invoked again.
   */
  class listener_registration_t {
  public:
    virtual ~listener_registration_t() = default;
  };
  /**
   * @brief Connection to the D-Bus display of one QEMU VM.
   * @details All public methods are thread-safe.
   */
  class session_t {
  public:
    /**
     * @brief Connect to a bus where QEMU owns `org.qemu` and discover its consoles.
     *
     * @param address D-Bus address of the bus, or empty for the session bus.
     * @param timeout Timeout applied to each D-Bus call.
     * @return Connected session, or nullptr when the bus or QEMU is unreachable.
     */
    static std::shared_ptr<session_t> connect(const std::string &address, std::chrono::milliseconds timeout = 5s);
    virtual ~session_t() = default;
    /**
     * @brief Snapshot the VM properties, including the current console sizes.
     *
     * @return VM information.
     */
    [[nodiscard]] virtual vm_info_t vm() const = 0;
    /**
     * @brief Report whether QEMU is still reachable.
     *
     * @return False once the bus connection closed or `org.qemu` lost its owner.
     */
    [[nodiscard]] virtual bool alive() const = 0;
    /**
     * @brief Register a display listener on a console.
     *
     * @param console_id Id of the console to listen to.
     * @param listener Receiver for the display calls; kept alive by the registration.
     * @return Registration handle, or nullptr when QEMU refused the listener.
     */
    virtual std::unique_ptr<listener_registration_t> register_listener(std::uint32_t console_id, std::shared_ptr<display_listener_t> listener) = 0;
  };
  /**
   * @brief Get the live session for an address, connecting when there is none.
   * @details Capture, input, and audio share one session while any of them holds it. A session
   * whose QEMU went away is replaced by a new connection attempt.
   *
   * @param address D-Bus address, or empty for the session bus.
   * @return Live session, or nullptr when QEMU is unreachable.
   */
  std::shared_ptr<session_t> shared_session(const std::string &address);
  /**
   * @brief Find a console by id or label.
   *
   * @param vm VM information to search.
   * @param name Console id, label, or empty for the first graphical console.
   * @return Matching console, or nothing when no console matches.
   */
  std::optional<console_info_t> find_console(const vm_info_t &vm, std::string_view name);
  /**
   * @brief List the names Sunshine uses for the graphical consoles.
   *
   * @param vm VM information to list.
   * @return Console ids as strings, for graphical consoles only.
   */
  std::vector<std::string> graphic_console_names(const vm_info_t &vm);
}  // namespace qemu