Docs: blurry interface on Linux with display scaling, and how to fix it (#5979) (#6195)

SolidCraft runs through XWayland whenever an X display is available. A
compositor that doesn't let X11 apps scale themselves draws the window at
100 % and stretches it. docs/nix.md said so only for fractional scaling,
but GNOME 47 (RHEL and Rocky Linux 10) does it at any scale: the report
shows 1.05 physical pixels per point at 200 %.

The troubleshooting page gets a section with the cause, the Window system
preference, SOLIDCRAFT_WAYLAND=1 for 0.21.0 and earlier, and the file drop
trade-off; docs/nix.md links to it.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Thosch
2026-10-26 10:24:30 +00:00
committed by GitHub
parent 4d61100534
commit 102314dbb2
2 changed files with 28 additions and 2 deletions
+23
View File
@@ -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
+5 -2
View File
@@ -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).