Browse Source

Docs: Better explain bounding volumes. (#27744)

* Docs: Better explain bounding volumes.

* Docs: Improve wording.

* Docs: Clean up.
Michael Herzog 1 year ago
parent
commit
08101a5483

+ 6 - 8
docs/api/en/core/BufferGeometry.html

@@ -231,18 +231,16 @@
 
 		<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>

+ 6 - 7
docs/api/en/objects/InstancedMesh.html

@@ -94,17 +94,16 @@
 
 		<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>

+ 6 - 10
docs/api/en/objects/SkinnedMesh.html

@@ -151,20 +151,16 @@
 
 		<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>

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

@@ -190,7 +190,6 @@ line.geometry.computeBoundingSphere();
 
 		</div>
 
-
 		<h2>Cameras</h2>
 		<div>
 			<p>A camera's position and target is updated automatically. If you need to change</p>
@@ -216,5 +215,35 @@ camera.aspect = window.innerWidth / window.innerHeight;
 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>