BKE_attribute.hh

Go to the documentation of this file.

/* SPDX-FileCopyrightText: 2023 Blender Authors
 *
 * SPDX-License-Identifier: GPL-2.0-or-later */

 
#pragma once
 
#include <functional>
#include <optional>
 
#include "BLI_function_ref.hh"
#include "BLI_generic_pointer.hh"
#include "BLI_generic_virtual_array.hh"
#include "BLI_math_matrix_types.hh"
#include "BLI_offset_indices.hh"
#include "BLI_set.hh"
#include "BLI_struct_equality_utils.hh"
 
#include "BKE_attribute.h"
#include "BKE_attribute_filters.hh"
 
struct Mesh;
struct PointCloud;
namespace blender::fn {
namespace multi_function {
class MultiFunction;
}
class GField;
}  // namespace blender::fn
 
namespace blender::bke {

enum class AttrStorageType : int8_t {
  Array,
  Single,
};
 
enum class AttrType : int16_t {
  Bool,
  Int8,
  Int16_2D,
  Int32,
  Int32_2D,
  Float,
  Float2,
  Float3,
  Float4x4,
  ColorByte,
  ColorFloat,
  Quaternion,
  String,
};
 
const CPPType &attribute_type_to_cpp_type(AttrType type);
AttrType cpp_type_to_attribute_type(const CPPType &type);
 
enum class AttrDomain : int8_t {
  /* Used to choose automatically based on other data. */
  Auto = -1,
  /* Mesh, Curve or Point Cloud Point. */
  Point = 0,
  /* Mesh Edge. */
  Edge = 1,
  /* Mesh Face. */
  Face = 2,
  /* Mesh Corner. */
  Corner = 3,
  /* A single curve in a larger curve data-block. */
  Curve = 4,
  /* Instance. */
  Instance = 5,
  /* A layer in a grease pencil data-block. */
  Layer = 6,
};
#define ATTR_DOMAIN_NUM 7
 
const CPPType *custom_data_type_to_cpp_type(eCustomDataType type);
eCustomDataType cpp_type_to_custom_data_type(const CPPType &type);

struct AttributeMetaData {
  AttrDomain domain;
  eCustomDataType data_type;
 
  BLI_STRUCT_EQUALITY_OPERATORS_2(AttributeMetaData, domain, data_type)
};
 
struct AttributeDomainAndType {
  AttrDomain domain;
  eCustomDataType data_type;
  BLI_STRUCT_EQUALITY_OPERATORS_2(AttributeDomainAndType, domain, data_type)
};

struct AttributeInit {
  enum class Type {
    Construct,
    DefaultValue,
    VArray,
    MoveArray,
    Shared,
  };
  Type type;
  AttributeInit(const Type type) : type(type) {}
};

struct AttributeInitConstruct : public AttributeInit {
  AttributeInitConstruct() : AttributeInit(Type::Construct) {}
};

struct AttributeInitDefaultValue : public AttributeInit {
  AttributeInitDefaultValue() : AttributeInit(Type::DefaultValue) {}
};

struct AttributeInitVArray : public AttributeInit {
  GVArray varray;
 
  AttributeInitVArray(GVArray varray) : AttributeInit(Type::VArray), varray(std::move(varray)) {}
};

struct AttributeInitMoveArray : public AttributeInit {
  void *data = nullptr;
 
  AttributeInitMoveArray(void *data) : AttributeInit(Type::MoveArray), data(data) {}
};

struct AttributeInitShared : public AttributeInit {
  const void *data = nullptr;
  const ImplicitSharingInfo *sharing_info = nullptr;
 
  AttributeInitShared(const void *data, const ImplicitSharingInfo &sharing_info)
      : AttributeInit(Type::Shared), data(data), sharing_info(&sharing_info)
  {
  }
};
 
/* Returns false when the iteration should be stopped. */
using AttributeForeachCallback =
    FunctionRef<bool(StringRefNull attribute_id, const AttributeMetaData &meta_data)>;

template<typename T> struct AttributeReader {
  VArray<T> varray;
  AttrDomain domain;

  const ImplicitSharingInfo *sharing_info;
 
  const VArray<T> &operator*() const &
  {
    return this->varray;
  }
 
  VArray<T> &operator*() &
  {
    return this->varray;
  }
 
  VArray<T> operator*() &&
  {
    return std::move(this->varray);
  }
 
  operator bool() const
  {
    return this->varray;
  }
};

struct AttributeValidator {
  const fn::multi_function::MultiFunction *function;
 
