@react-three/postprocessing 3.0.4 → 3.1.0

package/src/effects/SMAA.tsx

@@ -1,4 +1,20 @@
-import { SMAAEffect } from 'postprocessing'
-import { wrapEffect } from '../util'
-
-export const SMAA = /* @__PURE__ */ wrapEffect(SMAAEffect)
+import { SMAAEffect } from 'postprocessing'
+import type { Ref } from 'react'
+import { useMemo } from 'react'
+import { createEffectComponent, type EffectOptions } from '../createEffectComponent'
+
+type SMAAOptions = EffectOptions<typeof SMAAEffect>
+
+const SMAAImpl = /* @__PURE__ */ createEffectComponent<typeof SMAAEffect, SMAAOptions>(SMAAEffect)
+
+export type SMAAProps = SMAAOptions & { opacity?: number; ref?: Ref<SMAAEffect> }
+
+// preset/edgeDetectionMode/predicationMode have no live setter in
+// postprocessing - routed through args so they still work as plain props.
+export function SMAA({ preset, edgeDetectionMode, predicationMode, ...liveProps }: SMAAProps) {
+  const args = useMemo<[SMAAOptions]>(
+    () => [{ preset, edgeDetectionMode, predicationMode }],
+    [preset, edgeDetectionMode, predicationMode]
+  )
+  return <SMAAImpl args={args} {...liveProps} />
+}

package/src/effects/SSAO.tsx

@@ -1,41 +1,152 @@
-import { Ref, forwardRef, useContext, useMemo } from 'react'
-import { SSAOEffect, BlendFunction } from 'postprocessing'
-import { EffectComposerContext } from '../EffectComposer'
-
-// first two args are camera and texture
-type SSAOProps = ConstructorParameters<typeof SSAOEffect>[2]
-
-export const SSAO = /* @__PURE__ */ forwardRef<SSAOEffect, SSAOProps>(function SSAO(
-  props: SSAOProps,
-  ref: Ref<SSAOEffect>
-) {
-  const { camera, normalPass, downSamplingPass, resolutionScale } = useContext(EffectComposerContext)
-  const effect = useMemo<SSAOEffect | {}>(() => {
-    if (normalPass === null && downSamplingPass === null) {
-      console.error('Please enable the NormalPass in the EffectComposer in order to use SSAO.')
-      return {}
-    }
-    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,
-      // @ts-ignore
-      normalDepthBuffer: downSamplingPass ? downSamplingPass.texture : null,
-      resolutionScale: resolutionScale ?? 1,
-      depthAwareUpsampling: true,
-      ...props,
-    })
-    // NOTE: `props` is an unstable reference, so we can't memoize it
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [camera, downSamplingPass, normalPass, resolutionScale])
-  return <primitive ref={ref} object={effect} dispose={null} />
-})
+import { BlendFunction, SSAOEffect } from 'postprocessing'
+import { Ref, use, useMemo } from 'react'
+import { EffectComposerContext } from '../EffectComposer'
+import { applyPierced, readPierced, useDispose, useLiveDefaults } from '../util'
+
+// first two args are camera and texture
+type SSAOProps = ConstructorParameters<typeof SSAOEffect>[2] & { ref?: Ref<SSAOEffect> }
+
+// 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) {
+      console.error('Please enable the NormalPass in the EffectComposer in order to use SSAO.')
+      return {}
+    }
+
+    return new SSAOEffect(camera, normalPass && !downSamplingPass ? (normalPass as any).texture : null, {
+      blendFunction,
+      samples,
+      rings,
+      distanceThreshold,
+      distanceFalloff,
+      rangeThreshold,
+      rangeFalloff,
+      luminanceInfluence,
+      radius,
+      bias,
+      intensity,
+      // @ts-ignore
+      normalDepthBuffer: downSamplingPass ? downSamplingPass.texture : null,
+      resolutionScale: resolutionScale ?? composerResolutionScale ?? 1,
+      resolutionX,
+      resolutionY,
+      width,
+      height,
+      depthAwareUpsampling,
+    })
+    // 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, 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 as SSAOEffect)
+
+  return <primitive ref={ref} object={effect} />
+}

package/src/effects/ScanlineEffect.tsx

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

package/src/effects/SelectiveBloom.tsx

