Release/3.1.0

.github/workflows/main.yml

@@ -9,17 +9,18 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
+      - uses: pnpm/action-setup@v6
       - uses: actions/setup-node@v3
         with:
-          cache: 'yarn'
+          cache: 'pnpm'
       - name: Install Dependencies
-        run: yarn install --frozen-lockfile
+        run: pnpm install --frozen-lockfile
 
       - name: Check build health
-        run: yarn build
+        run: pnpm build
 
       - name: Check for regressions
-        run: yarn eslint:ci
+        run: pnpm eslint:ci
 
       - name: Run tests
-        run: yarn test
+        run: pnpm test

.github/workflows/release.yml

@@ -42,12 +42,14 @@ jobs:
       - name: Check out repository
         uses: actions/checkout@v6
 
+      - uses: pnpm/action-setup@v6
+
       - name: Set up Node.js
         uses: actions/setup-node@v6
         with:
           node-version: 24
           registry-url: https://registry.npmjs.org
-          package-manager-cache: false
+          cache: 'pnpm'
 
       - name: Verify release version
         env:
@@ -60,16 +62,16 @@ jobs:
           fi
 
       - name: Install dependencies
-        run: yarn install --frozen-lockfile
+        run: pnpm install --frozen-lockfile
 
       - name: Lint
-        run: yarn eslint:ci
+        run: pnpm eslint:ci
 
       - name: Test
-        run: yarn test
+        run: pnpm test
 
       - name: Build
-        run: yarn build
+        run: pnpm build
 
       - name: Publish package
         env:

.gitignore

@@ -16,7 +16,6 @@ yarn-error.log
 .size-snapshot.json
 pnpm-debug.log
 .parcel-cache
-pnpm-lock.yaml
 storybook-static
 
 *.tgz

CONTRIBUTING.md

@@ -5,7 +5,7 @@ Thanks for wanting to make a contribution and wanting to improve this library fo
 ## How to Contribute
 
 1.  Fork and clone the repo
-2.  Run `yarn install` to install dependencies
+2.  Run `pnpm install` to install dependencies
 3.  Create a branch for your PR with `git checkout -b pr-type/issue-number-your-branch-name`
 4.  Let's get cooking! 👨🏻‍🍳🥓
 

docs/custom-effects.mdx

