BKE_idprop.hh

Go to the documentation of this file.

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

 
#include <memory>
 
#include "DNA_ID.h"
#include "DNA_ID_enums.h"
 
#include "BLI_compiler_attrs.h"
#include "BLI_function_ref.hh"
#include "BLI_span.hh"
#include "BLI_string_ref.hh"
#include "BLI_sys_types.h"
#include "BLI_vector_set.hh"
 
struct BlendDataReader;
struct BlendWriter;
struct ID;
struct IDProperty;
struct IDPropertyUIData;
struct IDPropertyUIDataEnumItem;
namespace blender::io::serialize {
class ArrayValue;
class Value;
}  // namespace blender::io::serialize
 
union IDPropertyTemplate {
  int i;
  float f;
  double d;
  struct {
    const char *str;
    int len;
    char subtype;
  } string;
  ID *id;
  struct {
    int len;
    char type;
  } array;
};
 
/* ----------- Property Array Type ---------- */

IDProperty *IDP_NewIDPArray(blender::StringRef name) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
IDProperty *IDP_CopyIDPArray(const IDProperty *array, int flag) ATTR_WARN_UNUSED_RESULT
    ATTR_NONNULL();

void IDP_SetIndexArray(IDProperty *prop, int index, IDProperty *item) ATTR_NONNULL();
IDProperty *IDP_GetIndexArray(IDProperty *prop, int index) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
void IDP_AppendArray(IDProperty *prop, IDProperty *item);
void IDP_ResizeIDPArray(IDProperty *prop, int newlen);
 
/* ----------- Numeric Array Type ----------- */

void IDP_ResizeArray(IDProperty *prop, int newlen);
void IDP_FreeArray(IDProperty *prop);
 
/* ---------- String Type ------------ */
IDProperty *IDP_NewStringMaxSize(const char *st,
                                 size_t st_maxncpy,
                                 blender::StringRef name,
                                 eIDPropertyFlag flags = {}) ATTR_WARN_UNUSED_RESULT;
IDProperty *IDP_NewString(const char *st,
                          blender::StringRef name,
                          eIDPropertyFlag flags = {}) ATTR_WARN_UNUSED_RESULT;
void IDP_AssignStringMaxSize(IDProperty *prop, const char *st, size_t st_maxncpy) ATTR_NONNULL();
void IDP_AssignString(IDProperty *prop, const char *st) ATTR_NONNULL();
void IDP_FreeString(IDProperty *prop) ATTR_NONNULL();
 
/*-------- Enum Type -------*/
 
const IDPropertyUIDataEnumItem *IDP_EnumItemFind(const IDProperty *prop);
 
bool IDP_EnumItemsValidate(const IDPropertyUIDataEnumItem *items,
                           int items_num,
                           void (*error_fn)(const char *));
 
/*-------- ID Type -------*/
 
using IDPWalkFunc = void (*)(void *user_data, IDProperty *idp);

void IDP_AssignID(IDProperty *prop, ID *id, int flag);
 
/*-------- Group Functions -------*/

void IDP_SyncGroupValues(IDProperty *dest, const IDProperty *src) ATTR_NONNULL();
void IDP_SyncGroupTypes(IDProperty *dest, const IDProperty *src, bool do_arraylen) ATTR_NONNULL();
void IDP_ReplaceGroupInGroup(IDProperty *dest, const IDProperty *src) ATTR_NONNULL();
void IDP_ReplaceInGroup(IDProperty *group, IDProperty *prop) ATTR_NONNULL();
void IDP_ReplaceInGroup_ex(IDProperty *group, IDProperty *prop, IDProperty *prop_exist, int flag);
void IDP_MergeGroup(IDProperty *dest, const IDProperty *src, bool do_overwrite) ATTR_NONNULL();
void IDP_MergeGroup_ex(IDProperty *dest, const IDProperty *src, bool do_overwrite, int flag)
    ATTR_NONNULL();
bool IDP_AddToGroup(IDProperty *group, IDProperty *prop) ATTR_NONNULL();
void IDP_RemoveFromGroup(IDProperty *group, IDProperty *prop) ATTR_NONNULL();
void IDP_FreeFromGroup(IDProperty *group, IDProperty *prop) ATTR_NONNULL();
 
IDProperty *IDP_GetPropertyFromGroup(const IDProperty *prop,
                                     blender::StringRef name) ATTR_WARN_UNUSED_RESULT
    ATTR_NONNULL();
IDProperty *IDP_GetPropertyFromGroup_null(const IDProperty *prop,
                                          blender::StringRef name) ATTR_WARN_UNUSED_RESULT;

IDProperty *IDP_GetPropertyTypeFromGroup(const IDProperty *prop,
                                         blender::StringRef name,
                                         char type) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
 
/*-------- Main Functions --------*/
IDProperty *IDP_GetProperties(ID *id) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1);
IDProperty *IDP_EnsureProperties(ID *id) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1);
IDProperty *IDP_ID_system_properties_get(ID *id) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1);
IDProperty *IDP_ID_system_properties_ensure(ID *id) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1);
 
