@react-three/postprocessing 3.0.4 → 3.1.0

package/src/util.tsx

@@ -1,55 +1,221 @@
-import React, { RefObject } from 'react'
-import { Vector2 } from 'three'
-import * as THREE from 'three'
-import { type ReactThreeFiber, type ThreeElement, extend, useThree } from '@react-three/fiber'
-import type { Effect, Pass, BlendFunction } from 'postprocessing'
-
-export const resolveRef = <T,>(ref: T | React.RefObject<T>) =>
-  typeof ref === 'object' && ref != null && 'current' in ref ? ref.current : ref
-
-export type EffectConstructor = new (...args: any[]) => Effect | Pass
-
-export type EffectProps<T extends EffectConstructor> = ThreeElement<T> &
-  ConstructorParameters<T>[0] & {
-    blendFunction?: BlendFunction
-    opacity?: number
-  }
-
-let i = 0
-const components = new WeakMap<EffectConstructor, React.ExoticComponent<any> | string>()
-
-export const wrapEffect = <T extends EffectConstructor>(effect: T, defaults?: EffectProps<T>) =>
-  /* @__PURE__ */ function Effect({ blendFunction = defaults?.blendFunction, opacity = defaults?.opacity, ...props }) {
-    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 args = React.useMemo(
-      () => [...(defaults?.args ?? []), ...(props.args ?? [{ ...defaults, ...props }])],
-      // eslint-disable-next-line react-hooks/exhaustive-deps
-      [JSON.stringify(props)]
-    )
-
-    return (
-      <Component
-        camera={camera}
-        blendMode-blendFunction={blendFunction}
-        blendMode-opacity-value={opacity}
-        {...props}
-        args={args}
-      />
-    )
-  }
-
-export const useVector2 = (props: Record<string, unknown>, key: string): THREE.Vector2 => {
-  const value = props[key] as ReactThreeFiber.Vector2 | undefined
-  return React.useMemo(() => {
-    if (typeof value === 'number') return new THREE.Vector2(value, value)
-    else if (value) return new THREE.Vector2(...(value as THREE.Vector2Tuple))
-    else return new THREE.Vector2()
-  }, [value])
-}
+import { useThree, type Instance, type ReactThreeFiber } from '@react-three/fiber'
+import type { Selection as PPSelection } from 'postprocessing'
+import { use, useCallback, useEffect, useLayoutEffect, useMemo, useRef, type Ref, type RefObject } from 'react'
+import { Group, Object3D, Vector2, Vector3, type Vector2Tuple, type Vector3Tuple } from 'three'
+import { selectionContext } from './Selection'
+
+// Stable reference for array-typed props defaulting to "nothing" - `= []`
+// as a default parameter allocates a new array on every call, which is
+// enough to retrigger any effect that depends on it.
+export const EMPTY_ARRAY: never[] = []
+
+export const resolveRef = <T,>(ref: T | RefObject<T>) =>
+  typeof ref === 'object' && ref != null && 'current' in ref ? ref.current : ref
+
+// Merges a local ref with a caller-supplied ref (object or callback form).
+// Clears localRef inside the callback ref's own returned cleanup, since
+// React 19 never re-invokes it with null once it returns one.
+export function useMergeRefs<T>(
+  localRef: RefObject<T | null>,
+  outerRef: Ref<T> | undefined
+): (instance: T | null) => void | (() => void) {
+  return useCallback(
+    (instance: T | null) => {
+      localRef.current = instance
+      if (typeof outerRef !== 'function') {
+        if (outerRef) outerRef.current = instance
+        return
+      }
+      const cleanup = outerRef(instance)
+      if (typeof cleanup !== 'function') return
+      return () => {
+        localRef.current = null
+        cleanup()
+      }
+    },
+    [localRef, outerRef]
+  )
+}
+
+// Reads a <group>'s direct r3f children, filtered by type - transparent to
+// non-host wrapper components, since r3f's instance tree already is.
+export function readGroupChildren<T>(group: Group, filter: (object: unknown) => object is T): T[] {
+  const groupInstance = (group as Group & { __r3f: Instance<Group> }).__r3f
+  return groupInstance ? groupInstance.children.map((child) => child.object).filter(filter) : []
+}
+
+// Diffs `next` against what's stored in `ref`, updating it only when the
+// contents actually changed. Returns whether it changed.
+export function updateIfChanged<T>(ref: RefObject<T[]>, next: T[]): boolean {
+  const previous = ref.current
+  if (next.length === previous.length && next.every((item, i) => item === previous[i])) return false
+  ref.current = next
+  return true
+}
+
+// Keeps `selection` synced with whichever mode is active: the manual
+// `selection` prop, or the declarative Selection/Select API (context wins).
+export function useSelectionSync(
+  effect: { selection: PPSelection },
+  selection: Object3D | Object3D[] | RefObject<Object3D | null> | RefObject<Object3D | null>[],
+  selectionLayer: number
+): void {
+  const invalidate = useThree((state) => state.invalidate)
+  const api = use(selectionContext)
+
+  useEffect(() => {
+    effect.selection.layer = selectionLayer
+    invalidate()
+  }, [effect, invalidate, selectionLayer])
+
+  useEffect(() => {
+    if (api) return
+    const resolved = (Array.isArray(selection) ? selection.map((o) => resolveRef(o)) : [resolveRef(selection)]).filter(
+      (o): o is Object3D => o != null
+    )
+    if (!resolved.length) return
+
+    effect.selection.set(resolved)
+    invalidate()
+    return () => {
+      effect.selection.clear()
+      invalidate()
+    }
+  }, [effect, selection, api, invalidate])
+
+  useEffect(() => {
+    if (api && api.enabled && api.selected?.length) {
+      effect.selection.set(api.selected)
+      invalidate()
+      return () => {
+        effect.selection.clear()
+        invalidate()
+      }
+    }
+  }, [api, effect.selection, invalidate])
+}
+
+// r3f never disposes <primitive> objects, so they must dispose themselves.
+export const useDispose = <T extends { dispose?: () => void }>(instance: T): void => {
+  useEffect(() => {
+    return () => {
+      instance?.dispose?.()
+    }
+  }, [instance])
+}
+
+// Reads a plain or r3f-pierced ("a-b-c") key off an object, matching what
+// applyProps below can write - a single reader that works for both shapes.
+export function readPierced(instance: object, key: string): unknown {
+  let target: unknown = instance
+  for (const part of key.split('-')) {
+    if (target == null) return undefined
+    target = (target as Record<string, unknown>)[part]
+  }
+  return target
+}
+
+// Writes a plain or r3f-pierced ("a-b-c") key, mirroring readPierced.
+// Deliberately a plain assignment, not r3f's applyProps: these instances
+// are built with `new`, not r3f's reconciler, so applyProps' Color/Vector
+// coercion never applies to them. Callers wrap values that need coercion.
+export function applyPierced(instance: object, key: string, value: unknown): void {
+  const parts = key.split('-')
+  let target: unknown = instance
+  for (let idx = 0; idx < parts.length - 1; idx++) {
+    if (target == null) return
+    target = (target as Record<string, unknown>)[parts[idx]]
+  }
+  if (target == null) return
+  ;(target as Record<string, unknown>)[parts[parts.length - 1]] = value
+}
+
+// Applies live-mutable properties onto an instance built via `new` (not
+// r3f's reconciler, so r3f's own prop diffing/reset never runs on it).
+// Falls back to the constructor-time default when a value is `undefined`.
+// Only calls `set` when the resolved value actually changed since the last
+// apply - some setters have side effects beyond storing the value (e.g.
+// OutlineEffect's `multisampling` disposes its render target on every set).
+export function useLiveDefaults<T extends object>(
+  instance: T | RefObject<T | null> | null,
+  values: Record<string, unknown>,
+  keys: Iterable<string>,
+  get: (instance: T, key: string) => unknown = readPierced,
+  set: (instance: T, key: string, value: unknown) => void = applyPierced
+): void {
+  const snapshotRef = useRef<{ instance: T; defaults: Map<string, unknown>; applied: Map<string, unknown> } | null>(
+    null
+  )
+  const invalidate = useThree((state) => state.invalidate)
+
+  useLayoutEffect(() => {
+    const resolved = resolveRef(instance)
+    if (!resolved) return
+    if (snapshotRef.current?.instance !== resolved) {
+      snapshotRef.current = { instance: resolved, defaults: new Map(), applied: new Map() }
+    }
+    const { defaults, applied } = snapshotRef.current
+    let changed = false
+
+    for (const key of keys) {
+      if (!defaults.has(key)) {
+        // Seed `applied` too, not just `defaults`, so an unchanged key
+        // skips `set` even on this first pass (avoids re-triggering
+        // setters with side effects, e.g. multisampling's dispose).
+        const current = get(resolved, key)
+        defaults.set(key, current)
+        applied.set(key, current)
+      }
+      const next = values[key] !== undefined ? values[key] : defaults.get(key)
+      if (Object.is(applied.get(key), next)) continue
+      set(resolved, key, next)
+      applied.set(key, next)
+      changed = true
+    }
+
+    // These instances are mutated directly (not via r3f's reconciler), so
+    // r3f never sees the change - without this, frameloop="demand" would
+    // never repaint after a live prop update.
+    if (changed) invalidate()
+  })
+}
+
+export const useVector2 = (props: Record<string, unknown>, key: string): Vector2 => {
+  const value = props[key] as ReactThreeFiber.Vector2 | undefined
+
+  return useMemo(() => {
+    if (typeof value === 'number') {
+      return new Vector2(value, value)
+    }
+
+    if (value instanceof Vector2) {
+      return value
+    }
+
+    if (value) {
+      return new Vector2(...(value as Vector2Tuple))
+    }
+
+    return new Vector2()
+  }, [value])
+}
+
+export const useVector3 = (props: Record<string, unknown>, key: string): Vector3 => {
+  const value = props[key] as ReactThreeFiber.Vector3 | undefined
+
+  return useMemo(() => {
+    if (typeof value === 'number') {
+      return new Vector3(value, value, value)
+    }
+
+    if (value instanceof Vector3) {
+      return value
+    }
+
+    if (value) {
+      return new Vector3(...(value as Vector3Tuple))
+    }
+
+    return new Vector3()
+  }, [value])
+}

