npm - @realsee/five - Versions diffs - 6.8.9 → 6.9.0-alpha.1 - Mend

@realsee/five 6.8.9 → 6.9.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (281) hide show

package/docs/documents/features_plugin.html CHANGED Viewed

@@ -11,7 +11,7 @@
 <p><strong>Definition</strong>: <a href="../../plugins/BasePlugin/index.d.ts">BasePlugin</a></p>
 </blockquote>
 <p><code>BasePlugin</code> 是一个命名空间，包含 <code>Controller</code> (抽象基类), <code>State</code> (状态接口), <code>EventMap</code> (事件映射) 等核心定义。</p>
-<pre><code class="typescript"><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">namespace</span><span class="hl-1"> </span><span class="hl-7">BasePlugin</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">State</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-6">enabled</span><span class="hl-1">: </span><span class="hl-7">boolean</span><br/><span class="hl-1">    </span><span class="hl-6">visible</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><br/><span class="hl-1">    </span><span class="hl-6">config</span><span class="hl-1">?: </span><span class="hl-7">unknown</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">  </span><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">abstract</span><span class="hl-1"> </span><span class="hl-3">class</span><span class="hl-1"> </span><span class="hl-7">Controller</span><span class="hl-1">&lt;</span><span class="hl-7">PluginState</span><span class="hl-1">, </span><span class="hl-7">PluginEventMap</span><span class="hl-1">, </span><span class="hl-7">PluginServerData</span><span class="hl-1">, </span><span class="hl-7">PluginData</span><span class="hl-1">&gt; {</span><br/><span class="hl-1">    </span><span class="hl-3">public</span><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">: </span><span class="hl-7">Five</span><br/><span class="hl-1">    </span><span class="hl-3">public</span><span class="hl-1"> </span><span class="hl-3">abstract</span><span class="hl-1"> </span><span class="hl-6">state</span><span class="hl-1">: </span><span class="hl-7">PluginState</span><br/><span class="hl-1">    </span><span class="hl-3">public</span><span class="hl-1"> </span><span class="hl-6">hooks</span><span class="hl-1">: </span><span class="hl-7">Subscribe</span><span class="hl-1">&lt;</span><span class="hl-7">PluginEventMap</span><span class="hl-1">&gt;</span><br/><span class="hl-1">    </span><span class="hl-8">// ...</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
+<pre><code class="typescript"><span class="hl-11">export</span><span class="hl-1"> </span><span class="hl-8">namespace</span><span class="hl-1"> </span><span class="hl-9">BasePlugin</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-11">export</span><span class="hl-1"> </span><span class="hl-8">interface</span><span class="hl-1"> </span><span class="hl-9">State</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-5">enabled</span><span class="hl-1">: </span><span class="hl-9">boolean</span><br/><span class="hl-1">    </span><span class="hl-5">visible</span><span class="hl-1">?: </span><span class="hl-9">boolean</span><br/><span class="hl-1">    </span><span class="hl-5">config</span><span class="hl-1">?: </span><span class="hl-9">unknown</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">  </span><span class="hl-11">export</span><span class="hl-1"> </span><span class="hl-8">abstract</span><span class="hl-1"> </span><span class="hl-8">class</span><span class="hl-1"> </span><span class="hl-9">Controller</span><span class="hl-1">&lt;</span><span class="hl-9">PluginState</span><span class="hl-1">, </span><span class="hl-9">PluginEventMap</span><span class="hl-1">, </span><span class="hl-9">PluginServerData</span><span class="hl-1">, </span><span class="hl-9">PluginData</span><span class="hl-1">&gt; {</span><br/><span class="hl-1">    </span><span class="hl-8">public</span><span class="hl-1"> </span><span class="hl-5">five</span><span class="hl-1">: </span><span class="hl-9">Five</span><br/><span class="hl-1">    </span><span class="hl-8">public</span><span class="hl-1"> </span><span class="hl-8">abstract</span><span class="hl-1"> </span><span class="hl-5">state</span><span class="hl-1">: </span><span class="hl-9">PluginState</span><br/><span class="hl-1">    </span><span class="hl-8">public</span><span class="hl-1"> </span><span class="hl-5">hooks</span><span class="hl-1">: </span><span class="hl-9">Subscribe</span><span class="hl-1">&lt;</span><span class="hl-9">PluginEventMap</span><span class="hl-1">&gt;</span><br/><span class="hl-1">    </span><span class="hl-7">// ...</span><br/><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>
@@ -79,17 +79,17 @@
 <p>以创建一个 <code>MyPlugin</code> 为例。</p>
 <h4 id="1-定义类型-typingts" class="tsd-anchor-link">1. 定义类型 (typing.ts)<a href="#1-定义类型-typingts" 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></h4>
 <p>定义插件所需的参数、状态、数据和事件类型。</p>
