@realsee/five-webgpu 1.0.0-alpha.1 → 1.0.0-alpha.11

package/docs/documents/features_clipper.html

@@ -49,7 +49,7 @@
 <h2 id="examples" class="tsd-anchor-link">Examples<a href="#examples" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <h3 id="基础用法-basic-usage" class="tsd-anchor-link">基础用法 (Basic Usage)<a href="#基础用法-basic-usage" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <p>创建一个不可见的 Box，将其位置和大小作为裁切区域。</p>
-<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;three&#39;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 1. 创建一个辅助 Mesh 来定义裁切区域</span><br/><span class="hl-8">// 注意：必须使用 1x1x1 的 BoxGeometry，因为 Shader 是基于单位立方体判断的</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">clipperMesh</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Mesh</span><span class="hl-1">(</span><br/><span class="hl-1">  </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">BoxGeometry</span><span class="hl-1">(</span><span class="hl-11">1</span><span class="hl-1">, </span><span class="hl-11">1</span><span class="hl-1">, </span><span class="hl-11">1</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">MeshBasicMaterial</span><span class="hl-1">({ </span><span class="hl-6">color:</span><span class="hl-1"> </span><span class="hl-11">0xff0000</span><span class="hl-1">, </span><span class="hl-6">wireframe:</span><span class="hl-1"> </span><span class="hl-3">true</span><span class="hl-1"> })</span><br/><span class="hl-1">);</span><br/><br/><span class="hl-8">// 2. 设置裁切盒的位置、旋转和缩放</span><br/><span class="hl-6">clipperMesh</span><span class="hl-1">.</span><span class="hl-6">position</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">1.5</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">); </span><span class="hl-8">// 抬高位置</span><br/><span class="hl-6">clipperMesh</span><span class="hl-1">.</span><span class="hl-6">scale</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-11">2</span><span class="hl-1">, </span><span class="hl-11">3</span><span class="hl-1">, </span><span class="hl-11">2</span><span class="hl-1">);      </span><span class="hl-8">// 设定大小为 2x3x2</span><br/><span class="hl-6">clipperMesh</span><span class="hl-1">.</span><span class="hl-6">rotation</span><span class="hl-1">.</span><span class="hl-6">y</span><span class="hl-1"> = </span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-4">PI</span><span class="hl-1"> / </span><span class="hl-11">4</span><span class="hl-1">; </span><span class="hl-8">// 旋转 45 度</span><br/><br/><span class="hl-8">// 更新矩阵，确保 .matrix 属性是最新的</span><br/><span class="hl-6">clipperMesh</span><span class="hl-1">.</span><span class="hl-5">updateMatrix</span><span class="hl-1">();</span><br/><br/><span class="hl-8">// (可选) 将辅助 Mesh 加入场景以便调试看到范围</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">clipperMesh</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 3. 应用裁切参数</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-6">clippers</span><span class="hl-1"> = [</span><br/><span class="hl-1">  {</span><br/><span class="hl-1">    </span><span class="hl-6">clippingBoxMatrix:</span><span class="hl-1"> </span><span class="hl-6">clipperMesh</span><span class="hl-1">.</span><span class="hl-6">matrix</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-8">// floorIndex: 0 // 可选：仅裁切第 0 层</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">];</span><br/><br/><span class="hl-8">// 4. 触发重绘</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">needsRender</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span>
+<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;three&#39;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five-webgpu&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 1. 创建一个辅助 Mesh 来定义裁切区域</span><br/><span class="hl-8">// 注意：必须使用 1x1x1 的 BoxGeometry，因为 Shader 是基于单位立方体判断的</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">clipperMesh</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Mesh</span><span class="hl-1">(</span><br/><span class="hl-1">  </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">BoxGeometry</span><span class="hl-1">(</span><span class="hl-11">1</span><span class="hl-1">, </span><span class="hl-11">1</span><span class="hl-1">, </span><span class="hl-11">1</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">MeshBasicMaterial</span><span class="hl-1">({ </span><span class="hl-6">color:</span><span class="hl-1"> </span><span class="hl-11">0xff0000</span><span class="hl-1">, </span><span class="hl-6">wireframe:</span><span class="hl-1"> </span><span class="hl-3">true</span><span class="hl-1"> })</span><br/><span class="hl-1">);</span><br/><br/><span class="hl-8">// 2. 设置裁切盒的位置、旋转和缩放</span><br/><span class="hl-6">clipperMesh</span><span class="hl-1">.</span><span class="hl-6">position</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">1.5</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">); </span><span class="hl-8">// 抬高位置</span><br/><span class="hl-6">clipperMesh</span><span class="hl-1">.</span><span class="hl-6">scale</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-11">2</span><span class="hl-1">, </span><span class="hl-11">3</span><span class="hl-1">, </span><span class="hl-11">2</span><span class="hl-1">);      </span><span class="hl-8">// 设定大小为 2x3x2</span><br/><span class="hl-6">clipperMesh</span><span class="hl-1">.</span><span class="hl-6">rotation</span><span class="hl-1">.</span><span class="hl-6">y</span><span class="hl-1"> = </span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-4">PI</span><span class="hl-1"> / </span><span class="hl-11">4</span><span class="hl-1">; </span><span class="hl-8">// 旋转 45 度</span><br/><br/><span class="hl-8">// 更新矩阵，确保 .matrix 属性是最新的</span><br/><span class="hl-6">clipperMesh</span><span class="hl-1">.</span><span class="hl-5">updateMatrix</span><span class="hl-1">();</span><br/><br/><span class="hl-8">// (可选) 将辅助 Mesh 加入场景以便调试看到范围</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">clipperMesh</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 3. 应用裁切参数</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-6">clippers</span><span class="hl-1"> = [</span><br/><span class="hl-1">  {</span><br/><span class="hl-1">    </span><span class="hl-6">clippingBoxMatrix:</span><span class="hl-1"> </span><span class="hl-6">clipperMesh</span><span class="hl-1">.</span><span class="hl-6">matrix</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-8">// floorIndex: 0 // 可选：仅裁切第 0 层</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">];</span><br/><br/><span class="hl-8">// 4. 触发重绘</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">needsRender</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="动态更新-dynamic-update" class="tsd-anchor-link">动态更新 (Dynamic Update)<a href="#动态更新-dynamic-update" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>

package/docs/documents/features_coordinate-system.html

@@ -113,7 +113,7 @@
 <h2 id="examples" class="tsd-anchor-link">Examples<a href="#examples" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <h3 id="坐标转换-coordinate-transformation" class="tsd-anchor-link">坐标转换 (Coordinate Transformation)<a href="#坐标转换-coordinate-transformation" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <p>推荐在与后端或算法交互时，将 Local 坐标转换为 ENU 坐标。</p>
