@react-three/postprocessing 3.0.5 → 3.1.1

package/src/passes/DepthPicking.tsx

@@ -0,0 +1,63 @@
+import { useThree } from '@react-three/fiber'
+import { CopyPass, DepthPickingPass as DepthPickingPassImpl } from 'postprocessing'
+import { use, useCallback, useEffect, useImperativeHandle, useState, type Ref } from 'react'
+import type { Camera } from 'three'
+import { Vector2, Vector3 } from 'three'
+import { EffectComposerContext } from '../EffectComposer'
+import { useDispose } from '../util'
+
+export type DepthPickingApi = {
+  readDepth: (ndc: Vector2 | Vector3) => Promise<number>
+}
+
+export type DepthPickingProps = {
+  ref?: Ref<DepthPickingApi>
+}
+
+// Mounts a vanilla `postprocessing` DepthPickingPass and exposes its
+// `readDepth` via ref - nothing else. Renders nothing. Pair with
+// `useDepthPicking` for a world-space position instead of raw depth.
+export function DepthPicking({ ref }: DepthPickingProps) {
+  const { composer } = use(EffectComposerContext)
+
+  const [depthPickingPass] = useState(() => new DepthPickingPassImpl())
+  const [copyPass] = useState(() => new CopyPass())
+  useEffect(() => {
+    composer.addPass(depthPickingPass)
+    composer.addPass(copyPass)
+    return () => {
+      composer.removePass(depthPickingPass)
+      composer.removePass(copyPass)
+    }
+  }, [composer, depthPickingPass, copyPass])
+
+  useDispose(depthPickingPass)
+  useDispose(copyPass)
+
+  useImperativeHandle(ref, () => ({ readDepth: (ndc) => depthPickingPass.readDepth(ndc) }), [depthPickingPass])
+
+  return null
+}
+
+export function useDepthPicking(pass: React.RefObject<DepthPickingApi | null>, camera?: Camera) {
+  const composerCamera = use(EffectComposerContext)?.camera
+  const defaultCamera = useThree((state) => state.camera)
+  const resolvedCamera = camera ?? composerCamera ?? defaultCamera
+  const [ndc] = useState(() => new Vector3())
+
+  return useCallback(
+    async (x: number, y: number): Promise<Vector3 | false> => {
+      if (!pass.current) return false
+      ndc.x = x
+      ndc.y = y
+      ndc.z = await pass.current.readDepth(ndc)
+      ndc.z = ndc.z * 2.0 - 1.0
+      const hit = 1 - ndc.z > 0.0000001 // missed if ndc.z is close to 1
+      // clone - unproject mutates in place, and ndc is reused across calls,
+      // so returning it directly would hand out a reference that changes
+      // under the caller on the next pick.
+      return hit ? ndc.clone().unproject(resolvedCamera) : false
+    },
+    [pass, resolvedCamera, ndc]
+  )
+}

package/src/{effects → passes}/N8AO.tsx

@@ -5,9 +5,11 @@ import { ReactThreeFiber, applyProps, useThree } from '@react-three/fiber'
 import { Ref, useLayoutEffect, useMemo } from 'react'
 /* @ts-ignore */
 import { N8AOPostPass } from 'n8ao'
