Communitygithub.com

Liquid Glass (液态玻璃)

Apple WWDC25 の Liquid Glass(液体ガラス)マテリアル・コントロール・フルインタラクションを実装します。ボタン・カード・ナビゲーションバー・Dock・メニューなどの透明屈折ガラスUIを、Web(WebGL/CSS)、C++/Qt6、SwiftUIで再現します。

Liquid Glass (液态玻璃) とは?

このスキルは、Apple WWDC25 で発表された Liquid Glass(液体ガラス)マテリアルを、Web(WebGL/CSS)、C++/Qt6、SwiftUI の各プラットフォームで再現するための包括的な実装ガイドです。レンズ屈折、スネル位移、フレネルエッジ、RGB 色収差、厚み勾配、レンズリップ、内部発光、Regular/Clear バリアント、アダプティブ明暗、スクロールエッジフェード、そしてマルチパネルの独立したドローコールによるパフォーマンスアーキテクチャをカバーしています。 スターターファイル(glass-starter.html)は約90行のシェーダー、1プログラム、1回のドローで動作し、Chrome(ソフトウェアレンダリング SwiftShader 含む)で実動作確認済みです。このファイルをベースに修正することで、ゼロからGLSLを書くことなく、10分で実用的なガラス効果を実現できます。 本番環境では、9枚のガラスパネルとフルインタラクションを備えたスタジオ版(liquid-glass-studio.html)が推奨されます。各パネルは自身のAABB(バウンディングボックス)のみをラスタライズすることで、8枚のガラスでも1枚のフルスクリーンと同等のフィルレートを実現し、高いパフォーマンスを維持します。 スキルは、光路モデル(凸面高さ場、スネル屈折、厚み加重)、パラメータレシピ、対話モデル(クリック、ドラッグ、展開/分離、押下フィードバック)、Apple HIGに基づくデザインルール、8つのよくある落とし穴、そして性能予算と段階的な機能縮退戦略を詳細に文書化しています。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Cyt-56/liquid-glass-webgl/tree/main/legacy

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Liquid Glass 実装

0. 最速パス(この通りやれば10分で使えるガラスができる)

ゼロからGLSLシェーダーを書かないでください。 ゼロから400行のGLSLを書いて正しく動作させるのは非常に難しく、「何か違う」という結果になる最大の原因はこれです。

  1. starter/glass-starter.html を納品ディレクトリにコピーします。
  2. ファイル上部の CONFIG 内の5つの数値(refract / mag / rim / disp / tint)だけを変更し、リロードして変化を確認します。
  3. drawBG() の描画内容を、ユーザーが要求する下層コンテンツに置き換えます。これが最も重要なステップです:ガラス効果の90%は、その下にあるものによって決まります。
  4. PANEL の幅・高さ・角丸を変更してガラスの形状を決定します(r = h/2 で完全なカプセル型になります)。
  5. さらにガラスを増やす場合は、矩形をコピーし、ループ内で uRect を使って個別に描画します(アーキテクチャは第3節を参照)。

starter は約90行のシェーダー、1つのプログラム、1回のドローで構成されており、以下すべてを含みます:スネル屈折、厚み加重横方向変位、フレネルリム、エッジ乳白色、上部ハイライト帯、下部輝弧、RGB 色収差、レンズ巻きリップ、押下フィードバック。Chrome(ソフトウェアレンダリング SwiftShader 含む)で実動作確認済みです。

すぐに効果を確認したい場合:ブラウザで starter/glass-starter.html を開き、マウスでガラス上をドラッグすると、青いバーが拡大・変位する様子が見られます。