-<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">BasePlugin</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;../BasePlugin&#39;</span><br/><br/><span class="hl-8">// 1. 定义参数</span><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">Params</span><span class="hl-1"> </span><span class="hl-3">extends</span><span class="hl-1"> </span><span class="hl-7">BasePlugin</span><span class="hl-1">.</span><span class="hl-7">Config</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">initialState</span><span class="hl-1">?: </span><span class="hl-7">Partial</span><span class="hl-1">&lt;</span><span class="hl-7">State</span><span class="hl-1">&gt;</span><br/><span class="hl-1">  </span><span class="hl-6">config</span><span class="hl-1">?: </span><span class="hl-7">Config</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-8">// 2. 定义配置</span><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">Config</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">color</span><span class="hl-1">?: </span><span class="hl-7">string</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-8">// 3. 定义状态 (继承 BasePlugin.State)</span><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">State</span><span class="hl-1"> </span><span class="hl-3">extends</span><span class="hl-1"> </span><span class="hl-7">BasePlugin</span><span class="hl-1">.</span><span class="hl-7">State</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">activeId</span><span class="hl-1">?: </span><span class="hl-7">string</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-8">// 4. 定义数据类型</span><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">ServerData</span><span class="hl-1"> { </span><span class="hl-8">/* 服务端数据结构 */</span><span class="hl-1"> }</span><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">PluginData</span><span class="hl-1"> { </span><span class="hl-8">/* 解析后的数据结构 */</span><span class="hl-1"> }</span><br/><br/><span class="hl-8">// 5. 定义事件 (继承 BasePlugin.EventMap)</span><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">EventMap</span><span class="hl-1"> </span><span class="hl-3">extends</span><span class="hl-1"> </span><span class="hl-7">BasePlugin</span><span class="hl-1">.</span><span class="hl-7">EventMap</span><span class="hl-1">&lt;</span><span class="hl-7">State</span><span class="hl-1">, </span><span class="hl-7">PluginData</span><span class="hl-1">&gt; {</span><br/><span class="hl-1">  </span><span class="hl-5">click</span><span class="hl-1">: (</span><span class="hl-6">id</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-7">void</span><br/><span class="hl-1">}</span>
+<pre><code class="typescript"><span class="hl-11">import</span><span class="hl-1"> { </span><span class="hl-5">BasePlugin</span><span class="hl-1"> } </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&#39;../BasePlugin&#39;</span><br/><br/><span class="hl-7">// 1. 定义参数</span><br/><span class="hl-11">export</span><span class="hl-1"> </span><span class="hl-8">interface</span><span class="hl-1"> </span><span class="hl-9">Params</span><span class="hl-1"> </span><span class="hl-8">extends</span><span class="hl-1"> </span><span class="hl-9">BasePlugin</span><span class="hl-1">.</span><span class="hl-9">Config</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-5">initialState</span><span class="hl-1">?: </span><span class="hl-9">Partial</span><span class="hl-1">&lt;</span><span class="hl-9">State</span><span class="hl-1">&gt;</span><br/><span class="hl-1">  </span><span class="hl-5">config</span><span class="hl-1">?: </span><span class="hl-9">Config</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-7">// 2. 定义配置</span><br/><span class="hl-11">export</span><span class="hl-1"> </span><span class="hl-8">interface</span><span class="hl-1"> </span><span class="hl-9">Config</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-5">color</span><span class="hl-1">?: </span><span class="hl-9">string</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-7">// 3. 定义状态 (继承 BasePlugin.State)</span><br/><span class="hl-11">export</span><span class="hl-1"> </span><span class="hl-8">interface</span><span class="hl-1"> </span><span class="hl-9">State</span><span class="hl-1"> </span><span class="hl-8">extends</span><span class="hl-1"> </span><span class="hl-9">BasePlugin</span><span class="hl-1">.</span><span class="hl-9">State</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-5">activeId</span><span class="hl-1">?: </span><span class="hl-9">string</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-7">// 4. 定义数据类型</span><br/><span class="hl-11">export</span><span class="hl-1"> </span><span class="hl-8">interface</span><span class="hl-1"> </span><span class="hl-9">ServerData</span><span class="hl-1"> { </span><span class="hl-7">/* 服务端数据结构 */</span><span class="hl-1"> }</span><br/><span class="hl-11">export</span><span class="hl-1"> </span><span class="hl-8">interface</span><span class="hl-1"> </span><span class="hl-9">PluginData</span><span class="hl-1"> { </span><span class="hl-7">/* 解析后的数据结构 */</span><span class="hl-1"> }</span><br/><br/><span class="hl-7">// 5. 定义事件 (继承 BasePlugin.EventMap)</span><br/><span class="hl-11">export</span><span class="hl-1"> </span><span class="hl-8">interface</span><span class="hl-1"> </span><span class="hl-9">EventMap</span><span class="hl-1"> </span><span class="hl-8">extends</span><span class="hl-1"> </span><span class="hl-9">BasePlugin</span><span class="hl-1">.</span><span class="hl-9">EventMap</span><span class="hl-1">&lt;</span><span class="hl-9">State</span><span class="hl-1">, </span><span class="hl-9">PluginData</span><span class="hl-1">&gt; {</span><br/><span class="hl-1">  </span><span class="hl-4">click</span><span class="hl-1">: (</span><span class="hl-5">id</span><span class="hl-1">: </span><span class="hl-9">string</span><span class="hl-1">) </span><span class="hl-8">=&gt;</span><span class="hl-1"> </span><span class="hl-9">void</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 <h4 id="2-实现控制器-controllerts" class="tsd-anchor-link">2. 实现控制器 (Controller.ts)<a href="#2-实现控制器-controllerts" 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></h4>
 <p>继承 <code>BasePlugin.Controller</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-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">BasePlugin</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;../BasePlugin&#39;</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">MyPluginType</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;./typing&#39;</span><br/><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">class</span><span class="hl-1"> </span><span class="hl-7">Controller</span><span class="hl-1"> </span><span class="hl-3">extends</span><span class="hl-1"> </span><span class="hl-7">BasePlugin</span><span class="hl-1">.</span><span class="hl-7">Controller</span><span class="hl-1">&lt;</span><br/><span class="hl-1">  </span><span class="hl-7">MyPluginType</span><span class="hl-1">.</span><span class="hl-7">State</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-7">MyPluginType</span><span class="hl-1">.</span><span class="hl-7">EventMap</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-7">MyPluginType</span><span class="hl-1">.</span><span class="hl-7">ServerData</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-7">MyPluginType</span><span class="hl-1">.</span><span class="hl-7">PluginData</span><br/><span class="hl-1">&gt; {</span><br/><span class="hl-1">  </span><span class="hl-3">public</span><span class="hl-1"> </span><span class="hl-6">state</span><span class="hl-1">: </span><span class="hl-7">MyPluginType</span><span class="hl-1">.</span><span class="hl-7">State</span><br/><br/><span class="hl-1">  </span><span class="hl-3">constructor</span><span class="hl-1">(</span><span class="hl-6">five</span><span class="hl-1">: </span><span class="hl-7">Five</span><span class="hl-1">, </span><span class="hl-6">params</span><span class="hl-1">?: </span><span class="hl-7">MyPluginType</span><span class="hl-1">.</span><span class="hl-7">Params</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-3">super</span><span class="hl-1">(</span><span class="hl-6">five</span><span class="hl-1">)</span><br/><span class="hl-1">    </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">state</span><span class="hl-1"> = {</span><br/><span class="hl-1">      </span><span class="hl-6">enabled:</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-6">visible:</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-6">params</span><span class="hl-1">?.</span><span class="hl-6">initialState</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">    </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">state</span><span class="hl-1">.</span><span class="hl-6">enabled</span><span class="hl-1">) {</span><br/><span class="hl-1">      </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-5">_enable</span><span class="hl-1">()</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-3">public</span><span class="hl-1"> </span><span class="hl-3">async</span><span class="hl-1"> </span><span class="hl-5">load</span><span class="hl-1">(</span><span class="hl-6">serverData</span><span class="hl-1">: </span><span class="hl-7">MyPluginType</span><span class="hl-1">.</span><span class="hl-7">ServerData</span><span class="hl-1">) {</span><br/><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-3">public</span><span class="hl-1"> </span><span class="hl-5">enable</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">state</span><span class="hl-1">.</span><span class="hl-6">enabled</span><span class="hl-1">) </span><span class="hl-10">return</span><br/><span class="hl-1">    </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">state</span><span class="hl-1">.</span><span class="hl-6">enabled</span><span class="hl-1"> = </span><span class="hl-3">true</span><br/><span class="hl-1">    </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-5">_enable</span><span class="hl-1">()</span><br/><span class="hl-1">    </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">hooks</span><span class="hl-1">.</span><span class="hl-5">emit</span><span class="hl-1">(</span><span class="hl-9">&#39;stateChange&#39;</span><span class="hl-1">, { </span><span class="hl-6">state:</span><span class="hl-1"> </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">state</span><span class="hl-1">, </span><span class="hl-6">userAction:</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-1">  </span><span class="hl-3">public</span><span class="hl-1"> </span><span class="hl-5">disable</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-10">if</span><span class="hl-1"> (!</span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">state</span><span class="hl-1">.</span><span class="hl-6">enabled</span><span class="hl-1">) </span><span class="hl-10">return</span><br/><span class="hl-1">    </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">state</span><span class="hl-1">.</span><span class="hl-6">enabled</span><span class="hl-1"> = </span><span class="hl-3">false</span><br/><span class="hl-1">    </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-5">_disable</span><span class="hl-1">()</span><br/><span class="hl-1">    </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">hooks</span><span class="hl-1">.</span><span class="hl-5">emit</span><span class="hl-1">(</span><span class="hl-9">&#39;stateChange&#39;</span><span class="hl-1">, { </span><span class="hl-6">state:</span><span class="hl-1"> </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">state</span><span class="hl-1">, </span><span class="hl-6">userAction:</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-1">  </span><span class="hl-3">public</span><span class="hl-1"> </span><span class="hl-5">dispose</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-3">this</span><span class="hl-1">.</span><span class="hl-5">disable</span><span class="hl-1">()</span><br/><span class="hl-1">    </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">hooks</span><span class="hl-1">.</span><span class="hl-5">emit</span><span class="hl-1">(</span><span class="hl-9">&#39;dispose&#39;</span><span class="hl-1">)</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-3">private</span><span class="hl-1"> </span><span class="hl-5">_enable</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-8">// five.scene.add(...)</span><br/><span class="hl-1">    </span><span class="hl-8">// five.on(&#39;tap&#39;, this.onTap)</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-3">private</span><span class="hl-1"> </span><span class="hl-5">_disable</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-8">// five.scene.remove(...)</span><br/><span class="hl-1">    </span><span class="hl-8">// five.off(&#39;tap&#39;, this.onTap)</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
