@realsee/five
Version:
Realsee Renderer SDK
243 lines (235 loc) • 53 kB
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-fireworks-3d-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-fireworks-3d-pass</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="flowing-fireworks-3d-pass-流光烟花-3d-通道" class="tsd-anchor-link">Flowing Fireworks 3D Pass (流光烟花 3D 通道)<a href="#flowing-fireworks-3d-pass-流光烟花-3d-通道" 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>FlowingFireworks3DPass</code> 与 <a href="features_flowing-light-3d-pass.html"><code>FlowingLight3DPass</code></a> 配套使用,在每条流光线条的「尾部位置」(渐变淡出处)持续喷射出烟花状向四周发散的粒子,适合为流光拖尾增加飞溅火花、星点爆裂等增强效果。</li>
<li><strong>Schema</strong>: <code>FlowingFireworks3DPass</code> 类及 <code>FireworksLine</code> 数据结构。</li>
<li><strong>Concepts</strong>: GPU 粒子运动积分、环形缓冲发射、与流光尾部位置同步、加法混合发光。</li>
<li><strong>Configuration</strong>: 3D 路径点、颜色、动画周期、尾长比例、粒子数量/发射率/扩散/重力等调优参数。</li>
<li><strong>Examples</strong>: 流光拖尾火花、多条 3D 路径烟花、与 FlowingLight3DPass 配合、参数调优。</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-fireworks-3d-pass.d.ts">FlowingFireworks3DPass</a></p>
</blockquote>
<p><code>FlowingFireworks3DPass</code> 继承自 <code>FivePass</code>,与 <code>FlowingLight3DPass</code> 共享同一套线条数据结构(<code>points</code> / <code>totalLength</code> / <code>duration</code> / <code>startTime</code> / <code>tailLengthRatio</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">'three'</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">'./pass'</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">'../../../core/camera'</span><span class="hl-1">;</span><br/><br/><span class="hl-3">type</span><span class="hl-1"> </span><span class="hl-7">FireworksLine</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">Vector3</span><span class="hl-1">[]; </span><span class="hl-8">// 世界坐标系路径点</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">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,与 FlowingLight3DPass 含义一致</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">// 动画周期(毫秒),默认 1000</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/><br/><span class="hl-1"> </span><span class="hl-8">// ---- 烟花粒子调优参数(可选) ----</span><br/><span class="hl-1"> </span><span class="hl-6">particleCount</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">; </span><span class="hl-8">// 该线条的粒子池大小,默认 200</span><br/><span class="hl-1"> </span><span class="hl-6">emissionRate</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">; </span><span class="hl-8">// 每秒发射的粒子数量,默认 300</span><br/><span class="hl-1"> </span><span class="hl-6">spread</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">particleSize</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">; </span><span class="hl-8">// 粒子尺寸(世界单位),默认 spread * 0.12</span><br/><span class="hl-1"> </span><span class="hl-6">particleLife</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">; </span><span class="hl-8">// 粒子最大寿命(秒),默认 0.5</span><br/><span class="hl-1"> </span><span class="hl-6">gravity</span><span class="hl-1">?: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Vector3</span><span class="hl-1">; </span><span class="hl-8">// 粒子加速度(世界单位/秒²),默认沿 -Y 缓慢下落</span><br/><span class="hl-1"> </span><span class="hl-6">leadRatio</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">; </span><span class="hl-8">// 发射点相对尾部向前(头部方向)的提前比例,默认 0.04</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">FlowingFireworks3DPass</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">FireworksLine</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">FireworksLine</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"> } & </span><span class="hl-7">Partial</span><span class="hl-1"><</span><span class="hl-7">Omit</span><span class="hl-1"><</span><span class="hl-7">FireworksLine</span><span class="hl-1">, </span><span class="hl-9">'id'</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-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="与流光尾部同步-tail-synced-emission" class="tsd-anchor-link">与流光尾部同步 (Tail-synced Emission)<a href="#与流光尾部同步-tail-synced-emission" 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 的粒子发射点与 <code>FlowingLight3DPass</code> 的「尾部位置」(<code>tailPosWorld</code>)保持一致:</p>
<ul>
<li>流光的头部(Head)是前进方向的亮端,尾部(Tail)是渐变淡出的末端。</li>
<li><code>tailLengthRatio</code> 表示从头部到渐变结束所占路径比例(默认 0.2)。粒子在「渐变结束的位置」喷射,即 <code>headPos - tailLengthRatio * totalLength</code>。</li>
<li>把本 Pass 与 <code>FlowingLight3DPass</code> 配置<strong>完全相同</strong>的线条数据(<code>points</code>/<code>totalLength</code>/<code>duration</code>/<code>startTime</code>/<code>tailLengthRatio</code>),即可让烟花精准跟随流光尾部。</li>
</ul>
<h3 id="提前量-lead-ratio" class="tsd-anchor-link">提前量 (Lead Ratio)<a href="#提前量-lead-ratio" 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>leadRatio</code> 让发射点相对尾部向头部方向提前一小段(占 <code>totalLength</code> 的比例,默认 0.04),使火花出现时机更早。提前量会被限制在当前尾长以内,不会越过头部。设为 <code>0</code> 即严格在尾部位置喷射。</p>
<h3 id="gpu-粒子运动积分-gpu-particle-integration" class="tsd-anchor-link">GPU 粒子运动积分 (GPU Particle Integration)<a href="#gpu-粒子运动积分-gpu-particle-integration" 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>每个粒子在 CPU 端发射时仅写入「出生世界坐标 / 初速度 / 加速度 / 出生时间 / 寿命」等属性,后续运动完全在顶点着色器中按 <code>p = p0 + v·t + ½·a·t²</code> 积分计算,并随寿命淡出与缩小。CPU 每帧只需计算尾部位置并发射少量新粒子,性能开销低。</p>
<h3 id="环形缓冲发射-ring-buffer-emission" class="tsd-anchor-link">环形缓冲发射 (Ring-buffer Emission)<a href="#环形缓冲发射-ring-buffer-emission" 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>particleCount</code>),按环形缓冲循环复用槽位。<code>emissionRate</code>(粒子/秒)结合每帧 <code>deltaTime</code> 决定发射数量,寿命到期的粒子自动被新粒子覆盖。</p>
<h3 id="加法混合发光-additive-glow" class="tsd-anchor-link">加法混合发光 (Additive Glow)<a href="#加法混合发光-additive-glow" 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>AdditiveBlending</code> 渲染到离屏缓冲并累加,再叠加到场景输出,自然形成重叠处更亮的发光效果。粒子为圆形柔光点,中心亮、边缘柔和。</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>与 <code>FlowingLight3DPass</code> 一致,Pass 自动同步相机投影/视图矩阵,并根据 <code>readBuffer</code> 尺寸自动调整离屏渲染目标,适配高 DPR 屏幕。</p>
<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="fireworksline-配置参数" class="tsd-anchor-link">FireworksLine 配置参数<a href="#fireworksline-配置参数" 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.Vector3[]</code></td>
<td style="text-align:left">✓</td>
<td style="text-align:left">-</td>
<td style="text-align:left">世界坐标系路径点数组。至少 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>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>
<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>particleCount</code></td>
<td style="text-align:left"><code>number</code></td>
<td style="text-align:left"></td>
<td style="text-align:left"><code>200</code></td>
<td style="text-align:left">该线条粒子池大小。越大可同时存在的火花越多。</td>
</tr>
<tr>
<td style="text-align:left"><code>emissionRate</code></td>
<td style="text-align:left"><code>number</code></td>
<td style="text-align:left"></td>
<td style="text-align:left"><code>300</code></td>
<td style="text-align:left">每秒发射的粒子数量。控制火花密度。</td>
</tr>
<tr>
<td style="text-align:left"><code>spread</code></td>
<td style="text-align:left"><code>number</code></td>
<td style="text-align:left"></td>
<td style="text-align:left"><code>0.1</code></td>
<td style="text-align:left">扩散尺度(世界单位)。控制火花向四周飞散的范围。</td>
</tr>
<tr>
<td style="text-align:left"><code>particleSize</code></td>
<td style="text-align:left"><code>number</code></td>
<td style="text-align:left"></td>
<td style="text-align:left"><code>spread * 0.12</code></td>
<td style="text-align:left">粒子尺寸(世界单位)。</td>
</tr>
<tr>
<td style="text-align:left"><code>particleLife</code></td>
<td style="text-align:left"><code>number</code></td>
<td style="text-align:left"></td>
<td style="text-align:left"><code>0.5</code></td>
<td style="text-align:left">粒子最大寿命(秒)。越长火花拖得越远。</td>
</tr>
<tr>
<td style="text-align:left"><code>gravity</code></td>
<td style="text-align:left"><code>THREE.Vector3</code></td>
<td style="text-align:left"></td>
<td style="text-align:left">沿 -Y 缓慢下落</td>
<td style="text-align:left">粒子加速度(世界单位/秒²)。可制造下坠或上升效果。</td>
</tr>
<tr>
<td style="text-align:left"><code>leadRatio</code></td>
<td style="text-align:left"><code>number</code></td>
<td style="text-align:left"></td>
<td style="text-align:left"><code>0.04</code></td>
<td style="text-align:left">发射点相对尾部的提前比例(占 <code>totalLength</code>)。增大可让火花更早出现,<code>0</code> 表示严格在尾部。</td>
</tr>
</tbody>
</table>
<blockquote>
<p><strong>注意</strong>: <code>spread</code> / <code>particleSize</code> / <code>gravity</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: FireworksLine[])</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>: 没有 <code>id</code> 时自动生成 UUID。
<strong>自动设置 startTime</strong>: 没有 <code>startTime</code> 时使用当前内部时间。</p>
<pre><code class="ts"><span class="hl-6">pass</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-11">12</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">3000</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">tailLengthRatio:</span><span class="hl-1"> </span><span class="hl-11">0.2</span><span class="hl-1">,</span><br/><span class="hl-1">}]);</span>
</code><button type="button">Copy</button></pre>
<h3 id="_-2" class="tsd-anchor-link"><code>addLine(...lines: FireworksLine[]): 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>
<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>
<h3 id="_-4" class="tsd-anchor-link"><code>setLine(params: { id: string } & Partial<Omit<FireworksLine, 'id'>>)</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>、<code>color</code>、<code>totalLength</code>、<code>duration</code>、<code>spread</code>、<code>gravity</code> 等)会在下一帧发射时即时生效,<strong>无需重建</strong>。</li>
<li>仅当 <code>particleCount</code> 改变时才会重建粒子缓冲。</li>
</ul>
<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><span class="hl-6">id:</span><span class="hl-1"> </span><span class="hl-9">'line-1'</span><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><span class="hl-6">emissionRate:</span><span class="hl-1"> </span><span class="hl-11">500</span><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><span class="hl-6">id:</span><span class="hl-1"> </span><span class="hl-9">'line-1'</span><span class="hl-1">, </span><span class="hl-6">particleCount:</span><span class="hl-1"> </span><span class="hl-11">400</span><span class="hl-1"> });</span>
</code><button type="button">Copy</button></pre>
<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>释放粒子缓冲、着色材质、渲染目标等资源,销毁 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="与-flowinglight3dpass-配合推荐" class="tsd-anchor-link">与 FlowingLight3DPass 配合(推荐)<a href="#与-flowinglight3dpass-配合推荐" 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 配置<strong>相同</strong>的线条数据。</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">'@realsee/five'</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">FlowingLight3DPass</span><span class="hl-1">, </span><span class="hl-6">FlowingFireworks3DPass</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">'../../lib/five/renderer/postprocessing'</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">calculatePath3DLength</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">'@realsee/five/plugins'</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">'three'</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-3">const</span><span class="hl-1"> </span><span class="hl-4">flowingLight</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">FlowingLight3DPass</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/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">fireworks</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">FlowingFireworks3DPass</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-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">Vector3</span><span class="hl-1">(-</span><span class="hl-11">5</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector3</span><span class="hl-1">(-</span><span class="hl-11">2</span><span class="hl-1">, </span><span class="hl-11">3</span><span class="hl-1">, </span><span class="hl-11">2</span><span class="hl-1">),</span><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">Vector3</span><span class="hl-1">(</span><span class="hl-11">2</span><span class="hl-1">, </span><span class="hl-11">3</span><span class="hl-1">, -</span><span class="hl-11">2</span><span class="hl-1">),</span><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">Vector3</span><span class="hl-1">(</span><span class="hl-11">5</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</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">lineData</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-5">calculatePath3DLength</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">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">0xff00ee</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">8000</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">tailLengthRatio:</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/><br/><span class="hl-6">flowingLight</span><span class="hl-1">.</span><span class="hl-5">setLines</span><span class="hl-1">([</span><span class="hl-6">lineData</span><span class="hl-1">]);</span><br/><span class="hl-6">fireworks</span><span class="hl-1">.</span><span class="hl-5">setLines</span><span class="hl-1">([</span><span class="hl-6">lineData</span><span class="hl-1">]); </span><span class="hl-8">// 相同数据 => 烟花精准跟随流光尾部</span><br/><br/><span class="hl-8">// 注意添加顺序:烟花叠加在流光之上</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">flowingLight</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">fireworks</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="多条-3d-路径烟花" class="tsd-anchor-link">多条 3D 路径烟花<a href="#多条-3d-路径烟花" 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">fireworks</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">FlowingFireworks3DPass</span><span class="hl-1">(</span><span class="hl-6">camera</span><span class="hl-1">);</span><br/><br/><span class="hl-6">fireworks</span><span class="hl-1">.</span><span class="hl-5">setLines</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><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector3</span><span class="hl-1">(</span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">), </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector3</span><span class="hl-1">(</span><span class="hl-11">10</span><span class="hl-1">, </span><span class="hl-11">5</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">totalLength:</span><span class="hl-1"> </span><span class="hl-11">11</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/><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-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector3</span><span class="hl-1">(</span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">), </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector3</span><span class="hl-1">(</span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">10</span><span class="hl-1">, </span><span class="hl-11">5</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">12</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">2500</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><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-6">fireworks</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-5">calculatePath3DLength</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">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">0xffaa00</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">6000</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">emissionRate:</span><span class="hl-1"> </span><span class="hl-11">600</span><span class="hl-1">, </span><span class="hl-8">// 更密集</span><br/><span class="hl-1"> </span><span class="hl-6">spread:</span><span class="hl-1"> </span><span class="hl-11">0.25</span><span class="hl-1">, </span><span class="hl-8">// 飞散更广</span><br/><span class="hl-1"> </span><span class="hl-6">particleLife:</span><span class="hl-1"> </span><span class="hl-11">0.9</span><span class="hl-1">, </span><span class="hl-8">// 拖得更远</span><br/><span class="hl-1"> </span><span class="hl-6">particleSize:</span><span class="hl-1"> </span><span class="hl-11">0.04</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">gravity:</span><span class="hl-1"> </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector3</span><span class="hl-1">(</span><span class="hl-11">0</span><span class="hl-1">, -</span><span class="hl-11">0.5</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">), </span><span class="hl-8">// 明显下坠</span><br/><span class="hl-1"> </span><span class="hl-6">leadRatio:</span><span class="hl-1"> </span><span class="hl-11">0.08</span><span class="hl-1">, </span><span class="hl-8">// 出现更早</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-8">// 视觉上火花偏晚 => 增大 leadRatio 让其更早出现</span><br/><span class="hl-6">pass</span><span class="hl-1">.</span><span class="hl-5">setLine</span><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><span class="hl-6">leadRatio:</span><span class="hl-1"> </span><span class="hl-11">0.1</span><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><span class="hl-6">id:</span><span class="hl-1"> </span><span class="hl-6">lineId</span><span class="hl-1">, </span><span class="hl-6">leadRatio:</span><span class="hl-1"> </span><span class="hl-11">0</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>addPass</code>。</li>
<li><strong>火花太稀疏</strong>: 增大 <code>emissionRate</code> 或 <code>particleCount</code>(注意 <code>particleCount</code> 是上限,过小会限制同时存在的粒子数)。</li>
<li><strong>火花范围太小/太大</strong>: 调整 <code>spread</code>(世界单位),需结合场景尺度。</li>
<li><strong>火花出现偏晚/偏早</strong>: 调整 <code>leadRatio</code>(增大更早,<code>0</code> 严格在尾部)。</li>
<li><strong>位置与流光尾部不一致</strong>: 确认两个 Pass 使用了<strong>完全相同</strong>的 <code>points</code>/<code>totalLength</code>/<code>duration</code>/<code>startTime</code>/<code>tailLengthRatio</code>。</li>
<li><strong>粒子不下落或方向不对</strong>: 检查 <code>gravity</code> 向量;默认沿 -Y(世界上方向取决于场景坐标系)。</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>
<ul>
<li><strong>GPU 积分</strong>: 粒子运动全部在着色器中完成,CPU 每帧只发射少量新粒子,开销低。</li>
<li><strong>环形缓冲</strong>: 粒子池大小固定(<code>particleCount</code>),不会随时间增长,显存稳定。</li>
<li><strong>加法混合</strong>: 重叠粒子会累加亮度,过高的 <code>emissionRate</code> × <code>particleCount</code> 会增加片元填充率,建议按需调节。</li>
</ul>
<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>控制 <code>particleCount</code> 与 <code>emissionRate</code>,避免不必要的高密度。</li>
<li>大场景适当放大 <code>spread</code> / <code>particleSize</code>,小场景调小,保持视觉比例。</li>
<li>使用 <code>setLine</code> 而非 <code>setLines</code> 更新单条线;除 <code>particleCount</code> 外的修改无需重建。</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>: 烟花与流光必须共享相同的线条参数,否则尾部位置不对齐。</li>
<li><strong>添加顺序</strong>: 应在流光 Pass 之后 <code>addPass</code> 烟花 Pass,使火花叠加在流光之上。</li>
<li><strong>单位混淆</strong>: <code>spread</code> / <code>particleSize</code> / <code>gravity</code> 为世界单位,<code>totalLength</code> 也是世界单位,不要混用像素。</li>
<li><strong>particleCount 过小</strong>: 它是同时存在粒子数的上限,过小会使高 <code>emissionRate</code> 失效。</li>
<li><strong>未调用 dispose()</strong>: 销毁 Pass 时必须调用 <code>dispose()</code>,避免 GPU 资源泄漏。</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_flowing-light-3d-pass.html">Flowing Light 3D Pass</a>: 3D 流光效果,本 Pass 的配套来源。</li>
<li><a href="features_flowing-light-2d-pass.html">Flowing Light 2D Pass</a>: 屏幕空间的流光效果。</li>
<li><a href="features_postprocessing.html">Postprocessing</a>: 后处理通用概念与 EffectComposer 使用指南。</li>
</ul>
<hr>
<p>tags: [烟花, 火花, 粒子, 流光拖尾, 发散, 爆裂, 特效, postprocessing, effect, fireworks, particle, sparks, flowing, pass, rendering, worldspace, 3d, world-space, additive, gpu-particles]</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-fireworks-3d-pass-流光烟花-3d-通道"><span>Flowing <wbr/>Fireworks 3<wbr/>D <wbr/>Pass (流光烟花 3<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="#与流光尾部同步-tail-synced-emission"><span>与流光尾部同步 (<wbr/>Tail-<wbr/>synced <wbr/>Emission)</span></a></li><li><a href="#提前量-lead-ratio"><span>提前量 (<wbr/>Lead <wbr/>Ratio)</span></a></li><li><a href="#gpu-粒子运动积分-gpu-particle-integration"><span>GPU 粒子运动积分 (<wbr/>GPU <wbr/>Particle <wbr/>Integration)</span></a></li><li><a href="#环形缓冲发射-ring-buffer-emission"><span>环形缓冲发射 (<wbr/>Ring-<wbr/>buffer <wbr/>Emission)</span></a></li><li><a href="#加法混合发光-additive-glow"><span>加法混合发光 (<wbr/>Additive <wbr/>Glow)</span></a></li><li><a href="#相机同步与-dpr"><span>相机同步与 <wbr/>DPR</span></a></li></ul></li><li><a href="#configuration"><span>Configuration</span></a></li><li><ul><li><a href="#fireworksline-配置参数"><span>Fireworks<wbr/>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="#与-flowinglight3dpass-配合推荐"><span>与 <wbr/>Flowing<wbr/>Light3<wbr/>D<wbr/>Pass 配合(推荐)</span></a></li><li><a href="#多条-3d-路径烟花"><span>多条 3<wbr/>D 路径烟花</span></a></li><li><a href="#参数调优更密集、飞溅更远的火花"><span>参数调优:更密集、飞溅更远的火花</span></a></li><li><a href="#调整火花出现时机"><span>调整火花出现时机</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></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>