UNPKG

@realsee/five

Version:

Realsee Renderer SDK

273 lines • 77.5 kB
<!DOCTYPE html><html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>features/flowing-light-2d-pass | 如视 Five SDK</title><meta name="description" content="Documentation for 如视 Five SDK"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script><script async src="../assets/hierarchy.js" id="tsd-hierarchy-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="../index.html" class="title">如视 Five SDK</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="" aria-current="page">features/flowing-light-2d-pass</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="flowing-light-2d-pass-流光-2d-通道" class="tsd-anchor-link">Flowing Light 2D Pass (流光 2D 通道)<a href="#flowing-light-2d-pass-流光-2d-通道" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h1>
<ul>
<li><strong>Summary</strong>: <code>FlowingLight2DPass</code> 提供屏幕空间的流光(光带)特效,使用 InstancedMesh 实例化渲染优化性能,沿着 2D 归一化坐标路径绘制动态光流,适用于突出导航路径、指示线或动态路径演示。</li>
<li><strong>Schema</strong>: <code>FlowingLight2DPass</code> 类及 Line 数据结构。</li>
<li><strong>Concepts</strong>: 后处理通道、屏幕空间光带、InstancedMesh 实例化渲染、归一化坐标系统、头尾追逐动画。</li>
<li><strong>Configuration</strong>: 归一化路径点、颜色、不透明度、线宽、动画时长、延迟。</li>
<li><strong>Examples</strong>: 基础集成、多条路径、动态更新、高 DPR 场景优化。</li>
</ul>
<h2 id="schema" class="tsd-anchor-link">Schema<a href="#schema" 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>
<blockquote>
<p><strong>Definition</strong>: <a href="../../five/renderer/postprocessing/passes/flowing-light-2d-pass.d.ts">FlowingLight2DPass</a></p>
</blockquote>
<p><code>FlowingLight2DPass</code> 是 <code>FivePass</code> 的子类,核心接口如下:</p>
<pre><code class="ts"><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">FivePass</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;./pass&#39;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-10">type</span><span class="hl-1"> </span><span class="hl-6">Camera</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;../../../core/camera&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">type</span><span class="hl-1"> </span><span class="hl-7">Line</span><span class="hl-1"> = {</span><br/><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-8">// 可选的唯一标识符,不传则自动生成 UUID</span><br/><span class="hl-1">  </span><span class="hl-6">points</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Vector2</span><span class="hl-1">[];      </span><span class="hl-8">// 归一化坐标路径点 [0, 1]</span><br/><span class="hl-1">  </span><span class="hl-6">totalLength</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">;           </span><span class="hl-8">// 路径总长度(归一化单位)</span><br/><span class="hl-1">  </span><span class="hl-6">color</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Color</span><span class="hl-1">;            </span><span class="hl-8">// 光带颜色</span><br/><span class="hl-1">  </span><span class="hl-6">opacity</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;              </span><span class="hl-8">// 光带不透明度(0-1)</span><br/><span class="hl-1">  </span><span class="hl-6">duration</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;             </span><span class="hl-8">// 动画时长(毫秒)</span><br/><span class="hl-1">  </span><span class="hl-6">startTime</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;            </span><span class="hl-8">// 线条开始时间(毫秒),默认使用当前内部时间</span><br/><span class="hl-1">  </span><span class="hl-6">lineWidth</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;            </span><span class="hl-8">// 线宽(归一化单位)</span><br/><span class="hl-1">  </span><span class="hl-6">tailLengthRatio</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;      </span><span class="hl-8">// 尾巴长度比例(0-1),默认 0.2</span><br/><span class="hl-1">};</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">FlowingLight2DPass</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><span class="hl-6">camera</span><span class="hl-1">: </span><span class="hl-7">Camera</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 批量设置路径列表(替换所有现有线条)</span><br/><span class="hl-1">  </span><span class="hl-3">public</span><span class="hl-1"> </span><span class="hl-5">setLines</span><span class="hl-1">(</span><span class="hl-6">lines</span><span class="hl-1">: </span><span class="hl-7">Line</span><span class="hl-1">[]): </span><span class="hl-7">void</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 追加一条或多条线,返回生成的 id 数组</span><br/><span class="hl-1">  </span><span class="hl-3">public</span><span class="hl-1"> </span><span class="hl-5">addLine</span><span class="hl-1">(...</span><span class="hl-6">lines</span><span class="hl-1">: </span><span class="hl-7">Line</span><span class="hl-1">[]): </span><span class="hl-7">string</span><span class="hl-1">[];</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 按 id 移除一条或多条线,返回实际移除的数量</span><br/><span class="hl-1">  </span><span class="hl-3">public</span><span class="hl-1"> </span><span class="hl-5">removeLine</span><span class="hl-1">(...</span><span class="hl-6">ids</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">[]): </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 修改单条线的参数(通过 id),支持部分更新</span><br/><span class="hl-1">  </span><span class="hl-3">public</span><span class="hl-1"> </span><span class="hl-5">setLine</span><span class="hl-1">(</span><span class="hl-6">params</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"> } &amp; </span><span class="hl-7">Partial</span><span class="hl-1">&lt;</span><span class="hl-7">Omit</span><span class="hl-1">&lt;</span><span class="hl-7">Line</span><span class="hl-1">, </span><span class="hl-9">&#39;id&#39;</span><span class="hl-1">&gt;&gt;): </span><span class="hl-7">void</span><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">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><span class="hl-1">,</span><br/><span class="hl-1">  ): </span><span class="hl-7">void</span><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-7">void</span><span class="hl-1">;</span><br/><span class="hl-1">}</span>
</code><button type="button">Copy</button></pre>

