3D Graphics Recovery¶

To close a terminal-launched session, use the window close button or press Ctrl+C once. Terminal interrupts request normal Qt shutdown, including unsaved changes prompts and analysis/server cleanup. Finish or cancel an open modal editor first, then press Ctrl+C again. Repeated interrupts do not bypass a save prompt. This requires a responsive Qt event loop; it cannot resolve a native driver deadlock.

If the entire application is unresponsive, identify that session's process and terminate only that process as a last resort. Forced termination can lose unsaved work and does not run normal cleanup. On relaunch, check for autosave recovery; recovery is not a substitute for saving. An EGL warning alone does not establish that the application is frozen.

When a Linux graphics driver/EGL/Vulkan mismatch prevents WebGL2 from starting, close Brecon after saving and launch with:

uv run brecon --software-rendering

This requests Chromium's CPU-based ANGLE/SwiftShader driver before Qt initializes, disables GPU compositing, and requests software OpenGL for Qt. Qt can select its platform-specific WebGL driver instead; the tested NVIDIA/Wayland configuration uses Mesa llvmpipe, while offscreen Qt selects the NVIDIA driver with CPU compositing. This is a compatibility mode, not a guarantee that every GPU operation is disabled. No QT_QUICK_BACKEND override is applied because Qt WebEngine's software GL driver is incompatible with that override on some hosts. This mode does not install drivers, alter the operating system, disable Chromium sandboxing, or enable the unsafe-WebGL fallback flag. The view uses only bundled local content. Some EGL/driver warnings may remain even when the viewport renders successfully. CPU rendering can be slower for large models. Qt's --disable-gpu workaround alone is insufficient for this WebGL2 viewport; it may disable the context Three.js needs.

View > 3D Rendering > Software (CPU Compositing) saves this preference for normal future launches; rendering changes require an application restart. A failed viewport also offers Use Software Rendering on Restart, keeping model data and unsaved work intact. Automatic (GPU) restores the normal backend on subsequent starts. The command-line options --graphics=software / --graphics=auto override saved preferences for one launch. Existing unrelated Chromium flags are retained; explicit software mode replaces conflicting graphics-disable/backend flags.

Backend references: Chromium SwiftShader driver documentation and Qt WebEngine hardware acceleration. Terminal warning/output lines are not shell commands; paste only the command above.

Source: GUIDE.md. This manual follows the current repository; the published rc1 wheel has a smaller feature set.