@@ -1,126 +1,98 @@
-import { SelectiveBloomEffect, BlendFunction } from 'postprocessing'
-import type { BloomEffectOptions } from 'postprocessing'
-import React, { Ref, RefObject, forwardRef, useMemo, useEffect, useContext, useRef } from 'react'
-import { Object3D } from 'three'
-import { useThree } from '@react-three/fiber'
-import { EffectComposerContext } from '../EffectComposer'
-import { selectionContext } from '../Selection'
-import { resolveRef } from '../util'
-
-type ObjectRef = RefObject<Object3D>
-
-export type SelectiveBloomProps = BloomEffectOptions &
-  Partial<{
-    lights: Object3D[] | ObjectRef[]
-    selection: Object3D | Object3D[] | ObjectRef | ObjectRef[]
-    selectionLayer: number
-    inverted: boolean
-    ignoreBackground: boolean
-  }>
-
-const addLight = (light: Object3D, effect: SelectiveBloomEffect) => light.layers.enable(effect.selection.layer)
-const removeLight = (light: Object3D, effect: SelectiveBloomEffect) => light.layers.disable(effect.selection.layer)
-
-export const SelectiveBloom = /* @__PURE__ */ forwardRef(function SelectiveBloom(
-  {
-    selection = [],
-    selectionLayer = 10,
-    lights = [],
-    inverted = false,
-    ignoreBackground = false,
-    luminanceThreshold,
-    luminanceSmoothing,
-    intensity,
-    width,
-    height,
-    kernelSize,
-    mipmapBlur,
-
-    ...props
-  }: SelectiveBloomProps,
-  forwardRef: Ref<SelectiveBloomEffect>
-) {
-  if (lights.length === 0) {
-    console.warn('SelectiveBloom requires lights to work.')
-  }
-
-  const invalidate = useThree((state) => state.invalidate)
-  const { scene, camera } = useContext(EffectComposerContext)
-  const effect = useMemo(() => {
-    const effect = new SelectiveBloomEffect(scene, camera, {
-      blendFunction: BlendFunction.ADD,
-      luminanceThreshold,
-      luminanceSmoothing,
-      intensity,
-      width,
-      height,
-      kernelSize,
-      mipmapBlur,
-      ...props,
-    })
-    effect.inverted = inverted
-    effect.ignoreBackground = ignoreBackground
-    return effect
-  }, [
-    scene,
-    camera,
-    luminanceThreshold,
-    luminanceSmoothing,
-    intensity,
-    width,
-    height,
-    kernelSize,
-    mipmapBlur,
-    inverted,
-    ignoreBackground,
-    props,
-  ])
-
-  const api = useContext(selectionContext)
-
-  useEffect(() => {
-    // Do not allow array selection if declarative selection is active
-    // TODO: array selection should probably be deprecated altogether
-    if (!api && selection) {
-      effect.selection.set(
-        Array.isArray(selection) ? (selection as Object3D[]).map(resolveRef) : [resolveRef(selection) as Object3D]
-      )
-      invalidate()
-      return () => {
-        effect.selection.clear()
-        invalidate()
-      }
-    }
-  }, [effect, selection, api, invalidate])
-
-  useEffect(() => {
-    effect.selection.layer = selectionLayer
-    invalidate()
-  }, [effect, invalidate, selectionLayer])
-
-  useEffect(() => {
-    if (lights && lights.length > 0) {
-      lights.forEach((light) => addLight(resolveRef(light), effect))
-      invalidate()
-      return () => {
-        lights.forEach((light) => removeLight(resolveRef(light), effect))
-        invalidate()
-      }
-    }
-  }, [effect, invalidate, lights, selectionLayer])
-
-  useEffect(() => {
-    if (api && api.enabled) {
-      if (api.selected?.length) {
-        effect.selection.set(api.selected)
-        invalidate()
-        return () => {
-          effect.selection.clear()
-          invalidate()
-        }
-      }
-    }
-  }, [api, effect.selection, invalidate])
-
-  return <primitive ref={forwardRef} object={effect} dispose={null} />
-})
+import { useThree } from '@react-three/fiber'
+import type { BloomEffectOptions } from 'postprocessing'
+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, useLiveDefaults, useSelectionSync } from '../util'
+
+type ObjectRef = RefObject<Object3D | null>
+
+export type SelectiveBloomProps = BloomEffectOptions &
+  Partial<{
+    lights: Object3D[] | ObjectRef[]
+    selection: Object3D | Object3D[] | ObjectRef | ObjectRef[]
+    selectionLayer: number
+    inverted: boolean
+    ignoreBackground: boolean
+    ref?: Ref<SelectiveBloomEffect>
+  }>
+
+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,
+  luminanceThreshold,
+  luminanceSmoothing,
+  mipmapBlur,
+  radius,
+  levels,
+  resolutionScale,
+  resolutionX,
+  resolutionY,
+  ref,
+  ...liveProps
+}: SelectiveBloomProps) {
+  const { scene, camera } = use(EffectComposerContext)
+
+  const invalidate = useThree((state) => state.invalidate)
+
+  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
+  // latest selectionLayer by the time lights get (re-)assigned to it.
+  useSelectionSync(effect, selection, selectionLayer)
+
+  useEffect(() => {
+    if (lights.length === 0) {
+      console.warn('SelectiveBloom requires lights to work.')
+      return
+    }
+
+    // Refs may not have attached yet - resolve and drop nullish entries
+    // rather than crashing addLight/removeLight on a null object.
+    const resolvedLights = lights.map((light) => resolveRef(light)).filter((light): light is Object3D => light != null)
+    if (resolvedLights.length === 0) return
+
+    resolvedLights.forEach((light) => addLight(light, effect))
+
+    invalidate()
+
+    return () => {
+      resolvedLights.forEach((light) => removeLight(light, effect))
+
+      invalidate()
+    }
+  }, [effect, invalidate, lights, selectionLayer])
+
+  useDispose(effect)
+
+  return <primitive ref={ref} object={effect} />
+}

