VectoJS Three
このスキルを使用すると、ライブの VectoJS 2D インターフェースを Three.js テクスチャ上に配置し、3D ポインター入力を VectoJS シーンにルーティングできます。
統合ワークフロー
@vectojs/core、@vectojs/three、three、および UI コンポーネントを使用する場合は@vectojs/uiをインストールします。- VectoJS パネルテクスチャごとに 1 つの
ThreeAdapterを作成します。 - VectoJS エンティティを
adapter.vectoSceneに追加し、内部シーンを起動します。 adapter.meshまたはアダプターのテクスチャ/マテリアルをホストの Three.js シーンに追加します。- ホストのポインター/ホイールループで、アダプターメッシュに対してレイキャストを実行し、
adapter.updateIntersection(...)を呼び出します。 - パネルを削除するときは
adapter.dispose()を呼び出します。
詳細なスニペットについては references/three-recipes.md を参照してください。
制約
- デフォルトの出力は平らなテクスチャ付きプレーンであり、3D 空間で DOM レンダリングされるわけではありません。
- VectoJS の論理的なヒットテストは、メッシュがワールド空間で変換されても 2D のままです。
- ホストアプリケーションがカメラ、レンダラー、コントロール、XR セッション、レイキャスター、およびオクルージョンルールを所有します。
- レイキャスト UV はアダプターの論理的な
width/heightにマッピングする必要があります。レイアウト計算にバッキングストアサイズを使用しないでください。 - テクスチャ解像度はシャープネスとアップロードコストに影響します。視聴距離に合わせた寸法を選択してください。
よくあるミス
| ミス | 修正方法 |
|---|---|
| オフスクリーンアダプターキャンバスを DOM に追加する | adapter.mesh を Three.js に追加します。キャンバスはテクスチャをバックアップします。 |
updateIntersection の呼び出しを忘れる | ホストのレイキャスターイベントを各ポインター/ホイールイベントごとにアダプターにルーティングします。 |
| 画面座標でディスパッチする | ThreeAdapter を通じてレイキャスト UV を使用します。 |
| 破棄されたテクスチャを保持し続ける | adapter.dispose() を呼び出し、ホストの参照を削除します。 |
| XR 内で完全な DOM アクセシビリティを期待する | 3D パネルをキャンバステクスチャとして扱い、必要に応じてホストレベルのセマンティクスを提供します。 |
バージョンおよびバックエンドの注意点(ソース確認済み)
- three ≤ 0.1.3:
ThreeRenderer.flush()は完全な GL レンダリングを実行し、Scene はすべての非バッチノードの周りでフラッシュします。そのため、エンティティ数に応じてフレームコストが O(N²) で増加しました。three 0.1.4 ではpresent()フックを介して 1 フレームに 1 回レンダリングします。他のプロファイリングを行う前にアップグレードしてください。 - テクスチャ内のネイティブ入力は制限されています。 アダプターのキャンバスはオフスクリーンであるため、Scene の投影されたアクセシビリティ要素はドキュメントに接続されません。
updateIntersectionは VectoJS 独自のイベントディスパッチにフォールバックします。ボタン、ホバー、ホイールは動作しますが、完全なネイティブ IME/テキスト編集は動作しません。テキスト入力は 3D パネルの外部に保持するか、簡略化された入力を許容してください。 stroke()の線幅はほとんどのプラットフォームで実質的に 1px です(LineBasicMaterial.linewidthは既知の WebGL の制限です)。太い線は塗りつぶし形状として描画してください。ThreeRenderer.drawImageは呼び出しごとにテクスチャを割り当てます(clear()で破棄されます)。可能な場合はソースキャンバスを再利用してください。fillTextは three 0.1.4 からキャッシュされます(font|color|text をキーとし、256 エントリの LRU)。≤ 0.1.3 では呼び出しごとに同じコストがかかるため、その場合はMSDFTextEntityを優先的に使用してください。