Skip to content

Latest commit

 

History

History
402 lines (324 loc) · 20.5 KB

api.md

File metadata and controls

402 lines (324 loc) · 20.5 KB
Raw

Effects

Here's a list of all wrapped effects with demos, example usage (with default props) and reference to postprocessing docs.

<SSAO /> 

import { SSAO } from '@react-three/postprocessing'
import { BlendFunction } from 'postprocessing'

return (
  <SSAO
    blendFunction={BlendFunction.MULTIPLY} // blend mode
    samples={30} // amount of samples per pixel (shouldn't be a multiple of the ring count)
    rings={4} // amount of rings in the occlusion sampling pattern
    distanceThreshold={1.0} // global distance threshold at which the occlusion effect starts to fade out. min: 0, max: 1
    distanceFalloff={0.0} // distance falloff. min: 0, max: 1
    rangeThreshold={0.5} // local occlusion range threshold at which the occlusion starts to fade out. min: 0, max: 1
    rangeFalloff={0.1} // occlusion range falloff. min: 0, max: 1
    luminanceInfluence={0.9} // how much the luminance of the scene influences the ambient occlusion
    radius={20} // occlusion sampling radius
    scale={0.5} // scale of the ambient occlusion
    bias={0.5} // occlusion bias
  />
)

<Glitch /> 

import { Glitch } from '@react-three/postprocessing'
import { GlitchMode } from 'postprocessing'

return (
  <Glitch
    delay={[1.5, 3.5]} // min and max glitch delay
    duration={[0.6, 1.0]} // min and max glitch duration
    strength={[0.3, 1.0]} // min and max glitch strength
    mode={GlitchMode.SPORADIC} // glitch mode
    active // turn on/off the effect (switches between "mode" prop and GlitchMode.DISABLED)
    ratio={0.85} // Threshold for strong glitches, 0 - no weak glitches, 1 - no strong glitches.
  />
)

<GodRays />

The GodRays effect requires a mesh that will be used as an origin point for the rays. Refer to this example for more details.

import { GodRays } from '@react-three/postprocessing'

return (
 <GodRays
   sun={sunRef}
   blendFunction={BlendFunction.Screen} // The blend function of this effect.
   samples={60} // The number of samples per pixel.
   density={0.96} // The density of the light rays.
   decay={0.9} // An illumination decay factor.
   weight={0.4} // A light ray weight factor.
   exposure={0.6} // A constant attenuation coefficient.
   clampMax={1} // An upper bound for the saturation of the overall effect.
   width={Resizer.AUTO_SIZE} // Render width.
   height={Resizer.AUTO_SIZE} // Render height.
   kernelSize={KernelSize.SMALL} // The blur kernel size. Has no effect if blur is disabled.
   blur={true} // Whether the god rays should be blurred to reduce artifacts.
  />

)

<Noise /> 

import { Noise } from '@react-three/postprocessing'
import { BlendFunction } from 'postprocessing'

return (
  <Noise
    premultiply // enables or disables noise premultiplication
    blendFunction={BlendFunction.ADD} // blend mode
  />
)

<Bloom /> 

import { Bloom } from '@react-three/postprocessing'
import { BlurPass, Resizer, KernelSize } from 'postprocessing'

return (
  <Bloom
    intensity={1.0} // The bloom intensity.
    blurPass={undefined} // A blur pass.
    width={Resizer.AUTO_SIZE} // render width
    height={Resizer.AUTO_SIZE} // render height
    kernelSize={KernelSize.LARGE} // blur kernel size
    luminanceThreshold={0.9} // luminance threshold. Raise this value to mask out darker elements in the scene.
    luminanceSmoothing={0.025} // smoothness of the luminance threshold. Range is [0, 1]
  />
)

<Outline /> 

import { Outline } from '@react-three/postprocessing'
import { BlendFunction, Resizer, KernelSize } from 'postprocessing'

return (
  <Outline
    selection={[meshRef1, meshRef2]} // selection of objects that will be outlined
    selectionLayer={10} // selection layer
    blendFunction={BlendFunction.SCREEN} // set this to BlendFunction.ALPHA for dark outlines
    patternTexture={null} // a pattern texture
    edgeStrength={2.5} // the edge strength
    pulseSpeed={0.0} // a pulse speed. A value of zero disables the pulse effect
    visibleEdgeColor={0xffffff} // the color of visible edges
    hiddenEdgeColor={0x22090a} // the color of hidden edges
    width={Resizer.AUTO_SIZE} // render width
    height={Resizer.AUTO_SIZE} // render height
    kernelSize={KernelSize.LARGE} // blur kernel size
    blur={false} // whether the outline should be blurred
    xRay={true} // indicates whether X-Ray outlines are enabled
  />
)

<SelectiveBloom /> 

import { Bloom } from '@react-three/postprocessing'
import { BlurPass, Resizer, KernelSize } from 'postprocessing'

return (
  <SelectiveBloom
    lights={[lightRef1, lightRef2]} // ⚠️ REQUIRED! all relevant lights
    selection={[meshRef1, meshRef2]} // selection of objects that will have bloom effect
    selectionLayer={10} // selection layer
    intensity={1.0} // The bloom intensity.
    blurPass={undefined} // A blur pass.
    width={Resizer.AUTO_SIZE} // render width
    height={Resizer.AUTO_SIZE} // render height
    kernelSize={KernelSize.LARGE} // blur kernel size
    luminanceThreshold={0.9} // luminance threshold. Raise this value to mask out darker elements in the scene.
    luminanceSmoothing={0.025} // smoothness of the luminance threshold. Range is [0, 1]
  />
)

