From d56bd4b9c3bda11d14f226a588dca9d8705b8706 Mon Sep 17 00:00:00 2001 From: Mugen87 Date: Wed, 14 Feb 2024 10:36:37 +0100 Subject: [PATCH 1/3] Docs: Better explain bounding volumes. --- docs/api/en/core/BufferGeometry.html | 16 +++++----- docs/api/en/objects/InstancedMesh.html | 13 ++++---- docs/api/en/objects/SkinnedMesh.html | 10 +++--- .../en/introduction/How-to-update-things.html | 31 ++++++++++++++++++- 4 files changed, 49 insertions(+), 21 deletions(-) diff --git a/docs/api/en/core/BufferGeometry.html b/docs/api/en/core/BufferGeometry.html index 43630ef3bf4acb..59b5a808992938 100644 --- a/docs/api/en/core/BufferGeometry.html +++ b/docs/api/en/core/BufferGeometry.html @@ -231,18 +231,18 @@

[method:BufferGeometry clone]()

[method:undefined computeBoundingBox]()

- Computes bounding box of the geometry, updating [page:.boundingBox] - attribute.
- Bounding boxes aren't computed by default. They need to be explicitly - computed, otherwise they are `null`. + Computes bounding box of the geometry, updating [page:.boundingBox] attribute.
+ Bounding boxes aren't computed by default. They need to be explicitly computed, otherwise they are `null`. + Once computed, it's the responsibility of the app to recompute the bounding box with this method when + vertices are transformed.

[method:undefined computeBoundingSphere]()

- Computes bounding sphere of the geometry, updating [page:.boundingSphere] - attribute.
- Bounding spheres aren't computed by default. They need to be explicitly - computed, otherwise they are `null`. + Computes bounding sphere of the geometry, updating [page:.boundingSphere] attribute.
+ Bounding spheres are computed by the engine once when they are internally required + e.g. for ray casting or view frustum culling. It's the responsibility of the app to recompute + the bounding sphere with this method when vertices are transformed.

[method:undefined computeTangents]()

diff --git a/docs/api/en/objects/InstancedMesh.html b/docs/api/en/objects/InstancedMesh.html index c880c77a90b2a8..cec06e95496461 100644 --- a/docs/api/en/objects/InstancedMesh.html +++ b/docs/api/en/objects/InstancedMesh.html @@ -95,16 +95,17 @@

Methods

[method:undefined computeBoundingBox]()

Computes the bounding box, updating [page:.boundingBox] attribute.
- Bounding boxes aren't computed by default. They need to be explicitly - computed, otherwise they are `null`. + Bounding boxes aren't computed by default. They need to be explicitly computed, + otherwise they are `null`. Once computed, it's the responsibility of the app to recompute the + bounding box with this method when instances are transformed via [page:.setMatrixAt]().

[method:undefined computeBoundingSphere]()

- Computes the bounding sphere, updating [page:.boundingSphere] - attribute.
- Bounding spheres aren't computed by default. They need to be explicitly - computed, otherwise they are `null`. + Computes the bounding sphere, updating [page:.boundingSphere] attribute.
+ Bounding spheres are computed by the engine once when they are internally required e.g. for + ray casting or view frustum culling. It's the responsibility of the app to recompute + the bounding sphere with this method when instances are transformed via [page:.setMatrixAt]().

[method:undefined dispose]()

diff --git a/docs/api/en/objects/SkinnedMesh.html b/docs/api/en/objects/SkinnedMesh.html index f9ed6d4c229230..4c9c1e5f931c7e 100644 --- a/docs/api/en/objects/SkinnedMesh.html +++ b/docs/api/en/objects/SkinnedMesh.html @@ -159,12 +159,10 @@

[method:undefined computeBoundingBox]()

[method:undefined computeBoundingSphere]()

- Computes the bounding sphere, updating [page:.boundingSphere] - attribute.
- 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, updating [page:.boundingSphere] attribute.
+ Bounding spheres are computed by the engine once when they are internally required + e.g. for ray casting or view frustum culling. If an instance of [name] is animated, + this method should be called per frame to compute a correct bounding sphere.

[method:undefined normalizeSkinWeights]()

diff --git a/docs/manual/en/introduction/How-to-update-things.html b/docs/manual/en/introduction/How-to-update-things.html index 69bbd04d999903..7a28ac5bcfd17f 100644 --- a/docs/manual/en/introduction/How-to-update-things.html +++ b/docs/manual/en/introduction/How-to-update-things.html @@ -190,7 +190,6 @@

Examples

-

Cameras

A camera's position and target is updated automatically. If you need to change

@@ -216,5 +215,35 @@

Cameras

camera.updateProjectionMatrix();
+ +

InstancedMesh

+
+

+ `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. +

+

+ 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. +

+ +instancedMesh.computeBoundingBox(); +instancedMesh.computeBoundingSphere(); + + +
+ +

SkinnedMesh

+
+

+ `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). +

