@react-three/postprocessing 3.0.4 → 3.1.0

package/src/effects/Noise.tsx

@@ -1,4 +1,16 @@
-import { NoiseEffect, BlendFunction } from 'postprocessing'
-import { wrapEffect } from '../util'
-
-export const Noise = /* @__PURE__ */ wrapEffect(NoiseEffect, { blendFunction: BlendFunction.COLOR_DODGE })
+import { BlendFunction, NoiseEffect } from 'postprocessing'
+import type { Ref } from 'react'
+import { createEffectComponent, type EffectOptions } from '../createEffectComponent'
+
+const NoiseImpl = /* @__PURE__ */ createEffectComponent<typeof NoiseEffect, EffectOptions<typeof NoiseEffect>>(
+  NoiseEffect
+)
+
+export type NoiseProps = EffectOptions<typeof NoiseEffect> & {
+  opacity?: number
+  ref?: Ref<NoiseEffect>
+}
+
+export function Noise({ blendFunction = BlendFunction.COLOR_DODGE, ...props }: NoiseProps) {
+  return <NoiseImpl blendFunction={blendFunction} {...props} />
+}

package/src/effects/Outline.tsx

@@ -1,117 +1,84 @@
-import { OutlineEffect } from 'postprocessing'
-import { Ref, RefObject, forwardRef, useMemo, useEffect, useContext, useRef } from 'react'
-import { Object3D } from 'three'
-import { useThree } from '@react-three/fiber'
-import { EffectComposerContext } from '../EffectComposer'
-import { selectionContext } from '../Selection'
-import { resolveRef } from '../util'
-
-type ObjectRef = RefObject<Object3D>
-
-export type OutlineProps = ConstructorParameters<typeof OutlineEffect>[2] &
-  Partial<{
-    selection: Object3D | Object3D[] | ObjectRef | ObjectRef[]
-    selectionLayer: number
-  }>
-
-export const Outline = /* @__PURE__ */ forwardRef(function Outline(
-  {
-    selection = [],
-    selectionLayer = 10,
-    blendFunction,
-    patternTexture,
-    edgeStrength,
-    pulseSpeed,
-    visibleEdgeColor,
-    hiddenEdgeColor,
-    width,
-    height,
-    kernelSize,
-    blur,
-    xRay,
-    ...props
-  }: OutlineProps,
-  forwardRef: Ref<OutlineEffect>
-) {
-  const invalidate = useThree((state) => state.invalidate)
-  const { scene, camera } = useContext(EffectComposerContext)
-
-  const effect = useMemo(
-    () =>
-      new OutlineEffect(scene, camera, {
-        blendFunction,
-        patternTexture,
-        edgeStrength,
-        pulseSpeed,
-        visibleEdgeColor,
-        hiddenEdgeColor,
-        width,
-        height,
-        kernelSize,
-        blur,
-        xRay,
-        ...props,
-      }),
-    // NOTE: `props` is an unstable reference, so we can't memoize it
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [
-      blendFunction,
-      blur,
-      camera,
-      edgeStrength,
-      height,
-      hiddenEdgeColor,
-      kernelSize,
-      patternTexture,
-      pulseSpeed,
-      scene,
-      visibleEdgeColor,
-      width,
-      xRay,
-    ]
-  )
-
-  const api = useContext(selectionContext)
-
-  useEffect(() => {
-    // Do not allow array selection if declarative selection is active
-    // TODO: array selection should probably be deprecated altogether
-    if (!api && selection) {
-      effect.selection.set(
-        Array.isArray(selection) ? (selection as Object3D[]).map(resolveRef) : [resolveRef(selection) as Object3D]
-      )
-      invalidate()
-      return () => {
-        effect.selection.clear()
-        invalidate()
-      }
-    }
-  }, [effect, selection, api, invalidate])
-
-  useEffect(() => {
-    effect.selectionLayer = selectionLayer
-    invalidate()
-  }, [effect, invalidate, selectionLayer])
-
-  const ref = useRef<OutlineEffect>(undefined)
-  useEffect(() => {
-    if (api && api.enabled) {
-      if (api.selected?.length) {
-        effect.selection.set(api.selected)
-        invalidate()
-        return () => {
-          effect.selection.clear()
-          invalidate()
-        }
-      }
-    }
-  }, [api, effect.selection, invalidate])
-
-  useEffect(() => {
-    return () => {
-      effect.dispose()
-    }
-  }, [effect])
-
-  return <primitive ref={forwardRef} object={effect} />
-})
+import { OutlineEffect } from 'postprocessing'
+import { Ref, RefObject, use, useEffect, useMemo } from 'react'
+import { Color, Object3D, type ColorRepresentation } from 'three'
+import { EffectComposerContext } from '../EffectComposer'
+import { applyPierced, EMPTY_ARRAY, readPierced, useDispose, useLiveDefaults, useSelectionSync } from '../util'
+
+type ObjectRef = RefObject<Object3D | null>
+
+type OutlineEffectOptions = NonNullable<ConstructorParameters<typeof OutlineEffect>[2]>
+
+export type OutlineProps = Omit<OutlineEffectOptions, 'visibleEdgeColor' | 'hiddenEdgeColor'> &
+  Partial<{
+    selection: Object3D | Object3D[] | ObjectRef | ObjectRef[]
+    selectionLayer: number
+    visibleEdgeColor: ColorRepresentation
+    hiddenEdgeColor: ColorRepresentation
+    ref?: Ref<OutlineEffect>
+  }>
+
+// Every OutlineEffect option that has a real setter (verified against
+// postprocessing's source) - resolutionScale/resolutionX/resolutionY are
+// the only ones without one, since they only feed the internal blur pass
+// at construction time. scene/camera are required constructor args, so
+// OutlineEffect can't use createEffectComponent (needs `new Effect()` to
+// work with zero args) - built by hand instead.
+const LIVE_KEYS = [
+  'patternTexture',
+  'patternScale',
+  'edgeStrength',
+  'pulseSpeed',
+  'visibleEdgeColor',
+  'hiddenEdgeColor',
+  'multisampling',
+  'width',
+  'height',
+  'kernelSize',
+  'blur',
+  'xRay',
+  'dithering',
+  'blendMode-blendFunction',
+]
+
+// The setter stores whatever it's given as-is, unlike the constructor -
+// wrap in a Color here too, or a raw hex/string breaks the shader uniform.
+function set(effect: OutlineEffect, key: string, value: unknown): void {
+  if (key === 'visibleEdgeColor' || key === 'hiddenEdgeColor') applyPierced(effect, key, new Color(value as never))
+  else applyPierced(effect, key, value)
+}
+
+export function Outline({
+  selection = EMPTY_ARRAY,
+  selectionLayer = 10,
+  blendFunction,
+  resolutionScale,
+  resolutionX,
+  resolutionY,
+  ref,
+  ...liveProps
+}: OutlineProps) {
+  const { scene, camera, autoClear } = use(EffectComposerContext)
+
+  const effect = useMemo(
+    () => new OutlineEffect(scene, camera, { resolutionScale, resolutionX, resolutionY }),
+    [scene, camera, resolutionScale, resolutionX, resolutionY]
+  )
+
+  useEffect(() => {
+    if (autoClear !== false) {
+      console.warn('Outline requires <EffectComposer autoClear={false}> to render correctly.')
+    }
+  }, [autoClear])
+
+  useLiveDefaults(
+    effect,
+    { ...liveProps, 'blendMode-blendFunction': blendFunction } as Record<string, unknown>,
+    LIVE_KEYS,
+    readPierced,
+    set
+  )
+  useSelectionSync(effect, selection, selectionLayer)
+  useDispose(effect)
+
+  return <primitive ref={ref} object={effect} />
+}

