@realsee/five
Version:
Realsee Renderer SDK
183 lines (175 loc) • 33.8 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/gaussian-blur-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/gaussian-blur-pass</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="gaussian-blur-pass-高斯模糊通道" class="tsd-anchor-link">Gaussian Blur Pass (高斯模糊通道)<a href="#gaussian-blur-pass-高斯模糊通道" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h1>
<ul>
<li><strong>Summary</strong>: GaussianBlurPass 是一个后处理通道,用于对渲染结果应用高斯模糊效果。</li>
<li><strong>Schema</strong>: GaussianBlurPass 类及其关键参数。</li>
<li><strong>Concepts</strong>: 后处理通道 (Pass)、高斯模糊、Shader、EffectComposer。</li>
<li><strong>Configuration</strong>: 模糊半径 (radius) 和标准差 (sigma) 参数。</li>
<li><strong>Examples</strong>: 基础使用、参数调整。</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/gaussian-blur-pass.d.ts">GaussianBlurPass</a></p>
</blockquote>
<p><code>GaussianBlurPass</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">'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-10">export</span><span class="hl-1"> </span><span class="hl-3">class</span><span class="hl-1"> </span><span class="hl-7">GaussianBlurPass</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-8">// 构造函数,传入相机实例</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">setRadius</span><span class="hl-1">(</span><span class="hl-6">radius</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">): </span><span class="hl-7">void</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 渲染方法(由 EffectComposer 调用)</span><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-8">// 释放资源</span><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>
<h3 id="shader-uniforms-内部-shader-参数" class="tsd-anchor-link">Shader Uniforms (内部 Shader 参数)<a href="#shader-uniforms-内部-shader-参数" 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>该通道使用 ShaderMaterial,包含以下 uniforms:</p>
<table>
<thead>
<tr>
<th style="text-align:left">Uniform</th>
<th style="text-align:left">Type</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>colorMap</code></td>
<td style="text-align:left"><code>THREE.Texture</code></td>
<td style="text-align:left"><code>null</code></td>
<td style="text-align:left">输入纹理(来自 readBuffer)</td>
</tr>
<tr>
<td style="text-align:left"><code>resolution</code></td>
<td style="text-align:left"><code>THREE.Vector2</code></td>
<td style="text-align:left"><code>相机分辨率</code></td>
<td style="text-align:left">渲染目标的分辨率</td>
</tr>
<tr>
<td style="text-align:left"><code>radius</code></td>
<td style="text-align:left"><code>number</code></td>
<td style="text-align:left"><code>4.0</code></td>
<td style="text-align:left">模糊采样半径(像素数)</td>
</tr>
<tr>
<td style="text-align:left"><code>sigma</code></td>
<td style="text-align:left"><code>number</code></td>
<td style="text-align:left"><code>4.0</code></td>
<td style="text-align:left">高斯核的标准差</td>
</tr>
</tbody>
</table>
<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="后处理通道-post-processing-pass" class="tsd-anchor-link">后处理通道 (Post-Processing Pass)<a href="#后处理通道-post-processing-pass" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>GaussianBlurPass 是 Three.js EffectComposer 生态中的一个通道。它接收前一个通道的输出(readBuffer),进行高斯模糊处理后,输出到下一个通道或屏幕(writeBuffer 或 renderToScreen)。</p>
<h3 id="高斯模糊原理" class="tsd-anchor-link">高斯模糊原理<a href="#高斯模糊原理" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>该通道采用离散高斯核进行模糊。在 fragment shader 中:</p>
<ul>
<li>对采样范围内的像素(由 <code>radius</code> 定义)计算高斯权重</li>
<li>根据 <code>sigma</code> 值计算高斯分布的形状</li>
<li>对所有采样点的颜色值加权平均</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>
<p>构造函数需传入 <code>Camera</code> 实例,用于获取当前渲染分辨率。通过 <code>camera.resolution</code> 自动同步分辨率变化,确保模糊效果在窗口 resize 时保持正确。</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="常用参数" class="tsd-anchor-link">常用参数<a href="#常用参数" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>通过 <code>setRadius()</code> 方法调整模糊效果强度:</p>
<table>
<thead>
<tr>
<th style="text-align:left">Parameter</th>
<th style="text-align:left">Type</th>
<th style="text-align:left">Default</th>
<th style="text-align:left">Range</th>
<th style="text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>radius</code></td>
<td style="text-align:left"><code>number</code></td>
<td style="text-align:left"><code>4.0</code></td>
<td style="text-align:left"><code>0 ~ 8</code></td>
<td style="text-align:left">采样半径(像素),值越大模糊越明显</td>
</tr>
<tr>
<td style="text-align:left"><code>sigma</code></td>
<td style="text-align:left"><code>number</code></td>
<td style="text-align:left"><code>4.0</code></td>
<td style="text-align:left"><code>0.1 ~ 10</code></td>
<td style="text-align:left">高斯核标准差,控制模糊的柔和度</td>
</tr>
</tbody>
</table>
<blockquote>
<p>注意:当前实现中 <code>sigma</code> 固定为 4.0,仅 <code>radius</code> 可动态调整。如需修改 <code>sigma</code>,需直接访问 <code>material.uniforms.sigma.value</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>初始化高斯模糊通道,需传入相机实例以获取分辨率信息。</p>
<h3 id="_-1" class="tsd-anchor-link"><code>setRadius(radius: number)</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>
<ul>
<li><strong>参数</strong>: <code>radius</code> - 采样半径,建议范围 1 ~ 8</li>
<li><strong>默认值</strong>: 4.0</li>
<li><strong>影响</strong>: 较大的 radius 会增加 GPU 计算成本</li>
</ul>
<h3 id="_-2" class="tsd-anchor-link"><code>render(...)</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>由 EffectComposer 在每一帧自动调用,用于执行模糊处理。通常不需要手动调用。</p>
<h3 id="_-3" class="tsd-anchor-link"><code>dispose()</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>释放 Shader Material 和 FullScreenQuad 资源。在销毁 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="ts"><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">GaussianBlurPass</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/><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">// 使用 Five 的 addPass() 方法添加后处理通道</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">blurPass</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">GaussianBlurPass</span><span class="hl-1">(</span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">camera</span><span class="hl-1">);</span><br/><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">blurPass</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 动画循环由 Five 内部管理</span><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="进阶用法-advanced-usage" class="tsd-anchor-link">进阶用法 (Advanced Usage)<a href="#进阶用法-advanced-usage" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<h4 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></h4>
<pre><code class="ts"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">blurPass</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">GaussianBlurPass</span><span class="hl-1">(</span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">camera</span><span class="hl-1">);</span><br/><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">blurPass</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">'keydown'</span><span class="hl-1">, (</span><span class="hl-6">e</span><span class="hl-1">) </span><span class="hl-3">=></span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">e</span><span class="hl-1">.</span><span class="hl-6">key</span><span class="hl-1"> === </span><span class="hl-9">'+'</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">current</span><span class="hl-1"> = </span><span class="hl-6">blurPass</span><span class="hl-1">[</span><span class="hl-9">'material'</span><span class="hl-1">].</span><span class="hl-6">uniforms</span><span class="hl-1">.</span><span class="hl-6">radius</span><span class="hl-1">.</span><span class="hl-6">value</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-6">blurPass</span><span class="hl-1">.</span><span class="hl-5">setRadius</span><span class="hl-1">(</span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-5">min</span><span class="hl-1">(</span><span class="hl-11">8</span><span class="hl-1">, </span><span class="hl-6">current</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-10">if</span><span class="hl-1"> (</span><span class="hl-6">e</span><span class="hl-1">.</span><span class="hl-6">key</span><span class="hl-1"> === </span><span class="hl-9">'-'</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">current</span><span class="hl-1"> = </span><span class="hl-6">blurPass</span><span class="hl-1">[</span><span class="hl-9">'material'</span><span class="hl-1">].</span><span class="hl-6">uniforms</span><span class="hl-1">.</span><span class="hl-6">radius</span><span class="hl-1">.</span><span class="hl-6">value</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-6">blurPass</span><span class="hl-1">.</span><span class="hl-5">setRadius</span><span class="hl-1">(</span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-5">max</span><span class="hl-1">(</span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-6">current</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>
</code><button type="button">Copy</button></pre>
<h4 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></h4>
<pre><code class="ts"><span class="hl-8">// Five 的 addPass() 会自动管理后处理链</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">blurPass</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">GaussianBlurPass</span><span class="hl-1">(</span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">camera</span><span class="hl-1">);</span><br/><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">blurPass</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 可添加其他后处理通道</span><br/><span class="hl-8">// five.addPass(otherPass);</span>
</code><button type="button">Copy</button></pre>
<h4 id="修改高斯标准差-advanced" class="tsd-anchor-link">修改高斯标准差 (Advanced)<a href="#修改高斯标准差-advanced" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4>
<pre><code class="ts"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">blurPass</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">GaussianBlurPass</span><span class="hl-1">(</span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">camera</span><span class="hl-1">);</span><br/><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">blurPass</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 获取 Material 并直接修改 sigma</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">sigmaMaterial</span><span class="hl-1"> = </span><span class="hl-6">blurPass</span><span class="hl-1">[</span><span class="hl-9">'material'</span><span class="hl-1">] </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">ShaderMaterial</span><span class="hl-1">;</span><br/><span class="hl-6">sigmaMaterial</span><span class="hl-1">.</span><span class="hl-6">uniforms</span><span class="hl-1">.</span><span class="hl-6">sigma</span><span class="hl-1">.</span><span class="hl-6">value</span><span class="hl-1"> = </span><span class="hl-11">2.0</span><span class="hl-1">; </span><span class="hl-8">// 调整标准差(更强锐利)</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>
<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>确保 <code>renderToScreen</code> 为 <code>true</code>,或后续通道正确读取该通道的输出。</li>
<li>确保传入的 <code>camera</code> 对象有有效的 <code>resolution</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>
<ul>
<li>大 <code>radius</code> 值会导致 GPU 开销增加。建议在性能受限的设备上限制最大 radius(如 ≤ 6)。</li>
<li>考虑在低端设备上禁用该通道(设置 <code>blurPass.enabled = false</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>
<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">blurPass</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">GaussianBlurPass</span><span class="hl-1">(</span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">camera</span><span class="hl-1">);</span><br/><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">'Blur Radius:'</span><span class="hl-1">, </span><span class="hl-6">blurPass</span><span class="hl-1">[</span><span class="hl-9">'material'</span><span class="hl-1">].</span><span class="hl-6">uniforms</span><span class="hl-1">.</span><span class="hl-6">radius</span><span class="hl-1">.</span><span class="hl-6">value</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">'Blur Sigma:'</span><span class="hl-1">, </span><span class="hl-6">blurPass</span><span class="hl-1">[</span><span class="hl-9">'material'</span><span class="hl-1">].</span><span class="hl-6">uniforms</span><span class="hl-1">.</span><span class="hl-6">sigma</span><span class="hl-1">.</span><span class="hl-6">value</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">'Resolution:'</span><span class="hl-1">, </span><span class="hl-6">blurPass</span><span class="hl-1">[</span><span class="hl-9">'material'</span><span class="hl-1">].</span><span class="hl-6">uniforms</span><span class="hl-1">.</span><span class="hl-6">resolution</span><span class="hl-1">.</span><span class="hl-6">value</span><span class="hl-1">);</span>
</code><button type="button">Copy</button></pre>
<h2 id="common-pitfalls" class="tsd-anchor-link">Common Pitfalls<a href="#common-pitfalls" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<ol>
<li>
<p><strong>忘记调用 dispose()</strong></p>
<ul>
<li>销毁 Pass 时,必须调用 <code>blurPass.dispose()</code> 释放 Shader 资源,否则会导致内存泄漏。</li>
</ul>
</li>
<li>
<p><strong>分辨率变化未更新</strong></p>
<ul>
<li>GaussianBlurPass 会自动从 <code>camera.resolution</code> 同步分辨率,无需手动处理。但如果使用自定义相机,需确保其 <code>resolution</code> 属性始终有效。</li>
</ul>
</li>
<li>
<p><strong>设置过大的 radius</strong></p>
<ul>
<li>超过 8 的 radius 值虽然技术上可行,但会显著增加计算成本。建议不超过 8。</li>
</ul>
</li>
<li>
<p><strong>与其他 Pass 的 needsSwap 冲突</strong></p>
<ul>
<li>如果通道链中多个 Pass 设置了不同的 <code>needsSwap</code> 值,可能导致缓冲区错乱。确保通道顺序和 swap 设置一致。</li>
</ul>
</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>
</ul>
<hr>
<pre><code class="yaml"><span class="hl-0">tags</span><span class="hl-1">: [</span><span class="hl-2">模糊</span><span class="hl-1">, </span><span class="hl-2">高斯模糊</span><span class="hl-1">, </span><span class="hl-2">毛玻璃</span><span class="hl-1">, </span><span class="hl-2">背景虚化</span><span class="hl-1">, </span><span class="hl-2">postprocessing</span><span class="hl-1">, </span><span class="hl-2">shader</span><span class="hl-1">, </span><span class="hl-2">effect</span><span class="hl-1">, </span><span class="hl-2">blur</span><span class="hl-1">, </span><span class="hl-2">pass</span><span class="hl-1">, </span><span class="hl-2">rendering</span><span class="hl-1">, </span><span class="hl-2">gaussian</span><span class="hl-1">, </span><span class="hl-2">blur-effect</span><span class="hl-1">]</span>
</code><button type="button">Copy</button></pre>
</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#gaussian-blur-pass-高斯模糊通道"><span>Gaussian <wbr/>Blur <wbr/>Pass (高斯模糊通道)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><ul><li><a href="#shader-uniforms-内部-shader-参数"><span>Shader <wbr/>Uniforms (内部 <wbr/>Shader 参数)</span></a></li></ul></li><li><a href="#concepts"><span>Concepts</span></a></li><li><ul><li><a href="#后处理通道-post-processing-pass"><span>后处理通道 (<wbr/>Post-<wbr/>Processing <wbr/>Pass)</span></a></li><li><a href="#高斯模糊原理"><span>高斯模糊原理</span></a></li><li><a href="#相机依赖"><span>相机依赖</span></a></li></ul></li><li><a href="#configuration"><span>Configuration</span></a></li><li><ul><li><a href="#常用参数"><span>常用参数</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></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="#进阶用法-advanced-usage"><span>进阶用法 (<wbr/>Advanced <wbr/>Usage)</span></a></li><li><ul><li><a href="#动态调整模糊强度"><span>动态调整模糊强度</span></a></li><li><a href="#多通道组合(模糊-其他效果)"><span>多通道组合(模糊 + 其他效果)</span></a></li><li><a href="#修改高斯标准差-advanced"><span>修改高斯标准差 (<wbr/>Advanced)</span></a></li></ul></li></ul></li><li><a href="#debugging"><span>Debugging</span></a></li><li><ul><li><a href="#检查模糊效果是否生效"><span>检查模糊效果是否生效</span></a></li><li><a href="#性能优化建议"><span>性能优化建议</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>