0.5 三つの絶対ルール

  1. 必ず開いて確認してから納品すること。 コードを書いただけで開かずに納品するのは、本スキルで失敗する最大の原因です。GUIがない場合は、ヘッドレススクリーンショットを使用してください:

    chrome --headless=new --enable-unsafe-swiftshader --virtual-time-budget=5000 ^
           --window-size=820,700 --screenshot=out.png "file:///<絶対パス>"
    

    そして、実際にその画像を確認し、ガラスが表示されていることを確認してください。スクリーンショットの証拠がない限り、完了と主張しないでください。

  2. シェーダーのエラーは必ずページ上に表示すること。 スクリーンショットでは console.error は見えません。真っ黒な画面を見てなぜ動かないかわからなくなります。compileShader の直後に以下を追加してください:

    if (!gl.getShaderParameter(s, gl.COMPILE_STATUS))
      appendPre("shader コンパイル失敗:\n" + gl.getShaderInfoLog(s));   // appendPre = body に赤い <pre> を追加
    
  3. まず少なく、後から多く。 一枚のガラスが正しく動くことを確認してから、二枚目を追加してください。屈折 + インタラクション + マルチパネル + アニメーションを同時に行うと、エラーが発生した場合に原因を特定できません。

0.6 「なんか違う」?症状別原因

症状最も可能性の高い原因修正方法
画面全体が真っ黒で背景だけが見えるパネルが描画されていないuRect が渡されているか、uRad が0でないか、draw が4頂点 TRIANGLE_STRIP で行われているか確認
ガラスの中が鏡像 / 文字が反転テクスチャの Y 軸方向が逆UNPACK_FLIP_Y を有効にしている場合は 1.0 - uv.y でサンプリング、無効の場合はそのまま uv.y を使用
屈折が分からず、ただぼやけているだけ変位量が小さすぎるoff = lat * tpx * refract、まず tpx が数十ピクセルあることを確認。refract を一時的に3にして変化を見る
エッジ全体に虹色の硬い帯が出る色収差がエッジ全体に広がっている色収差に eW*eW の二乗減衰をかけ、最も外側でのみチャンネルを分離する
ガラスが灰色のプラスチックのように見える下層のコンテンツが単調すぎる下にコントラストの高いコンテンツ(テキスト、カラーバー、グリッド)が必要。そうでなければ何を調整しても霧のようになる
上部のハイライトがマウスに追従する懐中電灯のようになるハイライト帯が横方向に狭くなっているエッジ全体の基本輝度を維持し、ポインターは局所的な強調のみ行う(0.7 ベース + 0.3 ゲイン)
アニメーションがふにゃふにゃしていて勢いがない1次指数イージングを使用している2次バネに置き換え、減衰0.6〜0.7、5〜8%のオーバーシュートを許可(第6.5節参照)
フレームレートが30以下に落ちるパネルが多すぎる / 毎フレーム全画面描画各ガラスは自身のAABBのみラスタライズ。同一画面で10枚以下。背景アップロードは頻度を下げる

本格版(マルチパネル、フルインタラクション、光路解析)が必要な場合は以下を読み進めてください。ガラス一枚だけであれば、starter で十分であり、第4節まで読めば十分です。

1. プラットフォーム選択

目標使用するアセット説明
一枚のガラス / 素早く正しく作りたいstarter/glass-starter.html90行シェーダー、1回のドロー、実動作確認済み。これをベースに修正し、ゼロから書かないこと
ウェブ / デモ / インタラクティブプロトタイプ(推奨)liquid-glass-studio.html単一WebGLキャンバス + 9枚のガラス + フルインタラクション + リアルタイム光路解析。実際のスネル屈折、色収差、厚み勾配
シンプルなガラス一枚だけliquid-glass-webgl.htmlシングルパネル・シングルパスの軽量版。変位近似、インタラクションレイヤーなし
WebGLが使えない / フォールバックが必要liquid-glass-css.htmlbackdrop-filter + SVG変位。動作は似ているがピクセル単位の屈折はなし
デスクトップ C++ / 自前レンダラーcpp/glass_math.h + cpp/qt6/純粋数学ライブラリ + Qt6 ウィジェット。実運用では公式をGLSLに移植
iOS / macOS ネイティブswift/LiquidGlassDemo.swift公式 .glassEffect API。低バージョンでは SimulatedGlass でフォールバック

