275 lines
11 KiB
Markdown
275 lines
11 KiB
Markdown
# WindowMaker Wayland Port — Roadmap
|
|
|
|
Last updated: 2026-05-14
|
|
|
|
## Governing Principles
|
|
|
|
1. **No guards in the middle** — the core (src/, wrlib/, WINGs/) never asks "am I on
|
|
X11 or Wayland?" Backend-specific behavior lives exclusively in the backend that
|
|
owns it. Zero `#ifdef WAYLAND` or runtime backend checks in shared code.
|
|
|
|
2. **Duplication over coupling** — if both backends need similar-but-not-identical
|
|
logic, each gets its own copy. Shared abstractions that leak backend details are
|
|
forbidden. Clarity and independence beat DRY.
|
|
|
|
3. **Fail fast, fail loudly** — no defensive null checks, no silent fallbacks, no
|
|
"just in case" guards. If a precondition is violated, crash immediately with a
|
|
clear signal. Defensive coding for the sake of being defensive is not acceptable.
|
|
|
|
4. **Perfect architecture over fewer lines** — the right structure wins even if it
|
|
means more files or duplicated code. Clean separation now buys simple reasoning
|
|
forever.
|
|
|
|
```
|
|
┌─────────────┐ ┌─────────────────────────┐ ┌─────────────────┐
|
|
│ X11 Backend │◄────┤ Core / wrlib / WINGs ├────►│ Wayland Backend │
|
|
└─────────────┘ └─────────────────────────┘ └─────────────────┘
|
|
│ │ │
|
|
backend-specific pure policy, backend-specific
|
|
special cases zero backend guards special cases
|
|
```
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
WindowMaker 0.96.0 uses a vtable-based backend abstraction (`WMBackend` struct in
|
|
`src/backend/backend.h`) with ~150+ function pointer slots. Policy code calls
|
|
`wm_backend->operation(...)` and never touches X11/Wayland APIs directly.
|
|
|
|
Two backends:
|
|
- **X11**: `src/backend/x11/x11_backend.c` (150K)
|
|
- **Wayland**: `src/backend/wayland/wl_backend.c` (316K, wlroots-based compositor)
|
|
|
|
Activation: `WMAKER_USE_WAYLAND=1` env var. Nested mode: `WMAKER_WAYLAND_NESTED=1`.
|
|
|
|
Three major libraries:
|
|
- **src/** — WM core (policy layer, zero Xlib calls remaining)
|
|
- **WINGs/** — Widget toolkit ("WINGs Is Not GNUstep"), split into `_x11.c` / `_wl.c` backends
|
|
- **wrlib/** — Raster graphics library (image loading, manipulation, rendering)
|
|
|
|
---
|
|
|
|
## Completed (as of 2026-05-14)
|
|
|
|
- Backend vtable abstraction (150+ slots)
|
|
- Policy layer fully X11-free (zero direct Xlib calls in WM core)
|
|
- wlroots compositor (headless + nested modes)
|
|
- XDG shell + XWayland bridge
|
|
- Frame rendering (titlebar, buttons, resizebar) via pixman → wlr_scene_buffer
|
|
- Menu rendering + highlighting + item activation
|
|
- Root menu from config file
|
|
- Dock rendering (SHM panel, icon slots, app tracking)
|
|
- Clip rendering
|
|
- Background rendering
|
|
- Mouse input (motion, buttons, scroll, grabs)
|
|
- Keyboard input (XKB, modifiers, keysym translation)
|
|
- Interactive move/resize with edge detection + cursor changes
|
|
- Click-to-focus via hit-testing
|
|
- Run dialog (WINGs modal loop with compositor tick)
|
|
- Window manage/unmanage lifecycle (XDG toplevel + XWayland)
|
|
- Focus delivery (wlr_seat_keyboard_notify_enter)
|
|
- WINGs Wayland backend (views, fonts/PangoFT2, events/ring buffer, rendering/pixman, colors)
|
|
- Smoke test suite (30+ tests in tests/wl-smoke-test.sh)
|
|
|
|
---
|
|
|
|
## Phase A: Core Window Management Gaps
|
|
|
|
Priority: HIGH — needed for daily-driver use.
|
|
|
|
| # | Task | Key Files | Complexity |
|
|
|---|------|-----------|------------|
|
|
| A1 | ~~Stacking (raise/lower via scene graph)~~ | stacking.c, wlr_scene_node_raise/lower | ✅ Done |
|
|
| A2 | ~~Window maximize~~ | actions.c, usable area calc | ✅ Done |
|
|
| A3 | ~~Window shade (titlebar collapse)~~ | actions.c, frame buffer resize | ✅ Done |
|
|
| A4 | Workspace switching (create/destroy/switch) | workspace.c, scene tree reparenting | Medium |
|
|
| A5 | Alt-Tab window cycling + switch panel | cycling.c, switchpanel.c, vtable switchpanel_enter | Medium |
|
|
| A6 | Window iconification (minimize) + miniwindow | icon.c, appicon.c, vtable icon_paint/icon_update_pixmap | Medium |
|
|
| A7 | Window placement algorithms (smart/cascade/random) | placement.c (may already work via vtable) | Low |
|
|
|
|
---
|
|
|
|
## Phase B: Dock & App Icons
|
|
|
|
| # | Task | Key Files | Complexity |
|
|
|---|------|-----------|------------|
|
|
| B1 | App icon rendering (load .tiff/.png, render into dock) | appicon.c, wrlib loaders, vtable appicon_show | Medium |
|
|
| B2 | Dock icon drag & drop (reorder, add/remove) | dock.c DnD handlers | Medium |
|
|
| B3 | Dock auto-launch on login | dock.c session restore | Low |
|
|
| B4 | Clip workspace indicator (number, arrows) | dock.c clip paint | Low |
|
|
| B5 | Drawer support (horizontal dock extension) | dock.c drawer subsystem | Medium |
|
|
| B6 | Icon bounce on launch | vtable appicon_bounce | Low |
|
|
|
|
---
|
|
|
|
## Phase C: Visual Polish & Animations
|
|
|
|
| # | Task | Key Files | Complexity |
|
|
|---|------|-----------|------------|
|
|
| C1 | Slide animations (iconify/deiconify zoom) | vtable slide_window | Medium |
|
|
| C2 | Menu scrolling (long menus) | menu.c scroll logic | Low |
|
|
| C3 | Balloon tooltips (dock icon hover) | vtable balloon_show | Low |
|
|
| C4 | Cursor themes (xcursor loading) | wlr_xcursor_manager | Low |
|
|
| C5 | Window opacity (NETWM alpha) | vtable netwm_set_opacity | Low |
|
|
|
|
---
|
|
|
|
## Phase D: WINGs Widgets (for Preferences & Inspectors)
|
|
|
|
Core rendering backends exist. Complex widgets need verification/porting:
|
|
|
|
| Widget | Needed For | Notes |
|
|
|--------|-----------|-------|
|
|
| WMList | File panels, icon chooser | Test |
|
|
| WMBrowser | File browser in dialogs | Test |
|
|
| WMColorPanel | Color picker in prefs | May need porting |
|
|
| WMFontPanel | Font selection | May need porting |
|
|
| WMFilePanel | Open/save dialogs | Test |
|
|
| WMTabView | Preferences app tabs | Test |
|
|
| WMScroller/WMScrollView | Scrollable content | Test |
|
|
| WMSlider | Preference sliders | Test |
|
|
| WMPopUpButton | Dropdown menus in prefs | Test |
|
|
| WMTextField (advanced) | Multi-line editing | Test |
|
|
| Drag & Drop | Icon DnD, file DnD | Likely needs porting |
|
|
|
|
---
|
|
|
|
## Phase E: Dialogs & Panels
|
|
|
|
| # | Task | Key Files | Complexity |
|
|
|---|------|-----------|------------|
|
|
| E1 | Window Inspector (per-window attributes) | winspector.c | High (many widgets) |
|
|
| E2 | Info Panel (about dialog) | dialog.c | Low |
|
|
| E3 | Crash Dialog (recovery UI) | dialog.c | Low |
|
|
| E4 | Icon Chooser (browse icon files) | dialog.c | Medium |
|
|
| E5 | Preferences App (full GUI) | WPrefs.app/ | High |
|
|
|
|
---
|
|
|
|
## Phase F: wrlib Wayland Integration
|
|
|
|
| # | Task | Description | Complexity |
|
|
|---|------|-------------|------------|
|
|
| F1 | RContext for Wayland | pixman-backed RContext without X11 Display | Medium |
|
|
| F2 | RImage → pixman_image conversion | Direct path without XImage | Low (may exist) |
|
|
| F3 | Texture rendering verification | Solid, gradient, pixmap textures | Verify |
|
|
| F4 | Image format loaders | PNG/JPEG/GIF/WebP (X11-independent) | Verify |
|
|
|
|
---
|
|
|
|
## Phase G: Session & Persistence
|
|
|
|
| # | Task | Key Files | Complexity |
|
|
|---|------|-----------|------------|
|
|
| G1 | Session save/restore (positions, workspaces) | session.c | Medium |
|
|
| G2 | Dock state persistence (icon layout) | dock.c state files | Low (may work) |
|
|
| G3 | Defaults database (~/GNUstep/Defaults/) | defaults.c | Verify |
|
|
| G4 | Autostart (launch apps from session) | startup.c | Low |
|
|
|
|
---
|
|
|
|
## Phase H: Advanced Compositor Features
|
|
|
|
| # | Task | Description | Complexity |
|
|
|---|------|-------------|------------|
|
|
| H1 | Multi-monitor (output layout, per-output workspaces) | wlr_output_layout, screen.c | High |
|
|
| H2 | HiDPI / output scaling | wlr_output_set_scale, buffer scaling | Medium |
|
|
| H3 | Gamma control (night light) | Already advertised, wire up | Low |
|
|
| H4 | Screen lock integration | ext-session-lock-v1 protocol | Medium |
|
|
| H5 | Clipboard (copy/paste between clients) | wl_data_device (may work via wlroots) | Verify |
|
|
| H6 | Primary selection | Already advertised | Verify |
|
|
| H7 | Screencopy (screenshots) | Already advertised | Verify |
|
|
| H8 | DMA-BUF (GPU buffer sharing) | Already advertised | Verify |
|
|
| H9 | Input method (IME support) | Already advertised | Medium |
|
|
|
|
---
|
|
|
|
## Phase I: EWMH / Foreign Toplevel
|
|
|
|
| # | Task | Description | Complexity |
|
|
|---|------|-------------|------------|
|
|
| I1 | Foreign toplevel list (taskbar integration) | Already advertised, verify events | Low |
|
|
| I2 | XDG activation (focus stealing prevention) | Wire to policy | Low |
|
|
| I3 | Idle inhibit (prevent blank during video) | Already advertised | Low |
|
|
|
|
---
|
|
|
|
## Phase J: DRM/KMS Backend (Native)
|
|
|
|
For running without a host compositor:
|
|
|
|
| # | Task | Description | Complexity |
|
|
|---|------|-------------|------------|
|
|
| J1 | DRM backend | wlr_backend_autocreate | Medium |
|
|
| J2 | libinput (real hardware input) | wlroots handles this | Low |
|
|
| J3 | VT switching | wlr_session | Low |
|
|
| J4 | Multi-GPU | Secondary GPU rendering | High |
|
|
|
|
---
|
|
|
|
## Suggested Implementation Order
|
|
|
|
```
|
|
NOW (daily-driver basics):
|
|
A1. Stacking (raise/lower)
|
|
A2. ~~Maximize~~ ✅
|
|
A3. ~~Shade~~ ✅
|
|
A4. Workspace switching
|
|
A5. Alt-Tab cycling
|
|
A6. Icon/minimize
|
|
A7. Placement (verify)
|
|
|
|
NEXT (visual completeness):
|
|
B1. App icon rendering (wrlib → pixman)
|
|
F1. wrlib RContext for Wayland
|
|
C1. Slide animations
|
|
C3. Balloon tooltips
|
|
|
|
THEN (full feature parity):
|
|
D*. Test all WINGs widgets
|
|
E1. Window Inspector
|
|
E4. Icon Chooser
|
|
G*. Session persistence
|
|
B2-B6. Full dock features
|
|
|
|
LATER (production-ready):
|
|
H1. Multi-monitor
|
|
H2. HiDPI
|
|
J*. DRM/KMS native backend
|
|
E5. WPrefs app
|
|
```
|
|
|
|
---
|
|
|
|
## Technical Notes
|
|
|
|
1. **Rendering pattern**: pixman_image_t → wlr_scene_buffer → position in scene graph
|
|
2. **wrlib is mostly X11-independent** — only context.c and convert.c touch X11
|
|
3. **WINGs complex widgets** are the hardest remaining work (subtle X11 assumptions in events/coords)
|
|
4. **wlroots handles compositor plumbing** — protocols advertised, work is wiring to policy
|
|
5. **wl_backend.c (316K) should be split** into wl_frame.c, wl_menu.c, wl_input.c, wl_toplevel.c, wl_output.c as complexity grows
|
|
6. **Many vtable slots are no-ops** — stubs exist, need implementation following the pixman→scene pattern
|
|
|
|
---
|
|
|
|
## Key Source Files Reference
|
|
|
|
| File | Size | Purpose |
|
|
|------|------|---------|
|
|
| src/backend/backend.h | 74K | Vtable definition |
|
|
| src/backend/backend_types.h | 16K | Backend-neutral types |
|
|
| src/backend/wayland/wl_backend.c | 316K | Wayland compositor |
|
|
| src/backend/x11/x11_backend.c | 150K | X11 backend |
|
|
| src/window.c | 83K | Window management |
|
|
| src/dock.c | 130K | Dock/Clip/Drawers |
|
|
| src/menu.c | 61K | Menu system |
|
|
| src/actions.c | 68K | Window actions |
|
|
| src/defaults.c | 102K | Preferences/config |
|
|
| src/event.c | 61K | Event dispatch |
|
|
| src/moveres.c | 67K | Move/resize |
|
|
| src/wmspec.c | 61K | EWMH compliance |
|
|
| src/main.c | 22K | Entry point |
|
|
| WINGs/WINGs.h | 56K | Toolkit public API |
|
|
| wrlib/wraster.h | 17K | Raster lib public API |
|