+<pre><code class="typescript"><span class="hl-11">import</span><span class="hl-1"> { </span><span class="hl-5">Five</span><span class="hl-1"> } </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&#39;@realsee/five&#39;</span><br/><span class="hl-11">import</span><span class="hl-1"> { </span><span class="hl-5">BasePlugin</span><span class="hl-1"> } </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&#39;../BasePlugin&#39;</span><br/><span class="hl-11">import</span><span class="hl-1"> </span><span class="hl-8">*</span><span class="hl-1"> </span><span class="hl-11">as</span><span class="hl-1"> </span><span class="hl-5">MyPluginType</span><span class="hl-1"> </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&#39;./typing&#39;</span><br/><br/><span class="hl-11">export</span><span class="hl-1"> </span><span class="hl-8">class</span><span class="hl-1"> </span><span class="hl-9">Controller</span><span class="hl-1"> </span><span class="hl-8">extends</span><span class="hl-1"> </span><span class="hl-9">BasePlugin</span><span class="hl-1">.</span><span class="hl-9">Controller</span><span class="hl-1">&lt;</span><br/><span class="hl-1">  </span><span class="hl-9">MyPluginType</span><span class="hl-1">.</span><span class="hl-9">State</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-9">MyPluginType</span><span class="hl-1">.</span><span class="hl-9">EventMap</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-9">MyPluginType</span><span class="hl-1">.</span><span class="hl-9">ServerData</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-9">MyPluginType</span><span class="hl-1">.</span><span class="hl-9">PluginData</span><br/><span class="hl-1">&gt; {</span><br/><span class="hl-1">  </span><span class="hl-8">public</span><span class="hl-1"> </span><span class="hl-5">state</span><span class="hl-1">: </span><span class="hl-9">MyPluginType</span><span class="hl-1">.</span><span class="hl-9">State</span><br/><br/><span class="hl-1">  </span><span class="hl-8">constructor</span><span class="hl-1">(</span><span class="hl-5">five</span><span class="hl-1">: </span><span class="hl-9">Five</span><span class="hl-1">, </span><span class="hl-5">params</span><span class="hl-1">?: </span><span class="hl-9">MyPluginType</span><span class="hl-1">.</span><span class="hl-9">Params</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-8">super</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-8">this</span><span class="hl-1">.</span><span class="hl-5">state</span><span class="hl-1"> = {</span><br/><span class="hl-1">      </span><span class="hl-5">enabled:</span><span class="hl-1"> </span><span class="hl-8">true</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-5">visible:</span><span class="hl-1"> </span><span class="hl-8">true</span><span class="hl-1">,</span><br/><span class="hl-1">      ...</span><span class="hl-5">params</span><span class="hl-1">?.</span><span class="hl-5">initialState</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">    </span><span class="hl-11">if</span><span class="hl-1"> (</span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-5">state</span><span class="hl-1">.</span><span class="hl-5">enabled</span><span class="hl-1">) {</span><br/><span class="hl-1">      </span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-4">_enable</span><span class="hl-1">()</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-8">public</span><span class="hl-1"> </span><span class="hl-8">async</span><span class="hl-1"> </span><span class="hl-4">load</span><span class="hl-1">(</span><span class="hl-5">serverData</span><span class="hl-1">: </span><span class="hl-9">MyPluginType</span><span class="hl-1">.</span><span class="hl-9">ServerData</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-7">// 解析数据</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-8">public</span><span class="hl-1"> </span><span class="hl-4">enable</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-11">if</span><span class="hl-1"> (</span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-5">state</span><span class="hl-1">.</span><span class="hl-5">enabled</span><span class="hl-1">) </span><span class="hl-11">return</span><br/><span class="hl-1">    </span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-5">state</span><span class="hl-1">.</span><span class="hl-5">enabled</span><span class="hl-1"> = </span><span class="hl-8">true</span><br/><span class="hl-1">    </span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-4">_enable</span><span class="hl-1">()</span><br/><span class="hl-1">    </span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-5">hooks</span><span class="hl-1">.</span><span class="hl-4">emit</span><span class="hl-1">(</span><span class="hl-10">&#39;stateChange&#39;</span><span class="hl-1">, { </span><span class="hl-5">state:</span><span class="hl-1"> </span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-5">state</span><span class="hl-1">, </span><span class="hl-5">userAction:</span><span class="hl-1"> </span><span class="hl-8">true</span><span class="hl-1"> })</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-8">public</span><span class="hl-1"> </span><span class="hl-4">disable</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-11">if</span><span class="hl-1"> (!</span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-5">state</span><span class="hl-1">.</span><span class="hl-5">enabled</span><span class="hl-1">) </span><span class="hl-11">return</span><br/><span class="hl-1">    </span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-5">state</span><span class="hl-1">.</span><span class="hl-5">enabled</span><span class="hl-1"> = </span><span class="hl-8">false</span><br/><span class="hl-1">    </span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-4">_disable</span><span class="hl-1">()</span><br/><span class="hl-1">    </span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-5">hooks</span><span class="hl-1">.</span><span class="hl-4">emit</span><span class="hl-1">(</span><span class="hl-10">&#39;stateChange&#39;</span><span class="hl-1">, { </span><span class="hl-5">state:</span><span class="hl-1"> </span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-5">state</span><span class="hl-1">, </span><span class="hl-5">userAction:</span><span class="hl-1"> </span><span class="hl-8">true</span><span class="hl-1"> })</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-8">public</span><span class="hl-1"> </span><span class="hl-4">dispose</span><span class="hl-1"> = () </span><span class="hl-8">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-4">disable</span><span class="hl-1">()</span><br/><span class="hl-1">    </span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-5">hooks</span><span class="hl-1">.</span><span class="hl-4">emit</span><span class="hl-1">(</span><span class="hl-10">&#39;dispose&#39;</span><span class="hl-1">)</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-8">private</span><span class="hl-1"> </span><span class="hl-4">_enable</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-7">// five.scene.add(...)</span><br/><span class="hl-1">    </span><span class="hl-7">// five.on(&#39;tap&#39;, this.onTap)</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-8">private</span><span class="hl-1"> </span><span class="hl-4">_disable</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-7">// five.scene.remove(...)</span><br/><span class="hl-1">    </span><span class="hl-7">// five.off(&#39;tap&#39;, this.onTap)</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 <h4 id="3-导出插件-indexts" class="tsd-anchor-link">3. 导出插件 (index.ts)<a href="#3-导出插件-indexts" 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></h4>
 <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">&#39;@realsee/five&#39;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Controller</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;./Controller&#39;</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">MyPluginType</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;./typing&#39;</span><br/><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-5">MyPlugin</span><span class="hl-1"> = (</span><span class="hl-6">five</span><span class="hl-1">: </span><span class="hl-7">Five</span><span class="hl-1">, </span><span class="hl-6">params</span><span class="hl-1">?: </span><span class="hl-7">MyPluginType</span><span class="hl-1">.</span><span class="hl-7">Params</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><br/><span class="hl-1">  </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Controller</span><span class="hl-1">(</span><span class="hl-6">five</span><span class="hl-1">, </span><span class="hl-6">params</span><span class="hl-1">)</span><br/><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-10">type</span><span class="hl-1"> { </span><span class="hl-6">MyPluginType</span><span class="hl-1">, </span><span class="hl-6">Controller</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">MyPluginController</span><span class="hl-1"> }</span>
+<pre><code class="typescript"><span class="hl-11">import</span><span class="hl-1"> { </span><span class="hl-5">Five</span><span class="hl-1"> } </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&#39;@realsee/five&#39;</span><br/><span class="hl-11">import</span><span class="hl-1"> { </span><span class="hl-5">Controller</span><span class="hl-1"> } </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&#39;./Controller&#39;</span><br/><span class="hl-11">import</span><span class="hl-1"> </span><span class="hl-8">*</span><span class="hl-1"> </span><span class="hl-11">as</span><span class="hl-1"> </span><span class="hl-5">MyPluginType</span><span class="hl-1"> </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&#39;./typing&#39;</span><br/><br/><span class="hl-11">export</span><span class="hl-1"> </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-4">MyPlugin</span><span class="hl-1"> = (</span><span class="hl-5">five</span><span class="hl-1">: </span><span class="hl-9">Five</span><span class="hl-1">, </span><span class="hl-5">params</span><span class="hl-1">?: </span><span class="hl-9">MyPluginType</span><span class="hl-1">.</span><span class="hl-9">Params</span><span class="hl-1">) </span><span class="hl-8">=&gt;</span><br/><span class="hl-1">  </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-4">Controller</span><span class="hl-1">(</span><span class="hl-5">five</span><span class="hl-1">, </span><span class="hl-5">params</span><span class="hl-1">)</span><br/><br/><span class="hl-11">export</span><span class="hl-1"> </span><span class="hl-11">type</span><span class="hl-1"> { </span><span class="hl-5">MyPluginType</span><span class="hl-1">, </span><span class="hl-5">Controller</span><span class="hl-1"> </span><span class="hl-11">as</span><span class="hl-1"> </span><span class="hl-5">MyPluginController</span><span class="hl-1"> }</span>
 </code><button type="button">Copy</button></pre>
 <h2 id="common-pitfalls-最佳实践" class="tsd-anchor-link">Common Pitfalls (最佳实践)<a href="#common-pitfalls-最佳实践" 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_postprocessing.html CHANGED Viewed

@@ -10,7 +10,7 @@
 <blockquote>
 <p><strong>Definition</strong>: <a href="../../five/renderer/postprocessing/passes/pass.d.ts">FivePass</a></p>
 </blockquote>
