From 9a449de3388e77482f3f4e21fc0fa2eb0652e255 Mon Sep 17 00:00:00 2001
From: Nathan Bierema <nbierema@gmail.com>
Date: Thu, 22 Feb 2024 10:00:42 -0500
Subject: [PATCH] Docs: Better explain bounding volumes. (#832)

---
 types/three/src/core/BufferGeometry.d.ts   | 10 ++++++----
 types/three/src/objects/InstancedMesh.d.ts | 10 ++++++----
 types/three/src/objects/SkinnedMesh.d.ts   | 15 ++++++---------
 3 files changed, 18 insertions(+), 17 deletions(-)

diff --git a/types/three/src/core/BufferGeometry.d.ts b/types/three/src/core/BufferGeometry.d.ts
index 3632cfbdb..21e2170c2 100644
--- a/types/three/src/core/BufferGeometry.d.ts
+++ b/types/three/src/core/BufferGeometry.d.ts
@@ -333,14 +333,16 @@ export class BufferGeometry<
     setFromPoints(points: Vector3[] | Vector2[]): this;
 
     /**
-     * Computes bounding box of the geometry, updating {@link boundingBox | .boundingBox} attribute.
-     * @remarks 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 {@link .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.
      */
     computeBoundingBox(): void;
 
     /**
-     * Computes bounding sphere of the geometry, updating {@link boundingSphere | .boundingSphere} attribute.
-     * @remarks 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 {@link .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.
      */
     computeBoundingSphere(): void;
 
diff --git a/types/three/src/objects/InstancedMesh.d.ts b/types/three/src/objects/InstancedMesh.d.ts
index 7ac790434..84acece1f 100644
--- a/types/three/src/objects/InstancedMesh.d.ts
+++ b/types/three/src/objects/InstancedMesh.d.ts
@@ -90,14 +90,16 @@ export class InstancedMesh<
     morphTexture: DataTexture | null;
 
     /**
-     * Computes bounding box of the all instances, updating {@link boundingBox | .boundingBox} attribute.
-     * @remarks 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 {@link .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 {@link .setMatrixAt()}.
      */
     computeBoundingBox(): void;
 
     /**
-     * Computes bounding sphere of the all instances, updating {@link boundingSphere | .boundingSphere} attribute.
-     * @remarks 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 {@link .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]().
      */
     computeBoundingSphere(): void;
 
diff --git a/types/three/src/objects/SkinnedMesh.d.ts b/types/three/src/objects/SkinnedMesh.d.ts
index 8e0288a72..a0476c75a 100644
--- a/types/three/src/objects/SkinnedMesh.d.ts
+++ b/types/three/src/objects/SkinnedMesh.d.ts
@@ -117,19 +117,16 @@ export class SkinnedMesh<
     bind(skeleton: Skeleton, bindMatrix?: Matrix4): void;
 
     /**
-     * Computes the bounding box, updating {@link boundingBox | .boundingBox} attribute.
-     * @remarks
-     * Bounding boxes aren't computed by default. They need to be explicitly computed, otherwise they are `null`. If an
-     * instance of SkinnedMesh 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 {@link .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.
      */
     computeBoundingBox(): void;
 
     /**
-     * Computes the bounding sphere, updating {@link boundingSphere | .boundingSphere} attribute.
-     * @remarks
-     * Bounding spheres aren't computed by default. They need to be explicitly computed, otherwise they are `null`. If
-     * an instance of SkinnedMesh 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 {@link .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.
      */
     computeBoundingSphere(): void;