From 7f4878ac7f5612082a1235cf6083dc490cbfc212 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Thu, 9 Dec 2021 21:16:25 +1100 Subject: Cleanup: move public doc-strings into headers for 'functions' Ref T92709 --- source/blender/functions/FN_field.hh | 27 ++++++++++++++++++++++ .../blender/functions/FN_generic_virtual_array.hh | 21 +++++++++++++++++ source/blender/functions/FN_multi_function.hh | 6 +++++ source/blender/functions/intern/field.cc | 27 ---------------------- .../functions/intern/generic_virtual_array.cc | 9 -------- source/blender/functions/intern/multi_function.cc | 6 ----- 6 files changed, 54 insertions(+), 42 deletions(-) (limited to 'source/blender/functions') diff --git a/source/blender/functions/FN_field.hh b/source/blender/functions/FN_field.hh index da8e820c42a..d82f685e7ea 100644 --- a/source/blender/functions/FN_field.hh +++ b/source/blender/functions/FN_field.hh @@ -405,6 +405,24 @@ class FieldEvaluator : NonMovable, NonCopyable { IndexMask get_evaluated_as_mask(const int field_index); }; +/** + * Evaluate fields in the given context. If possible, multiple fields should be evaluated together, + * because that can be more efficient when they share common sub-fields. + * + * \param scope: The resource scope that owns data that makes up the output virtual arrays. Make + * sure the scope is not destructed when the output virtual arrays are still used. + * \param fields_to_evaluate: The fields that should be evaluated together. + * \param mask: Determines which indices are computed. The mask may be referenced by the returned + * 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_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_varrays is passed, the + * provided virtual arrays are returned. + */ Vector evaluate_fields(ResourceScope &scope, Span fields_to_evaluate, IndexMask mask, @@ -434,6 +452,15 @@ template Field make_constant_field(T value) GField make_constant_field(const CPPType &type, const void *value); +/** + * If the field depends on some input, the same field is returned. + * Otherwise the field is evaluated and a new field is created that just computes this constant. + * + * Making the field constant has two benefits: + * - The field-tree becomes a single node, which is more efficient when the field is evaluated many + * times. + * - Memory of the input fields may be freed. + */ GField make_field_constant_if_possible(GField field); class IndexFieldInput final : public FieldInput { diff --git a/source/blender/functions/FN_generic_virtual_array.hh b/source/blender/functions/FN_generic_virtual_array.hh index aed7c206fe5..03e81b13714 100644 --- a/source/blender/functions/FN_generic_virtual_array.hh +++ b/source/blender/functions/FN_generic_virtual_array.hh @@ -148,11 +148,29 @@ class GVArrayCommon { void materialize_to_uninitialized(void *dst) const; void materialize_to_uninitialized(const IndexMask mask, void *dst) const; + /** + * Returns true when the virtual array is stored as a span internally. + */ bool is_span() const; + /** + * Returns the internally used span of the virtual array. This invokes undefined behavior is the + * virtual array is not stored as a span internally. + */ GSpan get_internal_span() const; + /** + * Returns true when the virtual array returns the same value for every index. + */ bool is_single() const; + /** + * Copies the value that is used for every element into `r_value`, which is expected to point to + * initialized memory. This invokes undefined behavior if the virtual array would not return the + * same value for every index. + */ void get_internal_single(void *r_value) const; + /** + * Same as `get_internal_single`, but `r_value` points to initialized memory. + */ void get_internal_single_to_uninitialized(void *r_value) const; void get(const int64_t index, void *r_value) const; @@ -226,6 +244,9 @@ class GVMutableArray : public GVArrayCommon { void set_by_relocate(const int64_t index, void *value); void fill(const void *value); + /** + * Copy the values from the source buffer to all elements in the virtual array. + */ void set_all(const void *src); GVMutableArrayImpl *get_implementation() const; diff --git a/source/blender/functions/FN_multi_function.hh b/source/blender/functions/FN_multi_function.hh index af60e54808e..1e36d87668a 100644 --- a/source/blender/functions/FN_multi_function.hh +++ b/source/blender/functions/FN_multi_function.hh @@ -60,6 +60,12 @@ class MultiFunction { { } + /** + * The result is the same as using #call directly but this method has some additional features. + * - Automatic multi-threading when possible and appropriate. + * - Automatic index mask offsetting to avoid large temporary intermediate arrays that are mostly + * unused. + */ void call_auto(IndexMask mask, MFParams params, MFContext context) const; virtual void call(IndexMask mask, MFParams params, MFContext context) const = 0; diff --git a/source/blender/functions/intern/field.cc b/source/blender/functions/intern/field.cc index 27f213f2ba3..f55b9cd92ff 100644 --- a/source/blender/functions/intern/field.cc +++ b/source/blender/functions/intern/field.cc @@ -257,24 +257,6 @@ static void build_multi_function_procedure_for_fields(MFProcedure &procedure, BLI_assert(procedure.validate()); } -/** - * Evaluate fields in the given context. If possible, multiple fields should be evaluated together, - * because that can be more efficient when they share common sub-fields. - * - * \param scope: The resource scope that owns data that makes up the output virtual arrays. Make - * sure the scope is not destructed when the output virtual arrays are still used. - * \param fields_to_evaluate: The fields that should be evaluated together. - * \param mask: Determines which indices are computed. The mask may be referenced by the returned - * 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_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_varrays is passed, the - * provided virtual arrays are returned. - */ Vector evaluate_fields(ResourceScope &scope, Span fields_to_evaluate, IndexMask mask, @@ -488,15 +470,6 @@ void evaluate_constant_field(const GField &field, void *r_value) varrays[0].get_to_uninitialized(0, r_value); } -/** - * If the field depends on some input, the same field is returned. - * Otherwise the field is evaluated and a new field is created that just computes this constant. - * - * Making the field constant has two benefits: - * - The field-tree becomes a single node, which is more efficient when the field is evaluated many - * times. - * - Memory of the input fields may be freed. - */ GField make_field_constant_if_possible(GField field) { if (field.node().depends_on_input()) { diff --git a/source/blender/functions/intern/generic_virtual_array.cc b/source/blender/functions/intern/generic_virtual_array.cc index 415445eebd6..b4180a885e7 100644 --- a/source/blender/functions/intern/generic_virtual_array.cc +++ b/source/blender/functions/intern/generic_virtual_array.cc @@ -547,36 +547,28 @@ void GVArrayCommon::move_from(GVArrayCommon &&other) noexcept other.impl_ = nullptr; } -/* Returns true when the virtual array is stored as a span internally. */ bool GVArrayCommon::is_span() const { return impl_->is_span(); } -/* Returns the internally used span of the virtual array. This invokes undefined behavior is the - * virtual array is not stored as a span internally. */ GSpan GVArrayCommon::get_internal_span() const { BLI_assert(this->is_span()); return impl_->get_internal_span(); } -/* Returns true when the virtual array returns the same value for every index. */ bool GVArrayCommon::is_single() const { return impl_->is_single(); } -/* Copies the value that is used for every element into `r_value`, which is expected to point to - * initialized memory. This invokes undefined behavior if the virtual array would not return the - * same value for every index. */ void GVArrayCommon::get_internal_single(void *r_value) const { BLI_assert(this->is_single()); impl_->get_internal_single(r_value); } -/* Same as `get_internal_single`, but `r_value` points to initialized memory. */ void GVArrayCommon::get_internal_single_to_uninitialized(void *r_value) const { impl_->type().default_construct(r_value); @@ -729,7 +721,6 @@ GVMutableArrayImpl *GVMutableArray::get_implementation() const return this->get_impl(); } -/* Copy the values from the source buffer to all elements in the virtual array. */ void GVMutableArray::set_all(const void *src) { this->get_impl()->set_all(src); diff --git a/source/blender/functions/intern/multi_function.cc b/source/blender/functions/intern/multi_function.cc index 3e5539d4248..837ccc4f4fb 100644 --- a/source/blender/functions/intern/multi_function.cc +++ b/source/blender/functions/intern/multi_function.cc @@ -66,12 +66,6 @@ static int64_t compute_grain_size(const ExecutionHints &hints, const IndexMask m return grain_size; } -/** - * The result is the same as using #call directly but this method has some additional features. - * - Automatic multi-threading when possible and appropriate. - * - Automatic index mask offsetting to avoid large temporary intermediate arrays that are mostly - * unused. - */ void MultiFunction::call_auto(IndexMask mask, MFParams params, MFContext context) const { if (mask.is_empty()) { -- cgit v1.2.3