-<pre><code class="typescript"><span class="hl-8">/**</span><br/><span class="hl-8"> * Pass 接口 (兼容 three.js EffectComposer)</span><br/><span class="hl-8"> */</span><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">Pass</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">enabled</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-6">needsSwap</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-6">clear</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-6">renderToScreen</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-5">setSize</span><span class="hl-1">(</span><span class="hl-6">width</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">, </span><span class="hl-6">height</span><span class="hl-1">: </span><span class="hl-7">number</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-5">render</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-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-6">writeBuffer</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">WebGLRenderTarget</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">readBuffer</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">WebGLRenderTarget</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">deltaTime</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-6">maskActive</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><br/><span class="hl-1">  ): </span><span class="hl-7">void</span><span class="hl-1">;</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-8">/**</span><br/><span class="hl-8"> * FivePass 基类</span><br/><span class="hl-8"> * 支持 G-Buffer 注入 (depth, normal, color)</span><br/><span class="hl-8"> */</span><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">class</span><span class="hl-1"> </span><span class="hl-7">FivePass</span><span class="hl-1"> </span><span class="hl-3">implements</span><span class="hl-1"> </span><span class="hl-7">Pass</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-3">public</span><span class="hl-1"> </span><span class="hl-6">enabled</span><span class="hl-1">: </span><span class="hl-7">boolean</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-3">public</span><span class="hl-1"> </span><span class="hl-6">needsSwap</span><span class="hl-1">: </span><span class="hl-7">boolean</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-3">public</span><span class="hl-1"> </span><span class="hl-6">clear</span><span class="hl-1">: </span><span class="hl-7">boolean</span><span class="hl-1"> = </span><span class="hl-3">false</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-3">public</span><span class="hl-1"> </span><span class="hl-6">renderToScreen</span><span class="hl-1">: </span><span class="hl-7">boolean</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-3">public</span><span class="hl-1"> </span><span class="hl-6">dependencies</span><span class="hl-1">: (</span><span class="hl-9">&#39;depth&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;normal&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;color&#39;</span><span class="hl-1">)[];</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 由 EffectComposer 在 render 时注入</span><br/><span class="hl-1">  </span><span class="hl-3">public</span><span class="hl-1"> </span><span class="hl-6">gbuffer</span><span class="hl-1">!: </span><span class="hl-7">Map</span><span class="hl-1">&lt;</span><span class="hl-9">&#39;depth&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;normal&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;color&#39;</span><span class="hl-1">, </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Texture</span><span class="hl-1">&gt;;</span><br/><br/><span class="hl-1">  </span><span class="hl-3">constructor</span><span class="hl-1">(</span><span class="hl-6">dependencies</span><span class="hl-1">?: (</span><span class="hl-9">&#39;depth&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;normal&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;color&#39;</span><span class="hl-1">)[]);</span><br/><span class="hl-1">  </span><span class="hl-8">// ... render method implementation</span><br/><span class="hl-1">}</span>
+<pre><code class="typescript"><span class="hl-7">/**</span><br/><span class="hl-7"> * Pass 接口 (兼容 three.js EffectComposer)</span><br/><span class="hl-7"> */</span><br/><span class="hl-11">export</span><span class="hl-1"> </span><span class="hl-8">interface</span><span class="hl-1"> </span><span class="hl-9">Pass</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-5">enabled</span><span class="hl-1">: </span><span class="hl-9">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-5">needsSwap</span><span class="hl-1">: </span><span class="hl-9">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-5">clear</span><span class="hl-1">: </span><span class="hl-9">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-5">renderToScreen</span><span class="hl-1">: </span><span class="hl-9">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-4">setSize</span><span class="hl-1">(</span><span class="hl-5">width</span><span class="hl-1">: </span><span class="hl-9">number</span><span class="hl-1">, </span><span class="hl-5">height</span><span class="hl-1">: </span><span class="hl-9">number</span><span class="hl-1">): </span><span class="hl-9">void</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-4">render</span><span class="hl-1">(</span><br/><span class="hl-1">    </span><span class="hl-5">renderer</span><span class="hl-1">: </span><span class="hl-9">THREE</span><span class="hl-1">.</span><span class="hl-9">WebGLRenderer</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">writeBuffer</span><span class="hl-1">: </span><span class="hl-9">THREE</span><span class="hl-1">.</span><span class="hl-9">WebGLRenderTarget</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">readBuffer</span><span class="hl-1">: </span><span class="hl-9">THREE</span><span class="hl-1">.</span><span class="hl-9">WebGLRenderTarget</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">deltaTime</span><span class="hl-1">?: </span><span class="hl-9">number</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">maskActive</span><span class="hl-1">?: </span><span class="hl-9">boolean</span><br/><span class="hl-1">  ): </span><span class="hl-9">void</span><span class="hl-1">;</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-7">/**</span><br/><span class="hl-7"> * FivePass 基类</span><br/><span class="hl-7"> * 支持 G-Buffer 注入 (depth, normal, color)</span><br/><span class="hl-7"> */</span><br/><span class="hl-11">export</span><span class="hl-1"> </span><span class="hl-8">class</span><span class="hl-1"> </span><span class="hl-9">FivePass</span><span class="hl-1"> </span><span class="hl-8">implements</span><span class="hl-1"> </span><span class="hl-9">Pass</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-8">public</span><span class="hl-1"> </span><span class="hl-5">enabled</span><span class="hl-1">: </span><span class="hl-9">boolean</span><span class="hl-1"> = </span><span class="hl-8">true</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">public</span><span class="hl-1"> </span><span class="hl-5">needsSwap</span><span class="hl-1">: </span><span class="hl-9">boolean</span><span class="hl-1"> = </span><span class="hl-8">true</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">public</span><span class="hl-1"> </span><span class="hl-5">clear</span><span class="hl-1">: </span><span class="hl-9">boolean</span><span class="hl-1"> = </span><span class="hl-8">false</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">public</span><span class="hl-1"> </span><span class="hl-5">renderToScreen</span><span class="hl-1">: </span><span class="hl-9">boolean</span><span class="hl-1"> = </span><span class="hl-8">true</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">public</span><span class="hl-1"> </span><span class="hl-5">dependencies</span><span class="hl-1">: (</span><span class="hl-10">&#39;depth&#39;</span><span class="hl-1"> | </span><span class="hl-10">&#39;normal&#39;</span><span class="hl-1"> | </span><span class="hl-10">&#39;color&#39;</span><span class="hl-1">)[];</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// 由 EffectComposer 在 render 时注入</span><br/><span class="hl-1">  </span><span class="hl-8">public</span><span class="hl-1"> </span><span class="hl-5">gbuffer</span><span class="hl-1">!: </span><span class="hl-9">Map</span><span class="hl-1">&lt;</span><span class="hl-10">&#39;depth&#39;</span><span class="hl-1"> | </span><span class="hl-10">&#39;normal&#39;</span><span class="hl-1"> | </span><span class="hl-10">&#39;color&#39;</span><span class="hl-1">, </span><span class="hl-9">THREE</span><span class="hl-1">.</span><span class="hl-9">Texture</span><span class="hl-1">&gt;;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">constructor</span><span class="hl-1">(</span><span class="hl-5">dependencies</span><span class="hl-1">?: (</span><span class="hl-10">&#39;depth&#39;</span><span class="hl-1"> | </span><span class="hl-10">&#39;normal&#39;</span><span class="hl-1"> | </span><span class="hl-10">&#39;color&#39;</span><span class="hl-1">)[]);</span><br/><span class="hl-1">  </span><span class="hl-7">// ... render method implementation</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>
@@ -56,7 +56,7 @@
 <li><strong><a href="features_flowing-fireworks-3d-pass.html">FlowingFireworks3DPass</a></strong>: 在 3D 流光尾部喷射烟花粒子的配套特效。</li>
 </ul>
 <h4 id="gaussianblurpass-使用示例" class="tsd-anchor-link">GaussianBlurPass 使用示例<a href="#gaussianblurpass-使用示例" 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></h4>
-<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">GaussianBlurPass</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. 创建 GaussianBlurPass 实例 (需要传入 camera)</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">gaussianBlurPass</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">GaussianBlurPass</span><span class="hl-1">(</span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">camera</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 2. 配置参数</span><br/><span class="hl-8">// 设置模糊半径 (默认 4.0)</span><br/><span class="hl-6">gaussianBlurPass</span><span class="hl-1">.</span><span class="hl-5">setRadius</span><span class="hl-1">(</span><span class="hl-11">6</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 3. 将 Pass 添加到渲染链</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">addPass</span><span class="hl-1">(</span><span class="hl-6">gaussianBlurPass</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 4. (可选) 动态开关</span><br/><span class="hl-8">// gaussianBlurPass.enabled = false;</span><br/><br/><span class="hl-8">// 5. (可选) 移除 Pass</span><br/><span class="hl-8">// five.removePass(gaussianBlurPass);</span>
+<pre><code class="typescript"><span class="hl-11">import</span><span class="hl-1"> { </span><span class="hl-5">GaussianBlurPass</span><span class="hl-1"> } </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-7">// 1. 创建 GaussianBlurPass 实例 (需要传入 camera)</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">gaussianBlurPass</span><span class="hl-1"> = </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-4">GaussianBlurPass</span><span class="hl-1">(</span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">camera</span><span class="hl-1">);</span><br/><br/><span class="hl-7">// 2. 配置参数</span><br/><span class="hl-7">// 设置模糊半径 (默认 4.0)</span><br/><span class="hl-5">gaussianBlurPass</span><span class="hl-1">.</span><span class="hl-4">setRadius</span><span class="hl-1">(</span><span class="hl-3">6</span><span class="hl-1">);</span><br/><br/><span class="hl-7">// 3. 将 Pass 添加到渲染链</span><br/><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">addPass</span><span class="hl-1">(</span><span class="hl-5">gaussianBlurPass</span><span class="hl-1">);</span><br/><br/><span class="hl-7">// 4. (可选) 动态开关</span><br/><span class="hl-7">// gaussianBlurPass.enabled = false;</span><br/><br/><span class="hl-7">// 5. (可选) 移除 Pass</span><br/><span class="hl-7">// five.removePass(gaussianBlurPass);</span>
 </code><button type="button">Copy</button></pre>
 <h2 id="custom-pass-自定义-pass" class="tsd-anchor-link">Custom Pass (自定义 Pass)<a href="#custom-pass-自定义-pass" 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>
@@ -70,16 +70,16 @@
 </ol>
 <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="开启内置-pass" class="tsd-anchor-link">开启内置 Pass<a href="#开启内置-pass" 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>