IDProperty *IDP_CopyProperty(const IDProperty *prop) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
IDProperty *IDP_CopyProperty_ex(const IDProperty *prop, int flag) ATTR_WARN_UNUSED_RESULT
    ATTR_NONNULL();
void IDP_CopyPropertyContent(IDProperty *dst, const IDProperty *src) ATTR_NONNULL();

bool IDP_EqualsProperties_ex(const IDProperty *prop1,
                             const IDProperty *prop2,
                             bool is_strict) ATTR_WARN_UNUSED_RESULT;
 
bool IDP_EqualsProperties(const IDProperty *prop1,
                          const IDProperty *prop2) ATTR_WARN_UNUSED_RESULT;

IDProperty *IDP_New(char type,
                    const IDPropertyTemplate *val,
                    blender::StringRef name,
                    eIDPropertyFlag flags = {}) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();

void IDP_FreePropertyContent_ex(IDProperty *prop, bool do_id_user);
void IDP_FreePropertyContent(IDProperty *prop);
void IDP_FreeProperty_ex(IDProperty *prop, bool do_id_user);
void IDP_FreeProperty(IDProperty *prop);
 
void IDP_ClearProperty(IDProperty *prop);
 
void IDP_Reset(IDProperty *prop, const IDProperty *reference);
 
#ifndef NDEBUG
const IDProperty *_IDP_assert_type(const IDProperty *prop, char ty);
const IDProperty *_IDP_assert_type_and_subtype(const IDProperty *prop, char ty, char sub_ty);
const IDProperty *_IDP_assert_type_mask(const IDProperty *prop, int ty_mask);
 
#else
#  define _IDP_assert_type(prop, ty) (prop)
#  define _IDP_assert_type_and_subtype(prop, ty, sub_ty) (prop)
#  define _IDP_assert_type_mask(prop, ty_mask) (prop)
#endif
 
#define IDP_int_get(prop) (_IDP_assert_type(prop, IDP_INT)->data.val)
#define IDP_int_set(prop, value) \
  { \
    IDProperty *prop_ = (prop); \
    BLI_assert(prop_->type == IDP_INT); \
    prop_->data.val = value; \
  } \
  ((void)0)
 
#define IDP_bool_get(prop) ((_IDP_assert_type(prop, IDP_BOOLEAN))->data.val)
#define IDP_bool_set(prop, value) \
  { \
    IDProperty *prop_ = (prop); \
    BLI_assert(prop_->type == IDP_BOOLEAN); \
    prop_->data.val = value; \
  } \
  ((void)0)
 
#define IDP_int_or_bool_get(prop) \
  (_IDP_assert_type_mask(prop, (1 << IDP_INT) | (1 << IDP_BOOLEAN))->data.val)
#define IDP_int_or_bool_set(prop, value) \
  { \
    IDProperty *prop_ = (prop); \
    BLI_assert(ELEM(prop_->type, IDP_INT, IDP_BOOLEAN)); \
    prop_->data.val = value; \
  } \
  ((void)0)
 
#define IDP_float_get(prop) (*(const float *)&(_IDP_assert_type(prop, IDP_FLOAT)->data.val))
#define IDP_float_set(prop, value) \
  { \
    IDProperty *prop_ = (prop); \
    BLI_assert(prop_->type == IDP_FLOAT); \
    (*(float *)&(prop_)->data.val) = value; \
  } \
  ((void)0)
 
#define IDP_double_get(prop) (*(const double *)&(_IDP_assert_type(prop, IDP_DOUBLE)->data.val))
#define IDP_double_set(prop, value) \
  { \
    IDProperty *prop_ = (prop); \
    BLI_assert(prop_->type == IDP_DOUBLE); \
    (*(double *)&(prop_)->data.val) = value; \
  } \
  ((void)0)

#define IDP_array_voidp_get(prop) (_IDP_assert_type(prop, IDP_ARRAY)->data.pointer)
 
#define IDP_array_int_get(prop) \
  static_cast<int *>(_IDP_assert_type_and_subtype(prop, IDP_ARRAY, IDP_INT)->data.pointer)
#define IDP_array_bool_get(prop) \
  static_cast<int8_t *>(_IDP_assert_type_and_subtype(prop, IDP_ARRAY, IDP_BOOLEAN)->data.pointer)
#define IDP_array_float_get(prop) \
  static_cast<float *>(_IDP_assert_type_and_subtype(prop, IDP_ARRAY, IDP_FLOAT)->data.pointer)
#define IDP_array_double_get(prop) \
  static_cast<double *>(_IDP_assert_type_and_subtype(prop, IDP_ARRAY, IDP_DOUBLE)->data.pointer)
#define IDP_property_array_get(prop) \
  static_cast<IDProperty *>(_IDP_assert_type(prop, IDP_IDPARRAY)->data.pointer)
 
