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_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"
 
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(const char *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 len);
 
/* ----------- 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,
                                 const char *name,
                                 eIDPropertyFlag flags = {}) ATTR_WARN_UNUSED_RESULT
    ATTR_NONNULL(3);
IDProperty *IDP_NewString(const char *st,
                          const char *name,
                          eIDPropertyFlag flags = {}) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(2);
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);
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();
bool IDP_InsertToGroup(IDProperty *group, IDProperty *previous, IDProperty *pnew)
    ATTR_NONNULL(1 /*group*/, 3 /*pnew*/);
void IDP_RemoveFromGroup(IDProperty *group, IDProperty *prop) ATTR_NONNULL();
void IDP_FreeFromGroup(IDProperty *group, IDProperty *prop) ATTR_NONNULL();
 
IDProperty *IDP_GetPropertyFromGroup(const IDProperty *prop,
                                     const char *name) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
IDProperty *IDP_GetPropertyTypeFromGroup(const IDProperty *prop,
                                         const char *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_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,
                    const char *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);
 
#define IDP_Int(prop) ((prop)->data.val)
#define IDP_Bool(prop) ((prop)->data.val)
#define IDP_Array(prop) ((prop)->data.pointer)
/* C11 const correctness for casts */
#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L)
#  define IDP_Float(prop) \
    _Generic((prop), \
        IDProperty *: (*(float *)&(prop)->data.val), \
        const IDProperty *: (*(const float *)&(prop)->data.val))
#  define IDP_Double(prop) \
    _Generic((prop), \
        IDProperty *: (*(double *)&(prop)->data.val), \
        const IDProperty *: (*(const double *)&(prop)->data.val))
#  define IDP_String(prop) \
    _Generic((prop), \
        IDProperty *: ((char *)(prop)->data.pointer), \
        const IDProperty *: ((const char *)(prop)->data.pointer))
#  define IDP_IDPArray(prop) \
    _Generic((prop), \
        IDProperty *: ((IDProperty *)(prop)->data.pointer), \
        const IDProperty *: ((const IDProperty *)(prop)->data.pointer))
#  define IDP_Id(prop) \
    _Generic((prop), \
        IDProperty *: ((ID *)(prop)->data.pointer), \
        const IDProperty *: ((const ID *)(prop)->data.pointer))
#else
#  define IDP_Float(prop) (*(float *)&(prop)->data.val)
#  define IDP_Double(prop) (*(double *)&(prop)->data.val)
#  define IDP_String(prop) ((char *)(prop)->data.pointer)
#  define IDP_IDPArray(prop) ((IDProperty *)(prop)->data.pointer)
#  define IDP_Id(prop) ((ID *)(prop)->data.pointer)
#endif
 
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);
  }
};
 
std::unique_ptr<IDProperty, IDPropertyDeleter> create_bool(StringRefNull prop_name,
                                                           bool value,
                                                           eIDPropertyFlag flags = {});
 
std::unique_ptr<IDProperty, IDPropertyDeleter> create(StringRefNull prop_name,
                                                      int32_t value,
                                                      eIDPropertyFlag flags = {});
 
std::unique_ptr<IDProperty, IDPropertyDeleter> create(StringRefNull prop_name,
                                                      float value,
                                                      eIDPropertyFlag flags = {});
 
std::unique_ptr<IDProperty, IDPropertyDeleter> create(StringRefNull prop_name,
                                                      double value,
                                                      eIDPropertyFlag flags = {});
 
std::unique_ptr<IDProperty, IDPropertyDeleter> create(StringRefNull prop_name,
                                                      const StringRefNull value,
                                                      eIDPropertyFlag flags = {});
 
std::unique_ptr<IDProperty, IDPropertyDeleter> create(StringRefNull prop_name,
                                                      ID *value,
                                                      eIDPropertyFlag flags = {});
 
std::unique_ptr<IDProperty, IDPropertyDeleter> create(StringRefNull prop_name,
                                                      Span<int32_t> values,
                                                      eIDPropertyFlag flags = {});
 
std::unique_ptr<IDProperty, IDPropertyDeleter> create(StringRefNull prop_name,
                                                      Span<float> values,
                                                      eIDPropertyFlag flags = {});
 
std::unique_ptr<IDProperty, IDPropertyDeleter> create(StringRefNull prop_name,
                                                      Span<double> values,
                                                      eIDPropertyFlag flags = {});
 
std::unique_ptr<IDProperty, IDPropertyDeleter> create_group(StringRefNull prop_name,
                                                            eIDPropertyFlag flags = {});
 
}  // namespace blender::bke::idprop