WebGL を優先する理由:屈折は下層をピクセル単位でサンプリングする必要があります。CSSではブロック全体の変位しかできず、エッジの「レンズリップ」は絶対に再現できません。

2. アセットとドキュメント

liquid-glass/
├── starter/
│   └── glass-starter.html        # 最小実行可能スケルトン:90行シェーダー、1プログラム1ドロー、実動作確認済み
├── liquid-glass-studio.html      # フラッグシップ:フルインタラクション + リアルタイム光路(本スキルの主要な納品物)
├── liquid-glass-webgl.html       # 軽量シングルパネル版
├── liquid-glass-css.html         # CSS/SVG フォールバック
├── cpp/
│   ├── glass_math.h              # SDF、スクワイル、スネル/フレネル、BK7色収差、厚み/リップ/アークリムの純粋関数
│   └── qt6/                      # CMake プロジェクト
├── swift/LiquidGlassDemo.swift   # 公式 API + シミュレーションフォールバック
└── references/
    ├── feature-matrix.md         # Session 219 の22項目機能マトリックス、各プラットフォームのカバレッジ、デザイン上の制約
    ├── optics-model.md           # 光路物理モデルとパラメータ範囲(シェーダーを書く前に必読)
    ├── interaction-playbook.md   # クリック/展開/分離/ドラッグのステートマシンと受け入れチェックリスト
    └── swiftui-api.md            # SwiftUI ガラスAPIのシグネチャと注意点

3. レンダリングアーキテクチャ(スタジオ版)

2つのプログラム、9回のドローコール。複数のガラスを1つのフルスクリーンパスのuniform配列に詰め込まないこと。

Pass 1  pBg   : フルスクリーンクアッド、背景テクスチャを直接サンプリング
Pass 2  pGl   : 同じクアッドVBO、各ガラスを自身のAABBに平行移動/スケーリングし、一度に drawArrays

頂点シェーダーは [-1,1] のクアッドをパネルにマッピングします:

uniform vec2 uC, uH, uRes;          // 中心、半幅高さ、キャンバスサイズ(全てデバイスピクセル)
void main(){
  vec2 cN = (uC/uRes)*2.0 - 1.0;  cN.y = -cN.y;      // 画面左上原点 → NDC
  vec2 hN = ((uH + vec2(6.0))/uRes)*2.0;             // アンチエイリアス用に6px拡張
  gl_Position = vec4(cN + vec2(aPos.x, -aPos.y)*hN, 0.0, 1.0);
}

フラグメントでは gl_FragCoord からスクリーン座標を逆算します(varying ではありません。varying は平行移動後のクアッド内のローカル座標です):

vec2 px = vec2(gl_FragCoord.x, uRes.y - gl_FragCoord.y);
float d  = sdRoundBox(px - uC, uH, uRad);
float aa = smoothstep(-1.0, 1.4, d);
if(aa > 0.995) discard;                 // AABB 内で輪郭外のピクセルは破棄
    gl_FragColor = vec4(gcol, 1.0 - aa);    // エッジはアルファで遷移

外側で gl.enable(BLEND) + blendFunc(SRC_ALPHA, ONE_MINUS_SRC_ALPHA) を有効にし、描画後に無効にします。

この方法により、各ガラスは自身の矩形のみをラスタライズするため、8枚のガラスのフィルレートはほぼ1枚のフルスクリーンと同等になり、「フルスクリーン × 8回ループ」より一桁高速です。

各ガラスの1回のドローに設定する必要があるスカラーuniform(固定順序、全て必須):

uniform意味算出元
uC uH画面中心 / 半幅高さ(デバイスピクセル、左上原点)(g.x+g.w/2)*dpr 等
uRad角丸半径(デバイスピクセル)min(g.radius, min(w,h)/2)*dpr
uVariant uThick uMagMulバリアント / 厚マテリアル / パネルレベルの倍率パネル属性
uHover uPress uGlow uActiveインタラクション状態 0~1毎フレームのバネ値
uPtrパネル内のポインターの正規化座標 −1~1(cx-c)/(w/2)
uAmb下層環境色 rgbgetImageData サンプリング
グローバルuRes uTex uRefraction uRim uTint uDisp uN uMode uContrast uOpaque uMag uWire毎フレーム1回設定

