@react-three/postprocessing 3.0.5 → 3.1.1

package/src/EffectGroup.tsx

@@ -0,0 +1,74 @@
+import { Effect, EffectPass } from 'postprocessing'
+import { use, useImperativeHandle, useLayoutEffect, useRef, useState, type ReactNode, type Ref } from 'react'
+import type { Group } from 'three'
+import { disposePassWithoutEffects, EffectComposerContext, groupPasses } from './EffectComposer'
+import { readGroupChildren, updateIfChanged } from './util'
+
+export type EffectGroupProps = {
+  /** Toggles the whole pass, like Pass.enabled in vanilla postprocessing - cheap, no reconstruction. */
+  enabled?: boolean
+  children: ReactNode
+  ref?: Ref<EffectPass>
+}
+
+// Groups its children into one EffectPass instead of relying on
+// EffectComposer's automatic consecutive-effect merging. Renders children
+// into a hidden inner <group> (invisible to EffectComposer's own top-level
+// walk) and renders the resulting pass back out via <primitive> at this
+// component's own JSX position, so EffectComposer's existing bare-Pass
+// passthrough places it correctly relative to sibling effects.
+export function EffectGroup({ enabled = true, children, ref }: EffectGroupProps) {
+  const { camera, requestRebuild } = use(EffectComposerContext)
+
+  const group = useRef<Group>(null!)
+  const effectsRef = useRef<Effect[]>([])
+  const [pass, setPass] = useState<EffectPass | null>(null)
+
+  // Mirrors EffectComposer's own buildPasses: always constructs a fresh
+  // EffectPass when the effect list changes, rather than updating one in
+  // place - so composer.addPass() runs its normal setSize/initialize dance
+  // for every effect, with nothing to replicate by hand here.
+  useLayoutEffect(() => {
+    const effects = readGroupChildren(group.current, (object): object is Effect => object instanceof Effect)
+    if (!updateIfChanged(effectsRef, effects)) return
+
+    if (!effects.length) {
+      setPass(null)
+      return
+    }
+
+    const newPass = new EffectPass(camera, ...effects)
+    groupPasses.add(newPass)
+    setPass(newPass)
+  })
+
+  // useLayoutEffect (not useEffect) so `enabled` is applied before
+  // EffectComposer's own effect adds this pass to the composer.
+  useLayoutEffect(() => {
+    if (pass) pass.enabled = enabled
+  }, [pass, enabled])
+
+  // A local state update above doesn't re-render EffectComposer, so its own
+  // tree walk would never notice this pass appearing/disappearing.
+  useLayoutEffect(() => {
+    requestRebuild()
+  }, [pass, requestRebuild])
+
+  // Disposes whichever pass this replaces (or the last one, on unmount) -
+  // the only place a pass gets disposed, so there's no double-dispose risk
+  // from also doing it inline above where `pass` is replaced.
+  useLayoutEffect(() => {
+    return () => {
+      if (pass) disposePassWithoutEffects(pass)
+    }
+  }, [pass])
+
+  useImperativeHandle(ref, () => pass as EffectPass, [pass])
+
+  return (
+    <>
+      <group ref={group}>{children}</group>
+      {pass && <primitive object={pass} />}
+    </>
+  )
+}

package/src/createEffectComponent.tsx