<h2 id="concepts" class="tsd-anchor-link">Concepts<a href="#concepts" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<h3 id="instancedmesh-实例化渲染-instanced-rendering" class="tsd-anchor-link">InstancedMesh 实例化渲染 (Instanced Rendering)<a href="#instancedmesh-实例化渲染-instanced-rendering" 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>为了优化高 DPR(Device Pixel Ratio)场景下的性能,该 Pass 使用 InstancedMesh 代替全屏着色器。每个线段作为一个实例,只渲染线段覆盖的区域,避免了对每个像素的全屏检查,显著提升了渲染效率。</p>
<h3 id="归一化坐标系统-normalized-coordinates" class="tsd-anchor-link">归一化坐标系统 (Normalized Coordinates)<a href="#归一化坐标系统-normalized-coordinates" 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>[0, 1]</code> 定义:</p>
<ul>
<li><code>(0, 0)</code> 表示屏幕左上角</li>
<li><code>(1, 1)</code> 表示屏幕右下角</li>
<li><code>(0.5, 0.5)</code> 表示屏幕中心</li>
</ul>
<p>这种坐标系统与屏幕分辨率无关,自动适配不同尺寸和 DPR。</p>
<h3 id="头尾追逐动画-head-tail-chase-animation" class="tsd-anchor-link">头尾追逐动画 (Head-Tail Chase Animation)<a href="#头尾追逐动画-head-tail-chase-animation" 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>流光效果采用&quot;头尾追逐&quot;模式:</p>
<ul>
<li><strong>头部(Head)</strong>: 光流的前端,沿路径循环移动</li>
<li><strong>尾部(Tail)</strong>: 光流的后端,跟随头部移动</li>
<li><strong>渐变</strong>: 从尾部(透明度 0)到头部(透明度 1)线性渐变</li>
<li><strong>尾长</strong>: 尾部长度由 <code>tailLengthRatio</code> 参数控制(默认 0.2,即路径总长的 20%)</li>
</ul>
<p>光头在路径上循环流动,通过像素空间投影计算每个像素的渐变位置,确保渐变效果准确。尾巴长度会在动画开始时逐渐增长,直到达到 <code>tailLengthRatio * totalLength</code>。</p>
<h3 id="ndc-坐标转换" class="tsd-anchor-link">NDC 坐标转换<a href="#ndc-坐标转换" 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>[0, 1]</code> 会转换为 NDC(Normalized Device Coordinates) <code>[-1, 1]</code>,与 WebGL 标准坐标系统一致,确保投影计算准确。</p>
<h3 id="dpr-处理与宽高比适配" class="tsd-anchor-link">DPR 处理与宽高比适配<a href="#dpr-处理与宽高比适配" 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>自动处理高 DPR 场景和不同屏幕宽高比:</p>
<ul>
<li><strong>DPR 补偿</strong>: 通过 <code>uPixelRatio</code> uniform 自动补偿高 DPR 设备的光线宽度,确保在 Retina 等高分辨率屏幕上视觉一致</li>
<li><strong>像素空间计算</strong>: 所有距离计算在像素空间进行,而非 NDC 空间,确保横向和纵向光线宽度在任何宽高比下都保持一致</li>
<li><strong>各向同性渲染</strong>: 无论屏幕是横屏、竖屏还是方形,光线的扩散效果在各个方向上都保持相同</li>
</ul>
<h2 id="configuration" class="tsd-anchor-link">Configuration<a href="#configuration" 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="line-配置参数" class="tsd-anchor-link">Line 配置参数<a href="#line-配置参数" 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>
<table>
<thead>
<tr>
<th style="text-align:left">Parameter</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Required</th>
<th style="text-align:left">Default</th>
<th style="text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>id</code></td>
<td style="text-align:left"><code>string</code></td>
<td style="text-align:left"></td>
<td style="text-align:left">自动生成 UUID</td>
<td style="text-align:left">唯一标识符,用于 <code>setLine</code> 方法更新单条线。</td>
</tr>
<tr>
<td style="text-align:left"><code>points</code></td>
<td style="text-align:left"><code>THREE.Vector2[]</code></td>
<td style="text-align:left">✓</td>
<td style="text-align:left">-</td>
<td style="text-align:left">归一化坐标路径点数组 [0, 1]。至少 2 个点。</td>
</tr>
<tr>
<td style="text-align:left"><code>totalLength</code></td>
<td style="text-align:left"><code>number</code></td>
<td style="text-align:left">✓</td>
<td style="text-align:left">-</td>
<td style="text-align:left">路径总长度(归一化单位)。通常为所有相邻点间距离之和。</td>
</tr>
<tr>
<td style="text-align:left"><code>color</code></td>
<td style="text-align:left"><code>THREE.Color</code></td>
<td style="text-align:left">✓</td>
<td style="text-align:left">-</td>
<td style="text-align:left">光带颜色(RGB)。</td>
</tr>
<tr>
<td style="text-align:left"><code>opacity</code></td>
<td style="text-align:left"><code>number</code></td>
<td style="text-align:left"></td>
<td style="text-align:left"><code>1.0</code></td>
<td style="text-align:left">光带不透明度(0-1)。控制与背景的混合强度。</td>
</tr>
<tr>
<td style="text-align:left"><code>duration</code></td>
<td style="text-align:left"><code>number</code></td>
<td style="text-align:left"></td>
<td style="text-align:left"><code>1000</code></td>
<td style="text-align:left">动画周期(毫秒)。光头从路径起点完成一个周期的时长。</td>
</tr>
<tr>
<td style="text-align:left"><code>startTime</code></td>
<td style="text-align:left"><code>number</code></td>
<td style="text-align:left"></td>
<td style="text-align:left">当前内部时间</td>
<td style="text-align:left">线条开始时间(毫秒)。控制线条动画从何时开始播放,可用于多条线错开起始时间。</td>
</tr>
<tr>
<td style="text-align:left"><code>lineWidth</code></td>
<td style="text-align:left"><code>number</code></td>
<td style="text-align:left"></td>
<td style="text-align:left"><code>0.01</code></td>
<td style="text-align:left">线宽(归一化单位)。控制光带在屏幕上的宽度。</td>
</tr>
<tr>
<td style="text-align:left"><code>tailLengthRatio</code></td>
<td style="text-align:left"><code>number</code></td>
<td style="text-align:left"></td>
<td style="text-align:left"><code>0.2</code></td>
<td style="text-align:left">尾巴长度比例(0-1)。控制流光尾巴相对于路径总长的比例。</td>
</tr>
</tbody>
</table>
<blockquote>
<p><strong>注意</strong>: <code>totalLength</code> 和 <code>lineWidth</code> 使用归一化单位,与屏幕实际像素无关。</p>
</blockquote>
<h2 id="instance-methods" class="tsd-anchor-link">Instance Methods<a href="#instance-methods" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<h3 id="_" class="tsd-anchor-link"><code>constructor(camera: Camera)</code><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>初始化 Pass,需传入相机以获取屏幕分辨率。</p>
<h3 id="_-1" class="tsd-anchor-link"><code>setLines(lines: Line[])</code><a href="#_-1" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>批量设置路径列表,替换所有现有线条。可随时调用以修改或新增路径。</p>
<p><strong>自动生成 ID</strong>: 如果 line 没有提供 <code>id</code>,会自动生成 UUID。
<strong>自动设置 startTime</strong>: 如果 line 没有提供 <code>startTime</code>,会使用当前内部时间。</p>
<p><strong>示例</strong>:</p>
<pre><code class="ts"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">pathLine</span><span class="hl-1">: </span><span class="hl-7">Line</span><span class="hl-1"> = {</span><br/><span class="hl-1">  </span><span class="hl-6">id:</span><span class="hl-1"> </span><span class="hl-9">&#39;my-line-1&#39;</span><span class="hl-1">,  </span><span class="hl-8">// 可选,不传则自动生成</span><br/><span class="hl-1">  </span><span class="hl-6">points:</span><span class="hl-1"> [</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.3</span><span class="hl-1">, </span><span class="hl-11">0.7</span><span class="hl-1">),</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.7</span><span class="hl-1">, </span><span class="hl-11">0.7</span><span class="hl-1">),</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.7</span><span class="hl-1">, </span><span class="hl-11">0.3</span><span class="hl-1">),</span><br/><span class="hl-1">  ],</span><br/><span class="hl-1">  </span><span class="hl-6">totalLength:</span><span class="hl-1"> </span><span class="hl-11">0.8</span><span class="hl-1">,  </span><span class="hl-8">// 归一化单位</span><br/><span class="hl-1">  </span><span class="hl-6">color:</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">Color</span><span class="hl-1">(</span><span class="hl-11">0x00c2ff</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-6">opacity:</span><span class="hl-1"> </span><span class="hl-11">0.8</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">2000</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">startTime:</span><span class="hl-1"> </span><span class="hl-11">500</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">lineWidth:</span><span class="hl-1"> </span><span class="hl-11">0.01</span><span class="hl-1">,</span><br/><span class="hl-1">};</span><br/><span class="hl-6">pass</span><span class="hl-1">.</span><span class="hl-5">setLines</span><span class="hl-1">([</span><span class="hl-6">pathLine</span><span class="hl-1">]);</span>
</code><button type="button">Copy</button></pre>