-<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">&#39;@realsee/five&#39;</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-6">adaptiveLuminancePass</span><span class="hl-1">.</span><span class="hl-6">enabled</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">adaptiveLuminancePass</span><span class="hl-1">.</span><span class="hl-6">luminanceScale</span><span class="hl-1"> = </span><span class="hl-11">0.5</span><span class="hl-1">; </span><span class="hl-8">// 调整目标亮度</span><br/><br/><span class="hl-8">// 开启 EDL (通常用于点云模式)</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">eyeDomeLightingPass</span><span class="hl-1">.</span><span class="hl-6">enabled</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">eyeDomeLightingPass</span><span class="hl-1">.</span><span class="hl-6">strength</span><span class="hl-1"> = </span><span class="hl-11">1.5</span><span class="hl-1">; </span><span class="hl-8">// 增强轮廓感</span><br/><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-11">import</span><span class="hl-1"> { </span><span class="hl-5">Five</span><span class="hl-1"> } </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1"> = </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-4">Five</span><span class="hl-1">();</span><br/><br/><span class="hl-7">// 开启自适应亮度</span><br/><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">adaptiveLuminancePass</span><span class="hl-1">.</span><span class="hl-5">enabled</span><span class="hl-1"> = </span><span class="hl-8">true</span><span class="hl-1">;</span><br/><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">adaptiveLuminancePass</span><span class="hl-1">.</span><span class="hl-5">luminanceScale</span><span class="hl-1"> = </span><span class="hl-3">0.5</span><span class="hl-1">; </span><span class="hl-7">// 调整目标亮度</span><br/><br/><span class="hl-7">// 开启 EDL (通常用于点云模式)</span><br/><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">eyeDomeLightingPass</span><span class="hl-1">.</span><span class="hl-5">enabled</span><span class="hl-1"> = </span><span class="hl-8">true</span><span class="hl-1">;</span><br/><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">eyeDomeLightingPass</span><span class="hl-1">.</span><span class="hl-5">strength</span><span class="hl-1"> = </span><span class="hl-3">1.5</span><span class="hl-1">; </span><span class="hl-7">// 增强轮廓感</span><br/><br/><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">needsRender</span><span class="hl-1"> = </span><span class="hl-8">true</span><span class="hl-1">;</span>
 </code><button type="button">Copy</button></pre>
 <h3 id="自定义-pass-黑白滤镜" class="tsd-anchor-link">自定义 Pass (黑白滤镜)<a href="#自定义-pass-黑白滤镜" 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>
-<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-6">FivePass</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/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">FullScreenQuad</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five/lib/five/tools/full-screen-quad&#39;</span><span class="hl-1">; </span><span class="hl-8">// 需根据实际路径引用</span><br/><br/><span class="hl-8">// 1. 定义 Shader</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">grayscaleVertexShader</span><span class="hl-1"> = </span><span class="hl-9">`</span><br/><span class="hl-9">  varying vec2 vUv;</span><br/><span class="hl-9">  void main() {</span><br/><span class="hl-9">    vUv = uv;</span><br/><span class="hl-9">    gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);</span><br/><span class="hl-9">  }</span><br/><span class="hl-9">`</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">grayscaleFragmentShader</span><span class="hl-1"> = </span><span class="hl-9">`</span><br/><span class="hl-9">  uniform sampler2D tDiffuse;</span><br/><span class="hl-9">  varying vec2 vUv;</span><br/><span class="hl-9">  void main() {</span><br/><span class="hl-9">    vec4 color = texture2D(tDiffuse, vUv);</span><br/><span class="hl-9">    float gray = dot(color.rgb, vec3(0.299, 0.587, 0.114));</span><br/><span class="hl-9">    gl_FragColor = vec4(vec3(gray), color.a);</span><br/><span class="hl-9">  }</span><br/><span class="hl-9">`</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 2. 创建 Pass 类</span><br/><span class="hl-3">class</span><span class="hl-1"> </span><span class="hl-7">GrayscalePass</span><span class="hl-1"> </span><span class="hl-3">extends</span><span class="hl-1"> </span><span class="hl-7">FivePass</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-3">private</span><span class="hl-1"> </span><span class="hl-6">material</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">ShaderMaterial</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-3">private</span><span class="hl-1"> </span><span class="hl-6">fsQuad</span><span class="hl-1">: </span><span class="hl-7">FullScreenQuad</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-3">constructor</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-3">super</span><span class="hl-1">(); </span><span class="hl-8">// 不需要额外的 G-Buffer 依赖，只需要前一个 Pass 的颜色结果</span><br/><span class="hl-1">    </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">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">ShaderMaterial</span><span class="hl-1">({</span><br/><span class="hl-1">      </span><span class="hl-6">uniforms:</span><span class="hl-1"> {</span><br/><span class="hl-1">        </span><span class="hl-6">tDiffuse:</span><span class="hl-1"> { </span><span class="hl-6">value:</span><span class="hl-1"> </span><span class="hl-3">null</span><span class="hl-1"> }</span><br/><span class="hl-1">      },</span><br/><span class="hl-1">      </span><span class="hl-6">vertexShader:</span><span class="hl-1"> </span><span class="hl-6">grayscaleVertexShader</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-6">fragmentShader:</span><span class="hl-1"> </span><span class="hl-6">grayscaleFragmentShader</span><br/><span class="hl-1">    });</span><br/><span class="hl-1">    </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">fsQuad</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">FullScreenQuad</span><span class="hl-1">(</span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">material</span><span class="hl-1">);</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-5">render</span><span class="hl-1">(</span><span class="hl-6">renderer</span><span class="hl-1">, </span><span class="hl-6">writeBuffer</span><span class="hl-1">, </span><span class="hl-6">readBuffer</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-8">// 将上一个 Pass 的结果 (readBuffer) 传给 Shader</span><br/><span class="hl-1">    </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">material</span><span class="hl-1">.</span><span class="hl-6">uniforms</span><span class="hl-1">.</span><span class="hl-6">tDiffuse</span><span class="hl-1">.</span><span class="hl-6">value</span><span class="hl-1"> = </span><span class="hl-6">readBuffer</span><span class="hl-1">.</span><span class="hl-6">texture</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-3">this</span><span class="hl-1">.</span><span class="hl-6">renderToScreen</span><span class="hl-1">) {</span><br/><span class="hl-1">      </span><span class="hl-8">// 如果是最后一个 Pass，直接渲染到屏幕</span><br/><span class="hl-1">      </span><span class="hl-6">renderer</span><span class="hl-1">.</span><span class="hl-5">setRenderTarget</span><span class="hl-1">(</span><span class="hl-3">null</span><span class="hl-1">);</span><br/><span class="hl-1">      </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">fsQuad</span><span class="hl-1">.</span><span class="hl-5">render</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-10">else</span><span class="hl-1"> {</span><br/><span class="hl-1">      </span><span class="hl-8">// 否则渲染到 writeBuffer，供下一个 Pass 使用</span><br/><span class="hl-1">      </span><span class="hl-6">renderer</span><span class="hl-1">.</span><span class="hl-5">setRenderTarget</span><span class="hl-1">(</span><span class="hl-6">writeBuffer</span><span class="hl-1">);</span><br/><span class="hl-1">      </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">clear</span><span class="hl-1">) </span><span class="hl-6">renderer</span><span class="hl-1">.</span><span class="hl-5">clear</span><span class="hl-1">();</span><br/><span class="hl-1">      </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">fsQuad</span><span class="hl-1">.</span><span class="hl-5">render</span><span class="hl-1">(</span><span class="hl-6">renderer</span><span class="hl-1">);</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-8">// 3. 挂载到 Five</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">grayPass</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">GrayscalePass</span><span class="hl-1">();</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">addPass</span><span class="hl-1">(</span><span class="hl-6">grayPass</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-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-11">import</span><span class="hl-1"> </span><span class="hl-8">*</span><span class="hl-1"> </span><span class="hl-11">as</span><span class="hl-1"> </span><span class="hl-5">THREE</span><span class="hl-1"> </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&#39;three&#39;</span><span class="hl-1">;</span><br/><span class="hl-11">import</span><span class="hl-1"> { </span><span class="hl-5">Five</span><span class="hl-1">, </span><span class="hl-5">FivePass</span><span class="hl-1"> } </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><span class="hl-11">import</span><span class="hl-1"> { </span><span class="hl-5">FullScreenQuad</span><span class="hl-1"> } </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&#39;@realsee/five/lib/five/tools/full-screen-quad&#39;</span><span class="hl-1">; </span><span class="hl-7">// 需根据实际路径引用</span><br/><br/><span class="hl-7">// 1. 定义 Shader</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">grayscaleVertexShader</span><span class="hl-1"> = </span><span class="hl-10">`</span><br/><span class="hl-10">  varying vec2 vUv;</span><br/><span class="hl-10">  void main() {</span><br/><span class="hl-10">    vUv = uv;</span><br/><span class="hl-10">    gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);</span><br/><span class="hl-10">  }</span><br/><span class="hl-10">`</span><span class="hl-1">;</span><br/><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">grayscaleFragmentShader</span><span class="hl-1"> = </span><span class="hl-10">`</span><br/><span class="hl-10">  uniform sampler2D tDiffuse;</span><br/><span class="hl-10">  varying vec2 vUv;</span><br/><span class="hl-10">  void main() {</span><br/><span class="hl-10">    vec4 color = texture2D(tDiffuse, vUv);</span><br/><span class="hl-10">    float gray = dot(color.rgb, vec3(0.299, 0.587, 0.114));</span><br/><span class="hl-10">    gl_FragColor = vec4(vec3(gray), color.a);</span><br/><span class="hl-10">  }</span><br/><span class="hl-10">`</span><span class="hl-1">;</span><br/><br/><span class="hl-7">// 2. 创建 Pass 类</span><br/><span class="hl-8">class</span><span class="hl-1"> </span><span class="hl-9">GrayscalePass</span><span class="hl-1"> </span><span class="hl-8">extends</span><span class="hl-1"> </span><span class="hl-9">FivePass</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-8">private</span><span class="hl-1"> </span><span class="hl-5">material</span><span class="hl-1">: </span><span class="hl-9">THREE</span><span class="hl-1">.</span><span class="hl-9">ShaderMaterial</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">private</span><span class="hl-1"> </span><span class="hl-5">fsQuad</span><span class="hl-1">: </span><span class="hl-9">FullScreenQuad</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">constructor</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-8">super</span><span class="hl-1">(); </span><span class="hl-7">// 不需要额外的 G-Buffer 依赖，只需要前一个 Pass 的颜色结果</span><br/><span class="hl-1">    </span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-5">material</span><span class="hl-1"> = </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1">.</span><span class="hl-4">ShaderMaterial</span><span class="hl-1">({</span><br/><span class="hl-1">      </span><span class="hl-5">uniforms:</span><span class="hl-1"> {</span><br/><span class="hl-1">        </span><span class="hl-5">tDiffuse:</span><span class="hl-1"> { </span><span class="hl-5">value:</span><span class="hl-1"> </span><span class="hl-8">null</span><span class="hl-1"> }</span><br/><span class="hl-1">      },</span><br/><span class="hl-1">      </span><span class="hl-5">vertexShader:</span><span class="hl-1"> </span><span class="hl-5">grayscaleVertexShader</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-5">fragmentShader:</span><span class="hl-1"> </span><span class="hl-5">grayscaleFragmentShader</span><br/><span class="hl-1">    });</span><br/><span class="hl-1">    </span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-5">fsQuad</span><span class="hl-1"> = </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-4">FullScreenQuad</span><span class="hl-1">(</span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-5">material</span><span class="hl-1">);</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-4">render</span><span class="hl-1">(</span><span class="hl-5">renderer</span><span class="hl-1">, </span><span class="hl-5">writeBuffer</span><span class="hl-1">, </span><span class="hl-5">readBuffer</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-7">// 将上一个 Pass 的结果 (readBuffer) 传给 Shader</span><br/><span class="hl-1">    </span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-5">material</span><span class="hl-1">.</span><span class="hl-5">uniforms</span><span class="hl-1">.</span><span class="hl-5">tDiffuse</span><span class="hl-1">.</span><span class="hl-5">value</span><span class="hl-1"> = </span><span class="hl-5">readBuffer</span><span class="hl-1">.</span><span class="hl-5">texture</span><span class="hl-1">;</span><br/><br/><span class="hl-1">    </span><span class="hl-11">if</span><span class="hl-1"> (</span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-5">renderToScreen</span><span class="hl-1">) {</span><br/><span class="hl-1">      </span><span class="hl-7">// 如果是最后一个 Pass，直接渲染到屏幕</span><br/><span class="hl-1">      </span><span class="hl-5">renderer</span><span class="hl-1">.</span><span class="hl-4">setRenderTarget</span><span class="hl-1">(</span><span class="hl-8">null</span><span class="hl-1">);</span><br/><span class="hl-1">      </span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-5">fsQuad</span><span class="hl-1">.</span><span class="hl-4">render</span><span class="hl-1">(</span><span class="hl-5">renderer</span><span class="hl-1">);</span><br/><span class="hl-1">    } </span><span class="hl-11">else</span><span class="hl-1"> {</span><br/><span class="hl-1">      </span><span class="hl-7">// 否则渲染到 writeBuffer，供下一个 Pass 使用</span><br/><span class="hl-1">      </span><span class="hl-5">renderer</span><span class="hl-1">.</span><span class="hl-4">setRenderTarget</span><span class="hl-1">(</span><span class="hl-5">writeBuffer</span><span class="hl-1">);</span><br/><span class="hl-1">      </span><span class="hl-11">if</span><span class="hl-1"> (</span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-5">clear</span><span class="hl-1">) </span><span class="hl-5">renderer</span><span class="hl-1">.</span><span class="hl-4">clear</span><span class="hl-1">();</span><br/><span class="hl-1">      </span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-5">fsQuad</span><span class="hl-1">.</span><span class="hl-4">render</span><span class="hl-1">(</span><span class="hl-5">renderer</span><span class="hl-1">);</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-7">// 3. 挂载到 Five</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">grayPass</span><span class="hl-1"> = </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-4">GrayscalePass</span><span class="hl-1">();</span><br/><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">addPass</span><span class="hl-1">(</span><span class="hl-5">grayPass</span><span class="hl-1">);</span><br/><br/><span class="hl-7">// 触发重绘</span><br/><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">needsRender</span><span class="hl-1"> = </span><span class="hl-8">true</span><span class="hl-1">;</span>
 </code><button type="button">Copy</button></pre>
 <h3 id="使用-g-buffer-深度图示例" class="tsd-anchor-link">使用 G-Buffer (深度图示例)<a href="#使用-g-buffer-深度图示例" 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>如果你的 Pass 需要使用场景的深度信息（例如雾效），可以在构造函数中声明依赖。</p>