package/src/wrapEffect.tsx

@@ -0,0 +1,123 @@
+import { extend, useThree } from '@react-three/fiber'
+import type { BlendFunction } from 'postprocessing'
+import { useMemo, type ExoticComponent, type JSX, type Ref } from 'react'
+import type { EffectConstructor } from './createEffectComponent'
+
+export type { EffectConstructor }
+
+// Handles three ConstructorParameters<T> shapes: required first param
+// (P), optional first param (Partial<P> — some effects in postprocessing
+// type inner fields as required even though the whole object is
+// omittable), and no params at all ({})
+type FirstConstructorParam<T extends EffectConstructor> =
+  ConstructorParameters<T> extends [infer P, ...any[]]
+    ? P
+    : ConstructorParameters<T> extends [(infer P)?, ...any[]]
+      ? Partial<P>
+      : {}
+
+export type EffectProps<T extends EffectConstructor> = FirstConstructorParam<T> & {
+  ref?: Ref<InstanceType<T>>
+  blendFunction?: BlendFunction
+  opacity?: number
+  args?: ConstructorParameters<T>
+}
+
+let i = 0
+
+const components = new WeakMap<EffectConstructor, ExoticComponent<any> | string>()
+
+const identityTokens = new WeakMap<object, number>()
+let nextIdentityToken = 0
+
+// Same object in, same token out — lets otherwise-opaque values (textures,
+// refs, any class instance) still change the fingerprint when swapped for
+// a different instance, without walking into them.
+function identityOf(value: object): number {
+  let token = identityTokens.get(value)
+  if (token === undefined) {
+    token = nextIdentityToken++
+    identityTokens.set(value, token)
+  }
+  return token
+}
+
+// Walks props into a JSON-safe fingerprint for the args memo below. Two
+// things JSON.stringify can't be trusted with here:
+//  - it throws on cycles (refs, or any three.js object with a back-
+//    reference), so cycles are cut off with a WeakSet guard instead.
+//  - it calls a value's own toJSON first if present, which for e.g.
+//    THREE.Texture re-encodes the whole image to a base64 data URL on
+//    every single render (measured ~39ms for a 512x512 texture) just to
+//    throw the result away. Reading properties directly sidesteps that.
+//  - reading properties directly instead means typed arrays need their
+//    own case: Object.keys() on one returns every numeric index, so
+//    walking a texture's backing buffer element-by-element is even
+//    slower (~340ms for the same texture) than the toJSON it replaces.
+//    Identity is enough — same buffer means unchanged.
+function fingerprint(value: unknown, seen: WeakSet<object>): unknown {
+  if (value === null || typeof value !== 'object') return value
+  if (seen.has(value)) return '[Circular]'
+
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+    return identityOf(value)
+  }
+
+  seen.add(value)
+
+  if (Array.isArray(value)) {
+    return value.map((item) => fingerprint(item, seen))
+  }
+
+  const out: Record<string, unknown> = {}
+  for (const key of Object.keys(value).sort()) {
+    out[key] = fingerprint((value as Record<string, unknown>)[key], seen)
+  }
+  return out
+}
+
+function stableStringify(value: unknown): string {
+  return JSON.stringify(fingerprint(value, new WeakSet()))
+}
+
+export function wrapEffect<T extends EffectConstructor>(
+  effect: T,
+  defaults?: EffectProps<T>
+): (props: EffectProps<T>) => JSX.Element {
+  return function WrappedEffect({
+    ref,
+    blendFunction = defaults?.blendFunction,
+    opacity = defaults?.opacity,
+    ...props
+  }) {
+    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 args = useMemo(
+      () => [
+        ...((defaults?.args as unknown as any[]) ?? []),
+        ...((props.args as unknown as any[]) ?? [{ ...defaults, ...props }]),
+      ],
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      [stableStringify(props)]
+    )
+
+    return (
+      <Component
+        camera={camera}
+        blendMode-blendFunction={blendFunction}
+        blendMode-opacity-value={opacity}
+        {...props}
+        args={args}
+        ref={ref}
+      />
+    )
+  }
+}