-<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;three&#39;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">ViewLayer</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 假设已加载 ViewLayer</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">viewLayer</span><span class="hl-1">: </span><span class="hl-7">ViewLayer</span><span class="hl-1"> = ...;</span><br/><br/><span class="hl-8">// 1. 获取场景中某点的坐标 (Local Y-up)</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">localPosition</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector3</span><span class="hl-1">(</span><span class="hl-11">10</span><span class="hl-1">, </span><span class="hl-11">20</span><span class="hl-1">, </span><span class="hl-11">30</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 2. 转换为 ENU 坐标 (Z-up) 用于传输给后端/算法</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">enuPosition</span><span class="hl-1"> = </span><span class="hl-6">viewLayer</span><span class="hl-1">.</span><span class="hl-5">localToEnu</span><span class="hl-1">(</span><span class="hl-6">localPosition</span><span class="hl-1">.</span><span class="hl-5">clone</span><span class="hl-1">());</span><br/><br/><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">`Local: </span><span class="hl-3">${</span><span class="hl-6">localPosition</span><span class="hl-12">.</span><span class="hl-5">toArray</span><span class="hl-12">()</span><span class="hl-3">}</span><span class="hl-9">`</span><span class="hl-1">); </span><span class="hl-8">// [x, y, z] (y-up)</span><br/><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">`ENU: </span><span class="hl-3">${</span><span class="hl-6">enuPosition</span><span class="hl-12">.</span><span class="hl-5">toArray</span><span class="hl-12">()</span><span class="hl-3">}</span><span class="hl-9">`</span><span class="hl-1">);     </span><span class="hl-8">// [x, y, z] (z-up)</span><br/><br/><span class="hl-8">// 3. 将 ECEF 坐标转换为 Local 坐标用于显示</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">ecefPosition</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector3</span><span class="hl-1">( ... );</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">displayPosition</span><span class="hl-1"> = </span><span class="hl-6">viewLayer</span><span class="hl-1">.</span><span class="hl-5">ecefToLocal</span><span class="hl-1">(</span><span class="hl-6">ecefPosition</span><span class="hl-1">.</span><span class="hl-5">clone</span><span class="hl-1">());</span>
+<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;three&#39;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">ViewLayer</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five-webgpu&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 假设已加载 ViewLayer</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">viewLayer</span><span class="hl-1">: </span><span class="hl-7">ViewLayer</span><span class="hl-1"> = ...;</span><br/><br/><span class="hl-8">// 1. 获取场景中某点的坐标 (Local Y-up)</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">localPosition</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector3</span><span class="hl-1">(</span><span class="hl-11">10</span><span class="hl-1">, </span><span class="hl-11">20</span><span class="hl-1">, </span><span class="hl-11">30</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 2. 转换为 ENU 坐标 (Z-up) 用于传输给后端/算法</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">enuPosition</span><span class="hl-1"> = </span><span class="hl-6">viewLayer</span><span class="hl-1">.</span><span class="hl-5">localToEnu</span><span class="hl-1">(</span><span class="hl-6">localPosition</span><span class="hl-1">.</span><span class="hl-5">clone</span><span class="hl-1">());</span><br/><br/><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">`Local: </span><span class="hl-3">${</span><span class="hl-6">localPosition</span><span class="hl-12">.</span><span class="hl-5">toArray</span><span class="hl-12">()</span><span class="hl-3">}</span><span class="hl-9">`</span><span class="hl-1">); </span><span class="hl-8">// [x, y, z] (y-up)</span><br/><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">`ENU: </span><span class="hl-3">${</span><span class="hl-6">enuPosition</span><span class="hl-12">.</span><span class="hl-5">toArray</span><span class="hl-12">()</span><span class="hl-3">}</span><span class="hl-9">`</span><span class="hl-1">);     </span><span class="hl-8">// [x, y, z] (z-up)</span><br/><br/><span class="hl-8">// 3. 将 ECEF 坐标转换为 Local 坐标用于显示</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">ecefPosition</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector3</span><span class="hl-1">( ... );</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">displayPosition</span><span class="hl-1"> = </span><span class="hl-6">viewLayer</span><span class="hl-1">.</span><span class="hl-5">ecefToLocal</span><span class="hl-1">(</span><span class="hl-6">ecefPosition</span><span class="hl-1">.</span><span class="hl-5">clone</span><span class="hl-1">());</span>
 </code><button type="button">Copy</button></pre>
 
 <h2 id="related" class="tsd-anchor-link">Related<a href="#related" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>

package/docs/documents/features_event.html

@@ -53,7 +53,6 @@
 <ul>
 <li><code>pano.arrived</code>: 成功到达新点位（移动动画结束）。</li>
 <li><code>pano.moving</code>: 正在移动到新点位（动画进行中）。</li>
-<li><code>pano.willChange</code>: 即将发生点位变更（旧版兼容）。</li>
 <li><code>pano.error</code>: 点位加载或移动出错。</li>
 </ul>
 <h3 id="state-events-状态变更" class="tsd-anchor-link">State Events (状态变更)<a href="#state-events-状态变更" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
@@ -80,7 +79,7 @@
 <h2 id="examples" class="tsd-anchor-link">Examples<a href="#examples" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <h3 id="快速上手-quick-example" class="tsd-anchor-link">快速上手 (Quick Example)<a href="#快速上手-quick-example" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <p>监听点击事件并打印日志。</p>
-<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">();</span><br/><br/><span class="hl-8">// 监听点击事件</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;gesture.tap&quot;</span><span class="hl-1">, (</span><span class="hl-6">pose</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&quot;User tapped at:&quot;</span><span class="hl-1">, </span><span class="hl-6">pose</span><span class="hl-1">);</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// 监听点位变更完成</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;pano.arrived&quot;</span><span class="hl-1">, (</span><span class="hl-6">index</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&quot;Arrived at pano index:&quot;</span><span class="hl-1">, </span><span class="hl-6">index</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
+<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five-webgpu&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">();</span><br/><br/><span class="hl-8">// 监听点击事件</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;gesture.tap&quot;</span><span class="hl-1">, (</span><span class="hl-6">pose</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&quot;User tapped at:&quot;</span><span class="hl-1">, </span><span class="hl-6">pose</span><span class="hl-1">);</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// 监听点位变更完成</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;pano.arrived&quot;</span><span class="hl-1">, (</span><span class="hl-6">index</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&quot;Arrived at pano index:&quot;</span><span class="hl-1">, </span><span class="hl-6">index</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="进阶用法-advanced-usage" class="tsd-anchor-link">进阶用法 (Advanced Usage)<a href="#进阶用法-advanced-usage" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>

