BlinkGTK GPU Modes

BlinkGTK runs in one of three GPU modes, selected with the BLINKGTK_GPU_MODE environment variable.

About this page (updated 2026-08-16)
Parts of chapter 6 (troubleshooting) record symptoms observed on earlier
releases; some are resolved in the current release. Chapter 5 (switching)
is up to date. For the authoritative list of environment variables, see the
environment variables reference.

1. The three modes

On-screen rendering

In the current release (BlinkGTK 1.2.3 / Chromium 154), the software and EGL modes
display Blink's rendering output in the GTK window. Up to 1.2.3-build1 the
swiftshader mode showed nothing on screen (issue #151; the capture API also failed
because no frame arrived). This is fixed as of 1.2.3-build2: pages appear as in software
and EGL, and WebGL output is visible too. On 1.2.3-build1 and earlier, use software or EGL.

On machines without a usable GPU, asking for EGL falls back to software
automatically (since v1.2.1-build2). It switches when no frame arrives within
five seconds and writes the reason to standard error; it does not switch where
the GPU path works. Set BLINKGTK_EGL_AUTO_FALLBACK=0 to disable it (the screen
may then stay white).

Resolved so far (history)

2. Mode details

2.1 Software (software)

Behavior:

• Blink produces pixels on the CPU
• viz::SoftwareOutputDevice writes the bitmap into the framebuffer
• BlinkGTK retrieves it via CopyFromSurface and displays it through GtkPicture / GtkGLArea
• --disable-gpu-compositing is added internally

Strengths:

• The most stable mode; does not depend on GPU drivers
• Verified on Weston headless, virtual machines, and CI
• Easy to debug (the rendering path is simple)

Weaknesses:

• Slower than the other modes
• WebGL and WebGPU do not work in this mode. Pages with 3D content will log console errors such as
  THREE.WebGLRenderer: Error creating WebGL context or
  Failed to create WebGPU Context Provider. If your JavaScript depends on GPU acceleration, choose
  swiftshader or egl.

Recommended for:

• E-book readers (reading UIs are mostly static content)
• Kiosk terminals
• Server-side PDF generation
• Automated CI tests

2.2 SwiftShader (swiftshader)

Behavior:

• ANGLE translates GL commands into Vulkan
• SwiftShader emulates Vulkan on the CPU
• GL is emulated in software, but from Blink's point of view a GPU is present
• --use-gl=angle --use-angle=swiftshader is set

Strengths:

• WebGL and fast canvas rendering without a GPU driver
• Can be 2–3× faster than software mode
• Reproducible behavior because it does not depend on hardware

Weaknesses:

