Skip to content

Commit

Permalink
Docs: Better explain bounding volumes. (#27744)
Browse files Browse the repository at this point in the history
* Docs: Better explain bounding volumes.

* Docs: Improve wording.

* Docs: Clean up.
  • Loading branch information
Mugen87 committed Feb 15, 2024
1 parent 35ad738 commit 08101a5
Show file tree
Hide file tree
Showing 4 changed files with 48 additions and 26 deletions.
14 changes: 6 additions & 8 deletions docs/api/en/core/BufferGeometry.html
Original file line number Diff line number Diff line change
Expand Up @@ -231,18 +231,16 @@ <h3>[method:BufferGeometry clone]()</h3>

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

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

<h3>[method:undefined computeTangents]()</h3>
Expand Down
13 changes: 6 additions & 7 deletions docs/api/en/objects/InstancedMesh.html
Original file line number Diff line number Diff line change
Expand Up @@ -94,17 +94,16 @@ <h2>Methods</h2>

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

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

<h3>[method:undefined dispose]()</h3>
Expand Down
16 changes: 6 additions & 10 deletions docs/api/en/objects/SkinnedMesh.html
Original file line number Diff line number Diff line change
Expand Up @@ -151,20 +151,16 @@ <h3>[method:SkinnedMesh clone]()</h3>

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

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

<h3>[method:undefined normalizeSkinWeights]()</h3>
Expand Down
31 changes: 30 additions & 1 deletion docs/manual/en/introduction/How-to-update-things.html
Original file line number Diff line number Diff line change
Expand Up @@ -190,7 +190,6 @@ <h3>Examples</h3>

</div>


<h2>Cameras</h2>
<div>
<p>A camera's position and target is updated automatically. If you need to change</p>
Expand All @@ -216,5 +215,35 @@ <h2>Cameras</h2>
camera.updateProjectionMatrix();
</code>
</div>

<h2>InstancedMesh</h2>
<div>
<p>
`InstancedMesh` is a class for conveniently access instanced rendering in `three.js`. Certain library features like view frustum culling or
ray casting rely on up-to-date bounding volumes (bounding sphere and bounding box). Because of the way how `InstancedMesh` works, the class
has its own [page:InstancedMesh.boundingBox boundingBox] and [page:InstancedMesh.boundingSphere boundingSphere] properties that supersede
the bounding volumes on geometry level.
</p>
<p>
Similar to geometries you have to recompute the bounding box and sphere whenever you change the underlying data. In context of `InstancedMesh`, that
happens when you transform instances via [page:InstancedMesh.setMatrixAt setMatrixAt](). You can use the same pattern like with geometries.
</p>
<code>
instancedMesh.computeBoundingBox();
instancedMesh.computeBoundingSphere();
</code>

</div>

<h2>SkinnedMesh</h2>
<div>
<p>
`SkinnedMesh` follows the same principles like `InstancedMesh` in context of bounding volumes. Meaning the class has its own version of
[page:SkinnedMesh.boundingBox boundingBox] and [page:SkinnedMesh.boundingSphere boundingSphere] to correctly enclose animated meshes.
When calling `computeBoundingBox()` and `computeBoundingSphere()`, the class computes the respective bounding volumes based on the current
bone tranformation (or in other words the current animation state).
</p>
</div>

</body>
</html>

0 comments on commit 08101a5

Please sign in to comment.