4. 光路モデル(シェーダーを書く前にこの節を必読)

7ステップ、順序は変更不可:

  1. 輪郭:sdRoundBox で符号付き距離 d(内部は負)を取得。正規化深度 x = clamp(-d/band, 0, 1)、0 = 輪郭、1 = 中心。band = max(5, min(hx,hy)*0.30)。
  2. 凸面高さ場:H(x) = sqrt(1 - (1-x)²)、H'(x) = v/sqrt(1-v²)(v = clamp(1-x, 0.02, 0.9995))。sqrt を使用し pow は使わないこと——pow は ANGLE 上で非常に低速です。
  3. 入射角:sinI = min(H'/sqrt(1+H'²), 0.62)、thI = asin(sinI)、thT = asin(sinI/n)、n = 1.5168(BK7)。 上限0.62はハード制約:0.93まで上げるとエッジの変位が200ピクセル級になり、パネル全体が黒い塊に押しつぶされます。
  4. 厚み:tpx = mdim*(0.05 + 0.28*H)*(1 + 0.40*thick)*vg、vg = 1 + 0.24*(1 - smoothstep(-0.85, 0.35, q.y))(下厚上薄)。 tpx は「ピクセル厚み」で、正常範囲は 0.1 ~ 0.4 * mdim。0.5を超えると必ず歪みます。
  5. 変位:lat = tan(thI-thT)、off = -dir*lat*tpx*uRefraction*Tf、さらにエッジ付近の補正項 -dir*(1-smoothstep(0,0.28,x))*tpx*0.22 を追加。最終的に off = clamp(off, -10, 10)——クリッピングは「エッジが遠くのコンテンツを無理やり引き込む」のを防ぐ唯一の保険です。
  6. 焦点/レンズリップ:focal = uMag * uMagMul * (0.50*cW - 0.40*eW)、cW = smoothstep(0.10,0.90,x)、eW = 1-smoothstep(0,0.62,x)。 中心 focal > 0 → サンプリング点が中心に収束 → 拡大。エッジ focal < 0 → サンプリング点が外側に拡散 → コンテンツが外側に折れ曲がる、これが Apple のリップです。1-focal は常に正でなければなりません。そうしないと局所的に180° 反転し、反転した文字が現れます。 uMagMul はパネルレベルの倍率です(第6節参照):小さいガラスは曲率が大きく拡大率が高く、大きなガラス板は平面に近く拡大率が低い。この係数がないと、同じ uMag で 214×300 のテキストプレートが拡大されすぎて文字化けし、158×126 のレンズでは効果が不十分になります。パネルサイズと magMul の対応:lens 1.30、plate 0.55、capsule 0.85、panel 0.60、dock 0.80、nav 0.90。
  7. サンプリングと合成:sp = c + rel*(1-focal) - off。3チャンネルを ±uDisp*7*eW で分離サンプリングし色収差を実現。次に variant による減光、uAmb 環境色のにじみ(0.10)、tint による輝度圧縮 0.58*L + 0.133、暗部補光 +vec3(0.048,0.051,0.058)、フレネルリム + 乳白色 + 上部鏡面 + 下部輝弧((1+0.75*press))、内部発光、の順で合成します。

テクスチャ座標のY反転は必須

背景キャンバスのアップロード時に UNPACK_FLIP_Y_WEBGL = true を有効にしている場合、テクスチャの v=0 は画面下部に対応します。一方 px は左上原点です。したがって:

vec2 uv0 = vec2(sp.x/uRes.x, 1.0 - sp.y/uRes.y);   // これがないとガラス全体が反転画像になる

これはオプションではありません。症状は:ガラス内に上下反転した文字が表示され、かつコンテンツが画面の別の場所から取得されることです。

5. リアルタイム光路解析

2セットを提供します。互いに代替ではありません:

