Skip to content

fix(terminal): skip WebGL renderer on software-only GPU#3362

Merged
gregpriday merged 3 commits intodevelopfrom
feature/issue-3280-webgl-terminal-renderer
Mar 16, 2026
Merged

fix(terminal): skip WebGL renderer on software-only GPU#3362
gregpriday merged 3 commits intodevelopfrom
feature/issue-3280-webgl-terminal-renderer

Conversation

@gregpriday
Copy link
Collaborator

Summary

  • Adds a GPU detection check before attaching @xterm/addon-webgl to terminals. When Chromium reports WebGL as software_only (CPU-emulated via llvmpipe or ANGLE fallback), WebGL attachment is skipped entirely and terminals fall back to the DOM renderer automatically.
  • Exposes GPU WebGL status from the main process via a new IPC handler (app/state) so the renderer can read it at startup through stateHydration.
  • Extracts GPU detection logic into electron/utils/gpuDetection.ts to keep the IPC handler thin and the helper independently testable.

Resolves #3280

Changes

  • electron/utils/gpuDetection.ts — new helper that reads app.getGPUFeatureStatus().webgl2 and returns whether hardware WebGL is available
  • electron/ipc/handlers/app/state.ts — surfaces gpuWebGLAvailable flag in the app state IPC response
  • shared/types/ipc/app.ts — adds gpuWebGLAvailable: boolean to the AppState type
  • src/utils/stateHydration.ts — hydrates the GPU flag into a module-level export consumed by TerminalWebGLManager
  • src/services/terminal/TerminalWebGLManager.ts — guards ensureContext() with the hydrated GPU flag; logs a clear message when WebGL is skipped
  • src/services/terminal/TerminalInstanceService.ts — calls hydrateGpuState() at startup before any terminal is created
  • Tests covering GPU detection, state hydration, and the WebGL skip path

Testing

  • Unit tests pass for all new and modified files (TerminalWebGLManager.test.ts, stateHydration.test.ts, app.gpuDetection.test.ts)
  • npm run check passes cleanly (typecheck, lint, format)
  • The existing CANOPY_DISABLE_WEBGL=1 env override continues to work alongside the new runtime check

- Add isWebGLHardwareAccelerated helper to detect software GPU via app.getGPUFeatureStatus().webgl2
- Include gpuWebGLHardware boolean in APP_HYDRATE IPC payload
- Add hardwareAvailable instance field and setter on TerminalWebGLManager
- Thread GPU status from stateHydration through TerminalInstanceService to WebGL manager
- Add comprehensive tests for GPU detection, WebGL skip behavior, and hydration propagation
…tests

- Move isWebGLHardwareAccelerated to electron/utils/gpuDetection.ts
- Use gpuStatus.webgl2 directly instead of unsafe Record cast
- Fix test import to avoid pulling in Electron app module chain
- Add toHaveBeenCalledTimes(1) to all three GPU propagation tests
- Ensures setGPUHardwareAvailable is called exactly once per hydration
@gregpriday
Copy link
Collaborator Author

Review status: Ready

@gregpriday gregpriday merged commit 8535a0e into develop Mar 16, 2026
4 checks passed
@gregpriday gregpriday deleted the feature/issue-3280-webgl-terminal-renderer branch March 16, 2026 06:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

WebGL terminal renderer attaches without checking for CPU-emulated GPU

1 participant