<h3 id="_-2" class="tsd-anchor-link"><code>addLine(...lines: Line[]): string[]</code><a href="#_-2" 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>追加一条或多条线到现有列表中,不影响已有线条。返回新增线条的 id 数组。</p>
<p><strong>示例</strong>:</p>
<pre><code class="ts"><span class="hl-8">// 追加单条线</span><br/><span class="hl-3">const</span><span class="hl-1"> [</span><span class="hl-4">id1</span><span class="hl-1">] = </span><span class="hl-6">pass</span><span class="hl-1">.</span><span class="hl-5">addLine</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-6">points:</span><span class="hl-1"> [</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.1</span><span class="hl-1">, </span><span class="hl-11">0.1</span><span class="hl-1">),</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.9</span><span class="hl-1">, </span><span class="hl-11">0.9</span><span class="hl-1">),</span><br/><span class="hl-1">  ],</span><br/><span class="hl-1">  </span><span class="hl-6">totalLength:</span><span class="hl-1"> </span><span class="hl-11">1.13</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-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Color</span><span class="hl-1">(</span><span class="hl-11">0xff0000</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">2000</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// 追加多条线</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">ids</span><span class="hl-1"> = </span><span class="hl-6">pass</span><span class="hl-1">.</span><span class="hl-5">addLine</span><span class="hl-1">(</span><br/><span class="hl-1">  {</span><br/><span class="hl-1">    </span><span class="hl-6">points:</span><span class="hl-1"> [...],</span><br/><span class="hl-1">    </span><span class="hl-6">totalLength:</span><span class="hl-1"> </span><span class="hl-11">0.8</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-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Color</span><span class="hl-1">(</span><span class="hl-11">0x00ff00</span><span class="hl-1">),</span><br/><span class="hl-1">    </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">1500</span><span class="hl-1">,</span><br/><span class="hl-1">  },</span><br/><span class="hl-1">  {</span><br/><span class="hl-1">    </span><span class="hl-6">points:</span><span class="hl-1"> [...],</span><br/><span class="hl-1">    </span><span class="hl-6">totalLength:</span><span class="hl-1"> </span><span class="hl-11">1.2</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-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Color</span><span class="hl-1">(</span><span class="hl-11">0x0000ff</span><span class="hl-1">),</span><br/><span class="hl-1">    </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">1800</span><span class="hl-1">,</span><br/><span class="hl-1">  },</span><br/><span class="hl-1">);</span><br/><span class="hl-8">// ids = [&#39;uuid-1&#39;, &#39;uuid-2&#39;]</span>
</code><button type="button">Copy</button></pre>

