andrew
27cb97ac00
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.
102 lines
2.7 KiB
Markdown
102 lines
2.7 KiB
Markdown
# 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
|