diff --git a/docs/book/src/guide/troubleshooting.md b/docs/book/src/guide/troubleshooting.md index bd9e9758e..5cdcd262b 100644 --- a/docs/book/src/guide/troubleshooting.md +++ b/docs/book/src/guide/troubleshooting.md @@ -86,6 +86,29 @@ system then resets the GPU. SolidCraft already builds bodies on the CPU on the A D300/D500/D700 (Mac Pro 2013). On another GPU that does this, start SolidCraft with `SOLIDCRAFT_CPU_TESS=1` set to build bodies on the CPU, and open an issue with the GPU's name. +## The interface looks blurry on Linux with display scaling + +On Linux, SolidCraft runs through XWayland whenever an X display is available, because file +drag and drop from a file manager only works there (niri is the exception and stays on native +Wayland). A compositor that doesn't let X11 apps scale themselves draws an XWayland window at +100 % and stretches it to the monitor's scale, so text and icons look soft. That happens with +fractional scaling (125 %, 140 %), and on GNOME 47 (RHEL and Rocky Linux 10) at any scale, +200 % included. The diagnostics in a bug report show it as about 1 physical pixel per point at +a scale of 200 %. + +Run SolidCraft on native Wayland instead: Preferences › Graphics › **Window system** › +Wayland, which applies at the next start. Versions without that setting (0.21.0 and earlier) +take `SOLIDCRAFT_WAYLAND=1` in the environment: + +``` +SOLIDCRAFT_WAYLAND=1 solidcraft +``` + +On native Wayland, dropping files onto the window doesn't work; use File > Open or pass the file +on the command line. +[Wayland, XWayland and niri](https://github.com/tangency-labs/solidcraft/blob/main/docs/nix.md#wayland-xwayland-and-niri) +has the details. + ## SolidCraft closes right away on Windows A graphics driver can crash the app while it starts, before SolidCraft can show anything (an diff --git a/docs/nix.md b/docs/nix.md index 265db81ac..e9f75855e 100644 --- a/docs/nix.md +++ b/docs/nix.md @@ -100,8 +100,11 @@ This applies to every build, not only the Nix package. Choose it in Preferences › Graphics › **Window system** (Automatic, Wayland or X11; it applies at the next start). The pane says which one is running and, on native Wayland, links to winit's issue about dropping files there. Native Wayland is the better choice with -**fractional scaling** (a monitor at 125 % or 140 %): XWayland windows are drawn at 100 % and -stretched by the compositor, so the interface looks soft and small. +display scaling whenever the compositor doesn't let X11 apps scale themselves: XWayland +windows are then drawn at 100 % and stretched, so the interface looks soft and small. That's +the case with **fractional scaling** (a monitor at 125 % or 140 %), and on GNOME 47 (RHEL and +Rocky Linux 10) at any scale, 200 % included; see +[the troubleshooting page](book/src/guide/troubleshooting.md#the-interface-looks-blurry-on-linux-with-display-scaling). The environment overrides the preference: `SOLIDCRAFT_WAYLAND=1` (always native Wayland) or `SOLIDCRAFT_WAYLAND=0` (XWayland whenever an X display is available).