  operator bool() const
  {
    return this->function != nullptr;
  }

  fn::GField validate_field_if_necessary(const fn::GField &field) const;
};

template<typename T> struct AttributeWriter {
  VMutableArray<T> varray;
  AttrDomain domain;
  std::function<void()> tag_modified_fn;
 
  operator bool() const
  {
    return this->varray;
  }

  void finish()
  {
    if (this->tag_modified_fn) {
      this->tag_modified_fn();
    }
  }
};

template<typename T> struct SpanAttributeWriter {
  MutableVArraySpan<T> span;
  AttrDomain domain;
  std::function<void()> tag_modified_fn;
 
  SpanAttributeWriter() = default;
 
  SpanAttributeWriter(AttributeWriter<T> &&other, const bool copy_values_to_span)
      : span(std::move(other.varray), copy_values_to_span),
        domain(other.domain),
        tag_modified_fn(std::move(other.tag_modified_fn))
  {
  }
 
  operator bool() const
  {
    return span.varray();
  }

  void finish()
  {
    if (this->span.varray()) {
      this->span.save();
    }
    if (this->tag_modified_fn) {
      this->tag_modified_fn();
    }
  }
};

struct GAttributeReader {
  GVArray varray;
  AttrDomain domain;
  const ImplicitSharingInfo *sharing_info;
 
  operator bool() const
  {
    return this->varray;
  }
 
  const GVArray &operator*() const &
  {
    return this->varray;
  }
 
  GVArray &operator*() &
  {
    return this->varray;
  }
 
  GVArray operator*() &&
  {
    return std::move(this->varray);
  }
 
  template<typename T> AttributeReader<T> typed() const
  {
    return {varray.typed<T>(), domain, sharing_info};
  }
};

struct GAttributeWriter {
  GVMutableArray varray;
  AttrDomain domain;
  std::function<void()> tag_modified_fn;
 
  operator bool() const
  {
    return this->varray;
  }
 
  void finish()
  {
    if (this->tag_modified_fn) {
      this->tag_modified_fn();
    }
  }
 
  template<typename T> AttributeWriter<T> typed() const
  {
    return {varray.typed<T>(), domain, tag_modified_fn};
  }
};

struct GSpanAttributeWriter {
  GMutableVArraySpan span;
  AttrDomain domain;
  std::function<void()> tag_modified_fn;
 
  GSpanAttributeWriter() = default;
 
  GSpanAttributeWriter(GAttributeWriter &&other, const bool copy_values_to_span)
      : span(std::move(other.varray), copy_values_to_span),
        domain(other.domain),
        tag_modified_fn(std::move(other.tag_modified_fn))
  {
  }
 
  operator bool() const
  {
    return span.varray();
  }
 
  void finish()
  {
    if (this->span.varray()) {
      this->span.save();
    }
    if (this->tag_modified_fn) {
      this->tag_modified_fn();
    }
  }
};

class AttributeIter {
 public:
  StringRefNull name;
  AttrDomain domain;
  eCustomDataType data_type;
  bool is_builtin = false;
  mutable const AttributeAccessor *accessor = nullptr;
 
 private:
  FunctionRef<GAttributeReader()> get_fn_;
  mutable bool stop_iteration_ = false;
 
 public:
  AttributeIter(const StringRefNull name,
                const AttrDomain domain,
                const eCustomDataType data_type,
                const FunctionRef<GAttributeReader()> get_fn)
      : name(name), domain(domain), data_type(data_type), get_fn_(get_fn)
  {
  }

  void stop() const
  {
    stop_iteration_ = true;
  }
 
  bool is_stopped() const
  {
    return stop_iteration_;
  }

  GAttributeReader get() const
  {
    return get_fn_();
  }

  GAttributeReader get(std::optional<AttrDomain> domain,
                       std::optional<eCustomDataType> data_type) const;
 
