Add SteamOS GPU fixes and launch script
Introduces SteamOS/Steam Deck detection and GPU configuration in gpu-config.js, adds a dedicated start-steamos.sh launch script, and updates package.json with new scripts for SteamOS and Linux GPU-safe launches. Also adds a comprehensive GPU troubleshooting guide in GPU-FIX-README.md to address rendering issues on various platforms.
This commit is contained in:
@@ -0,0 +1,101 @@
|
||||
# GPU Fix Guide for Nebula Browser
|
||||
|
||||
## Common GPU Issues
|
||||
|
||||
Nebula Browser is an Electron-based application that uses Chromium's rendering engine. Some systems may experience GPU-related issues such as:
|
||||
- Black/blank screens
|
||||
- Webviews not loading content
|
||||
- Flickering or visual artifacts
|
||||
- Application crashes
|
||||
|
||||
## SteamOS / Steam Deck
|
||||
|
||||
### Symptoms
|
||||
On SteamOS (Steam Deck), you may see:
|
||||
- Browser chrome loads (tab bar, URL bar visible)
|
||||
- Web page content area is completely black/empty
|
||||
- No error messages visible
|
||||
|
||||
### Cause
|
||||
This is caused by GPU compositing conflicts between Electron's Chromium renderer and Gamescope (Steam Deck's compositor). The AMD GPU in Steam Deck handles nested compositor contexts differently.
|
||||
|
||||
### Solution
|
||||
|
||||
**Option 1: Automatic Detection (Recommended)**
|
||||
The latest version of Nebula automatically detects SteamOS/Gamescope and applies the necessary fixes. Simply update to the latest version.
|
||||
|
||||
**Option 2: Manual Launch Script**
|
||||
Use the provided `start-steamos.sh` script:
|
||||
```bash
|
||||
chmod +x start-steamos.sh
|
||||
./start-steamos.sh
|
||||
```
|
||||
|
||||
**Option 3: Command-line Flags**
|
||||
If running manually, add these flags:
|
||||
```bash
|
||||
electron . --ozone-platform=x11 --disable-gpu-compositing --disable-gpu-vsync --no-sandbox --disable-dev-shm-usage
|
||||
```
|
||||
|
||||
**Option 4: Environment Variable**
|
||||
Set the `ELECTRON_OZONE_PLATFORM_HINT` environment variable:
|
||||
```bash
|
||||
export ELECTRON_OZONE_PLATFORM_HINT=x11
|
||||
npm start
|
||||
```
|
||||
|
||||
## Linux (General)
|
||||
|
||||
### Wayland
|
||||
If running on a Wayland compositor (GNOME Wayland, KDE Wayland, Sway, etc.):
|
||||
```bash
|
||||
electron . --ozone-platform=wayland --enable-features=UseOzonePlatform,WaylandWindowDecorations
|
||||
```
|
||||
|
||||
### X11
|
||||
For X11 sessions:
|
||||
```bash
|
||||
electron . --ozone-platform=x11
|
||||
```
|
||||
|
||||
### NVIDIA GPUs
|
||||
If using NVIDIA proprietary drivers:
|
||||
```bash
|
||||
electron . --disable-gpu-sandbox --no-sandbox
|
||||
```
|
||||
|
||||
## Windows
|
||||
|
||||
### Intel/AMD Integrated Graphics Issues
|
||||
If experiencing blank screens on Windows with integrated graphics:
|
||||
1. Try running with `start-gpu-safe.bat`
|
||||
2. Update your graphics drivers
|
||||
3. Disable hardware acceleration in settings (if available)
|
||||
|
||||
### Multiple GPU Systems
|
||||
On laptops with both integrated and discrete GPUs:
|
||||
- Right-click the Nebula shortcut
|
||||
- Select "Run with graphics processor"
|
||||
- Choose your dedicated GPU
|
||||
|
||||
## macOS
|
||||
|
||||
macOS typically has fewer GPU issues, but if problems occur:
|
||||
```bash
|
||||
electron . --disable-gpu
|
||||
```
|
||||
|
||||
## Diagnostic Information
|
||||
|
||||
To see GPU information and diagnostics:
|
||||
1. Open Nebula Browser
|
||||
2. Navigate to `nebula://gpu` or `chrome://gpu`
|
||||
3. Check the "Graphics Feature Status" section
|
||||
|
||||
## Reporting Issues
|
||||
|
||||
If none of the above solutions work, please report the issue with:
|
||||
1. Operating system and version
|
||||
2. GPU model and driver version
|
||||
3. Contents of `chrome://gpu` page
|
||||
4. Any error messages from terminal/console
|
||||
|
||||
Reference in New Issue
Block a user