A. 診断フィールド(params.wire = 1) — シェーダー内の中間変数を直接描画し、「本当に屈折しているか」を判断するために使用します:

チャンネル意味読み方
Rlength(off)/mdim*22赤 = 偏向強度。中心はほぼ黒、エッジは赤いはず
Gx(エッジ深度)緑の輪が輪郭に沿い、内側に向かって急速にゼロになる
Bfocal*2青 = 倍率、中心が明るく、エッジが暗い

3つすべてが同時に現れ、かつ領域がはっきりしている場合、光路が成立しています。全面真っ黒の場合は、通常 uniform が渡されていません(第7節の落とし穴1を参照)。

B. 断面光路図(右下 308×150 canvas) — 11本の光線が凸面ガラスを透過する際の入射/内部/出射を描画し、エッジの光線の θi / θt / Δx と厚みの段階(thin/thick)をラベル付けします。焦点パネルはポインターのホバー状態に応じて切り替わります。

2つの曲線(シェーダーと2D図)は同じ公式と同一の sinI 上限を使用する必要があります。そうしないと、図には68°と書かれていても画面は38°で計算され、パラメータ調整時に誤解を招きます。

6. パラメータレシピ(参考画像を見ながら調整)

欲しい効果refractmagrimdisptintthick
厚ガラスカプセル(大きく、エッジが明るく、下部の弧が顕著、内部はやや暗く透過)1.200.350.950.220.24✓
カラーバー上のレンズ(バーが拡大・変位、左右に明るい点ができる)1.500.601.000.180.10✓
小さな文字の上の厚ガラス(文字が拡大 + エッジが歪む)1.250.420.800.300.16✓
上部ナビゲーションバー(薄く、控えめ)0.900.200.600.150.10✗
コントロールパネル(大きく、文字が読めること)1.000.150.550.120.14✗
0 番デフォルト1.200.450.850.350.20—

調整順序:まず refract で変位の大きさを決める → 次に mag でリップの強さを決める → 次に rim でエッジの明るさを決める → 最後に disp/tint で質感を決める。逆の順序で調整すると、必ず調整が互いに干渉します。

3つのレシピをワンクリックで切り替え(スタジオ版は組み込み済み)

コントロールパネル上部に「厚カプセル / レンズ / テキスト / デフォルト」の4つのボタンがあります。クリックすると同時に2つの動作を行います:5つのスライダーを上の表の値に設定し、対応するパネルに1回の flash 内部発光を追加します(「この部分を見て」と視覚的に示す)。

var PRESETS = {
  capsule: { refract:1.20, mag:0.35, rim:0.95, disp:0.22, tint:0.24, focus:"capsule" },
  lens:    { refract:1.50, mag:0.60, rim:1.00, disp:0.18, tint:0.10, focus:"lens" },
  text:    { refract:1.25, mag:0.42, rim:0.80, disp:0.30, tint:0.16, focus:"plate" },
  reset:   { refract:1.20, mag:0.45, rim:0.85, disp:0.35, tint:0.20, focus:null }
};

プログラムで params を変更しても、スライダーの input イベントはトリガーされません。そのため、手動で syncUI() を呼び出してスライダーの位置と数値ラベルを書き戻さなければならず、そうしないとスライダーと実際のパラメータが乖離します。

flash の減衰は step() 内に記述し、かつ glow に統合する必要があります(上書きしてはいけません。そうしないと、押下中のグローが flash に打ち消されます):

if(g.flash > 0.002) g.flash *= 0.90; else g.flash = 0;
var gl = Math.max(g.active ? 1 : 0, g.flash*0.85);
g.glow += (gl - g.glow)*k;

6.5 最も見落とされがちな4つのAppleディテール

これら3項目は Session 219 に登場しますが、デモを見ただけでは見逃しがちです。これらがないと、「ガラスらしさ」が一気に低下します。

① 上部ハイライトがポインターに追従する(鏡面反射は動くが、ポインターに追従してはいけない)

