Skip to content

Commit 47d30ba

Browse files
committed
chore: Move ShaderMaterial uniform notes to objects out of pitfalls
1 parent ece1a3f commit 47d30ba

2 files changed

Lines changed: 44 additions & 44 deletions

File tree

docs/API/objects.mdx

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -208,3 +208,47 @@ function Mesh() {
208208
<group dispose={null}>
209209
<mesh geometry={globalGeometry} material={globalMaterial} />
210210
```
211+
212+
## Shader material uniforms
213+
214+
`ShaderMaterial`, `RawShaderMaterial` and subclasses keep the material's [`uniforms` object](https://threejs.org/docs/#ShaderMaterial.uniforms) stable. When you pass a new `uniforms` object, React Three Fiber merges the incoming uniforms into the existing target instead of replacing it.
215+
216+
This preserves three.js internal uniform caching, even if your component creates a fresh `uniforms` object on each render. Existing uniform entries are updated in place and new entries are added as needed.
217+
218+
```jsx
219+
<shaderMaterial
220+
uniforms={{
221+
time: { value: time },
222+
color: { value: color },
223+
}}
224+
/>
225+
```
226+
227+
To get a stable reference to the material's `uniforms`, use the React ref.
228+
229+
```jsx
230+
function Component() {
231+
const ref = useRef()
232+
233+
// This object is merged into the material, so mutating this reference
234+
// later will not update the shader.
235+
const uniforms = useMemo(
236+
() => ({
237+
time: { value: 0 },
238+
color: { value: color },
239+
}),
240+
[color],
241+
)
242+
243+
useFrame(({ clock }) => {
244+
// The material ref's uniforms object is stable and should be mutated instead.
245+
ref.current.uniforms.time.value = clock.elapsedTime
246+
})
247+
248+
return (
249+
<mesh>
250+
<shaderMaterial ref={ref} uniforms={uniforms} />
251+
</mesh>
252+
)
253+
}
254+
```

docs/advanced/pitfalls.mdx

Lines changed: 0 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -213,50 +213,6 @@ function Foo(props)
213213
})
214214
```
215215
216-
## Shader material uniforms
217-
218-
`ShaderMaterial`, `RawShaderMaterial` and subclasses keep the material's [`uniforms` object](https://threejs.org/docs/#ShaderMaterial.uniforms) stable. When you pass a new `uniforms` object, React Three Fiber merges the incoming uniforms into the existing target instead of replacing it.
219-
220-
This preserves three.js internal uniform caching, even if your component creates a fresh `uniforms` object on each render. Existing uniform entries are updated in place and new entries are added as needed.
221-
222-
```jsx
223-
<shaderMaterial
224-
uniforms={{
225-
time: { value: time },
226-
color: { value: color },
227-
}}
228-
/>
229-
```
230-
231-
To get a stable reference to the material's `uniforms`, use the React ref.
232-
233-
```jsx
234-
function Component() {
235-
const ref = useRef()
236-
237-
// This object is merged into the material, so mutating this reference
238-
// later will not update the shader.
239-
const uniforms = useMemo(
240-
() => ({
241-
time: { value: 0 },
242-
color: { value: color },
243-
}),
244-
[color],
245-
)
246-
247-
useFrame(({ clock }) => {
248-
// The material ref's uniforms object is stable and should be mutated instead.
249-
ref.current.uniforms.time.value = clock.elapsedTime
250-
})
251-
252-
return (
253-
<mesh>
254-
<shaderMaterial ref={ref} uniforms={uniforms} />
255-
</mesh>
256-
)
257-
}
258-
```
259-
260216
## `useLoader` instead of plain loaders
261217
262218
Threejs loaders give you the ability to load async assets (models, textures, etc), but if you do not re-use assets it can quickly become problematic.

0 commit comments

Comments
 (0)