animaxxing-webgl

Animaxxing WebGL

GSAP で WebGL を制御する、Vanilla TypeScript のレシピです。プレーンは各画像を実際のボックスに描画し、フレーム付きビューは要素のボックス内にシーン、パーティクル、または液体の表面を描画します。GSAP はシェーダーの uniform をトゥイーンします。ページは DOM のままです。実際の <img>、またはビューのポスター <img> が alt テキスト、レイアウト、リンクを保持し、WebGL で描画できない場合は自身を表示します。

まず、対応する gsap-<framework> スキル（通常のサイトでは gsap-vanilla）を読み込み、見つからない場合はインストールしてください。このスキルが、マウント → 初期状態 → イントロ → 整定 → アウトロ → 終了状態 → アンマウント、初期化、ナビゲーション、復旧、クリーンアップのタイミングを管理します。その references/transition-archetypes.md にある Persistent WebGL canvas では、ルート間でキャンバスを維持する方法を説明しています。DOM のみのエフェクトは animaxxing スキルで扱います。このスキルでそれが必要になることはありません。

レンダラー：OGL

このレシピでは OGL 1.x を使用します。レシピで使うクラス（renderer、program、mesh、plane geometry、texture、scene）を esbuild で計測し、ミニファイして gzip 圧縮した場合、OGL 1.0.11 は 14.5 KB、three.js r186 は 133 KB です。これは、three.js の WebGLRenderer がライブラリの大部分を読み込むためです。画像のレシピでは、カスタムシェーダーを使ったピクセル空間の 2D プレーンが必要です。フレーム付きビューでは、カメラ、レンダーターゲット、ポイントジオメトリを追加しますが、ライト、マテリアル、ローダーは必要ありません。OGL の Program、Mesh、Plane、Camera、RenderTarget、Texture は、これらにそれぞれ 1 対 1 で対応します。OGL はコンテキストロストを処理しないため、ステージ側で処理します。復元時にレンダラーとすべてのレイヤーを再構築します。

プロジェクトで既に three.js を使用している場合は、OGL を追加せず、レシピを移植してください。Program には ShaderMaterial（同じ uniform オブジェクト）、Plane には PlaneGeometry、Texture には Texture を使い、Scene と、レシピのピクセル空間頂点シェーダーを使う任意のカメラを用意し、削除処理には dispose() を呼び出します。three.js はロストしたコンテキストを自動で復元するため、再構築処理は削除し、DOM フォールバックを維持してください。

セットアップと適応

• gsap 3.13 以降と ogl 1.x をインストールします。これらのレシピをそのまま信頼する前に、インストール済みのバージョンと型定義を確認してください。エフェクトはモジュールスコープで ScrollTrigger を登録します。プロジェクトでプラグインを一元管理している場合は、この処理を削除してください。モジュールはクライアントコードからのみインポートしてください。
• タスクで必要なモジュールだけを、次のファイル名でコピーします。常に webgl-stage.ts、プレーンと画像テクスチャを読み込むレシピには image-planes.ts、画像エフェクトには uniform-effects.ts、ビューには framed-views.ts を使い、その後に scene-flight.ts、particle-morph.ts、liquid-image.ts、または metaballs.ts を使います。各モジュールがインポートするのは、それより前に記載されたモジュールだけです。
• 画像には CORS が必要です。同一オリジン、data:、blob: の画像は使用できます。CDN 画像には、マークアップで Access-Control-Allow-Origin と crossorigin="anonymous" が必要です（画像プレーン）。読み取りできない画像は、DOM の描画を維持します。
• 要求されたエフェクトだけを追加してください。エフェクト定数、シェーダーの数値、ワイプ方向は編集可能なデフォルト値です。表示面に合わせて調整してください。プレーンはページレイアウトどおりに画像を描画し、独自の色、フォント、レイアウトは追加しません。
• img[data-webgl] などを使って、どの画像にプレーンを適用するかを指定します。祖先要素によるクリッピング、border-radius、フィルター、object-position に依存する画像は WebGL の対象外にするか、置き換え用シェーダーにそれらを追加してください。

必要なものだけ読む