package/docs/documents/features_five.html

@@ -1,6 +1,6 @@
 <!DOCTYPE html><html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>features/five | 如视 Five SDK</title><meta name="description" content="Documentation for 如视 Five SDK"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script><script async src="../assets/hierarchy.js" id="tsd-hierarchy-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="../index.html" class="title">如视 Five SDK</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="" aria-current="page">features/five</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="five-five-核心类" class="tsd-anchor-link">Five (Five 核心类)<a href="#five-five-核心类" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h1>
 <ul>
-<li><strong>Summary</strong>: Five 是 @realsee/five 的核心类，负责 3D 场景的渲染、资源加载、用户交互和状态管理。</li>
+<li><strong>Summary</strong>: Five 是 @realsee/five-webgpu 的核心类，负责 3D 场景的渲染、资源加载、用户交互和状态管理。</li>
 <li><strong>Schema</strong>: FiveInitArgs 初始化参数接口。</li>
 <li><strong>Concepts</strong>: Instance Management, Rendering Loop, Resource Loading, State Sync.</li>
 <li><strong>Configuration</strong>: Five 初始化参数详解。</li>
@@ -12,7 +12,7 @@
 <p><strong>Definition</strong>: <a href="../../five/application/fiveInitArgs.d.ts">FiveInitArgs</a></p>
 </blockquote>
 <p><code>new Five(args)</code> 的初始化参数对象。</p>
-<pre><code class="typescript"><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">FiveInitArgs</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-8">/** 外部传入的渲染器 (如果传入，部分渲染配置将失效) */</span><br/><span class="hl-1">  </span><span class="hl-6">renderer</span><span class="hl-1">?: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">WebGLRenderer</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/**</span><br/><span class="hl-8">   * 屏幕渲染区域 { left, bottom, width, height }</span><br/><span class="hl-8">   * 必须配合外部 renderer 使用</span><br/><span class="hl-8">   */</span><br/><span class="hl-1">  </span><span class="hl-6">viewport</span><span class="hl-1">?: </span><span class="hl-7">Viewport</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 背景颜色 (默认 0x181A1C) */</span><br/><span class="hl-1">  </span><span class="hl-6">backgroundColor</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1"> | </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Color</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 背景透明度 (0-1, 默认 1) */</span><br/><span class="hl-1">  </span><span class="hl-6">backgroundAlpha</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 是否开启抗锯齿 (默认 false) */</span><br/><span class="hl-1">  </span><span class="hl-6">antialias</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 全景图配置 (见 image-options.md) */</span><br/><span class="hl-1">  </span><span class="hl-6">imageOptions</span><span class="hl-1">?: </span><span class="hl-7">ImageOptions</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 贴图配置 (见 image-options.md) */</span><br/><span class="hl-1">  </span><span class="hl-6">textureOptions</span><span class="hl-1">?: </span><span class="hl-7">TextureOptions</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 是否按需渲染 (默认 true, 推荐开启以节省性能) */</span><br/><span class="hl-1">  </span><span class="hl-6">onlyRenderIfNeeds</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 模式切换动画时长 (ms, 默认 1000) */</span><br/><span class="hl-1">  </span><span class="hl-6">modeChangeDuration</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 是否支持滚轮缩放 (默认 true) */</span><br/><span class="hl-1">  </span><span class="hl-6">enableWheel</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 插件列表 */</span><br/><span class="hl-1">  </span><span class="hl-6">plugins</span><span class="hl-1">?: </span><span class="hl-7">FivePlugin</span><span class="hl-1">[];</span><br/><span class="hl-1">  </span><span class="hl-8">/** 是否显示 Powered by Realsee */</span><br/><span class="hl-1">  </span><span class="hl-6">poweredByRealsee</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">}</span>
+<pre><code class="typescript"><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">FiveInitArgs</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-8">/** 外部传入的渲染器 (如果传入，部分渲染配置将失效) */</span><br/><span class="hl-1">  </span><span class="hl-6">renderer</span><span class="hl-1">?: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">WebGPURenderer</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/**</span><br/><span class="hl-8">   * 屏幕渲染区域 { left, bottom, width, height }</span><br/><span class="hl-8">   * 必须配合外部 renderer 使用</span><br/><span class="hl-8">   */</span><br/><span class="hl-1">  </span><span class="hl-6">viewport</span><span class="hl-1">?: </span><span class="hl-7">Viewport</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 背景颜色 (默认 0x181A1C) */</span><br/><span class="hl-1">  </span><span class="hl-6">backgroundColor</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1"> | </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Color</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 背景透明度 (0-1, 默认 1) */</span><br/><span class="hl-1">  </span><span class="hl-6">backgroundAlpha</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 是否开启抗锯齿 (默认 false) */</span><br/><span class="hl-1">  </span><span class="hl-6">antialias</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 全景图配置 (见 image-options.md) */</span><br/><span class="hl-1">  </span><span class="hl-6">imageOptions</span><span class="hl-1">?: </span><span class="hl-7">ImageOptions</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 贴图配置 (见 image-options.md) */</span><br/><span class="hl-1">  </span><span class="hl-6">textureOptions</span><span class="hl-1">?: </span><span class="hl-7">TextureOptions</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 是否按需渲染 (默认 true, 推荐开启以节省性能) */</span><br/><span class="hl-1">  </span><span class="hl-6">onlyRenderIfNeeds</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 模式切换动画时长 (ms, 默认 800) */</span><br/><span class="hl-1">  </span><span class="hl-6">modeChangeDuration</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 是否支持滚轮缩放 (默认 true) */</span><br/><span class="hl-1">  </span><span class="hl-6">enableWheel</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 插件列表 */</span><br/><span class="hl-1">  </span><span class="hl-6">plugins</span><span class="hl-1">?: </span><span class="hl-7">FivePlugin</span><span class="hl-1">[];</span><br/><span class="hl-1">  </span><span class="hl-8">/** 是否显示 Powered by Realsee */</span><br/><span class="hl-1">  </span><span class="hl-6">poweredByRealsee</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/**</span><br/><span class="hl-8">   * 强制使用 WebGL2 回落后端（默认 false）</span><br/><span class="hl-8">   * 进入 XRPanorama（WebXR 头显全景）的前置条件。</span><br/><span class="hl-8">   * 只在构造期生效，后端无法在运行时切换，设备检测必须在 new Five() 之前完成。</span><br/><span class="hl-8">   * 详见下方《forceWebGL 与 XR 回落后端》。</span><br/><span class="hl-8">   */</span><br/><span class="hl-1">  </span><span class="hl-6">forceWebGL</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/**</span><br/><span class="hl-8">   * </span><span class="hl-3">@deprecated</span><span class="hl-8"> 在 five-webgpu 中未接线、无效。需要 WebGL2 后端请使用 `forceWebGL`。</span><br/><span class="hl-8">   */</span><br/><span class="hl-1">  </span><span class="hl-6">webgl2</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 
 <h2 id="concepts" class="tsd-anchor-link">Concepts<a href="#concepts" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