<h3 id="_-3" class="tsd-anchor-link"><code>removeLine(...ids: string[]): number</code><a href="#_-3" 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>按 id 移除一条或多条线,返回实际移除的数量。如果 id 不存在,会在控制台输出警告。</p>
<p><strong>示例</strong>:</p>
<pre><code class="ts"><span class="hl-8">// 移除单条线</span><br/><span class="hl-6">pass</span><span class="hl-1">.</span><span class="hl-5">removeLine</span><span class="hl-1">(</span><span class="hl-6">id1</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 移除多条线</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">removedCount</span><span class="hl-1"> = </span><span class="hl-6">pass</span><span class="hl-1">.</span><span class="hl-5">removeLine</span><span class="hl-1">(</span><span class="hl-6">id1</span><span class="hl-1">, </span><span class="hl-6">id2</span><span class="hl-1">, </span><span class="hl-6">id3</span><span class="hl-1">);</span><br/><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">`移除了 </span><span class="hl-3">${</span><span class="hl-6">removedCount</span><span class="hl-3">}</span><span class="hl-9"> 条线`</span><span class="hl-1">);</span>
</code><button type="button">Copy</button></pre>

<h3 id="_-4" class="tsd-anchor-link"><code>setLine(params: { id: string } &amp; Partial&lt;Omit&lt;Line, 'id'&gt;&gt;)</code><a href="#_-4" 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>id</code> 修改单条线的参数。支持部分更新,只更新传入的字段。</p>
<p><strong>性能优化</strong>:</p>
<ul>
<li>如果 <code>points</code> 数量不变,只更新 GPU 的 instance attributes,性能极高</li>
<li>如果 <code>points</code> 数量改变,会重建整个 mesh,性能开销较大</li>
</ul>
<p><strong>示例</strong>:</p>
<pre><code class="ts"><span class="hl-8">// 只修改颜色 - 高性能</span><br/><span class="hl-6">pass</span><span class="hl-1">.</span><span class="hl-5">setLine</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-6">id:</span><span class="hl-1"> </span><span class="hl-9">&#39;my-line-1&#39;</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-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Color</span><span class="hl-1">(</span><span class="hl-11">0xff0000</span><span class="hl-1">),</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// 修改多个属性 - 高性能</span><br/><span class="hl-6">pass</span><span class="hl-1">.</span><span class="hl-5">setLine</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-6">id:</span><span class="hl-1"> </span><span class="hl-9">&#39;my-line-1&#39;</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-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Color</span><span class="hl-1">(</span><span class="hl-11">0x00ff00</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-6">opacity:</span><span class="hl-1"> </span><span class="hl-11">0.5</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">3000</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// 修改 points (相同数量) - 高性能</span><br/><span class="hl-6">pass</span><span class="hl-1">.</span><span class="hl-5">setLine</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-6">id:</span><span class="hl-1"> </span><span class="hl-9">&#39;my-line-1&#39;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">points:</span><span class="hl-1"> [</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.2</span><span class="hl-1">, </span><span class="hl-11">0.2</span><span class="hl-1">),</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.8</span><span class="hl-1">, </span><span class="hl-11">0.8</span><span class="hl-1">),</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.8</span><span class="hl-1">, </span><span class="hl-11">0.2</span><span class="hl-1">),</span><br/><span class="hl-1">  ],  </span><span class="hl-8">// 仍是 3 个点</span><br/><span class="hl-1">  </span><span class="hl-6">totalLength:</span><span class="hl-1"> </span><span class="hl-11">1.2</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// 修改 points (不同数量) - 会重建 mesh</span><br/><span class="hl-6">pass</span><span class="hl-1">.</span><span class="hl-5">setLine</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-6">id:</span><span class="hl-1"> </span><span class="hl-9">&#39;my-line-1&#39;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">points:</span><span class="hl-1"> [</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.2</span><span class="hl-1">, </span><span class="hl-11">0.2</span><span class="hl-1">),</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.8</span><span class="hl-1">, </span><span class="hl-11">0.8</span><span class="hl-1">),</span><br/><span class="hl-1">  ],  </span><span class="hl-8">// 从 3 个点变为 2 个点</span><br/><span class="hl-1">  </span><span class="hl-6">totalLength:</span><span class="hl-1"> </span><span class="hl-11">0.85</span><span class="hl-1">,</span><br/><span class="hl-1">});</span>
</code><button type="button">Copy</button></pre>

