Documentation · BlinkGTK

BlinkGTK GPU モード解説

BlinkGTK は 3 つの GPU モードで動作します。環境変数 BLINKGTK_GPU_MODE で選択します。

記述時点について（2026-08-16 更新）
第 6 章 (トラブルシューティング) の一部は過去の版で観測した症状の記録で、
現行の版では解消済みのものを含みます。切り替えの仕組み (第 5 章) は
現行の版に合わせて更新済みです。環境変数の正リストは
環境変数リファレンス を
ご確認ください。

1. 3 つのモード

モード BLINKGTK_GPU_MODE レンダリング コンポジション 用途

|

ソフトウェア | software（既定） | CPU | ソフトウェアコンポジタ | ヘッドレス・CI・サーバ・低スペック |
|

SwiftShader | swiftshader | ソフトウェア GL（ANGLE→Vulkan→SwiftShader） | ソフトウェアコンポジタ | 仮想マシン・安定優先 |
|

EGL ネイティブ | egl | ハードウェア GPU（Wayland EGL） | GPU コンポジタ | デスクトップ・本番 |

画面描画について

v1.0.10 iter7 以降、3 モードすべてで GTK ウィンドウに Blink の
レンダリング結果が基本的に表示されます。

ただし、以下の既知事項は iter9 時点で追跡中です:

2. モード別詳細

2.1 ソフトウェア (software)

挙動:

長所:

短所:

推奨用途:

2.2 SwiftShader (swiftshader)

挙動:

長所:

短所:

推奨用途:

2.3 EGL ネイティブ (egl)

挙動:

v1.2.0-build2 以前では白画面になります。

動作に必要な設定 (GTK4 統合・手動 viewport・device scale・受け手ウィジェット)
が利用者側に委ねられており、指定しないと表示されませんでした。
次の版からはエンジンが行うので、BLINKGTK_GPU_MODE=egl だけで動きます。
それ以前の版では software をお使いください。

目指しているもの:

現状の制約:

現在の位置付け:

3. モード選択フロー

アプリの実行環境は？
├─ GPU あり・デスクトップ・Wayland → egl
├─ GPU なし・WebGL 必要           → swiftshader
├─ GPU なし・WebGL 不要           → software（既定）
└─ ヘッドレス・CI                  → software または swiftshader

4. 起動例

# ソフトウェアモード（既定）
./myapp --no-sandbox --no-zygote

# SwiftShader モード
BLINKGTK_GPU_MODE=swiftshader ./myapp --no-sandbox --no-zygote

# EGL ネイティブモード
BLINKGTK_GPU_MODE=egl ./myapp --no-sandbox --no-zygote

コード内から指定する場合（v1.0.2 以降）:

GtkWidget* view = blink_web_view_new_with_gpu_mode(BLINK_GPU_MODE_EGL);

注意: この関数は BLINKGTK_GPU_MODE をプロセス全体に対して設定します。
同一プロセス内で複数の WebView を異なるモードで作っても、最初に作られた
WebView のモードが全体に適用されます。WebView 単位の分離は将来の課題です
(公開ヘッダ blink_web_view_new_with_gpu_mode の注記どおり)。

確実に意図したモードで動かすには、blink_gtk_init(&argc, &argv) を呼ぶ前に
環境変数を設定してください。

5. モードと経路の切り替え — 何が実行中に変えられるか

切り替えには二つの軸があり、できることが違います。

軸 例 実行中の切替
GPU モード (本ページの software / swiftshader / egl) software → egl 不可 — プロセス再起動が必要
配送経路 (software モード内部の画面転送経路) P1 (直接) ↔︎ P2 (mojo 共有メモリ) 可 (v1.2.0-build9 以降) — blink_web_view_switch_render_path()

5.1 GPU モードの切替 (再起動が必要)

ユーザーが GPU モードを選択できる UI（メニュー項目など）を提供する場合、
モード切替にはプロセス再起動が必要です。

// ユーザーが別モードを選んだら
g_setenv("BLINKGTK_GPU_MODE", "egl", TRUE);
execv(argv[0], argv);  // プロセス再起動