+
+ From 7cb61be578211b791d1598c4277a6879a84d01fb Mon Sep 17 00:00:00 2001 From: Mugen87 Date: Thu, 15 Feb 2024 10:20:06 +0100 Subject: [PATCH 2/3] Docs: Improve wording. --- docs/api/en/core/BufferGeometry.html | 14 ++++++-------- docs/api/en/objects/InstancedMesh.html | 14 ++++++-------- docs/api/en/objects/SkinnedMesh.html | 14 ++++++-------- 3 files changed, 18 insertions(+), 24 deletions(-) diff --git a/docs/api/en/core/BufferGeometry.html b/docs/api/en/core/BufferGeometry.html index 59b5a808992938..477af4a6c75762 100644 --- a/docs/api/en/core/BufferGeometry.html +++ b/docs/api/en/core/BufferGeometry.html @@ -231,18 +231,16 @@

[method:BufferGeometry clone]()

[method:undefined computeBoundingBox]()

- Computes bounding box of the geometry, updating [page:.boundingBox] attribute.
- Bounding boxes aren't computed by default. They need to be explicitly computed, otherwise they are `null`. - Once computed, it's the responsibility of the app to recompute the bounding box with this method when - vertices are transformed. + 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.

[method:undefined computeBoundingSphere]()

- Computes bounding sphere of the geometry, updating [page:.boundingSphere] attribute.
- Bounding spheres are computed by the engine once when they are internally required - e.g. for ray casting or view frustum culling. It's the responsibility of the app to recompute - the bounding sphere with this method when vertices are transformed. + 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.

[method:undefined computeTangents]()

diff --git a/docs/api/en/objects/InstancedMesh.html b/docs/api/en/objects/InstancedMesh.html index cec06e95496461..58220fa6cd3aba 100644 --- a/docs/api/en/objects/InstancedMesh.html +++ b/docs/api/en/objects/InstancedMesh.html @@ -94,18 +94,16 @@

Methods

[method:undefined computeBoundingBox]()

- Computes the bounding box, updating [page:.boundingBox] attribute.
- Bounding boxes aren't computed by default. They need to be explicitly computed, - otherwise they are `null`. Once computed, it's the responsibility of the app to recompute the - bounding box with this method when instances are transformed via [page:.setMatrixAt](). + 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 an instance is transformed via [page:.setMatrixAt]().

[method:undefined computeBoundingSphere]()

- Computes the bounding sphere, updating [page:.boundingSphere] attribute.
- Bounding spheres are computed by the engine once when they are internally required e.g. for - ray casting or view frustum culling. It's the responsibility of the app to recompute - the bounding sphere with this method when instances are transformed via [page:.setMatrixAt](). + 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 an instance is transformed via [page:.setMatrixAt]().

[method:undefined dispose]()

diff --git a/docs/api/en/objects/SkinnedMesh.html b/docs/api/en/objects/SkinnedMesh.html index 4c9c1e5f931c7e..4ae2cb9e4a9a1b 100644 --- a/docs/api/en/objects/SkinnedMesh.html +++ b/docs/api/en/objects/SkinnedMesh.html @@ -151,18 +151,16 @@

[method:SkinnedMesh clone]()

[method:undefined computeBoundingBox]()

- Computes the bounding box, updating [page:.boundingBox] attribute.
- 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 geometry, 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.

[method:undefined computeBoundingSphere]()

- Computes the bounding sphere, updating [page:.boundingSphere] attribute.
- Bounding spheres are computed by the engine once when they are internally required - e.g. for ray casting or view frustum culling. 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 geometry, 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.

[method:undefined normalizeSkinWeights]()

From 342895a814f16889dd8965a39c9e74ee2bebb49d Mon Sep 17 00:00:00 2001 From: Mugen87 Date: Thu, 15 Feb 2024 10:28:59 +0100 Subject: [PATCH 3/3] Docs: Clean up. --- docs/api/en/objects/InstancedMesh.html | 4 ++-- docs/api/en/objects/SkinnedMesh.html | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/api/en/objects/InstancedMesh.html b/docs/api/en/objects/InstancedMesh.html index 58220fa6cd3aba..c3fb76db5faa5a 100644 --- a/docs/api/en/objects/InstancedMesh.html +++ b/docs/api/en/objects/InstancedMesh.html @@ -94,14 +94,14 @@

Methods

[method:undefined computeBoundingBox]()

- Computes the bounding box of the geometry, and updates the [page:.boundingBox] attribute. + 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]().

[method:undefined computeBoundingSphere]()

- Computes the bounding sphere of the geometry, and updates the [page:.boundingSphere] attribute. + 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]().

diff --git a/docs/api/en/objects/SkinnedMesh.html b/docs/api/en/objects/SkinnedMesh.html index 4ae2cb9e4a9a1b..02c5f2f9cec8f4 100644 --- a/docs/api/en/objects/SkinnedMesh.html +++ b/docs/api/en/objects/SkinnedMesh.html @@ -151,14 +151,14 @@

[method:SkinnedMesh clone]()

[method:undefined computeBoundingBox]()

- Computes the bounding box of the geometry, and updates the [page:.boundingBox] attribute. + 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.

[method:undefined computeBoundingSphere]()

- Computes the bounding sphere of the geometry, and updates the [page:.boundingSphere] attribute. + 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.