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 コンポジタ デスクトップ・本番

画面描画について

現行 (BlinkGTK 1.2.3 / Chromium 154) では、software と EGL の 2 モードで
GTK ウィンドウに Blink のレンダリング結果が表示されます。 swiftshader モードは
1.2.3-build1 まで画面に何も出ませんでした (issue #151。撮影 API もフレームが
来ずに失敗します)。1.2.3-build2 から直っており、software・EGL と同じくページが表示され、
WebGL の描画も写ります。1.2.3-build1 以前では software か EGL を使ってください。

GPU が使えない機械では、EGL を指定しても自動で software へ退避します
(v1.2.1-build2 以降)。描画データが 5 秒間届かなければ切り替わり、理由を標準
エラー出力に記します。GPU が使える機械では切り替わりません。
無効化するには BLINKGTK_EGL_AUTO_FALLBACK=0 を指定します
(白いままになる可能性があります)。

これまでに解決したもの (履歴)

版 内容
v0.9 系 --headless が browser プロセスに強制付与され白画面になっていた
v1.0.1 Issue #47 — EGL モード修正
v1.0.10 iter2-iter7 Issue #53 — SwiftShader モード修正
v1.0.10 iter5 Issue #54 — EGL モード viz Skia readback 修正
v1.0.10 iter7 Issue #55 — EGL モード Context Lost 修正
v1.0.x (2026-04-20 解決) Issue #58 — HiDPI で親コンテナのサイズに追従しない (size_allocate vfunc の実装で解決)
v1.1.x (2026-06-21 解決) Issue #59 — blink_web_view_load_uri() の繰返しでリソースが累積する
v1.2.0-build3 から GPU 描画が環境変数の指定だけで使えるようになった
v1.2.1-build2 から GPU の無い機械での自動退避

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 をお使いください。

GPU が使えない機械では自動で退避します:

ドライバが無い、仮想環境で GPU が見えないなど、egl を指定してもその機械で
GPU 経路が使えないことがあります。以前はこの場合に画面が白いまま何も起きず、
原因を知る手立てがありませんでした。

現在は、EGL 経路に描画データが 5 秒間 1 枚も届かなければ、自動的にソフトウェア
経路へ切り替えて描画を続け、その理由を標準エラー出力に記します。
GPU が使える機械では退避しません。無効化は BLINKGTK_EGL_AUTO_FALLBACK=0
(その場合、画面は白いままになります)。詳しくは
環境変数 を参照してください。

目指しているもの:

現状の制約:

現在の位置付け:

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.2.2-build5 以降):

blink_gtk_set_gpu_mode(BLINK_GPU_MODE_EGL);   /* blink_gtk_init より前 */
blink_gtk_init(&argc, &argv);

注意: blink_web_view_new_with_gpu_mode() では経路を選べません。
描画経路は blink_gtk_init() の時点で決まり、GPU プロセスへ渡す起動フラグも
そこで確定します。WebView を作る時点ではもう変えられないので、この関数に
モードを渡しても反映されず、警告だけが出ます (2026-09-14 に外部利用者の報告で判明。
それまで「EGL のつもりで software を測る」ことが起きていました)。

経路はプロセス全体に 1 つです。同一プロセス内で WebView ごとに変えることは
できません。

反映されたかどうかは blink_web_view_get_gpu_mode() で確かめられます。
起動完了のログにも「描画経路=」が出ます。
環境変数 BLINKGTK_GPU_MODE を起動前に設定する方法も従来どおり使えます。

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

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

軸 例 実行中の切替
GPU モード (本ページの software / swiftshader / egl) software → egl 不可 — プロセス再起動が必要
配送経路 (画面転送の経路) P1 (直接) ↔︎ P2 (mojo 共有メモリ) ↔︎ P3 (EGL dmabuf) 可 (P1↔︎P2 は v1.2.0-build9 以降、P3 は v1.2.1-build3 以降) — 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 配送経路のライブ切替

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

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() が
正規の口です。画面転送の費用だけを省き、組版と描画（先読み）は止めません。
止めている間も、撮影 (blink_web_view_capture_screenshot_async() など) を求められたときは
1 枚だけ出して撮り、その後はまた止めます (1.2.3-build2 以降)。

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 に届かない

この症状は 1.2.3-build2 から解消しています (Issue #54 で 2026-04-19 に一度
直し、その後の版で再発していました。issue #151)。

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

この症状は解消済みです (Issue #58、2026-04-20)。

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. 関連資料