@react-three/postprocessing 3.0.4 → 3.1.0

package/src/effects/Autofocus.tsx

@@ -1,153 +1,122 @@
-import * as THREE from 'three'
-import React, {
-  useRef,
-  useContext,
-  useState,
-  useEffect,
-  useCallback,
-  forwardRef,
-  useImperativeHandle,
-  RefObject,
-  useMemo,
-} from 'react'
-import { useThree, useFrame, createPortal, type Vector3 } from '@react-three/fiber'
-import { CopyPass, DepthPickingPass, DepthOfFieldEffect } from 'postprocessing'
-import { easing } from 'maath'
-
-import { DepthOfField } from './DepthOfField'
-import { EffectComposerContext } from '../EffectComposer'
-
-export type AutofocusProps = React.ComponentProps<typeof DepthOfField> & {
-  target?: Vector3
-  /** should the target follow the pointer */
-  mouse?: boolean
-  /** size of the debug green point  */
-  debug?: number
-  /** manual update */
-  manual?: boolean
-  /** approximate time to reach the target */
-  smoothTime?: number
-}
-
-export type AutofocusApi = {
-  dofRef: RefObject<DepthOfFieldEffect | null>
-  hitpoint: THREE.Vector3
-  update: (delta: number, updateTarget: boolean) => void
-}
-
-export const Autofocus = /* @__PURE__ */ forwardRef<AutofocusApi, AutofocusProps>(
-  (
-    { target = undefined, mouse: followMouse = false, debug = undefined, manual = false, smoothTime = 0.25, ...props },
-    fref
-  ) => {
-    const dofRef = useRef<DepthOfFieldEffect>(null)
-    const hitpointRef = useRef<THREE.Mesh>(null)
-    const targetRef = useRef<THREE.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(() => new DepthPickingPass())
-    const [copyPass] = useState(() => 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 THREE.Vector3(0, 0, 0))
-
-    const [ndc] = useState(() => new THREE.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]
-    )
-
-    const update = useCallback(
-      async (delta: number, updateTarget = true) => {
-        // Update hitpoint
-        if (target) {
-          hitpoint.set(...(target as [number, number, number]))
-        } else {
-          const { x, y } = followMouse ? pointer : { x: 0, y: 0 }
-          const hit = await getHit(x, y)
-          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)
-          } else {
-            dofRef.current.target.copy(hitpoint)
-          }
-        }
-      },
-      [target, hitpoint, followMouse, getHit, smoothTime, pointer]
-    )
-
-    useFrame(async (_, delta) => {
-      if (!manual) {
-        update(delta)
-      }
-      if (hitpointRef.current) {
-        hitpointRef.current.position.copy(hitpoint)
-      }
-      if (targetRef.current && dofRef.current?.target) {
-        targetRef.current.position.copy(dofRef.current.target)
-      }
-    })
-
-    // Ref API
-    const api = useMemo<AutofocusApi>(
-      () => ({
-        dofRef,
-        hitpoint,
-        update,
-      }),
-      [hitpoint, update]
-    )
-    useImperativeHandle(fref, () => api, [api])
-
-    return (
-      <>
-        {debug
-          ? createPortal(
-              <>
-                <mesh ref={hitpointRef}>
-                  <sphereGeometry args={[debug, 16, 16]} />
-                  <meshBasicMaterial color="#00ff00" opacity={1} transparent depthWrite={false} />
-                </mesh>
-                <mesh ref={targetRef}>
-                  <sphereGeometry args={[debug / 2, 16, 16]} />
-                  <meshBasicMaterial color="#00ff00" opacity={0.5} transparent depthWrite={false} />
-                </mesh>
-              </>,
-              scene
-            )
-          : null}
-
-        <DepthOfField ref={dofRef} {...props} target={hitpoint} />
-      </>
-    )
-  }
-)
+import { createPortal, useFrame, useThree, type Vector3 as R3FVector3 } from '@react-three/fiber'
+import { easing } from 'maath'
+import { DepthOfFieldEffect } from 'postprocessing'
+import {
+  Ref,
+  useCallback,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentProps,
+  type RefObject,
+} from 'react'
+import { Mesh, Vector3 } from 'three'
+
+import { DepthPicking, useDepthPicking, type DepthPickingApi } from '../passes/DepthPicking'
+import { DepthOfField } from './DepthOfField'
+
+export type AutofocusProps = Omit<ComponentProps<typeof DepthOfField>, 'ref'> & {
+  target?: R3FVector3
+  /** should the target follow the pointer */
+  mouse?: boolean
+  /** size of the debug green point  */
+  debug?: number
+  /** manual update */
+  manual?: boolean
+  /** approximate time to reach the target */
+  smoothTime?: number
+  ref?: Ref<AutofocusApi>
+}
+
+export type AutofocusApi = {
+  dofRef: RefObject<DepthOfFieldEffect | null>
+  hitpoint: Vector3
+  update: (delta: number, updateTarget: boolean) => void
+}
+
+export function Autofocus({
+  target = undefined,
+  mouse: followMouse = false,
+  debug = undefined,
+  manual = false,
+  smoothTime = 0.25,
+  ref,
+  ...props
+}: AutofocusProps) {
+  const dofRef = useRef<DepthOfFieldEffect>(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)
+
+  // 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) => {
+      if (target) {
+        hitpoint.set(...(target as unknown as [number, number, number]))
+      } else {
+        const { x, y } = followMouse ? pointer : { x: 0, y: 0 }
+        const hit = await getHit(x, y)
+        if (hit) hitpoint.copy(hit)
+      }
+
+      if (updateTarget && dofRef.current?.target) {
+        if (smoothTime > 0 && delta > 0) {
+          easing.damp3(dofRef.current.target, hitpoint, smoothTime, delta)
+        } else {
+          dofRef.current.target.copy(hitpoint)
+        }
+      }
+    },
+    [target, hitpoint, followMouse, pointer, getHit, smoothTime]
+  )
+
+  useFrame((_, delta) => {
+    if (!manual) {
+      update(delta)
+    }
+    if (hitpointMarkerRef.current) {
+      hitpointMarkerRef.current.position.copy(hitpoint)
+    }
+    if (dofTargetMarkerRef.current && dofRef.current?.target) {
+      dofTargetMarkerRef.current.position.copy(dofRef.current.target)
+    }
+  })
+
+  // Ref API
+  const api = useMemo<AutofocusApi>(() => ({ dofRef, hitpoint, update }), [hitpoint, update])
+  useImperativeHandle(ref, () => api, [api])
+
+  return (
+    <>
+      <DepthPicking ref={pickRef} />
+
+      {debug
+        ? createPortal(
+            <>
+              <mesh ref={hitpointMarkerRef}>
+                <sphereGeometry args={[debug, 16, 16]} />
+                <meshBasicMaterial color="#00ff00" opacity={1} transparent depthWrite={false} />
+              </mesh>
+              <mesh ref={dofTargetMarkerRef}>
+                <sphereGeometry args={[debug / 2, 16, 16]} />
+                <meshBasicMaterial color="#00ff00" opacity={0.5} transparent depthWrite={false} />
+              </mesh>
+            </>,
+            scene
+          )
+        : null}
+
+      <DepthOfField ref={dofRef} {...props} target={autoFocusMarker} />
+    </>
+  )
+}