+import { groupPasses } from '../EffectComposer'
 import { useDispose } from '../util'
 
 export type N8AOProps = {
+  enabled?: boolean
   aoRadius?: number
   distanceFalloff?: number
   intensity?: number
@@ -24,6 +26,7 @@ export type N8AOProps = {
 }
 
 export function N8AO({
+  enabled = true,
   halfRes,
   screenSpaceRadius,
   quality,
@@ -38,12 +41,26 @@ export function N8AO({
   renderMode = 0,
   ref,
 }: N8AOProps) {
-  const { camera, scene } = useThree()
-  const effect = useMemo(() => new N8AOPostPass(scene, camera), [camera, scene])
+  const { camera, scene, invalidate } = useThree()
+  const effect = useMemo(() => {
+    const instance = new N8AOPostPass(scene, camera)
+    // N8AOPostPass isn't a postprocessing Effect, so it's not mergeable via
+    // EffectGroup - it's already a standalone Pass, hence its own `enabled`
+    // prop below instead. Registering it here still gets it the shared
+    // trailing CopyPass safety net (see EffectComposer.tsx) so disabling it
+    // while it's the last pass in the chain doesn't blank the canvas.
+    groupPasses.add(instance)
+    return instance
+  }, [camera, scene])
 
   // TODO: implement dispose upstream; this effect has memory leaks without
   useDispose(effect)
 
+  useLayoutEffect(() => {
+    effect.enabled = enabled
+    invalidate()
+  }, [effect, enabled, invalidate])
+
   useLayoutEffect(() => {
     applyProps(effect.configuration, {
       color,
@@ -58,6 +75,9 @@ export function N8AO({
       halfRes,
       depthAwareUpsampling,
     })
+    // effect.configuration is a plain object, never r3f-managed - applyProps'
+    // own invalidate (gated behind object.__r3f) never fires for it.
+    invalidate()
   }, [
     screenSpaceRadius,
     color,
@@ -71,11 +91,15 @@ export function N8AO({
     halfRes,
     depthAwareUpsampling,
     effect,
+    invalidate,
   ])
 
   useLayoutEffect(() => {
-    if (quality) effect.setQualityMode(quality.charAt(0).toUpperCase() + quality.slice(1))
-  }, [effect, quality])
+    if (quality) {
+      effect.setQualityMode(quality.charAt(0).toUpperCase() + quality.slice(1))
+      invalidate()
+    }
+  }, [effect, quality, invalidate])
 
   return <primitive ref={ref} object={effect} />
 }

package/src/tests/Autofocus.test.tsx

@@ -0,0 +1,38 @@
+import { DepthPickingPass, EffectComposer as EffectComposerImpl, EffectPass, RenderPass } from 'postprocessing'
+import * as React from 'react'
+import { describe, expect, it } from 'vitest'
+import { EffectComposer } from '../EffectComposer'
+import { Autofocus } from '../effects/Autofocus'
+import { flush, root, strict, waitForComposer } from './test-utils'
+
+describe('Autofocus', () => {
+  it('inserts depthPickingPass right after RenderPass, not appended at the end', async () => {
+    const composerRef = React.createRef<EffectComposerImpl>()
+
+    await React.act(async () => root.render(<EffectComposer ref={composerRef}>{<Autofocus />}</EffectComposer>))
+    const composer = await waitForComposer(composerRef)
+    await flush()
+
+    expect(composer.passes[0]).toBeInstanceOf(RenderPass)
+    expect(composer.passes[1]).toBeInstanceOf(DepthPickingPass)
+
+    await React.act(async () => root.render(null))
+  })
+
+  it('never lets depthPickingPass own renderToScreen, regardless of StrictMode double-invocation', async () => {
+    const composerRef = React.createRef<EffectComposerImpl>()
+
+    await React.act(async () => root.render(strict(<EffectComposer ref={composerRef}>{<Autofocus />}</EffectComposer>)))
+    const composer = await waitForComposer(composerRef)
+    for (let i = 0; i < 10; i++) await flush()
+
+    const depthPickingPass = composer.passes.find((p) => p instanceof DepthPickingPass)!
+    expect(depthPickingPass.renderToScreen).toBe(false)
+
+    // The real, visible output (DepthOfField's own EffectPass) must own it instead.
+    const effectPass = composer.passes.find((p) => p instanceof EffectPass)!
+    expect(effectPass.renderToScreen).toBe(true)
+
+    await React.act(async () => root.render(null))
+  })
+})

package/src/tests/Bloom.test.tsx

@@ -0,0 +1,76 @@
+import { BloomEffect, EffectComposer as EffectComposerImpl } from 'postprocessing'
+import * as React from 'react'
+import { describe, expect, it } from 'vitest'
+import { EffectComposer } from '../EffectComposer'
+import { Bloom } from '../effects/Bloom'
+import { flush, root } from './test-utils'
+
+describe('Bloom', () => {
+  it('applies intensity live, without reconstructing the effect', async () => {
+    const composerRef = React.createRef<EffectComposerImpl>()
+    const ref = React.createRef<BloomEffect>()
+
+    const render = (intensity: number) =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <Bloom ref={ref} intensity={intensity} />
+        </EffectComposer>
+      )
+
+    await React.act(async () => render(1))
+    await flush()
+    const first = ref.current
+    expect(first!.intensity).toBe(1)
+
+    await React.act(async () => render(2))
+    await flush()
+
+    expect(ref.current).toBe(first)
+    expect(ref.current!.intensity).toBe(2)
+
+    await React.act(async () => root.render(null))
+  })
+
+  it('applies mipmapBlur (a construction-only option) as a plain prop, reconstructing under the hood', async () => {
+    const composerRef = React.createRef<EffectComposerImpl>()
+    const ref = React.createRef<BloomEffect>()
+
+    const render = (mipmapBlur: boolean) =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <Bloom ref={ref} mipmapBlur={mipmapBlur} />
+        </EffectComposer>
+      )
+
+    await React.act(async () => render(true))
+    await flush()
+    const first = ref.current
+    expect(first!.mipmapBlurPass.enabled).toBe(true)
+
+    await React.act(async () => render(false))
+    await flush()
+
+    expect(ref.current).not.toBe(first)
+    expect(ref.current!.mipmapBlurPass.enabled).toBe(false)
+
+    await React.act(async () => root.render(null))
+  })
+
+  it('accepts opacity, as documented in the README (#opacity narrower than createEffectComponent allows)', async () => {
+    const composerRef = React.createRef<EffectComposerImpl>()
+    const ref = React.createRef<BloomEffect>()
+
+    await React.act(async () =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <Bloom ref={ref} opacity={0.02} />
+        </EffectComposer>
+      )
+    )
+    await flush()
+
+    expect(ref.current!.blendMode.opacity.value).toBe(0.02)
+
+    await React.act(async () => root.render(null))
+  })
+})

package/src/tests/ChromaticAberration.test.tsx

@@ -28,4 +28,54 @@ describe('ChromaticAberration', () => {
 
     await React.act(async () => root.render(null))
   })
+
+  it('applies offset live without reconstructing the effect', async () => {
+    const composerRef = React.createRef<EffectComposerImpl>()
+    const ref = React.createRef<ChromaticAberrationEffect>()
+
+    const render = (x: number) =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <ChromaticAberration ref={ref} offset={[x, 0.001]} />
+        </EffectComposer>
+      )
+
+    await React.act(async () => render(0.01))
+    await flush()
+    const first = ref.current
+    expect(first!.offset.x).toBeCloseTo(0.01)
+
+    await React.act(async () => render(0.02))
+    await flush()
+
+    expect(ref.current).toBe(first)
+    expect(ref.current!.offset.x).toBeCloseTo(0.02)
+
+    await React.act(async () => root.render(null))
+  })
+
+  it('applies radialModulation live, without reconstructing the effect', async () => {
+    const composerRef = React.createRef<EffectComposerImpl>()
+    const ref = React.createRef<ChromaticAberrationEffect>()
+
+    const render = (radialModulation: boolean) =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <ChromaticAberration ref={ref} radialModulation={radialModulation} />
+        </EffectComposer>
+      )
+
+    await React.act(async () => render(false))
+    await flush()
+    const first = ref.current
+    expect(first!.radialModulation).toBe(false)
+
+    await React.act(async () => render(true))
+    await flush()
+
+    expect(ref.current).toBe(first)
+    expect(ref.current!.radialModulation).toBe(true)
+
+    await React.act(async () => root.render(null))
+  })
 })

