|
1 | | - |
2 | | - |
3 | | -`use-shader-fx` is a library designed to easily implement shader effects such as fluid simulations and noise. It relies on [react-three-fiber](https://github.com/pmndrs/react-three-fiber) and has been designed with performance control in mind, especially when combined with [drei](https://github.com/pmndrs/drei). |
4 | | - |
5 | | -# Usage |
6 | | - |
7 | | -From each `fxHooks`, you can receive [`updateFx`, `setParams`, `fxObject`] in array format. The `config` is an object, which varies for each Hook, containing details such as `size` and `dpr`. |
8 | | - |
9 | | -1. `updateFx` - A function to be invoked inside `useFrame`, returning a `THREE.Texture`. |
10 | | -2. `setParams` - A function to refresh the parameters, beneficial for performance tweaking, etc. |
11 | | -3. `fxObject` - An object that holds various FX components, such as scene, camera, material, and renderTarget. |
12 | | - |
13 | | -```js |
14 | | -const [updateFx, setParams, fxObject] = useFruid(config); |
15 | | -``` |
16 | | - |
17 | | -Execute `updateFx` in `useFrame`. The first argument receives the RootState from `useFrame`, and the second one takes `HookPrams`. Each fx has its `HookPrams`, and each type is exported. |
18 | | - |
19 | | -```js |
20 | | -useFrame((props) => { |
21 | | - const texture = updateFx(props, params); |
22 | | - const main = mainShaderRef.current; |
23 | | - if (main) { |
24 | | - main.u_bufferTexture = texture; |
25 | | - } |
26 | | -}); |
27 | | -``` |
28 | | - |
29 | | -# Performance |
30 | | - |
31 | | -You can control the `dpr` using the `PerformanceMonitor` from [drei](https://github.com/pmndrs/drei). For more details, please refer to the [scaling-performance](https://docs.pmnd.rs/react-three-fiber/advanced/scaling-performance) of r3f. |
32 | | - |
33 | | -```js |
34 | | -export const Fx = () => { |
35 | | - const [dpr, setDpr] = useState(1.5); |
36 | | - return ( |
37 | | - <Canvas dpr={dpr}> |
38 | | - <PerformanceMonitor |
39 | | - factor={1} |
40 | | - onChange={({ factor }) => { |
41 | | - console.log(`dpr:${dpr}`); |
42 | | - setDpr(Math.round((0.5 + 1.5 * factor) * 10) / 10); |
43 | | - }}> |
44 | | - <Suspense fallback={null}> |
45 | | - <Scene /> |
46 | | - </Suspense> |
47 | | - <Perf position={"bottom-right"} minimal={false} /> |
48 | | - </PerformanceMonitor> |
49 | | - </Canvas> |
50 | | - ); |
51 | | -}; |
52 | | -``` |
53 | | - |
54 | | -By using the `PerformanceMonitor`, you can subscribe to performance changes with `usePerformanceMonitor`. For more details, refer to [drei](https://github.com/pmndrs/drei#performancemonitor). |
55 | | - |
56 | | -With `setParams` received from `fxHooks`, it's possible to independently control high-load items such as iteration counts. |
57 | | - |
58 | | -```js |
59 | | -usePerformanceMonitor({ |
60 | | - onChange({ factor }) { |
61 | | - setParams({ |
62 | | - pressure_iterations: Math.round(20 * factor), |
63 | | - }); |
64 | | - }, |
65 | | -}); |
66 | | -``` |
67 | | - |
68 | | -# How to make "custom fxHooks" |
69 | | - |
70 | | -With some functions provided by `use-shader-fx`, creating a custom hook is straightforward (the challenging part is only the shader!). Please refer to existing `fxHooks` for details. |
71 | | - |
72 | | -## useDoubleFBO |
73 | | - |
74 | | -Generates FBO and returns a double-buffered buffer texture after swapping. The `useFBO` of `drei` by default performs `setSize` for `THREE.WebGLRenderTarget` upon changes in `dpr` and `size`, making it challenging to handle buffer textures during changes like dpr adjustments. Therefore, a non-reactive hook against updates of dpr and size was created. It's possible to make them reactive individually through options. If you want to `setSize` at a custom timing, the `fxObject` that the fxHook receives as the third argument also stores `renderTarget`. |
75 | | - |
76 | | -```ts |
77 | | -type UseFboProps = { |
78 | | - scene: THREE.Scene; |
79 | | - camera: THREE.Camera; |
80 | | - size: Size; |
81 | | - /** If dpr is set, dpr will be multiplied, default:false */ |
82 | | - dpr?: number | false; |
83 | | - /** Whether to resize on resizes. If isDpr is true, set FBO to setSize even if dpr is changed, default:false */ |
84 | | - isSizeUpdate?: boolean; |
85 | | -}; |
86 | | - |
87 | | -const [velocityFBO, updateVelocityFBO] = useDoubleFBO(UseFboProps); |
88 | | -``` |
89 | | - |
90 | | -When you call the update function, it returns a double-buffered texture. The second argument gets a function called before `gl.render()`, allowing for operations like swapping materials or setting uniforms. |
91 | | - |
92 | | -```js |
93 | | -const texture = updateVelocityFBO(gl, ({ read, write }) => { |
94 | | - // callback before gl.render() |
95 | | - setMeshMaterial(materials.advectionMaterial); |
96 | | - setUniform(materials.advectionMaterial, "uVelocity", read); |
97 | | -}); |
98 | | -``` |
99 | | - |
100 | | -## useSingleFBO |
101 | | - |
102 | | -This is a version without double buffering. |
103 | | - |
104 | | -```js |
105 | | -const [renderTarget, updateRenderTarget] = useSingleFBO(UseFboProps); |
106 | | -``` |
107 | | - |
108 | | -## useCamera |
109 | | - |
110 | | -Generates and returns a `THREE.OrthographicCamera`. |
111 | | - |
112 | | -```js |
113 | | -const camera = useCamera(size); |
114 | | -``` |
115 | | - |
116 | | -## usePointer |
117 | | - |
118 | | -When given the `pointer` vector2 from r3f's `RootState`, it generates an update function that returns {currentPointer, prevPointer, diffPointer, isVelocityUpdate, velocity}. |
119 | | - |
120 | | -```js |
121 | | -const updatePointer = usePointer(); |
122 | | - |
123 | | -const { currentPointer, prevPointer, diffPointer, isVelocityUpdate, velocity } = |
124 | | - updatePointer(pointer); |
125 | | -``` |
126 | | - |
127 | | -## useResolution |
128 | | - |
129 | | -This hook returns `resolution`. If `dpr` isn't set (or set to false), dpr won't be multiplied. |
130 | | - |
131 | | -```ts |
132 | | -const resolution = useResolution(size: Size, dpr: number | false = false); |
133 | | -``` |
134 | | - |
135 | | -## useAddMesh |
136 | | - |
137 | | -Creates a mesh and adds it to scene, geometry, and material. Returns the mesh. |
138 | | - |
139 | | -```js |
140 | | -useAddMesh(scene, geometry, material); |
141 | | -``` |
142 | | - |
143 | | -## setUniform |
144 | | - |
145 | | -A function to set values in the uniforms of the shader material. |
146 | | - |
147 | | -```js |
148 | | -const setUniform = (material, key, value) => { |
149 | | - material.uniforms[key].value = value; |
150 | | -}; |
151 | | -``` |
152 | | - |
153 | | -## useParams |
154 | | - |
155 | | -Returns the refObject of params and its update function. |
156 | | - |
157 | | -```ts |
158 | | -const [params, setParams] = useParams<HooksParams>; |
159 | | -{ |
160 | | - // HookPrams |
161 | | -} |
162 | | -``` |
| 1 | +👉 [use-shader-fx](https://github.com/takuma-hmng8/use-shader-fx) 👈 |
0 commit comments