@@ -25,7 +25,7 @@
 <h3 id="rendering-loop-渲染循环" class="tsd-anchor-link">Rendering Loop (渲染循环)<a href="#rendering-loop-渲染循环" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <p>Five 内部维护了一个 <code>requestAnimationFrame</code> 循环。</p>
 <ul>
-<li><strong>按需渲染</strong>: 默认开启 <code>onlyRenderIfNeeds</code>，仅在画面发生变化（如视角移动、数据加载）时才触发 WebGL 绘制，大幅降低能耗。</li>
+<li><strong>按需渲染</strong>: 默认开启 <code>onlyRenderIfNeeds</code>，仅在画面发生变化（如视角移动、数据加载）时才触发渲染，大幅降低能耗。</li>
 <li><strong>手动触发</strong>: 可以通过 <code>five.needsRender = true</code> 强制下一帧进行渲染。</li>
 </ul>
 <h3 id="resource-loading-资源加载" class="tsd-anchor-link">Resource Loading (资源加载)<a href="#resource-loading-资源加载" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
@@ -72,7 +72,7 @@
 <tr>
 <td style="text-align:left"><code>modeChangeDuration</code></td>
 <td style="text-align:left"><code>number</code></td>
-<td style="text-align:left"><code>1000</code></td>
+<td style="text-align:left"><code>800</code></td>
 <td style="text-align:left">模式切换动画时长 (ms)</td>
 </tr>
 <tr>
@@ -81,17 +81,59 @@
 <td style="text-align:left"><code>true</code></td>
 <td style="text-align:left">是否支持滚轮缩放</td>
 </tr>
+<tr>
+<td style="text-align:left"><code>forceWebGL</code></td>
+<td style="text-align:left"><code>boolean</code></td>
+<td style="text-align:left"><code>false</code></td>
+<td style="text-align:left">强制使用 WebGL2 回落后端，进入 <code>XRPanorama</code> 的前置条件，详见下文</td>
+</tr>
+<tr>
+<td style="text-align:left"><code>webgl2</code></td>
+<td style="text-align:left"><code>boolean</code></td>
+<td style="text-align:left">—</td>
+<td style="text-align:left"><strong>已废弃</strong>，在 five-webgpu 中未接线。需要 WebGL2 请用 <code>forceWebGL</code></td>
+</tr>
 </tbody>
 </table>