<p><strong>注意事项</strong>:</p>
<ul>
<li>如果 <code>id</code> 不存在,会在控制台输出警告</li>
<li>动画时间(<code>uTime</code>)不会被重置,流光继续从当前位置播放</li>
<li>建议修改 <code>points</code> 时同时更新 <code>totalLength</code></li>
</ul>
<h3 id="_-5" class="tsd-anchor-link"><code>render(...)</code><a href="#_-5" 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>由 EffectComposer 自动调用,无需手动调用。自动同步渲染目标尺寸。</p>
<h3 id="_-6" class="tsd-anchor-link"><code>dispose()</code><a href="#_-6" 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>释放 InstancedMesh、着色材质和渲染目标资源,避免内存泄漏。销毁 Pass 时必须调用。</p>
<h2 id="examples" class="tsd-anchor-link">Examples<a href="#examples" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<h3 id="快速上手-quick-example" class="tsd-anchor-link">快速上手 (Quick Example)<a href="#快速上手-quick-example" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<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/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">FlowingLight2DPass</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;../../lib/five/renderer/postprocessing&#39;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;three&#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">// 创建 2D 流光通道</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">flowing2D</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">FlowingLight2DPass</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-3">const</span><span class="hl-1"> </span><span class="hl-4">path</span><span class="hl-1"> = [</span><br/><span class="hl-1">  </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.2</span><span class="hl-1">, </span><span class="hl-11">0.2</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.5</span><span class="hl-1">, </span><span class="hl-11">0.8</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.8</span><span class="hl-1">, </span><span class="hl-11">0.2</span><span class="hl-1">),</span><br/><span class="hl-1">];</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">totalLen</span><span class="hl-1"> = </span><span class="hl-11">1.2</span><span class="hl-1">; </span><span class="hl-8">// 归一化单位</span><br/><br/><span class="hl-6">flowing2D</span><span class="hl-1">.</span><span class="hl-5">setLines</span><span class="hl-1">([{</span><br/><span class="hl-1">  </span><span class="hl-6">points:</span><span class="hl-1"> </span><span class="hl-6">path</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">totalLength:</span><span class="hl-1"> </span><span class="hl-6">totalLen</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-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Color</span><span class="hl-1">(</span><span class="hl-11">0x00ff00</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-6">opacity:</span><span class="hl-1"> </span><span class="hl-11">0.9</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">2000</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">lineWidth:</span><span class="hl-1"> </span><span class="hl-11">0.01</span><span class="hl-1">,</span><br/><span class="hl-1">}]);</span><br/><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">flowing2D</span><span class="hl-1">);</span><br/><br/><span class="hl-3">function</span><span class="hl-1"> </span><span class="hl-5">animate</span><span class="hl-1">() {</span><br/><span class="hl-1">  </span><span class="hl-5">requestAnimationFrame</span><span class="hl-1">(</span><span class="hl-6">animate</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">render</span><span class="hl-1">();</span><br/><span class="hl-1">}</span><br/><span class="hl-5">animate</span><span class="hl-1">();</span>
</code><button type="button">Copy</button></pre>