@@ -0,0 +1,71 @@
+import { extend, useThree } from '@react-three/fiber'
+import type { BlendFunction, Effect, Pass } from 'postprocessing'
+import type { ExoticComponent, JSX, Ref } from 'react'
+import { useRef } from 'react'
+import { useLiveDefaults, useMergeRefs } from './util'
+
+export type EffectConstructor = new (...args: any[]) => Effect | Pass
+
+// The effect's own options type, straight off its constructor - postprocessing
+// already types every effect's sole options object precisely (either inline or,
+// like BloomEffect, as a named exported type); this just strips the `| undefined`
+// that comes from the parameter being optional.
+export type EffectOptions<T extends EffectConstructor> = NonNullable<ConstructorParameters<T>[0]>
+
+const components = new WeakMap<EffectConstructor, ExoticComponent<any> | string>()
+let i = 0
+
+const BLEND_KEYS = ['blendMode-blendFunction', 'blendMode-opacity-value']
+
+/**
+ * Registers `effect` as a JSX intrinsic once per class and returns a
+ * component that renders it. Everything else - construction from `args`,
+ * live prop application (with the same Color/Vector coercion and reset-
+ * to-default on removal any r3f element gets), disposal - is r3f's own
+ * reconciler, same rules as `<mesh>`/`<meshStandardMaterial>`. Only fits
+ * effects whose constructor works with zero arguments (`new Effect()`) -
+ * r3f's own reset-on-removal falls back to `0` otherwise, which is wrong
+ * for anything non-numeric. Effects that require e.g. scene/camera stay
+ * hand-rolled (see Outline.tsx, SelectiveBloom.tsx, ShockWave.tsx).
+ *
+ * `blendFunction`/`opacity` are pierced through to `blendMode-*` - every
+ * `Effect` has them on a nested `blendMode`, not on the effect itself, so a
+ * plain top-level prop would silently land on a stray, unread property.
+ * Applied via useLiveDefaults, not as plain JSX props: BlendMode's own
+ * constructor requires `blendFunction` (no default), so its constructor
+ * length isn't 0 either, and r3f's native reset-on-removal falls back to
+ * `changedProps[prop] = 0` - which is BlendFunction.SKIP, not a merely
+ * "wrong" blend function but one that hides the effect entirely.
+ */
+export function createEffectComponent<T extends EffectConstructor, P extends object>(
+  effect: T
+): (
+  props: P & {
+    blendFunction?: BlendFunction
+    opacity?: number
+    args?: ConstructorParameters<T>
+    ref?: Ref<InstanceType<T>>
+  }
+) => JSX.Element {
+  return function EffectComponent({ blendFunction, opacity, ref, ...props }: any) {
+    let Component = components.get(effect)
+
+    if (!Component) {
+      const key = `@react-three/postprocessing/${effect.name}-${i++}`
+      extend({ [key]: effect })
+      components.set(effect, (Component = key))
+    }
+
+    const camera = useThree((state) => state.camera)
+    const localRef = useRef<InstanceType<T>>(null)
+    const setRef = useMergeRefs(localRef, ref)
+
+    useLiveDefaults(
+      localRef,
+      { 'blendMode-blendFunction': blendFunction, 'blendMode-opacity-value': opacity },
+      BLEND_KEYS
+    )
+
+    return <Component ref={setRef} camera={camera} {...props} />
+  }
+}

package/src/effects/ASCII.tsx

@@ -2,9 +2,9 @@
 // https://twitter.com/emilwidlund/status/1652386482420609024
 
 import { Effect } from 'postprocessing'
-import { Ref, useMemo } from 'react'
-import { CanvasTexture, Color, NearestFilter, RepeatWrapping, Texture, Uniform } from 'three'
-import { useDispose } from '../util'
+import type { Ref } from 'react'
+import { CanvasTexture, Color, type ColorRepresentation, NearestFilter, RepeatWrapping, Texture, Uniform } from 'three'
+import { createEffectComponent } from '../createEffectComponent'
 
 const fragment = /* glsl */ `
   uniform sampler2D uCharacters;
@@ -47,17 +47,21 @@ const fragment = /* glsl */ `
   }
 `
 
-interface IASCIIEffectProps {
+export type ASCIIProps = {
   font?: string
   characters?: string
   fontSize?: number
   cellSize?: number
-  color?: string
+  color?: ColorRepresentation
   invert?: boolean
   ref?: Ref<ASCIIEffect>
 }
 
 class ASCIIEffect extends Effect {
+  private _font: string
+  private _characters: string
+  private _fontSize: number
+
   constructor({
     font = 'arial',
     characters = ` .:,'-^=*+?!|0#X%WM@`,