• Slightly longer startup than software mode
• Requires the SwiftShader ICD (vk_swiftshader_icd.json), libvk_swiftshader.so, and the Vulkan
  loader (libvulkan.so.1). Official tarballs and RPMs from v1.0.10 iter7 onward bundle these under
  lib/chromium/ (packaging fixed in
  Issue #56)
• ANGLE's Vulkan backend may fail to initialize on Intel Mesa and similar stacks; v1.0.10 iter7 added a
  mitigation equivalent to --disable-vulkan
  (Issue #53)

Recommended for:

• Automated tests on VMs, containers, and cloud hosts
• Running WebGL where no GPU driver is available
• As a desktop fallback when GPU drivers are unstable

2.3 Native EGL (egl)

Behavior:

• Uses Wayland EGL directly
• Uses the native GPU through the Ozone/Wayland platform
• --use-gl=angle --use-angle=gl --ignore-gpu-blocklist is set
• --headless is not added (fixed in Issue #47)

On v1.2.0-build2 and earlier this shows a white screen.

The setup this path needs (GTK4 integration, manual viewport, device scale,
and the receiving widget) was left to the application, so nothing appeared
unless you knew to configure it. From the next release the engine does
this, so BLINKGTK_GPU_MODE=egl alone is enough. On earlier versions,
please use software.

Falls back automatically on machines without a usable GPU:

You may select egl on a machine where the GPU path does not work (no driver,
no GPU visible inside a virtual machine, and so on). Previously the window
stayed blank with nothing to explain why.

Now, if no frame reaches the EGL path within five seconds, BlinkGTK switches to
the software path so drawing continues, and writes the reason to standard error.
The fallback does not trigger where the GPU path works. Disable it with
BLINKGTK_EGL_AUTO_FALLBACK=0 (the window then stays blank). See
Environment variables for details.

What it aims to provide:

• GPU acceleration for WebGL, WebGPU, and canvas
• High frame rates at 4K / HiDPI

Current limitations:

• Does not render on some machines (see above)
• May briefly turn white during a resize
• Requires a real GPU and a Wayland-EGL-capable driver
• Some functionality is limited under Weston headless
• Exposed to driver-specific bugs

Current status:

• Works with BLINKGTK_GPU_MODE=egl alone (from the next release)
• Requires a real GPU and a Wayland-EGL-capable driver

3. Choosing a mode

What is the application's runtime environment?
├─ GPU + desktop + Wayland         -> egl
├─ No GPU, need WebGL              -> swiftshader
├─ No GPU, no WebGL                -> software (default)
└─ Headless / CI                   -> software or swiftshader

4. Launch examples

# Software mode (default)
./myapp --no-sandbox --no-zygote

# SwiftShader mode
BLINKGTK_GPU_MODE=swiftshader ./myapp --no-sandbox --no-zygote

# Native EGL mode
BLINKGTK_GPU_MODE=egl ./myapp --no-sandbox --no-zygote

Selecting the path from code (v1.2.2-build5 and later):

blink_gtk_set_gpu_mode(BLINK_GPU_MODE_EGL);   /* before blink_gtk_init */
blink_gtk_init(&argc, &argv);

Note: blink_web_view_new_with_gpu_mode() cannot select the path. The
rendering path is fixed at blink_gtk_init(), and so are the launch flags handed
to the GPU process. By the time a WebView is created it can no longer change, so
passing a mode there has no effect — it only emits a warning. (Found on
2026-09-14 from an external report; until then it was possible to measure the
software path while believing EGL was in use.)

There is one path per process. It cannot differ between WebViews in the same
process.

Confirm what took effect with blink_web_view_get_gpu_mode(); the startup log
also prints the path. Setting BLINKGTK_GPU_MODE before launch still works.

5. Switching modes and paths — what can change at runtime

There are two different axes, with different capabilities.

5.1 Switching the GPU mode (restart required)

If your application offers a UI (for example a menu item) that lets the user
pick a GPU mode, changing the mode requires restarting the process.

// When the user selects a different mode
g_setenv("BLINKGTK_GPU_MODE", "egl", TRUE);
execv(argv[0], argv);  // restart the process

To carry state (URL, scroll position, display scale) across the restart, use
the handoff meta API (blink_web_view_export_handoff_meta() /
import_handoff_meta()). It carries the display scale in canonical units, so
the restarted view does not come back undersized.

5.2 Live delivery-path switching

There is more than one delivery path (P1 = direct, P2 = mojo shared memory,
P3 = EGL dmabuf), and these can be switched without a restart:

• P1 ↔︎ P2 (inside software mode) — since v1.2.0-build9
• Round trips involving P3 (EGL) — since v1.2.1-build3, but only when the
  process started with BLINKGTK_GPU_MODE=egl. A process started under
  software rendering cannot move to EGL: upstream treats the compositing mode
  as one-way for the whole process, and under a software start no GPU-side
  frames are produced at all

int seq = blink_web_view_switch_render_path(view, "P2");
/* Completion arrives on the "render-path-changed" signal. If the new path
 * fails its render check, the previous path is restored automatically
 * (result="rollback" — the screen is never broken). */

A switch takes a few hundred milliseconds in our test environment. See the
render-path-changed section of the
Signals API reference for details
(sequence numbers, result values).

Scope: this API switches software-side delivery paths ("P1" / "P2") only.
It does not switch the GPU mode itself (software ↔︎ egl) — use the restart
procedure in 5.1 for that.

5.3 Stopping presentation instead (presentation policy)

If what you actually want is "this view need not be presented right now"
(an audio-only mode, for example) rather than a different path, the proper
tool is the presentation policy:
blink_web_view_set_presentation_policy(). It skips only the cost of
presenting frames; layout and rasterization (read-ahead) continue.
While presentation is stopped, a screenshot request (blink_web_view_capture_screenshot_async()
and similar) still gets exactly one frame, after which presentation stays stopped (1.2.3-build2 and later).

6. Troubleshooting

6.1 FATAL: gl_factory_ozone NOTREACHED in EGL mode

Cause: the Wayland EGL driver is not found, or the process is falling back to an X11 display.
Fix: use v1.0.10 iter7 or later (fixed for v1.0.1 in
Issue #47, hardened further for v1.0.10 iter7 in
Issue #53).

6.2 VK_ERROR_INITIALIZATION_FAILED in SwiftShader mode

Cause: ANGLE's Vulkan backend fails to initialize against the environment's Vulkan driver
configuration.
Fix: use v1.0.10 iter7 or later. In iter7 the SwiftShader path was changed to explicitly avoid
ANGLE Vulkan (Issue #53). Upgrade if you are on
iter6 or earlier.

6.3 SwiftShader renders, but pixels never reach GTK

This is resolved as of 1.2.3-build2 (first fixed on 2026-04-19 under Issue #54;
it came back in later versions, issue #151).

• Symptom: BLINK_LOAD_FINISHED is reached and FPS is around 60, yet the
  GTK window stays black or shows only the background colour, and the capture
  API times out
• What caused it: the CopyFromSurface guard was applied to SwiftShader too.
  The guard avoids real-GPU readback (Issue #54) and is only needed for EGL.
  SwiftShader has no direct-to-screen path like EGL, so CopyFromSurface is the
  only way its pages reach the screen
• Versions where the regression was observed: 1.2.2-build6 and 1.2.3-build1 (when
  it first came back was not measured)
• If you still see it: use 1.2.3-build2 or later; if it persists there, tell us

6.4 EGL rendering is clipped to the top-left corner (HiDPI)

This is resolved (Issue #58, 2026-04-20).

• Symptom: with gtk_scale=2, the parent widget is 1536×785 logical px but
  web content appears only in a small area at the top left
• What caused it: the Chromium view was updated correctly through
  size_allocate, but the wl_subsurface / wp_viewport destination size did
  not follow. Implementing the size_allocate vfunc fixed it
• If you still see it on the current release, report it with the window size
  and gtk_scale. We check for these two symptoms automatically on every update

6.5 White screen in every mode

This can still occur under some conditions even on v1.0.10 iter7 and later. Check the following:

• BlinkGTK version: pkg-config --modversion blinkgtk-0.1 reports 1.0.10 or later
• Parent widget hierarchy:
  • Using blink_web_view_new() directly (recommended): any GtkContainer works as the parent
    (gtk_window_set_child(window, view) is the simplest)
  • Using blink_web_view_new_container(): a GtkOverlay + GtkPicture is built internally.
    Deprecated (Issue #90): on Chromium 148+ the internal software bridge does not render, so migrate
    to blink_web_view_new() with your own GtkOverlay
• Loaded HTML: try data:text/html,<body style='background:red'>TEST</body> as a test page
• Logs: check that DidFinishNavigation() and BLINK_LOAD_FINISHED appear

See Troubleshooting for details.

7. Benchmarking

The triple_gpu_compare sample (examples/triple_gpu_compare.c) compares all three modes side by side
within a single application.

Running from a Chromium build tree:

cd $CHROMIUM_SRC/out/Release_Component
LD_LIBRARY_PATH=$PWD ./triple_gpu_compare

When installed from a tarball or RPM:

# The executable lives in $prefix/bin; runtime .so files in $prefix/lib/chromium
cd /usr/local/lib/chromium   # or adjust to your prefix
/usr/local/bin/triple_gpu_compare

Three WebViews are displayed side by side so you can compare FPS and rendering quality.

8. Related documents

• Settings API reference — choosing the mode at creation (new_with_gpu_mode)
• Signals API reference — completion signal for live path switching
• [Issue #47: EGL mode fix]