Skip to content

Commit 08101a5

Browse files
authored
Docs: Better explain bounding volumes. (#27744)
* Docs: Better explain bounding volumes. * Docs: Improve wording. * Docs: Clean up.
1 parent 35ad738 commit 08101a5

File tree

4 files changed

+48
-26
lines changed

4 files changed

+48
-26
lines changed

docs/api/en/core/BufferGeometry.html

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -231,18 +231,16 @@ <h3>[method:BufferGeometry clone]()</h3>
231231

232232
<h3>[method:undefined computeBoundingBox]()</h3>
233233
<p>
234-
Computes bounding box of the geometry, updating [page:.boundingBox]
235-
attribute.<br />
236-
Bounding boxes aren't computed by default. They need to be explicitly
237-
computed, otherwise they are `null`.
234+
Computes the bounding box of the geometry, and updates the [page:.boundingBox] attribute.
235+
The bounding box is not computed by the engine; it must be computed by your app.
236+
You may need to recompute the bounding box if the geometry vertices are modified.
238237
</p>
239238

240239
<h3>[method:undefined computeBoundingSphere]()</h3>
241240
<p>
242-
Computes bounding sphere of the geometry, updating [page:.boundingSphere]
243-
attribute.<br />
244-
Bounding spheres aren't computed by default. They need to be explicitly
245-
computed, otherwise they are `null`.
241+
Computes the bounding sphere of the geometry, and updates the [page:.boundingSphere] attribute.
242+
The engine automatically computes the bounding sphere when it is needed, e.g., for ray casting or view frustum culling.
243+
You may need to recompute the bounding sphere if the geometry vertices are modified.
246244
</p>
247245

248246
<h3>[method:undefined computeTangents]()</h3>

docs/api/en/objects/InstancedMesh.html

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -94,17 +94,16 @@ <h2>Methods</h2>
9494

9595
<h3>[method:undefined computeBoundingBox]()</h3>
9696
<p>
97-
Computes the bounding box, updating [page:.boundingBox] attribute.<br />
98-
Bounding boxes aren't computed by default. They need to be explicitly
99-
computed, otherwise they are `null`.
97+
Computes the bounding box of the instanced mesh, and updates the [page:.boundingBox] attribute.
98+
The bounding box is not computed by the engine; it must be computed by your app.
99+
You may need to recompute the bounding box if an instance is transformed via [page:.setMatrixAt]().
100100
</p>
101101

102102
<h3>[method:undefined computeBoundingSphere]()</h3>
103103
<p>
104-
Computes the bounding sphere, updating [page:.boundingSphere]
105-
attribute.<br />
106-
Bounding spheres aren't computed by default. They need to be explicitly
107-
computed, otherwise they are `null`.
104+
Computes the bounding sphere of the instanced mesh, and updates the [page:.boundingSphere] attribute.
105+
The engine automatically computes the bounding sphere when it is needed, e.g., for ray casting or view frustum culling.
106+
You may need to recompute the bounding sphere if an instance is transformed via [page:.setMatrixAt]().
108107
</p>
109108

110109
<h3>[method:undefined dispose]()</h3>

docs/api/en/objects/SkinnedMesh.html

Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -151,20 +151,16 @@ <h3>[method:SkinnedMesh clone]()</h3>
151151

152152
<h3>[method:undefined computeBoundingBox]()</h3>
153153
<p>
154-
Computes the bounding box, updating [page:.boundingBox] attribute.<br />
155-
Bounding boxes aren't computed by default. They need to be explicitly
156-
computed, otherwise they are `null`. If an instance of [name] is animated,
157-
this method should be called per frame to compute a correct bounding box.
154+
Computes the bounding box of the skinned mesh, and updates the [page:.boundingBox] attribute.
155+
The bounding box is not computed by the engine; it must be computed by your app.
156+
If the skinned mesh is animated, the bounding box should be recomputed per frame.
158157
</p>
159158

160159
<h3>[method:undefined computeBoundingSphere]()</h3>
161160
<p>
162-
Computes the bounding sphere, updating [page:.boundingSphere]
163-
attribute.<br />
164-
Bounding spheres aren't computed by default. They need to be explicitly
165-
computed, otherwise they are `null`. If an instance of [name] is animated,
166-
this method should be called per frame to compute a correct bounding
167-
sphere.
161+
Computes the bounding sphere of the skinned mesh, and updates the [page:.boundingSphere] attribute.
162+
The bounding sphere is automatically computed by the engine when it is needed, e.g., for ray casting and view frustum culling.
163+
If the skinned mesh is animated, the bounding sphere should be recomputed per frame.
168164
</p>
169165

170166
<h3>[method:undefined normalizeSkinWeights]()</h3>

docs/manual/en/introduction/How-to-update-things.html

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -190,7 +190,6 @@ <h3>Examples</h3>
190190

191191
</div>
192192

193-
194193
<h2>Cameras</h2>
195194
<div>
196195
<p>A camera's position and target is updated automatically. If you need to change</p>
@@ -216,5 +215,35 @@ <h2>Cameras</h2>
216215
camera.updateProjectionMatrix();
217216
</code>
218217
</div>
218+
219+
<h2>InstancedMesh</h2>
220+
<div>
221+
<p>
222+
`InstancedMesh` is a class for conveniently access instanced rendering in `three.js`. Certain library features like view frustum culling or
223+
ray casting rely on up-to-date bounding volumes (bounding sphere and bounding box). Because of the way how `InstancedMesh` works, the class
224+
has its own [page:InstancedMesh.boundingBox boundingBox] and [page:InstancedMesh.boundingSphere boundingSphere] properties that supersede
225+
the bounding volumes on geometry level.
226+
</p>
227+
<p>
228+
Similar to geometries you have to recompute the bounding box and sphere whenever you change the underlying data. In context of `InstancedMesh`, that
229+
happens when you transform instances via [page:InstancedMesh.setMatrixAt setMatrixAt](). You can use the same pattern like with geometries.
230+
</p>
231+
<code>
232+
instancedMesh.computeBoundingBox();
233+
instancedMesh.computeBoundingSphere();
234+
</code>
235+
236+
</div>
237+
238+
<h2>SkinnedMesh</h2>
239+
<div>
240+
<p>
241+
`SkinnedMesh` follows the same principles like `InstancedMesh` in context of bounding volumes. Meaning the class has its own version of
242+
[page:SkinnedMesh.boundingBox boundingBox] and [page:SkinnedMesh.boundingSphere boundingSphere] to correctly enclose animated meshes.
243+
When calling `computeBoundingBox()` and `computeBoundingSphere()`, the class computes the respective bounding volumes based on the current
244+
bone tranformation (or in other words the current animation state).
245+
</p>
246+
</div>
247+
219248
</body>
220249
</html>

0 commit comments

Comments
 (0)