固定された上部エッジの輝線は「シール」です。しかし、ハイライトを「ポインターを中心に両側に減衰する」ようにすると、ガラス上を懐中電灯で照らしているようになります——これは最もよくある誤りです。正しい方法は:上部エッジ全体が常に明るく、ポインターは局所的な強調のみを行うことです。

float tx       = q.x - uPtr.x*0.30;                    // ポインターのオフセットは小さく(0.3、0.55ではない)
float baseTop  = 1.0 - smoothstep(-0.92, -0.30, q.y);  // エッジ全体の基本輝度
float boostTop = 1.0 - smoothstep(0.12, 1.00, abs(tx)); // ポインター位置での追加ゲイン
float topW     = baseTop * (0.70 + 0.30*boostTop);      // 最低0.70、最高1.0

間違った書き方とその結果を比較してください:

書き方表現
smoothstep(-0.30,-0.92,q.y) * (1-smoothstep(0.06,0.72,abs(tx)))ポインターが動くと明るいのは短い部分だけ、他は真っ黒 → 懐中電灯
baseTop * (0.70 + 0.30*boostTop)エッジは常につながったまま、ポインター位置だけ少し明るい → 本物の鏡面

また、逆順の smoothstep を書かないこと:smoothstep(1.0, -1.0, d) や smoothstep(-0.30, -0.92, x) のように edge0 > edge1 となるものは、GLSL 仕様上は未定義動作であり、一部の実装で問題が発生します。すべて 1.0 - smoothstep(小, 大, x) の形に書き換えてください。

ポインター方向の鏡面反射(dot(dir, pdir) から計算される spec)は押下時にのみ強度を与え、ホバー時にはまったく加えないでください。そうしないと、マウスを動かしたときに小さな輝点がエッジを追いかけるように付いてきます。

② 内部発光が隣接するガラスに波及する(約12%) パネル A を押すと、隣のパネル B もわずかに光り、「光がガラス間を流れる」ような印象を与えます。

var maxGlow = 0;
G.forEach(g => { if(g.glow > maxGlow) maxGlow = g.glow; });
if(maxGlow > 0.02)
  G.forEach(g => { if(!g.active) g.glow = Math.max(g.glow, maxGlow*0.12); });

係数は0.15を超えないようにしてください。超えると画面全体が明るくなり、「ハイライトは控えめに」というデザイン上の制約を破ります。

③ スクロールエッジフェード効果 ガラスの後ろのコンテンツがエッジまでスクロールしてきたときに、ハードなカットラインではなく、「背景に溶け込む」ようにします。アルファマスクを使用し、かつコンテンツがまだある場合にのみマスクします:

var st   = el.scrollTop;
var rest = el.scrollHeight - el.clientHeight - st;
var top  = st > 3 ? 28 : 0;              // 一番上までスクロールしたらマスクしない。そうしないと常に偽の影ができる
var bot  = rest > 3 ? 28 : 0;
el.style.webkitMaskImage =
  "linear-gradient(to bottom, rgba(0,0,0,0) 0px, #000 "+top+"px, " +
  "#000 calc(100% - "+bot+"px), rgba(0,0,0,0) 100%)";

要点:mask は アルファチャンネルを読み取ります。rgba(0,0,0,0) を使用し、transparent は使用しないでください(一部の古い実装では transparent は透明な黒ですが、動作は同じでも意味がより明確です)。スクロールコンテナ自体は pointer-events:auto である必要があります。そうしないとスクロールできません。ただし、これによりガラス全体がドラッグを受け付けなくなることに注意。ドラッグが必要なガラスでは、スクロールコンテナを全面に敷き詰めないでください。

④ 分離 / 結合:「スライド」ではなく「バネのように弾む」

1次指数イージング x += (tx - x)*0.19 は決してオーバーシュートせず、最後は常にふにゃふにゃと停止します。2次バネに置き換えてください:

