Skip to content

Commit c7429bf

Browse files
kvvasuukvvasuu
committed
docs: add missing effect pages - #292
Adds docs for ASCII, ColorDepth, Depth, FXAA, LUT, N8AO, ShockWave, Texture, TiltShift, TiltShift2, and Water. Skips SSR from the original issue list since that effect no longer exists.
1 parent 6be1336 commit c7429bf

11 files changed

Lines changed: 345 additions & 0 deletions

File tree

‎docs/effects/ascii.mdx‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: ASCII
3+
nav: 1
4+
---
5+
6+
Renders the scene as ASCII art, mapping pixel luminance to characters drawn onto a canvas-based character atlas. Adapted from [emilwidlund/ASCII](https://github.com/emilwidlund/ASCII).
7+
8+
```jsx
9+
import { ASCII } from '@react-three/postprocessing'
10+
11+
return (
12+
<ASCII
13+
font="arial" // font family used to draw the character atlas
14+
characters=" .:,'-^=*+?!|0#X%WM@" // characters to sample from, in order of increasing "weight"
15+
fontSize={54} // font size used to draw the character atlas
16+
cellSize={16} // size of each character cell, in pixels
17+
color="#ffffff" // character color
18+
invert={false} // inverts which characters map to bright vs dark pixels
19+
/>
20+
)
21+
```
22+
23+
## Props
24+
25+
| Name | Type | Default | Description |
26+
| ---------- | ------- | ----------------------- | ------------------------------------------------------------------ |
27+
| font | String | 'arial' | The font family used to draw the character atlas. |
28+
| characters | String | ` .:,'-^=*+?!\|0#X%WM@` | The characters to sample from, ordered from "empty" to "dense". |
29+
| fontSize | Number | 54 | The font size used to draw the character atlas. |
30+
| cellSize | Number | 16 | The size of each character cell, in pixels. |
31+
| color | String | '#ffffff' | The color of the characters. |
32+
| invert | Boolean | false | Inverts which characters map to bright vs dark pixels. |

‎docs/effects/color-depth.mdx‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: ColorDepth
3+
nav: 1
4+
---
5+
6+
Reduces the color depth of the scene, uniformly across all color channels - a posterize-like effect.
7+
8+
```jsx
9+
import { ColorDepth } from '@react-three/postprocessing'
10+
11+
return (
12+
<ColorDepth
13+
bits={16} // the virtual color bit depth
14+
/>
15+
)
16+
```
17+
18+
## Props
19+
20+
| Name | Type | Default | Description |
21+
| ------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------- |
22+
| blendFunction | BlendFunction | | The blend function of this effect. |
23+
| bits | Number | 16 | The virtual amount of color bits. Each color channel effectively uses a fourth of this total; alpha is unaffected. |

‎docs/effects/depth.mdx‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
title: Depth
3+
nav: 1
4+
---
5+
6+
Visualizes the scene's depth buffer as grayscale - useful for debugging, or as an input for further custom effects.
7+
8+
```jsx
9+
import { Depth } from '@react-three/postprocessing'
10+
import { BlendFunction } from 'postprocessing'
11+
12+
return (
13+
<Depth
14+
blendFunction={BlendFunction.SRC} // the blend function of this effect
15+
inverted={false} // whether the depth should be inverted
16+
/>
17+
)
18+
```
19+
20+
## Props
21+
22+
| Name | Type | Default | Description |
23+
| ------------- | ------------- | --------------------- | ---------------------------------------- |
24+
| blendFunction | BlendFunction | BlendFunction.SRC | The blend function of this effect. |
25+
| inverted | Boolean | false | Whether the depth should be inverted. |

‎docs/effects/fxaa.mdx‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: FXAA
3+
nav: 1
4+
---
5+
6+
Fast Approximate Anti-Aliasing - a cheap, single-pass alternative to [SMAA](/effects/smaa) with lower visual quality but better performance.
7+
8+
```jsx
9+
import { FXAA } from '@react-three/postprocessing'
10+
import { BlendFunction } from 'postprocessing'
11+
12+
return (
13+
<FXAA
14+
blendFunction={BlendFunction.SRC} // the blend function of this effect
15+
minEdgeThreshold={0.0312} // the minimum edge detection threshold
16+
maxEdgeThreshold={0.125} // the maximum edge detection threshold
17+
subpixelQuality={0.75} // the subpixel blend quality
18+
samples={12} // the maximum amount of edge detection samples
19+
/>
20+
)
21+
```
22+
23+
## Props
24+
25+
| Name | Type | Default | Description |
26+
| ----------------- | ------------- | -------------------- | -------------------------------------------------------- |
27+
| blendFunction | BlendFunction | BlendFunction.SRC | The blend function of this effect. |
28+
| minEdgeThreshold | Number | 0.0312 | The minimum edge detection threshold. Range [0.0, 1.0]. |
29+
| maxEdgeThreshold | Number | 0.125 | The maximum edge detection threshold. Range [0.0, 1.0]. |
30+
| subpixelQuality | Number | 0.75 | The subpixel blend quality. Range [0.0, 1.0]. |
31+
| samples | Number | 12 | The maximum amount of edge detection samples. |

‎docs/effects/lut.mdx‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
title: LUT
3+
nav: 1
4+
---
5+
6+
Applies 3D LUT-based color grading using a lookup texture (a `THREE.Texture` built from e.g. a `.cube` file or a data texture you construct yourself).
7+
8+
```jsx
9+
import { LUT } from '@react-three/postprocessing'
10+
import { BlendFunction } from 'postprocessing'
11+
12+
return (
13+
<LUT
14+
lut={lutTexture} // the lookup texture
15+
blendFunction={BlendFunction.SRC} // the blend function of this effect
16+
tetrahedralInterpolation={false} // enables or disables tetrahedral interpolation
17+
/>
18+
)
19+
```
20+
21+
## Props
22+
23+
| Name | Type | Default | Description |
24+
| ------------------------ | ------------- | -------------------- | ----------------------------------------------------- |
25+
| lut | Texture | | The lookup texture. Required. |
26+
| blendFunction | BlendFunction | BlendFunction.SRC | The blend function of this effect. |
27+
| tetrahedralInterpolation | Boolean | false | Enables or disables tetrahedral interpolation. |

‎docs/effects/n8ao.mdx‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
title: N8AO
3+
nav: 1
4+
---
5+
6+
A fast, high quality ambient occlusion effect, wrapping [N8python/n8ao](https://github.com/N8python/n8ao). Self-contained - unlike [SSAO](/effects/ssao), it does not need `enableNormalPass` on `<EffectComposer>`.
7+
8+
```jsx
9+
import { N8AO } from '@react-three/postprocessing'
10+
11+
return (
12+
<N8AO
13+
aoRadius={5} // ambient occlusion sampling radius
14+
distanceFalloff={1} // distance falloff
15+
intensity={1} // effect intensity
16+
quality="performance" // 'performance' | 'low' | 'medium' | 'high' | 'ultra'
17+
aoSamples={16} // amount of ambient occlusion samples per frame
18+
denoiseSamples={4} // amount of denoise samples per frame
19+
denoiseRadius={12} // denoise sampling radius
20+
color={undefined} // tints the occlusion, defaults to black
21+
halfRes={false} // renders the effect at half resolution
22+
depthAwareUpsampling={true} // enables or disables depth-aware upsampling
23+
screenSpaceRadius={false} // scales the sampling radius with distance from the camera
24+
renderMode={0} // 0: Combined, 1: AO only, 2: No AO, 3: Split, 4: Split AO
25+
/>
26+
)
27+
```
28+
29+
## Props
30+
31+
| Name | Type | Default | Description |
32+
| -------------------- | ------------------------------------------------------- | ------------- | --------------------------------------------------------- |
33+
| aoRadius | Number | 5 | The ambient occlusion sampling radius. |
34+
| distanceFalloff | Number | 1 | The distance falloff. |
35+
| intensity | Number | 1 | The effect intensity. |
36+
| quality | 'performance' \| 'low' \| 'medium' \| 'high' \| 'ultra' | 'performance' | The quality preset. |
37+
| aoSamples | Number | 16 | The amount of ambient occlusion samples per frame. |
38+
| denoiseSamples | Number | 4 | The amount of denoise samples per frame. |
39+
| denoiseRadius | Number | 12 | The denoise sampling radius. |
40+
| color | Color | undefined | Tints the occlusion. Defaults to black. |
41+
| halfRes | Boolean | false | Renders the effect at half resolution. |
42+
| depthAwareUpsampling | Boolean | true | Enables or disables depth-aware upsampling. |
43+
| screenSpaceRadius | Boolean | false | Scales the sampling radius with distance from the camera. |
44+
| renderMode | 0 \| 1 \| 2 \| 3 \| 4 | 0 | 0: Combined, 1: AO only, 2: No AO, 3: Split, 4: Split AO. |

‎docs/effects/shockwave.mdx‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: ShockWave
3+
nav: 1
4+
---
5+
6+
An animated shockwave/distortion effect emanating from a point in 3D space. It doesn't trigger itself - call `explode()` on the effect's ref whenever you want the wave to fire.
7+
8+
```jsx
9+
import { useRef } from 'react'
10+
import { ShockWave } from '@react-three/postprocessing'
11+
import type { ShockWaveEffect } from 'postprocessing'
12+
13+
const ref = useRef<ShockWaveEffect>(null)
14+
15+
return (
16+
<>
17+
<ShockWave
18+
ref={ref}
19+
position={[0, 0, 0]} // the world position of the shockwave
20+
speed={2.0} // the animation speed
21+
maxRadius={1.0} // the extent of the shockwave
22+
waveSize={0.2} // the wave size
23+
amplitude={0.05} // the distortion amplitude
24+
/>
25+
<button onClick={() => ref.current?.explode()}>Explode</button>
26+
</>
27+
)
28+
```
29+
30+
## Props
31+
32+
| Name | Type | Default | Description |
33+
| --------- | ------- | -------- | ------------------------------------- |
34+
| position | Vector3 | (0,0,0) | The world position of the shockwave. |
35+
| speed | Number | 2.0 | The animation speed. |
36+
| maxRadius | Number | 1.0 | The extent of the shockwave. |
37+
| waveSize | Number | 0.2 | The wave size. |
38+
| amplitude | Number | 0.05 | The distortion amplitude. |

‎docs/effects/texture.mdx‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: Texture
3+
nav: 1
4+
---
5+
6+
Blends a texture over the scene. Give it a URL via `textureSrc` and it loads (and suspends on) the texture itself - pass an already-loaded `THREE.Texture` via `texture` instead if you're loading it yourself.
7+
8+
```jsx
9+
import { Texture } from '@react-three/postprocessing'
10+
11+
return (
12+
<Texture
13+
textureSrc="/texture.png" // loads the texture for you
14+
opacity={1} // opacity of the texture
15+
aspectCorrection={false} // deprecated - adjust the texture's offset/repeat/center instead
16+
/>
17+
)
18+
```
19+
20+
## Props
21+
22+
| Name | Type | Default | Description |
23+
| ----------------- | ------- | -------- | ------------------------------------------------------------------------------------- |
24+
| textureSrc | String | | URL of the texture to load. |
25+
| texture | Texture | | An already-loaded texture - alternative to `textureSrc`. |
26+
| blendFunction | BlendFunction | | The blend function of this effect. |
27+
| opacity | Number | 1 | The opacity of the texture. |
28+
| aspectCorrection | Boolean | false | Deprecated. Adjust the texture's offset, repeat and center instead. |

‎docs/effects/tilt-shift-2.mdx‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
title: TiltShift2
3+
nav: 1
4+
---
5+
6+
An alternate tilt-shift implementation with direct control over the blurred band's start/end points and blur direction, instead of a single centered focus-area size. For the simpler, centered version, see [TiltShift](/effects/tilt-shift).
7+
8+
```jsx
9+
import { TiltShift2 } from '@react-three/postprocessing'
10+
import { BlendFunction } from 'postprocessing'
11+
12+
return (
13+
<TiltShift2
14+
blendFunction={BlendFunction.NORMAL} // the blend function of this effect
15+
blur={0.15} // the blur intensity, [0, 1] (can go beyond 1)
16+
taper={0.5} // the size of the sharp/in-focus area, [0, 1] (can go beyond 1)
17+
start={[0.5, 0.0]} // start point of the blur band, in screen-space percent [0, 1]
18+
end={[0.5, 1.0]} // end point of the blur band, in screen-space percent [0, 1]
19+
samples={10} // number of blur samples
20+
direction={[1, 1]} // direction of the blur
21+
/>
22+
)
23+
```
24+
25+
## Props
26+
27+
| Name | Type | Default | Description |
28+
| ------------- | ------------- | ------------------ | ------------------------------------------------------------ |
29+
| blendFunction | BlendFunction | BlendFunction.NORMAL | The blend function of this effect. |
30+
| blur | Number | 0.15 | The blur intensity. Range [0, 1] (can exceed 1 for extra). |
31+
| taper | Number | 0.5 | The size of the sharp/in-focus area. Range [0, 1] (can exceed 1). |
32+
| start | [Number, Number] | [0.5, 0.0] | Start point of the blur band, in screen-space percent. |
33+
| end | [Number, Number] | [0.5, 1.0] | End point of the blur band, in screen-space percent. |
34+
| samples | Number | 10 | The number of blur samples. |
35+
| direction | [Number, Number] | [1, 1] | The direction of the blur. |

‎docs/effects/tilt-shift.mdx‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: TiltShift
3+
nav: 1
4+
---
5+
6+
A tilt-shift blur effect, simulating a shallow depth of field along a band across the screen - the classic "miniature model" look. For a version with more direct control over the band's start/end/direction, see [TiltShift2](/effects/tilt-shift-2).
7+
8+
```jsx
9+
import { TiltShift } from '@react-three/postprocessing'
10+
import { BlendFunction, KernelSize } from 'postprocessing'
11+
12+
return (
13+
<TiltShift
14+
blendFunction={BlendFunction.ADD} // the blend function of this effect
15+
offset={0.0} // the relative offset of the focus area
16+
rotation={0.0} // the rotation of the focus area, in radians
17+
focusArea={0.4} // the relative size of the focus area
18+
feather={0.3} // the softness of the focus area edges
19+
kernelSize={KernelSize.MEDIUM} // the blur kernel size
20+
resolutionScale={0.5} // the resolution scale
21+
/>
22+
)
23+
```
24+
25+
## Props
26+
27+
| Name | Type | Default | Description |
28+
| ---------------- | ------------- | ---------------------- | ------------------------------------------ |
29+
| blendFunction | BlendFunction | BlendFunction.ADD | The blend function of this effect. |
30+
| offset | Number | 0.0 | The relative offset of the focus area. |
31+
| rotation | Number | 0.0 | The rotation of the focus area, in radians. |
32+
| focusArea | Number | 0.4 | The relative size of the focus area. |
33+
| feather | Number | 0.3 | The softness of the focus area edges. |
34+
| kernelSize | KernelSize | KernelSize.MEDIUM | The blur kernel size. |
35+
| resolutionScale | Number | 0.5 | The resolution scale. |
36+
| resolutionX | Number | Resolution.AUTO_SIZE | The horizontal resolution. |
37+
| resolutionY | Number | Resolution.AUTO_SIZE | The vertical resolution. |

0 commit comments

Comments
 (0)