package/src/tests/ColorDepth.test.tsx

@@ -0,0 +1,71 @@
+import { ColorDepthEffect, EffectComposer as EffectComposerImpl } from 'postprocessing'
+import * as React from 'react'
+import { describe, expect, it } from 'vitest'
+import { ColorDepth } from '../effects/ColorDepth'
+import { EffectComposer } from '../EffectComposer'
+import { flush, root } from './test-utils'
+
+describe('ColorDepth', () => {
+  it('applies bits live via the differently-named bitDepth setter, without reconstructing the effect', async () => {
+    const composerRef = React.createRef<EffectComposerImpl>()
+    const ref = React.createRef<ColorDepthEffect>()
+
+    const render = (bits: number) =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <ColorDepth ref={ref} bits={bits} />
+        </EffectComposer>
+      )
+
+    await React.act(async () => render(4))
+    await flush()
+    const first = ref.current
+    expect(first!.bitDepth).toBe(4)
+
+    await React.act(async () => render(8))
+    await flush()
+
+    expect(ref.current).toBe(first)
+    expect(ref.current!.bitDepth).toBe(8)
+
+    await React.act(async () => root.render(null))
+  })
+
+  it('resets bitDepth to its constructor default when bits is removed', async () => {
+    const composerRef = React.createRef<EffectComposerImpl>()
+    const ref = React.createRef<ColorDepthEffect>()
+
+    await React.act(async () =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <ColorDepth ref={ref} />
+        </EffectComposer>
+      )
+    )
+    await flush()
+    const defaultBitDepth = ref.current!.bitDepth
+
+    await React.act(async () =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <ColorDepth ref={ref} bits={4} />
+        </EffectComposer>
+      )
+    )
+    await flush()
+    expect(ref.current!.bitDepth).toBe(4)
+
+    await React.act(async () =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <ColorDepth ref={ref} />
+        </EffectComposer>
+      )
+    )
+    await flush()
+
+    expect(ref.current!.bitDepth).toBe(defaultBitDepth)
+
+    await React.act(async () => root.render(null))
+  })
+})

