diff --git a/README.md b/README.md index bf8e84c..783dda7 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,7 @@ To **run** haul: | ---------------------- | ------------------------------------------------------- | | The system `ssh` client | Saved-host connections call `ssh -G ` to resolve the effective config, so ssh_config semantics are never re-implemented | | A graphical desktop | haul is a GUI application; it needs a display server | +| **OpenGL 2.1 or newer** | Fyne renders through OpenGL. Remote Desktop sessions, VMs without 3D acceleration, and machines running Microsoft Basic Display Adapter don't provide it — see [Remote Desktop and VMs](#running-over-remote-desktop-or-in-a-vm) | | An SFTP-capable server | Transfers use the SFTP subsystem — see [Scope](#scope) | ## Building @@ -200,8 +201,61 @@ If you would rather use the Makefile, install `make` inside the MSYS2 shell `-H=windowsgui` yourself, for example `make build LDFLAGS="-s -w -H=windowsgui"`. -Unlike Linux, Windows needs no graphics development packages: OpenGL is part of -the operating system. +Unlike Linux, Windows needs no graphics development *packages* to build: OpenGL +ships with the operating system. Getting a usable OpenGL at **run** time is a +separate matter — see below. + +### Running over Remote Desktop (or in a VM) + +A build that compiles perfectly will still fail to start in an RDP session with: + +``` +Fyne error: window creation error +Cause: APIUnavailable: WGL: The driver does not appear to support OpenGL +``` + +This is not a haul fault — any OpenGL application fails the same way. Fyne needs +OpenGL 2.1+, and Remote Desktop's display driver doesn't provide it. The same +applies to Hyper-V and to VMs without 3D acceleration, and to any machine using +Microsoft Basic Display Adapter. + +The fix is Mesa's software OpenGL renderer (llvmpipe), deployed just for haul: + +1. Download a `mesa3d--release-msvc.7z` from + [mesa-dist-win releases](https://github.com/pal1000/mesa-dist-win/releases). + It's a `.7z`, so you'll need 7-Zip (`winget install 7zip.7zip`) to extract it. +2. Open the extracted **`x64`** folder (not `x86`). +3. Copy **every DLL in it** — around 19 files — into the same folder as + `haul.exe`. + +``` +bin\ + haul.exe + opengl32.dll + libgallium_wgl.dll + ...and the rest of x64\ +``` + +Verified working in an RDP session on 2026-07-30. + +Three things worth knowing: + +- **Copy all of the DLLs, not just `opengl32.dll`.** In current Mesa builds that + file is a thin front-end that loads `libgallium_wgl.dll` and others alongside + it. Taking it on its own produces a DLL that can't load its dependencies, and + haul fails exactly as if you'd done nothing. +- **A local `opengl32.dll` always wins over the system one**, because Windows + searches the executable's own directory first. So these DLLs force software + rendering *unconditionally* — including on a machine with a perfectly good GPU. + If you use haul both locally and over RDP, keep two copies: one folder with the + Mesa DLLs, one without. +- **Don't run `systemwidedeploy.cmd`** if you see it in the archive. That + installs Mesa for every OpenGL application on the machine; copying files beside + `haul.exe` keeps the change contained to haul. + +Software rendering is slower than a GPU, but haul draws two tables and some text +— it's entirely adequate. The headless Linux target does the same thing via +`LIBGL_ALWAYS_SOFTWARE=1` in `make run-xvfb`. ### Make targets