<Vignette /> 

import { Vignette } from '@react-three/postprocessing'
import { BlendFunction } from 'postprocessing'

return (
  <Vignette
    offset={0.5} // vignette offset
    darkness={0.5} // vignette darkness
    eskil={false} // Eskil's vignette technique
    blendFunction={BlendFunction.NORMAL} // blend mode
  />
)

<Sepia /> 

import { Sepia } from '@react-three/postprocessing'

return (
  <Sepia
    intensity={1.0} // sepia intensity
    blendFunction={BlendFunction.NORMAL} // blend mode
  />
)

<DotScreen /> 

import { DotScreen } from '@react-three/postprocessing'
import { BlendFunction } from 'postprocessing'

return (
  <DotScreen
    blendFunction={BlendFunction.NORMAL} // blend mode
    angle={Math.PI * 0.5} // angle of the dot pattern
    scale={1.0} // scale of the dot pattern
  />
)

<Pixelation /> 

import { Pixelation } from '@react-three/postprocessing'

return (
  <Pixelation
    granularity={5} // pixel granularity
  />
)

<HueSaturation /> 

import { HueSaturation } from '@react-three/postprocessing'
import { BlendFunction } from 'postprocessing'

return (
  <HueSaturation
    blendFunction={BlendFunction.NORMAL} // blend mode
    hue={0} // hue in radians
    saturation={0} // saturation in radians
  />
)

<BrightnessContrast /> 

import { BrightnessContrast } from 'postprocessing'

return (
  <BrightnessContrast
    brightness={0} // brightness. min: -1, max: 1
    contrast={0} // contrast: min -1, max: 1
  />
)

<ToneMapping /> 

import { ToneMapping } from '@react-three/postprocessing'
import { BlendFunction } from 'postprocessing'

return (
  <ToneMapping
    blendFunction={BlendFunction.NORMAL} // blend mode
    adaptive={true} // toggle adaptive luminance map usage
    resolution={256} // texture resolution of the luminance map
    middleGrey={0.6} // middle grey factor
    maxLuminance={16.0} // maximum luminance
    averageLuminance={1.0} // average luminance
    adaptationRate={1.0} // luminance adaptation rate
  />
)

<Scanline /> 

import { Scanline } from '@react-three/postprocessing'
import { BlendFunction } from 'postprocessing'

return (
  <Scanline
    blendFunction={BlendFunction.OVERLAY} // blend mode
    density={1.25} // scanline density
  />
)

<ChromaticAberration /> 

import { ChromaticAberration } from '@react-three/postprocessing'
import { BlendFunction } from 'postprocessing'

return (
  <ChromaticAberration
    blendFunction={BlendFunction.NORMAL} // blend mode
    offset={[0.02, 0.002]} // color offset
  />
)

<ColorAverage /> 

import { ColorAverage } from '@react-three/postprocessing'
import { BlendFunction } from 'postprocessing'

return (
  <ColorAverage
    blendFunction={BlendFunction.NORMAL} // blend mode
  />
)

<Grid /> 

import { Grid } from '@react-three/postprocessing'
import { BlendFunction } from 'postprocessing'

return (
  <Grid
    blendFunction={BlendFunction.OVERLAY} // blend mode
    scale={1.0} // grid pattern scale
    lineWidth={0.0} // grid pattern line width
    size={{ width, height }} // overrides the default pass width and height
  />
)

<SMAA />

By default react-postprocessing uses webgl2 multisampling (MSAA) for native AA. In some effects this can result in artefacts. Should you either want to work with webgl1 exclusively, or you get artefacts, then you can switch MSAA off and use SMAA. This effect is async and relies on suspense!

import React, { Suspense } from 'react'
import { EffectComposer, SMAA } from '@react-three/postprocessing'

return (
  <Suspense fallback={null}>
    <EffectComposer multisampling={0}>
      <SMAA />
    </EffectComposer>
  </Suspense>
)

Custom effects

If you plan to use custom effects, make sure to expose the effect itself as a primitive!

import React, { forwardRef, useMemo } from 'react'
import { PixelationEffect } from 'postprocessing'

export const Pixelation = forwardRef(({ granularity = 5 }, ref) => {
  const effect = useMemo(() => new PixelationEffect(granularity), [granularity])
  return <primitive ref={ref} object={effect} dispose={null} />
})

For effects that aren't present in postprocessing you should extend the Effect class:

import React, { forwardRef, useMemo } from 'react'
import { Uniform } from 'three'
import { Effect } from 'postprocessing'

const fragmentShader = `some_shader_code`

let _uParam

// Effect implementation
class MyCustomEffectImpl extends Effect {
  constructor({ param = 0.1 } = {}) {
    super('MyCustomEffect', fragmentShader, {
      uniforms: new Map([['param', new Uniform(param)]])
    })

    _uParam = param
  }

  update(renderer, inputBuffer, deltaTime) {
    this.uniforms.get('param').value = _uParam
  }
}

// Effect component
export const MyCustomEffect = forwardRef(({ param }, ref) => {
  const effect = useMemo(() => new MyCustomEffectImpl(param), [param])
  return <primitive ref={ref} object={effect} dispose={null} />
})