package/src/EffectComposer.test.tsx

@@ -1,126 +0,0 @@
-import * as React from 'react'
-import * as THREE from 'three'
-import { vi, describe, it, expect } from 'vitest'
-import { extend, createRoot, act } from '@react-three/fiber'
-import { EffectComposer } from './EffectComposer'
-import { EffectComposer as EffectComposerImpl, RenderPass, Pass, Effect, EffectPass } from 'postprocessing'
-
-// Let React know that we'll be testing effectful components
-declare global {
-  var IS_REACT_ACT_ENVIRONMENT: boolean
-}
-global.IS_REACT_ACT_ENVIRONMENT = true
-
-// Create virtual R3F root for testing
-extend(THREE as any)
-const root = createRoot({
-  style: {} as CSSStyleDeclaration,
-  addEventListener: (() => {}) as any,
-  removeEventListener: (() => {}) as any,
-  width: 1280,
-  height: 800,
-  clientWidth: 1280,
-  clientHeight: 800,
-  getContext: (() =>
-    new Proxy(
-      {},
-      {
-        get(_target, prop) {
-          switch (prop) {
-            case 'getParameter':
-              return () => 'WebGL 2' // GL_VERSION
-            case 'getExtension':
-              return () => ({}) // EXT_blend_minmax
-            case 'getContextAttributes':
-              return () => ({ alpha: true })
-            case 'getShaderPrecisionFormat':
-              return () => ({ rangeMin: 1, rangeMax: 1, precision: 1 })
-            default:
-              return () => {}
-          }
-        },
-      }
-    )) as any,
-} satisfies Partial<HTMLCanvasElement> as HTMLCanvasElement)
-root.configure({ frameloop: 'never' })
-
-const EFFECT_SHADER = 'mainImage() {}'
-
-describe('EffectComposer', () => {
-  it('should merge effects together', async () => {
-    const composerRef = React.createRef<EffectComposerImpl>()
-
-    const effectA = new Effect('A', EFFECT_SHADER)
-    const effectB = new Effect('B', EFFECT_SHADER)
-    const effectC = new Effect('C', EFFECT_SHADER)
-    const passA = new Pass()
-    const passB = new Pass()
-
-    // Forward order
-    await act(async () =>
-      root.render(
-        <EffectComposer ref={composerRef}>
-          {/* EffectPass(effectA, effectB) */}
-          <primitive object={effectA} />
-          <primitive object={effectB} />
-          {/* PassA */}
-          <primitive object={passA} />
-          {/* EffectPass(effectC) */}
-          <primitive object={effectC} />
-          {/* PassB */}
-          <primitive object={passB} />
-        </EffectComposer>
-      )
-    )
-    expect(composerRef.current!.passes.map((p) => p.constructor)).toStrictEqual([
-      RenderPass,
-      EffectPass,
-      Pass,
-      EffectPass,
-      Pass,
-    ])
-    // @ts-expect-error
-    expect((composerRef.current!.passes[1] as EffectPass).effects).toStrictEqual([effectA, effectB])
-    expect(composerRef.current!.passes[2]).toBe(passA)
-    // @ts-expect-error
-    expect((composerRef.current!.passes[3] as EffectPass).effects).toStrictEqual([effectC])
-    expect(composerRef.current!.passes[4]).toBe(passB)
-
-    // NOTE: instance children ordering is unstable until R3F v9, so we remount from scratch
-    await act(async () => root.render(null))
-
-    // Reverse order
-    await act(async () =>
-      root.render(
-        <EffectComposer ref={composerRef}>
-          {/* PassB */}
-          <primitive object={passB} />
-          {/* EffectPass(effectC) */}
-          <primitive object={effectC} />
-          {/* PassA */}
-          <primitive object={passA} />
-          {/* EffectPass(effectB, effectA) */}
-          <primitive object={effectB} />
-          <primitive object={effectA} />
-        </EffectComposer>
-      )
-    )
-    expect(composerRef.current!.passes.map((p) => p.constructor)).toStrictEqual([
-      RenderPass,
-      Pass,
-      EffectPass,
-      Pass,
-      EffectPass,
-    ])
-    expect(composerRef.current!.passes[1]).toBe(passB)
-    // @ts-expect-error
-    expect((composerRef.current!.passes[2] as EffectPass).effects).toStrictEqual([effectC])
-    expect(composerRef.current!.passes[3]).toBe(passA)
-    // @ts-expect-error
-    expect((composerRef.current!.passes[4] as EffectPass).effects).toStrictEqual([effectB, effectA])
-  })
-
-  it.skip('should split convolution effects', async () => {
-    await act(async () => root.render(null))
-  })
-})