タスク	参照先
共通のレンダラーとキャンバス、予算、コンテキストロスト、一時停止、ルートをまたいだ永続化	WebGL ステージ
<img> を追従する WebGL プレーン、CORS、シェーダーの置き換え	画像プレーン
ホバーレンズ、スクロール速度に応じた波、表示と終了時のワイプ、画像のグリッチ、ディゾルブ、ピクセル化、リップル	ユニフォームエフェクト
画像ではない描画を要素のボックス内に表示し、ポスターをフォールバックとして使う	フレーム付きビュー
スクロールまたはタイムラインで操作する、画像の3Dスパイラルを通るカメラフライト	シーンフライト
テキスト、ロゴ、球体、散布形状の間でモーフィングする GPU パーティクル	パーティクルモーフ
ポインターでドラッグした軌跡が残るリキッド画像と、注ぐように描くイントロストローク	リキッド画像
集まって単語や形になり、滴り落ちる液体金属のドロップ。またはスクロールに合わせて柱を流れ落ちるストリーム	メタボール
クライアント側のナビゲーションをまたいで1つのキャンバスを維持する	インストール済みの該当フレームワークスキルにある references/transition-archetypes.md の Persistent WebGL canvas
イントロに必要なプレーン、期限、復旧	インストール済みの該当フレームワークスキルにある references/initialization.md
スマートフォンのティアとピクセル予算	インストール済みの該当フレームワークスキルにある references/devices.md
フォールバック、コンテキストロスト、一時停止、破棄を検証する	検証、続いてフレームワークの該当チェック

フォールバックの仕様

ページの本体は DOM です。読み取り、ナビゲーション、操作にキャンバスは必要ありません。

条件	結果
JavaScript が無効	何も実行されません。画像とポスターがページになります。
WebGL がない	holdStage は null を返します。キャンバスは作成されず、プレーンとビューの ready は false になり、入力エフェクトは何も構築されません。ワイプ、グリッチ、ディゾルブ、ピクセル化、リップル、モーフ、ポアの各タイムラインは即座に終了します。
モーションの低減が有効	WebGL がない場合と同じです。設定が変更されると、コントローラーはティアダウンして再構築します。
画像が CORS で読み取り可能でない、または読み込みに失敗	その画像は DOM でのレンダリングを維持し、ほかのプレーンには影響しません。フライトではその画像が除外され、読み込まれた画像がない場合はポスターが維持されます。
コンテキストロスト	すべての画像とポスターが同時に表示され、描画は停止します。復元時には、保持されたソースとユニフォーム値から各プレーンとビューが再構築されます。
フレームで例外が発生	キャンバスは非表示になり、すべての画像が表示され、エラーが記録されます。ステージは再作成されるまで新しいプレーンを受け付けません。
画面外、またはタブが非表示	ステージはティックを停止します。画像がビューポートに近づくか、タブに戻るまで何も描画されません。

<img> またはポスターは、プレーンまたはビューが代わりにフレームを描画してから初めて透明になります（opacity: 0。アクセシビリティツリーとレイアウトには引き続き存在します）。ビューのポスターは静止状態のフレームを静止画にしたもので、描画内容を説明する代替テキストが付いています。

レシピの契約

フレームワークのフェーズ	エフェクトの責務
初期状態	なし：<img> が初期状態です。スクロール位置より上に隠されたワイプには、フレームワークの初期状態と期限を使用します。
イントロ	マウント後に imagePlane(image) またはビューのレシピを使用します。イントロが ready に依存する場合にのみ、ready を待機します。ワイプまたはグリッチは enter()、モーフは to()、リキッドは pour() を実行します。
安定状態	ホバーとウェーブは入力に応答します。アクティブなプレーンがない場合、またはタブが非表示の場合、ステージはスリープします。
アウトロ	ホバーとウェーブを元に戻してから、ワイプまたはグリッチの exit() を実行します。
終了状態	プレーンは描画を続けます。次のアクションはコントローラーが決定します。
アンマウント	エフェクトを元に戻してから、プレーンとビューを破棄します。最後の解放時にキャンバスが削除され、コンテキストが解放されます。

• ビルダーは、ページ遷移、マウント、ページのライフサイクルへの登録を行わず、実行タイミングも決定しません。
• すべてのビルダーは冪等な元に戻す関数を返します。元に戻す関数は、作成したプログラム、シェーダー、バッファー、頂点配列、テクスチャをすべて解放し、オブザーバーを切断し、トゥイーンとトリガーを停止し、リスナーを削除し、ユニフォームと画像のインライン opacity を復元します。
• ターゲットごとに所有者は 1 つです。プレーンは画像の opacity を、ビューはポスターの opacity を所有し、各エフェクトは自身のユニフォームのみを所有します。同じ画像の opacity または transform に対して、プレーンまたはビューと DOM エフェクトを組み合わせないでください。
• ユニフォームはコンテキストの復元後も維持される、通常の { value } オブジェクトです。GSAP と overwrite を使ってトゥイーンし、OGL オブジェクトを直接トゥイーンしないでください。
• ホバーはタッチとペンを無視し、タップ後に固定されません。キーボードフォーカスではレンズが中央に配置されます。フライトの傾きとリキッドの軌跡はマウスのみに応答し、指には touch で応答します。ウェーブとフライトのスクロールは、スクロールにのみ応答します。自動で動き続けるものはありません。モーフのきらめきは形状から数千分の数の範囲内にとどまり、軌跡は静止状態までフェードするため、一時停止コントロールは不要です。ループする uSpin や uTravel は環境的な動きとなるため、一時停止コントロールが必要です。