// 毎フレーム dt = 1/60
g.vx += ((g.tx - g.x)*omX*omX - 2*z*omX*g.vx)*dt;
g.x  += g.vx*dt;
g.vw += ((g.tw - g.w)*omW*omW - 2*z*omW*g.vw)*dt;
g.w  += g.vw*dt;
if (g.w < 0){ g.w = 0; g.vw = 0; }   // 狭まりすぎて負の幅になると描画がおかしくなる

omX = 15, omW = 18.5, z = 0.66 → 約6%のオーバーシュート、約0.45秒周期。幅の剛性は変位より大きくする必要があります(18.5 > 15)。そうすることで「まず変形して、後で戻る」という動作になります。両方が同じだと、パネル全体が平行移動するだけで、また板のように見えてしまいます。

分離が「2枚の板が押し広げられた」ように見せるための2つの重要なポイント:

  • 右側のピースの位置は固定(tx は常に lay.x + lay.w - 一片の幅)。幅だけを 0 ↔ 140 の間で変化させる → 視覚的には「中央から裂ける」ように見え、「縮んだり伸びたり、横に引き合う」ようには見えない
  • 裂ける/閉じる瞬間に、両方のピースにそれぞれ flash = 1 の内部発光のアクセントを与えることで、動作に重みが出る

1次イージングの係数をいくら大きくしても、「弾む」ような動作は作れません。それは速度の問題ではなく、曲線の形状の問題です。

7. 必ず踏む8つの落とし穴(実機検証済み)

  1. 配列 uniform は信頼できない。uniform vec4 uGeo[12] は ANGLE/D3D 上で getUniformLocation("uGeo[0]") が非 null を返し、uniform4fv もエラーを出さないが、データがシェーダーに入らない——すべてのパネルが0を読み取り、if(hh.x < 1.5) continue ですべてスキップされ、ページは暗い背景だけが残る。結論:uniform 配列でマルチパネルのジオメトリを渡さない。代わりにパネルごとに1回のドローコールを使用する。

  2. ループ + uniform の分岐はまとめて最適化される可能性がある。for 内で if(uOpaque > 0.5){...} と書くと、一部のドライバでループ本体が破棄される。ループ内では常に分岐のない mix/step を使用する。「パネルごとに1回のドロー」にすれば、ループ自体が不要になる。

  3. 使用されていない uniform は宣言しても最適化で削除され、getUniformLocation が null を返し、「uniform が足りない」と誤報する。宣言と使用は常にペアで存在しなければならない。

  4. gl.getUniform(prog, null) は TypeError を投げ、そのフレームの後続のコード(FPS、プローブなど)がすべてスキップされ、ページが「フリーズした」ように見える。location を取得した後は必ず null チェックを行うこと。

  5. テクスチャの Y 軸(第4節参照):反転しないと、鏡像 + 反転文字になる。

  6. click のみにバインドするとイベントが失われる。自動化環境や一部のホストでは click が合成されず、インタラクションがすべて無効になる。pointerdown + pointerup + 変位閾値 でクリック判定を実装し、click は補助としてのみ使用する。

  7. half は GLSL ES の予約語:vec2 half = uRect.zw*0.5; と書くとシェーダー全体のコンパイルが失敗し、エラーログには syntax error としか表示されず、原因の特定が非常に難しい。半幅半高には hb を使用する。同様のトラップワードとして filter、input、output、long、short、double、packed がある。

  8. 逆順の smoothstep は未定義動作:smoothstep(1.0, -1.0, d)、smoothstep(-0.30, -0.92, y) のような edge0 > edge1 の書き方は、テストしたブラウザでは正しく動いても、別のブラウザではゴミ値になる可能性がある。常に 1.0 - smoothstep(-1.0, 1.0, d) の形に書き換える。

8. 受け入れチェックリスト(修正のたびに実行)

レンダリング

  • 8枚のガラスすべてが表示され、位置がレイアウトテーブルと一致している
  • ガラス内に下層コンテンツ(文字/青バー/グリッド)が見える。単なる色の塊ではない
  • ガラス内のコンテンツの向きが正しい(反転、左右ミラーがない)
  • エッジに明るいリムがあり、上部に鏡面ハイライト、下部に輝弧がある
  • 暗い背景上のガラス内部が真っ黒ではない(わずかに霧状のグレーがある)
  • 輪郭エッジのアンチエイリアスがきれいで、ハードエッジや白い縁がない

