diff --git a/src/hidpi-scaling-patches.md b/src/hidpi-scaling-patches.md new file mode 100644 index 0000000..8a3ad4a --- /dev/null +++ b/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. + diff --git a/src/hidpi-scaling.md b/src/hidpi-scaling.md new file mode 100644 index 0000000..ec63319 --- /dev/null +++ b/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. + diff --git a/src/template_pre.html b/src/template_pre.html index 94883aa..b3acf87 100644 --- a/src/template_pre.html +++ b/src/template_pre.html @@ -147,6 +147,7 @@ [manual] [troubleshooting] [tips & tricks] +[faq] [faq]