r3f-postprocessing

React Three Fiber のポストプロセッシング

まず、実際のレンダラーとパッケージのピア依存関係を確認してください。この例は、WebGL 上の Fiber 9.7／React 19 と @react-three/postprocessing 3.1、postprocessing 6.39 を対象としています。任意の最新パッケージバージョンを組み合わせたり、プロジェクトを暗黙にアップグレードしたりしないでください。

パイプラインを選ぶ

• ここで使う React のポストプロセッシングコンポーザーは WebGL 向けです。Three.js の WebGPURenderer は r183 以降、ノードエフェクトと RenderPipeline を使います。このバックエンドは別途確認してください。
• 最終シーンをレンダリングする所有者は 1 つにしてください。EffectComposer は正のフレーム優先度を使用するため、手動で追加した gl.render がその出力を上書きしたり、重複させたりする可能性があります。
• 通常の Bloom は HDR のしきい値を使って明るいサーフェスを分離できます。実際にオブジェクトを選択する必要がある場合に限り、SelectiveBloom を使ってください。処理負荷が増加します。

選択したオブジェクトだけに適用する Bloom

Canvas の下にマウントします。左のボックスをクリックして選択を切り替えます。どちらのボックスも明るいですが、この Bloom パスに寄与するのは選択したオブジェクトだけです。

import { useMemo, useRef, useState } from 'react'
import { EffectComposer, Select, Selection, SelectiveBloom, ToneMapping } from '@react-three/postprocessing'
import { ToneMappingMode } from 'postprocessing'
import type { DirectionalLight } from 'three'

export default function Example() {
  const light = useRef<DirectionalLight>(null)
  const lights = useMemo(() => [light], [])
  const [selected, setSelected] = useState(true)
  return (
    <Selection>
      <directionalLight ref={light} position={[0, 3, 5]} intensity={2} />
      <Select enabled={selected}>
        <mesh name="bloom-selected" position={[-1.2, 0, 0]} onClick={() => setSelected((value) => !value)}>
          <boxGeometry args={[0.7, 0.7, 0.7]} />
          <meshStandardMaterial color="black" emissive="white" emissiveIntensity={3} />
        </mesh>
      </Select>
      <mesh name="bloom-control" position={[1.2, 0, 0]}>
        <boxGeometry args={[0.7, 0.7, 0.7]} />
        <meshStandardMaterial color="black" emissive="white" emissiveIntensity={3} />
      </mesh>
      <EffectComposer multisampling={0}>
        <SelectiveBloom lights={lights} luminanceThreshold={0} intensity={2} mipmapBlur />
        <ToneMapping mode={ToneMappingMode.ACES_FILMIC} />
      </EffectComposer>
    </Selection>
  )
}

色、選択、ref

• Selection／Select は、Outline や SelectiveBloom など、選択に対応するエフェクトに選択状態を渡します。通常の Bloom を Selection でラップしても、Bloom が選択したオブジェクトだけを処理するようにはなりません。
• SelectiveBloom に関連するライトを渡し、選択レイヤーを他のレイヤー用途と整合させてください。暗い背景だけでなく、同程度に明るい未選択オブジェクトでもテストしてください。
• Bloom は最終的なトーンマッピングの前に輝度を処理します。発光値／HDR 値と適切なしきい値を使用してください。グローを発生させるためにシーン全体を平坦化しないでください。
• このコンポーザーはレンダラーのトーンマッピングを無効にします。意図した最終的な見た目にするには、ToneMapping エフェクトを使用してください。Bloom／HDR エフェクトはトーンマッピングより前に配置し、出力変換が重複しないようにしてください。
• ref.current が null 以外になっても、React の再レンダリングは発生しません。ref の代入だけを条件にエフェクトの初回マウントを制御しないでください。オブジェクトがリアクティブに必要な場合は、サポートされている ref またはコールバック ref の state を使用してください。

深度とエフェクト固有の要件

• このラッパーで SSAO を使うには、<EffectComposer enableNormalPass> が必要です。追加バッファーは、それを必要とするエフェクトに限って有効にしてください。ドキュメントの内容と動作が一致しない場合は、インストール済みエフェクトのソース／型定義を確認してください。
• DepthOfField の target はワールド座標（ベクトル／タプル）であり、メッシュの ref ではありません。focusDistance={0} は、あらゆる環境で使えるオートフォーカスの切り替えではありません。サポートされている target または Autofocus ヘルパーを使ってください。
• 一部のエフェクトの props は、タプルではなく Three.js の Vector2／Vector3 インスタンスを受け取ります。インストール済みのラッパーに対して型チェックを行い、JSX の型変換に関する想定を任意の React コンポーネントに当てはめないでください。
• アルファブレンドされたサーフェス、深度、選択、マルチサンプリングは相互に影響します。不透明なボックスのスクリーンショットを当てにせず、実際の透明／透過シーンをテストしてください。

パフォーマンスとカスタムエフェクト

• エフェクトを少数に抑え、DPR／解像度を控えめにするところから始めてください。アンチエイリアス方式を意図的に選び、MSAA、SMAA、FXAA をむやみに重ねないでください。
• エフェクトの数とパスの数は同じとは限りません。互換性のあるエフェクトは統合できます。それでも畳み込み／深度エフェクトや補助バッファーには処理コストがかかる場合があります。GPU の負荷を計測してください。
• サポートされているラッパーコンポーネントを優先してください。カスタム postprocessing Effect を作る場合は、mainImage／mainUv、uniform、入力バッファー、エフェクト属性の規約に従ってください。UV を変更するエフェクトには、適切な畳み込み宣言が必要です。
• カスタム Effect インスタンスのクリーンアップを明確に管理してください。所有者がいない状態で dispose={null} を使ったり、共有エフェクトを 1 つのコンシューマーから破棄したりしないでください。
• 更新後の動的な prop のサポートを確認してください。構築時にしか設定できない項目を変更すると、エフェクトが再作成されることがあります。uniform をアニメーションさせるために、毎フレームコンポーザーを再構築しないでください。

検証

パイプライン全体をレンダリングし、エフェクト／選択を切り替え、リサイズし、Strict Mode 下でアンマウント／再マウントしてください。選択したオブジェクトだけが対象になることと、最終的な色出力を確認してください。TypeScript だけでは、どちらも保証できません。

参照資料

• 選択、SelectiveBloom、Bloom。
• リリース済みラッパーのソース — composer、SSAO、ref、target の型。
• Postprocessing、Three.js 移行ガイド。