@react-three/postprocessing 3.0.5 → 3.1.0

package/src/effects/Outline.tsx

@@ -1,83 +1,82 @@
 import { OutlineEffect } from 'postprocessing'
-import { Ref, RefObject, use, useMemo } from 'react'
-import { Object3D } from 'three'
+import { Ref, RefObject, use, useEffect, useMemo } from 'react'
+import { Color, Object3D, type ColorRepresentation } from 'three'
 import { EffectComposerContext } from '../EffectComposer'
-import { EMPTY_ARRAY, useDispose, useSelectionSync } from '../util'
+import { applyPierced, EMPTY_ARRAY, readPierced, useDispose, useLiveDefaults, useSelectionSync } from '../util'
 
 type ObjectRef = RefObject<Object3D | null>
 
-export type OutlineProps = ConstructorParameters<typeof OutlineEffect>[2] &
+type OutlineEffectOptions = NonNullable<ConstructorParameters<typeof OutlineEffect>[2]>
+
+export type OutlineProps = Omit<OutlineEffectOptions, 'visibleEdgeColor' | 'hiddenEdgeColor'> &
   Partial<{
     selection: Object3D | Object3D[] | ObjectRef | ObjectRef[]
     selectionLayer: number
+    visibleEdgeColor: ColorRepresentation
+    hiddenEdgeColor: ColorRepresentation
     ref?: Ref<OutlineEffect>
   }>
 