@@ -0,0 +1,85 @@
+---
+title: Custom effects
+description: Wrapping your own effects, or postprocessing's, as components
+nav: 0
+---
+
+Most effects from `postprocessing` are already wrapped by this library, but if you need one that isn't, or want to write your own, there are three ways to do it depending on what the effect's constructor needs.
+
+## Zero-arg effects (recommended)
+
+If the effect's constructor works with zero arguments (`new SomeEffect()`), `createEffectComponent` gives you a component with live-updating props for free - no `useMemo`/`useDispose` needed, and no reconstruction on every prop change. This is exactly how this library's own simple effects (`BrightnessContrast`, `ChromaticAberration`, `Noise`, ...) are built:
+
+```jsx
+import { SomeEffect } from 'postprocessing'
+import { createEffectComponent } from '@react-three/postprocessing'
+
+export const SomeEffectComponent = createEffectComponent(SomeEffect)
+```
+
+Every constructor option becomes a live prop that updates the existing instance in place, and `blendFunction`/`opacity` are supported automatically. `ref` resolves to the effect instance. Disposal is handled for you - unlike `<primitive>`, r3f disposes elements it constructed itself.
+
+### Custom defaults
+
+If you want different defaults than the class's own, or the constructor takes a positional argument instead of an options object, wrap it in a thin component - this is how this library's own `Pixelation` is built (its default `granularity` is `5`, not the class's own `30`):
+
+```jsx
+import { PixelationEffect } from 'postprocessing'
+import { createEffectComponent } from '@react-three/postprocessing'
+
+const PixelationImpl = createEffectComponent(PixelationEffect)
+
+export function Pixelation({ granularity = 5, ...props }) {
+  return <PixelationImpl granularity={granularity} {...props} />
+}
+```
+
+## Effects that need real constructor arguments
+
+Effects whose constructor needs more than zero arguments - e.g. `OutlineEffect(scene, camera, options)` - can't use `createEffectComponent`: it relies on r3f's `extend()`, which always constructs via `new Effect()`. Build these by hand instead: `useMemo`/`useDispose` for construction, `useLiveDefaults` for props that should update the existing instance rather than reconstruct it.
+
+```jsx
+import { useMemo } from 'react'
+import { SomeEffect } from 'postprocessing'
+import { useDispose, useLiveDefaults } from '@react-three/postprocessing'
+
+const LIVE_KEYS = ['someProp', 'anotherProp']
+
+export function SomeEffectComponent({ requiredArg, someProp, anotherProp, ref }) {
+  const effect = useMemo(() => new SomeEffect(requiredArg), [requiredArg])
+
+  useLiveDefaults(effect, { someProp, anotherProp }, LIVE_KEYS)
+  useDispose(effect)
+
+  return <primitive ref={ref} object={effect} />
+}
+```
+
+`LIVE_KEYS` should only list options that have a real setter on the class - check the effect's own source. `useLiveDefaults` resets a prop to the effect's constructor-time default when it's removed, and only calls the setter when the resolved value actually changed (some setters have side effects beyond storing the value). See `Outline.tsx` in this repo for a real example, including piercing into a nested property like `blendMode.blendFunction`.
+
+## Writing a brand new effect
+
+For effects that don't exist in `postprocessing` at all, extend `Effect` and wrap the result the same way as any other zero-arg effect:
+
+```jsx
+import { Effect } from 'postprocessing'
+import { Uniform } from 'three'
+import { createEffectComponent } from '@react-three/postprocessing'
+
+const fragmentShader = `some_shader_code`
+
+class MyCustomEffect extends Effect {
+  constructor({ param = 0.1 } = {}) {
+    super('MyCustomEffect', fragmentShader, {
+      uniforms: new Map([['param', new Uniform(param)]]),
+    })
+  }
+
+  update(renderer, inputBuffer, deltaTime) {
+    // read/write per-frame state on `this` (e.g. this.uniforms.get('param').value = ...),
+    // never on a module-level variable - that would be shared across every instance
+  }
+}
+
+export const MyCustomEffectComponent = createEffectComponent(MyCustomEffect)
+```

docs/effect-composer.mdx

@@ -12,13 +12,19 @@ The `EffectComposer` must wrap all your effects. It will manage them for you.
   enableNormalPass?: boolean
   stencilBuffer?: boolean
   autoClear?: boolean
+  /** Whether the last pass automatically renders to the screen. Set to `false` when rendering to a target of your own (e.g. via a trailing CopyPass) instead. */
+  autoRenderToScreen?: boolean
   multisampling?: number
   frameBufferType?: TextureDataType
   /** For effects that support DepthDownsamplingPass */
   resolutionScale?: number
   renderPriority?: number
   camera?: THREE.Camera
   scene?: THREE.Scene
+  /** Constructs the initial pass that renders the scene - override to substitute your own RenderPass-like implementation. Defaults to `(scene, camera) => new RenderPass(scene, camera)`. */
+  renderPass?: (scene: THREE.Scene, camera: THREE.Camera) => Pass
+  /** Controls how effects are merged into EffectPass instances. `'auto'` (default) merges consecutive effects into one pass, keeping at most one convolution effect (e.g. DepthOfField) per pass - matching what postprocessing actually supports. `'all'` merges without that limit - only enable it if you've verified your specific combination works, since multiple convolution effects sharing a pass throws at render time. `'none'` disables merging entirely, giving every effect its own pass. */
+  mergeMode?: 'auto' | 'all' | 'none'
 >
 {/* your effects go here */}
 </EffectComposer>

docs/effect-group.mdx

@@ -0,0 +1,48 @@
+---
+title: EffectGroup
+description: Explicit effect grouping with a pass-level enable toggle
+nav: 0
+---
+
+`EffectComposer` groups effects into passes automatically: consecutive effects
+merge into one `EffectPass`, based only on what happens to sit next to them in
+JSX. `EffectGroup` lets you group specific effects into one pass explicitly,
+regardless of what's around them, and gives that whole pass a cheap
+`enabled` toggle - the same thing `Pass.enabled` gives you in vanilla
+`postprocessing`, without reconstructing anything.
+
+```jsx
+<EffectGroup
+  enabled?: boolean // true
+>
+  {/* effects to group go here */}
+</EffectGroup>
+```
+
+```jsx
+<EffectComposer>
+  <Bloom />
+  <EffectGroup enabled={showVignetteAndNoise}>
+    <Vignette />
+    <Noise />
+  </EffectGroup>
+</EffectComposer>
+```
+
+`Bloom` still gets its own pass as usual. `Vignette` and `Noise` are merged
+into one pass together, positioned exactly where `EffectGroup` sits in the
+JSX, and toggling `enabled` turns that whole pass on or off without rebuilding
+it - so it's cheap to flip every frame if you need to.
+
+`ref` resolves to the underlying `EffectPass`:
+
+```jsx
+<EffectGroup ref={groupRef}>...</EffectGroup>
+```
+
+## Limitations
+
+- `EffectGroup` only groups `postprocessing` `Effect`s - things that merge
+  into one shader pass. A handful of effects in this library (like `N8AO`)
+  are full standalone passes, not effects, and can't be grouped this way -
+  they take their own `enabled` prop instead.

docs/effects/ascii.mdx

@@ -28,5 +28,5 @@ return (
 | characters | String  | ` .:,'-^=*+?!\|0#X%WM@` | The characters to sample from, ordered from "empty" to "dense".    |
 | fontSize   | Number  | 54                       | The font size used to draw the character atlas.                    |
 | cellSize   | Number  | 16                       | The size of each character cell, in pixels.                        |
-| color      | String  | '#ffffff'                | The color of the characters.                                       |
+| color      | ColorRepresentation | '#ffffff'   | The color of the characters.                                       |
 | invert     | Boolean | false                    | Inverts which characters map to bright vs dark pixels.              |

docs/effects/autofocus.mdx

@@ -5,7 +5,7 @@ nav: 1
 
 An auto-focus effect, that extends `<DepthOfField>`.
 
-Based on [ektogamat/AutoFocusDOF](https://github.com/ektogamat/AutoFocusDOF).
+Based on [ektogamat/AutoFocusDOF](https://github.com/ektogamat/AutoFocusDOF). Built on `<DepthPicking>` and `useDepthPicking` internally - use those directly if you want a picked position for something other than `<DepthOfField>`'s own focus target.
 
 ```tsx
 export type AutofocusProps = typeof DepthOfField & {

docs/effects/god-rays.mdx

@@ -5,6 +5,8 @@ nav: 1
 
 The GodRays effect requires a mesh that will be used as an origin point for the rays. Refer to this [example](https://pmndrs.github.io/examples/take-control) for more details.
 
+For correct occlusion by other objects, also set `<EffectComposer autoClear={false}>`.
+
 ```jsx
 import { GodRays } from '@react-three/postprocessing'
 

docs/effects/outline.mdx

@@ -5,6 +5,8 @@ nav: 1
 
 An outline effect.
 
+Requires `<EffectComposer autoClear={false}>` - without it, outlines don't render at all.
+
 ```jsx
 import { Outline } from '@react-three/postprocessing'
 import { BlendFunction, Resolution, KernelSize } from 'postprocessing'
@@ -37,21 +39,23 @@ return (
 
 ## Props
 
-| Name             | Type          | Default               | Description                                                                |
-| ---------------- | ------------- | --------------------- | -------------------------------------------------------------------------- |
-| selection        | Objects       |                       | Selection of objects that will be outlined                                 |
-| selectionLayer   | Number        | 10                    | The selection layer                                                        |
-| blendFunction    | BlendFunction | BlendFunction.SCREEN  | The blend function of this effect.                                         |
-| patternTexture   | Texture       | null                  | A pattern texture.                                                         |
-| patternScale     | Number        | 1.0                   | The pattern texture scale.                                                 |
-| edgeStrength     | Number        | 1.0                   | The edge strength.                                                         |
-| pulseSpeed       | Number        | 0                     | The pulse speed. A value of zero disables the pulse effect.                |
-| visibleEdgeColor | Number        | 0xffffff              | The color of visible edges.                                                |
-| hiddenEdgeColor  | Number        | 0x22090a              | The color of hidden edges.                                                 |
-| multisampling    | Number        | 0                     | The number of samples used for multisample antialiasing. Requires WebGL 2. |
-| resolutionScale  | Number        | 0.5                   | The render resolution scale.                                               |
-| resolutionX      | Number        | Resolution.AUTO_SIZE  | The render width.                                                          |
-| resolutionY      | Number        | Resolution.AUTO_SIZE  | The render height.                                                         |
-| kernelSize       | KernelSize    | KernelSize.VERY_SMALL | The blur kernel size.                                                      |
-| blur             | Boolean       | false                 | Whether the outline should be blurred.                                     |
-| xRay             | Boolean       | true                  | Whether occluded parts of selected objects should be visible.              |
+| Name             | Type                 | Default                | Description                                                                          |
+| ---------------- | -------------------- | ----------------------- | ------------------------------------------------------------------------------------- |
+| selection        | Objects              |                        | Selection of objects that will be outlined                                            |
+| selectionLayer   | Number               | 10                     | The selection layer                                                                   |
+| blendFunction    | BlendFunction        | BlendFunction.SCREEN   | The blend function of this effect.                                                    |
+| patternTexture   | THREE.Texture        | null                   | A pattern texture.                                                                    |
+| patternScale     | Number               | 1.0                    | The pattern texture scale.                                                            |
+| edgeStrength     | Number               | 1.0                    | The edge strength.                                                                    |
+| pulseSpeed       | Number               | 0                      | The pulse speed. A value of zero disables the pulse effect.                           |
+| visibleEdgeColor | ColorRepresentation  | 0xffffff               | The color of visible edges.                                                           |
+| hiddenEdgeColor  | ColorRepresentation  | 0x22090a               | The color of hidden edges.                                                            |
+| multisampling    | Number               | 0                      | The number of samples used for multisample antialiasing. Requires WebGL 2.            |
+| resolutionScale  | Number               | 0.5                    | The render resolution scale. Applied at construction only.                            |
+| resolutionX      | Number               | Resolution.AUTO_SIZE   | The render width. Applied at construction only.                                       |
+| resolutionY      | Number               | Resolution.AUTO_SIZE   | The render height. Applied at construction only.                                      |
+| width            | Number               | Resizer.AUTO_SIZE      | The render width. Unlike `resolutionX`, updates live without reconstructing the effect. |
+| height           | Number               | Resizer.AUTO_SIZE      | The render height. Unlike `resolutionY`, updates live without reconstructing the effect. |
+| kernelSize       | KernelSize           | KernelSize.VERY_SMALL  | The blur kernel size.                                                                 |
+| blur             | Boolean              | false                  | Whether the outline should be blurred.                                                |
+| xRay             | Boolean              | true                   | Whether occluded parts of selected objects should be visible.                         |

docs/effects/shockwave.mdx

@@ -29,9 +29,9 @@ return (
 
 ## Props
 
-| Name      | Type    | Default | Description                        |
-| --------- | ------- | -------- | ------------------------------------- |
-| position  | Vector3 | (0,0,0)  | The world position of the shockwave. |
+| Name      | Type                          | Default | Description                        |
+| --------- | ----------------------------- | -------- | ------------------------------------- |
+| position  | Vector3 \| [x, y, z] \| Number | (0,0,0)  | The world position of the shockwave. |
 | speed     | Number  | 2.0      | The animation speed.                 |
 | maxRadius | Number  | 1.0      | The extent of the shockwave.         |
 | waveSize  | Number  | 0.2      | The wave size.                       |