From 1b6bc2c2403d51e29214a375ec9974008dfb9c62 Mon Sep 17 00:00:00 2001
From: Kxie <56177821+ua-kxie@users.noreply.github.com>
Date: Tue, 4 Jun 2024 07:46:31 +0800
Subject: [PATCH] document need to update Aabb in Mesh::(with_)insert_attribute
 (#13349)

# Objective

solves #12475 for functions `Mesh::insert_attribute` and
`Mesh::with_inserted_attribute`.

## Solution

added references to Aabb and suggest solutions in doc strings

## Testing

ran cargo docs, links work.

---------

Co-authored-by: BD103 <59022059+BD103@users.noreply.github.com>
---
 crates/bevy_render/src/mesh/mesh/mod.rs | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/crates/bevy_render/src/mesh/mesh/mod.rs b/crates/bevy_render/src/mesh/mesh/mod.rs
index c94bc10c5a..a02d8a64f2 100644
--- a/crates/bevy_render/src/mesh/mesh/mod.rs
+++ b/crates/bevy_render/src/mesh/mesh/mod.rs
@@ -104,6 +104,9 @@ pub const VERTEX_ATTRIBUTE_BUFFER_ID: u64 = 10;
 /// - It is possible and sometimes useful for multiple vertices to have the same
 /// [position attribute](Mesh::ATTRIBUTE_POSITION) value,
 /// it's a common technique in 3D modelling for complex UV mapping or other calculations.
+/// - Bevy performs frustum culling based on the [`Aabb`] of meshes, which is calculated
+/// and added automatically for new meshes only. If a mesh is modified, the entity's [`Aabb`]
+/// needs to be updated manually or deleted so that it is re-calculated.
 ///
 /// ## Use with `StandardMaterial`
 ///
@@ -225,6 +228,8 @@ impl Mesh {
     /// Sets the data for a vertex attribute (position, normal, etc.). The name will
     /// often be one of the associated constants such as [`Mesh::ATTRIBUTE_POSITION`].
     ///
+    /// [`Aabb`] of entities with modified mesh are not updated automatically.
+    ///
     /// # Panics
     /// Panics when the format of the values does not match the attribute's format.
     #[inline]
@@ -251,6 +256,8 @@ impl Mesh {
     ///
     /// (Alternatively, you can use [`Mesh::insert_attribute`] to mutate an existing mesh in-place)
     ///
+    /// [`Aabb`] of entities with modified mesh are not updated automatically.
+    ///
     /// # Panics
     /// Panics when the format of the values does not match the attribute's format.
     #[must_use]
@@ -727,6 +734,8 @@ impl Mesh {
     ///
     /// Note that attributes of `other` that don't exist on `self` will be ignored.
     ///
+    /// [`Aabb`] of entities with modified mesh are not updated automatically.
+    ///
     /// # Panics
     ///
     /// Panics if the vertex attribute values of `other` are incompatible with `self`.
@@ -803,12 +812,16 @@ impl Mesh {
     }
 
     /// Transforms the vertex positions, normals, and tangents of the mesh by the given [`Transform`].
+    ///
+    /// [`Aabb`] of entities with modified mesh are not updated automatically.
     pub fn transformed_by(mut self, transform: Transform) -> Self {
         self.transform_by(transform);
         self
     }
 
     /// Transforms the vertex positions, normals, and tangents of the mesh in place by the given [`Transform`].
+    ///
+    /// [`Aabb`] of entities with modified mesh are not updated automatically.
     pub fn transform_by(&mut self, transform: Transform) {
         // Needed when transforming normals and tangents
         let scale_recip = 1. / transform.scale;
@@ -857,12 +870,16 @@ impl Mesh {
     }
 
     /// Translates the vertex positions of the mesh by the given [`Vec3`].
+    ///
+    /// [`Aabb`] of entities with modified mesh are not updated automatically.
     pub fn translated_by(mut self, translation: Vec3) -> Self {
         self.translate_by(translation);
         self
     }
 
     /// Translates the vertex positions of the mesh in place by the given [`Vec3`].
+    ///
+    /// [`Aabb`] of entities with modified mesh are not updated automatically.
     pub fn translate_by(&mut self, translation: Vec3) {
         if translation == Vec3::ZERO {
             return;
@@ -879,12 +896,16 @@ impl Mesh {
     }
 
     /// Rotates the vertex positions, normals, and tangents of the mesh by the given [`Quat`].
+    ///
+    /// [`Aabb`] of entities with modified mesh are not updated automatically.
     pub fn rotated_by(mut self, rotation: Quat) -> Self {
         self.rotate_by(rotation);
         self
     }
 
     /// Rotates the vertex positions, normals, and tangents of the mesh in place by the given [`Quat`].
+    ///
+    /// [`Aabb`] of entities with modified mesh are not updated automatically.
     pub fn rotate_by(&mut self, rotation: Quat) {
         if let Some(VertexAttributeValues::Float32x3(ref mut positions)) =
             self.attribute_mut(Mesh::ATTRIBUTE_POSITION)
@@ -920,12 +941,16 @@ impl Mesh {
     }
 
     /// Scales the vertex positions, normals, and tangents of the mesh by the given [`Vec3`].
+    ///
+    /// [`Aabb`] of entities with modified mesh are not updated automatically.
     pub fn scaled_by(mut self, scale: Vec3) -> Self {
         self.scale_by(scale);
         self
     }
 
     /// Scales the vertex positions, normals, and tangents of the mesh in place by the given [`Vec3`].
+    ///
+    /// [`Aabb`] of entities with modified mesh are not updated automatically.
     pub fn scale_by(&mut self, scale: Vec3) {
         // Needed when transforming normals and tangents
         let scale_recip = 1. / scale;