package/src/effects/Bloom.tsx

@@ -1,6 +1,34 @@
-import { BloomEffect, BlendFunction } from 'postprocessing'
-import { wrapEffect } from '../util'
-
-export const Bloom = /* @__PURE__ */ wrapEffect(BloomEffect, {
-  blendFunction: BlendFunction.ADD,
-})
+import { BlendFunction, BloomEffect } from 'postprocessing'
+import type { Ref } from 'react'
+import { useMemo } from 'react'
+import { createEffectComponent, type EffectOptions } from '../createEffectComponent'
+
+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 '../util'
-
-export const BrightnessContrast = /* @__PURE__ */ wrapEffect(BrightnessContrastEffect)
+import { BrightnessContrastEffect } from 'postprocessing'
+import { createEffectComponent, type EffectOptions } from '../createEffectComponent'
+
+export const BrightnessContrast = /* @__PURE__ */ createEffectComponent<
+  typeof BrightnessContrastEffect,
+  EffectOptions<typeof BrightnessContrastEffect>
+>(BrightnessContrastEffect)

package/src/effects/ChromaticAberration.tsx

@@ -1,5 +1,22 @@
-import { ChromaticAberrationEffect } from 'postprocessing'
-import { type EffectProps, wrapEffect } from '../util'
-
-export type ChromaticAberrationProps = EffectProps<typeof ChromaticAberrationEffect>
-export const ChromaticAberration = /* @__PURE__ */ wrapEffect(ChromaticAberrationEffect)
+import type { ReactThreeFiber } from '@react-three/fiber'
+import { ChromaticAberrationEffect } from 'postprocessing'
+import type { Ref } from 'react'
+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<
+  EffectOptions<typeof ChromaticAberrationEffect>,
+  'offset' | 'radialModulation' | 'modulationOffset'
+> & {
+  offset?: ReactThreeFiber.Vector2
+  radialModulation?: boolean
+  modulationOffset?: number
+  ref?: Ref<ChromaticAberrationEffect>
+}
+
+export const ChromaticAberration = /* @__PURE__ */ createEffectComponent<
+  typeof ChromaticAberrationEffect,
+  ChromaticAberrationProps
+>(ChromaticAberrationEffect)