package/src/effects/Sepia.tsx

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

package/src/effects/ShockWave.tsx

@@ -1,4 +1,32 @@
-import { ShockWaveEffect } from 'postprocessing'
-import { wrapEffect } from '../util'
-
-export const ShockWave = /* @__PURE__ */ wrapEffect(ShockWaveEffect)
+import type { ReactThreeFiber } from '@react-three/fiber'
+import { ShockWaveEffect } from 'postprocessing'
+import { Ref, use, useMemo } from 'react'
+import { EffectComposerContext } from '../EffectComposer'
+import { useDispose, useLiveDefaults, useVector3 } from '../util'
+
+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,23 +1,28 @@
-import { TextureEffect } from 'postprocessing'
-import { Ref, forwardRef, useMemo, useLayoutEffect } from 'react'
-import { useLoader } from '@react-three/fiber'
-import { TextureLoader, SRGBColorSpace, RepeatWrapping } from 'three'
-
-type TextureProps = ConstructorParameters<typeof TextureEffect>[0] & {
-  textureSrc: string
-  /** opacity of provided texture */
-  opacity?: number
-}
-
-export const Texture = /* @__PURE__ */ forwardRef<TextureEffect, TextureProps>(function Texture(
-  { textureSrc, texture, opacity = 1, ...props }: TextureProps,
-  ref: Ref<TextureEffect>
-) {
-  const t = useLoader(TextureLoader, textureSrc)
-  useLayoutEffect(() => {
-    t.colorSpace = SRGBColorSpace
-    t.wrapS = t.wrapT = RepeatWrapping
-  }, [t])
-  const effect = useMemo(() => new TextureEffect({ ...props, texture: t || texture }), [props, t, texture])
-  return <primitive ref={ref} object={effect} blendMode-opacity-value={opacity} dispose={null} />
-})
+import { useLoader } from '@react-three/fiber'
+import { TextureEffect } from 'postprocessing'
+import type { Ref } from 'react'
+import { useLayoutEffect } from 'react'
+import { RepeatWrapping, SRGBColorSpace, TextureLoader } from 'three'
+import { createEffectComponent, type EffectOptions } from '../createEffectComponent'
+
+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, ...props }: TextureProps) {
+  const t = useLoader(TextureLoader, textureSrc)
+
+  useLayoutEffect(() => {
+    t.colorSpace = SRGBColorSpace
+    t.wrapS = t.wrapT = RepeatWrapping
+  }, [t])
+
+  return <TextureImpl {...props} texture={texture ?? t} opacity={opacity} />
+}

package/src/effects/TiltShift.tsx

@@ -1,4 +1,32 @@
-import { TiltShiftEffect, BlendFunction } from 'postprocessing'
-import { wrapEffect } from '../util'
-
-export const TiltShift = /* @__PURE__ */ wrapEffect(TiltShiftEffect, { blendFunction: BlendFunction.ADD })
+import { BlendFunction, TiltShiftEffect } from 'postprocessing'
+import type { Ref } from 'react'
+import { useMemo } from 'react'
+import { createEffectComponent, type EffectOptions } from '../createEffectComponent'
+
+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} />
+}