Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Better explain bounding volumes. #27744

Merged
merged 3 commits into from
Feb 15, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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>