package/src/effects/Pixelation.tsx

@@ -1,15 +1,20 @@
-import { forwardRef, useMemo, Ref } from 'react'
-import { PixelationEffect } from 'postprocessing'
-
-export type PixelationProps = {
-  granularity?: number
-}
-
-export const Pixelation = /* @__PURE__ */ forwardRef<PixelationEffect, PixelationProps>(function Pixelation(
-  { granularity = 5 }: PixelationProps,
-  ref: Ref<PixelationEffect>
-) {
-  /** Because GlitchEffect granularity is not an object but a number, we have to define a custom prop "granularity" */
-  const effect = useMemo(() => new PixelationEffect(granularity), [granularity])
-  return <primitive ref={ref} object={effect} dispose={null} />
-})
+import { PixelationEffect } from 'postprocessing'
+import type { Ref } from 'react'
+import { createEffectComponent } from '../createEffectComponent'
+
+// PixelationEffect's sole constructor arg is a bare number, not an options
+// object - granularity is a real live setter though, so it's just a normal
+// prop; only the curated default (5, vs the class's own default of 30)
+// needs a thin wrapper.
+const PixelationImpl = /* @__PURE__ */ createEffectComponent<typeof PixelationEffect, { granularity?: number }>(
+  PixelationEffect
+)
+
+export type PixelationProps = {
+  granularity?: number
+  ref?: Ref<PixelationEffect>
+}
+
+export function Pixelation({ granularity = 5, ref }: PixelationProps) {
+  return <PixelationImpl granularity={granularity} ref={ref} />
+}