  GAttributeReader get(const AttrDomain domain) const
  {
    return this->get(domain, std::nullopt);
  }
 
  GAttributeReader get(const eCustomDataType data_type) const
  {
    return this->get(std::nullopt, data_type);
  }
 
  template<typename T>
  AttributeReader<T> get(const std::optional<AttrDomain> domain = std::nullopt) const
  {
    const CPPType &cpp_type = CPPType::get<T>();
    const eCustomDataType data_type = cpp_type_to_custom_data_type(cpp_type);
    return this->get(domain, data_type).typed<T>();
  }
};

struct AttributeAccessorFunctions {
  bool (*domain_supported)(const void *owner, AttrDomain domain);
  int (*domain_size)(const void *owner, AttrDomain domain);
  std::optional<AttributeDomainAndType> (*builtin_domain_and_type)(const void *owner,
                                                                   StringRef attribute_id);
  GPointer (*get_builtin_default)(const void *owner, StringRef attribute_id);
  GAttributeReader (*lookup)(const void *owner, StringRef attribute_id);
  GVArray (*adapt_domain)(const void *owner,
                          const GVArray &varray,
                          AttrDomain from_domain,
                          AttrDomain to_domain);
  void (*foreach_attribute)(const void *owner,
                            FunctionRef<void(const AttributeIter &iter)> fn,
                            const AttributeAccessor &accessor);
  AttributeValidator (*lookup_validator)(const void *owner, StringRef attribute_id);
  GAttributeWriter (*lookup_for_write)(void *owner, StringRef attribute_id);
  bool (*remove)(void *owner, StringRef attribute_id);
  bool (*add)(void *owner,
              StringRef attribute_id,
              AttrDomain domain,
              eCustomDataType data_type,
              const AttributeInit &initializer);
};

class AttributeAccessor {
 protected:
  void *owner_;
  const AttributeAccessorFunctions *fn_;
 
 public:
  AttributeAccessor(const void *owner, const AttributeAccessorFunctions &fn)
      : owner_(const_cast<void *>(owner)), fn_(&fn)
  {
  }

  static std::optional<AttributeAccessor> from_id(const ID &id);

  bool contains(StringRef attribute_id) const;

  std::optional<AttributeMetaData> lookup_meta_data(StringRef attribute_id) const;

  bool domain_supported(const AttrDomain domain) const
  {
    return fn_->domain_supported(owner_, domain);
  }

  int domain_size(const AttrDomain domain) const
  {
    return fn_->domain_size(owner_, domain);
  }

  bool is_builtin(const StringRef attribute_id) const
  {
    return fn_->builtin_domain_and_type(owner_, attribute_id).has_value();
  }

  std::optional<AttributeDomainAndType> get_builtin_domain_and_type(const StringRef name) const
  {
    return fn_->builtin_domain_and_type(owner_, name);
  }

  GPointer get_builtin_default(const StringRef attribute_id) const
  {
    BLI_assert(this->is_builtin(attribute_id));
    return fn_->get_builtin_default(owner_, attribute_id);
  }

  GAttributeReader lookup(const StringRef attribute_id) const
  {
    return fn_->lookup(owner_, attribute_id);
  }

  GAttributeReader lookup(StringRef attribute_id,
                          std::optional<AttrDomain> domain,
                          std::optional<eCustomDataType> data_type) const;

  GAttributeReader lookup(const StringRef attribute_id, const AttrDomain domain) const
  {
    return this->lookup(attribute_id, domain, std::nullopt);
  }

  GAttributeReader lookup(const StringRef attribute_id, const eCustomDataType data_type) const
  {
    return this->lookup(attribute_id, std::nullopt, data_type);
  }

  template<typename T>
  AttributeReader<T> lookup(const StringRef attribute_id,
                            const std::optional<AttrDomain> domain = std::nullopt) const
  {
    const CPPType &cpp_type = CPPType::get<T>();
    const eCustomDataType data_type = cpp_type_to_custom_data_type(cpp_type);
    return this->lookup(attribute_id, domain, data_type).typed<T>();
  }