インタラクション(詳細版は references/interaction-playbook.md を参照)

  • カプセルをクリック → メニューが上に伸び、下端は動かない。再度クリックで収納
  • カプセルをドラッグ → 追従し、離すとバウンドして戻る。エッジでクランプされる
  • Dock の分離ボタンをクリック → 2つのピースが開く。再度クリックで閉じる
  • 任意のパネルを押す → わずかに縮む + 内部発光。離すとゼロに戻る
  • ホバー → ハイライトがポインター方向にオフセット
  • スペース / S / W キーボードショートカットが機能する
  • 「厚カプセル / レンズ / テキスト / デフォルト」の4つのキーをクリック:5つのスライダーの位置と数値が同期して変化し、ターゲットパネルが内部発光で一瞬光る
  • リサイズ後も展開・分離状態が保持される

パフォーマンス

  • FPS が安定しており、定期的なフレームドロップがない
  • パネル数を変更した後、ドローコール数を再評価している

9. 性能予算と機能縮退

項目予算超えた場合の対応
同一画面のガラスパネル≤ 10枚1枚にまとめる、または重要でないパネルを CSS フォールバックに
各ドローのカバー面積自身のAABBのみフルスクリーンでガラスパスを実行しない
背景テクスチャのアップロード5フレームに1回(光斑は遅い)静止時は8フレームに1回に低下
背景ピクセル比min(dpr, 1.5)フレームドロップがあれば1.0に低下
レンダリング倍率アダプティブ 0.72 / 1.0< 42fps でダウングレード、> 56fps でアップグレード
下層輝度サンプリング getImageData10フレームに1回、w*h > 24000 のパネルのみ最大の同期オーバーヘッド。サンプリングを減らす方が良い
光路断面図4フレームに1回静止時は6フレームに1回に低下可能
コントロールパネルの高さmin(520, VH*0.62, VH-250)右下の光路図に240px確保。小さいウィンドウでは重なる可能性あり

機能縮退の順序:パネル数を減らす → レンダリング倍率を下げる → 背景アップロード頻度を下げる → 色収差をオフにする → ページ全体を CSS 版にフォールバック。

10. デザイン上の制約(Apple HIG)

  • ガラスはナビゲーションレイヤーのみで使用する。コンテンツレイヤーにガラスをかぶせない。
  • ガラスを重ねない。2枚のガラスが重なると、屈折の参照が失われ、汚れた斑点のように見える。
  • バリアントを混在させない。1画面内で Regular と Clear を混ぜない。
  • tint は主要な操作にのみ、かつ小さな面積で使用する。全面を染色するとガラスではなくなる。
  • ハイライトは控えめに。rim は「一周」であって「太い白い線」ではない。uRim > 1.2 は偽物に見える。
  • 3つのアクセシビリティスイッチを必ず用意する:透明度を下げる、コントラストを上げる、動きを減らす。前者は背景コンテンツを不透明なベースに置き換え、後者はバネの k を1に設定する。
  • ガラス上に文字を重ねる場合、DOM コンテンツには text-shadow が必要。明るいガラス上では白い文字が読めなくなる。

11. C++ / SwiftUI への移植

  • C++:cpp/glass_math.h には、同じ H(x)、H'(x)、fres()、厚み勾配、リップ、弧リムの純粋関数が入っている。これらをフラグメントシェーダーに直接移植する。Qt6 の例はインターフェースの形態を示すだけであり、本番環境では CPU でピクセル単位の処理を行わないこと。
  • SwiftUI:可能な限り .glassEffect(.regular, in: shape) でシステム実装を使用する。カスタム形状やカスタム屈折が必要な場合のみ、SimulatedGlass を自前で描画し、コメントにシステム効果との差異(システム版にはプロセス間の背景サンプリングと本物の動的ハイライトがある)を明記すること。

関連スキル