#define IDP_string_get(prop) ((char *)_IDP_assert_type(prop, IDP_STRING)->data.pointer)
/* No `IDP_string_set` needed. */
#define IDP_ID_get(prop) ((void)0, ((ID *)_IDP_assert_type(prop, IDP_ID)->data.pointer))
/* No `IDP_ID_set` needed. */

int IDP_coerce_to_int_or_zero(const IDProperty *prop);
float IDP_coerce_to_float_or_zero(const IDProperty *prop);
double IDP_coerce_to_double_or_zero(const IDProperty *prop);

void IDP_foreach_property(IDProperty *id_property_root,
                          int type_filter,
                          blender::FunctionRef<void(IDProperty *id_property)> callback);
 
/* Format IDProperty as strings */
char *IDP_reprN(const IDProperty *prop, uint *r_len);
void IDP_repr_fn(const IDProperty *prop,
                 void (*str_append_fn)(void *user_data, const char *str, uint str_len),
                 void *user_data);
void IDP_print(const IDProperty *prop);
 
const char *IDP_type_str(eIDPropertyType type, short sub_type);
const char *IDP_type_str(const IDProperty *prop);
 
void IDP_BlendWrite(BlendWriter *writer, const IDProperty *prop);
void IDP_BlendReadData_impl(BlendDataReader *reader,
                            IDProperty **prop,
                            const char *caller_func_id);
#define IDP_BlendDataRead(reader, prop) IDP_BlendReadData_impl(reader, prop, __func__)
 
enum eIDPropertyUIDataType {
  IDP_UI_DATA_TYPE_UNSUPPORTED = -1,
  IDP_UI_DATA_TYPE_INT = 0,
  IDP_UI_DATA_TYPE_FLOAT = 1,
  IDP_UI_DATA_TYPE_STRING = 2,
  IDP_UI_DATA_TYPE_ID = 3,
  IDP_UI_DATA_TYPE_BOOLEAN = 4,
};
 
bool IDP_ui_data_supported(const IDProperty *prop);
eIDPropertyUIDataType IDP_ui_data_type(const IDProperty *prop);
void IDP_ui_data_free(IDProperty *prop);
void IDP_ui_data_free_unique_contents(IDPropertyUIData *ui_data,
                                      eIDPropertyUIDataType type,
                                      const IDPropertyUIData *other);
IDPropertyUIData *IDP_ui_data_ensure(IDProperty *prop);
IDPropertyUIData *IDP_ui_data_copy(const IDProperty *prop);
IDPropertyUIData *IDP_TryConvertUIData(IDPropertyUIData *src,
                                       eIDPropertyUIDataType src_type,
                                       eIDPropertyUIDataType dst_type);
 
namespace blender::bke::idprop {

std::unique_ptr<blender::io::serialize::ArrayValue> convert_to_serialize_values(
    const IDProperty *properties);

IDProperty *convert_from_serialize_value(const blender::io::serialize::Value &value);
 
class IDPropertyDeleter {
 public:
  void operator()(IDProperty *id_prop)
  {
    IDP_FreeProperty(id_prop);
  }
};
 
struct IDPropertyGroupChildrenSet {
  struct IDPropNameGetter {
    StringRef operator()(const IDProperty *value) const
    {
      return StringRef(value->name);
    }
  };
 
  CustomIDVectorSet<IDProperty *, IDPropNameGetter, 8> children;
};

std::unique_ptr<IDProperty, IDPropertyDeleter> create_bool(StringRef prop_name,
                                                           bool value,
                                                           eIDPropertyFlag flags = {});

std::unique_ptr<IDProperty, IDPropertyDeleter> create(StringRef prop_name,
                                                      int32_t value,
                                                      eIDPropertyFlag flags = {});

std::unique_ptr<IDProperty, IDPropertyDeleter> create(StringRef prop_name,
                                                      float value,
                                                      eIDPropertyFlag flags = {});

std::unique_ptr<IDProperty, IDPropertyDeleter> create(StringRef prop_name,
                                                      double value,
                                                      eIDPropertyFlag flags = {});

std::unique_ptr<IDProperty, IDPropertyDeleter> create(StringRef prop_name,
                                                      StringRefNull value,
                                                      eIDPropertyFlag flags = {});

std::unique_ptr<IDProperty, IDPropertyDeleter> create(StringRef prop_name,
                                                      ID *value,
                                                      eIDPropertyFlag flags = {});

std::unique_ptr<IDProperty, IDPropertyDeleter> create(StringRef prop_name,
                                                      Span<int32_t> values,
                                                      eIDPropertyFlag flags = {});

std::unique_ptr<IDProperty, IDPropertyDeleter> create(StringRef prop_name,
                                                      Span<float> values,
                                                      eIDPropertyFlag flags = {});

std::unique_ptr<IDProperty, IDPropertyDeleter> create(StringRef prop_name,
                                                      Span<double> values,
                                                      eIDPropertyFlag flags = {});

 
std::unique_ptr<IDProperty, IDPropertyDeleter> create_group(StringRef prop_name,
                                                            eIDPropertyFlag flags = {});
 
}  // namespace blender::bke::idprop