Docs: Better explain bounding volumes.

[Mugen87]

Related issue: #27735

Description

This is a new attempt to better explain the bounding volumes in BufferGeometry, InstancedMesh and SkinnedMesh.

[WestLangley]

@Mugen87 Thanks for having a go at this. Here is my proposal based on your initial version. Feel free to edit this post if you feel it is warranted, and I will have a second look.

I think it should be clear how difficult it is to make precise statements in these descriptions, and why a more-lengthy tutorial is more appropriate for this kind of information.

I'm thinking I'd prefer to simply describe what each method does and add something like: See "How To Update Things" for important info on when to call this method. "How To Update Things" could then be fully-detailed.

But either approach is fine with me, if you feel strongly about one or the other.

//

BufferGeometry

.computeBoundingBox()

Computes the bounding box of the geometry, and updates the .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.

.computeBoundingSphere()

Computes the bounding sphere of the geometry, and updates the .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.

InstancedMesh

.computeBoundingBox()

Computes the bounding box of the geometry, and updates the .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 .setMatrixAt().

.computeBoundingSphere()

Computes the bounding sphere of the geometry, and updates the .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 .setMatrixAt().

SkinnedMesh

.computeBoundingBox()

Computes the bounding box of the geometry, and updates the .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.

.computeBoundingSphere()

Computes the bounding sphere of the geometry, and updates the .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.

How-to-update-things

TODO

[Mugen87]

I like the new wording very much so I've replaced the previous descriptions with the new ones.