package/src/effects/Ramp.tsx

@@ -1,150 +1,239 @@
-import { Uniform } from 'three'
-import { Effect } from 'postprocessing'
-import { wrapEffect } from '../util'
-
-const RampShader = {
-  fragmentShader: /* glsl */ `
-    uniform int rampType;
-
-    uniform vec2 rampStart;
-    uniform vec2 rampEnd;
-
-    uniform vec4 startColor;
-    uniform vec4 endColor;
-
-    uniform float rampBias;
-    uniform float rampGain;
-
-    uniform bool rampMask;
-    uniform bool rampInvert;
-
-    float getBias(float time, float bias) {
-      return time / (((1.0 / bias) - 2.0) * (1.0 - time) + 1.0);
-    }
-
-    float getGain(float time, float gain) {
-      if (time < 0.5)
-        return getBias(time * 2.0, gain) / 2.0;
-      else
-        return getBias(time * 2.0 - 1.0, 1.0 - gain) / 2.0 + 0.5;
-    }
-
-    void mainImage(const in vec4 inputColor, const in vec2 uv, out vec4 outputColor) {
-      vec2 centerPixel = uv * resolution;
-      vec2 startPixel = rampStart * resolution;
-      vec2 endPixel = rampEnd * resolution;
-
-      float rampAlpha;
-
-      if (rampType == 1) {
-        vec2 fuv = centerPixel / resolution.y;
-        vec2 suv = startPixel / resolution.y;
-        vec2 euv = endPixel / resolution.y;
-
-        float radius = length(suv - euv);
-        float falloff = length(fuv - suv);
-        rampAlpha = smoothstep(0.0, radius, falloff);
-      } else {
-        float radius = length(startPixel - endPixel);
-        vec2 direction = normalize(vec2(endPixel.x - startPixel.x, -(startPixel.y - endPixel.y)));
-
-        float fade = dot(centerPixel - startPixel, direction);
-        if (rampType == 2) fade = abs(fade);
-
-        rampAlpha = smoothstep(0.0, 1.0, fade / radius);
-      }
-
-      rampAlpha = abs((rampInvert ? 1.0 : 0.0) - getBias(rampAlpha, rampBias) * getGain(rampAlpha, rampGain));
-
-      if (rampMask) {
-        vec4 inputBuff = texture2D(inputBuffer, uv);
-        outputColor = mix(inputBuff, inputColor, rampAlpha);
-      } else {
-        outputColor = mix(startColor, endColor, rampAlpha);
-      }
-    }
-  `,
-}
-
-export enum RampType {
-  Linear,
-  Radial,
-  MirroredLinear,
-}
-
-export class RampEffect extends Effect {
-  constructor({
-    /**
-     * Type of ramp gradient.
-     */
-    rampType = RampType.Linear,
-    /**
-     * Starting point of the ramp gradient in normalized coordinates.
-     *
-     * Ranges from `[0 - 1]` as `[x, y]`. Default is `[0.5, 0.5]`.
-     */
-    rampStart = [0.5, 0.5],
-    /**
-     * Ending point of the ramp gradient in normalized coordinates.
-     *
-     * Ranges from `[0 - 1]` as `[x, y]`. Default is `[1, 1]`
-     */
-    rampEnd = [1, 1],
-    /**
-     * Color at the starting point of the gradient.
-     *
-     * Default is black: `[0, 0, 0, 1]`
-     */
-    startColor = [0, 0, 0, 1],
-    /**
-     * Color at the ending point of the gradient.
-     *
-     * Default is white: `[1, 1, 1, 1]`
-     */
-    endColor = [1, 1, 1, 1],
-    /**
-     * Bias for the interpolation curve when both bias and gain are 0.5.
-     *
-     * Ranges from `[0 - 1]`. Default is `0.5`.
-     */
-    rampBias = 0.5,
-    /**
-     * Gain for the interpolation curve when both bias and gain are 0.5.
-     *
-     * Ranges from `[0 - 1]`. Default is `0.5`.
-     */
-    rampGain = 0.5,
-    /**
-     * When enabled, the ramp gradient is used as an effect mask, and colors are ignored.
-     *
-     * Default is `false`.
-     */
-    rampMask = false,
-    /**
-     * Controls whether the ramp gradient is inverted.
-     *
-     * When disabled, rampStart is transparent and rampEnd is opaque.
-     *
-     * Default is `false`.
-     */
-    rampInvert = false,
-    ...params
-  } = {}) {
-    super('RampEffect', RampShader.fragmentShader, {
-      ...params,
-      uniforms: new Map<string, Uniform>([
-        ['rampType', new Uniform(rampType)],
-        ['rampStart', new Uniform(rampStart)],
-        ['rampEnd', new Uniform(rampEnd)],
-        ['startColor', new Uniform(startColor)],
-        ['endColor', new Uniform(endColor)],
-        ['rampBias', new Uniform(rampBias)],
-        ['rampGain', new Uniform(rampGain)],
-        ['rampMask', new Uniform(rampMask)],
-        ['rampInvert', new Uniform(rampInvert)],
-      ]),
-    })
-  }
-}
-
-export const Ramp = /* @__PURE__ */ wrapEffect(RampEffect)
+import { BlendFunction, Effect } from 'postprocessing'
+import type { Ref } from 'react'
+import { Uniform } from 'three'
+import { createEffectComponent } from '../createEffectComponent'
+
+const RampShader = {
+  fragmentShader: /* glsl */ `
+    uniform int rampType;
+
+    uniform vec2 rampStart;
+    uniform vec2 rampEnd;
+
+    uniform vec4 startColor;
+    uniform vec4 endColor;
+
+    uniform float rampBias;
+    uniform float rampGain;
+
+    uniform bool rampMask;
+    uniform bool rampInvert;
+
+    float getBias(float time, float bias) {
+      return time / (((1.0 / bias) - 2.0) * (1.0 - time) + 1.0);
+    }
+
+    float getGain(float time, float gain) {
+      if (time < 0.5)
+        return getBias(time * 2.0, gain) / 2.0;
+      else
+        return getBias(time * 2.0 - 1.0, 1.0 - gain) / 2.0 + 0.5;
+    }
+
+    void mainImage(const in vec4 inputColor, const in vec2 uv, out vec4 outputColor) {
+      vec2 centerPixel = uv * resolution;
+      vec2 startPixel = rampStart * resolution;
+      vec2 endPixel = rampEnd * resolution;
+
+      float rampAlpha;
+
+      if (rampType == 1) {
+        vec2 fuv = centerPixel / resolution.y;
+        vec2 suv = startPixel / resolution.y;
+        vec2 euv = endPixel / resolution.y;
+
+        float radius = length(suv - euv);
+        float falloff = length(fuv - suv);
+        rampAlpha = smoothstep(0.0, radius, falloff);
+      } else {
+        float radius = length(startPixel - endPixel);
+        vec2 direction = normalize(vec2(endPixel.x - startPixel.x, -(startPixel.y - endPixel.y)));
+
+        float fade = dot(centerPixel - startPixel, direction);
+        if (rampType == 2) fade = abs(fade);
+
+        rampAlpha = smoothstep(0.0, 1.0, fade / radius);
+      }
+
+      rampAlpha = abs((rampInvert ? 1.0 : 0.0) - getBias(rampAlpha, rampBias) * getGain(rampAlpha, rampGain));
+
+      if (rampMask) {
+        vec4 inputBuff = texture2D(inputBuffer, uv);
+        outputColor = mix(inputBuff, inputColor, rampAlpha);
+      } else {
+        outputColor = mix(startColor, endColor, rampAlpha);
+      }
+    }
+  `,
+}
+
+export enum RampType {
+  Linear,
+  Radial,
+  MirroredLinear,
+}
+
+type RampTuple2 = [number, number]
+type RampTuple4 = [number, number, number, number]
+
+export class RampEffect extends Effect {
+  constructor({
+    /**
+     * Type of ramp gradient.
+     */
+    rampType = RampType.Linear,
+    /**
+     * Starting point of the ramp gradient in normalized coordinates.
+     *
+     * Ranges from `[0 - 1]` as `[x, y]`. Default is `[0.5, 0.5]`.
+     */
+    rampStart = [0.5, 0.5] as RampTuple2,
+    /**
+     * Ending point of the ramp gradient in normalized coordinates.
+     *
+     * Ranges from `[0 - 1]` as `[x, y]`. Default is `[1, 1]`
+     */
+    rampEnd = [1, 1] as RampTuple2,
+    /**
+     * Color at the starting point of the gradient.
+     *
+     * Default is black: `[0, 0, 0, 1]`
+     */
+    startColor = [0, 0, 0, 1] as RampTuple4,
+    /**
+     * Color at the ending point of the gradient.
+     *
+     * Default is white: `[1, 1, 1, 1]`
+     */
+    endColor = [1, 1, 1, 1] as RampTuple4,
+    /**
+     * Bias for the interpolation curve when both bias and gain are 0.5.
+     *
+     * Ranges from `[0 - 1]`. Default is `0.5`.
+     */
+    rampBias = 0.5,
+    /**
+     * Gain for the interpolation curve when both bias and gain are 0.5.
+     *
+     * Ranges from `[0 - 1]`. Default is `0.5`.
+     */
+    rampGain = 0.5,
+    /**
+     * When enabled, the ramp gradient is used as an effect mask, and colors are ignored.
+     *
+     * Default is `false`.
+     */
+    rampMask = false,
+    /**
+     * Controls whether the ramp gradient is inverted.
+     *
+     * When disabled, rampStart is transparent and rampEnd is opaque.
+     *
+     * Default is `false`.
+     */
+    rampInvert = false,
+    ...params
+  } = {}) {
+    super('RampEffect', RampShader.fragmentShader, {
+      ...params,
+      uniforms: new Map<string, Uniform>([
+        ['rampType', new Uniform(rampType)],
+        ['rampStart', new Uniform(rampStart)],
+        ['rampEnd', new Uniform(rampEnd)],
+        ['startColor', new Uniform(startColor)],
+        ['endColor', new Uniform(endColor)],
+        ['rampBias', new Uniform(rampBias)],
+        ['rampGain', new Uniform(rampGain)],
+        ['rampMask', new Uniform(rampMask)],
+        ['rampInvert', new Uniform(rampInvert)],
+      ]),
+    })
+  }
+
+  private u<T>(name: string): T {
+    return this.uniforms.get(name)!.value
+  }
+
+  private setU(name: string, value: unknown): void {
+    this.uniforms.get(name)!.value = value
+  }
+
+  get rampType(): RampType {
+    return this.u('rampType')
+  }
+  set rampType(value: RampType) {
+    this.setU('rampType', value)
+  }
+
+  get rampStart(): RampTuple2 {
+    return this.u('rampStart')
+  }
+  set rampStart(value: RampTuple2) {
+    this.setU('rampStart', value)
+  }
+
+  get rampEnd(): RampTuple2 {
+    return this.u('rampEnd')
+  }
+  set rampEnd(value: RampTuple2) {
+    this.setU('rampEnd', value)
+  }
+
+  get startColor(): RampTuple4 {
+    return this.u('startColor')
+  }
+  set startColor(value: RampTuple4) {
+    this.setU('startColor', value)
+  }
+
+  get endColor(): RampTuple4 {
+    return this.u('endColor')
+  }
+  set endColor(value: RampTuple4) {
+    this.setU('endColor', value)
+  }
+
+  get rampBias(): number {
+    return this.u('rampBias')
+  }
+  set rampBias(value: number) {
+    this.setU('rampBias', value)
+  }
+
+  get rampGain(): number {
+    return this.u('rampGain')
+  }
+  set rampGain(value: number) {
+    this.setU('rampGain', value)
+  }
+
+  get rampMask(): boolean {
+    return this.u('rampMask')
+  }
+  set rampMask(value: boolean) {
+    this.setU('rampMask', value)
+  }
+
+  get rampInvert(): boolean {
+    return this.u('rampInvert')
+  }
+  set rampInvert(value: boolean) {
+    this.setU('rampInvert', value)
+  }
+}
+
+export type RampProps = {
+  blendFunction?: BlendFunction
+  rampType?: RampType
+  rampStart?: RampTuple2
+  rampEnd?: RampTuple2
+  startColor?: RampTuple4
+  endColor?: RampTuple4
+  rampBias?: number
+  rampGain?: number
+  rampMask?: boolean
+  rampInvert?: boolean
+  ref?: Ref<RampEffect>
+}
+
+export const Ramp = /* @__PURE__ */ createEffectComponent<typeof RampEffect, RampProps>(RampEffect)