+// Every OutlineEffect option that has a real setter (verified against
+// postprocessing's source) - resolutionScale/resolutionX/resolutionY are
+// the only ones without one, since they only feed the internal blur pass
+// at construction time. scene/camera are required constructor args, so
+// OutlineEffect can't use createEffectComponent (needs `new Effect()` to
+// work with zero args) - built by hand instead.
+const LIVE_KEYS = [
+  'patternTexture',
+  'patternScale',
+  'edgeStrength',
+  'pulseSpeed',
+  'visibleEdgeColor',
+  'hiddenEdgeColor',
+  'multisampling',
+  'width',
+  'height',
+  'kernelSize',
+  'blur',
+  'xRay',
+  'dithering',
+  'blendMode-blendFunction',
+]
+
+// The setter stores whatever it's given as-is, unlike the constructor -
+// wrap in a Color here too, or a raw hex/string breaks the shader uniform.
+function set(effect: OutlineEffect, key: string, value: unknown): void {
+  if (key === 'visibleEdgeColor' || key === 'hiddenEdgeColor') applyPierced(effect, key, new Color(value as never))
+  else applyPierced(effect, key, value)
+}
+
 export function Outline({
   selection = EMPTY_ARRAY,
   selectionLayer = 10,
   blendFunction,
-  patternTexture,
-  patternScale,
-  edgeStrength,
-  pulseSpeed,
-  visibleEdgeColor,
-  hiddenEdgeColor,
-  multisampling,
   resolutionScale,
   resolutionX,
   resolutionY,
-  width,
-  height,
-  kernelSize,
-  blur,
-  xRay,
   ref,
+  ...liveProps
 }: OutlineProps) {
-  const { scene, camera } = use(EffectComposerContext)
+  const { scene, camera, autoClear } = use(EffectComposerContext)
 
   const effect = useMemo(
-    () =>
-      new OutlineEffect(scene, camera, {
-        blendFunction,
-        patternTexture,
-        patternScale,
-        edgeStrength,
-        pulseSpeed,
-        visibleEdgeColor,
-        hiddenEdgeColor,
-        multisampling,
-        resolutionScale,
-        resolutionX,
-        resolutionY,
-        width,
-        height,
-        kernelSize,
-        blur,
-        xRay,
-      }),
-    [
-      blendFunction,
-      patternTexture,
-      patternScale,
-      edgeStrength,
-      pulseSpeed,
-      visibleEdgeColor,
-      hiddenEdgeColor,
-      multisampling,
-      resolutionScale,
-      resolutionX,
-      resolutionY,
-      width,
-      height,
-      kernelSize,
-      blur,
-      xRay,
-      camera,
-      scene,
-    ]
+    () => new OutlineEffect(scene, camera, { resolutionScale, resolutionX, resolutionY }),
+    [scene, camera, resolutionScale, resolutionX, resolutionY]
   )
 
+  useEffect(() => {
+    if (autoClear !== false) {
+      console.warn('Outline requires <EffectComposer autoClear={false}> to render correctly.')
+    }
+  }, [autoClear])
+
+  useLiveDefaults(
+    effect,
+    { ...liveProps, 'blendMode-blendFunction': blendFunction } as Record<string, unknown>,
+    LIVE_KEYS,
+    readPierced,
+    set
+  )
   useSelectionSync(effect, selection, selectionLayer)
   useDispose(effect)
 

package/src/effects/Pixelation.tsx

@@ -1,6 +1,14 @@
 import { PixelationEffect } from 'postprocessing'
-import { Ref, useMemo } from 'react'
-import { useDispose } from '../util'
+import type { Ref } from 'react'
+import { createEffectComponent } from '../createEffectComponent'
+
+// PixelationEffect's sole constructor arg is a bare number, not an options
+// object - granularity is a real live setter though, so it's just a normal
+// prop; only the curated default (5, vs the class's own default of 30)
+// needs a thin wrapper.
+const PixelationImpl = /* @__PURE__ */ createEffectComponent<typeof PixelationEffect, { granularity?: number }>(
+  PixelationEffect
+)
 
 export type PixelationProps = {
   granularity?: number
@@ -8,10 +16,5 @@ export type PixelationProps = {
 }
 
 export function Pixelation({ granularity = 5, ref }: PixelationProps) {
-  /** Because GlitchEffect granularity is not an object but a number, we have to define a custom prop "granularity" */
-  const effect = useMemo(() => new PixelationEffect(granularity), [granularity])
-
-  useDispose(effect)
-
-  return <primitive ref={ref} object={effect} />
+  return <PixelationImpl granularity={granularity} ref={ref} />
 }

package/src/effects/Ramp.tsx

@@ -1,6 +1,7 @@
-import { Effect } from 'postprocessing'
+import { BlendFunction, Effect } from 'postprocessing'
+import type { Ref } from 'react'
 import { Uniform } from 'three'
-import { wrapEffect } from '../wrapEffect'
+import { createEffectComponent } from '../createEffectComponent'
 
 const RampShader = {
   fragmentShader: /* glsl */ `
@@ -72,6 +73,9 @@ export enum RampType {
   MirroredLinear,
 }
 
+type RampTuple2 = [number, number]
+type RampTuple4 = [number, number, number, number]
+
 export class RampEffect extends Effect {
   constructor({
     /**
@@ -83,25 +87,25 @@ export class RampEffect extends Effect {
      *
      * Ranges from `[0 - 1]` as `[x, y]`. Default is `[0.5, 0.5]`.
      */
-    rampStart = [0.5, 0.5],
+    rampStart = [0.5, 0.5] as RampTuple2,
     /**
      * Ending point of the ramp gradient in normalized coordinates.
      *
      * Ranges from `[0 - 1]` as `[x, y]`. Default is `[1, 1]`
      */
-    rampEnd = [1, 1],
+    rampEnd = [1, 1] as RampTuple2,
     /**
      * Color at the starting point of the gradient.
      *
      * Default is black: `[0, 0, 0, 1]`
      */
-    startColor = [0, 0, 0, 1],
+    startColor = [0, 0, 0, 1] as RampTuple4,
     /**
      * Color at the ending point of the gradient.
      *
      * Default is white: `[1, 1, 1, 1]`
      */
-    endColor = [1, 1, 1, 1],
+    endColor = [1, 1, 1, 1] as RampTuple4,
     /**
      * Bias for the interpolation curve when both bias and gain are 0.5.
      *
@@ -145,6 +149,91 @@ export class RampEffect 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 rampType(): RampType {
+    return this.u('rampType')
+  }
+  set rampType(value: RampType) {
+    this.setU('rampType', value)
+  }
+
+  get rampStart(): RampTuple2 {
+    return this.u('rampStart')
+  }
+  set rampStart(value: RampTuple2) {
+    this.setU('rampStart', value)
+  }
+
+  get rampEnd(): RampTuple2 {
+    return this.u('rampEnd')
+  }
+  set rampEnd(value: RampTuple2) {
+    this.setU('rampEnd', value)
+  }
+
+  get startColor(): RampTuple4 {
+    return this.u('startColor')
+  }
+  set startColor(value: RampTuple4) {
+    this.setU('startColor', value)
+  }
+
+  get endColor(): RampTuple4 {
+    return this.u('endColor')
+  }
+  set endColor(value: RampTuple4) {
+    this.setU('endColor', value)
+  }
+
+  get rampBias(): number {
+    return this.u('rampBias')
+  }
+  set rampBias(value: number) {
+    this.setU('rampBias', value)
+  }
+
+  get rampGain(): number {
+    return this.u('rampGain')
+  }
+  set rampGain(value: number) {
+    this.setU('rampGain', value)
+  }
+
+  get rampMask(): boolean {
+    return this.u('rampMask')
+  }
+  set rampMask(value: boolean) {
+    this.setU('rampMask', value)
+  }
+
+  get rampInvert(): boolean {
+    return this.u('rampInvert')
+  }
+  set rampInvert(value: boolean) {
+    this.setU('rampInvert', value)
+  }
+}
+
+export type RampProps = {
+  blendFunction?: BlendFunction
+  rampType?: RampType
+  rampStart?: RampTuple2
+  rampEnd?: RampTuple2
+  startColor?: RampTuple4
+  endColor?: RampTuple4
+  rampBias?: number
+  rampGain?: number
+  rampMask?: boolean
+  rampInvert?: boolean
+  ref?: Ref<RampEffect>
 }
 
-export const Ramp = /* @__PURE__ */ wrapEffect(RampEffect)
+export const Ramp = /* @__PURE__ */ createEffectComponent<typeof RampEffect, RampProps>(RampEffect)

package/src/effects/SMAA.tsx

@@ -1,4 +1,20 @@
 import { SMAAEffect } from 'postprocessing'
-import { wrapEffect } from '../wrapEffect'
+import type { Ref } from 'react'
+import { useMemo } from 'react'
+import { createEffectComponent, type EffectOptions } from '../createEffectComponent'
 
-export const SMAA = /* @__PURE__ */ wrapEffect(SMAAEffect)
+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,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} />
+}