@react-three/postprocessing 3.0.5 → 3.1.1

package/src/effects/SSAO.tsx

@@ -1,13 +1,81 @@
 import { BlendFunction, SSAOEffect } from 'postprocessing'
-import { Ref, useContext, useMemo } from 'react'
+import { Ref, use, useMemo } from 'react'
 import { EffectComposerContext } from '../EffectComposer'
-import { useDispose } from '../util'
+import { applyPierced, readPierced, useDispose, useLiveDefaults } from '../util'
 
 // first two args are camera and texture
 type SSAOProps = ConstructorParameters<typeof SSAOEffect>[2] & { ref?: Ref<SSAOEffect> }
 
-export function SSAO({ ref, ...props }: SSAOProps) {
-  const { camera, normalPass, downSamplingPass, resolutionScale } = useContext(EffectComposerContext)
+// Only resolutionScale/resolutionX/resolutionY/width/height and
+// normalDepthBuffer have no live setter in postprocessing - everything else
+// either has a real accessor directly on SSAOEffect, or on the nested
+// ssaoMaterial (rangeThreshold/rangeFalloff are the constructor's names for
+// what ssaoMaterial exposes as proximityThreshold/proximityFalloff).
+// camera+normalBuffer being required constructor args also rule out
+// createEffectComponent (needs `new Effect()` to work with zero args).
+const LIVE_KEYS = [
+  'blendMode-blendFunction',
+  'normalBuffer',
+  'samples',
+  'rings',
+  'radius',
+  'depthAwareUpsampling',
+  'color',
+  'luminanceInfluence',
+  'intensity',
+  'ssaoMaterial-bias',
+  'ssaoMaterial-fade',
+  'ssaoMaterial-minRadiusScale',
+  'ssaoMaterial-distanceThreshold',
+  'ssaoMaterial-distanceFalloff',
+  'ssaoMaterial-worldDistanceThreshold',
+  'ssaoMaterial-worldDistanceFalloff',
+  'rangeThreshold',
+  'rangeFalloff',
+  'ssaoMaterial-worldProximityThreshold',
+  'ssaoMaterial-worldProximityFalloff',
+]
+
+function get(effect: SSAOEffect, key: string): unknown {
+  if (key === 'rangeThreshold') return effect.ssaoMaterial.proximityThreshold
+  if (key === 'rangeFalloff') return effect.ssaoMaterial.proximityFalloff
+  return readPierced(effect, key)
+}
+
+function set(effect: SSAOEffect, key: string, value: unknown): void {
+  if (key === 'rangeThreshold') effect.ssaoMaterial.proximityThreshold = value as number
+  else if (key === 'rangeFalloff') effect.ssaoMaterial.proximityFalloff = value as number
+  else applyPierced(effect, key, value)
+}
+
+export function SSAO({
+  blendFunction = BlendFunction.MULTIPLY,
+  samples = 30,
+  rings = 4,
+  distanceThreshold = 1.0,
+  distanceFalloff = 0.0,
+  rangeThreshold = 0.5,
+  rangeFalloff = 0.1,
+  luminanceInfluence = 0.9,
+  radius = 20,
+  bias = 0.5,
+  intensity = 1.0,
+  color,
+  worldDistanceThreshold,
+  worldDistanceFalloff,
+  worldProximityThreshold,
+  worldProximityFalloff,
+  minRadiusScale,
+  fade,
+  depthAwareUpsampling = true,
+  resolutionScale,
+  resolutionX,
+  resolutionY,
+  width,
+  height,
+  ref,
+}: SSAOProps) {
+  const { camera, normalPass, downSamplingPass, resolutionScale: composerResolutionScale } = use(EffectComposerContext)
 
   const effect = useMemo<SSAOEffect | {}>(() => {
     if (normalPass === null && downSamplingPass === null) {
@@ -16,29 +84,69 @@ export function SSAO({ ref, ...props }: SSAOProps) {
     }
 
     return new SSAOEffect(camera, normalPass && !downSamplingPass ? (normalPass as any).texture : null, {
-      blendFunction: BlendFunction.MULTIPLY,
-      samples: 30,
-      rings: 4,
-      distanceThreshold: 1.0,
-      distanceFalloff: 0.0,
-      rangeThreshold: 0.5,
-      rangeFalloff: 0.1,
-      luminanceInfluence: 0.9,
-      radius: 20,
-      bias: 0.5,
-      intensity: 1.0,
-      color: undefined,
+      blendFunction,
+      samples,
+      rings,
+      distanceThreshold,
+      distanceFalloff,
+      rangeThreshold,
+      rangeFalloff,
+      luminanceInfluence,
+      radius,
+      bias,
+      intensity,
       // @ts-ignore
       normalDepthBuffer: downSamplingPass ? downSamplingPass.texture : null,
-      resolutionScale: resolutionScale ?? 1,
-      depthAwareUpsampling: true,
-      ...props,
+      resolutionScale: resolutionScale ?? composerResolutionScale ?? 1,
+      resolutionX,
+      resolutionY,
+      width,
+      height,
+      depthAwareUpsampling,
     })
-    // NOTE: `props` is an unstable reference, so we can't memoize it
+    // color/worldDistanceThreshold/worldDistanceFalloff/worldProximityThreshold/
+    // worldProximityFalloff/minRadiusScale/fade are deliberately left out here
+    // even though they're valid constructor options: they have no JS-level
+    // default in this component's own signature, so useLiveDefaults' first
+    // snapshot must see SSAOEffect's own real default for them, not whatever
+    // value happened to be passed on the mounting render - otherwise removing
+    // the prop later "resets" to that first-render value instead of the
+    // effect's true default. They're still applied immediately below, live.
+    //
+    // Only the genuinely construction-only options belong here - everything
+    // else is applied live below via useLiveDefaults instead.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [camera, downSamplingPass, normalPass, resolutionScale])
+  }, [camera, downSamplingPass, normalPass, resolutionScale, composerResolutionScale, resolutionX, resolutionY, width, height])
+
+  useLiveDefaults(
+    effect instanceof SSAOEffect ? effect : null,
+    {
+      'blendMode-blendFunction': blendFunction,
+      samples,
+      rings,
+      radius,
+      depthAwareUpsampling,
+      color,
+      luminanceInfluence,
+      intensity,
+      'ssaoMaterial-bias': bias,
+      'ssaoMaterial-fade': fade,
+      'ssaoMaterial-minRadiusScale': minRadiusScale,
+      'ssaoMaterial-distanceThreshold': distanceThreshold,
+      'ssaoMaterial-distanceFalloff': distanceFalloff,
+      'ssaoMaterial-worldDistanceThreshold': worldDistanceThreshold,
+      'ssaoMaterial-worldDistanceFalloff': worldDistanceFalloff,
+      rangeThreshold,
+      rangeFalloff,
+      'ssaoMaterial-worldProximityThreshold': worldProximityThreshold,
+      'ssaoMaterial-worldProximityFalloff': worldProximityFalloff,
+    },
+    LIVE_KEYS,
+    get,
+    set
+  )
 
-  useDispose(effect)
+  useDispose(effect as SSAOEffect)
 
   return <primitive ref={ref} object={effect} />
 }

package/src/effects/ScanlineEffect.tsx

@@ -1,7 +1,7 @@
-import { BlendFunction, ScanlineEffect } from 'postprocessing'
-import { wrapEffect } from '../wrapEffect'
+import { ScanlineEffect } from 'postprocessing'
+import { createEffectComponent, type EffectOptions } from '../createEffectComponent'
 
-export const Scanline = /* @__PURE__ */ wrapEffect(ScanlineEffect, {
-  blendFunction: BlendFunction.OVERLAY,
-  density: 1.25,
-})
+export const Scanline = /* @__PURE__ */ createEffectComponent<
+  typeof ScanlineEffect,
+  EffectOptions<typeof ScanlineEffect>
+>(ScanlineEffect)

package/src/effects/SelectiveBloom.tsx

@@ -4,7 +4,7 @@ import { BlendFunction, SelectiveBloomEffect } from 'postprocessing'
 import { Ref, RefObject, use, useEffect, useMemo } from 'react'
 import { Object3D } from 'three'
 import { EffectComposerContext } from '../EffectComposer'
-import { EMPTY_ARRAY, resolveRef, useDispose, useSelectionSync } from '../util'
+import { EMPTY_ARRAY, resolveRef, useDispose, useLiveDefaults, useSelectionSync } from '../util'
 
 type ObjectRef = RefObject<Object3D | null>
 
@@ -21,67 +21,49 @@ export type SelectiveBloomProps = BloomEffectOptions &
 const addLight = (light: Object3D, effect: SelectiveBloomEffect) => light.layers.enable(effect.selection.layer)
 const removeLight = (light: Object3D, effect: SelectiveBloomEffect) => light.layers.disable(effect.selection.layer)
 
+// BloomEffect (which SelectiveBloomEffect extends) only exposes real
+// setters for these - luminanceThreshold/luminanceSmoothing/mipmapBlur/
+// radius/levels/resolution* are construction-only in postprocessing itself.
+// scene/camera being required constructor args also rules out
+// createEffectComponent (needs `new Effect()` to work with zero args).
+const LIVE_KEYS = ['width', 'height', 'kernelSize', 'intensity', 'inverted', 'ignoreBackground']
+
 export function SelectiveBloom({
   selection = EMPTY_ARRAY,
   selectionLayer = 10,
   lights = EMPTY_ARRAY,
-  inverted = false,
-  ignoreBackground = false,
   luminanceThreshold,
   luminanceSmoothing,
   mipmapBlur,
-  intensity,
   radius,
   levels,
-  kernelSize,
   resolutionScale,
-  width,
-  height,
   resolutionX,
   resolutionY,
   ref,
+  ...liveProps
 }: SelectiveBloomProps) {
   const { scene, camera } = use(EffectComposerContext)
 
   const invalidate = useThree((state) => state.invalidate)
 
-  const effect = useMemo(() => {
-    const instance = new SelectiveBloomEffect(scene, camera, {
-      blendFunction: BlendFunction.ADD,
-      luminanceThreshold,
-      luminanceSmoothing,
-      mipmapBlur,
-      intensity,
-      radius,
-      levels,
-      kernelSize,
-      resolutionScale,
-      width,
-      height,
-      resolutionX,
-      resolutionY,
-    })
-    instance.inverted = inverted
-    instance.ignoreBackground = ignoreBackground
-    return instance
-  }, [
-    scene,
-    camera,
-    luminanceThreshold,
-    luminanceSmoothing,
-    mipmapBlur,
-    intensity,
-    radius,
-    levels,
-    kernelSize,
-    resolutionScale,
-    width,
-    height,
-    resolutionX,
-    resolutionY,
-    inverted,
-    ignoreBackground,
-  ])
+  const effect = useMemo(
+    () =>
+      new SelectiveBloomEffect(scene, camera, {
+        blendFunction: BlendFunction.ADD,
+        luminanceThreshold,
+        luminanceSmoothing,
+        mipmapBlur,
+        radius,
+        levels,
+        resolutionScale,
+        resolutionX,
+        resolutionY,
+      }),
+    [scene, camera, luminanceThreshold, luminanceSmoothing, mipmapBlur, radius, levels, resolutionScale, resolutionX, resolutionY]
+  )
+
+  useLiveDefaults(effect, liveProps as Record<string, unknown>, LIVE_KEYS)
 
   // Must run before the lights effect below: addLight/removeLight read
   // effect.selection.layer live, so it needs to already reflect the

package/src/effects/Sepia.tsx

@@ -1,4 +1,6 @@
 import { SepiaEffect } from 'postprocessing'
-import { wrapEffect } from '../wrapEffect'
+import { createEffectComponent, type EffectOptions } from '../createEffectComponent'
 
-export const Sepia = /* @__PURE__ */ wrapEffect(SepiaEffect)
+export const Sepia = /* @__PURE__ */ createEffectComponent<typeof SepiaEffect, EffectOptions<typeof SepiaEffect>>(
+  SepiaEffect
+)

package/src/effects/ShockWave.tsx

@@ -1,4 +1,32 @@
+import type { ReactThreeFiber } from '@react-three/fiber'
 import { ShockWaveEffect } from 'postprocessing'
-import { wrapEffect } from '../wrapEffect'
+import { Ref, use, useMemo } from 'react'
+import { EffectComposerContext } from '../EffectComposer'
+import { useDispose, useLiveDefaults, useVector3 } from '../util'
 
-export const ShockWave = /* @__PURE__ */ wrapEffect(ShockWaveEffect)
+export type ShockWaveProps = {
+  position?: ReactThreeFiber.Vector3
+  speed?: number
+  maxRadius?: number
+  waveSize?: number
+  amplitude?: number
+  ref?: Ref<ShockWaveEffect>
+}
+
+const LIVE_KEYS = ['position', 'speed', 'maxRadius', 'waveSize', 'amplitude']
+
+// ShockWaveEffect's constructor is (camera, position, options) - camera is
+// a required arg, so it can't use createEffectComponent (needs
+// `new Effect()` to work with zero args). Built by hand instead, like
+// Outline/GodRays.
+export function ShockWave(props: ShockWaveProps) {
+  const { speed, maxRadius, waveSize, amplitude, ref } = props
+  const { camera } = use(EffectComposerContext)
+  const effect = useMemo(() => new ShockWaveEffect(camera), [camera])
+  const position = useVector3(props, 'position')
+
+  useLiveDefaults(effect, { position, speed, maxRadius, waveSize, amplitude }, LIVE_KEYS)
+  useDispose(effect)
+
+  return <primitive ref={ref} object={effect} />
+}

package/src/effects/Texture.tsx

@@ -1,17 +1,22 @@
 import { useLoader } from '@react-three/fiber'
 import { TextureEffect } from 'postprocessing'
-import { Ref, useLayoutEffect, useMemo } from 'react'
+import type { Ref } from 'react'
+import { useLayoutEffect } from 'react'
 import { RepeatWrapping, SRGBColorSpace, TextureLoader } from 'three'
-import { useDispose } from '../util'
+import { createEffectComponent, type EffectOptions } from '../createEffectComponent'
 
-type TextureProps = ConstructorParameters<typeof TextureEffect>[0] & {
+const TextureImpl = /* @__PURE__ */ createEffectComponent<typeof TextureEffect, EffectOptions<typeof TextureEffect>>(
+  TextureEffect
+)
+
+export type TextureProps = EffectOptions<typeof TextureEffect> & {
   textureSrc: string
   /** opacity of provided texture */
   opacity?: number
   ref?: Ref<TextureEffect>
 }
 
-export function Texture({ textureSrc, texture, opacity = 1, ref, ...props }: TextureProps) {
+export function Texture({ textureSrc, texture, opacity = 1, ...props }: TextureProps) {
   const t = useLoader(TextureLoader, textureSrc)
 
   useLayoutEffect(() => {
@@ -19,9 +24,5 @@ export function Texture({ textureSrc, texture, opacity = 1, ref, ...props }: Tex
     t.wrapS = t.wrapT = RepeatWrapping
   }, [t])
 
-  const effect = useMemo(() => new TextureEffect({ ...props, texture: t || texture }), [])
-
-  useDispose(effect)
-
-  return <primitive ref={ref} object={effect} blendMode-opacity-value={opacity} />
+  return <TextureImpl {...props} texture={texture ?? t} opacity={opacity} />
 }

package/src/effects/TiltShift.tsx

@@ -1,4 +1,32 @@
 import { BlendFunction, TiltShiftEffect } from 'postprocessing'
-import { wrapEffect } from '../wrapEffect'
+import type { Ref } from 'react'
+import { useMemo } from 'react'
+import { createEffectComponent, type EffectOptions } from '../createEffectComponent'
 
-export const TiltShift = /* @__PURE__ */ wrapEffect(TiltShiftEffect, { blendFunction: BlendFunction.ADD })
+type TiltShiftOptions = EffectOptions<typeof TiltShiftEffect>
+
+const TiltShiftImpl = /* @__PURE__ */ createEffectComponent<typeof TiltShiftEffect, TiltShiftOptions>(TiltShiftEffect)
+
+export type TiltShiftProps = TiltShiftOptions & {
+  opacity?: number
+  ref?: Ref<TiltShiftEffect>
+}
+
+// kernelSize/resolutionScale/resolutionX/resolutionY have no live setter in
+// postprocessing - routed through args so they still work as plain props
+// (previously they were passed as plain props and silently never reached
+// the effect at all, since there was no setter for diffProps to hit).
+export function TiltShift({
+  blendFunction = BlendFunction.ADD,
+  kernelSize,
+  resolutionScale,
+  resolutionX,
+  resolutionY,
+  ...liveProps
+}: TiltShiftProps) {
+  const args = useMemo<[TiltShiftOptions]>(
+    () => [{ kernelSize, resolutionScale, resolutionX, resolutionY }],
+    [kernelSize, resolutionScale, resolutionX, resolutionY]
+  )
+  return <TiltShiftImpl blendFunction={blendFunction} args={args} {...liveProps} />
+}

package/src/effects/TiltShift2.tsx

@@ -1,6 +1,7 @@
 import { BlendFunction, Effect, EffectAttribute } from 'postprocessing'
+import type { Ref } from 'react'
 import { Uniform } from 'three'
-import { wrapEffect } from '../wrapEffect'
+import { createEffectComponent } from '../createEffectComponent'
 
 const TiltShiftShader = {
   fragmentShader: /* glsl */ `
@@ -62,20 +63,22 @@ const TiltShiftShader = {
     `,
 }
 
+type Vec2Tuple = [number, number]
+
 export class TiltShiftEffect extends Effect {
   constructor({
     blendFunction = BlendFunction.NORMAL,
     blur = 0.15, // [0, 1], can go beyond 1 for extra
     taper = 0.5, // [0, 1], can go beyond 1 for extra
-    start = [0.5, 0.0], // [0,1] percentage x,y of screenspace
-    end = [0.5, 1.0], // [0,1] percentage x,y of screenspace
+    start = [0.5, 0.0] as Vec2Tuple, // [0,1] percentage x,y of screenspace
+    end = [0.5, 1.0] as Vec2Tuple, // [0,1] percentage x,y of screenspace
     samples = 10.0, // number of blur samples
-    direction = [1, 1], // direction of blur
+    direction = [1, 1] as Vec2Tuple, // direction of blur
   } = {}) {
     super('TiltShiftEffect', TiltShiftShader.fragmentShader, {
       blendFunction,
       attributes: EffectAttribute.CONVOLUTION,
-      uniforms: new Map<string, Uniform<number | number[]>>([
+      uniforms: new Map<string, Uniform<number | Vec2Tuple>>([
         ['blur', new Uniform(blur)],
         ['taper', new Uniform(taper)],
         ['start', new Uniform(start)],
@@ -85,6 +88,69 @@ export class TiltShiftEffect extends Effect {
       ]),
     })
   }
+
+  private u<T>(name: string): T {
+    return this.uniforms.get(name)!.value
+  }
+
+  private setU(name: string, value: unknown): void {
+    this.uniforms.get(name)!.value = value
+  }
+
+  get blur(): number {
+    return this.u('blur')
+  }
+  set blur(value: number) {
+    this.setU('blur', value)
+  }
+
+  get taper(): number {
+    return this.u('taper')
+  }
+  set taper(value: number) {
+    this.setU('taper', value)
+  }
+
+  get start(): Vec2Tuple {
+    return this.u('start')
+  }
+  set start(value: Vec2Tuple) {
+    this.setU('start', value)
+  }
+
+  get end(): Vec2Tuple {
+    return this.u('end')
+  }
+  set end(value: Vec2Tuple) {
+    this.setU('end', value)
+  }
+
+  get samples(): number {
+    return this.u('samples')
+  }
+  set samples(value: number) {
+    this.setU('samples', value)
+  }
+
+  get direction(): Vec2Tuple {
+    return this.u('direction')
+  }
+  set direction(value: Vec2Tuple) {
+    this.setU('direction', value)
+  }
+}
+
+export type TiltShift2Props = {
+  blendFunction?: BlendFunction
+  blur?: number
+  taper?: number
+  start?: Vec2Tuple
+  end?: Vec2Tuple
+  samples?: number
+  direction?: Vec2Tuple
+  ref?: Ref<TiltShiftEffect>
 }
 
-export const TiltShift2 = /* @__PURE__ */ wrapEffect(TiltShiftEffect, { blendFunction: BlendFunction.NORMAL })
+export const TiltShift2 = /* @__PURE__ */ createEffectComponent<typeof TiltShiftEffect, TiltShift2Props>(
+  TiltShiftEffect
+)

package/src/effects/ToneMapping.tsx

@@ -1,6 +1,19 @@
 import { ToneMappingEffect } from 'postprocessing'
-import { type EffectProps, wrapEffect } from '../wrapEffect'
+import type { Ref } from 'react'
+import { useMemo } from 'react'
+import { createEffectComponent, type EffectOptions } from '../createEffectComponent'
 
-export type ToneMappingProps = EffectProps<typeof ToneMappingEffect>
+type ToneMappingOptions = EffectOptions<typeof ToneMappingEffect>
 
-export const ToneMapping = /* @__PURE__ */ wrapEffect(ToneMappingEffect)
+const ToneMappingImpl = /* @__PURE__ */ createEffectComponent<typeof ToneMappingEffect, ToneMappingOptions>(
+  ToneMappingEffect
+)
+
+export type ToneMappingProps = ToneMappingOptions & { opacity?: number; ref?: Ref<ToneMappingEffect> }
+
+// minLuminance/maxLuminance have no live setter in postprocessing - routed
+// through args so they still work as plain props.
+export function ToneMapping({ minLuminance, maxLuminance, ...liveProps }: ToneMappingProps) {
+  const args = useMemo<[ToneMappingOptions]>(() => [{ minLuminance, maxLuminance }], [minLuminance, maxLuminance])
+  return <ToneMappingImpl args={args} {...liveProps} />
+}

package/src/effects/Vignette.tsx

@@ -1,4 +1,7 @@
 import { VignetteEffect } from 'postprocessing'
-import { wrapEffect } from '../wrapEffect'
+import { createEffectComponent, type EffectOptions } from '../createEffectComponent'
 
-export const Vignette = /* @__PURE__ */ wrapEffect(VignetteEffect)
+export const Vignette = /* @__PURE__ */ createEffectComponent<
+  typeof VignetteEffect,
+  EffectOptions<typeof VignetteEffect>
+>(VignetteEffect)

package/src/effects/Water.tsx

@@ -1,6 +1,7 @@
 import { BlendFunction, Effect, EffectAttribute } from 'postprocessing'
+import type { Ref } from 'react'
 import { Uniform } from 'three'
-import { wrapEffect } from '../wrapEffect'
+import { createEffectComponent } from '../createEffectComponent'
 
 const WaterShader = {
   fragmentShader: /* glsl */ `
@@ -10,7 +11,7 @@ const WaterShader = {
       vec2 vUv = uv;
       float frequency = 6.0 * factor;
       float amplitude = 0.015 * factor;
-      float x = vUv.y * frequency + time * 0.7; 
+      float x = vUv.y * frequency + time * 0.7;
       float y = vUv.x * frequency + time * 0.3;
       vUv.x += cos(x + y) * amplitude * cos(y);
       vUv.y += sin(x - y) * amplitude * cos(y);
@@ -25,11 +26,25 @@ export class WaterEffectImpl extends Effect {
     super('WaterEffect', WaterShader.fragmentShader, {
       blendFunction,
       attributes: EffectAttribute.CONVOLUTION,
-      uniforms: new Map<string, Uniform<number | number[]>>([['factor', new Uniform(factor)]]),
+      uniforms: new Map<string, Uniform<number>>([['factor', new Uniform(factor)]]),
     })
   }
+
+  get factor(): number {
+    return this.uniforms.get('factor')!.value
+  }
+
+  set factor(value: number) {
+    this.uniforms.get('factor')!.value = value
+  }
+}
+
+export type WaterEffectProps = {
+  blendFunction?: BlendFunction
+  factor?: number
+  ref?: Ref<WaterEffectImpl>
 }
 
-export const WaterEffect = /* @__PURE__ */ wrapEffect(WaterEffectImpl, {
-  blendFunction: BlendFunction.NORMAL,
-})
+export const WaterEffect = /* @__PURE__ */ createEffectComponent<typeof WaterEffectImpl, WaterEffectProps>(
+  WaterEffectImpl
+)

package/src/index.ts

@@ -1,4 +1,6 @@
+export * from './createEffectComponent'
 export * from './EffectComposer'
+export * from './EffectGroup'
 export * from './Selection'
 export * from './util'
 export * from './wrapEffect'
@@ -37,5 +39,5 @@ export * from './effects/ToneMapping'
 export * from './effects/Vignette'
 export * from './effects/Water'
 
-// These are not effect passes
-export * from './effects/N8AO'
+export * from './passes/DepthPicking'
+export * from './passes/N8AO'