VectoJS Three 是做什麼的?
使用此技巧將即時的 VectoJS 2D 介面放置到 Three.js 紋理上,並將 3D 指標輸入路由回 VectoJS 場景。
整合工作流程
- 安裝
@vectojs/core、@vectojs/three、three及@vectojs/ui(如使用 UI 元件)。 - 為每個 VectoJS 面板紋理建立一個
ThreeAdapter。 - 將 VectoJS 實體新增至
adapter.vectoScene,然後啟動內部場景。 - 將
adapter.mesh或適配器的紋理/材質新增至主 Three.js 場景。 - 在主機的指標/滾輪循環中,對適配器網格進行光線投射,並呼叫
adapter.updateIntersection(...)。 - 移除面板時,呼叫
adapter.dispose()。
請參閱 references/three-recipes.md 以取得程式碼片段。
限制
- 預設輸出為平坦紋理平面,而非 DOM 渲染的 3D 物件。
- 即使網格在世界空間中進行變換,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 渲染,且場景會對每個非批次處理的節點進行清除——因此每個畫面的成本會隨實體數量呈 O(N²) 增長。three 0.1.4 透過present()鉤子每個畫面僅渲染一次;在進行任何效能分析前請先升級。 - 紋理內的原生輸入功能有限。 適配器的畫布為離屏,因此場景的投影無障礙元素永遠不會連接到文件;
updateIntersection會回退到 VectoJS 自身的事件分派。按鈕/懸停/滾輪可正常運作;完整的原生 IME/文字編輯則無法使用——請將文字輸入保留在 3D 面板外部,或接受簡化後的輸入。 stroke()線條寬度在大多數平台上實際上為 1px(LineBasicMaterial.linewidth是已知的 WebGL 限制)。建議改用填充形狀繪製粗線條。ThreeRenderer.drawImage每呼叫一次每個畫面就會分配一個紋理(在clear()時釋放);請盡可能重複使用來源畫布。fillText從 three 0.1.4 開始會進行快取(以字型|顏色|文字為鍵的 LRU,共 256 個條目)——在 ≤ 0.1.3 版本中,它仍有每次呼叫的成本,因此建議使用MSDFTextEntity。