package/src/effects/ColorAverage.tsx

@@ -1,15 +1,4 @@
-import { ColorAverageEffect, BlendFunction } from 'postprocessing'
-import React, { Ref, forwardRef, useMemo } from 'react'
-
-export type ColorAverageProps = Partial<{
-  blendFunction: BlendFunction
-}>
-
-export const ColorAverage = /* @__PURE__ */ forwardRef<ColorAverageEffect, ColorAverageProps>(function ColorAverage(
-  { blendFunction = BlendFunction.NORMAL }: ColorAverageProps,
-  ref: Ref<ColorAverageEffect>
-) {
-  /** Because ColorAverage blendFunction is not an object but a number, we have to define a custom prop "blendFunction" */
-  const effect = useMemo(() => new ColorAverageEffect(blendFunction), [blendFunction])
-  return <primitive ref={ref} object={effect} dispose={null} />
-})
+import { ColorAverageEffect } from 'postprocessing'
+import { createEffectComponent } from '../createEffectComponent'
+
+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 '../util'
-
-export const ColorDepth = /* @__PURE__ */ wrapEffect(ColorDepthEffect)
+import { ColorDepthEffect } from 'postprocessing'
+import type { Ref } from 'react'
+import { createEffectComponent, type EffectOptions } from '../createEffectComponent'
+
+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 '../util'
-
-export const Depth = /* @__PURE__ */ wrapEffect(DepthEffect)
+import { DepthEffect } from 'postprocessing'
+import { createEffectComponent, type EffectOptions } from '../createEffectComponent'
+
+export const Depth = /* @__PURE__ */ createEffectComponent<typeof DepthEffect, EffectOptions<typeof DepthEffect>>(
+  DepthEffect
+)

package/src/effects/DepthOfField.tsx

