Wayland compositor (wlroots)
git clone https://git.lucas.co/cce-compositor.git
scenefx/README.md (4.4K)
1 # scenefx
2
3 wlroots is the de-facto library for building wayland compositors, and its scene api is a great stride in simplifying wayland compositor development. The problem with the scene api (for compositors looking for eye candy), however, is that it forces you to use the wlr renderer, which is powerful yet simple. SceneFX is a project that takes the scene api and replaces the wlr renderer with our own fx renderer, capable of rendering surfaces with eye-candy effects including blur, shadows, and rounded corners, while maintaining the benefits of simplicity gained from using the scene api.
4
5 **Please note: while SceneFX is in use by SwayFX version 0.4, it is not yet ready for usage by other compositors. Please refer to the [1.0 milestone](https://github.com/wlrfx/scenefx/milestone/2) to track the remaining tasks for our stable 1.0 release**
6
7 ## Compositors Using SceneFX
8 Plenty of popular wayland compositors are using SceneFX to render eyecandy, including:
9 - [SwayFX](https://github.com/WillPower3309/swayfx)
10 - [MangoWC](https://github.com/DreamMaoMao/mangowc)
11 - [mwc](https://github.com/nikoloc/mwc)
12 - dwl [with a patch](https://codeberg.org/dwl/dwl-patches/src/branch/main/stale-patches/scenefx)
13
14 ## Installation
15 <a href="https://repology.org/project/scenefx/versions"><img src="https://repology.org/badge/vertical-allrepos/scenefx.svg"/></a>
16
17
18 ## Compiling From Source
19 Install dependencies:
20 * meson \*
21 * wlroots
22 * wayland
23 * wayland-protocols \*
24 * EGL and GLESv2
25 * libdrm
26 * pixman
27
28 _\* Compile-time dep_
29
30 Run these commands:
31 ```sh
32 meson setup build/
33 ninja -C build/
34 ```
35
36 Install like so:
37 ```sh
38 sudo ninja -C build/ install
39 ```
40
41 ## Troubleshooting
42
43 ### Using scenefx features breaks the compositor
44
45 This issue might be caused by compiling scenefx and wlroots with
46 Clang compiler and thin LTO(`-flto=thin`) option enabled. Try to
47 compile the libraries without LTO optimizations or with GCC compiler instead.
48
49 ## Debugging
50
51 SceneFX includes the same debugging tools and environment variables as upstream wlroots does, but with some extra goodies.
52
53 ### Environment variables:
54
55 - `WLR_RENDERER_ALLOW_SOFTWARE=1`: Use software rendering
56 - `WLR_SCENE_DEBUG_DAMAGE=rerender`: Re-render the whole display on each commit (don't use damage)
57 - `WLR_SCENE_DEBUG_DAMAGE=highlight`: Highlights where damage has occurred (where SwayFX get's re-rendered)
58 - `WLR_SCENE_DISABLE_DIRECT_SCANOUT=1`: Disable direct scanout (always composites, even fullscreen windows)
59 - `WLR_SCENE_DISABLE_VISIBILITY=1`: Disables culling of non-visible regions of a window/buffer (an example would be a small window fully covered by an opaque window)
60 - `WLR_SCENE_HIGHLIGHT_TRANSPARENT_REGION=1`: Highlights the transparent areas of a window/buffer
61 - `WLR_EGL_NO_MODIFIERS=1`: Disables modifiers for EGL
62
63 ### Tracy profiling
64
65 Optional [Tracy](https://github.com/wolfpld/tracy) profiling can be enabled for an extra good view of when and what is happening.
66
67 #### Enabling:
68
69 Note: These instructions will enable basic profiling
70
71 1. Add SceneFX as a subproject to your compositor
72 2. Import it as a subproject dependency
73 3. Run `meson subprojects download` to download the tracy project into the subproject directory
74 4. Compile SceneFX with `-Dtracy_enable=true` (and `--buildtype=debugoptimized` if using meson).
75 5. Start your compositor
76 6. Start the `tracy-profiler` and connect to the running compositor (The version of the profiler should not matter, but if any issues are encountered, try using a version that matches the subproject).
77
78 To enable more advanced profiling, the compositor in question needs to be run by the root user which comes with its own drawbacks, like DBus not working out of the box. A recommended way of doing this is by running your compositor with the `-E` sudo flag, such as `sudo -E sway`.
79
80 To enable DBus, you need to give the root user access to the DBus session bus by adding the following lines to the `/etc/dbus-1/session-local.conf` file (you might have to create said file), and reboot your system.
81
82 ```xml
83 <!-- /etc/dbus-1/session-local.conf -->
84 <!-- Allow root to access session bus -->
85 <busconfig>
86 <policy context="mandatory">
87 <allow user="root"/>
88 </policy>
89 </busconfig>
90 ```
91
92 #### Additional tracy documentation
93
94 The links below are helpful when learning how to use tracy:
95
96 - https://github.com/wolfpld/tracy/releases/latest/download/tracy.pdf
97 - https://www.youtube.com/watch?v=ghXk3Bk5F2U
98
99 ---
100 [Join our Discord](https://discord.gg/qsSx397rkh)