{"id":17206839,"url":"https://github.com/galister/wlx-overlay-s","last_synced_at":"2025-04-13T22:12:11.318Z","repository":{"id":206418372,"uuid":"716598943","full_name":"galister/wlx-overlay-s","owner":"galister","description":"Access your Wayland/X11 desktop from Monado/WiVRn/SteamVR. Now with Vulkan!","archived":false,"fork":false,"pushed_at":"2025-04-09T20:11:45.000Z","size":8336,"stargazers_count":322,"open_issues_count":34,"forks_count":40,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-09T21:23:54.931Z","etag":null,"topics":["linux","openvr","openvr-overlay","openxr","openxr-overlay","steamvr","steamvr-overlay","vr-overlay","wayland","x11"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/galister.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-11-09T13:28:33.000Z","updated_at":"2025-04-09T21:10:40.000Z","dependencies_parsed_at":"2024-02-17T02:29:48.547Z","dependency_job_id":"3d8386f5-5cd0-45c5-b089-95a6be2de20a","html_url":"https://github.com/galister/wlx-overlay-s","commit_stats":null,"previous_names":["galister/wlx-overlay-s"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/galister%2Fwlx-overlay-s","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/galister%2Fwlx-overlay-s/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/galister%2Fwlx-overlay-s/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/galister%2Fwlx-overlay-s/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/galister","download_url":"https://codeload.github.com/galister/wlx-overlay-s/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248788916,"owners_count":21161728,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["linux","openvr","openvr-overlay","openxr","openxr-overlay","steamvr","steamvr-overlay","vr-overlay","wayland","x11"],"created_at":"2024-10-15T02:44:08.507Z","updated_at":"2025-04-13T22:12:11.294Z","avatar_url":"https://github.com/galister.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WlxOverlay-S\n\nA lightweight OpenXR/OpenVR overlay for Wayland and X11 desktops, inspired by XSOverlay.\n\nWlxOverlay-S lets you to access your desktop screens while in VR.\n\nIn comparison to similar overlays, WlxOverlay-S aims to run alongside VR games and experiences while having as little performance impact as possible. The UI appearance and rendering techniques are kept as simple and efficient as possible, while still allowing a high degree of customizability.\n\n![Screenshot of WlxOverlay-S being used as an OpenXR home environment](https://github.com/galister/wlx-overlay-s/blob/guide/wlx-s.png?raw=true)\n\n## Join the Linux VR Community\n\nWe are available on either:\n\n- Discord: \u003chttps://discord.gg/gHwJ2vwSWV\u003e\n- Matrix Space: `#linux-vr-adventures:matrix.org`\n\nQuestions/issues specific to WlxOverlay-S will be handled in the `wlxoverlay` chat room.\n\n## Setup\n\n### General Setup\n\n1. Grab the latest AppImage from [Releases](https://github.com/galister/wlx-overlay-s/releases).\n1. `chmod +x WlxOverlay-S-*.AppImage`\n1. Start Monado, WiVRn or SteamVR.\n1. Run the overlay\n\n**Note:** If you are using Monado or WiVRn, no additional setup steps are required for Flatpak Steam compatibility—most people use WlxOverlay-S seamlessly with Monado/WiVRn.\n\n### SteamVR via Steam Flatpak\n\nFor users specifically running **SteamVR via Steam Flatpak**, follow these steps:\n\n1. Grab the latest AppImage from [Releases](https://github.com/galister/wlx-overlay-s/releases).\n1. `WlxOverlay-S-*.AppImage --appimage-extract`\n1. `chmod +x squashfs-root/AppRun`\n1. Move the newly created `squashfs-root` folder to a location accessible by the Steam Flatpak.\n1. `flatpak override com.valvesoftware.Steam --user --filesystem=xdg-run/pipewire-0/:rw`\n1. Restart Steam.\n1. Start SteamVR.\n1. `flatpak run --command='/path/to/squashfs-root/AppRun' com.valvesoftware.Steam`\n\nAUR package is [wlx-overlay-s-git](https://aur.archlinux.org/packages/wlx-overlay-s-git).\n\nYou may also want to [build from source](https://github.com/galister/wlx-overlay-s/wiki/Building-from-Source).\n\n## First Start\n\n**When the screen share pop-up appears, check the terminal and select the screens in the order it requests.**\n\nIn case screens were selected in the wrong order:\n\n- `rm ~/.config/wlxoverlay/conf.d/pw_tokens.yaml` then restart\n\n**SteamVR users**: WlxOverlay-S will register itself for auto-start, so there is no need to start it every time.\n\n**Envision users**: Set `wlx-overlay-s --openxr --show` as the _Autostart Command_ on your Envision profile! This will show a home environment with headset passthrough by default or a [customizable background](https://github.com/galister/wlx-overlay-s/wiki/OpenXR-Skybox)! If you are using the appimage instead, set the _Autostart Command_ to the location of tha appimage binary, e.g `/full/path/to/wlx-overlay-s.appimage --openxr --show`.\n\n**Please continue reading the guide below.**\n\n## Getting Started\n\n### Working Set\n\nThe working set consists of all currently selected overlays; screens, mirrors, keyboard, etc.\n\nThe working set appears in front of the headset when shown, and can be re-centered by hiding and showing again.\n\nShow and hide the working set using:\n\n- Non-vive controller: double-tap B or Y on the left controller.\n- Vive controller: double-tap the menu button on the left controller (for SteamVR, the `showhide` binding must be bound)\n\n### Pointer Modes AKA Laser Colors\n\nMuch of the functionality in WlxOverlay-S depends on what color of laser is used to interact with a UI element. \\\nUsing the default settings, there are 3 modes:\n\n- Regular Mode: Blue laser\n- Right-click Mode: Orange laser\n- Middle-click Mode: Purple laser\n\nPlease see the bindings section below on how to activate these modes.\n\nThe guide here uses the colors for ease of getting started.\n\n### The Watch\n\nCheck your left wrist for the watch. The watch is the primary tool for controlling the app.\n\n![Watch usage guide](https://github.com/galister/wlx-overlay-s/blob/guide/wlx-watch.png)\n\n### The Screens\n\nHovering a pointer over a screen will move the mouse. If there are more than one pointers hovering a screen, the pointer that was last used to click will take precedence.\n\nThe click depends on the laser color:\n\n- Blue laser: Left click\n- Orange laser: Right click\n- Purple laser: Middle click\n- Stick up/down: Scroll wheel\n\nTo **curve a screen**, grab it with one hand. Then, using the other hand, hover the laser over the screen and use the scroll action.\n\nSee the [bindings](#default-bindings) section on how to grab, move and resize screens.\n\n### The keyboard\n\nThe keyboard is fully customizable via the [keyboard.yaml](https://raw.githubusercontent.com/galister/wlx-overlay-s/main/src/res/keyboard.yaml) file. \\\nDownload it into the `~/.config/wlxoverlay/` folder and edit it to your liking.\n\nTyping\n\n- Use the BLUE laser when typing regularly.\n- While using ORANGE laser, all keystrokes will have SHIFT applied.\n- Purple laser has no effect as of now.\n\n**Modifier Keys** are sticky. They will remain pressed until a non-modifier key is pressed, the modifier gets toggled off, or the keyboard gets hidden.\n\n### Default Bindings\n\n![Index Controller Bindings](https://github.com/galister/wlx-overlay-s/blob/guide/wlx-index.png)\n\n![Touch Controller Bindings](https://github.com/galister/wlx-overlay-s/blob/guide/wlx-oculus.png)\n\nTo customize bindings on OpenXR, refer to the [OpenXR Bindings wiki page](https://github.com/galister/wlx-overlay-s/wiki/OpenXR-Bindings).\n\nIf your bindings are not supported, please reach out. \\\nWe would like to work with you and include additional bindings.\n\n## Troubleshooting\n\nWhen an error is detected, we often print tips for fixing into the log file.\n\nLogs will be at `/tmp/wlx.log` for most distros.\n\nCheck [here](https://github.com/galister/wlx-overlay-s/wiki/Troubleshooting) for tips.\n\n## Known Issues\n\n### Mouse is not where it should be\n\nHyprland users: Hyprland v0.41.0 changed their absolute input implementation to one that does not respect existing absolute input standards. Make your voice heard: [Hyprland#6023](https://github.com/hyprwm/Hyprland/issues/6023)・[Hyprland#6889](https://github.com/hyprwm/Hyprland/issues/6889)\n\nNiri users: use on Niri 0.1.7 or later.\n\nX11 users might be dealing with a [Phantom Monitor](https://wiki.archlinux.org/title/Xrandr#Disabling_phantom_monitor).\n\nOther desktops: The screens may have been selected in the wrong order, see [First Start](#first-start).\n\n### Crashes, blank screens\n\nThere are some driver-desktop combinations that don't play nice with DMA-buf capture. \n\nDisabling DMA-buf capture is a good first step to try when encountering an app crash or gpu driver reset.\n\n```bash\necho 'capture_method: pw_fallback' \u003e ~/.config/wlxoverlay/conf.d/pw_fallback.yaml\n```\n\nWithout DMA-buf capture, capturing screens takes CPU power, so let's try and not show too many screens at the same time.\n\n### Space-drag crashes SteamVR\n\nThis has been idenfitied as an issue with SteamVR versions 2.5.5 and above (latest tested 2.7.2). One way to avoid the crash is by switching to the `temp-v1.27.5` branch of SteamVR (via beta selection) and selecting [Steam-Play-None](https://github.com/Scrumplex/Steam-Play-None) under the compatibility tab.\n\n### Modifiers get stuck in weird ways\n\nThis is a rare issue that can make KDE Plasma not react to click or keys due to what seems to be a race condition with modifiers. Restarting the overlay fixes this.\n\n### X11 limitations\n\n- X11 capture can generally seem slow. This is because zero-copy GPU capture is not supported on the general X11 desktop. Consider trying Wayland or Picom.\n- DPI scaling is not supported and may cause the mouse to not follow the laser properly.\n- Upright screens are not supported and can cause the mouse to act weirdly.\n- Screen changes (connecting / disconnecting a display, resolution changes, etc) are not handled at runtime. Restart the overlay for these to take effect.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgalister%2Fwlx-overlay-s","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgalister%2Fwlx-overlay-s","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgalister%2Fwlx-overlay-s/lists"}