  GAttributeReader lookup_or_default(StringRef attribute_id,
                                     AttrDomain domain,
                                     eCustomDataType data_type,
                                     const void *default_value = nullptr) const;

  template<typename T>
  AttributeReader<T> lookup_or_default(const StringRef attribute_id,
                                       const AttrDomain domain,
                                       const T &default_value) const
  {
    if (AttributeReader<T> varray = this->lookup<T>(attribute_id, domain)) {
      return varray;
    }
    return {VArray<T>::ForSingle(default_value, this->domain_size(domain)), domain};
  }

  AttributeValidator lookup_validator(const StringRef attribute_id) const
  {
    return fn_->lookup_validator(owner_, attribute_id);
  }

  GVArray adapt_domain(const GVArray &varray,
                       const AttrDomain from_domain,
                       const AttrDomain to_domain) const
  {
    return fn_->adapt_domain(owner_, varray, from_domain, to_domain);
  }

  template<typename T>
  VArray<T> adapt_domain(const VArray<T> &varray,
                         const AttrDomain from_domain,
                         const AttrDomain to_domain) const
  {
    return this->adapt_domain(GVArray(varray), from_domain, to_domain).typed<T>();
  }

  void foreach_attribute(const FunctionRef<void(const AttributeIter &)> fn) const
  {
    if (owner_ != nullptr) {
      fn_->foreach_attribute(owner_, fn, *this);
    }
  }

  Set<StringRefNull> all_ids() const;
};

class MutableAttributeAccessor : public AttributeAccessor {
 public:
  MutableAttributeAccessor(void *owner, const AttributeAccessorFunctions &fn)
      : AttributeAccessor(owner, fn)
  {
  }

  GAttributeWriter lookup_for_write(StringRef attribute_id);

  GSpanAttributeWriter lookup_for_write_span(StringRef attribute_id);

  template<typename T> AttributeWriter<T> lookup_for_write(const StringRef attribute_id)
  {
    GAttributeWriter attribute = this->lookup_for_write(attribute_id);
    if (!attribute) {
      return {};
    }
    if (!attribute.varray.type().is<T>()) {
      return {};
    }
    return attribute.typed<T>();
  }

  template<typename T> SpanAttributeWriter<T> lookup_for_write_span(const StringRef attribute_id)
  {
    AttributeWriter<T> attribute = this->lookup_for_write<T>(attribute_id);
    if (attribute) {
      return SpanAttributeWriter<T>{std::move(attribute), true};
    }
    return {};
  }

  bool rename(StringRef old_attribute_id, StringRef new_attribute_id);

  bool add(const StringRef attribute_id,
           const AttrDomain domain,
           const eCustomDataType data_type,
           const AttributeInit &initializer)
  {
    if (this->contains(attribute_id)) {
      return false;
    }
    return fn_->add(owner_, attribute_id, domain, data_type, initializer);
  }
  template<typename T>
  bool add(const StringRef attribute_id, const AttrDomain domain, const AttributeInit &initializer)
  {
    const CPPType &cpp_type = CPPType::get<T>();
    const eCustomDataType data_type = cpp_type_to_custom_data_type(cpp_type);
    return this->add(attribute_id, domain, data_type, initializer);
  }

  GAttributeWriter lookup_or_add_for_write(
      StringRef attribute_id,
      AttrDomain domain,
      eCustomDataType data_type,
      const AttributeInit &initializer = AttributeInitDefaultValue());

  GSpanAttributeWriter lookup_or_add_for_write_span(
      StringRef attribute_id,
      AttrDomain domain,
      eCustomDataType data_type,
      const AttributeInit &initializer = AttributeInitDefaultValue());

  template<typename T>
  AttributeWriter<T> lookup_or_add_for_write(
      const StringRef attribute_id,
      const AttrDomain domain,
      const AttributeInit &initializer = AttributeInitDefaultValue())
  {
    const CPPType &cpp_type = CPPType::get<T>();
    const eCustomDataType data_type = cpp_type_to_custom_data_type(cpp_type);
    return this->lookup_or_add_for_write(attribute_id, domain, data_type, initializer).typed<T>();
  }