<h3 id="多条路径-动态更新" class="tsd-anchor-link">多条路径 &amp; 动态更新<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>
<pre><code class="typescript"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">pass</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">FlowingLight2DPass</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-3">const</span><span class="hl-1"> </span><span class="hl-4">paths</span><span class="hl-1"> = [</span><br/><span class="hl-1">  {</span><br/><span class="hl-1">    </span><span class="hl-6">points:</span><span class="hl-1"> [</span><br/><span class="hl-1">      </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.1</span><span class="hl-1">, </span><span class="hl-11">0.1</span><span class="hl-1">),</span><br/><span class="hl-1">      </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.9</span><span class="hl-1">, </span><span class="hl-11">0.1</span><span class="hl-1">),</span><br/><span class="hl-1">    ],</span><br/><span class="hl-1">    </span><span class="hl-6">totalLength:</span><span class="hl-1"> </span><span class="hl-11">0.8</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-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Color</span><span class="hl-1">(</span><span class="hl-11">0xff6600</span><span class="hl-1">),</span><br/><span class="hl-1">    </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">1500</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">lineWidth:</span><span class="hl-1"> </span><span class="hl-11">0.01</span><span class="hl-1">,</span><br/><span class="hl-1">  },</span><br/><span class="hl-1">  {</span><br/><span class="hl-1">    </span><span class="hl-6">points:</span><span class="hl-1"> [</span><br/><span class="hl-1">      </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.1</span><span class="hl-1">, </span><span class="hl-11">0.5</span><span class="hl-1">),</span><br/><span class="hl-1">      </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.9</span><span class="hl-1">, </span><span class="hl-11">0.5</span><span class="hl-1">),</span><br/><span class="hl-1">    ],</span><br/><span class="hl-1">    </span><span class="hl-6">totalLength:</span><span class="hl-1"> </span><span class="hl-11">0.8</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-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Color</span><span class="hl-1">(</span><span class="hl-11">0x0066ff</span><span class="hl-1">),</span><br/><span class="hl-1">    </span><span class="hl-6">opacity:</span><span class="hl-1"> </span><span class="hl-11">0.7</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">2000</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">startTime:</span><span class="hl-1"> </span><span class="hl-11">500</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">lineWidth:</span><span class="hl-1"> </span><span class="hl-11">0.015</span><span class="hl-1">,</span><br/><span class="hl-1">  },</span><br/><span class="hl-1">];</span><br/><br/><span class="hl-6">pass</span><span class="hl-1">.</span><span class="hl-5">setLines</span><span class="hl-1">(</span><span class="hl-6">paths</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">pass</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 响应用户交互动态更新路径</span><br/><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-5">addEventListener</span><span class="hl-1">(</span><span class="hl-9">&#39;click&#39;</span><span class="hl-1">, (</span><span class="hl-6">e</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">const</span><span class="hl-1"> </span><span class="hl-4">rect</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">canvas</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-3">const</span><span class="hl-1"> </span><span class="hl-4">x</span><span class="hl-1"> = (</span><span class="hl-6">e</span><span class="hl-1">.</span><span class="hl-6">clientX</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><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">y</span><span class="hl-1"> = (</span><span class="hl-6">e</span><span class="hl-1">.</span><span class="hl-6">clientY</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-8">// 左上角为原点,无需翻转</span><br/><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">newPath</span><span class="hl-1"> = {</span><br/><span class="hl-1">    </span><span class="hl-6">points:</span><span class="hl-1"> [</span><br/><span class="hl-1">      </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.5</span><span class="hl-1">, </span><span class="hl-11">0.5</span><span class="hl-1">),</span><br/><span class="hl-1">      </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-6">x</span><span class="hl-1">, </span><span class="hl-6">y</span><span class="hl-1">),</span><br/><span class="hl-1">    ],</span><br/><span class="hl-1">    </span><span class="hl-6">totalLength:</span><span class="hl-1"> </span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-5">hypot</span><span class="hl-1">(</span><span class="hl-6">x</span><span class="hl-1"> - </span><span class="hl-11">0.5</span><span class="hl-1">, </span><span class="hl-6">y</span><span class="hl-1"> - </span><span class="hl-11">0.5</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-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Color</span><span class="hl-1">(</span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-5">random</span><span class="hl-1">() * </span><span class="hl-11">0xffffff</span><span class="hl-1">),</span><br/><span class="hl-1">    </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">1200</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">lineWidth:</span><span class="hl-1"> </span><span class="hl-11">0.01</span><span class="hl-1">,</span><br/><span class="hl-1">  };</span><br/><span class="hl-1">  </span><span class="hl-6">pass</span><span class="hl-1">.</span><span class="hl-5">setLines</span><span class="hl-1">([...</span><span class="hl-6">paths</span><span class="hl-1">, </span><span class="hl-6">newPath</span><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>
<pre><code class="typescript"><span class="hl-3">function</span><span class="hl-1"> </span><span class="hl-5">calculatePathLength</span><span class="hl-1">(</span><span class="hl-6">points</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Vector2</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-3">let</span><span class="hl-1"> </span><span class="hl-6">length</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-10">for</span><span class="hl-1"> (</span><span class="hl-3">let</span><span class="hl-1"> </span><span class="hl-6">i</span><span class="hl-1"> = </span><span class="hl-11">1</span><span class="hl-1">; </span><span class="hl-6">i</span><span class="hl-1"> &lt; </span><span class="hl-6">points</span><span class="hl-1">.</span><span class="hl-6">length</span><span class="hl-1">; </span><span class="hl-6">i</span><span class="hl-1">++) {</span><br/><span class="hl-1">    </span><span class="hl-6">length</span><span class="hl-1"> += </span><span class="hl-6">points</span><span class="hl-1">[</span><span class="hl-6">i</span><span class="hl-1">].</span><span class="hl-5">distanceTo</span><span class="hl-1">(</span><span class="hl-6">points</span><span class="hl-1">[</span><span class="hl-6">i</span><span class="hl-1"> - </span><span class="hl-11">1</span><span class="hl-1">]);</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-6">length</span><span class="hl-1">;</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">points</span><span class="hl-1"> = [</span><br/><span class="hl-1">  </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.3</span><span class="hl-1">, </span><span class="hl-11">0.7</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.7</span><span class="hl-1">, </span><span class="hl-11">0.7</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.7</span><span class="hl-1">, </span><span class="hl-11">0.3</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.3</span><span class="hl-1">, </span><span class="hl-11">0.3</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.3</span><span class="hl-1">, </span><span class="hl-11">0.7</span><span class="hl-1">),</span><br/><span class="hl-1">];</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">pathLine</span><span class="hl-1"> = {</span><br/><span class="hl-1">  </span><span class="hl-6">points:</span><span class="hl-1"> </span><span class="hl-6">points</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">totalLength:</span><span class="hl-1"> </span><span class="hl-5">calculatePathLength</span><span class="hl-1">(</span><span class="hl-6">points</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-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Color</span><span class="hl-1">(</span><span class="hl-11">0x00ffff</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">2000</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">lineWidth:</span><span class="hl-1"> </span><span class="hl-11">0.01</span><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>
<pre><code class="ts"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">pass</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">FlowingLight2DPass</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-3">const</span><span class="hl-1"> </span><span class="hl-4">rectPath</span><span class="hl-1"> = {</span><br/><span class="hl-1">  </span><span class="hl-6">points:</span><span class="hl-1"> [</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.3</span><span class="hl-1">, </span><span class="hl-11">0.3</span><span class="hl-1">),  </span><span class="hl-8">// 左上</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.7</span><span class="hl-1">, </span><span class="hl-11">0.3</span><span class="hl-1">),  </span><span class="hl-8">// 右上</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.7</span><span class="hl-1">, </span><span class="hl-11">0.7</span><span class="hl-1">),  </span><span class="hl-8">// 右下</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.3</span><span class="hl-1">, </span><span class="hl-11">0.7</span><span class="hl-1">),  </span><span class="hl-8">// 左下</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.3</span><span class="hl-1">, </span><span class="hl-11">0.3</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-6">totalLength:</span><span class="hl-1"> </span><span class="hl-11">1.6</span><span class="hl-1">, </span><span class="hl-8">// 矩形周长</span><br/><span class="hl-1">  </span><span class="hl-6">color:</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">Color</span><span class="hl-1">(</span><span class="hl-11">1.0</span><span class="hl-1">, </span><span class="hl-11">1.0</span><span class="hl-1">, </span><span class="hl-11">1.0</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-6">opacity:</span><span class="hl-1"> </span><span class="hl-11">1.0</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">4000</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">startTime:</span><span class="hl-1"> </span><span class="hl-11">2000</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">lineWidth:</span><span class="hl-1"> </span><span class="hl-11">0.01</span><span class="hl-1">,</span><br/><span class="hl-1">};</span><br/><br/><span class="hl-6">pass</span><span class="hl-1">.</span><span class="hl-5">setLines</span><span class="hl-1">([</span><span class="hl-6">rectPath</span><span class="hl-1">]);</span>
</code><button type="button">Copy</button></pre>

<h3 id="高-dpr-场景优化" class="tsd-anchor-link">高 DPR 场景优化<a href="#高-dpr-场景优化" 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-8">// InstancedMesh 实现自动优化高 DPR 性能</span><br/><span class="hl-8">// 在 DPR=2 的 Retina 屏幕上,性能显著优于全屏着色器方案</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">pass</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">FlowingLight2DPass</span><span class="hl-1">(</span><span class="hl-6">camera</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 多条路径在高 DPR 下仍能保持流畅</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">paths</span><span class="hl-1"> = </span><span class="hl-6">Array</span><span class="hl-1">.</span><span class="hl-5">from</span><span class="hl-1">({ </span><span class="hl-6">length:</span><span class="hl-1"> </span><span class="hl-11">10</span><span class="hl-1"> }, (</span><span class="hl-6">_</span><span class="hl-1">, </span><span class="hl-6">i</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> ({</span><br/><span class="hl-1">  </span><span class="hl-6">points:</span><span class="hl-1"> [</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.1</span><span class="hl-1">, </span><span class="hl-11">0.1</span><span class="hl-1"> + </span><span class="hl-6">i</span><span class="hl-1"> * </span><span class="hl-11">0.08</span><span class="hl-1">),</span><br/><span class="hl-1">    </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.9</span><span class="hl-1">, </span><span class="hl-11">0.1</span><span class="hl-1"> + </span><span class="hl-6">i</span><span class="hl-1"> * </span><span class="hl-11">0.08</span><span class="hl-1">),</span><br/><span class="hl-1">  ],</span><br/><span class="hl-1">  </span><span class="hl-6">totalLength:</span><span class="hl-1"> </span><span class="hl-11">0.8</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-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Color</span><span class="hl-1">(</span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-5">random</span><span class="hl-1">() * </span><span class="hl-11">0xffffff</span><span class="hl-1">),</span><br/><span class="hl-1">  </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">2000</span><span class="hl-1"> + </span><span class="hl-6">i</span><span class="hl-1"> * </span><span class="hl-11">100</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">startTime:</span><span class="hl-1"> </span><span class="hl-6">i</span><span class="hl-1"> * </span><span class="hl-11">200</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">lineWidth:</span><span class="hl-1"> </span><span class="hl-11">0.01</span><span class="hl-1">,</span><br/><span class="hl-1">}));</span><br/><br/><span class="hl-6">pass</span><span class="hl-1">.</span><span class="hl-5">setLines</span><span class="hl-1">(</span><span class="hl-6">paths</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>
<ul>
<li><strong>光带不出现</strong>: 检查 <code>color</code> 和 <code>opacity</code>,确保非全透明;验证 <code>points</code> 至少 2 个;确认坐标在 [0, 1] 范围内。</li>
<li><strong>流速不对</strong>: 检查 <code>totalLength</code> 计算是否准确;若流速过快/过慢,调整 <code>duration</code>。</li>
<li><strong>位置偏移</strong>: 确认坐标系统使用归一化坐标 [0, 1],不是像素坐标;注意坐标系统以左上角为原点,Y 轴方向为 0(上) 到 1(下)。</li>
<li><strong>性能问题</strong>: InstancedMesh 实现已优化,但过多路径点仍会影响性能。建议单条路径不超过 20 个点。</li>
</ul>
<h2 id="performance" class="tsd-anchor-link">Performance<a href="#performance" 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>
<ul>
<li><strong>全屏着色器</strong>: 每帧检查所有像素,DPR=2 时像素数增加 4 倍,性能下降明显</li>
<li><strong>InstancedMesh</strong>: 仅渲染线段覆盖区域,DPR=2 时性能影响较小</li>
<li><strong>实测</strong>: 在 DPR=2 场景下,InstancedMesh 方案 FPS 提升约 3-5 倍</li>
</ul>
<h3 id="setline-性能优化" class="tsd-anchor-link">setLine 性能优化<a href="#setline-性能优化" 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>setLine</code> 方法根据修改类型自动选择最优更新策略:</p>
<table>
<thead>
<tr>
<th>修改类型</th>
<th>性能</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>只修改颜色/透明度</td>
<td>⚡️ 极快 (~100x)</td>
<td>只更新 instanceColor attribute</td>
</tr>
<tr>
<td>只修改 duration/startTime</td>
<td>⚡️ 极快 (~100x)</td>
<td>只更新 instanceMeta attribute</td>
</tr>
<tr>
<td>只修改 lineWidth</td>
<td>⚡️ 极快 (~100x)</td>
<td>只更新 instanceData attribute</td>
</tr>
<tr>
<td>修改 points (相同数量)</td>
<td>⚡️ 快 (~50x)</td>
<td>只更新 instanceStart/End attributes</td>
</tr>
<tr>
<td>修改 points (不同数量)</td>
<td>⚠️ 慢</td>
<td>重建整个 mesh</td>
</tr>
</tbody>
</table>
<p><strong>最佳实践</strong>:</p>
<pre><code class="ts"><span class="hl-8">// ✅ 高性能 - 频繁修改颜色</span><br/><span class="hl-5">requestAnimationFrame</span><span class="hl-1">(() </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">pass</span><span class="hl-1">.</span><span class="hl-5">setLine</span><span class="hl-1">({</span><br/><span class="hl-1">    </span><span class="hl-6">id:</span><span class="hl-1"> </span><span class="hl-6">lineId</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-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Color</span><span class="hl-1">(</span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-5">random</span><span class="hl-1">(), </span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-5">random</span><span class="hl-1">(), </span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-5">random</span><span class="hl-1">())</span><br/><span class="hl-1">  });</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// ✅ 高性能 - 动画路径(保持点数)</span><br/><span class="hl-3">function</span><span class="hl-1"> </span><span class="hl-5">animatePath</span><span class="hl-1">(</span><span class="hl-6">t</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">pass</span><span class="hl-1">.</span><span class="hl-5">setLine</span><span class="hl-1">({</span><br/><span class="hl-1">    </span><span class="hl-6">id:</span><span class="hl-1"> </span><span class="hl-6">lineId</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">points:</span><span class="hl-1"> [</span><br/><span class="hl-1">      </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.1</span><span class="hl-1">, </span><span class="hl-11">0.1</span><span class="hl-1">),</span><br/><span class="hl-1">      </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.5</span><span class="hl-1"> + </span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-5">sin</span><span class="hl-1">(</span><span class="hl-6">t</span><span class="hl-1">) * </span><span class="hl-11">0.2</span><span class="hl-1">, </span><span class="hl-11">0.5</span><span class="hl-1">),</span><br/><span class="hl-1">      </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">(</span><span class="hl-11">0.9</span><span class="hl-1">, </span><span class="hl-11">0.9</span><span class="hl-1">),</span><br/><span class="hl-1">    ]  </span><span class="hl-8">// 始终 3 个点</span><br/><span class="hl-1">  });</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-8">// ⚠️ 低性能 - 避免频繁改变点数</span><br/><span class="hl-5">setInterval</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">const</span><span class="hl-1"> </span><span class="hl-4">pointCount</span><span class="hl-1"> = </span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-5">floor</span><span class="hl-1">(</span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-5">random</span><span class="hl-1">() * </span><span class="hl-11">5</span><span class="hl-1">) + </span><span class="hl-11">2</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-6">pass</span><span class="hl-1">.</span><span class="hl-5">setLine</span><span class="hl-1">({</span><br/><span class="hl-1">    </span><span class="hl-6">id:</span><span class="hl-1"> </span><span class="hl-6">lineId</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">points:</span><span class="hl-1"> </span><span class="hl-5">generateRandomPoints</span><span class="hl-1">(</span><span class="hl-6">pointCount</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-11">100</span><span class="hl-1">);</span>
</code><button type="button">Copy</button></pre>

<h3 id="优化建议" class="tsd-anchor-link">优化建议<a href="#优化建议" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<ol>
<li>减少路径点数量,使用更简化的路径</li>
<li>降低 <code>lineWidth</code>,减少渲染区域</li>
<li>控制同时渲染的路径数量</li>
<li>使用 <code>setLine</code> 而非 <code>setLines</code> 来更新单条线</li>
<li>保持 points 数量不变,只修改坐标</li>
<li>在低端设备上可通过 <code>pass.enabled = false</code> 禁用</li>
</ol>
<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>
<ol>
<li><strong>坐标系统混淆</strong>: 必须使用归一化坐标 [0, 1],不能使用像素坐标。坐标系统以左上角为原点,Y 轴方向为 0(上) 到 1(下)。</li>
<li><strong>totalLength 计算错误</strong>: 光流速度直接依赖 <code>totalLength</code>。手动计算时务必精确,使用归一化单位。</li>
<li><strong>lineWidth 过大</strong>: 归一化单位下,0.01 约为屏幕高度的 1%。过大的值会导致光带过宽。</li>
<li><strong>未及时 dispose()</strong>: 移除 Pass 时必须调用 <code>dispose()</code>,否则 GPU 资源泄漏。</li>
<li><strong>DPR 不匹配</strong>: 确保渲染目标尺寸与实际屏幕 DPR 匹配,Pass 会自动处理。</li>
</ol>
<h2 id="related" class="tsd-anchor-link">Related<a href="#related" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<ul>
<li><a href="features_postprocessing.html">Postprocessing</a>: 后处理通用概念与 EffectComposer 使用指南。</li>
<li><a href="features_flowing-light-3d-pass.html">Flowing Light 3D Pass</a>: 基于 3D 世界坐标的流光效果。</li>
</ul>
<hr>
<p>tags: [流光, 光带, 导航路径, 指示线, 动态路径, 特效, postprocessing, effect, flowing, light, pass, rendering, screenspace, instanced, performance, 2d, screen-space]</p>
</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#flowing-light-2d-pass-流光-2d-通道"><span>Flowing <wbr/>Light 2<wbr/>D <wbr/>Pass (流光 2<wbr/>D 通道)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><a href="#concepts"><span>Concepts</span></a></li><li><ul><li><a href="#instancedmesh-实例化渲染-instanced-rendering"><span>Instanced<wbr/>Mesh 实例化渲染 (<wbr/>Instanced <wbr/>Rendering)</span></a></li><li><a href="#归一化坐标系统-normalized-coordinates"><span>归一化坐标系统 (<wbr/>Normalized <wbr/>Coordinates)</span></a></li><li><a href="#头尾追逐动画-head-tail-chase-animation"><span>头尾追逐动画 (<wbr/>Head-<wbr/>Tail <wbr/>Chase <wbr/>Animation)</span></a></li><li><a href="#ndc-坐标转换"><span>NDC 坐标转换</span></a></li><li><a href="#dpr-处理与宽高比适配"><span>DPR 处理与宽高比适配</span></a></li></ul></li><li><a href="#configuration"><span>Configuration</span></a></li><li><ul><li><a href="#line-配置参数"><span>Line 配置参数</span></a></li></ul></li><li><a href="#instance-methods"><span>Instance <wbr/>Methods</span></a></li><li><ul><li><a href="#_"><span></span></a></li><li><a href="#_-1"><span></span></a></li><li><a href="#_-2"><span></span></a></li><li><a href="#_-3"><span></span></a></li><li><a href="#_-4"><span></span></a></li><li><a href="#_-5"><span></span></a></li><li><a href="#_-6"><span></span></a></li></ul></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#快速上手-quick-example"><span>快速上手 (<wbr/>Quick <wbr/>Example)</span></a></li><li><a href="#多条路径-动态更新"><span>多条路径 &amp; 动态更新</span></a></li><li><a href="#计算路径总长度"><span>计算路径总长度</span></a></li><li><a href="#矩形路径示例"><span>矩形路径示例</span></a></li><li><a href="#高-dpr-场景优化"><span>高 <wbr/>DPR 场景优化</span></a></li></ul></li><li><a href="#debugging"><span>Debugging</span></a></li><li><a href="#performance"><span>Performance</span></a></li><li><ul><li><a href="#与全屏着色器对比"><span>与全屏着色器对比</span></a></li><li><a href="#setline-性能优化"><span>set<wbr/>Line 性能优化</span></a></li><li><a href="#优化建议"><span>优化建议</span></a></li></ul></li><li><a href="#common-pitfalls"><span>Common <wbr/>Pitfalls</span></a></li><li><a href="#related"><span>Related</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">如视 Five SDK</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>