Skip to content

Commit b9923ac

Browse files
kvvasuukvvasuu
authored
Merge pull request #370 from pmndrs/fix/docs-workflow-v3
Fix/docs workflow v3
2 parents 82026be + 8838341 commit b9923ac

5 files changed

Lines changed: 104 additions & 199 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ concurrency:
1111

1212
jobs:
1313
build:
14-
uses: pmndrs/docs/.github/workflows/build.yml@v2
14+
uses: pmndrs/docs/.github/workflows/build.yml@v3
1515
with:
1616
mdx: 'docs'
1717
libname: 'React Postprocessing'

‎docs/effects/custom-effects.mdx‎

Lines changed: 19 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -5,45 +5,50 @@ nav: 2
55

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

8+
r3f never disposes objects rendered via `<primitive object={...}>` (their state may be owned outside
9+
React), so effects rendered this way must dispose themselves - use the `useDispose` hook exported by
10+
this library for that.
11+
812
```jsx
9-
import React, { forwardRef, useMemo } from 'react'
13+
import { useMemo } from 'react'
1014
import { PixelationEffect } from 'postprocessing'
15+
import { useDispose } from '@react-three/postprocessing'
1116

12-
export const Pixelation = forwardRef(({ granularity = 5 }, ref) => {
17+
export function Pixelation({ granularity = 5, ref }) {
1318
const effect = useMemo(() => new PixelationEffect(granularity), [granularity])
14-
return <primitive ref={ref} object={effect} dispose={null} />
15-
})
19+
useDispose(effect)
20+
return <primitive ref={ref} object={effect} />
21+
}
1622
```
1723

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

20-
```js
21-
import React, { forwardRef, useMemo } from 'react'
26+
```jsx
27+
import { useMemo } from 'react'
2228
import { Uniform } from 'three'
2329
import { Effect } from 'postprocessing'
30+
import { useDispose } from '@react-three/postprocessing'
2431

2532
const fragmentShader = `some_shader_code`
2633

27-
let _uParam
28-
2934
// Effect implementation
3035
class MyCustomEffectImpl extends Effect {
3136
constructor({ param = 0.1 } = {}) {
3237
super('MyCustomEffect', fragmentShader, {
3338
uniforms: new Map([['param', new Uniform(param)]]),
3439
})
35-
36-
_uParam = param
3740
}
3841

3942
update(renderer, inputBuffer, deltaTime) {
40-
this.uniforms.get('param').value = _uParam
43+
// read/write per-frame state on `this` (e.g. this.uniforms.get('param').value = ...),
44+
// never on a module-level variable - that would be shared across every instance
4145
}
4246
}
4347

