|
| 1 | +# HiDPI Scaling |
| 2 | + |
| 3 | +1. [Introduction](#introduction) |
| 4 | +2. [Scaling](#scaling) |
| 5 | +3. [Wayland Applications](#wayland-applications) |
| 6 | +4. [XWayland Applications](#xwayland-applications) |
| 7 | +5. [Troubleshooting](troubleshooting) |
| 8 | + |
| 9 | +## Introduction |
| 10 | + |
| 11 | +`HiDPI` refers to monitors with high pixels density, such as 4k monitors or |
| 12 | +laptops with a high resolution display. On Apple laptops, they are called |
| 13 | +Retina displays. |
| 14 | + |
| 15 | +`Pixels density` is the number pixels per unit length and is commonly measured |
| 16 | +in Dots Per Inch (DPI). |
| 17 | + |
| 18 | +`Resolution` is the actual pixel size of the monitor, for example 1920x1080. |
| 19 | + |
| 20 | +You can usually tell if you have a HiDPI display by looking at the resolution. |
| 21 | +If it's 1920x1080 or 2560x1440, then you don't have a HiDPI display. If it's |
| 22 | +3840x2160 or 5120x2880, then you have a HiDPI display. You can also have a high |
| 23 | +DPI situation on lower resolutions if the screen is small, e.g. on notebooks, |
| 24 | +tablets or phones. |
| 25 | + |
| 26 | +When running Labwc, if the text is tiny, then you probably have a HiDPI display. |
| 27 | + |
| 28 | +This documentation page guides you through setting up HiDPI scaling in Wayland |
| 29 | +for the Labwc compositor. An intermediate level of understanding of labwc and |
| 30 | +XServer is will be helpful for some of the steps. |
| 31 | + |
| 32 | +A highly recommended resource for further reading is the |
| 33 | +[ArchWiki page about HiDPI]. |
| 34 | + |
| 35 | +[ArchWiki page about HiDPI]: https://wiki.archlinux.org/title/HiDPI |
| 36 | + |
| 37 | +## Scaling |
| 38 | + |
| 39 | +Labwc supports scaling, which will make Wayland native apps look fantastic. |
| 40 | + |
| 41 | +Wayland has a [fractional-scale-v1] protocol, which is supported by `wlroots` |
| 42 | +since version `v0.17` and `labwc` has nearly implemented. Be aware though that |
| 43 | +it is still work in progress on XServer and with many applications. |
| 44 | + |
| 45 | +To determine the best scaling setting for your monitor, use [wlr-randr], which |
| 46 | +allows you to see your output, current resolution, scale, refresh rate, etc. |
| 47 | + |
| 48 | +Example output: |
| 49 | + |
| 50 | +```sh |
| 51 | +eDP-1 "XXX XXX (eDP-1)" |
| 52 | + Physical size: 286x179 mm |
| 53 | + Enabled: yes |
| 54 | + Modes: |
| 55 | + 2560x1600 px, 60.000000 Hz (preferred, current) |
| 56 | + Position: 0,0 |
| 57 | + Transform: normal |
| 58 | + Scale: 1.000000 |
| 59 | + Adaptive Sync: disabled |
| 60 | +``` |
| 61 | + |
| 62 | +The first section of the `wlr-randr` command is the name of the output |
| 63 | +(`eDP-1`), the second section is the name of the monitor. The `Scale` is the |
| 64 | +part to take note of for now, as this is the scale of the output. The modes are |
| 65 | +a list of resolutions that your supports, and the default. |
| 66 | + |
| 67 | +So to start testing the scale with `wlr-randr`, you can run the following |
| 68 | +command, replacing `eDP-1` with the name of your output: |
| 69 | + |
| 70 | +```sh |
| 71 | +wlr-randr --output eDP-1 --scale 1.2 |
| 72 | +``` |
| 73 | + |
| 74 | +The base scale is 1.0. So 1.2 means 20% larger than the base scale. You might |
| 75 | +need to reopen applications for them to pick up the new scale, as they might |
| 76 | +look blurry until you do. |
| 77 | + |
| 78 | +> Tip: To test GTK3 & GTK4 apps, use the `gtk3-demo` and `gtk4-demo` apps, which |
| 79 | +> allow you to see how GTK apps look at different scales. |
| 80 | +
|
| 81 | +The exact scale that works well for you will depend on your monitor, eye sight, |
| 82 | +and personal preference. I (@joshuataylor - the original author of this |
| 83 | +document) found that 1.35 works well on a 32" 4k monitor, whereas on a laptop |
| 84 | +with a 2560x1600 display 1.25 was suitable. Play with the settings until you |
| 85 | +find what works best for you. |
| 86 | + |
| 87 | +Other Operating Systems that support scaling usually start at 150% (1.5), such |
| 88 | +as MacOS for their laptops, and Windows recommends 150% (1.5) for 4k monitors as |
| 89 | +well. |
| 90 | + |
| 91 | +If you have multiple monitors, a great app to manage scale configuration is |
| 92 | +[kanshi], as it also allows you to set the resolution, position, rotation, etc. |
| 93 | +of your monitors. It allows you to also set up profiles, so if you have a |
| 94 | +laptop and an external monitor, you can set up a profile for each. It's also |
| 95 | +handy for a single monitor. |
| 96 | + |
| 97 | +You can create a profile in `~/.config/kanshi/config`, which might look like |
| 98 | +this (replace `DP-1` with the name of your output, etc): |
| 99 | + |
| 100 | +[fractional-scale-v1]: https://wayland.app/protocols/fractional-scale-v1 |
| 101 | +[wlr-randr]: https://sr.ht/~emersion/wlr-randr/ |
| 102 | +[kanshi]: https://sr.ht/~emersion/kanshi/ |
| 103 | + |
| 104 | +```conf |
| 105 | +profile { |
| 106 | + output DP-1 |
| 107 | + mode 3840x2160@143.9629972Hz |
| 108 | + position 0,0 |
| 109 | + scale 1.35 |
| 110 | +} |
| 111 | +``` |
| 112 | + |
| 113 | +To make kanshi settings permanent, add a kanshi entry in |
| 114 | +`~/.config/labwc/autostart`. |
| 115 | + |
| 116 | +If you change the kanshi config file on a runnnig system, you can trigger a |
| 117 | +re-load with `killall -s SIGHUP kanshi`. |
| 118 | + |
| 119 | +## Wayland Applications |
| 120 | + |
| 121 | +Wayland applications are clients which run natively in Wayland, basically not |
| 122 | +through [XWayland]. Most apps now support Wayland, with the main exception |
| 123 | +being Java. |
| 124 | + |
| 125 | +If you use [Jetbrains Products] such as IntelliJ, CLion, PyCharm, Datagrip, |
| 126 | +Rubymine, Goland, Rider, Webstorm or PHPStorm, you're going to have blurry text, |
| 127 | +as XWayland does not yet scale properly. |
| 128 | + |
| 129 | +> Sidenote, work is being done in "Project Wakefield" for native Java on Wayland |
| 130 | +> [0](https://wiki.openjdk.org/display/wakefield/Work+breakdown), |
| 131 | +> [1](https://github.com/openjdk/wakefield/tree/pure_wl_toolkit). |
| 132 | +
|
| 133 | +[XWayland]: https://wayland.freedesktop.org/xserver.html |
| 134 | +[Jetbrains Products]: https://www.jetbrains.com |
| 135 | + |
| 136 | +You can see which apps use XWayland by using `xlsclients`, which on ArchLinux |
| 137 | +is part of the [xorg-xlsclients] package; or by simply using alt-tab and |
| 138 | +looking at the first column: `xdg-shell` means wayland native and `xwayland` |
| 139 | +means XWayland. |
| 140 | + |
| 141 | +[xorg-xlsclients]: https://archlinux.org/packages/extra/x86_64/xorg-xlsclients/ |
| 142 | + |
| 143 | +You can find more information about Wayland on the [Archwiki page about Wayland] |
| 144 | +and more information about XWayland [on the Archwiki page]. |
| 145 | + |
| 146 | +[Archwiki page about Wayland]: https://wiki.archlinux.org/title/wayland |
| 147 | +[on the Archwiki page]: https://wiki.archlinux.org/title/wayland#XWayland |
| 148 | + |
| 149 | +## XWayland Applications |
| 150 | + |
| 151 | +XWayland does not support scaling, and as such, you will have blurry text when |
| 152 | +using XWayland apps. |
| 153 | + |
| 154 | +There is ongoing work in xserver to support HiDPI, see [MR #733]. This has |
| 155 | +ended up being very contentious topic, as there have been multiple Merge |
| 156 | +Requests to add HiDPI support to XWayland, with different approaches. |
| 157 | + |
| 158 | +Until it is merged, you will have to add the patch manually to your XWayland |
| 159 | +installation. If you are using ArchLinux, there are AUR packages which have the |
| 160 | +patch applied. |
| 161 | + |
| 162 | +See [this page](hidpi-scaling-patches.html) instructions on applying XWayland |
| 163 | +related patches. |
| 164 | + |
| 165 | +[MR #733]: https://gitlab.freedesktop.org/xorg/xserver/-/merge_requests/733 |
| 166 | + |
| 167 | +### Labwc XWayland Settings |
| 168 | + |
| 169 | +To enable scaling in XWayland applications, you will need to run `xprop` as an |
| 170 | +autostart command in labwc, and set the `GDK_SCALE` environment variable. You |
| 171 | +can also set these properties before running an application during runtime, so |
| 172 | +you don't need to restart labwc. You will need to reopen applications for the |
| 173 | +changes to take effect. |
| 174 | + |
| 175 | +1. In your `~/.config/labwc/autostart` file, add the following line: |
| 176 | + |
| 177 | +```sh |
| 178 | +xprop -root -f _XWAYLAND_GLOBAL_OUTPUT_SCALE 32c -set _XWAYLAND_GLOBAL_OUTPUT_SCALE 2 |
| 179 | +``` |
| 180 | + |
| 181 | +You can also run this when you are logged in, and it will set the scaling for |
| 182 | +all XWayland apps. You will need to restart the apps for the changes to take |
| 183 | +effect. |
| 184 | + |
| 185 | +2. This step is optional, as it doesn't change non-Wayland GTK apps, but is a |
| 186 | +good idea if you want to scale GTK apps as well. |
| 187 | + |
| 188 | +In your `~/.config/labwc/environment` file, add the following line: |
| 189 | + |
| 190 | +```sh |
| 191 | +GDK_SCALE=2 |
| 192 | +``` |
| 193 | + |
| 194 | +This will make non-Wayland GTK apps 2x. You can also use `GDK_DPI_SCALE` |
| 195 | +environment variable to scale the font size if needed. |
| 196 | + |
| 197 | +To test scaling with GDK, you can use `gtk3-demo` and `gtk4-demo`, which both |
| 198 | +run on Wayland: |
| 199 | + |
| 200 | +```sh |
| 201 | +GDK_SCALE=2 gtk3-demo |
| 202 | +``` |
| 203 | + |
| 204 | +## Troubleshooting |
| 205 | + |
| 206 | +As mentioned initially, this is a work in progress, and you will need to tweak |
| 207 | +your settings until you find a setting you like. Most apps should behave as |
| 208 | +expected, but there are a few issues that you might run into. |
| 209 | + |
| 210 | +### Cursor size is small |
| 211 | + |
| 212 | +Sometimes in XWayland apps, the cursor is half the usual cursor size. |
| 213 | + |
| 214 | +You can try adding the following as a startup script to manage the cursor for |
| 215 | +XWayland apps, replacing the cursor theme name and size as needed: |
| 216 | + |
| 217 | +```sh |
| 218 | +xsetroot -xcf /usr/share/icons/$your_cursor_theme_name/cursors/left_ptr 48 |
| 219 | +``` |
| 220 | + |
| 221 | +The `-xcf` option tells xsetroot to set the root window's cursor using an X11 |
| 222 | +cursor file (XCF) format, and 48 is the size of the cursor in pixels. |
| 223 | + |
| 224 | +Another option is to change your XWayland launch script to add the following: |
| 225 | + |
| 226 | +```sh |
| 227 | +export XCURSOR_SIZE=48 export XCURSOR_THEME=Adwaita |
| 228 | +``` |
| 229 | + |
| 230 | +### Font size / DPI issues |
| 231 | + |
| 232 | +#### GTK apps |
| 233 | + |
| 234 | +If you are using GTK apps, you can use the `GDK_SCALE` and `GDK_DPI_SCALE` to |
| 235 | +scale the font. You might also need to run `GDK_DPI_SCALE=0.5` to undo the |
| 236 | +scaling if needed. |
| 237 | + |
| 238 | +#### Jetbrains |
| 239 | + |
| 240 | +If you have installed Jetbrains applications via the Jetbrains Toolbox, the |
| 241 | +.desktop files are located in `~/.local/share/applications` and these can be |
| 242 | +modfied to set environment variables in the `Exec=` line, see the |
| 243 | +[Modify environment variables](https://wiki.archlinux.org/title/Desktop_entries#Modify_environment_variables) |
| 244 | +archwiki page for instructions. |
| 245 | + |
| 246 | +> These will be updated every time the product updates.. So you'll need to keep |
| 247 | +> adding them here, which is a pain. You could have another desktop entry, which |
| 248 | +> sets then launches this one, but then you'll have two entries in your |
| 249 | +> launcher. |
| 250 | +
|
| 251 | +Using the Jetbrains Toolbox App you can also create launch scripts, which will |
| 252 | +be named `idea.sh`, `clion.sh`, etc. You can edit these to add the |
| 253 | +application-specific environment variables. |
| 254 | + |
0 commit comments