@realsee/five
Version:
Realsee Renderer SDK
112 lines (105 loc) • 37.5 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/postprocessing | 如视 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/postprocessing</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="后处理-post-processing" class="tsd-anchor-link">后处理 (Post Processing)<a href="#后处理-post-processing" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h1>
<ul>
<li><strong>Summary</strong>: Five 提供了基于 EffectComposer 的后处理机制,默认挂载了自适应亮度 (Auto Exposure) 和眼球穹顶光照 (EDL) 两种效果,同时提供多种可选内置 Pass,并支持开发者编写自定义 Pass。</li>
<li><strong>Schema</strong>: <code>FivePass</code> 类及 <code>Pass</code> 接口。</li>
<li><strong>Concepts</strong>: EffectComposer, G-Buffer, Pass, AdaptiveLuminance, EyeDomeLighting。</li>
<li><strong>Configuration</strong>: 开启内置 Pass 的开关及参数配置。</li>
<li><strong>Examples</strong>: 开启内置 Pass 示例,自定义黑白滤镜 Pass 示例。</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/pass.d.ts">FivePass</a></p>
</blockquote>
<pre><code class="typescript"><span class="hl-8">/**</span><br/><span class="hl-8"> * Pass 接口 (兼容 three.js EffectComposer)</span><br/><span class="hl-8"> */</span><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">Pass</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">enabled</span><span class="hl-1">: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-6">needsSwap</span><span class="hl-1">: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-6">clear</span><span class="hl-1">: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-6">renderToScreen</span><span class="hl-1">: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-5">setSize</span><span class="hl-1">(</span><span class="hl-6">width</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">, </span><span class="hl-6">height</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">): </span><span class="hl-7">void</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-5">render</span><span class="hl-1">(</span><br/><span class="hl-1"> </span><span class="hl-6">renderer</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">WebGLRenderer</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">writeBuffer</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">WebGLRenderTarget</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">readBuffer</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">WebGLRenderTarget</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">deltaTime</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">maskActive</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><br/><span class="hl-1"> ): </span><span class="hl-7">void</span><span class="hl-1">;</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-8">/**</span><br/><span class="hl-8"> * FivePass 基类</span><br/><span class="hl-8"> * 支持 G-Buffer 注入 (depth, normal, color)</span><br/><span class="hl-8"> */</span><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">class</span><span class="hl-1"> </span><span class="hl-7">FivePass</span><span class="hl-1"> </span><span class="hl-3">implements</span><span class="hl-1"> </span><span class="hl-7">Pass</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-3">public</span><span class="hl-1"> </span><span class="hl-6">enabled</span><span class="hl-1">: </span><span class="hl-7">boolean</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-3">public</span><span class="hl-1"> </span><span class="hl-6">needsSwap</span><span class="hl-1">: </span><span class="hl-7">boolean</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-3">public</span><span class="hl-1"> </span><span class="hl-6">clear</span><span class="hl-1">: </span><span class="hl-7">boolean</span><span class="hl-1"> = </span><span class="hl-3">false</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-3">public</span><span class="hl-1"> </span><span class="hl-6">renderToScreen</span><span class="hl-1">: </span><span class="hl-7">boolean</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-3">public</span><span class="hl-1"> </span><span class="hl-6">dependencies</span><span class="hl-1">: (</span><span class="hl-9">'depth'</span><span class="hl-1"> | </span><span class="hl-9">'normal'</span><span class="hl-1"> | </span><span class="hl-9">'color'</span><span class="hl-1">)[];</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 由 EffectComposer 在 render 时注入</span><br/><span class="hl-1"> </span><span class="hl-3">public</span><span class="hl-1"> </span><span class="hl-6">gbuffer</span><span class="hl-1">!: </span><span class="hl-7">Map</span><span class="hl-1"><</span><span class="hl-9">'depth'</span><span class="hl-1"> | </span><span class="hl-9">'normal'</span><span class="hl-1"> | </span><span class="hl-9">'color'</span><span class="hl-1">, </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Texture</span><span class="hl-1">>;</span><br/><br/><span class="hl-1"> </span><span class="hl-3">constructor</span><span class="hl-1">(</span><span class="hl-6">dependencies</span><span class="hl-1">?: (</span><span class="hl-9">'depth'</span><span class="hl-1"> | </span><span class="hl-9">'normal'</span><span class="hl-1"> | </span><span class="hl-9">'color'</span><span class="hl-1">)[]);</span><br/><span class="hl-1"> </span><span class="hl-8">// ... render method implementation</span><br/><span class="hl-1">}</span>
</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>
<ul>
<li><strong>EffectComposer</strong>: 后处理管理器,负责按顺序执行 Pass,管理渲染目标 (RenderTarget) 和 G-Buffer。</li>
<li><strong>FivePass</strong>: Five 引擎优化的 Pass 基类。相比普通 Pass,它声明了 <code>dependencies</code>,Five 会在渲染 Pass 之前准备好所需的 G-Buffer (如深度图、法线图),避免在每个 Pass 中重复渲染场景。</li>
<li><strong>AdaptiveLuminancePass (自适应亮度)</strong>: 模拟人眼对光线的适应过程。当场景亮度变化时,会自动平滑调整曝光度,使画面保持在舒适的亮度范围内。</li>
<li><strong>EyeDomeLightingPass (EDL)</strong>: 一种非真实感渲染技术,主要用于增强点云模型的深度感知。通过屏幕空间的深度差计算遮蔽效果,让点云看起来更有轮廓感。</li>
</ul>
<h2 id="built-in-passes-内置-pass" class="tsd-anchor-link">Built-in Passes (内置 Pass)<a href="#built-in-passes-内置-pass" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<p>Five 默认挂载了两个 Pass 实例,挂载在 <code>five</code> 实例上,默认是关闭状态。</p>
<h3 id="1-adaptiveluminancepass" class="tsd-anchor-link">1. AdaptiveLuminancePass<a href="#1-adaptiveluminancepass" 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>five.adaptiveLuminancePass</code>。</p>
<ul>
<li><strong>作用</strong>: 自动调整画面曝光。</li>
<li><strong>开启方式</strong>: <code>five.adaptiveLuminancePass.enabled = true</code>。</li>
<li><strong>配置项</strong>:
<ul>
<li><code>luminanceScale</code> (number): 亮度缩放系数,影响最终画面的整体亮度。</li>
<li><code>luminanceStep</code> (number): 亮度适应步长,影响适应速度。</li>
</ul>
</li>
</ul>
<h3 id="2-eyedomelightingpass" class="tsd-anchor-link">2. EyeDomeLightingPass<a href="#2-eyedomelightingpass" 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>five.eyeDomeLightingPass</code>。</p>
<ul>
<li><strong>作用</strong>: 增强点云的轮廓和深度感。</li>
<li><strong>开启方式</strong>: <code>five.eyeDomeLightingPass.enabled = true</code>。</li>
<li><strong>配置项</strong>:
<ul>
<li><code>strength</code> (number): 增强强度,值越大轮廓越明显。</li>
<li><code>radius</code> (number): 采样半径,影响阴影的范围。</li>
</ul>
</li>
<li><strong>注意</strong>: 这是一个基于屏幕空间深度的算法,依赖 Depth Buffer。</li>
</ul>
<h3 id="3-optional-built-in-passes-可选内置-pass" class="tsd-anchor-link">3. Optional Built-in Passes (可选内置 Pass)<a href="#3-optional-built-in-passes-可选内置-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>Five 新增了多个可选使用的内置 Pass,这些 Pass 没有预先挂载在 <code>five</code> 实例上,需手动导入并添加到渲染链中:</p>
<ul>
<li><strong><a href="features_gaussian-blur-pass.html">GaussianBlurPass</a></strong>: 高斯模糊效果。</li>
<li><strong><a href="features_flowing-light-2d-pass.html">FlowingLight2DPass</a></strong>: 2D 流光效果(通常用于平面路线流光)。</li>
<li><strong><a href="features_flowing-light-3d-pass.html">FlowingLight3DPass</a></strong>: 3D 流光效果(通常用于空间路径流光)。</li>
<li><strong><a href="features_flowing-fireworks-3d-pass.html">FlowingFireworks3DPass</a></strong>: 在 3D 流光尾部喷射烟花粒子的配套特效。</li>
</ul>
<h4 id="gaussianblurpass-使用示例" class="tsd-anchor-link">GaussianBlurPass 使用示例<a href="#gaussianblurpass-使用示例" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4>
<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">GaussianBlurPass</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">'@realsee/five'</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 1. 创建 GaussianBlurPass 实例 (需要传入 camera)</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">gaussianBlurPass</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">GaussianBlurPass</span><span class="hl-1">(</span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">camera</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 2. 配置参数</span><br/><span class="hl-8">// 设置模糊半径 (默认 4.0)</span><br/><span class="hl-6">gaussianBlurPass</span><span class="hl-1">.</span><span class="hl-5">setRadius</span><span class="hl-1">(</span><span class="hl-11">6</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 3. 将 Pass 添加到渲染链</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">addPass</span><span class="hl-1">(</span><span class="hl-6">gaussianBlurPass</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 4. (可选) 动态开关</span><br/><span class="hl-8">// gaussianBlurPass.enabled = false;</span><br/><br/><span class="hl-8">// 5. (可选) 移除 Pass</span><br/><span class="hl-8">// five.removePass(gaussianBlurPass);</span>
</code><button type="button">Copy</button></pre>
<h2 id="custom-pass-自定义-pass" class="tsd-anchor-link">Custom Pass (自定义 Pass)<a href="#custom-pass-自定义-pass" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<p>如果需要实现自定义的后处理效果(如景深、色彩校正、描边等),建议继承 <code>FivePass</code>。</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>
<ol>
<li><strong>创建类</strong>: 继承 <code>FivePass</code>。</li>
<li><strong>声明依赖</strong>: 在 <code>super()</code> 中传入需要的 G-Buffer 依赖 (如 <code>['depth']</code>)。</li>
<li><strong>实现 render</strong>: 使用 <code>readBuffer</code> 作为输入,将结果渲染到 <code>writeBuffer</code> (或直接渲染到屏幕)。</li>
<li><strong>挂载</strong>: 使用 <code>five.addPass(pass)</code> 将其实例添加到渲染链中。</li>
</ol>
<h2 id="examples" class="tsd-anchor-link">Examples<a href="#examples" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<h3 id="开启内置-pass" class="tsd-anchor-link">开启内置 Pass<a href="#开启内置-pass" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">'@realsee/five'</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">();</span><br/><br/><span class="hl-8">// 开启自适应亮度</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">adaptiveLuminancePass</span><span class="hl-1">.</span><span class="hl-6">enabled</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">adaptiveLuminancePass</span><span class="hl-1">.</span><span class="hl-6">luminanceScale</span><span class="hl-1"> = </span><span class="hl-11">0.5</span><span class="hl-1">; </span><span class="hl-8">// 调整目标亮度</span><br/><br/><span class="hl-8">// 开启 EDL (通常用于点云模式)</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">eyeDomeLightingPass</span><span class="hl-1">.</span><span class="hl-6">enabled</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">eyeDomeLightingPass</span><span class="hl-1">.</span><span class="hl-6">strength</span><span class="hl-1"> = </span><span class="hl-11">1.5</span><span class="hl-1">; </span><span class="hl-8">// 增强轮廓感</span><br/><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">needsRender</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span>
</code><button type="button">Copy</button></pre>
<h3 id="自定义-pass-黑白滤镜" class="tsd-anchor-link">自定义 Pass (黑白滤镜)<a href="#自定义-pass-黑白滤镜" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">'three'</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1">, </span><span class="hl-6">FivePass</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">'@realsee/five'</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">FullScreenQuad</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">'@realsee/five/lib/five/tools/full-screen-quad'</span><span class="hl-1">; </span><span class="hl-8">// 需根据实际路径引用</span><br/><br/><span class="hl-8">// 1. 定义 Shader</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">grayscaleVertexShader</span><span class="hl-1"> = </span><span class="hl-9">`</span><br/><span class="hl-9"> varying vec2 vUv;</span><br/><span class="hl-9"> void main() {</span><br/><span class="hl-9"> vUv = uv;</span><br/><span class="hl-9"> gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);</span><br/><span class="hl-9"> }</span><br/><span class="hl-9">`</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">grayscaleFragmentShader</span><span class="hl-1"> = </span><span class="hl-9">`</span><br/><span class="hl-9"> uniform sampler2D tDiffuse;</span><br/><span class="hl-9"> varying vec2 vUv;</span><br/><span class="hl-9"> void main() {</span><br/><span class="hl-9"> vec4 color = texture2D(tDiffuse, vUv);</span><br/><span class="hl-9"> float gray = dot(color.rgb, vec3(0.299, 0.587, 0.114));</span><br/><span class="hl-9"> gl_FragColor = vec4(vec3(gray), color.a);</span><br/><span class="hl-9"> }</span><br/><span class="hl-9">`</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 2. 创建 Pass 类</span><br/><span class="hl-3">class</span><span class="hl-1"> </span><span class="hl-7">GrayscalePass</span><span class="hl-1"> </span><span class="hl-3">extends</span><span class="hl-1"> </span><span class="hl-7">FivePass</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-3">private</span><span class="hl-1"> </span><span class="hl-6">material</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">ShaderMaterial</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-3">private</span><span class="hl-1"> </span><span class="hl-6">fsQuad</span><span class="hl-1">: </span><span class="hl-7">FullScreenQuad</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-3">constructor</span><span class="hl-1">() {</span><br/><span class="hl-1"> </span><span class="hl-3">super</span><span class="hl-1">(); </span><span class="hl-8">// 不需要额外的 G-Buffer 依赖,只需要前一个 Pass 的颜色结果</span><br/><span class="hl-1"> </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">material</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">ShaderMaterial</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-6">uniforms:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">tDiffuse:</span><span class="hl-1"> { </span><span class="hl-6">value:</span><span class="hl-1"> </span><span class="hl-3">null</span><span class="hl-1"> }</span><br/><span class="hl-1"> },</span><br/><span class="hl-1"> </span><span class="hl-6">vertexShader:</span><span class="hl-1"> </span><span class="hl-6">grayscaleVertexShader</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">fragmentShader:</span><span class="hl-1"> </span><span class="hl-6">grayscaleFragmentShader</span><br/><span class="hl-1"> });</span><br/><span class="hl-1"> </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">fsQuad</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">FullScreenQuad</span><span class="hl-1">(</span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">material</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-5">render</span><span class="hl-1">(</span><span class="hl-6">renderer</span><span class="hl-1">, </span><span class="hl-6">writeBuffer</span><span class="hl-1">, </span><span class="hl-6">readBuffer</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-8">// 将上一个 Pass 的结果 (readBuffer) 传给 Shader</span><br/><span class="hl-1"> </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">material</span><span class="hl-1">.</span><span class="hl-6">uniforms</span><span class="hl-1">.</span><span class="hl-6">tDiffuse</span><span class="hl-1">.</span><span class="hl-6">value</span><span class="hl-1"> = </span><span class="hl-6">readBuffer</span><span class="hl-1">.</span><span class="hl-6">texture</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">renderToScreen</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-8">// 如果是最后一个 Pass,直接渲染到屏幕</span><br/><span class="hl-1"> </span><span class="hl-6">renderer</span><span class="hl-1">.</span><span class="hl-5">setRenderTarget</span><span class="hl-1">(</span><span class="hl-3">null</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">fsQuad</span><span class="hl-1">.</span><span class="hl-5">render</span><span class="hl-1">(</span><span class="hl-6">renderer</span><span class="hl-1">);</span><br/><span class="hl-1"> } </span><span class="hl-10">else</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// 否则渲染到 writeBuffer,供下一个 Pass 使用</span><br/><span class="hl-1"> </span><span class="hl-6">renderer</span><span class="hl-1">.</span><span class="hl-5">setRenderTarget</span><span class="hl-1">(</span><span class="hl-6">writeBuffer</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">clear</span><span class="hl-1">) </span><span class="hl-6">renderer</span><span class="hl-1">.</span><span class="hl-5">clear</span><span class="hl-1">();</span><br/><span class="hl-1"> </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">fsQuad</span><span class="hl-1">.</span><span class="hl-5">render</span><span class="hl-1">(</span><span class="hl-6">renderer</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-8">// 3. 挂载到 Five</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">grayPass</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">GrayscalePass</span><span class="hl-1">();</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">addPass</span><span class="hl-1">(</span><span class="hl-6">grayPass</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 触发重绘</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">needsRender</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span>
</code><button type="button">Copy</button></pre>
<h3 id="使用-g-buffer-深度图示例" class="tsd-anchor-link">使用 G-Buffer (深度图示例)<a href="#使用-g-buffer-深度图示例" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>如果你的 Pass 需要使用场景的深度信息(例如雾效),可以在构造函数中声明依赖。</p>
<pre><code class="typescript"><span class="hl-3">class</span><span class="hl-1"> </span><span class="hl-7">FogPass</span><span class="hl-1"> </span><span class="hl-3">extends</span><span class="hl-1"> </span><span class="hl-7">FivePass</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-3">constructor</span><span class="hl-1">() {</span><br/><span class="hl-1"> </span><span class="hl-3">super</span><span class="hl-1">([</span><span class="hl-9">'depth'</span><span class="hl-1">]); </span><span class="hl-8">// 声明需要深度图</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-5">render</span><span class="hl-1">(</span><span class="hl-6">renderer</span><span class="hl-1">, </span><span class="hl-6">writeBuffer</span><span class="hl-1">, </span><span class="hl-6">readBuffer</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-8">// 获取深度图</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">depthTexture</span><span class="hl-1"> = </span><span class="hl-3">this</span><span class="hl-1">.</span><span class="hl-6">gbuffer</span><span class="hl-1">.</span><span class="hl-5">get</span><span class="hl-1">(</span><span class="hl-9">'depth'</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 在 Shader 中使用 depthTexture ...</span><br/><span class="hl-1"> </span><span class="hl-8">// this.material.uniforms.tDepth.value = depthTexture;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// ... 渲染逻辑</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}</span>
</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>查看 Pass 列表</strong>: 检查 <code>five.fiveRenderer.composer.passes</code> 数组,确认 Pass 是否已添加以及顺序是否正确。</li>
<li><strong>检查 Enabled 状态</strong>: 确保 Pass 实例的 <code>.enabled</code> 属性为 <code>true</code>。</li>
<li><strong>G-Buffer 调试</strong>: 如果自定义 Pass 依赖 G-Buffer 但效果不对,检查 <code>this.gbuffer</code> 是否包含预期的纹理。</li>
</ul>
<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>Pass 顺序</strong>: 后处理是按顺序执行的。如果添加了多个 Pass,要注意它们的添加顺序。<code>addPass</code> 会添加到末尾,<code>insertPass</code> 可以插入到指定位置。</li>
<li><strong>renderToScreen</strong>: 只有链中的最后一个 Pass (且 <code>renderToScreen</code> 为 true) 才会渲染到屏幕。EffectComposer 会自动管理这个标志,但自定义 Pass 必须在 <code>render</code> 方法中正确处理 <code>this.renderToScreen</code> 逻辑。</li>
<li><strong>Performance</strong>: 过多的后处理 Pass 会显著降低帧率,尤其是在高分辨率屏幕上。尽量合并 Shader 逻辑,避免频繁的 Buffer 拷贝。</li>
<li><strong>Dependencies</strong>: 只有继承 <code>FivePass</code> 并声明了 <code>dependencies</code>,<code>this.gbuffer</code> 才会有值。普通 <code>Pass</code> 实现无法自动获取 G-Buffer。</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_gaussian-blur-pass.html">Gaussian Blur Pass</a>: 高斯模糊 Pass 文档。</li>
<li><a href="features_flowing-light-2d-pass.html">Flowing Light 2D Pass</a>: 2D 流光 Pass 文档。</li>
<li><a href="features_flowing-light-3d-pass.html">Flowing Light 3D Pass</a>: 3D 流光 Pass 文档。</li>
<li><a href="features_flowing-fireworks-3d-pass.html">Flowing Fireworks 3D Pass</a>: 流光烟花粒子 Pass 文档。</li>
<li><a href="../../five/application/five.d.ts">five.ts</a>: 查看 <code>addPass</code> 方法的实现。</li>
<li><a href="../../five/renderer/postprocessing/passes/pass.d.ts">pass.ts</a>: 查看 <code>FivePass</code> 基类定义。</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">自定义shader</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">渲染管线</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">adaptive-luminance</span><span class="hl-1">, </span><span class="hl-2">edl</span><span class="hl-1">, </span><span class="hl-2">effect-composer</span><span class="hl-1">, </span><span class="hl-2">addPass</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="#后处理-post-processing"><span>后处理 (<wbr/>Post <wbr/>Processing)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><a href="#concepts"><span>Concepts</span></a></li><li><a href="#built-in-passes-内置-pass"><span>Built-<wbr/>in <wbr/>Passes (内置 <wbr/>Pass)</span></a></li><li><ul><li><a href="#1-adaptiveluminancepass"><span>1. <wbr/>Adaptive<wbr/>Luminance<wbr/>Pass</span></a></li><li><a href="#2-eyedomelightingpass"><span>2. <wbr/>Eye<wbr/>Dome<wbr/>Lighting<wbr/>Pass</span></a></li><li><a href="#3-optional-built-in-passes-可选内置-pass"><span>3. <wbr/>Optional <wbr/>Built-<wbr/>in <wbr/>Passes (可选内置 <wbr/>Pass)</span></a></li><li><ul><li><a href="#gaussianblurpass-使用示例"><span>Gaussian<wbr/>Blur<wbr/>Pass 使用示例</span></a></li></ul></li></ul></li><li><a href="#custom-pass-自定义-pass"><span>Custom <wbr/>Pass (自定义 <wbr/>Pass)</span></a></li><li><ul><li><a href="#步骤"><span>步骤</span></a></li></ul></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#开启内置-pass"><span>开启内置 <wbr/>Pass</span></a></li><li><a href="#自定义-pass-黑白滤镜"><span>自定义 <wbr/>Pass (黑白滤镜)</span></a></li><li><a href="#使用-g-buffer-深度图示例"><span>使用 <wbr/>G-<wbr/>Buffer (深度图示例)</span></a></li></ul></li><li><a href="#debugging"><span>Debugging</span></a></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>