4448
// Effect component
45-
export const MyCustomEffect = ({ ref, param }) => {
46-
const effect = useMemo(() => new MyCustomEffectImpl(param), [param])
47-
return <primitive ref={ref} object={effect} dispose={null} />
49+
export function MyCustomEffect({ param, ref }) {
50+
const effect = useMemo(() => new MyCustomEffectImpl({ param }), [param])
51+
useDispose(effect)
52+
return <primitive ref={ref} object={effect} />
4853
}
4954
```

‎docs/effects/outline.mdx‎

Lines changed: 26 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -7,21 +7,24 @@ An outline effect.
77

88
```jsx
99
import { Outline } from '@react-three/postprocessing'
10-
import { BlendFunction, Resizer, KernelSize } from 'postprocessing'
10+
import { BlendFunction, Resolution, KernelSize } from 'postprocessing'
1111

1212
return (
1313
<Outline
1414
selection={[meshRef1, meshRef2]} // selection of objects that will be outlined
1515
selectionLayer={10} // selection layer
1616
blendFunction={BlendFunction.SCREEN} // set this to BlendFunction.ALPHA for dark outlines
1717
patternTexture={null} // a pattern texture
18-
edgeStrength={2.5} // the edge strength
18+
patternScale={1.0} // the pattern texture scale
19+
edgeStrength={1.0} // the edge strength
1920
pulseSpeed={0.0} // a pulse speed. A value of zero disables the pulse effect
2021
visibleEdgeColor={0xffffff} // the color of visible edges
2122
hiddenEdgeColor={0x22090a} // the color of hidden edges
22-
width={Resizer.AUTO_SIZE} // render width
23-
height={Resizer.AUTO_SIZE} // render height
24-
kernelSize={KernelSize.LARGE} // blur kernel size
23+
multisampling={0} // the number of samples used for multisample antialiasing, requires WebGL 2
24+
resolutionScale={0.5} // render resolution scale
25+
resolutionX={Resolution.AUTO_SIZE} // render width
26+
resolutionY={Resolution.AUTO_SIZE} // render height
27+
kernelSize={KernelSize.VERY_SMALL} // blur kernel size
2528
blur={false} // whether the outline should be blurred
2629
xRay={true} // indicates whether X-Ray outlines are enabled
2730
/>
@@ -30,18 +33,21 @@ return (
3033

3134
## Props
3235

33-
| Name | Type | Default | Description |
34-
| ---------------- | ------------- | --------------------- | ------------------------------------------------------------- |
35-
| selection | Objects | | Selection of objects that will be outlined |
36-
| blendFunction | BlendFunction | BlendFunction.SCREEN | The blend function of this effect. |
37-
| width | Number | Resizer.AUTO_SIZE | The render width. |
38-
| height | Number | Resizer.AUTO_SIZE | The render height. |
39-
| selectionLayer | Number | | The selection layer |
40-
| patternTexture | Number | null | A pattern texture |
41-
| edgeStrength | Number | 1 | The edge strength |
42-
| pulseSpeed | Number | 0 | The pulse speed. A value of zero disables the pulse effect. |
43-
| visibleEdgeColor | Number | 0xffffff | The color of visible edges. |
44-
| hiddenEdgeColor | Number | 0x22090a | The color of hidden edges. |
45-
| kernelSize | KernelSize | KernelSize.VERY_SMALL | The blur kernel size. |
46-
| blur | Boolean | false | Whether the outline should be blurred. |
47-
| xray | Boolean | true | Whether occluded parts of selected objects should be visible. |
36+
| Name | Type | Default | Description |
37+
| ---------------- | ------------- | ----------------------- | ---------------------------------------------------------------------------------- |
38+
| selection | Objects | | Selection of objects that will be outlined |
39+
| selectionLayer | Number | 10 | The selection layer |
40+
| blendFunction | BlendFunction | BlendFunction.SCREEN | The blend function of this effect. |
41+
| patternTexture | Texture | null | A pattern texture. |
42+
| patternScale | Number | 1.0 | The pattern texture scale. |
43+
| edgeStrength | Number | 1.0 | The edge strength. |
44+
| pulseSpeed | Number | 0 | The pulse speed. A value of zero disables the pulse effect. |
45+
| visibleEdgeColor | Number | 0xffffff | The color of visible edges. |
46+
| hiddenEdgeColor | Number | 0x22090a | The color of hidden edges. |
47+
| multisampling | Number | 0 | The number of samples used for multisample antialiasing. Requires WebGL 2. |
48+
| resolutionScale | Number | 0.5 | The render resolution scale. |
49+
| resolutionX | Number | Resolution.AUTO_SIZE | The render width. |
50+
| resolutionY | Number | Resolution.AUTO_SIZE | The render height. |
51+
| kernelSize | KernelSize | KernelSize.VERY_SMALL | The blur kernel size. |
52+
| blur | Boolean | false | Whether the outline should be blurred. |
53+
| xRay | Boolean | true | Whether occluded parts of selected objects should be visible. |

‎docs/effects/selective-bloom.mdx‎

Lines changed: 32 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -11,36 +11,46 @@ Attention: If you don't need to limit bloom to a subset of objects, consider usi
1111

1212
```jsx
1313
import { SelectiveBloom } from '@react-three/postprocessing'
14-
import { BlurPass, Resizer, KernelSize } from 'postprocessing'
14+
import { BlendFunction, Resolution, KernelSize } from 'postprocessing'
1515

1616
return (
1717
<SelectiveBloom
1818
lights={[lightRef1, lightRef2]} // ⚠️ REQUIRED! all relevant lights
19-
selection={[meshRef1, meshRef2]} // selection of objects that will have bloom effect
19+
selection={[meshRef1, meshRef2]} // selection of objects that will have the bloom effect
2020
selectionLayer={10} // selection layer
21-
intensity={1.0} // The bloom intensity.
22-
blurPass={undefined} // A blur pass.
23-
width={Resizer.AUTO_SIZE} // render width
24-
height={Resizer.AUTO_SIZE} // render height
25-
kernelSize={KernelSize.LARGE} // blur kernel size
26-
luminanceThreshold={0.9} // luminance threshold. Raise this value to mask out darker elements in the scene.
27-
luminanceSmoothing={0.025} // smoothness of the luminance threshold. Range is [0, 1]
21+
inverted={false} // consider the selection inverted
22+
ignoreBackground={false} // discard the background of the selection
23+
luminanceThreshold={1.0} // luminance threshold. Raise this value to mask out darker elements in the scene.
24+
luminanceSmoothing={0.03} // smoothness of the luminance threshold. Range is [0, 1]
25+
mipmapBlur={true} // enables/disables mipmap blur
26+
intensity={1.0} // the bloom intensity
27+
radius={0.85} // the blur radius, only applies to mipmap blur
28+
levels={8} // the amount of MIP levels, only applies to mipmap blur
29+
kernelSize={KernelSize.LARGE} // blur kernel size, ignored if mipmapBlur is enabled
30+
resolutionScale={0.5} // render resolution scale, ignored if mipmapBlur is enabled
31+
resolutionX={Resolution.AUTO_SIZE} // render width, ignored if mipmapBlur is enabled
32+
resolutionY={Resolution.AUTO_SIZE} // render height, ignored if mipmapBlur is enabled
2833
/>
2934
)
3035
```
3136

3237
## Props
3338

34-
| Name | Type | Default | Description |
35-
| ------------------ | ------------------------------------------------------------------------------------------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------- |
36-
| selection | Objects | | Selection of objects that will be outlined |
37-
| lights | Lights | | All lights that will affect the effect |
38-
| blendFunction | BlendFunction | BlendFunction.SCREEN | The blend function of this effect. |
39-
| width | Number | Resizer.AUTO_SIZE | The render width. |
40-
| height | Number | Resizer.AUTO_SIZE | The render height. |
41-
| selectionLayer | Number | | The selection layer |
42-
| blurPass | [BlurPass](https://vanruesc.github.io/postprocessing/public/docs/class/src/passes/BlurPass.js~BlurPass.html) | null | An efficient, incremental blur pass. |
43-
| kernelSize | KernelSize | KernelSize.LARGE | The blur kernel size. |
44-
| luminanceThreshold | Number | 0.9 | The luminance threshold. Raise this value to mask out darker elements in the scene. Range is [0, 1]. |
45-
| luminanceSmoothing | Number | 0.025 | Controls the smoothness of the luminance threshold. Range is [0, 1]. |
46-
| intensity | Number | 1 | Intensity of the effect |
39+
| Name | Type | Default | Description |
40+
| ------------------ | ------------- | -------------------- | ---------------------------------------------------------------------------------------------------- |
41+
| selection | Objects | | Selection of objects that will have the bloom effect |
42+
| lights | Lights | | All lights that will affect the effect - required |
43+
| selectionLayer | Number | 10 | The selection layer |
44+
| inverted | Boolean | false | Consider the selection inverted. |
45+
| ignoreBackground | Boolean | false | Discard the background of the selection. |
46+
| blendFunction | BlendFunction | BlendFunction.SCREEN | The blend function of this effect. |
47+
| luminanceThreshold | Number | 1.0 | The luminance threshold. Raise this value to mask out darker elements in the scene. Range is [0, 1]. |
48+
| luminanceSmoothing | Number | 0.03 | Controls the smoothness of the luminance threshold. Range is [0, 1]. |
49+
| mipmapBlur | Boolean | true | Enables or disables mipmap blur. |
50+
| intensity | Number | 1.0 | The bloom intensity. |
51+
| radius | Number | 0.85 | The blur radius. Only applies to mipmap blur. |
52+
| levels | Number | 8 | The amount of MIP levels. Only applies to mipmap blur. |
53+
| kernelSize | KernelSize | KernelSize.LARGE | The blur kernel size. Ignored if `mipmapBlur` is enabled. |
54+
| resolutionScale | Number | 0.5 | The render resolution scale. Ignored if `mipmapBlur` is enabled. |
55+
| resolutionX | Number | Resolution.AUTO_SIZE | The render width. Ignored if `mipmapBlur` is enabled. |
56+
| resolutionY | Number | Resolution.AUTO_SIZE | The render height. Ignored if `mipmapBlur` is enabled. |

0 commit comments

Comments
 (0)