再起動をまたぐ状態（URL・スクロール位置・表示スケール）の引き継ぎには
handoff meta API（blink_web_view_export_handoff_meta() /
import_handoff_meta()）が使えます。表示スケールを含めて正準単位で
引き継ぐため、再起動後に「描画が小さい」が起きません。

5.2 配送経路のライブ切替 (v1.2.0-build9 以降)

software モードの内部には画面転送の経路が複数あり
（P1 = 直接配送 / P2 = mojo 共有メモリ配送）、これは再起動なしに
切り替えられます。

int seq = blink_web_view_switch_render_path(view, "P2");
/* 完了は "render-path-changed" シグナル。切替後の描画が確認できなければ
 * 自動で元の経路に戻ります (result="rollback"、画面は壊れません) */

切替はテスト環境の実測で数百ミリ秒です。詳細（seq による前後対応付け・
result の意味）は シグナル API リファレンス
の render-path-changed の節を参照してください。

適用範囲に注意: この API が切り替えるのは software 系の配送経路
（"P1" / "P2"）だけです。GPU モードそのもの（software ↔︎ egl）の実行時切替は
できません（5.1 の再起動手順を使ってください）。

5.3 画面転送を止めたい場合 (提示ポリシー)

「経路を変える」のではなく「今は画面に出す必要がない」場合（音声だけを聞く
場面など）は、提示ポリシー blink_web_view_set_presentation_policy() が
正規の口です。画面転送の費用だけを省き、組版と描画（先読み）は止めません。

6. トラブルシューティング

6.1 EGL モードで FATAL: gl_factory_ozone NOTREACHED

原因: Wayland EGL ドライバが見つからない、または X11 Display に
フォールバックしている
対処: v1.0.10 iter7 以降を使用
(Issue #47 で v1.0.1 修正済、
Issue #53 で v1.0.10 iter7
さらに強化)。

6.2 SwiftShader モードで VK_ERROR_INITIALIZATION_FAILED

原因: ANGLE の Vulkan backend 初期化が環境の Vulkan ドライバ設定で失敗する
対処: v1.0.10 iter7 以降を使用。iter7 で SwiftShader 経路は
ANGLE Vulkan を明示的に回避するよう修正済 (Issue #53)。
iter6 以前を使っている場合は更新してください。

6.3 SwiftShader モードで描画されるがピクセルが GTK に届かない

症状: BLINK_LOAD_FINISHED に到達、FPS も 60 前後、しかし GTK ウィンドウは
真っ黒または背景色のまま
原因: Issue #54 の CopyFromSurface ガードが SwiftShader にも過剰適用されている
可能性 ([Issue #54 follow-up])
対処: v1.0.10 iter10 以降の修正を待つ。当面は software または egl に
切替。

6.4 EGL モードで描画範囲が左上にクリップされる (HiDPI)

症状: gtk_scale=2 環境で EGL モード、親ウィジェットは 1536×785 logical px
あるのに Web コンテンツが約 400×360 physical px の左上領域のみに表示
原因: size_allocate 経由で Chromium 側のビュー (RenderWidgetHostView) は正しく更新されるが、
wl_subsurface / wp_viewport の destination サイズが追従していない
(Issue #58)
対処: iter10 以降の修正を待つ。暫定的には window を 800×600 以下にして全体
表示を確保。

6.5 全モードで白画面

v1.0.10 iter7 以降でも条件によっては発生することがあります。確認手順:

詳細は トラブルシューティング を参照。

7. ベンチマーク

triple_gpu_compare サンプル (examples/triple_gpu_compare.c) で 3 モードを同一
アプリ内で並列比較できます。

Chromium ビルドツリーから実行する場合:

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

tarball / RPM でインストールした場合:

# 実行ファイルは $prefix/bin、ランタイム .so は $prefix/lib/chromium
cd /usr/local/lib/chromium   # もしくは prefix に応じて
/usr/local/bin/triple_gpu_compare

3 つの WebView が並列表示され、FPS とレンダリング品質を比較できます。

8. 関連資料