package/src/effects/N8AO.tsx

@@ -1,81 +0,0 @@
-// From https://github.com/N8python/n8ao
-// https://twitter.com/N8Programs/status/1660996748485984261
-
-import { Ref, forwardRef, useLayoutEffect, useMemo } from 'react'
-/* @ts-ignore */
-import { N8AOPostPass } from 'n8ao'
-import { useThree, ReactThreeFiber, applyProps } from '@react-three/fiber'
-
-export type N8AOProps = {
-  aoRadius?: number
-  distanceFalloff?: number
-  intensity?: number
-  quality?: 'performance' | 'low' | 'medium' | 'high' | 'ultra'
-  aoSamples?: number
-  denoiseSamples?: number
-  denoiseRadius?: number
-  color?: ReactThreeFiber.Color
-  halfRes?: boolean
-  depthAwareUpsampling?: boolean
-  screenSpaceRadius?: boolean
-  renderMode?: 0 | 1 | 2 | 3 | 4
-}
-
-export const N8AO = /* @__PURE__ */ forwardRef<N8AOPostPass, N8AOProps>(
-  (
-    {
-      halfRes,
-      screenSpaceRadius,
-      quality,
-      depthAwareUpsampling = true,
-      aoRadius = 5,
-      aoSamples = 16,
-      denoiseSamples = 4,
-      denoiseRadius = 12,
-      distanceFalloff = 1,
-      intensity = 1,
-      color,
-      renderMode = 0,
-    },
-    ref: Ref<N8AOPostPass>
-  ) => {
-    const { camera, scene } = useThree()
-    const effect = useMemo(() => new N8AOPostPass(scene, camera), [camera, scene])
-
-    // TODO: implement dispose upstream; this effect has memory leaks without
-    useLayoutEffect(() => {
-      applyProps(effect.configuration, {
-        color,
-        aoRadius,
-        distanceFalloff,
-        intensity,
-        aoSamples,
-        denoiseSamples,
-        denoiseRadius,
-        screenSpaceRadius,
-        renderMode,
-        halfRes,
-        depthAwareUpsampling,
-      })
-    }, [
-      screenSpaceRadius,
-      color,
-      aoRadius,
-      distanceFalloff,
-      intensity,
-      aoSamples,
-      denoiseSamples,
-      denoiseRadius,
-      renderMode,
-      halfRes,
-      depthAwareUpsampling,
-      effect,
-    ])
-
-    useLayoutEffect(() => {
-      if (quality) effect.setQualityMode(quality.charAt(0).toUpperCase() + quality.slice(1))
-    }, [effect, quality])
-
-    return <primitive ref={ref} object={effect} />
-  }
-)