-<pre><code class="typescript"><span class="hl-3">class</span><span class="hl-1"> </span><span class="hl-7">FogPass</span><span class="hl-1"> </span><span class="hl-3">extends</span><span class="hl-1"> </span><span class="hl-7">FivePass</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-3">constructor</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-3">super</span><span class="hl-1">([</span><span class="hl-9">&#39;depth&#39;</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-5">render</span><span class="hl-1">(</span><span class="hl-6">renderer</span><span class="hl-1">, </span><span class="hl-6">writeBuffer</span><span class="hl-1">, </span><span class="hl-6">readBuffer</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-3">const</span><span class="hl-1"> </span><span class="hl-4">depthTexture</span><span class="hl-1"> = </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">gbuffer</span><span class="hl-1">.</span><span class="hl-5">get</span><span class="hl-1">(</span><span class="hl-9">&#39;depth&#39;</span><span class="hl-1">);</span><br/><br/><span class="hl-1">    </span><span class="hl-8">// 在 Shader 中使用 depthTexture ...</span><br/><span class="hl-1">    </span><span class="hl-8">// this.material.uniforms.tDepth.value = depthTexture;</span><br/><br/><span class="hl-1">    </span><span class="hl-8">// ... 渲染逻辑</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
+<pre><code class="typescript"><span class="hl-8">class</span><span class="hl-1"> </span><span class="hl-9">FogPass</span><span class="hl-1"> </span><span class="hl-8">extends</span><span class="hl-1"> </span><span class="hl-9">FivePass</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-8">constructor</span><span class="hl-1">() {</span><br/><span class="hl-1">    </span><span class="hl-8">super</span><span class="hl-1">([</span><span class="hl-10">&#39;depth&#39;</span><span class="hl-1">]); </span><span class="hl-7">// 声明需要深度图</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-4">render</span><span class="hl-1">(</span><span class="hl-5">renderer</span><span class="hl-1">, </span><span class="hl-5">writeBuffer</span><span class="hl-1">, </span><span class="hl-5">readBuffer</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-7">// 获取深度图</span><br/><span class="hl-1">    </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">depthTexture</span><span class="hl-1"> = </span><span class="hl-8">this</span><span class="hl-1">.</span><span class="hl-5">gbuffer</span><span class="hl-1">.</span><span class="hl-4">get</span><span class="hl-1">(</span><span class="hl-10">&#39;depth&#39;</span><span class="hl-1">);</span><br/><br/><span class="hl-1">    </span><span class="hl-7">// 在 Shader 中使用 depthTexture ...</span><br/><span class="hl-1">    </span><span class="hl-7">// this.material.uniforms.tDepth.value = depthTexture;</span><br/><br/><span class="hl-1">    </span><span class="hl-7">// ... 渲染逻辑</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 <h2 id="debugging" class="tsd-anchor-link">Debugging<a href="#debugging" 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_raycast.html CHANGED Viewed

@@ -10,7 +10,7 @@
 <p><strong>Definition</strong>: <a href="../../five/declare.d.ts">Raycaster</a></p>
 </blockquote>
 <p>Five 对 Three.js 的 <code>Raycaster</code> 进行了扩展，在 <code>declare module 'three'</code> 中增加了以下属性：</p>
-<pre><code class="typescript"><span class="hl-8">// defined in five/declare.d.ts</span><br/><span class="hl-3">declare</span><span class="hl-1"> </span><span class="hl-3">module</span><span class="hl-1"> </span><span class="hl-9">&#39;three&#39;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">Raycaster</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-8">/**</span><br/><span class="hl-8">     * 只捕获第一个焦点 (性能优化)</span><br/><span class="hl-8">     * - true: 找到第一个交点后立即停止检测，返回结果。</span><br/><span class="hl-8">     * - false (默认): 检测所有可能的交点。</span><br/><span class="hl-8">     */</span><br/><span class="hl-1">    </span><span class="hl-6">firstHitOnly</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-8">     * 自定义交点过滤器</span><br/><span class="hl-8">     * - 回调函数，返回 boolean。</span><br/><span class="hl-8">     * - true: 保留该交点。</span><br/><span class="hl-8">     * - false: 丢弃该交点。</span><br/><span class="hl-8">     */</span><br/><span class="hl-1">    </span><span class="hl-5">hitFilter</span><span class="hl-1">?: (</span><span class="hl-6">intersect</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Intersection</span><span class="hl-1">) </span><span class="hl-3">=&gt;</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-8">     * 是否由近及远排序</span><br/><span class="hl-8">     * - true (默认): 返回的结果数组按距离摄像机从近到远排序。</span><br/><span class="hl-8">     * - false: 结果顺序不确定（通常按遍历顺序）。</span><br/><span class="hl-8">     */</span><br/><span class="hl-1">    </span><span class="hl-6">sortByDistance</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-8">     * 作用楼层 (Five 特有逻辑)</span><br/><span class="hl-8">     * - 用于多楼层场景过滤。</span><br/><span class="hl-8">     */</span><br/><span class="hl-1">    </span><span class="hl-6">floorIndex</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">Intersection</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-8">/** 命中的具体 Tile 对象 (仅 3DTiles) */</span><br/><span class="hl-1">    </span><span class="hl-6">tile</span><span class="hl-1">?: </span><span class="hl-7">Tile</span><span class="hl-1">;</span><br/><span class="hl-1">    </span><span class="hl-8">/** 命中的 ViewLayer 对象 */</span><br/><span class="hl-1">    </span><span class="hl-6">viewLayer</span><span class="hl-1">?: </span><span class="hl-7">ViewLayer</span><span class="hl-1">;</span><br/><span class="hl-1">    </span><span class="hl-8">/** 命中的 Model 对象 */</span><br/><span class="hl-1">    </span><span class="hl-6">model</span><span class="hl-1">?: </span><span class="hl-7">Model</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-7">// defined in five/declare.d.ts</span><br/><span class="hl-8">declare</span><span class="hl-1"> </span><span class="hl-8">module</span><span class="hl-1"> </span><span class="hl-10">&#39;three&#39;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-11">export</span><span class="hl-1"> </span><span class="hl-8">interface</span><span class="hl-1"> </span><span class="hl-9">Raycaster</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-7">/**</span><br/><span class="hl-7">     * 只捕获第一个焦点 (性能优化)</span><br/><span class="hl-7">     * - true: 找到第一个交点后立即停止检测，返回结果。</span><br/><span class="hl-7">     * - false (默认): 检测所有可能的交点。</span><br/><span class="hl-7">     */</span><br/><span class="hl-1">    </span><span class="hl-5">firstHitOnly</span><span class="hl-1">?: </span><span class="hl-9">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1">    </span><span class="hl-7">/**</span><br/><span class="hl-7">     * 自定义交点过滤器</span><br/><span class="hl-7">     * - 回调函数，返回 boolean。</span><br/><span class="hl-7">     * - true: 保留该交点。</span><br/><span class="hl-7">     * - false: 丢弃该交点。</span><br/><span class="hl-7">     */</span><br/><span class="hl-1">    </span><span class="hl-4">hitFilter</span><span class="hl-1">?: (</span><span class="hl-5">intersect</span><span class="hl-1">: </span><span class="hl-9">THREE</span><span class="hl-1">.</span><span class="hl-9">Intersection</span><span class="hl-1">) </span><span class="hl-8">=&gt;</span><span class="hl-1"> </span><span class="hl-9">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1">    </span><span class="hl-7">/**</span><br/><span class="hl-7">     * 是否由近及远排序</span><br/><span class="hl-7">     * - true (默认): 返回的结果数组按距离摄像机从近到远排序。</span><br/><span class="hl-7">     * - false: 结果顺序不确定（通常按遍历顺序）。</span><br/><span class="hl-7">     */</span><br/><span class="hl-1">    </span><span class="hl-5">sortByDistance</span><span class="hl-1">?: </span><span class="hl-9">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1">    </span><span class="hl-7">/**</span><br/><span class="hl-7">     * 作用楼层 (Five 特有逻辑)</span><br/><span class="hl-7">     * - 用于多楼层场景过滤。</span><br/><span class="hl-7">     */</span><br/><span class="hl-1">    </span><span class="hl-5">floorIndex</span><span class="hl-1">?: </span><span class="hl-9">number</span><span class="hl-1">;</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-11">export</span><span class="hl-1"> </span><span class="hl-8">interface</span><span class="hl-1"> </span><span class="hl-9">Intersection</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-7">/** 命中的具体 Tile 对象 (仅 3DTiles) */</span><br/><span class="hl-1">    </span><span class="hl-5">tile</span><span class="hl-1">?: </span><span class="hl-9">Tile</span><span class="hl-1">;</span><br/><span class="hl-1">    </span><span class="hl-7">/** 命中的 ViewLayer 对象 */</span><br/><span class="hl-1">    </span><span class="hl-5">viewLayer</span><span class="hl-1">?: </span><span class="hl-9">ViewLayer</span><span class="hl-1">;</span><br/><span class="hl-1">    </span><span class="hl-7">/** 命中的 Model 对象 */</span><br/><span class="hl-1">    </span><span class="hl-5">model</span><span class="hl-1">?: </span><span class="hl-9">Model</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>
 <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>
@@ -62,17 +62,17 @@
 <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="基础用法：检测点击位置" 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>最常见的场景是将鼠标点击的屏幕坐标转换为 3D 空间中的点。</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-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-8">// ... 初始化 ...</span><br/><br/><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-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Raycaster</span><span class="hl-1">();</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">vector</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">Vector2</span><span class="hl-1">();</span><br/><br/><span class="hl-8">// 假设 onTap 是点击事件处理函数</span><br/><span class="hl-3">function</span><span class="hl-1"> </span><span class="hl-5">onTap</span><span class="hl-1">(</span><span class="hl-6">event</span><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-6">y</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">// 1. 将屏幕坐标转换为归一化设备坐标 (NDC)</span><br/><span class="hl-1">  </span><span class="hl-8">// 注意：five.getElement() 获取 canvas 容器</span><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">element</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">getElement</span><span class="hl-1">();</span><br/><span class="hl-1">  </span><span class="hl-10">if</span><span class="hl-1"> (!</span><span class="hl-6">element</span><span class="hl-1">) </span><span class="hl-10">return</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">rect</span><span class="hl-1"> = </span><span class="hl-6">element</span><span class="hl-1">.</span><span class="hl-5">getBoundingClientRect</span><span class="hl-1">();</span><br/><span class="hl-1">  </span><span class="hl-6">vector</span><span class="hl-1">.</span><span class="hl-6">x</span><span class="hl-1"> = ((</span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-6">x</span><span class="hl-1"> - </span><span class="hl-6">rect</span><span class="hl-1">.</span><span class="hl-6">left</span><span class="hl-1">) / </span><span class="hl-6">rect</span><span class="hl-1">.</span><span class="hl-6">width</span><span class="hl-1">) * </span><span class="hl-11">2</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-6">vector</span><span class="hl-1">.</span><span class="hl-6">y</span><span class="hl-1"> = -((</span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-6">y</span><span class="hl-1"> - </span><span class="hl-6">rect</span><span class="hl-1">.</span><span class="hl-6">top</span><span class="hl-1">) / </span><span class="hl-6">rect</span><span class="hl-1">.</span><span class="hl-6">height</span><span class="hl-1">) * </span><span class="hl-11">2</span><span class="hl-1"> + </span><span class="hl-11">1</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-6">raycaster</span><span class="hl-1">.</span><span class="hl-5">setFromCamera</span><span class="hl-1">(</span><span class="hl-6">vector</span><span class="hl-1">, </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">camera</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 3. 调用 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">firstHit</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-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&#39;点击到了模型:&#39;</span><span class="hl-1">, </span><span class="hl-6">firstHit</span><span class="hl-1">.</span><span class="hl-6">object</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">&#39;交点坐标 (世界坐标):&#39;</span><span class="hl-1">, </span><span class="hl-6">firstHit</span><span class="hl-1">.</span><span class="hl-6">point</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-11">import</span><span class="hl-1"> </span><span class="hl-8">*</span><span class="hl-1"> </span><span class="hl-11">as</span><span class="hl-1"> </span><span class="hl-5">THREE</span><span class="hl-1"> </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&#39;three&#39;</span><span class="hl-1">;</span><br/><span class="hl-11">import</span><span class="hl-1"> { </span><span class="hl-5">Five</span><span class="hl-1"> } </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1"> = </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-4">Five</span><span class="hl-1">();</span><br/><span class="hl-7">// ... 初始化 ...</span><br/><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">raycaster</span><span class="hl-1"> = </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1">.</span><span class="hl-4">Raycaster</span><span class="hl-1">();</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">vector</span><span class="hl-1"> = </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1">.</span><span class="hl-4">Vector2</span><span class="hl-1">();</span><br/><br/><span class="hl-7">// 假设 onTap 是点击事件处理函数</span><br/><span class="hl-8">function</span><span class="hl-1"> </span><span class="hl-4">onTap</span><span class="hl-1">(</span><span class="hl-5">event</span><span class="hl-1">: { </span><span class="hl-5">x</span><span class="hl-1">: </span><span class="hl-9">number</span><span class="hl-1">, </span><span class="hl-5">y</span><span class="hl-1">: </span><span class="hl-9">number</span><span class="hl-1"> }) {</span><br/><span class="hl-1">  </span><span class="hl-7">// 1. 将屏幕坐标转换为归一化设备坐标 (NDC)</span><br/><span class="hl-1">  </span><span class="hl-7">// 注意：five.getElement() 获取 canvas 容器</span><br/><span class="hl-1">  </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">element</span><span class="hl-1"> = </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">getElement</span><span class="hl-1">();</span><br/><span class="hl-1">  </span><span class="hl-11">if</span><span class="hl-1"> (!</span><span class="hl-5">element</span><span class="hl-1">) </span><span class="hl-11">return</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">rect</span><span class="hl-1"> = </span><span class="hl-5">element</span><span class="hl-1">.</span><span class="hl-4">getBoundingClientRect</span><span class="hl-1">();</span><br/><span class="hl-1">  </span><span class="hl-5">vector</span><span class="hl-1">.</span><span class="hl-5">x</span><span class="hl-1"> = ((</span><span class="hl-5">event</span><span class="hl-1">.</span><span class="hl-5">x</span><span class="hl-1"> - </span><span class="hl-5">rect</span><span class="hl-1">.</span><span class="hl-5">left</span><span class="hl-1">) / </span><span class="hl-5">rect</span><span class="hl-1">.</span><span class="hl-5">width</span><span class="hl-1">) * </span><span class="hl-3">2</span><span class="hl-1"> - </span><span class="hl-3">1</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-5">vector</span><span class="hl-1">.</span><span class="hl-5">y</span><span class="hl-1"> = -((</span><span class="hl-5">event</span><span class="hl-1">.</span><span class="hl-5">y</span><span class="hl-1"> - </span><span class="hl-5">rect</span><span class="hl-1">.</span><span class="hl-5">top</span><span class="hl-1">) / </span><span class="hl-5">rect</span><span class="hl-1">.</span><span class="hl-5">height</span><span class="hl-1">) * </span><span class="hl-3">2</span><span class="hl-1"> + </span><span class="hl-3">1</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// 2. 设置射线</span><br/><span class="hl-1">  </span><span class="hl-5">raycaster</span><span class="hl-1">.</span><span class="hl-4">setFromCamera</span><span class="hl-1">(</span><span class="hl-5">vector</span><span class="hl-1">, </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">camera</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// 3. 调用 Five 的检测方法</span><br/><span class="hl-1">  </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">intersects</span><span class="hl-1"> = </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">model</span><span class="hl-1">.</span><span class="hl-4">intersectRaycaster</span><span class="hl-1">(</span><span class="hl-5">raycaster</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-11">if</span><span class="hl-1"> (</span><span class="hl-5">intersects</span><span class="hl-1">.</span><span class="hl-5">length</span><span class="hl-1"> &gt; </span><span class="hl-3">0</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">firstHit</span><span class="hl-1"> = </span><span class="hl-5">intersects</span><span class="hl-1">[</span><span class="hl-3">0</span><span class="hl-1">];</span><br/><span class="hl-1">    </span><span class="hl-5">console</span><span class="hl-1">.</span><span class="hl-4">log</span><span class="hl-1">(</span><span class="hl-10">&#39;点击到了模型:&#39;</span><span class="hl-1">, </span><span class="hl-5">firstHit</span><span class="hl-1">.</span><span class="hl-5">object</span><span class="hl-1">);</span><br/><span class="hl-1">    </span><span class="hl-5">console</span><span class="hl-1">.</span><span class="hl-4">log</span><span class="hl-1">(</span><span class="hl-10">&#39;交点坐标 (世界坐标):&#39;</span><span class="hl-1">, </span><span class="hl-5">firstHit</span><span class="hl-1">.</span><span class="hl-5">point</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>
 <p>在进行如“地面检测”或“视线遮挡检测”时，通常只需要知道最近的交点。此时开启 <code>firstHitOnly</code> 可以显著提升性能。</p>
-<pre><code class="typescript"><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-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Raycaster</span><span class="hl-1">();</span><br/><span class="hl-6">raycaster</span><span class="hl-1">.</span><span class="hl-5">setFromCamera</span><span class="hl-1">(</span><span class="hl-6">mouseVector</span><span class="hl-1">, </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">camera</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 开启性能优化：找到最近的一个交点后立即停止</span><br/><span class="hl-6">raycaster</span><span class="hl-1">.</span><span class="hl-6">firstHitOnly</span><span class="hl-1"> = </span><span class="hl-3">true</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">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-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-8">// 处理最近的交点</span><br/><span class="hl-1">}</span>
+<pre><code class="typescript"><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">raycaster</span><span class="hl-1"> = </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1">.</span><span class="hl-4">Raycaster</span><span class="hl-1">();</span><br/><span class="hl-5">raycaster</span><span class="hl-1">.</span><span class="hl-4">setFromCamera</span><span class="hl-1">(</span><span class="hl-5">mouseVector</span><span class="hl-1">, </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">camera</span><span class="hl-1">);</span><br/><br/><span class="hl-7">// 开启性能优化：找到最近的一个交点后立即停止</span><br/><span class="hl-5">raycaster</span><span class="hl-1">.</span><span class="hl-5">firstHitOnly</span><span class="hl-1"> = </span><span class="hl-8">true</span><span class="hl-1">;</span><br/><br/><span class="hl-7">// 结果数组长度最多为 1</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">intersects</span><span class="hl-1"> = </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">model</span><span class="hl-1">.</span><span class="hl-4">intersectRaycaster</span><span class="hl-1">(</span><span class="hl-5">raycaster</span><span class="hl-1">);</span><br/><br/><span class="hl-11">if</span><span class="hl-1"> (</span><span class="hl-5">intersects</span><span class="hl-1">.</span><span class="hl-5">length</span><span class="hl-1"> &gt; </span><span class="hl-3">0</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-7">// 处理最近的交点</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>
 <p>如果你只想检测特定类型的物体（例如只检测地板，忽略天花板），可以使用 <code>hitFilter</code>。</p>
-<pre><code class="typescript"><span class="hl-6">raycaster</span><span class="hl-1">.</span><span class="hl-5">hitFilter</span><span class="hl-1"> = (</span><span class="hl-6">intersect</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">// 示例：假设地板的法线是向上的 (0, 1, 0)</span><br/><span class="hl-1">  </span><span class="hl-8">// 只保留法线朝上的交点（地板）</span><br/><span class="hl-1">  </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">intersect</span><span class="hl-1">.</span><span class="hl-6">face</span><span class="hl-1"> &amp;&amp; </span><span class="hl-6">intersect</span><span class="hl-1">.</span><span class="hl-6">face</span><span class="hl-1">.</span><span class="hl-6">normal</span><span class="hl-1">.</span><span class="hl-6">y</span><span class="hl-1"> &gt; </span><span class="hl-11">0.5</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-3">true</span><span class="hl-1">; </span><span class="hl-8">// 保留</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">  </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-3">false</span><span class="hl-1">; </span><span class="hl-8">// 丢弃</span><br/><span class="hl-1">};</span><br/><br/><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>
+<pre><code class="typescript"><span class="hl-5">raycaster</span><span class="hl-1">.</span><span class="hl-4">hitFilter</span><span class="hl-1"> = (</span><span class="hl-5">intersect</span><span class="hl-1">) </span><span class="hl-8">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-7">// 示例：假设地板的法线是向上的 (0, 1, 0)</span><br/><span class="hl-1">  </span><span class="hl-7">// 只保留法线朝上的交点（地板）</span><br/><span class="hl-1">  </span><span class="hl-11">if</span><span class="hl-1"> (</span><span class="hl-5">intersect</span><span class="hl-1">.</span><span class="hl-5">face</span><span class="hl-1"> &amp;&amp; </span><span class="hl-5">intersect</span><span class="hl-1">.</span><span class="hl-5">face</span><span class="hl-1">.</span><span class="hl-5">normal</span><span class="hl-1">.</span><span class="hl-5">y</span><span class="hl-1"> &gt; </span><span class="hl-3">0.5</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-11">return</span><span class="hl-1"> </span><span class="hl-8">true</span><span class="hl-1">; </span><span class="hl-7">// 保留</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">  </span><span class="hl-11">return</span><span class="hl-1"> </span><span class="hl-8">false</span><span class="hl-1">; </span><span class="hl-7">// 丢弃</span><br/><span class="hl-1">};</span><br/><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">intersects</span><span class="hl-1"> = </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">model</span><span class="hl-1">.</span><span class="hl-4">intersectRaycaster</span><span class="hl-1">(</span><span class="hl-5">raycaster</span><span class="hl-1">);</span>
 </code><button type="button">Copy</button></pre>
 <h2 id="debugging" class="tsd-anchor-link">Debugging<a href="#debugging" 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>