@@ -1,89 +1,109 @@
-import { DepthOfFieldEffect, MaskFunction } from 'postprocessing'
-import { Ref, forwardRef, useMemo, useEffect, useContext } from 'react'
-import { ReactThreeFiber } from '@react-three/fiber'
-import { type DepthPackingStrategies, type Texture, Vector3 } from 'three'
-import { EffectComposerContext } from '../EffectComposer'
-
-type DOFProps = ConstructorParameters<typeof DepthOfFieldEffect>[1] &
-  Partial<{
-    target: ReactThreeFiber.Vector3
-    depthTexture: {
-      texture: Texture
-      // TODO: narrow to DepthPackingStrategies
-      packing: number
-    }
-    // TODO: not used
-    blur: number
-  }>
-
-export const DepthOfField = /* @__PURE__ */ forwardRef(function DepthOfField(
-  {
-    blendFunction,
-    worldFocusDistance,
-    worldFocusRange,
-    focusDistance,
-    focusRange,
-    focalLength,
-    bokehScale,
-    resolutionScale,
-    resolutionX,
-    resolutionY,
-    width,
-    height,
-    target,
-    depthTexture,
-    ...props
-  }: DOFProps,
-  ref: Ref<DepthOfFieldEffect>
-) {
-  const { camera } = useContext(EffectComposerContext)
-  const autoFocus = target != null
-  const effect = useMemo(() => {
-    const effect = new DepthOfFieldEffect(camera, {
-      blendFunction,
-      worldFocusDistance,
-      worldFocusRange,
-      focusDistance,
-      focusRange,
-      focalLength,
-      bokehScale,
-      resolutionScale,
-      resolutionX,
-      resolutionY,
-      width,
-      height,
-    })
-    // Creating a target enables autofocus, R3F will set via props
-    if (autoFocus) effect.target = new Vector3()
-    // Depth texture for depth picking with optional packing strategy
-    if (depthTexture) effect.setDepthTexture(depthTexture.texture, depthTexture.packing as DepthPackingStrategies)
-    // Temporary fix that restores DOF 6.21.3 behavior, everything since then lets shapes leak through the blur
-    const maskPass = (effect as any).maskPass
-    maskPass.maskFunction = MaskFunction.MULTIPLY_RGB_SET_ALPHA
-    return effect
-  }, [
-    camera,
-    blendFunction,
-    worldFocusDistance,
-    worldFocusRange,
-    focusDistance,
-    focusRange,
-    focalLength,
-    bokehScale,
-    resolutionScale,
-    resolutionX,
-    resolutionY,
-    width,
-    height,
-    autoFocus,
-    depthTexture,
-  ])
-
-  useEffect(() => {
-    return () => {
-      effect.dispose()
-    }
-  }, [effect])
-
-  return <primitive {...props} ref={ref} object={effect} target={target} />
-})
+import type { ReactThreeFiber } from '@react-three/fiber'
+import { DepthOfFieldEffect, MaskFunction } from 'postprocessing'
+import type { Ref } from 'react'
+import { use, useMemo } from 'react'
+import { type DepthPackingStrategies, type Texture, Vector3 } from 'three'
+import { EffectComposerContext } from '../EffectComposer'
+import { applyPierced, readPierced, useDispose, useLiveDefaults } from '../util'
+
+export type DepthOfFieldProps = ConstructorParameters<typeof DepthOfFieldEffect>[1] &
+  Partial<{
+    ref: Ref<DepthOfFieldEffect>
+    target: ReactThreeFiber.Vector3
+    depthTexture: {
+      texture: Texture
+      // TODO: narrow to DepthPackingStrategies
+      packing: number
+    }
+    // TODO: not used
+    blur: number
+  }>
+
+// Only bokehScale, focusDistance/focusRange (via the nested cocMaterial),
+// depthTexture (via setDepthTexture) and blendFunction have real setters in
+// postprocessing - every resolution option is construction-only. camera
+// being a required constructor arg also rules out createEffectComponent
+// (needs `new Effect()` to work with zero args).
+const LIVE_KEYS = [
+  'blendMode-blendFunction',
+  'bokehScale',
+  'cocMaterial-focusDistance',
+  'cocMaterial-focusRange',
+  'depthTexture',
+]
+
+// cocMaterial.depthBuffer/depthPacking are write-only in postprocessing
+// (setters with no matching getters) - depthPacking can't be read back at
+// all, so a reverted default always re-applies BasicDepthPacking (the same
+// value setDepthTexture itself defaults to when packing is omitted).
+function get(effect: DepthOfFieldEffect, key: string): unknown {
+  if (key !== 'depthTexture') return readPierced(effect, key)
+  const texture = (effect.cocMaterial as unknown as { uniforms: { depthBuffer: { value: unknown } } }).uniforms
+    .depthBuffer.value
+  return texture ? { texture } : undefined
+}
+
+function set(effect: DepthOfFieldEffect, key: string, value: unknown): void {
+  if (key === 'depthTexture') {
+    const dt = value as { texture?: Texture; packing?: DepthPackingStrategies } | undefined
+    effect.setDepthTexture(dt?.texture as never, dt?.packing)
+  } else applyPierced(effect, key, value)
+}
+
+export function DepthOfField({
+  ref,
+  blendFunction,
+  worldFocusDistance,
+  worldFocusRange,
+  focusDistance,
+  focusRange,
+  focalLength,
+  bokehScale,
+  resolutionScale,
+  resolutionX,
+  resolutionY,
+  width,
+  height,
+  target,
+  depthTexture,
+  ...props
+}: DepthOfFieldProps) {
+  const { camera } = use(EffectComposerContext)
+  const autoFocus = target != null
+
+  const effect = useMemo(() => {
+    const effect = new DepthOfFieldEffect(camera, {
+      worldFocusDistance,
+      worldFocusRange,
+      focalLength,
+      resolutionScale,
+      resolutionX,
+      resolutionY,
+      width,
+      height,
+    })
+    // Creating a target enables autofocus, R3F will set via props
+    if (autoFocus) effect.target = new Vector3()
+    // Temporary fix that restores DOF 6.21.3 behavior, everything since then lets shapes leak through the blur
+    effect.maskFunction = MaskFunction.MULTIPLY_RGB_SET_ALPHA
+    return effect
+  }, [camera, worldFocusDistance, worldFocusRange, focalLength, resolutionScale, resolutionX, resolutionY, width, height, autoFocus])
+
+  useLiveDefaults(
+    effect,
+    {
+      'blendMode-blendFunction': blendFunction,
+      bokehScale,
+      'cocMaterial-focusDistance': focusDistance,
+      'cocMaterial-focusRange': focusRange,
+      depthTexture,
+    },
+    LIVE_KEYS,
+    get,
+    set
+  )
+
+  useDispose(effect)
+
+  return <primitive {...props} object={effect} ref={ref} target={target} />
+}

package/src/effects/DotScreen.tsx

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

package/src/effects/FXAA.tsx

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