Subdiv: Extend some comments

5 files changed, 23 insertions, 1 deletions

diff --git a/source/blender/blenkernel/BKE_subdiv_ccg.h b/source/blender/blenkernel/BKE_subdiv_ccg.h
index 7d612f293ab..f8534371b17 100644
--- a/source/blender/blenkernel/BKE_subdiv_ccg.h
+++ b/source/blender/blenkernel/BKE_subdiv_ccg.h
@@ -216,7 +216,10 @@ typedef struct SubdivCCG {
   } dirty;
 } SubdivCCG;
 
-/* Create real hi-res CCG from subdivision.
+/* Create CCG representation of subdivision surface.
+ *
+ * NOTE: CCG stores dense verticies in a grid-like storage. There is no edges or
+ * polygons informations for the high-poly surface.
  *
  * NOTE: Subdiv is expected to be refined and ready for evaluation.
  * NOTE: CCG becomes an owner of subdiv.
diff --git a/source/blender/blenkernel/BKE_subdiv_deform.h b/source/blender/blenkernel/BKE_subdiv_deform.h
index 72d2b252cf7..11ef225de27 100644
--- a/source/blender/blenkernel/BKE_subdiv_deform.h
+++ b/source/blender/blenkernel/BKE_subdiv_deform.h
@@ -34,6 +34,10 @@ struct Mesh;
 struct Subdiv;
 
 /* Special version of subdivision surface which calculates final positions for coarse vertices.
+ * Effectively is pushsing the coarse positions to the limit surface.
+ *
+ * One of the usage examples is calculation of crazy space of subdivision modifier, allowing to
+ * paint on a deformed mesh with subsurf on it.
  *
  * vertex_cos are supposed to hold coordinates of the coarse mesh. */
 void BKE_subdiv_deform_coarse_vertices(struct Subdiv *subdiv,
diff --git a/source/blender/blenkernel/BKE_subdiv_eval.h b/source/blender/blenkernel/BKE_subdiv_eval.h
index 095d3c17d63..3f682716928 100644
--- a/source/blender/blenkernel/BKE_subdiv_eval.h
+++ b/source/blender/blenkernel/BKE_subdiv_eval.h
@@ -50,6 +50,8 @@ void BKE_subdiv_eval_init_displacement(struct Subdiv *subdiv);
 
 /* Single point queries. */
 
+/* Evaluate point at a limit surface, with optional derivatives and normal. */
+
 void BKE_subdiv_eval_limit_point(
     struct Subdiv *subdiv, const int ptex_face_index, const float u, const float v, float r_P[3]);
 void BKE_subdiv_eval_limit_point_and_derivatives(struct Subdiv *subdiv,
@@ -72,6 +74,7 @@ void BKE_subdiv_eval_limit_point_and_short_normal(struct Subdiv *subdiv,
                                                   float r_P[3],
                                                   short r_N[3]);
 
+/* Evaluate face-varying layer (such as UV). */
 void BKE_subdiv_eval_face_varying(struct Subdiv *subdiv,
                                   const int face_varying_channel,
                                   const int ptex_face_index,
@@ -93,6 +96,7 @@ void BKE_subdiv_eval_displacement(struct Subdiv *subdiv,
                                   const float dPdv[3],
                                   float r_D[3]);
 
+/* Evaluate point on a limit surface with displacement applied to it. */
 void BKE_subdiv_eval_final_point(
     struct Subdiv *subdiv, const int ptex_face_index, const float u, const float v, float r_P[3]);
 
diff --git a/source/blender/blenkernel/BKE_subdiv_foreach.h b/source/blender/blenkernel/BKE_subdiv_foreach.h
index f1d4adda37c..bef141b5ac5 100644
--- a/source/blender/blenkernel/BKE_subdiv_foreach.h
+++ b/source/blender/blenkernel/BKE_subdiv_foreach.h
@@ -160,6 +160,10 @@ typedef struct SubdivForeachContext {
 /* Invokes callbacks in the order and with values which corresponds to creation
  * of final subdivided mesh.
  *
+ * Main goal is to abstract all the traversal routines to give geometry element
+ * indices (for vertices, edges, loops, polygons) in the same way as subdivision
+ * modifier will do for a dense mesh.
+ *
  * Returns truth if the whole topology was traversed, without any early exits.
  *
  * TODO(sergey): Need to either get rid of subdiv or of coarse_mesh.
diff --git a/source/blender/blenkernel/intern/subdiv_foreach.c b/source/blender/blenkernel/intern/subdiv_foreach.c
index 533279f4425..6e39f9f302b 100644
--- a/source/blender/blenkernel/intern/subdiv_foreach.c
+++ b/source/blender/blenkernel/intern/subdiv_foreach.c
@@ -1875,6 +1875,13 @@ bool BKE_subdiv_foreach_subdiv_geometry(Subdiv *subdiv,
   if (context->user_data_tls_free != NULL) {
     parallel_range_settings.func_finalize = subdiv_foreach_finalize;
   }
+
+  /* TODO(sergey): Possible optimization is to have a single pool and push all
+   * the tasks into it.
+   * NOTE: Watch out for callbacks which needs to run for loose geometry as they
+   * currently are relying on the fact that face/grid callbacks will tag non-
+   * loose geomtry. */
+
   BLI_task_parallel_range(
       0, coarse_mesh->totpoly, &ctx, subdiv_foreach_task, &parallel_range_settings);
   if (context->vertex_loose != NULL) {