+<h3 id="forcewebgl-与-xr-回落后端" class="tsd-anchor-link">forceWebGL 与 XR 回落后端<a href="#forcewebgl-与-xr-回落后端" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
+<p><code>forceWebGL</code> 让 five-webgpu 强制走 WebGL2 回落后端，而不是默认的 WebGPU 后端。它存在的唯一原因是 <strong>进入 <code>XRPanorama</code>（WebXR 头显全景）模式</strong>：<code>three</code> 的 WebGPU 后端目前不支持 WebXR，而 WebGL2 后端下 <code>renderer.xr</code> 完整可用。</p>
+<p><strong>语义与使用约束</strong></p>
+<ul>
+<li><strong>语义</strong>：<code>forceWebGL: true</code> 时，内部 <code>WebGPURenderer</code> 以 <code>{ forceWebGL: true }</code> 构造，使用 <code>WebGLBackend</code> 而非 WebGPU。</li>
+<li><strong>必须在 <code>new Five()</code> 时决定</strong>：后端在 renderer 构造期定死，<strong>运行时无法切换</strong>。因此业务侧的「是否需要进入 XR」的设备检测必须发生在 <code>new Five()</code> 之前，不能等实例创建后再改。</li>
+<li><strong>与 <code>enableHDR</code> 互斥</strong>：当 <code>forceWebGL</code> 为 <code>true</code> 时 <code>enableHDR</code> 不生效（<code>five.enableHDR</code> 会被置为 <code>false</code>），因为 XR 的 projection layer 固定 <code>colorFormat: RGBA8</code>，HDR 没有落地路径。</li>
+<li><strong>传入外部 <code>renderer</code> 时不生效</strong>：如果通过 <code>renderer</code> 参数传入了外部渲染器，<code>forceWebGL</code> 不会对其生效，需由调用方自行在构造该 renderer 时设置 <code>forceWebGL</code>（与 <code>antialias</code> 等参数一致）。</li>
+<li><strong><code>webgl2</code> 已废弃</strong>：遗留的 <code>webgl2</code> 参数在 five-webgpu 中未接线、无任何效果；需要 WebGL2 后端请改用 <code>forceWebGL</code>。</li>
+</ul>
+<p><strong>能力降级限制</strong>（开启 <code>forceWebGL</code> 后不可规避）</p>
+<ol>
+<li><strong>XR 下没有后处理</strong>：<code>XRPanorama</code> 模式会整体旁路 <code>FiveRenderer</code> 的后处理链路（合成 / EffectComposer 全屏 pass 均不参与），滤镜、泛光等后处理在头显中不生效。</li>
+<li><strong>点云走 NodeMaterial 路径</strong>：<code>forceWebGL</code> 下点云不再走 WebGPU compute 光栅化，而是退回 NodeMaterial 渲染路径。</li>
+<li><strong>3DGS 走 CPU 排序，且 VR 中性能预期需放低</strong>：<code>forceWebGL</code> 下 3DGS 只能走 CPU 排序（<code>RASTER_CPU_SORT</code>）；在 XR 中还要叠加双眼渲染开销，务必对点数 / 显示做降级，不要期待与 WebGPU 后端相同的帧率。</li>
+</ol>
+<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five-webgpu&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 设备检测需在 new Five() 之前完成</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">needXR</span><span class="hl-1"> = </span><span class="hl-5">detectNeedXR</span><span class="hl-1">();</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-6">forceWebGL:</span><span class="hl-1"> </span><span class="hl-6">needXR</span><span class="hl-1">, </span><span class="hl-8">// 一旦创建就无法再切换后端</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">load</span><span class="hl-1">(</span><span class="hl-6">workData</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 进入 XR（需在用户手势回调中调用，会触发 WebXR 权限请求）</span><br/><span class="hl-6">button</span><span class="hl-1">.</span><span class="hl-5">addEventListener</span><span class="hl-1">(</span><span class="hl-9">&quot;click&quot;</span><span class="hl-1">, () </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">changeMode</span><span class="hl-1">(</span><span class="hl-9">&quot;XRPanorama&quot;</span><span class="hl-1">).</span><span class="hl-5">catch</span><span class="hl-1">((</span><span class="hl-6">error</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-8">// 后端非 WebGL2 或浏览器不支持 WebXR 时，这里会收到含 forceWebGL 字样的中文错误</span><br/><span class="hl-1">    </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">error</span><span class="hl-1">(</span><span class="hl-6">error</span><span class="hl-1">);</span><br/><span class="hl-1">  });</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// 用户摘下头显 / 退出 XR 时切回普通全景</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;xr.session.end&quot;</span><span class="hl-1">, () </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">changeMode</span><span class="hl-1">(</span><span class="hl-9">&quot;Panorama&quot;</span><span class="hl-1">));</span>
+</code><button type="button">Copy</button></pre>
+
+<p>也可以直接使用内置的 <code>XRButton</code>，样式与 API 同原始 five 保持一致（<code>XRButton.createButton(onClickHook)</code>）：</p>
+<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1">, </span><span class="hl-6">XRButton</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five-webgpu&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">button</span><span class="hl-1"> = </span><span class="hl-6">XRButton</span><span class="hl-1">.</span><span class="hl-5">createButton</span><span class="hl-1">(() </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">changeMode</span><span class="hl-1">(</span><span class="hl-9">&quot;XRPanorama&quot;</span><span class="hl-1">));</span><br/><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-6">body</span><span class="hl-1">.</span><span class="hl-5">appendChild</span><span class="hl-1">(</span><span class="hl-6">button</span><span class="hl-1">);</span>
+</code><button type="button">Copy</button></pre>
+
+<ul>
+<li>浏览器没有 <code>navigator.xr</code> 时显示 <code>WEBXR NOT AVAILABLE</code>（非 HTTPS 时显示 <code>WEBXR NEEDS HTTPS</code>），不支持 <code>immersive-vr</code> 时显示 <code>VR NOT SUPPORTED</code>。</li>
+<li>回调返回 Promise 时，<code>XRButton</code> 会接住 reject。若失败原因是没有开启 <code>forceWebGL</code>（后端是 WebGPU），按钮文案会临时变为「需降级到 WebGL2」，3 秒后恢复。其他失败原因不改变按钮，错误通过 <code>five.on(&quot;error&quot;)</code> 上报。</li>
+</ul>
+<blockquote>
+<p>更多模式说明（含 <code>XRPanorama</code> 与 <code>VRPanorama</code> 的区别）见 <a href="features_mode.html">mode.md</a>，可运行示例参见 <code>examples/xr</code>。</p>
+</blockquote>
 <h2 id="examples" class="tsd-anchor-link">Examples<a href="#examples" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <h3 id="快速上手-quick-example" class="tsd-anchor-link">快速上手 (Quick Example)<a href="#快速上手-quick-example" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <p>创建一个全屏的 Five 实例并加载数据。</p>
-<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1">, </span><span class="hl-6">parseWork</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 1. 初始化实例</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-6">imageOptions:</span><span class="hl-1"> { </span><span class="hl-6">size:</span><span class="hl-1"> </span><span class="hl-11">512</span><span class="hl-1"> }, </span><span class="hl-8">// 初始加载小图</span><br/><span class="hl-1">  </span><span class="hl-6">onlyRenderIfNeeds:</span><span class="hl-1"> </span><span class="hl-3">true</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// 2. 挂载到 DOM</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">appendTo</span><span class="hl-1">(</span><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-5">getElementById</span><span class="hl-1">(</span><span class="hl-9">&quot;app&quot;</span><span class="hl-1">));</span><br/><br/><span class="hl-8">// 3. 加载数据</span><br/><span class="hl-8">// workData 通常来自服务端 API</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">load</span><span class="hl-1">(</span><span class="hl-6">workData</span><span class="hl-1">);</span>
+<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1">, </span><span class="hl-6">parseWork</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five-webgpu&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 1. 初始化实例</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-6">imageOptions:</span><span class="hl-1"> { </span><span class="hl-6">size:</span><span class="hl-1"> </span><span class="hl-11">512</span><span class="hl-1"> }, </span><span class="hl-8">// 初始加载小图</span><br/><span class="hl-1">  </span><span class="hl-6">onlyRenderIfNeeds:</span><span class="hl-1"> </span><span class="hl-3">true</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// 2. 挂载到 DOM</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">appendTo</span><span class="hl-1">(</span><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-5">getElementById</span><span class="hl-1">(</span><span class="hl-9">&quot;app&quot;</span><span class="hl-1">));</span><br/><br/><span class="hl-8">// 3. 加载数据</span><br/><span class="hl-8">// workData 通常来自服务端 API</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">load</span><span class="hl-1">(</span><span class="hl-6">workData</span><span class="hl-1">);</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="进阶用法：自定义渲染器与视口" class="tsd-anchor-link">进阶用法：自定义渲染器与视口<a href="#进阶用法：自定义渲染器与视口" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <p>使用外部渲染器并指定视口区域（例如用于分屏渲染）。</p>
-<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;three/webgpu&quot;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">renderer</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">WebGLRenderer</span><span class="hl-1">();</span><br/><span class="hl-6">renderer</span><span class="hl-1">.</span><span class="hl-5">setSize</span><span class="hl-1">(</span><span class="hl-6">window</span><span class="hl-1">.</span><span class="hl-6">innerWidth</span><span class="hl-1">, </span><span class="hl-6">window</span><span class="hl-1">.</span><span class="hl-6">innerHeight</span><span class="hl-1">);</span><br/><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-6">body</span><span class="hl-1">.</span><span class="hl-5">appendChild</span><span class="hl-1">(</span><span class="hl-6">renderer</span><span class="hl-1">.</span><span class="hl-6">domElement</span><span class="hl-1">);</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-6">renderer:</span><span class="hl-1"> </span><span class="hl-6">renderer</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">viewport:</span><span class="hl-1"> { </span><span class="hl-6">left:</span><span class="hl-1"> </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-6">bottom:</span><span class="hl-1"> </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-6">width:</span><span class="hl-1"> </span><span class="hl-11">0.5</span><span class="hl-1">, </span><span class="hl-6">height:</span><span class="hl-1"> </span><span class="hl-11">1</span><span class="hl-1"> } </span><span class="hl-8">// 仅占用左半屏</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">load</span><span class="hl-1">(</span><span class="hl-6">workData</span><span class="hl-1">);</span>
+<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;three/webgpu&quot;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five-webgpu&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">renderer</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">WebGPURenderer</span><span class="hl-1">();</span><br/><span class="hl-6">renderer</span><span class="hl-1">.</span><span class="hl-5">setSize</span><span class="hl-1">(</span><span class="hl-6">window</span><span class="hl-1">.</span><span class="hl-6">innerWidth</span><span class="hl-1">, </span><span class="hl-6">window</span><span class="hl-1">.</span><span class="hl-6">innerHeight</span><span class="hl-1">);</span><br/><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-6">body</span><span class="hl-1">.</span><span class="hl-5">appendChild</span><span class="hl-1">(</span><span class="hl-6">renderer</span><span class="hl-1">.</span><span class="hl-6">domElement</span><span class="hl-1">);</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-6">renderer:</span><span class="hl-1"> </span><span class="hl-6">renderer</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">viewport:</span><span class="hl-1"> { </span><span class="hl-6">left:</span><span class="hl-1"> </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-6">bottom:</span><span class="hl-1"> </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-6">width:</span><span class="hl-1"> </span><span class="hl-11">0.5</span><span class="hl-1">, </span><span class="hl-6">height:</span><span class="hl-1"> </span><span class="hl-11">1</span><span class="hl-1"> } </span><span class="hl-8">// 仅占用左半屏</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">load</span><span class="hl-1">(</span><span class="hl-6">workData</span><span class="hl-1">);</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="进阶用法：自定义相机动画" class="tsd-anchor-link">进阶用法：自定义相机动画<a href="#进阶用法：自定义相机动画" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
@@ -109,8 +151,8 @@
 <h3 id="实例方法-instance-methods" class="tsd-anchor-link">实例方法 (Instance Methods)<a href="#实例方法-instance-methods" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <ul>
 <li><strong><code>appendTo(element: HTMLElement)</code></strong>: 将 canvas 挂载到指定 DOM 元素。</li>
-<li><strong><code>load(work: Work, state?: State, duration?: number)</code></strong>: 加载场景数据。详见 <a href="features_work.html">work.md</a>。</li>
-<li><strong><code>dispose()</code></strong>: 销毁实例，释放 WebGL 上下文与内存。</li>
+<li><strong><code>load(inputWork, state?: &quot;inherit&quot; | &quot;initial&quot; | Partial&lt;State&gt;, options?: number | FiveLoadOptions, userAction?: boolean)</code></strong>: 加载场景数据。详见 <a href="features_work.html">work.md</a>。</li>
+<li><strong><code>dispose()</code></strong>: 销毁实例并释放相关渲染资源。</li>
 <li><strong><code>updateCamera(pose: Partial&lt;Pose&gt;, duration: number, userAction?: boolean)</code></strong>: 移动相机（不触发点位移动）。移动相机的视角或位置，不会改变当前所在的 PanoIndex。如果动画中途被打断，Promise 会被 reject。</li>
 <li><strong><code>updateCameraWithKeyframes(keyframes: { progress: number; value: Pose; key?: string }[], duration: number, userAction?: boolean)</code></strong>: 通过关键帧动画移动相机。</li>
 <li><strong><code>refresh()</code></strong>: 强制刷新画布尺寸。通常在窗口 resize 时调用，Five 会自动监听 resize，但在某些布局变化场景下可能需要手动调用。</li>
@@ -127,7 +169,7 @@
 </li>
 </ul>
 </li>
-<li><strong><code>setState(state: Partial&lt;State&gt;, options?: ChangeStateOptions)</code></strong>: 变更当前状态（如点位、视角）。详见 <a href="features_state.html">state.md</a>。</li>
+<li><strong><code>setState(state: Partial&lt;State&gt;, immediately?: boolean, userAction?: boolean)</code></strong>: 变更当前状态（如点位、视角）。详见 <a href="features_state.html">state.md</a>。</li>
 <li><strong><code>on(event, callback)</code> / <code>off(event, callback)</code></strong>: 事件监听。详见 <a href="features_event.html">event.md</a>。</li>
 </ul>
 <h2 id="related" class="tsd-anchor-link">Related<a href="#related" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
@@ -141,7 +183,7 @@
 <li><a href="features_parameter.html">parameter.md</a>: 其他核心参数。</li>
 </ul>
 <hr>
-<pre><code class="yaml"><span class="hl-0">tags</span><span class="hl-1">: [</span><span class="hl-2">five</span><span class="hl-1">, </span><span class="hl-2">initialization</span><span class="hl-1">, </span><span class="hl-2">core</span><span class="hl-1">, </span><span class="hl-2">instance</span><span class="hl-1">, </span><span class="hl-2">lifecycle</span><span class="hl-1">]</span>
+<pre><code class="yaml"><span class="hl-0">tags</span><span class="hl-1">: [</span><span class="hl-2">five</span><span class="hl-1">, </span><span class="hl-2">initialization</span><span class="hl-1">, </span><span class="hl-2">core</span><span class="hl-1">, </span><span class="hl-2">instance</span><span class="hl-1">, </span><span class="hl-2">lifecycle</span><span class="hl-1">, </span><span class="hl-2">forceWebGL</span><span class="hl-1">, </span><span class="hl-2">webgl2</span><span class="hl-1">, </span><span class="hl-2">xr</span><span class="hl-1">, </span><span class="hl-2">webxr</span><span class="hl-1">]</span>
 </code><button type="button">Copy</button></pre>
 
-</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#five-five-核心类"><span>Five (<wbr/>Five 核心类)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><ul><li><a href="#fiveinitargs"><span>Five<wbr/>Init<wbr/>Args</span></a></li></ul></li><li><a href="#concepts"><span>Concepts</span></a></li><li><ul><li><a href="#instance-management-实例管理"><span>Instance <wbr/>Management (实例管理)</span></a></li><li><a href="#rendering-loop-渲染循环"><span>Rendering <wbr/>Loop (渲染循环)</span></a></li><li><a href="#resource-loading-资源加载"><span>Resource <wbr/>Loading (资源加载)</span></a></li></ul></li><li><a href="#configuration"><span>Configuration</span></a></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#快速上手-quick-example"><span>快速上手 (<wbr/>Quick <wbr/>Example)</span></a></li><li><a href="#进阶用法：自定义渲染器与视口"><span>进阶用法：自定义渲染器与视口</span></a></li><li><a href="#进阶用法：自定义相机动画"><span>进阶用法：自定义相机动画</span></a></li><li><a href="#实例属性-instance-properties"><span>实例属性 (<wbr/>Instance <wbr/>Properties)</span></a></li><li><a href="#实例方法-instance-methods"><span>实例方法 (<wbr/>Instance <wbr/>Methods)</span></a></li></ul></li><li><a href="#related"><span>Related</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">如视 Five SDK</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>
+</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#five-five-核心类"><span>Five (<wbr/>Five 核心类)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><ul><li><a href="#fiveinitargs"><span>Five<wbr/>Init<wbr/>Args</span></a></li></ul></li><li><a href="#concepts"><span>Concepts</span></a></li><li><ul><li><a href="#instance-management-实例管理"><span>Instance <wbr/>Management (实例管理)</span></a></li><li><a href="#rendering-loop-渲染循环"><span>Rendering <wbr/>Loop (渲染循环)</span></a></li><li><a href="#resource-loading-资源加载"><span>Resource <wbr/>Loading (资源加载)</span></a></li></ul></li><li><a href="#configuration"><span>Configuration</span></a></li><li><ul><li><a href="#forcewebgl-与-xr-回落后端"><span>force<wbr/>Web<wbr/>GL 与 <wbr/>XR 回落后端</span></a></li></ul></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#快速上手-quick-example"><span>快速上手 (<wbr/>Quick <wbr/>Example)</span></a></li><li><a href="#进阶用法：自定义渲染器与视口"><span>进阶用法：自定义渲染器与视口</span></a></li><li><a href="#进阶用法：自定义相机动画"><span>进阶用法：自定义相机动画</span></a></li><li><a href="#实例属性-instance-properties"><span>实例属性 (<wbr/>Instance <wbr/>Properties)</span></a></li><li><a href="#实例方法-instance-methods"><span>实例方法 (<wbr/>Instance <wbr/>Methods)</span></a></li></ul></li><li><a href="#related"><span>Related</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">如视 Five SDK</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>

package/docs/documents/features_gesture.html

@@ -10,13 +10,13 @@
 <p><strong>Definition</strong>: <a href="../../five/utils/event.d.ts">GestureEvent</a></p>
 </blockquote>
 <p>所有手势事件的回调参数均为 <code>GestureEvent</code> 类型：</p>
-<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">State</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five&quot;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;three/webgpu&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">GestureEvent</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">type</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">;             </span><span class="hl-8">// 事件类型，如 &quot;gesture.tap&quot;</span><br/><span class="hl-1">  </span><span class="hl-6">timeStamp</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">;        </span><span class="hl-8">// 时间戳</span><br/><span class="hl-1">  </span><span class="hl-6">target</span><span class="hl-1">: </span><span class="hl-7">EventTarget</span><span class="hl-1"> | </span><span class="hl-7">null</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-6">pointerType</span><span class="hl-1">: </span><span class="hl-9">&#39;touch&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;pen&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;mouse&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;kinect&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 手势中心点信息</span><br/><span class="hl-1">  </span><span class="hl-6">center</span><span class="hl-1">: {</span><br/><span class="hl-1">    </span><span class="hl-6">x</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">;              </span><span class="hl-8">// 屏幕 X 坐标</span><br/><span class="hl-1">    </span><span class="hl-6">y</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">;              </span><span class="hl-8">// 屏幕 Y 坐标</span><br/><span class="hl-1">    </span><span class="hl-6">raycaster</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Raycaster</span><span class="hl-1">; </span><span class="hl-8">// 从相机发出的射线（已包含坐标变换）</span><br/><span class="hl-1">  };</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 当前相机状态</span><br/><span class="hl-1">  </span><span class="hl-6">state</span><span class="hl-1">: </span><span class="hl-7">State</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 是否是用户触发（区别于代码调用）</span><br/><span class="hl-1">  </span><span class="hl-6">userAction</span><span class="hl-1">: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 阻止默认行为</span><br/><span class="hl-1">  </span><span class="hl-5">preventDefault</span><span class="hl-1">(): </span><span class="hl-7">void</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-6">defaultPrevented</span><span class="hl-1">: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">}</span>
+<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">State</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five-webgpu&quot;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;three/webgpu&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">GestureEvent</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">type</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">;             </span><span class="hl-8">// 事件类型，如 &quot;gesture.tap&quot;</span><br/><span class="hl-1">  </span><span class="hl-6">timeStamp</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">;        </span><span class="hl-8">// 时间戳</span><br/><span class="hl-1">  </span><span class="hl-6">target</span><span class="hl-1">: </span><span class="hl-7">EventTarget</span><span class="hl-1"> | </span><span class="hl-7">null</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-6">pointerType</span><span class="hl-1">: </span><span class="hl-9">&#39;touch&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;pen&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;mouse&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;kinect&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 手势中心点信息</span><br/><span class="hl-1">  </span><span class="hl-6">center</span><span class="hl-1">: {</span><br/><span class="hl-1">    </span><span class="hl-6">x</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">;              </span><span class="hl-8">// 屏幕 X 坐标</span><br/><span class="hl-1">    </span><span class="hl-6">y</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">;              </span><span class="hl-8">// 屏幕 Y 坐标</span><br/><span class="hl-1">    </span><span class="hl-6">raycaster</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Raycaster</span><span class="hl-1">; </span><span class="hl-8">// 从相机发出的射线（已包含坐标变换）</span><br/><span class="hl-1">  };</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 当前相机状态</span><br/><span class="hl-1">  </span><span class="hl-6">state</span><span class="hl-1">: </span><span class="hl-7">State</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 是否是用户触发（区别于代码调用）</span><br/><span class="hl-1">  </span><span class="hl-6">userAction</span><span class="hl-1">: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 阻止默认行为</span><br/><span class="hl-1">  </span><span class="hl-5">preventDefault</span><span class="hl-1">(): </span><span class="hl-7">void</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-6">defaultPrevented</span><span class="hl-1">: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 
 <h2 id="concepts" class="tsd-anchor-link">Concepts<a href="#concepts" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <p>Five 的手势系统基于 Hammer.js 封装，主要包含以下几种手势：</p>
 <ul>
-<li><strong>gesture.create</strong>: 所有事件创建时。</li>
+<li><strong>gesture.fire</strong>: 任意事件被触发。</li>
 <li><strong>gesture.pan</strong>: 拖拽/平移。</li>
 <li><strong>gesture.pinch</strong>: 双指缩放。</li>
 <li><strong>gesture.tap</strong>: 点击。</li>
@@ -84,7 +84,7 @@
 
 <h3 id="场景交互：点击添加标签球-add-label-on-click" class="tsd-anchor-link">场景交互：点击添加标签球 (Add Label on Click)<a href="#场景交互：点击添加标签球-add-label-on-click" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <p>这个示例展示了如何通过点击事件在场景中添加一个红色的球体，并阻止 Five 默认的点位移动行为。</p>
-<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;three/webgpu&quot;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">();</span><br/><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;gesture.tap&quot;</span><span class="hl-1">, (</span><span class="hl-6">event</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-8">// 1. 阻止默认行为（防止点击地面时 Five 自动走点或切换模式）</span><br/><span class="hl-1">  </span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-5">preventDefault</span><span class="hl-1">();</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 2. 获取射线</span><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">raycaster</span><span class="hl-1"> = </span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-6">center</span><span class="hl-1">.</span><span class="hl-6">raycaster</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 3. 检测与模型的碰撞</span><br/><span class="hl-1">  </span><span class="hl-8">// five.model.intersectRaycaster 是 Five 提供的便捷方法，会自动检测所有可见模型</span><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">intersects</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-5">intersectRaycaster</span><span class="hl-1">(</span><span class="hl-6">raycaster</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">intersects</span><span class="hl-1">.</span><span class="hl-6">length</span><span class="hl-1"> &gt; </span><span class="hl-11">0</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">intersect</span><span class="hl-1"> = </span><span class="hl-6">intersects</span><span class="hl-1">[</span><span class="hl-11">0</span><span class="hl-1">];</span><br/><span class="hl-1">    </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">point</span><span class="hl-1"> = </span><span class="hl-6">intersect</span><span class="hl-1">.</span><span class="hl-6">point</span><span class="hl-1">; </span><span class="hl-8">// 碰撞点世界坐标</span><br/><br/><span class="hl-1">    </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&quot;点击到了模型，坐标:&quot;</span><span class="hl-1">, </span><span class="hl-6">point</span><span class="hl-1">);</span><br/><br/><span class="hl-1">    </span><span class="hl-8">// 4. 创建一个小球</span><br/><span class="hl-1">    </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">geometry</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">SphereGeometry</span><span class="hl-1">(</span><span class="hl-11">0.1</span><span class="hl-1">, </span><span class="hl-11">32</span><span class="hl-1">, </span><span class="hl-11">32</span><span class="hl-1">);</span><br/><span class="hl-1">    </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">material</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">MeshBasicMaterial</span><span class="hl-1">({ </span><span class="hl-6">color:</span><span class="hl-1"> </span><span class="hl-11">0xff0000</span><span class="hl-1"> });</span><br/><span class="hl-1">    </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">sphere</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Mesh</span><span class="hl-1">(</span><span class="hl-6">geometry</span><span class="hl-1">, </span><span class="hl-6">material</span><span class="hl-1">);</span><br/><br/><span class="hl-1">    </span><span class="hl-8">// 5. 设置位置并添加到场景</span><br/><span class="hl-1">    </span><span class="hl-6">sphere</span><span class="hl-1">.</span><span class="hl-6">position</span><span class="hl-1">.</span><span class="hl-5">copy</span><span class="hl-1">(</span><span class="hl-6">point</span><span class="hl-1">);</span><br/><span class="hl-1">    </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">sphere</span><span class="hl-1">);</span><br/><br/><span class="hl-1">    </span><span class="hl-8">// 强制刷新渲染，确保小球立即出现</span><br/><span class="hl-1">    </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">needsRender</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span><br/><span class="hl-1">  } </span><span class="hl-10">else</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&quot;未点击到任何模型&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">});</span>
+<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;three/webgpu&quot;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five-webgpu&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">();</span><br/><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;gesture.tap&quot;</span><span class="hl-1">, (</span><span class="hl-6">event</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-8">// 1. 阻止默认行为（防止点击地面时 Five 自动走点或切换模式）</span><br/><span class="hl-1">  </span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-5">preventDefault</span><span class="hl-1">();</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 2. 获取射线</span><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">raycaster</span><span class="hl-1"> = </span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-6">center</span><span class="hl-1">.</span><span class="hl-6">raycaster</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 3. 检测与模型的碰撞</span><br/><span class="hl-1">  </span><span class="hl-8">// five.model.intersectRaycaster 是 Five 提供的便捷方法，会自动检测所有可见模型</span><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">intersects</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-5">intersectRaycaster</span><span class="hl-1">(</span><span class="hl-6">raycaster</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">intersects</span><span class="hl-1">.</span><span class="hl-6">length</span><span class="hl-1"> &gt; </span><span class="hl-11">0</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">intersect</span><span class="hl-1"> = </span><span class="hl-6">intersects</span><span class="hl-1">[</span><span class="hl-11">0</span><span class="hl-1">];</span><br/><span class="hl-1">    </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">point</span><span class="hl-1"> = </span><span class="hl-6">intersect</span><span class="hl-1">.</span><span class="hl-6">point</span><span class="hl-1">; </span><span class="hl-8">// 碰撞点世界坐标</span><br/><br/><span class="hl-1">    </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&quot;点击到了模型，坐标:&quot;</span><span class="hl-1">, </span><span class="hl-6">point</span><span class="hl-1">);</span><br/><br/><span class="hl-1">    </span><span class="hl-8">// 4. 创建一个小球</span><br/><span class="hl-1">    </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">geometry</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">SphereGeometry</span><span class="hl-1">(</span><span class="hl-11">0.1</span><span class="hl-1">, </span><span class="hl-11">32</span><span class="hl-1">, </span><span class="hl-11">32</span><span class="hl-1">);</span><br/><span class="hl-1">    </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">material</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">MeshBasicMaterial</span><span class="hl-1">({ </span><span class="hl-6">color:</span><span class="hl-1"> </span><span class="hl-11">0xff0000</span><span class="hl-1"> });</span><br/><span class="hl-1">    </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">sphere</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Mesh</span><span class="hl-1">(</span><span class="hl-6">geometry</span><span class="hl-1">, </span><span class="hl-6">material</span><span class="hl-1">);</span><br/><br/><span class="hl-1">    </span><span class="hl-8">// 5. 设置位置并添加到场景</span><br/><span class="hl-1">    </span><span class="hl-6">sphere</span><span class="hl-1">.</span><span class="hl-6">position</span><span class="hl-1">.</span><span class="hl-5">copy</span><span class="hl-1">(</span><span class="hl-6">point</span><span class="hl-1">);</span><br/><span class="hl-1">    </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">sphere</span><span class="hl-1">);</span><br/><br/><span class="hl-1">    </span><span class="hl-8">// 强制刷新渲染，确保小球立即出现</span><br/><span class="hl-1">    </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">needsRender</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span><br/><span class="hl-1">  } </span><span class="hl-10">else</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&quot;未点击到任何模型&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="进阶用法：自定义双指缩放范围" class="tsd-anchor-link">进阶用法：自定义双指缩放范围<a href="#进阶用法：自定义双指缩放范围" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>