From 27cb97ac00d94e0b93094930b07ec7bd0e2c73d1 Mon Sep 17 00:00:00 2001 From: Andrew Zambazos Date: Sun, 28 Dec 2025 11:37:25 +1300 Subject: [PATCH] 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. --- GPU-FIX-README.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++ gpu-config.js | 93 ++++++++++++++++++++++++++++++++++++++++-- package.json | 2 + start-steamos.sh | 31 ++++++++++++++ 4 files changed, 224 insertions(+), 3 deletions(-) create mode 100644 start-steamos.sh diff --git a/GPU-FIX-README.md b/GPU-FIX-README.md index e69de29..223f878 100644 --- a/GPU-FIX-README.md +++ b/GPU-FIX-README.md @@ -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 diff --git a/gpu-config.js b/gpu-config.js index 2aa7f65..12960a4 100644 --- a/gpu-config.js +++ b/gpu-config.js @@ -5,6 +5,36 @@ class GPUConfig { constructor() { this.isGPUSupported = false; this.fallbackApplied = false; + this.isSteamOS = false; + this.isLinux = process.platform === 'linux'; + } + + // Detect if running on SteamOS/Steam Deck + detectSteamOS() { + if (!this.isLinux) return false; + + try { + const fs = require('fs'); + // Check for SteamOS identifiers + if (fs.existsSync('/etc/steamos-release')) return true; + if (fs.existsSync('/usr/share/steamos/steamos.conf')) return true; + + // Check os-release for SteamOS + if (fs.existsSync('/etc/os-release')) { + const osRelease = fs.readFileSync('/etc/os-release', 'utf8'); + if (osRelease.includes('SteamOS') || osRelease.includes('steamos')) return true; + } + + // Check if running under Gamescope (Steam Deck's compositor) + if (process.env.GAMESCOPE_WAYLAND_DISPLAY || process.env.SteamDeck) return true; + + // Check for Steam runtime environment + if (process.env.STEAM_RUNTIME || process.env.SteamAppId) return true; + } catch (err) { + console.log('SteamOS detection error:', err.message); + } + + return false; } // Apply GPU configuration based on system capabilities @@ -15,7 +45,14 @@ class GPUConfig { const platform = process.platform; const arch = process.arch; - console.log(`Platform: ${platform}, Architecture: ${arch}`); + this.isSteamOS = this.detectSteamOS(); + + console.log(`Platform: ${platform}, Architecture: ${arch}, SteamOS: ${this.isSteamOS}`); + + // Apply Linux/SteamOS specific configuration FIRST (before app ready) + if (this.isLinux) { + this.applyLinuxSettings(); + } // Start with conservative settings that usually work this.applyConservativeSettings(); @@ -24,6 +61,48 @@ class GPUConfig { this.tryEnableGPU(); } + // Linux-specific settings for proper rendering + applyLinuxSettings() { + console.log('Applying Linux-specific GPU settings...'); + + // Ozone platform selection - critical for rendering on Linux + // Check for Wayland vs X11 environment + const waylandDisplay = process.env.WAYLAND_DISPLAY; + const gamescope = process.env.GAMESCOPE_WAYLAND_DISPLAY; + const x11Display = process.env.DISPLAY; + + if (this.isSteamOS || gamescope) { + // SteamOS/Gamescope: Force X11 backend for better compatibility + // Gamescope provides X11 compatibility layer that works better with Electron + console.log('SteamOS/Gamescope detected - using X11 Ozone backend'); + app.commandLine.appendSwitch('ozone-platform', 'x11'); + + // Disable GPU compositing issues on Steam Deck AMD GPU + app.commandLine.appendSwitch('disable-gpu-compositing'); + app.commandLine.appendSwitch('disable-gpu-vsync'); + + // Use software rendering for webviews if needed + app.commandLine.appendSwitch('disable-accelerated-2d-canvas'); + + // Fix for AMD GPU rendering issues + app.commandLine.appendSwitch('use-gl', 'desktop'); + app.commandLine.appendSwitch('enable-features', 'UseOzonePlatform'); + } else if (waylandDisplay && !x11Display) { + // Pure Wayland environment + console.log('Wayland detected - using Wayland Ozone backend'); + app.commandLine.appendSwitch('ozone-platform', 'wayland'); + app.commandLine.appendSwitch('enable-features', 'UseOzonePlatform,WaylandWindowDecorations'); + } else if (x11Display) { + // X11 environment + console.log('X11 detected - using X11 Ozone backend'); + app.commandLine.appendSwitch('ozone-platform', 'x11'); + } + + // Common Linux fixes + app.commandLine.appendSwitch('disable-features', 'VizDisplayCompositor'); + app.commandLine.appendSwitch('enable-unsafe-swiftshader'); + } + applyConservativeSettings() { // Essential switches that usually don't cause issues app.commandLine.appendSwitch('no-sandbox'); @@ -40,6 +119,12 @@ class GPUConfig { tryEnableGPU() { try { + // Skip aggressive GPU features on SteamOS - they conflict with Gamescope + if (this.isSteamOS) { + console.log('SteamOS detected - skipping aggressive GPU acceleration'); + return; + } + // GPU acceleration switches app.commandLine.appendSwitch('ignore-gpu-blacklist'); app.commandLine.appendSwitch('ignore-gpu-blocklist'); @@ -50,8 +135,10 @@ class GPUConfig { app.commandLine.appendSwitch('enable-accelerated-video-decode'); app.commandLine.appendSwitch('enable-accelerated-mjpeg-decode'); - // Conservative feature enabling - app.commandLine.appendSwitch('enable-features', 'VaapiVideoDecoder'); + // Conservative feature enabling - skip on Linux to avoid conflicts + if (!this.isLinux) { + app.commandLine.appendSwitch('enable-features', 'VaapiVideoDecoder'); + } console.log('GPU acceleration switches applied'); } catch (err) { diff --git a/package.json b/package.json index 8c121f0..40f2eea 100644 --- a/package.json +++ b/package.json @@ -5,6 +5,8 @@ "main": "main.js", "scripts": { "start": "electron .", + "start:steamos": "electron . --ozone-platform=x11 --disable-gpu-compositing --disable-gpu-vsync --no-sandbox --disable-dev-shm-usage --disable-features=VizDisplayCompositor", + "start:linux-safe": "electron . --disable-gpu --disable-gpu-compositing --no-sandbox", "dist": "electron-builder", "run": "electron ." }, diff --git a/start-steamos.sh b/start-steamos.sh new file mode 100644 index 0000000..b7dd9e9 --- /dev/null +++ b/start-steamos.sh @@ -0,0 +1,31 @@ +#!/bin/bash +# SteamOS/Steam Deck launch script for Nebula Browser +# This script applies necessary flags for proper rendering on SteamOS/Gamescope + +# Detect if running on SteamOS +if [ -f /etc/steamos-release ] || [ -f /usr/share/steamos/steamos.conf ]; then + echo "SteamOS detected" +fi + +# Detect if running under Gamescope (Steam Deck's compositor) +if [ -n "$GAMESCOPE_WAYLAND_DISPLAY" ] || [ -n "$SteamDeck" ]; then + echo "Gamescope/Steam Deck environment detected" +fi + +# Get the directory where this script is located +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +# Launch Nebula with SteamOS-compatible flags +# These flags help with webview rendering issues on AMD GPUs under Gamescope +exec electron "$SCRIPT_DIR" \ + --ozone-platform=x11 \ + --disable-gpu-compositing \ + --disable-gpu-vsync \ + --disable-accelerated-2d-canvas \ + --use-gl=desktop \ + --no-sandbox \ + --disable-dev-shm-usage \ + --disable-gpu-sandbox \ + --disable-features=VizDisplayCompositor \ + --enable-unsafe-swiftshader \ + "$@"