[Bf-blender-cvs] [d60bbfdc187] temp-T96710-pbvh-pixels: Some documentation.

[Jeroen Bakker]

Commit: d60bbfdc1873bff904417ef7a02561c548a2c158
Author: Jeroen Bakker
Date:   Mon Apr 4 13:51:01 2022 +0200
Branches: temp-T96710-pbvh-pixels
https://developer.blender.org/rBd60bbfdc1873bff904417ef7a02561c548a2c158

Some documentation.

===================================================================

M	source/blender/blenkernel/BKE_pbvh.hh
M	source/blender/blenkernel/intern/pbvh_pixels.cc

===================================================================

diff --git a/source/blender/blenkernel/BKE_pbvh.hh b/source/blender/blenkernel/BKE_pbvh.hh
index 7927a057604..9deedc3ecb7 100644
--- a/source/blender/blenkernel/BKE_pbvh.hh
+++ b/source/blender/blenkernel/BKE_pbvh.hh
@@ -61,7 +61,7 @@ class BarycentricWeights {
  * Barycentric weights encoded into 2 floats.
  *
  * The third coordinate can be extracted as all 3 coordinates should sum up to 1.
- * 
+ *
  * \code{.cc}
  * co[2] = 1.0 - co[0] - co[1]
  * \endcode
@@ -118,10 +118,23 @@ struct TrianglePaintInput {
   }
 };
 
+/**
+ * Pixels of the same triangle share some data.
+ *
+ * Data is stored as a list of structs, grouped by usage to improve performance as it improves CPU
+ * cache prefetching.
+ *
+ */
 struct Triangles {
+  /** Paint input per triangle. */
   Vector<TrianglePaintInput> paint_input;
-  Vector<EncodedLoopIndices> loop_indices;
+  /** Polygon index per triangle. */
   Vector<int> poly_indices;
+  /**
+   * Loop indices per triangle.
+   * NOTE: is only available during building the triangles.
+   */
+  Vector<EncodedLoopIndices> loop_indices;
 
  public:
   void append(const Triangle &triangle)
@@ -135,6 +148,7 @@ struct Triangles {
   {
     return loop_indices[index].decode();
   }
+
   int get_poly_index(const int index)
   {
     return poly_indices[index];
diff --git a/source/blender/blenkernel/intern/pbvh_pixels.cc b/source/blender/blenkernel/intern/pbvh_pixels.cc
index a22cfb88f9a..f9b6ca84c5c 100644
--- a/source/blender/blenkernel/intern/pbvh_pixels.cc
+++ b/source/blender/blenkernel/intern/pbvh_pixels.cc
@@ -212,7 +212,12 @@ static bool should_pixels_be_updated(PBVHNode *node)
   return true;
 }
 
-static bool contains_triangles(PBVHNode *node)
+/**
+ * Does this the given node contains a list with owning polygons.
+ *
+ * The owning polygons are stored per triangle inside the node.
+ */
+static bool contains_polygons(PBVHNode *node)
 {
   if ((node->flag & PBVH_Leaf) == 0) {
     return false;
@@ -270,8 +275,9 @@ static bool find_nodes_to_update(PBVH *pbvh,
         node_data->clear_data();
       }
     }
-    else if (contains_triangles(node)) {
-      /* Mark polygons that are owned by other leafs, so they don't be added twice. */
+    else if (contains_polygons(node)) {
+      /* Mark polygons that are owned by other leafs, so they don't be added to new other PBVH_Leaf
+       * nodes. */
       Triangles &triangles = BKE_pbvh_pixels_triangles_get(*node);
       for (int &poly_index : triangles.poly_indices) {
         r_visited_polygons.tag_visited(poly_index);