  template<typename T>
  SpanAttributeWriter<T> lookup_or_add_for_write_span(
      const StringRef attribute_id,
      const AttrDomain domain,
      const AttributeInit &initializer = AttributeInitDefaultValue())
  {
    AttributeWriter<T> attribute = this->lookup_or_add_for_write<T>(
        attribute_id, domain, initializer);
    if (attribute) {
      return SpanAttributeWriter<T>{std::move(attribute), true};
    }
    return {};
  }

  GSpanAttributeWriter lookup_or_add_for_write_only_span(StringRef attribute_id,
                                                         AttrDomain domain,
                                                         eCustomDataType data_type);

  template<typename T>
  SpanAttributeWriter<T> lookup_or_add_for_write_only_span(const StringRef attribute_id,
                                                           const AttrDomain domain)
  {
    AttributeWriter<T> attribute = this->lookup_or_add_for_write<T>(
        attribute_id, domain, AttributeInitConstruct());
 
    if (attribute) {
      return SpanAttributeWriter<T>{std::move(attribute), false};
    }
    return {};
  }

  bool remove(const StringRef attribute_id)
  {
    return fn_->remove(owner_, attribute_id);
  }

  void remove_anonymous();
};
 
struct AttributeTransferData {
  /* Expect that if an attribute exists, it is stored as a contiguous array internally anyway. */
  GVArraySpan src;
  StringRef name;
  AttributeMetaData meta_data;
  GSpanAttributeWriter dst;
};

Vector<AttributeTransferData> retrieve_attributes_for_transfer(
    const AttributeAccessor src_attributes,
    MutableAttributeAccessor dst_attributes,
    AttrDomainMask domain_mask,
    const AttributeFilter &attribute_filter = {});
 
bool allow_procedural_attribute_access(StringRef attribute_name);
extern const char *no_procedural_access_message;
 
eCustomDataType attribute_data_type_highest_complexity(Span<eCustomDataType> data_types);
AttrDomain attribute_domain_highest_priority(Span<AttrDomain> domains);
 
void gather_attributes(AttributeAccessor src_attributes,
                       AttrDomain src_domain,
                       AttrDomain dst_domain,
                       const AttributeFilter &attribute_filter,
                       const IndexMask &selection,
                       MutableAttributeAccessor dst_attributes);

void gather_attributes(AttributeAccessor src_attributes,
                       AttrDomain src_domain,
                       AttrDomain dst_domain,
                       const AttributeFilter &attribute_filter,
                       Span<int> indices,
                       MutableAttributeAccessor dst_attributes);

void gather_attributes_group_to_group(AttributeAccessor src_attributes,
                                      AttrDomain src_domain,
                                      AttrDomain dst_domain,
                                      const AttributeFilter &attribute_filter,
                                      OffsetIndices<int> src_offsets,
                                      OffsetIndices<int> dst_offsets,
                                      const IndexMask &selection,
                                      MutableAttributeAccessor dst_attributes);
 
void gather_attributes_to_groups(AttributeAccessor src_attributes,
                                 AttrDomain src_domain,
                                 AttrDomain dst_domain,
                                 const AttributeFilter &attribute_filter,
                                 OffsetIndices<int> dst_offsets,
                                 const IndexMask &src_selection,
                                 MutableAttributeAccessor dst_attributes);
 
void copy_attributes(const AttributeAccessor src_attributes,
                     AttrDomain src_domain,
                     AttrDomain dst_domain,
                     const AttributeFilter &attribute_filter,
                     MutableAttributeAccessor dst_attributes);
 
void copy_attributes_group_to_group(AttributeAccessor src_attributes,
                                    AttrDomain src_domain,
                                    AttrDomain dst_domain,
                                    const AttributeFilter &attribute_filter,
                                    OffsetIndices<int> src_offsets,
                                    OffsetIndices<int> dst_offsets,
                                    const IndexMask &selection,
                                    MutableAttributeAccessor dst_attributes);
 
void fill_attribute_range_default(MutableAttributeAccessor dst_attributes,
                                  AttrDomain domain,
                                  const AttributeFilter &attribute_filter,
                                  IndexRange range);

void transform_custom_normal_attribute(const float4x4 &transform,
                                       MutableAttributeAccessor &attributes);
 
}  // namespace blender::bke