@react-three/postprocessing 3.0.5 → 3.1.0

package/src/tests/EffectComposer.test.tsx

@@ -3,6 +3,7 @@ import {
   ColorAverageEffect,
   DepthDownsamplingPass,
   Effect,
+  EffectAttribute,
   EffectComposer as EffectComposerImpl,
   EffectPass,
   NormalPass,
@@ -34,9 +35,23 @@ class EffectC extends Effect {
   }
 }
 
+class ConvolutionEffect extends Effect {
+  constructor() {
+    super('ConvolutionEffect', EFFECT_SHADER, { attributes: EffectAttribute.CONVOLUTION })
+  }
+}
+
+class ConvolutionEffectTwo extends Effect {
+  constructor() {
+    super('ConvolutionEffectTwo', EFFECT_SHADER, { attributes: EffectAttribute.CONVOLUTION })
+  }
+}
+
 const WrappedEffectA = wrapEffect(EffectA)
 const WrappedEffectB = wrapEffect(EffectB)
 const WrappedEffectC = wrapEffect(EffectC)
+const WrappedConvolutionEffect = wrapEffect(ConvolutionEffect)
+const WrappedConvolutionEffectTwo = wrapEffect(ConvolutionEffectTwo)
 
 afterEach(async () => {
   await React.act(async () => {
@@ -299,6 +314,285 @@ describe('EffectComposer', () => {
     })
   })
 
+  describe('autoRenderToScreen', () => {
+    it('defaults to true, with the last pass rendering to screen', async () => {
+      const ref = React.createRef<EffectComposerImpl>()
+
+      await React.act(async () =>
+        root.render(
+          <EffectComposer ref={ref}>
+            <WrappedEffectA />
+          </EffectComposer>
+        )
+      )
+
+      const composer = await waitForComposer(ref)
+      expect(composer.autoRenderToScreen).toBe(true)
+      expect(composer.passes.at(-1)?.renderToScreen).toBe(true)
+    })
+
+    it('applies false at mount, with no pass rendering to screen', async () => {
+      const ref = React.createRef<EffectComposerImpl>()
+
+      await React.act(async () =>
+        root.render(
+          <EffectComposer ref={ref} autoRenderToScreen={false}>
+            <WrappedEffectA />
+          </EffectComposer>
+        )
+      )
+
+      const composer = await waitForComposer(ref)
+      expect(composer.autoRenderToScreen).toBe(false)
+      expect(composer.passes.at(-1)?.renderToScreen).toBe(false)
+    })
+
+    // Not a constructor option in postprocessing itself, but the only place
+    // it's actually read is inside addPass() - deciding whether *that* call
+    // also assigns renderToScreen to the pass going in. Setting it after
+    // passes already exist doesn't revisit them, so treating this as a
+    // live/reactive prop (mutate the flag, leave existing passes alone)
+    // would leave a composer that was built with autoRenderToScreen: false
+    // permanently unable to render to screen again, even after the prop
+    // flips back to true - every existing pass already has renderToScreen:
+    // false baked in from when it was added, and nothing revisits it.
+    // Recreating the composer (same treatment as depthBuffer/multisampling/
+    // etc. above) sidesteps that entirely: every pass is freshly added
+    // through addPass() with the current flag already in effect.
+    it('recreates the composer when autoRenderToScreen changes, with the new last pass matching it', async () => {
+      const ref = React.createRef<EffectComposerImpl>()
+
+      await React.act(async () =>
+        root.render(
+          <EffectComposer ref={ref} autoRenderToScreen={false}>
+            <WrappedEffectA />
+          </EffectComposer>
+        )
+      )
+
+      const first = await waitForComposer(ref)
+      expect(first.passes.at(-1)?.renderToScreen).toBe(false)
+
+      await React.act(async () =>
+        root.render(
+          <EffectComposer ref={ref} autoRenderToScreen={true}>
+            <WrappedEffectA />
+          </EffectComposer>
+        )
+      )
+
+      const second = await waitForNewComposer(ref, first)
+      expect(second.autoRenderToScreen).toBe(true)
+      expect(second.passes.at(-1)?.renderToScreen).toBe(true)
+    })
+  })
+
+  describe('renderPass', () => {
+    it('adds a plain RenderPass as the first pass by default', async () => {
+      const ref = React.createRef<EffectComposerImpl>()
+
+      await React.act(async () =>
+        root.render(
+          <EffectComposer ref={ref}>
+            <WrappedEffectA />
+          </EffectComposer>
+        )
+      )
+
+      const composer = await waitForComposer(ref)
+      expect(composer.passes[0]).toBeInstanceOf(RenderPass)
+    })
+
+    it('uses a custom factory instead of the default RenderPass, called with the resolved scene/camera', async () => {
+      class CustomRenderPass extends RenderPass {}
+      const scene = new THREE.Scene()
+      const camera = new THREE.PerspectiveCamera()
+      const factory = vi.fn((s: THREE.Scene, c: THREE.Camera) => new CustomRenderPass(s, c))
+      const ref = React.createRef<EffectComposerImpl>()
+
+      await React.act(async () =>
+        root.render(
+          <EffectComposer ref={ref} scene={scene} camera={camera} renderPass={factory}>
+            <WrappedEffectA />
+          </EffectComposer>
+        )
+      )
+
+      const composer = await waitForComposer(ref)
+      expect(composer.passes[0]).toBeInstanceOf(CustomRenderPass)
+      expect(factory).toHaveBeenCalledWith(scene, camera)
+    })
+
+    // Not a postprocessing constructor option (it's this library's own prop),
+    // but the pass it produces is only ever added once, at construction -
+    // same treatment as depthBuffer/multisampling/autoRenderToScreen above.
+    it('recreates the composer when renderPass changes', async () => {
+      class CustomRenderPass extends RenderPass {}
+      const ref = React.createRef<EffectComposerImpl>()
+
+      await React.act(async () =>
+        root.render(
+          <EffectComposer ref={ref}>
+            <WrappedEffectA />
+          </EffectComposer>
+        )
+      )
+
+      const first = await waitForComposer(ref)
+      expect(first.passes[0]).toBeInstanceOf(RenderPass)
+      expect(first.passes[0]).not.toBeInstanceOf(CustomRenderPass)
+
+      await React.act(async () =>
+        root.render(
+          <EffectComposer ref={ref} renderPass={(s, c) => new CustomRenderPass(s, c)}>
+            <WrappedEffectA />
+          </EffectComposer>
+        )
+      )
+
+      const second = await waitForNewComposer(ref, first)
+      expect(second.passes[0]).toBeInstanceOf(CustomRenderPass)
+    })
+  })
+
+  describe('mergeMode', () => {
+    it("'auto' (default) merges a convolution effect with its non-convolution neighbors into one EffectPass", async () => {
+      const ref = React.createRef<EffectComposerImpl>()
+
+      await React.act(async () =>
+        root.render(
+          <EffectComposer ref={ref}>
+            <WrappedEffectA />
+            <WrappedConvolutionEffect />
+            <WrappedEffectB />
+            <WrappedEffectC />
+          </EffectComposer>
+        )
+      )
+
+      const composer = await waitForComposer(ref)
+      const effectPasses = composer.passes.filter((pass) => pass instanceof EffectPass)
+      expect(effectPasses).toHaveLength(1)
+      // @ts-expect-error - `effects` isn't part of the public Pass typing
+      expect(effectPasses[0].effects).toHaveLength(4)
+    })
+
+    it("'auto' still splits into separate passes rather than merging two convolution effects together", async () => {
+      const ref = React.createRef<EffectComposerImpl>()
+
+      await React.act(async () =>
+        root.render(
+          <EffectComposer ref={ref}>
+            <WrappedEffectA />
+            <WrappedConvolutionEffect />
+            <WrappedConvolutionEffectTwo />
+            <WrappedEffectB />
+          </EffectComposer>
+        )
+      )
+
+      const composer = await waitForComposer(ref)
+      const effectPasses = composer.passes.filter((pass) => pass instanceof EffectPass)
+      // [A, ConvolutionEffect] | [ConvolutionEffectTwo, B] - never both convolutions in one pass
+      expect(effectPasses).toHaveLength(2)
+      // @ts-expect-error - `effects` isn't part of the public Pass typing
+      const firstEffects = effectPasses[0].effects as Effect[]
+      // @ts-expect-error - `effects` isn't part of the public Pass typing
+      const secondEffects = effectPasses[1].effects as Effect[]
+      expect(firstEffects.filter((e) => e instanceof ConvolutionEffect || e instanceof ConvolutionEffectTwo)).toHaveLength(1)
+      expect(secondEffects.filter((e) => e instanceof ConvolutionEffect || e instanceof ConvolutionEffectTwo)).toHaveLength(1)
+    })
+
+    it("'all' merges even a single convolution effect with neighbors, same as 'auto'", async () => {
+      const ref = React.createRef<EffectComposerImpl>()
+
+      await React.act(async () =>
+        root.render(
+          <EffectComposer ref={ref} mergeMode="all">
+            <WrappedEffectA />
+            <WrappedConvolutionEffect />
+            <WrappedEffectB />
+          </EffectComposer>
+        )
+      )
+
+      const composer = await waitForComposer(ref)
+      const effectPasses = composer.passes.filter((pass) => pass instanceof EffectPass)
+      expect(effectPasses).toHaveLength(1)
+      // @ts-expect-error - `effects` isn't part of the public Pass typing
+      expect(effectPasses[0].effects).toHaveLength(3)
+    })
+
+    // postprocessing itself throws when two convolution effects share a
+    // pass - 'all' doesn't guard against that (same no-guardrail contract as
+    // EffectGroup), unlike 'auto' which keeps them apart specifically to
+    // avoid this.
+    it("'all' throws at render time if that removes 'auto'-only protection against merging two convolution effects", async () => {
+      const ref = React.createRef<EffectComposerImpl>()
+
+      await expect(
+        React.act(async () =>
+          root.render(
+            <EffectComposer ref={ref} mergeMode="all">
+              <WrappedEffectA />
+              <WrappedConvolutionEffect />
+              <WrappedConvolutionEffectTwo />
+              <WrappedEffectB />
+            </EffectComposer>
+          )
+        )
+      ).rejects.toThrow('Convolution effects cannot be merged')
+    })
+
+    it("'none' gives every effect its own EffectPass, even non-convolution ones", async () => {
+      const ref = React.createRef<EffectComposerImpl>()
+
+      await React.act(async () =>
+        root.render(
+          <EffectComposer ref={ref} mergeMode="none">
+            <WrappedEffectA />
+            <WrappedEffectB />
+            <WrappedEffectC />
+          </EffectComposer>
+        )
+      )
+
+      const composer = await waitForComposer(ref)
+      expect(composer.passes.filter((pass) => pass instanceof EffectPass)).toHaveLength(3)
+    })
+
+    it('rebuilds passes (without recreating the composer) when mergeMode changes', async () => {
+      const ref = React.createRef<EffectComposerImpl>()
+
+      await React.act(async () =>
+        root.render(
+          <EffectComposer ref={ref} mergeMode="none">
+            <WrappedEffectA />
+            <WrappedConvolutionEffect />
+            <WrappedEffectB />
+          </EffectComposer>
+        )
+      )
+
+      const composer = await waitForComposer(ref)
+      expect(composer.passes.filter((pass) => pass instanceof EffectPass)).toHaveLength(3)
+
+      await React.act(async () =>
+        root.render(
+          <EffectComposer ref={ref} mergeMode="auto">
+            <WrappedEffectA />
+            <WrappedConvolutionEffect />
+            <WrappedEffectB />
+          </EffectComposer>
+        )
+      )
+      await flush()
+
+      expect(await waitForComposer(ref)).toBe(composer)
+      expect(composer.passes.filter((pass) => pass instanceof EffectPass)).toHaveLength(1)
+    })
+  })
+
   describe('cleanup and disposal', () => {
     it('unregisters effects and clears the ref on full unmount', async () => {
       const ref = React.createRef<EffectComposerImpl>()
@@ -380,6 +674,128 @@ describe('EffectComposer', () => {
       disposeSpy.mockRestore()
     })
 
+    it('disposes a discarded EffectPass wrapper\'s own material on rebuild, without disposing the effects it wrapped', async () => {
+      const ref = React.createRef<EffectComposerImpl>()
+
+      await React.act(async () => root.render(<EffectComposer ref={ref}><WrappedEffectA /></EffectComposer>))
+      const composer = await waitForComposer(ref)
+      await waitForEffects(ref, 1)
+
+      const firstPass = composer.passes.find((p) => p instanceof EffectPass) as EffectPass
+      const materialDisposeSpy = vi.spyOn(firstPass.fullscreenMaterial, 'dispose')
+      const effectDisposeSpy = vi.spyOn(EffectA.prototype, 'dispose')
+
+      // Changing the node list forces a rebuild: buildPasses always
+      // constructs a brand new EffectPass, discarding the old wrapper.
+      await React.act(async () =>
+        root.render(
+          <EffectComposer ref={ref}>
+            <WrappedEffectA />
+            <WrappedEffectB />
+          </EffectComposer>
+        )
+      )
+      await flush()
+
+      const secondPass = composer.passes.find((p) => p instanceof EffectPass) as EffectPass
+      expect(secondPass).not.toBe(firstPass)
+      expect(materialDisposeSpy).toHaveBeenCalledTimes(1)
+      expect(effectDisposeSpy).not.toHaveBeenCalled()
+
+      materialDisposeSpy.mockRestore()
+      effectDisposeSpy.mockRestore()
+    })
+
+    it('detaches a discarded EffectPass\'s change listener from the effect it wrapped, so it no longer reacts to it', async () => {
+      const ref = React.createRef<EffectComposerImpl>()
+      const effectRef = React.createRef<EffectA>()
+
+      await React.act(async () => root.render(<EffectComposer ref={ref}><WrappedEffectA ref={effectRef} /></EffectComposer>))
+      const composer = await waitForComposer(ref)
+      await waitForEffects(ref, 1)
+
+      const firstPass = composer.passes.find((p) => p instanceof EffectPass) as EffectPass
+      const recompileSpy = vi.spyOn(firstPass, 'recompile')
+
+      await React.act(async () =>
+        root.render(
+          <EffectComposer ref={ref}>
+            <WrappedEffectA ref={effectRef} />
+            <WrappedEffectB />
+          </EffectComposer>
+        )
+      )
+      await flush()
+
+      const secondPass = composer.passes.find((p) => p instanceof EffectPass) as EffectPass
+      expect(secondPass).not.toBe(firstPass)
+
+      // The same effect instance survived the rebuild - firing its own
+      // 'change' event should only reach whatever pass currently wraps it,
+      // not the discarded one still listening from before.
+      effectRef.current!.dispatchEvent({ type: 'change' })
+
+      expect(recompileSpy).not.toHaveBeenCalled()
+
+      recompileSpy.mockRestore()
+    })
+
+    it('leaves a user-provided EffectPass (rendered directly as a child) untouched across a rebuild', async () => {
+      const ref = React.createRef<EffectComposerImpl>()
+      const camera = new THREE.PerspectiveCamera()
+      const userEffect = new EffectC()
+      const userPass = new EffectPass(camera, userEffect)
+
+      await React.act(async () =>
+        root.render(
+          <EffectComposer ref={ref}>
+            <WrappedEffectA />
+            <primitive object={userPass} />
+          </EffectComposer>
+        )
+      )
+      const composer = await waitForComposer(ref)
+      await waitForEffects(ref, 1)
+      expect(composer.passes).toContain(userPass)
+
+      // Forces a rebuild (node list changes) - buildPasses only ever
+      // constructs a *new* EffectPass for Effect children; userPass is
+      // passed through unchanged via the plain-Pass branch.
+      await React.act(async () =>
+        root.render(
+          <EffectComposer ref={ref}>
+            <WrappedEffectA />
+            <WrappedEffectB />
+            <primitive object={userPass} />
+          </EffectComposer>
+        )
+      )
+      await flush()
+
+      expect(composer.passes).toContain(userPass)
+      // @ts-expect-error - `effects` isn't part of the public Pass typing
+      expect(userPass.effects).toEqual([userEffect])
+
+      await React.act(async () => root.render(null))
+    })
+
+    it('disposes the final EffectPass wrapper\'s material on full unmount too (composer.dispose has nothing left to dispose by then)', async () => {
+      const ref = React.createRef<EffectComposerImpl>()
+
+      await React.act(async () => root.render(<EffectComposer ref={ref}><WrappedEffectA /></EffectComposer>))
+      const composer = await waitForComposer(ref)
+      await waitForEffects(ref, 1)
+
+      const pass = composer.passes.find((p) => p instanceof EffectPass) as EffectPass
+      const materialDisposeSpy = vi.spyOn(pass.fullscreenMaterial, 'dispose')
+
+      await React.act(async () => root.render(null))
+
+      expect(materialDisposeSpy).toHaveBeenCalled()
+
+      materialDisposeSpy.mockRestore()
+    })
+
     it('disposes exactly as many composers as it constructs, across repeated prop changes', async () => {
       const ref = React.createRef<EffectComposerImpl>()
       const disposeSpy = vi.spyOn(EffectComposerImpl.prototype, 'dispose')
@@ -405,6 +821,42 @@ describe('EffectComposer', () => {
       disposeSpy.mockRestore()
     })
 
+    it('does not dispose a still-in-use effect when a composer-level prop (multisampling) recreates the composer', async () => {
+      const ref = React.createRef<EffectComposerImpl>()
+      const effectRef = React.createRef<EffectA>()
+
+      await React.act(async () =>
+        root.render(
+          <EffectComposer ref={ref} multisampling={0}>
+            <WrappedEffectA ref={effectRef} />
+          </EffectComposer>
+        )
+      )
+      const firstComposer = await waitForComposer(ref)
+      await waitForEffects(ref, 1)
+      const effect = effectRef.current
+      expect(effect).toBeTruthy()
+
+      const effectDisposeSpy = vi.spyOn(EffectA.prototype, 'dispose')
+
+      await React.act(async () =>
+        root.render(
+          <EffectComposer ref={ref} multisampling={4}>
+            <WrappedEffectA ref={effectRef} />
+          </EffectComposer>
+        )
+      )
+      const secondComposer = await waitForNewComposer(ref, firstComposer)
+      await flush()
+
+      expect(secondComposer).not.toBe(firstComposer)
+      expect(effectRef.current).toBe(effect)
+      expect(effectDisposeSpy).not.toHaveBeenCalled()
+      expect(secondComposer.passes.some((p) => p instanceof EffectPass)).toBe(true)
+
+      effectDisposeSpy.mockRestore()
+    })
+
     it('disposes a hand-constructed effect exactly once on unmount', async () => {
       const disposeSpy = vi.spyOn(ColorAverageEffect.prototype, 'dispose')
       const ref = React.createRef<EffectComposerImpl>()
@@ -425,7 +877,7 @@ describe('EffectComposer', () => {
       disposeSpy.mockRestore()
     })
 
-    it('disposes exactly as many ColorAverage instances as it constructs, across repeated prop changes', async () => {
+    it('keeps a single ColorAverage instance across repeated blendFunction changes and disposes it exactly once (blendFunction is live, not construction-only)', async () => {
       const disposeSpy = vi.spyOn(ColorAverageEffect.prototype, 'dispose')
       const ref = React.createRef<ColorAverageEffect>()
       const seenInstances = new Set<ColorAverageEffect>()
@@ -446,15 +898,16 @@ describe('EffectComposer', () => {
 
         await React.act(async () => root.render(null))
 
-        expect(seenInstances.size).toBe(cycles)
-        expect(disposeSpy).toHaveBeenCalledTimes(cycles)
+        expect(seenInstances.size).toBe(1)
+        expect(disposeSpy).toHaveBeenCalledTimes(1)
       } finally {
         disposeSpy.mockRestore()
       }
     })
 
-    it('never disposes the same ColorAverage instance twice, even in StrictMode', async () => {
+    it('disposes every ColorAverage instance seen, even across StrictMode\'s mount/cleanup/mount cycle', async () => {
       const disposedNodes: ColorAverageEffect[] = []
+      const seenInstances = new Set<ColorAverageEffect>()
       const disposeSpy = vi.spyOn(ColorAverageEffect.prototype, 'dispose').mockImplementation(function (
         this: ColorAverageEffect
       ) {
@@ -474,11 +927,17 @@ describe('EffectComposer', () => {
             )
           )
           await flush()
+          if (ref.current) seenInstances.add(ref.current)
         }
         await React.act(async () => root.render(null))
 
-        const uniqueDisposed = new Set(disposedNodes)
-        expect(uniqueDisposed.size).toBe(disposedNodes.length)
+        // dispose() is idempotent (just event-firing / shallow property
+        // disposal, no internal state), so StrictMode calling it more than
+        // once per instance is fine - this only checks nothing leaked.
+        const disposedSet = new Set(disposedNodes)
+        for (const instance of seenInstances) {
+          expect(disposedSet.has(instance)).toBe(true)
+        }
       } finally {
         disposeSpy.mockRestore()
       }
@@ -883,7 +1342,7 @@ describe('EffectComposer', () => {
   })
 
   describe('performance characteristics (documented, not enforced)', () => {
-    it('rebuilds the EffectPass once per registration when mounting many effects at once', async () => {
+    it('rebuilds the EffectPass at most twice when mounting many effects at once', async () => {
       const addPassSpy = vi.spyOn(EffectComposerImpl.prototype, 'addPass')
 
       const ref = React.createRef<EffectComposerImpl>()
@@ -903,9 +1362,43 @@ describe('EffectComposer', () => {
 
       const effectPassAddCalls = addPassSpy.mock.calls.filter(([pass]) => pass instanceof EffectPass).length
 
-      expect(effectPassAddCalls).toBe(1)
+      // The node-list change detector and the pass-building effect settle
+      // over two synchronous layout-effect passes on first mount (detect
+      // change -> bump a version -> rebuild once more) - a one-time cost,
+      // not a per-render one. See the "does not rebuild on unrelated
+      // re-renders" test below for the actual guarantee this trades for.
+      expect(effectPassAddCalls).toBeLessThanOrEqual(2)
+
+      addPassSpy.mockRestore()
+    })
+
+    it('does not rebuild the EffectPass (or re-run EffectPass.initialize) on unrelated re-renders', async () => {
+      const ref = React.createRef<EffectComposerImpl>()
+
+      const render = (tick: number) =>
+        root.render(
+          <EffectComposer ref={ref}>
+            <WrappedEffectA />
+            <group name={`tick-${tick}`} />
+          </EffectComposer>
+        )
+
+      await React.act(async () => render(0))
+      await waitForEffects(ref, 1)
+
+      const addPassSpy = vi.spyOn(EffectComposerImpl.prototype, 'addPass')
+      const initializeSpy = vi.spyOn(EffectPass.prototype, 'initialize')
+
+      for (let t = 1; t <= 5; t++) {
+        await React.act(async () => render(t))
+        await flush()
+      }
+
+      expect(addPassSpy).not.toHaveBeenCalled()
+      expect(initializeSpy).not.toHaveBeenCalled()
 
       addPassSpy.mockRestore()
+      initializeSpy.mockRestore()
     })
   })
 })