Wine-NSPA – NSPA X11 Embed Protocol

This page documents Wine-NSPA’s X11 embed protocol for winelib hosts that need to place a Wine HWND-backed X11 child under a foreign Linux parent window.

Table of Contents

1. Overview
2. Public contract
3. Embed lifecycle
4. Geometry and resize ownership
5. Consumer pump discipline
6. Input and drag correctness
7. Current consumers
8. References

1. Overview

The embed protocol gives a winelib host one supported way to reparent a Wine window into a foreign X11 parent without reimplementing Wine’s embedded-window bookkeeping itself.

This page is X11-specific. Wayland embedding uses a separate Wine-NSPA contract because host and Wine surfaces must share one wl_display and the native parent relation is a wl_subsurface, not an X11 reparent.

The problem it solves is not just XReparentWindow(). A working host also needs Wine to:

• flip the window into embedded mode
• register the foreign parent for host-window tracking
• preserve the correct parent-relative origin at the moment embedded mode locks
• avoid emitting the wrong X11 move/size requests after the handoff
• keep Win32 hit-testing and cursor math coherent while the host moves or resizes the embedded surface

Wine-NSPA exposes that as a small driver-private message contract instead of making each host rebuild the old wrapper-window and synthetic event machinery.

2. Public contract

The supported interface lives in include/wine/nspa_x11_embed.h.

2.1 WM_X11DRV_NSPA_EMBED_WINDOW

Send the message to the top-level Wine HWND that owns the X11 child.

peerX and peerY are load-bearing. Wine locks embedded-mode position state when the window flips into embedded mode, so the initial reparent has to use the host’s intended parent-relative origin.

2.2 WM_X11DRV_NSPA_EMBED_DONE

Wine posts WM_X11DRV_NSPA_EMBED_DONE back to the same HWND after:

• XReparentWindow()
• XMapWindow()
• the WM state cycle has settled

The message is asynchronous. It lands on the HWND’s message queue and is observed when the host’s Win32 message pump runs.

2.3 Consumer responsibilities

The protocol does not make the host passive. After the embed handoff:

• the host owns X11 parentage
• the host owns X11 sizing with XMoveResizeWindow() or equivalent
• the host still uses SetWindowPos() so Wine’s Win32-side rects track the correct absolute screen location
• the host pumps the embedded HWND’s thread queue with a bounded general drain

That split is deliberate: Wine keeps Win32 state authoritative, while the host keeps the X11 embed tree authoritative.

2.4 Minimal host-side flow

The working host-side sequence is small, but each step is load-bearing:

SendMessageW(embedHwnd, WM_X11DRV_NSPA_EMBED_WINDOW,
             (WPARAM) foreignParent,
             MAKELPARAM(peerX, peerY));

for (;;) {
    while (PeekMessageW(&msg, nullptr, WM_MOUSEFIRST, WM_MOUSELAST, PM_REMOVE)) {
        TranslateMessage(&msg);
        DispatchMessageW(&msg);
    }
    while (PeekMessageW(&msg, nullptr, WM_KEYFIRST, WM_KEYLAST, PM_REMOVE)) {
        TranslateMessage(&msg);
        DispatchMessageW(&msg);
    }

    const auto deadlineMs = now_ms() + 4;
    while (PeekMessageW(&msg, nullptr, 0, 0, PM_REMOVE)) {
        if (msg.message == WM_X11DRV_NSPA_EMBED_DONE)
            goto embed_done;
        TranslateMessage(&msg);
        DispatchMessageW(&msg);
        if (now_ms() >= deadlineMs)
            break;
    }

    poll_linux_host_events();
}

embed_done:
    ;

After that completion edge, the host still owns X11 geometry:

SetWindowPos(embedHwnd, 0, screenX, screenY, width, height, SWP_NOZORDER);
XMoveResizeWindow(display, wineChild, peerX, peerY, width, height);

That split is the protocol. SetWindowPos() keeps Wine’s Win32-side rects honest; XMoveResizeWindow() keeps the foreign-parent X11 tree honest.

3. Embed lifecycle

The runtime sequence is:

1. the host creates a real top-level Wine HWND
2. the host resolves the backing X11 child and the foreign X11 parent
3. the host sends WM_X11DRV_NSPA_EMBED_WINDOW
4. winex11.drv reparents the child at the supplied parent-relative origin
5. Wine flips the window to embedded mode and records the foreign parent
6. Wine maps the X11 child and posts WM_X11DRV_NSPA_EMBED_DONE

Two details matter:

• the reparent happens before embedded-mode position locking
• the embed path is idempotent with respect to parent changes, so the same HWND can be re-embedded under a new parent when the host changes peer structure

This is why the protocol replaces a pile of host-local X11 bookkeeping instead of just hiding one XReparentWindow() call.

4. Geometry and resize ownership

After the embed handoff, geometry ownership is intentionally split.

In practice that means:

• the host calls SetWindowPos() when the embedded child moves in screen space
• the host also calls XMoveResizeWindow() or xcb_configure_window() on the embedded X11 child when the parent-relative X11 geometry changes
• Wine suppresses its own X11 position and size emission for nspa_embedded windows so the embedder stays authoritative at the X11 layer

5. Consumer pump discipline

WM_X11DRV_NSPA_EMBED_DONE is only one part of the consumer contract. The host-side message pump also matters.

The incorrect shape is an unbounded while (PeekMessage) drain on the same thread that must return to X11 polling. A redraw-heavy plugin can keep the queue non-empty with WM_TIMER and WM_PAINT, which means:

• the Win32 pump never returns
• the Linux host stops polling X11
• queued X11 mouse and keyboard input never reaches the plugin editor

The required shape is:

6. Input and drag correctness

Two follow-on pieces keep embedded editors usable under host motion and plugin cursor save/restore behavior.

6.1 Host-drag rect propagation

When the host moves the embedded child at the X11 layer, Wine also updates the Win32-side rect state for the embedded HWND. That keeps:

• USER32 hit-testing
• screen-to-client coordinate translation
• plugin code that queries window position

in sync with the host’s actual X11 layout.

6.2 Button-state freeze and cursor-jump suppression

During click-drag-release sequences, plugins may save screen coordinates on mouse-down and call SetCursorPos() on release. Mid-drag rect churn can make that restore point wrong.

Wine-NSPA therefore:

• freezes host-drag rect updates while mouse buttons are held on an embedded child
• suppresses the cursor-warp-on-release mismatch that showed up on embedded VST editors

The result is not a generic mouse optimization. It is targeted correctness for embedded Win32 editors living inside foreign X11 hosts.

7. Current consumers

The protocol is currently used by Wine-NSPA winelib hosts that embed Win32 plugin editors into native Linux UI trees.

The protocol stays intentionally small. It is a Wine-side primitive for hosts that already manage a foreign X11 parent, not a full host toolkit.

8. References

• include/wine/nspa_x11_embed.h
• dlls/win32u/message.c
• dlls/winex11.drv/window.c
• dlls/winex11.drv/mouse.c
• NSPA Wayland Embed Protocol
• JUCE-NSPA
• Lulada
• Yabridge-NSPA