@@ -65,7 +69,7 @@ class ASCIIEffect extends Effect {
     cellSize = 16,
     color = '#ffffff',
     invert = false,
-  }: Omit<IASCIIEffectProps, 'ref'> = {}) {
+  }: Omit<ASCIIProps, 'ref'> = {}) {
     const uniforms = new Map<string, Uniform>([
       ['uCharacters', new Uniform(new Texture())],
       ['uCellSize', new Uniform(cellSize)],
@@ -76,11 +80,71 @@ class ASCIIEffect extends Effect {
 
     super('ASCIIEffect', fragment, { uniforms })
 
-    const charactersTextureUniform = this.uniforms.get('uCharacters')
+    this._font = font
+    this._characters = characters
+    this._fontSize = fontSize
+    this.updateCharactersTexture()
+  }
 
-    if (charactersTextureUniform) {
-      charactersTextureUniform.value = this.createCharactersTexture(characters, font, fontSize)
-    }
+  get cellSize(): number {
+    return this.uniforms.get('uCellSize')!.value
+  }
+
+  set cellSize(value: number) {
+    this.uniforms.get('uCellSize')!.value = value
+  }
+
+  get invert(): boolean {
+    return this.uniforms.get('uInvert')!.value
+  }
+
+  set invert(value: boolean) {
+    this.uniforms.get('uInvert')!.value = value
+  }
+
+  get color(): Color {
+    return this.uniforms.get('uColor')!.value
+  }
+
+  set color(value: ColorRepresentation) {
+    this.uniforms.get('uColor')!.value.set(value)
+  }
+
+  get font(): string {
+    return this._font
+  }
+
+  set font(value: string) {
+    this._font = value
+    this.updateCharactersTexture()
+  }
+
+  get characters(): string {
+    return this._characters
+  }
+
+  set characters(value: string) {
+    this._characters = value
+    this.uniforms.get('uCharactersCount')!.value = value.length
+    this.updateCharactersTexture()
+  }
+
+  get fontSize(): number {
+    return this._fontSize
+  }
+
+  set fontSize(value: number) {
+    this._fontSize = value
+    this.updateCharactersTexture()
+  }
+
+  // Regenerates the character atlas texture - characters/font/fontSize have
+  // no cheaper live update path, unlike the plain-uniform props above.
+  private updateCharactersTexture(): void {
+    const uniform = this.uniforms.get('uCharacters')!
+    const previous = uniform.value as Texture
+    uniform.value = this.createCharactersTexture(this._characters, this._font, this._fontSize)
+    previous.dispose()
   }
 
   /** Draws the characters on a Canvas and returns a texture */
@@ -116,21 +180,4 @@ class ASCIIEffect extends Effect {
   }
 }
 
-export function ASCII({
-  font = 'arial',
-  characters = ` .:,'-^=*+?!|0#X%WM@`,
-  fontSize = 54,
-  cellSize = 16,
-  color = '#ffffff',
-  invert = false,
-  ref,
-}: IASCIIEffectProps) {
-  const effect = useMemo(
-    () => new ASCIIEffect({ characters, font, fontSize, cellSize, color, invert }),
-    [characters, fontSize, cellSize, color, invert, font]
-  )
-
-  useDispose(effect)
-
-  return <primitive ref={ref} object={effect} />
-}
+export const ASCII = /* @__PURE__ */ createEffectComponent<typeof ASCIIEffect, ASCIIProps>(ASCIIEffect)

package/src/effects/Autofocus.tsx

@@ -1,11 +1,9 @@
 import { createPortal, useFrame, useThree, type Vector3 as R3FVector3 } from '@react-three/fiber'
 import { easing } from 'maath'
-import { CopyPass, DepthOfFieldEffect, DepthPickingPass } from 'postprocessing'
+import { DepthOfFieldEffect } from 'postprocessing'
 import {
   Ref,
   useCallback,
-  useContext,
-  useEffect,
   useImperativeHandle,
   useMemo,
   useRef,
@@ -15,27 +13,10 @@ import {
 } from 'react'
 import { Mesh, Vector3 } from 'three'
 
-import { EffectComposerContext } from '../EffectComposer'
+import { DepthPicking, useDepthPicking, type DepthPickingApi } from '../passes/DepthPicking'
 import { DepthOfField } from './DepthOfField'
 
-// EffectComposerImpl.dispose() disposes every pass it currently holds —
-// including these two, since they're added via composer.addPass below.
-// When Autofocus unmounts alongside its ancestor EffectComposer (e.g. a
-// full tree unmount), both the composer's own teardown AND this
-// component's cleanup effect would dispose the same instances. Wrapping
-// dispose here makes it safe no matter which caller gets there first.
-function makeDisposeIdempotent<T extends { dispose: () => void }>(instance: T): T {
-  let disposed = false
-  const dispose = instance.dispose.bind(instance)
-  instance.dispose = () => {
-    if (disposed) return
-    disposed = true
-    dispose()
-  }
-  return instance
-}
-
-export type AutofocusProps = ComponentProps<typeof DepthOfField> & {
+export type AutofocusProps = Omit<ComponentProps<typeof DepthOfField>, 'ref'> & {
   target?: R3FVector3
   /** should the target follow the pointer */
   mouse?: boolean
@@ -64,50 +45,22 @@ export function Autofocus({
   ...props
 }: AutofocusProps) {
   const dofRef = useRef<DepthOfFieldEffect>(null)
-  const hitpointRef = useRef<Mesh>(null)
-  const targetRef = useRef<Mesh>(null)
+  const pickRef = useRef<DepthPickingApi>(null)
+  const getHit = useDepthPicking(pickRef)
+  const hitpointMarkerRef = useRef<Mesh>(null)
+  const dofTargetMarkerRef = useRef<Mesh>(null)
 
   const scene = useThree(({ scene }) => scene)
   const pointer = useThree(({ pointer }) => pointer)
-  const { composer, camera } = useContext(EffectComposerContext)
-
-  // see: https://codesandbox.io/s/depthpickingpass-x130hg
-  const [depthPickingPass] = useState(() => makeDisposeIdempotent(new DepthPickingPass()))
-  const [copyPass] = useState(() => makeDisposeIdempotent(new CopyPass()))
-  useEffect(() => {
-    composer.addPass(depthPickingPass)
-    composer.addPass(copyPass)
-    return () => {
-      composer.removePass(depthPickingPass)
-      composer.removePass(copyPass)
-    }
-  }, [composer, depthPickingPass, copyPass])
-
-  useEffect(() => {
-    return () => {
-      depthPickingPass.dispose()
-      copyPass.dispose()
-    }
-  }, [depthPickingPass, copyPass])
 
-  const [hitpoint] = useState(() => new Vector3(0, 0, 0))
-
-  const [ndc] = useState(() => new Vector3(0, 0, 0))
-  const getHit = useCallback(
-    async (x: number, y: number) => {
-      ndc.x = x
-      ndc.y = y
-      ndc.z = await depthPickingPass.readDepth(ndc)
-      ndc.z = ndc.z * 2.0 - 1.0
-      const hit = 1 - ndc.z > 0.0000001 // it is missed if ndc.z is close to 1
-      return hit ? ndc.unproject(camera) : false
-    },
-    [ndc, depthPickingPass, camera]
-  )
+  // A stable non-null value, purely to enable DepthOfField's own autoFocus
+  // mode (`target != null`) - the actual per-frame value is applied
+  // imperatively to dofRef.current.target below.
+  const [autoFocusMarker] = useState(() => new Vector3())
+  const [hitpoint] = useState(() => new Vector3())
 
   const update = useCallback(
     async (delta: number, updateTarget = true) => {
-      // Update hitpoint
       if (target) {
         hitpoint.set(...(target as unknown as [number, number, number]))
       } else {
@@ -116,7 +69,6 @@ export function Autofocus({
         if (hit) hitpoint.copy(hit)
       }
 
-      // Update target
       if (updateTarget && dofRef.current?.target) {
         if (smoothTime > 0 && delta > 0) {
           easing.damp3(dofRef.current.target, hitpoint, smoothTime, delta)
@@ -125,42 +77,37 @@ export function Autofocus({
         }
       }
     },
-    [target, hitpoint, followMouse, getHit, smoothTime, pointer]
+    [target, hitpoint, followMouse, pointer, getHit, smoothTime]
   )
 
-  useFrame(async (_, delta) => {
+  useFrame((_, delta) => {
     if (!manual) {
       update(delta)
     }
-    if (hitpointRef.current) {
-      hitpointRef.current.position.copy(hitpoint)
+    if (hitpointMarkerRef.current) {
+      hitpointMarkerRef.current.position.copy(hitpoint)
     }
-    if (targetRef.current && dofRef.current?.target) {
-      targetRef.current.position.copy(dofRef.current.target)
+    if (dofTargetMarkerRef.current && dofRef.current?.target) {
+      dofTargetMarkerRef.current.position.copy(dofRef.current.target)
     }
   })
 
   // Ref API
-  const api = useMemo<AutofocusApi>(
-    () => ({
-      dofRef,
-      hitpoint,
-      update,
-    }),
-    [hitpoint, update]
-  )
+  const api = useMemo<AutofocusApi>(() => ({ dofRef, hitpoint, update }), [hitpoint, update])
   useImperativeHandle(ref, () => api, [api])
 
   return (
     <>
+      <DepthPicking ref={pickRef} />
+
       {debug
         ? createPortal(
             <>
-              <mesh ref={hitpointRef}>
+              <mesh ref={hitpointMarkerRef}>
                 <sphereGeometry args={[debug, 16, 16]} />
                 <meshBasicMaterial color="#00ff00" opacity={1} transparent depthWrite={false} />
               </mesh>
-              <mesh ref={targetRef}>
+              <mesh ref={dofTargetMarkerRef}>
                 <sphereGeometry args={[debug / 2, 16, 16]} />
                 <meshBasicMaterial color="#00ff00" opacity={0.5} transparent depthWrite={false} />
               </mesh>
@@ -169,7 +116,7 @@ export function Autofocus({
           )
         : null}
 
-      <DepthOfField ref={dofRef} {...props} target={hitpoint} />
+      <DepthOfField ref={dofRef} {...props} target={autoFocusMarker} />
     </>
   )
 }

package/src/effects/Bloom.tsx

@@ -1,6 +1,34 @@
 import { BlendFunction, BloomEffect } from 'postprocessing'
-import { wrapEffect } from '../wrapEffect'
+import type { Ref } from 'react'
+import { useMemo } from 'react'
+import { createEffectComponent, type EffectOptions } from '../createEffectComponent'
 
-export const Bloom = /* @__PURE__ */ wrapEffect(BloomEffect, {
-  blendFunction: BlendFunction.ADD,
-})
+type BloomOptions = EffectOptions<typeof BloomEffect>
+
+const BloomImpl = /* @__PURE__ */ createEffectComponent<typeof BloomEffect, BloomOptions>(BloomEffect)
+
+export type BloomProps = BloomOptions & { opacity?: number; ref?: Ref<BloomEffect> }
+
+// luminanceThreshold/luminanceSmoothing/mipmapBlur/radius/levels/resolution*
+// have no live setter in postprocessing - routed through args so they still
+// work as plain props, just via reconstruction instead of mutation.
+export function Bloom({
+  blendFunction = BlendFunction.ADD,
+  luminanceThreshold,
+  luminanceSmoothing,
+  mipmapBlur,
+  radius,
+  levels,
+  resolutionScale,
+  resolutionX,
+  resolutionY,
+  ...liveProps
+}: BloomProps) {
+  const args = useMemo<[BloomOptions]>(
+    () => [
+      { luminanceThreshold, luminanceSmoothing, mipmapBlur, radius, levels, resolutionScale, resolutionX, resolutionY },
+    ],
+    [luminanceThreshold, luminanceSmoothing, mipmapBlur, radius, levels, resolutionScale, resolutionX, resolutionY]
+  )
+  return <BloomImpl blendFunction={blendFunction} args={args} {...liveProps} />
+}

package/src/effects/BrightnessContrast.tsx

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

package/src/effects/ChromaticAberration.tsx

@@ -1,30 +1,22 @@
 import type { ReactThreeFiber } from '@react-three/fiber'
 import { ChromaticAberrationEffect } from 'postprocessing'
 import type { Ref } from 'react'
-import { useMemo } from 'react'
-import { useDispose, useVector2 } from '../util'
+import { createEffectComponent, type EffectOptions } from '../createEffectComponent'
 
+// radialModulation/modulationOffset are typed as required by postprocessing's
+// own .d.ts, but its JSDoc confirms both are optional with defaults - an
+// upstream declaration bug, not a real constraint.
 export type ChromaticAberrationProps = Omit<
-  Partial<ConstructorParameters<typeof ChromaticAberrationEffect>[0]>,
-  'offset'
+  EffectOptions<typeof ChromaticAberrationEffect>,
+  'offset' | 'radialModulation' | 'modulationOffset'
 > & {
-  ref?: Ref<ChromaticAberrationEffect>
   offset?: ReactThreeFiber.Vector2
+  radialModulation?: boolean
+  modulationOffset?: number
+  ref?: Ref<ChromaticAberrationEffect>
 }
 
-export function ChromaticAberration({ ref, ...props }: ChromaticAberrationProps) {
-  const offset = useVector2(props, 'offset')
-
-  const effect = useMemo(
-    () =>
-      new ChromaticAberrationEffect({
-        ...props,
-        offset,
-      } as ConstructorParameters<typeof ChromaticAberrationEffect>[0]),
-    [offset, props]
-  )
-
-  useDispose(effect)
-
-  return <primitive object={effect} ref={ref} />
-}
+export const ChromaticAberration = /* @__PURE__ */ createEffectComponent<
+  typeof ChromaticAberrationEffect,
+  ChromaticAberrationProps
+>(ChromaticAberrationEffect)

package/src/effects/ColorAverage.tsx

@@ -1,17 +1,4 @@
-import { BlendFunction, ColorAverageEffect } from 'postprocessing'
-import type { Ref } from 'react'
-import { useMemo } from 'react'
-import { useDispose } from '../util'
+import { ColorAverageEffect } from 'postprocessing'
+import { createEffectComponent } from '../createEffectComponent'
 
-export type ColorAverageProps = {
-  blendFunction?: BlendFunction
-  ref?: Ref<ColorAverageEffect>
-}
-
-export function ColorAverage({ blendFunction = BlendFunction.NORMAL, ref }: ColorAverageProps) {
-  const effect = useMemo(() => new ColorAverageEffect(blendFunction), [blendFunction])
-
-  useDispose(effect)
-
-  return <primitive object={effect} ref={ref} />
-}
+export const ColorAverage = /* @__PURE__ */ createEffectComponent<typeof ColorAverageEffect, object>(ColorAverageEffect)

package/src/effects/ColorDepth.tsx

@@ -1,4 +1,25 @@
 import { ColorDepthEffect } from 'postprocessing'
-import { wrapEffect } from '../wrapEffect'
+import type { Ref } from 'react'
+import { createEffectComponent, type EffectOptions } from '../createEffectComponent'
 
-export const ColorDepth = /* @__PURE__ */ wrapEffect(ColorDepthEffect)
+const ColorDepthImpl = /* @__PURE__ */ createEffectComponent<
+  typeof ColorDepthEffect,
+  Omit<EffectOptions<typeof ColorDepthEffect>, 'bits'> & { bitDepth?: number }
+>(ColorDepthEffect)
+
+export type ColorDepthProps = EffectOptions<typeof ColorDepthEffect> & {
+  opacity?: number
+  ref?: Ref<ColorDepthEffect>
+}
+
+// bits (the constructor's option name) has no live setter of its own in
+// postprocessing - only the differently-named bitDepth does (bits is a
+// plain, dead field on the instance). Renamed here so it still works as a
+// plain prop after the initial mount.
+export function ColorDepth({ bits, ...props }: ColorDepthProps) {
+  // Only set bitDepth when bits is actually provided - r3f's reset-on-
+  // removal only fires when a key is absent from the new props, not when
+  // it's present but undefined.
+  if (bits !== undefined) (props as Record<string, unknown>).bitDepth = bits
+  return <ColorDepthImpl {...props} />
+}

package/src/effects/Depth.tsx

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