threejs-impl-post-processing

threejs-impl-post-processing

クイックリファレンス

アーキテクチャの概要

Three.js には、互換性のないポストプロセッシングシステムが2種類あります。絶対に混在させないでください。

システム	パッケージ	方式	最適な用途
組み込みの EffectComposer	three/addons/postprocessing/	エフェクトごとに1つのシェーダーパス	シンプルな構成、カスタムの ShaderPass
pmndrs/postprocessing	postprocessing (npm)	エフェクトを1つのパスに統合	パフォーマンスが重要な場合、R3F アプリ
WebGPU PostProcessing	three/addons/tsl/display/	ノードベースの TSL グラフ	WebGPU レンダラーのみ

標準パイプライン（組み込みの EffectComposer）

import { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js';
import { RenderPass } from 'three/addons/postprocessing/RenderPass.js';
import { OutputPass } from 'three/addons/postprocessing/OutputPass.js';

const composer = new EffectComposer( renderer );
composer.addPass( new RenderPass( scene, camera ) ); // ALWAYS first
// ... effect passes here ...
composer.addPass( new OutputPass() );                 // ALWAYS last

function animate() {
  composer.render(); // replaces renderer.render( scene, camera )
}

パスの順序に関するルール

1. RenderPass は必ず最初のパスにします。シーンを内部バッファーにレンダリングします
2. エフェクトパスは中央に、任意の順序で配置します（ブルーム、SSAO、アウトラインなど）
3. アンチエイリアスパス（SMAA、FXAA）はエフェクトパスの後に配置します
4. OutputPass は必ず最後のパスにします。トーンマッピングと色空間変換を適用します
5. OutputPass を省略しないでください。省略すると、色が白っぽく見えたり、正しく表示されなかったりします

重要な警告

three/addons/postprocessing/EffectComposer と、pmndrs/postprocessing の EffectComposer を絶対に混在させないでください。互換性のないバッファー形式を使用しているため、描画アーティファクトやクラッシュが発生します。

ウィンドウのリサイズ時に composer.setSize() を呼び出し忘れないでください。コンポーザーをリサイズしないと、エフェクトがぼやけたり、位置がずれたりします。

EffectComposer の使用中は renderer.render( scene, camera ) を呼び出さないでください。代わりに必ず composer.render() を呼び出してください。両方を呼び出すと、シーンが2回レンダリングされます。

WebGPU レンダラーでは WebGL のポストプロセッシングパスを使用しないでください。WebGPU では、ノードベースの別個の PostProcessing クラスを使用します。

必ず RenderPass を最初のパスに含めてください。含めないと、後続のパスに空のバッファーが渡されます。

---

EffectComposer API

コンストラクター

new EffectComposer( renderer: WebGLRenderer, renderTarget?: WebGLRenderTarget )

• renderer -- WebGLRenderer インスタンスです
• renderTarget -- 任意のカスタムレンダーターゲットです。省略すると自動的に作成されます

プロパティ

プロパティ	型	説明
.passes	Pass[]	順序付きのポストプロセッシングパス配列
.readBuffer	WebGLRenderTarget	内部読み取りバッファー
.writeBuffer	WebGLRenderTarget	内部書き込みバッファー
.renderToScreen	boolean	最終パスを画面にレンダリングするかどうか（デフォルトは true）
.renderer	WebGLRenderer	レンダラーインスタンス

メソッド

メソッド	説明
.addPass( pass )	パスをチェーンの末尾に追加します
.insertPass( pass, index )	指定した位置にパスを挿入します
.removePass( pass )	チェーンからパスを削除します
.render( deltaTime? )	有効なすべてのパスを順番に実行します
.setSize( width, height )	すべての内部バッファーとパスのサイズを変更します
.setPixelRatio( ratio )	デバイスのピクセル比を設定します
.swapBuffers()	読み取りバッファーと書き込みバッファーを入れ替えます
.reset( renderTarget? )	内部状態を復元します
.dispose()	すべての GPU リソースを解放します

---

利用可能なパスタイプ

コアパス（必ず必要）

パス	インポート	用途
RenderPass	postprocessing/RenderPass.js	シーンをバッファーにレンダリングします。必ず最初に配置します
OutputPass	postprocessing/OutputPass.js	トーンマッピングと色空間処理を行います。必ず最後に配置します

エフェクトパス

パス	コンストラクター	用途
UnrealBloomPass	( resolution, strength?, radius?, threshold? )	HDR ブルームの発光
SSAOPass	( scene, camera, width?, height? )	スクリーンスペースアンビエントオクルージョン
GTAOPass	( scene, camera, width?, height? )	グラウンドトゥルース AO（高品質）
SAOPass	( scene, camera )	スケーラブルアンビエントオブスキュランス
OutlinePass	( resolution, scene, camera, selectedObjects? )	オブジェクト選択の輪郭
BokehPass	( scene, camera, params )	被写界深度
SSRPass	( params )	スクリーンスペース反射
FilmPass	( intensity?, grayscale? )	フィルムグレイン／走査線
GlitchPass	( dtSize? )	デジタルグリッチエフェクト
HalftonePass	( width, height, params )	ハーフトーンのドットパターン
DotScreenPass	( center?, angle?, scale? )	ドットスクリーンオーバーレイ
AfterimagePass	( damp? )	モーショントレイル／残像
LUTPass	( params )	カラー LUT グレーディング
RenderPixelatedPass	( pixelSize, scene, camera )	ピクセル化エフェクト

アンチエイリアスパス

パス	コンストラクター	品質	コスト
FXAAPass	()	低 -- 高速な近似	最も低い
SMAAPass	( width, height )	中 -- サブピクセル形態学的処理	中程度
SSAARenderPass	( scene, camera )	高 -- スーパーサンプリング	高い
TAARenderPass	( scene, camera )	高 -- 時間方向の蓄積	高い

ユーティリティパス

パス	用途
ShaderPass	カスタム GLSL シェーダーエフェクト
MaskPass	ステンシルマスキング
ClearMaskPass	ステンシルマスクをクリア
ClearPass	バッファーをクリア
TexturePass	テクスチャをレンダリング
CubeTexturePass	キューブマップ背景をレンダリング
SavePass	現在のバッファーをレンダーターゲットに保存
RenderTransitionPass	2 つのシーン間のアニメーション付きトランジション

すべてのパスは three/addons/postprocessing/{PassName}.js からインポートします。

---

主なエフェクトの設定

UnrealBloomPass

import { UnrealBloomPass } from 'three/addons/postprocessing/UnrealBloomPass.js';

const bloom = new UnrealBloomPass(
  new THREE.Vector2( window.innerWidth, window.innerHeight ),
  1.5,  // strength -- bloom intensity [0, 3+]
  0.4,  // radius -- bloom spread [0, 1]
  0.85  // threshold -- luminance cutoff [0, 1]
);

ブルームを正しく機能させるには、レンダラーでトーンマッピングを必ず有効にしてください。オブジェクトごとの選択的なブルームは標準ではサポートされていません。回避策として、複数のレンダーパスと layers システムを使用してください。

SSAOPass / GTAOPass

本番品質では、必ず SSAOPass より GTAOPass を優先してください。SSAOPass はプロトタイピングでのみ使用してください。

// SSAOPass (faster, lower quality)
const ssao = new SSAOPass( scene, camera, width, height );
ssao.kernelRadius = 8;
ssao.minDistance = 0.005;
ssao.maxDistance = 0.1;

// GTAOPass (slower, production quality)
const gtao = new GTAOPass( scene, camera, width, height );

OutlinePass

const outline = new OutlinePass(
  new THREE.Vector2( window.innerWidth, window.innerHeight ),
  scene, camera
);
outline.selectedObjects = [ mesh1, mesh2 ];
outline.edgeStrength = 3;
outline.edgeGlow = 0;
outline.edgeThickness = 1;
outline.visibleEdgeColor.set( 0xffffff );
outline.hiddenEdgeColor.set( 0x190a05 );

---

カスタム ShaderPass

import { ShaderPass } from 'three/addons/postprocessing/ShaderPass.js';

const myShader = {
  uniforms: {
    tDiffuse: { value: null }, // ALWAYS include -- receives read buffer
    amount: { value: 0.5 }
  },
  vertexShader: `
    varying vec2 vUv;
    void main() {
      vUv = uv;
      gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
    }
  `,
  fragmentShader: `
    uniform sampler2D tDiffuse;
    uniform float amount;
    varying vec2 vUv;
    void main() {
      vec4 color = texture2D( tDiffuse, vUv );
      gl_FragColor = mix( color, vec4( 1.0 - color.rgb, color.a ), amount );
    }
  `
};

const customPass = new ShaderPass( myShader );
composer.insertPass( customPass, 1 ); // after RenderPass

textureID パラメーターのデフォルト値は 'tDiffuse' です。シェーダーが入力テクスチャに別のユニフォーム名を使用する場合は、2 番目の引数として渡してください。new ShaderPass( myShader, 'myInputTexture' )

---

pmndrs/postprocessing

アーキテクチャ

pmndrs/postprocessing ライブラリは複数のエフェクトを単一のシェーダーパスに統合し、組み込みシステムと比べてドローコールを大幅に削減します。

import { EffectComposer, EffectPass, RenderPass, BloomEffect,
         SMAAEffect } from 'postprocessing';

const composer = new EffectComposer( renderer );
composer.addPass( new RenderPass( scene, camera ) );
composer.addPass( new EffectPass( camera, new BloomEffect(), new SMAAEffect() ) );

function animate() {
  composer.render();
}

主なエフェクト

エフェクト	用途
BloomEffect	ミップマップを使用した設定可能なブルーム
SMAAEffect	サブピクセル形態学的アンチエイリアス
SSAOEffect	スクリーンスペースアンビエントオクルージョン
DepthOfFieldEffect	ボケによる被写界深度
ToneMappingEffect	トーンマッピングオペレーター
VignetteEffect	画面端の暗化
ChromaticAberrationEffect	色収差
NoiseEffect	フィルムグレイン
GodRaysEffect	ボリュームライトの散乱

React Three Fiber では、これらのエフェクトを JSX コンポーネントとしてラップする @react-three/postprocessing を使用してください。

---

リサイズ処理

ウィンドウのリサイズ時には、レンダラーとコンポーザーの両方を必ずリサイズしてください。

window.addEventListener( 'resize', () => {
  camera.aspect = window.innerWidth / window.innerHeight;
  camera.updateProjectionMatrix();
  renderer.setSize( window.innerWidth, window.innerHeight );
  composer.setSize( window.innerWidth, window.innerHeight ); // MUST resize
});

---

WebGPU ポストプロセッシング

WebGPU レンダラーでは、別個のノードベースシステムを使用します。

import { PostProcessing } from 'three/addons/tsl/display/PostProcessing.js';

const postProcessing = new PostProcessing( renderer );
// Uses TSL (Three Shading Language) node graphs for effects

これは、組み込みの WebGL EffectComposer と pmndrs/postprocessing のどちらとも完全に互換性がありません。

---

リファレンスリンク

• references/methods.md -- EffectComposer、すべてのパス、pmndrs のエフェクトの完全な API シグネチャ
• references/examples.md -- 一般的なポストプロセッシング設定の動作するコード例
• references/anti-patterns.md -- ポストプロセッシングで避けるべきこと

公式ソース

• https://threejs.org/docs/#examples/en/postprocessing/EffectComposer
• https://threejs.org/examples/?q=postprocessing
• https://github.com/pmndrs/postprocessing
• https://docs.pmnd.rs/react-three-fiber/tutorials/post-processing