This repo will eventually contain a collection of tools to enable virtual desktop environments for gaming and productivity on Linux using supported XR glasses. This currently includes XREAL Air 1, 2, 2 Pro and VITURE One models.
As of now, only a Vulkan implementation is available, primarily for gaming but could theoretically be used for anything that uses Vulkan rendering.
For Steam Deck users, the driver is now available via the Decky plugin loader. Just search "xreal" in the Decky store to install and use without leaving Gaming Mode. You can now enable or disable the driver and manage other driver settings via the Decky sidebar menu.
You may still opt to do a manual installation using the instructions below if you enter Desktop Mode.
- Download the setup script and set the execute flag (e.g. from the terminal:
chmod +x ~/Downloads/breezy_vulkan_setup) - Run the setup script as root (e.g.
sudo ~/Downloads/breezy_vulkan_setup) - If you're not on Steam Deck, you'll need to set the
ENABLE_VKBASALTenvironment variable to1. You'll either need to set this globally to enable it for all games, or set it as a launch option for individual games (e.g. in Steam's Launch Options fieldENABLE_VKBASALT=1 %command%).
Once installed, you'll want to make sure you've enabled the driver (~/bin/xreal_driver_config -e) and then you can go into whichever output mode you'd like using (~/bin/xreal_driver_config -m) where -m is for mouse mode, -j for joystick, -vd for virtual display, and -sv for sideview; note that these two commands can't be combined, they have to be done separately. From there, you should be able to launch any Vulkan game, plug in your glasses (at any point, not just after launching), and see a floating virtual display or a sideview screen (depending on which mode you've chosen).
There's a wait period of 15 seconds after plugging in XREAL glasses where the screen will stay static to allow for the glasses to calibrate. Once ready, the screen will anchor to the space where you are looking.
To see all the configuration options available to you, type ~/bin/xreal_driver_config with no parameters to get the usage statement. There are some things you can't trigger from the script, like re-centering the virtual display or entering SBS mode; you can achieve these things through multi-tap or through the physical buttons on the glasses, respectively.
I've implemented an experimental multi-tap detection feature for screen re-centering (2 taps) and re-calibrating the device (3 taps). To perform a multi-tap, you'll want to give decent taps on the top of the glasses. I tend to do this on the corner, right on top of the hinge. It should be a firm, sharp tap, and wait just a split second to do the second tap, as it needs to detect a slight pause in between (but it also shouldn't take more than a half a second between taps so don't wait too long).
Framerate is really important here, because individual frames are static, so moving your head quickly may produce a noticeable flicker as it moves the screen. Higher framerates will produce an overall better experience (less flicker and smoother follow), but lower framerates should still be totally usable.
It's important that your glasses are either on your head or sitting on a flat surface when they're first plugged in and calibrated. If you notice that your screen is constantly drifting in one direction or continues to move for several seconds after a head movement, almost as if the screen has some momentum that takes time to slow down, then you'll want to re-calibrate them. To do this, do a triple-tap as described in the Multi-tap section above.
If the screen appears very small in your view, you may be playing at the Deck screen's native resolution, and not at the glasses' native resolution. To fix this:
- Go to the game details in Steam, hit the Settings/cog icon, and open
Properties, then forGame ResolutionchooseNative. - After launching the game, if it's still small, go into the game options, and in the graphics or video settings, change the resolution (the glasses run at 1920x1080).
If you WANT to keep a low resolution, then you can just use the Zoom setting to make the screen appear larger. For now this is done through the config script: ~/bin/xreal_driver_config -z 1.0. Larger numbers zoom in (e.g. 2.0 doubles the screen size) and smaller numbers zoom out (e.g. 0.5 is half the screen size).
Supporter Tier features are enhancments to core functionality, offered as a way to reward those who have supported the project. Core features -- like Virtual Display mode, VR-Lite mouse/joystick modes, and Follow mode's display positioning/resizing settings -- will always remain available to everyone regardless of supporter status. Donating $10 gets you a year, and $25 gets you lifetime of Supporter Tier access. If you have enough funds, your access will renew automatically within 7 days of expiration so you never experience an unexpected outage. Your device is never required to be online to continue using Supporter Tier features when enabled, but if your access expires while offline (even if you have enough funds), the features will be disabled until the next time your device goes online and the license can be refreshed. Be sure to check for expiration warnings prior to travel.
Features currently offered:
- Smooth Follow (in Follow mode)
- Automatic Recentering (in Virtual Display mode)
- Side-by-side support (in Virtual Display mode)
If you donate at least $10, you should immediately receive an email (to your Ko-fi email address) with a verification token. If you don't, request it using the config script:
~/bin/xreal_driver_config --request-token [emailAddress]Once you have a token, verify it using:
~/bin/xreal_driver_config --verify-token [token]
~/bin/xreal_driver_config --refresh-licenseTo disable the floating screen effect, either disable the driver (~/bin/xreal_driver_config -d), unplug the glasses, or hit the Home key (you'll need to bind this to your controller, if on Steam Deck).
Rerun the breezy_vulkan_setup script. No need to re-download this script, as it will automatically download the latest installation binary for you.
If you wish to completely remove the installation, run the following: sudo ~/bin/breezy_vulkan_uninstall. This won't uninstall the base driver package, follow the instructions at the end of the uninstallation to do this manually.
Your right to privacy and the protection of your personal data are baked into every decision around how your personal data is collected, handled and stored. Your personal data will never be shared, sold, or distributed in any form.
In order to provide you with Supporter Tier features, this application and its backend services have to collect the following pieces of personal information:
- Your email address is sent to this application's backend server from either the payment vendor (Ko-fi) or from your device (at your request). Your email address may be used immediately upon receipt in its unaltered form to send you a transactional email, but it is then hashed prior to storage. The unaltered form of your email address is never stored and can no longer be referenced. The hashed value is stored for later reference.
- Other personal data may be sent from the payment vendor, but is never utilized nor stored.
- Your device's MAC address is hashed on your device. It never leaves your device in its original, unaltered form. The hashed value is sent to this application's backend server and stored for later reference, and -- up to version 0.8.7 -- to Google Analytics.
Hashing functions are a one-way process that serve to anonymize your personal data by irreversibly changing them. Once hashed, they can never be unhashed or traced back to their original values.
For inquires about data privacy or any related concerns, please contact:
Wayne Heaney - [email protected]
