Add a page around HiDPI scaling, with notes about both Wayland+XWayland

src/hidpi-scaling-patches.md

@@ -0,0 +1,139 @@
+### Installing the XOrg XWayland Patch
+
+#### ArchLinux
+
+You can install the
+[xorg-xwayland-hidpi-xprop](https://aur.archlinux.org/packages/xorg-xwayland-hidpi-xprop)
+package from AUR.
+
+#### Other distros
+
+You will need to patch xorg-xwayland yourself, and then compile it. Depending on
+your distro, there might be a package out there so you don't have to recompile,
+but compiling xorg-xwayland is pretty fast. The steps should be as follows:
+
+1. Find out what version of xorg-server you have installed.
+2. If it's 23.1.1 (or similar), [download the patch from
+AUR]([https://aur.archlinux.org/cgit/aur.git/tree/hidpi.patch?h=xorg-xwayland-hidpi-xprop]).
+3. Apply the patch - `patch -Np1 -i hidpi.patch`
+4. Build xorg-xwayland as you normally would.
+
+### Installing the Wlroots Patch
+
+#### ArchLinux
+
+You can install the
+[wlroots-hidpi-xprop-git](https://aur.archlinux.org/packages/wlroots-hidpi-xprop-git)
+package from AUR.
+
+> NOTE: If you wish, you can compile labwc with wlroots as a subproject, with
+> the patch applied. This makes it easier to try the scaling without having to
+> install the `wlroots-hidpi-xprop-git` AUR package globally. See below for
+> details on how to do this.
+
+#### Other distros
+
+You can [compile
+wlroots](https://gitlab.freedesktop.org/wlroots/wlroots#building) as you
+normally would:
+
+1. `git clone https://gitlab.freedesktop.org/wlroots/wlroots.git`
+2. `cd wlroots`
+3. Revert
+[18595000f3a21502fd60bf213122859cc348f9af](https://gitlab.freedesktop.org/wlroots/wlroots/-/commit/18595000f3a21502fd60bf213122859cc348f9af),
+as it can cause issues with certain XWayland apps: `git revert -n
+18595000f3a21502fd60bf213122859cc348f9af`
+4. `meson setup build/`
+5. `ninja -C build/`
+6. To install it globally: `sudo ninja -C build/ install`
+
+#### As a subproject in labwc
+
+A convenient way to test scaling without installing the patched version of
+wlroots globally is to compile labwc with wlroots as a subproject. This does
+require compiling Labwc with an [in-progress Pull
+Request](https://github.com/labwc/labwc/pull/626) which adds support for wlroots
+0.17.
+
+You can compile labwc with wlroots as a subproject as follows:
+
+1. `git clone https://github.com/labwc/labwc --branch=master`
+2. `cd labwc`
+3. Download the `wlroots-0.17` patch, and apply it:
+
+```sh
+wget https://patch-diff.githubusercontent.com/raw/labwc/labwc/pull/626.patch patch -p1 < 626.patch
+```
+
+4. Download the required wlroots patches:
+
+```sh
+mkdir subprojects/packagefiles
+wget https://raw.githubusercontent.com/joshuataylor/wlroots-hidpi-xprop-git/8f14904f40f22b5ad247f022de21875c5a4d1050/0001-xwayland-support-HiDPI-scale.patch -P subprojects/packagefiles
+wget https://raw.githubusercontent.com/joshuataylor/wlroots-hidpi-xprop-git/8f14904f40f22b5ad247f022de21875c5a4d1050/0002-Fix-configure_notify-event.patch -P subprojects/packagefiles
+```
+
+5. If you are using Meson 0.63 or above, you can use the
+[diff_files](https://mesonbuild.com/Wrap-dependency-system-manual.html#diff-files)
+feature to apply this patch for you, and keep the subproject up to date. If you
+are using an older version of Meson, you will have to apply the patch manually,
+and update it when you want to update the subproject.
+
+To find out which version of Meson you are using, run `meson --version`.
+
+Meson 0.63 and above: Add the following to the `subprojects/wrap/wlroots.wrap`
+file, as the last option in `[wrap-git]`:
+
+```sh
+diff_files = 0001-xwayland-support-HiDPI-scale.patch 0002-Fix-configure_notify-event.patch
+```
+
+Meson 0.62 and below, follow the steps until step 6, where you will need to
+apply the patch manually.
+
+6. Delete the current `build` directory, and subprojects/wlroots directory:
+
+```sh
+rm -rf build
+rm -rf subprojects/wlroots
+```
+
+7. Run `meson setup`, forcing the fallback for wlroots:
+
+```sh
+meson setup build --force-fallback-for=wlroots
+```
+
+> If you are using Meson 0.63 or above, you can skip this next step, as the
+> patch will be applied automatically.
+
+7a. If you are on Meson 0.62 and below, you will need to apply the patch
+manually:
+
+```sh
+cd subprojects/wlroots
+patch -p1 < ../packagefiles/0001-xwayland-support-HiDPI-scale.patch
+patch -p1 < ../packagefiles/0002-Fix-configure_notify-event.patch
+```
+
+8. Configure meson with a directory prefix (replacing the below with your own
+directory):
+
+```sh
+meson configure build -Dprefix=/opt/labwc/hidpi
+```
+
+9. Compile:
+
+```sh
+meson compile -C build
+```
+
+10. Install:
+
+```sh
+sudo meson install --skip-subprojects -C ./build
+```
+
+`--skip-subprojects` prevents installing the wlroots headers.
+

src/hidpi-scaling.md

@@ -0,0 +1,254 @@
+# HiDPI Scaling
+
+1. [Introduction](#introduction)
+2. [Scaling](#scaling)
+3. [Wayland Applications](#wayland-applications)
+4. [XWayland Applications](#xwayland-applications)
+5. [Troubleshooting](troubleshooting)
+
+## Introduction
+
+`HiDPI` refers to monitors with high pixels density, such as 4k monitors or
+laptops with a high resolution display. On Apple laptops, they are called
+Retina displays.
+
+`Pixels density` is the number pixels per unit length and is commonly measured
+in Dots Per Inch (DPI).
+
+`Resolution` is the actual pixel size of the monitor, for example 1920x1080.
+
+You can usually tell if you have a HiDPI display by looking at the resolution.
+If it's 1920x1080 or 2560x1440, then you don't have a HiDPI display. If it's
+3840x2160 or 5120x2880, then you have a HiDPI display. You can also have a high
+DPI situation on lower resolutions if the screen is small, e.g. on notebooks,
+tablets or phones.
+
+When running Labwc, if the text is tiny, then you probably have a HiDPI display.
+
+This documentation page guides you through setting up HiDPI scaling in Wayland
+for the Labwc compositor. An intermediate level of understanding of labwc and
+XServer is will be helpful for some of the steps.
+
+A highly recommended resource for further reading is the
+[ArchWiki page about HiDPI].
+
+[ArchWiki page about HiDPI]: https://wiki.archlinux.org/title/HiDPI
+
+## Scaling
+
+Labwc supports scaling, which will make Wayland native apps look fantastic.
+
+Wayland has a [fractional-scale-v1] protocol, which is supported by `wlroots`
+since version `v0.17` and `labwc` has nearly implemented. Be aware though that
+it is still work in progress on XServer and with many applications.
+
+To determine the best scaling setting for your monitor, use [wlr-randr], which
+allows you to see your output, current resolution, scale, refresh rate, etc.
+
+Example output:
+
+```sh
+eDP-1 "XXX XXX (eDP-1)"
+  Physical size: 286x179 mm
+  Enabled: yes
+  Modes:
+    2560x1600 px, 60.000000 Hz (preferred, current)
+  Position: 0,0
+  Transform: normal
+  Scale: 1.000000
+  Adaptive Sync: disabled
+```
+
+The first section of the `wlr-randr` command is the name of the output
+(`eDP-1`), the second section is the name of the monitor. The `Scale` is the
+part to take note of for now, as this is the scale of the output. The modes are
+a list of resolutions that your supports, and the default.
+
+So to start testing the scale with `wlr-randr`, you can run the following
+command, replacing `eDP-1` with the name of your output:
+
+```sh
+wlr-randr --output eDP-1 --scale 1.2
+```
+
+The base scale is 1.0. So 1.2 means 20% larger than the base scale. You might
+need to reopen applications for them to pick up the new scale, as they might
+look blurry until you do.
+
+> Tip: To test GTK3 & GTK4 apps, use the `gtk3-demo` and `gtk4-demo` apps, which
+> allow you to see how GTK apps look at different scales.
+
+The exact scale that works well for you will depend on your monitor, eye sight,
+and personal preference. I (@joshuataylor - the original author of this
+document) found that 1.35 works well on a 32" 4k monitor, whereas on a laptop
+with a 2560x1600 display 1.25 was suitable. Play with the settings until you
+find what works best for you.
+
+Other Operating Systems that support scaling usually start at 150% (1.5), such
+as MacOS for their laptops, and Windows recommends 150% (1.5) for 4k monitors as
+well.
+
+If you have multiple monitors, a great app to manage scale configuration is
+[kanshi], as it also allows you to set the resolution, position, rotation, etc.
+of your monitors. It allows you to also set up profiles, so if you have a
+laptop and an external monitor, you can set up a profile for each. It's also
+handy for a single monitor.
+
+You can create a profile in `~/.config/kanshi/config`, which might look like
+this (replace `DP-1` with the name of your output, etc):
+
+[fractional-scale-v1]: https://wayland.app/protocols/fractional-scale-v1
+[wlr-randr]: https://sr.ht/~emersion/wlr-randr/
+[kanshi]: https://sr.ht/~emersion/kanshi/
+
+```conf
+profile {
+  output DP-1
+  mode 3840x2160@143.9629972Hz
+  position 0,0
+  scale 1.35
+}
+```
+
+To make kanshi settings permanent, add a kanshi entry in
+`~/.config/labwc/autostart`.
+
+If you change the kanshi config file on a runnnig system, you can trigger a
+re-load with `killall -s SIGHUP kanshi`.
+
+## Wayland Applications
+
+Wayland applications are clients which run natively in Wayland, basically not
+through [XWayland].  Most apps now support Wayland, with the main exception
+being Java.
+
+If you use [Jetbrains Products] such as IntelliJ, CLion, PyCharm, Datagrip,
+Rubymine, Goland, Rider, Webstorm or PHPStorm, you're going to have blurry text,
+as XWayland does not yet scale properly.
+
+> Sidenote, work is being done in "Project Wakefield" for native Java on Wayland
+> [0](https://wiki.openjdk.org/display/wakefield/Work+breakdown),
+> [1](https://github.com/openjdk/wakefield/tree/pure_wl_toolkit).
+
+[XWayland]: https://wayland.freedesktop.org/xserver.html
+[Jetbrains Products]: https://www.jetbrains.com
+
+You can see which apps use XWayland by using `xlsclients`, which on ArchLinux
+is part of the [xorg-xlsclients] package; or by simply using alt-tab and
+looking at the first column: `xdg-shell` means wayland native and `xwayland`
+means XWayland.
+
+[xorg-xlsclients]: https://archlinux.org/packages/extra/x86_64/xorg-xlsclients/
+
+You can find more information about Wayland on the [Archwiki page about Wayland]
+and more information about XWayland [on the Archwiki page].
+
+[Archwiki page about Wayland]: https://wiki.archlinux.org/title/wayland
+[on the Archwiki page]: https://wiki.archlinux.org/title/wayland#XWayland
+
+## XWayland Applications
+
+XWayland does not support scaling, and as such, you will have blurry text when
+using XWayland apps.
+
+There is ongoing work in xserver to support HiDPI, see [MR #733]. This has
+ended up being very contentious topic, as there have been multiple Merge
+Requests to add HiDPI support to XWayland, with different approaches.
+
+Until it is merged, you will have to add the patch manually to your XWayland
+installation. If you are using ArchLinux, there are AUR packages which have the
+patch applied.
+
+See [this page](hidpi-scaling-patches.html) instructions on applying XWayland
+related patches.
+
+[MR #733]: https://gitlab.freedesktop.org/xorg/xserver/-/merge_requests/733
+
+### Labwc XWayland Settings
+
+To enable scaling in XWayland applications, you will need to run `xprop` as an
+autostart command in labwc, and set the `GDK_SCALE` environment variable. You
+can also set these properties before running an application during runtime, so
+you don't need to restart labwc. You will need to reopen applications for the
+changes to take effect.
+
+1. In your `~/.config/labwc/autostart` file, add the following line:
+
+```sh
+xprop -root -f _XWAYLAND_GLOBAL_OUTPUT_SCALE 32c -set _XWAYLAND_GLOBAL_OUTPUT_SCALE 2
+```
+
+You can also run this when you are logged in, and it will set the scaling for
+all XWayland apps. You will need to restart the apps for the changes to take
+effect.
+
+2. This step is optional, as it doesn't change non-Wayland GTK apps, but is a
+good idea if you want to scale GTK apps as well.
+
+In your `~/.config/labwc/environment` file, add the following line:
+
+```sh
+GDK_SCALE=2
+```
+
+This will make non-Wayland GTK apps 2x. You can also use `GDK_DPI_SCALE`
+environment variable to scale the font size if needed.
+
+To test scaling with GDK, you can use `gtk3-demo` and `gtk4-demo`, which both
+run on Wayland:
+
+```sh
+GDK_SCALE=2 gtk3-demo
+```
+
+## Troubleshooting
+
+As mentioned initially, this is a work in progress, and you will need to tweak
+your settings until you find a setting you like. Most apps should behave as
+expected, but there are a few issues that you might run into.
+
+### Cursor size is small
+
+Sometimes in XWayland apps, the cursor is half the usual cursor size.
+
+You can try adding the following as a startup script to manage the cursor for
+XWayland apps, replacing the cursor theme name and size as needed:
+
+```sh
+xsetroot -xcf /usr/share/icons/$your_cursor_theme_name/cursors/left_ptr 48
+```
+
+The `-xcf` option tells xsetroot to set the root window's cursor using an X11
+cursor file (XCF) format, and 48 is the size of the cursor in pixels.
+
+Another option is to change your XWayland launch script to add the following:
+
+```sh
+export XCURSOR_SIZE=48 export XCURSOR_THEME=Adwaita
+```
+
+### Font size / DPI issues
+
+#### GTK apps
+
+If you are using GTK apps, you can use the `GDK_SCALE` and `GDK_DPI_SCALE` to
+scale the font. You might also need to run `GDK_DPI_SCALE=0.5` to undo the
+scaling if needed.
+
+#### Jetbrains
+
+If you have installed Jetbrains applications via the Jetbrains Toolbox, the
+.desktop files are located in `~/.local/share/applications` and these can be
+modfied to set environment variables in the `Exec=` line, see the
+[Modify environment variables](https://wiki.archlinux.org/title/Desktop_entries#Modify_environment_variables)
+archwiki page for instructions.
+
+> These will be updated every time the product updates.. So you'll need to keep
+> adding them here, which is a pain. You could have another desktop entry, which
+> sets then launches this one, but then you'll have two entries in your
+> launcher.
+
+Using the Jetbrains Toolbox App you can also create launch scripts, which will
+be named `idea.sh`, `clion.sh`, etc. You can edit these to add the
+application-specific environment variables.
+