package/src/tests/DepthOfField.test.tsx

@@ -0,0 +1,130 @@
+import { DepthOfFieldEffect, EffectComposer as EffectComposerImpl } from 'postprocessing'
+import * as React from 'react'
+import { Texture } from 'three'
+import { describe, expect, it } from 'vitest'
+import { EffectComposer } from '../EffectComposer'
+import { DepthOfField } from '../effects/DepthOfField'
+import { flush, root, waitForComposer } from './test-utils'
+
+describe('DepthOfField', () => {
+  it('applies bokehScale live, without reconstructing the effect', async () => {
+    const composerRef = React.createRef<EffectComposerImpl>()
+    const ref = React.createRef<DepthOfFieldEffect>()
+
+    const render = (bokehScale: number) =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <DepthOfField ref={ref} bokehScale={bokehScale} />
+        </EffectComposer>
+      )
+
+    await React.act(async () => render(1))
+    await waitForComposer(composerRef)
+    await flush()
+    const first = ref.current
+    expect(first!.bokehScale).toBe(1)
+
+    await React.act(async () => render(2))
+    await flush()
+
+    expect(ref.current).toBe(first)
+    expect(ref.current!.bokehScale).toBe(2)
+
+    await React.act(async () => root.render(null))
+  })
+
+  it('applies focusDistance live via the nested cocMaterial, without reconstructing the effect', async () => {
+    const composerRef = React.createRef<EffectComposerImpl>()
+    const ref = React.createRef<DepthOfFieldEffect>()
+
+    const render = (focusDistance: number) =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <DepthOfField ref={ref} focusDistance={focusDistance} />
+        </EffectComposer>
+      )
+
+    await React.act(async () => render(0.1))
+    await waitForComposer(composerRef)
+    await flush()
+    const first = ref.current
+    expect(first!.cocMaterial.focusDistance).toBeCloseTo(0.1)
+
+    await React.act(async () => render(0.5))
+    await flush()
+
+    expect(ref.current).toBe(first)
+    expect(ref.current!.cocMaterial.focusDistance).toBeCloseTo(0.5)
+
+    await React.act(async () => root.render(null))
+  })
+
+  it('applies depthTexture live via setDepthTexture, without reconstructing, and resets on removal', async () => {
+    const composerRef = React.createRef<EffectComposerImpl>()
+    const ref = React.createRef<DepthOfFieldEffect>()
+    const textureA = new Texture()
+    const textureB = new Texture()
+    // cocMaterial.depthBuffer is write-only in postprocessing (setter, no
+    // getter) - the current value only reads back through its own uniform.
+    const currentDepthBuffer = () =>
+      (ref.current!.cocMaterial as unknown as { uniforms: { depthBuffer: { value: unknown } } }).uniforms.depthBuffer
+        .value
+
+    const render = (depthTexture?: { texture: Texture; packing: number }) =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <DepthOfField ref={ref} depthTexture={depthTexture} />
+        </EffectComposer>
+      )
+
+    await React.act(async () => render())
+    await waitForComposer(composerRef)
+    await flush()
+    const first = ref.current
+
+    await React.act(async () => render({ texture: textureA, packing: 0 }))
+    await flush()
+    expect(ref.current).toBe(first)
+    expect(currentDepthBuffer()).toBe(textureA)
+
+    await React.act(async () => render({ texture: textureB, packing: 0 }))
+    await flush()
+    expect(ref.current).toBe(first)
+    expect(currentDepthBuffer()).toBe(textureB)
+
+    await React.act(async () => render())
+    await flush()
+    expect(ref.current).toBe(first)
+    // Reverts to no manually-provided depth texture (undefined), the state
+    // useLiveDefaults captured as this instance's default on first apply -
+    // not whatever EffectComposer's own depth-attribute auto-wiring later
+    // assigns, which runs separately and after this.
+    expect(currentDepthBuffer()).toBeUndefined()
+
+    await React.act(async () => root.render(null))
+  })
+
+  it('still reconstructs when resolutionScale (construction-only) changes', async () => {
+    const composerRef = React.createRef<EffectComposerImpl>()
+    const ref = React.createRef<DepthOfFieldEffect>()
+
+    const render = (resolutionScale: number) =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <DepthOfField ref={ref} resolutionScale={resolutionScale} />
+        </EffectComposer>
+      )
+
+    await React.act(async () => render(0.5))
+    await waitForComposer(composerRef)
+    await flush()
+    const first = ref.current
+
+    await React.act(async () => render(1))
+    await flush()
+
+    expect(ref.current).not.toBe(first)
+
+    await React.act(async () => root.render(null))
+  })
+})