Rename "dst_hints" to "dst_varrays", update comments

2 files changed, 33 insertions, 35 deletions

diff --git a/source/blender/functions/FN_field.hh b/source/blender/functions/FN_field.hh
index 07859565a06..25188531580 100644
--- a/source/blender/functions/FN_field.hh
+++ b/source/blender/functions/FN_field.hh
@@ -27,8 +27,8 @@
  *
  * Fields can be build, composed and evaluated at run-time. They are stored in a directed tree
  * graph data structure, whereby each node is a #FieldNode and edges are dependencies. A #FieldNode
- * has an arbitrary number of inputs and at least one output. A #Field references a specific output
- * of a #FieldNode. The inputs of a #FieldNode are other fields.
+ * has an arbitrary number of inputs and at least one output and a #Field references a specific
+ * output of a #FieldNode. The inputs of a #FieldNode are other fields.
  *
  * There are two different types of field nodes:
  *  - #FieldInput: Has no input and exactly one output. It represents an input to the entire field
@@ -319,7 +319,7 @@ class FieldEvaluator : NonMovable, NonCopyable {
   const FieldContext &context_;
   const IndexMask mask_;
   Vector<GField> fields_to_evaluate_;
-  Vector<GVMutableArray *> dst_hints_;
+  Vector<GVMutableArray *> dst_varrays_;
   Vector<const GVArray *> evaluated_varrays_;
   Vector<OutputPointerInfo> output_pointer_infos_;
   bool is_evaluated_ = false;
@@ -352,9 +352,8 @@ class FieldEvaluator : NonMovable, NonCopyable {
   /** Same as #add_with_destination but typed. */
   template<typename T> int add_with_destination(Field<T> field, VMutableArray<T> &dst)
   {
-    GVMutableArray &generic_dst_hint = scope_.construct<GVMutableArray_For_VMutableArray<T>>(
-        __func__, dst);
-    return this->add_with_destination(GField(std::move(field)), generic_dst_hint);
+    GVMutableArray &varray = scope_.construct<GVMutableArray_For_VMutableArray<T>>(__func__, dst);
+    return this->add_with_destination(GField(std::move(field)), varray);
   }
 
   /**
@@ -373,9 +372,8 @@ class FieldEvaluator : NonMovable, NonCopyable {
    */
   template<typename T> int add_with_destination(Field<T> field, MutableSpan<T> dst)
   {
-    GVMutableArray &generic_dst_hint = scope_.construct<GVMutableArray_For_MutableSpan<T>>(
-        __func__, dst);
-    return this->add_with_destination(std::move(field), generic_dst_hint);
+    GVMutableArray &varray = scope_.construct<GVMutableArray_For_MutableSpan<T>>(__func__, dst);
+    return this->add_with_destination(std::move(field), varray);
   }
 
   int add(GField field, const GVArray **varray_ptr);
@@ -389,7 +387,7 @@ class FieldEvaluator : NonMovable, NonCopyable {
   template<typename T> int add(Field<T> field, const VArray<T> **varray_ptr)
   {
     const int field_index = fields_to_evaluate_.append_and_get_index(std::move(field));
-    dst_hints_.append(nullptr);
+    dst_varrays_.append(nullptr);
     output_pointer_infos_.append(OutputPointerInfo{
         varray_ptr, [](void *dst, const GVArray &varray, ResourceScope &scope) {
           *(const VArray<T> **)dst = &*scope.construct<GVArray_Typed<T>>(__func__, varray);
@@ -432,7 +430,7 @@ Vector<const GVArray *> evaluate_fields(ResourceScope &scope,
                                         Span<GFieldRef> fields_to_evaluate,
                                         IndexMask mask,
                                         const FieldContext &context,
-                                        Span<GVMutableArray *> dst_hints = {});
+                                        Span<GVMutableArray *> dst_varrays = {});
 
 /* --------------------------------------------------------------------
  * Utility functions for simple field creation and evaluation.
diff --git a/source/blender/functions/intern/field.cc b/source/blender/functions/intern/field.cc
index a27c5e4e3dc..fa7dea97b7f 100644
--- a/source/blender/functions/intern/field.cc
+++ b/source/blender/functions/intern/field.cc
@@ -30,9 +30,9 @@ namespace blender::fn {
 
 struct FieldTreeInfo {
   /**
-   * When fields are build, they only have references to the fields that they depend on. This map
-   * allows traversal of fields in the opposite direction. So for every field it stores what other
-   * fields directly depend on it.
+   * When fields are built, they only have references to the fields that they depend on. This map
+   * allows traversal of fields in the opposite direction. So for every field it stores the other
+   * fields that depend on it directly.
    */
   MultiValueMap<GFieldRef, GFieldRef> field_users;
   /**
@@ -111,7 +111,7 @@ static Set<GFieldRef> find_varying_fields(const FieldTreeInfo &field_tree_info,
 
   /* The varying fields are the ones that depend on inputs that are not constant. Therefore we
    * start the tree search at the non-constant input fields and traverse through all fields that
-   * depend on those. */
+   * depend on them. */
   for (const int i : field_context_inputs.index_range()) {
     const GVArray *varray = field_context_inputs[i];
     if (varray->is_single()) {
@@ -258,27 +258,29 @@ struct PartiallyInitializedArray : NonCopyable, NonMovable {
  *   virtual arrays. So the underlying indices (if applicable) should live longer then #scope.
  * \param context: The context that the field is evaluated in. Used to retrieve data from each
  *   #FieldInput in the field network.
- * \param dst_hints: If provided, the computed data will be written into those virtual arrays
+ * \param dst_varrays: If provided, the computed data will be written into those virtual arrays
  *   instead of into newly created ones. That allows making the computed data live longer than
  *   #scope and is more efficient when the data will be written into those virtual arrays
  *   later anyway.
- * \return The computed virtual arrays for each provided field. If #dst_hints is passed, the
+ * \return The computed virtual arrays for each provided field. If #dst_varrays is passed, the
  *   provided virtual arrays are returned.
  */
 Vector<const GVArray *> evaluate_fields(ResourceScope &scope,
                                         Span<GFieldRef> fields_to_evaluate,
                                         IndexMask mask,
                                         const FieldContext &context,
-                                        Span<GVMutableArray *> dst_hints)
+                                        Span<GVMutableArray *> dst_varrays)
 {
   Vector<const GVArray *> r_varrays(fields_to_evaluate.size(), nullptr);
+  const int array_size = mask.min_array_size();
 
-  /* Destination hints are optional. Create a small utility method to access them. */
-  auto get_dst_hint_if_available = [&](int index) -> GVMutableArray * {
-    if (dst_hints.is_empty()) {
+  /* Destination arrays are optional. Create a small utility method to access them. */
+  auto get_dst_varray_if_available = [&](int index) -> GVMutableArray * {
+    if (dst_varrays.is_empty()) {
       return nullptr;
     }
-    return dst_hints[index];
+    BLI_assert(dst_varrays[index] == nullptr || dst_varrays[index]->size() >= array_size);
+    return dst_varrays[index];
   };
 
   /* Traverse the field tree and prepare some data that is used in later steps. */
@@ -325,8 +327,6 @@ Vector<const GVArray *> evaluate_fields(ResourceScope &scope,
     }
   }
 
-  const int array_size = mask.min_array_size();
-
   /* Evaluate varying fields if necessary. */
   if (!varying_fields_to_evaluate.is_empty()) {
     /* Build the procedure for those fields. */
@@ -348,7 +348,7 @@ Vector<const GVArray *> evaluate_fields(ResourceScope &scope,
       const int out_index = varying_field_indices[i];
 
       /* Try to get an existing virtual array that the result should be written into. */
-      GVMutableArray *output_varray = get_dst_hint_if_available(out_index);
+      GVMutableArray *output_varray = get_dst_varray_if_available(out_index);
       void *buffer;
       if (output_varray == nullptr || !output_varray->is_span()) {
         /* Allocate a new buffer for the computed result. */
@@ -419,11 +419,11 @@ Vector<const GVArray *> evaluate_fields(ResourceScope &scope,
     procedure_executor.call(IndexRange(1), mf_params, mf_context);
   }
 
-  /* Copy data to destination hints if still necessary. In some cases the evaluation above has
+  /* Copy data to supplied destination arrays if necessary. In some cases the evaluation above has
    * written the computed data in the right place already. */
-  if (!dst_hints.is_empty()) {
+  if (!dst_varrays.is_empty()) {
     for (const int out_index : fields_to_evaluate.index_range()) {
-      GVMutableArray *output_varray = get_dst_hint_if_available(out_index);
+      GVMutableArray *output_varray = get_dst_varray_if_available(out_index);
       if (output_varray == nullptr) {
         /* Caller did not provide a destination for this output. */
         continue;
@@ -480,6 +480,7 @@ static Vector<int64_t> indices_from_selection(const VArray<bool> &selection)
   /* If the selection is just a single value, it's best to avoid calling this
    * function when constructing an IndexMask and use an IndexRange instead. */
   BLI_assert(!selection.is_single());
+
   Vector<int64_t> indices;
   if (selection.is_span()) {
     Span<bool> span = selection.get_internal_span();
@@ -502,22 +503,21 @@ static Vector<int64_t> indices_from_selection(const VArray<bool> &selection)
 int FieldEvaluator::add_with_destination(GField field, GVMutableArray &dst)
 {
   const int field_index = fields_to_evaluate_.append_and_get_index(std::move(field));
-  dst_hints_.append(&dst);
+  dst_varrays_.append(&dst);
   output_pointer_infos_.append({});
   return field_index;
 }
 
 int FieldEvaluator::add_with_destination(GField field, GMutableSpan dst)
 {
-  GVMutableArray &varray_dst_hint = scope_.construct<GVMutableArray_For_GMutableSpan>(__func__,
-                                                                                      dst);
-  return this->add_with_destination(std::move(field), varray_dst_hint);
+  GVMutableArray &varray = scope_.construct<GVMutableArray_For_GMutableSpan>(__func__, dst);
+  return this->add_with_destination(std::move(field), varray);
 }
 
 int FieldEvaluator::add(GField field, const GVArray **varray_ptr)
 {
   const int field_index = fields_to_evaluate_.append_and_get_index(std::move(field));
-  dst_hints_.append(nullptr);
+  dst_varrays_.append(nullptr);
   output_pointer_infos_.append(OutputPointerInfo{
       varray_ptr, [](void *dst, const GVArray &varray, ResourceScope &UNUSED(scope)) {
         *(const GVArray **)dst = &varray;
@@ -528,7 +528,7 @@ int FieldEvaluator::add(GField field, const GVArray **varray_ptr)
 int FieldEvaluator::add(GField field)
 {
   const int field_index = fields_to_evaluate_.append_and_get_index(std::move(field));
-  dst_hints_.append(nullptr);
+  dst_varrays_.append(nullptr);
   output_pointer_infos_.append({});
   return field_index;
 }
@@ -540,7 +540,7 @@ void FieldEvaluator::evaluate()
   for (const int i : fields_to_evaluate_.index_range()) {
     fields[i] = fields_to_evaluate_[i];
   }
-  evaluated_varrays_ = evaluate_fields(scope_, fields, mask_, context_, dst_hints_);
+  evaluated_varrays_ = evaluate_fields(scope_, fields, mask_, context_, dst_varrays_);
   BLI_assert(fields_to_evaluate_.size() == evaluated_varrays_.size());
   for (const int i : fields_to_evaluate_.index_range()) {
     OutputPointerInfo &info = output_pointer_infos_[i];