RNA_types.hh

Go to the documentation of this file.

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

 
/* Use a define instead of `#pragma once` because of `BKE_addon.h`, `ED_object.hh` & others. */
#ifndef __RNA_TYPES_H__
#define __RNA_TYPES_H__
 
#include <optional>
#include <string>
 
#include "../blenlib/BLI_function_ref.hh"
#include "../blenlib/BLI_sys_types.h"
#include "../blenlib/BLI_utildefines.h"
#include "../blenlib/BLI_vector.hh"
 
struct BlenderRNA;
struct FunctionRNA;
struct ID;
struct Main;
struct ParameterList;
struct PropertyRNA;
struct ReportList;
struct StructRNA;
struct bContext;

struct AncestorPointerRNA {
  StructRNA *type;
  void *data;
};

constexpr int64_t ANCESTOR_POINTERRNA_DEFAULT_SIZE = 2;

 
struct PointerRNA {
  ID *owner_id = nullptr;
  StructRNA *type = nullptr;
  void *data = nullptr;

  blender::Vector<AncestorPointerRNA, ANCESTOR_POINTERRNA_DEFAULT_SIZE> ancestors = {};
 
  PointerRNA() = default;
  PointerRNA(const PointerRNA &) = default;
  PointerRNA(PointerRNA &&) = default;
  PointerRNA &operator=(const PointerRNA &other) = default;
  PointerRNA &operator=(PointerRNA &&other) = default;
 
  PointerRNA(ID *owner_id, StructRNA *type, void *data)
      : owner_id(owner_id), type(type), data(data), ancestors{}
  {
  }
  PointerRNA(ID *owner_id, StructRNA *type, void *data, const PointerRNA &parent)
      : owner_id(owner_id), type(type), data(data), ancestors(parent.ancestors)
  {
    this->ancestors.append({parent.type, parent.data});
  }
  PointerRNA(ID *owner_id, StructRNA *type, void *data, blender::Span<AncestorPointerRNA> parents)
      : owner_id(owner_id), type(type), data(data), ancestors(parents)
  {
  }

  void reset()
  {
    *this = {};
  }

  void invalidate()
  {
    this->reset();
  }

  template<typename T> T *data_as() const
  {
    return static_cast<T *>(this->data);
  }

  PointerRNA parent() const
  {
    if (ancestors.is_empty()) {
      return PointerRNA();
    }
 
    return PointerRNA(owner_id, ancestors.last().type, ancestors.last().data);
  }
};
 
extern const PointerRNA PointerRNA_NULL;
 
struct PropertyPointerRNA {
  PointerRNA ptr = {};
  PropertyRNA *prop = nullptr;
};

struct PathResolvedRNA {
  PointerRNA ptr = {};
  PropertyRNA *prop = nullptr;
  int prop_index = -1;
};
 
/* Property */
 
enum PropertyType {
  PROP_BOOLEAN = 0,
  PROP_INT = 1,
  PROP_FLOAT = 2,
  PROP_STRING = 3,
  PROP_ENUM = 4,
  PROP_POINTER = 5,
  PROP_COLLECTION = 6,
};
 
/* also update rna_property_subtype_unit when you change this */
enum PropertyUnit {
  PROP_UNIT_NONE = (0 << 16),
  PROP_UNIT_LENGTH = (1 << 16),             /* m */
  PROP_UNIT_AREA = (2 << 16),               /* m^2 */
  PROP_UNIT_VOLUME = (3 << 16),             /* m^3 */
  PROP_UNIT_MASS = (4 << 16),               /* kg */
  PROP_UNIT_ROTATION = (5 << 16),           /* radians */
  PROP_UNIT_TIME = (6 << 16),               /* frame */
  PROP_UNIT_TIME_ABSOLUTE = (7 << 16),      /* time in seconds (independent of scene) */
  PROP_UNIT_VELOCITY = (8 << 16),           /* m/s */
  PROP_UNIT_ACCELERATION = (9 << 16),       /* m/(s^2) */
  PROP_UNIT_CAMERA = (10 << 16),            /* mm */
  PROP_UNIT_POWER = (11 << 16),             /* W */
  PROP_UNIT_TEMPERATURE = (12 << 16),       /* C */
  PROP_UNIT_WAVELENGTH = (13 << 16),        /* `nm` (independent of scene). */
  PROP_UNIT_COLOR_TEMPERATURE = (14 << 16), /* K */
  PROP_UNIT_FREQUENCY = (15 << 16),         /* Hz */
};
ENUM_OPERATORS(PropertyUnit, PROP_UNIT_TEMPERATURE)
 

enum PropertyScaleType {
  PROP_SCALE_LINEAR = 0,
  PROP_SCALE_LOG = 1,
  PROP_SCALE_CUBIC = 2,
};
 
#define RNA_SUBTYPE_UNIT(subtype) ((subtype) & 0x00FF0000)
#define RNA_SUBTYPE_VALUE(subtype) ((subtype) & ~0x00FF0000)
#define RNA_SUBTYPE_UNIT_VALUE(subtype) ((subtype) >> 16)
 
#define RNA_ENUM_BITFLAG_SIZE 32
 
#define RNA_TRANSLATION_PREC_DEFAULT 5
 
#define RNA_STACK_ARRAY 32

enum PropertySubType {
  PROP_NONE = 0,
 
  /* strings */
  PROP_FILEPATH = 1,
  PROP_DIRPATH = 2,
  PROP_FILENAME = 3,
  PROP_BYTESTRING = 4,
  /* 5 was used by "PROP_TRANSLATE" sub-type, which is now a flag. */
  PROP_PASSWORD = 6,
 
  /* numbers */
  PROP_PIXEL = 12,
  PROP_UNSIGNED = 13,
  PROP_PERCENTAGE = 14,
  PROP_FACTOR = 15,
  PROP_ANGLE = 16 | PROP_UNIT_ROTATION,
  PROP_TIME = 17 | PROP_UNIT_TIME,
  PROP_TIME_ABSOLUTE = 17 | PROP_UNIT_TIME_ABSOLUTE,
  PROP_DISTANCE = 18 | PROP_UNIT_LENGTH,
  PROP_DISTANCE_CAMERA = 19 | PROP_UNIT_CAMERA,
 
  /* number arrays */
  PROP_COLOR = 20,
  PROP_TRANSLATION = 21 | PROP_UNIT_LENGTH,
  PROP_DIRECTION = 22,
  PROP_VELOCITY = 23 | PROP_UNIT_VELOCITY,
  PROP_ACCELERATION = 24 | PROP_UNIT_ACCELERATION,
  PROP_MATRIX = 25,
  PROP_EULER = 26 | PROP_UNIT_ROTATION,
  PROP_QUATERNION = 27,
  PROP_AXISANGLE = 28,
  PROP_XYZ = 29,
  PROP_XYZ_LENGTH = 29 | PROP_UNIT_LENGTH,
  PROP_COLOR_GAMMA = 30,
  PROP_COORDS = 31,
 
  /* booleans */
  PROP_LAYER = 40,
  PROP_LAYER_MEMBER = 41,

  PROP_POWER = 42 | PROP_UNIT_POWER,
 
  /* temperature */
  PROP_TEMPERATURE = 43 | PROP_UNIT_TEMPERATURE,
 
  /* wavelength */
  PROP_WAVELENGTH = 44 | PROP_UNIT_WAVELENGTH,
 
  /* wavelength */
  PROP_COLOR_TEMPERATURE = 45 | PROP_UNIT_COLOR_TEMPERATURE,
 
  PROP_FREQUENCY = 46 | PROP_UNIT_FREQUENCY,
  PROP_PIXEL_DIAMETER = 47,
  PROP_DISTANCE_DIAMETER = 48 | PROP_UNIT_LENGTH,
};
 
/* Make sure enums are updated with these */
/* HIGHEST FLAG IN USE: 1u << 31
 * FREE FLAGS: 13. */
enum PropertyFlag {
  PROP_EDITABLE = (1 << 0),
  PROP_LIB_EXCEPTION = (1 << 16),
  PROP_ANIMATABLE = (1 << 1),
  PROP_TEXTEDIT_UPDATE = (1u << 31),
 
  /* icon */
  PROP_ICONS_CONSECUTIVE = (1 << 12),
  PROP_ICONS_REVERSE = (1 << 8),

  PROP_HIDDEN = (1 << 19),
  PROP_SKIP_SAVE = (1 << 28),
 
  /* numbers */

  PROP_PROPORTIONAL = (1 << 26),
 
  /* pointers */

  PROP_ID_REFCOUNT = (1 << 6),

  PROP_ID_SELF_CHECK = (1 << 20),
  PROP_NEVER_NULL = (1 << 18),
  PROP_NEVER_UNLINK = (1 << 25),

  PROP_PTR_NO_OWNERSHIP = (1 << 7),

  PROP_ENUM_FLAG = (1 << 21),
 
  /* need context for update function */
  PROP_CONTEXT_UPDATE = (1 << 22),
  PROP_CONTEXT_PROPERTY_UPDATE = PROP_CONTEXT_UPDATE | (1 << 27),
 
  /* registering */
  PROP_REGISTER = (1 << 4),
  PROP_REGISTER_OPTIONAL = PROP_REGISTER | (1 << 5),

  PROP_THICK_WRAP = (1 << 23),

  PROP_IDPROPERTY = (1 << 10),
  PROP_DYNAMIC = (1 << 17),
  PROP_ENUM_NO_CONTEXT = (1 << 24),
  PROP_ENUM_NO_TRANSLATE = (1 << 29),

  PROP_NO_DEG_UPDATE = (1 << 30),

  PROP_DEG_SYNC_ONLY = (1 << 9),

  PROP_PATH_OUTPUT = (1 << 2),
  PROP_PATH_SUPPORTS_BLEND_RELATIVE = (1 << 15),

  PROP_PATH_SUPPORTS_TEMPLATES = (1 << 14),

  PROP_SKIP_PRESET = (1 << 11),
};
ENUM_OPERATORS(PropertyFlag, PROP_TEXTEDIT_UPDATE)
 

enum PropertyPathTemplateType {
  /* Only supports general and type-specific variables, no purpose-specific
   * variables. */
  PROP_VARIABLES_NONE = 0,
 
  /* Supports render output variables.
   *
   * \see BKE_add_template_variables_for_render_path() */
  PROP_VARIABLES_RENDER_OUTPUT,
};

enum PropertyOverrideFlag {
  PROPOVERRIDE_OVERRIDABLE_LIBRARY = (1 << 0),

  PROPOVERRIDE_NO_COMPARISON = (1 << 1),

  PROPOVERRIDE_IGNORE = (1 << 2),
 
  /*** Collections-related ***/

  PROPOVERRIDE_LIBRARY_INSERTION = (1 << 10),

  PROPOVERRIDE_NO_PROP_NAME = (1 << 11),
};
ENUM_OPERATORS(PropertyOverrideFlag, PROPOVERRIDE_NO_PROP_NAME);

enum ParameterFlag {
  PARM_REQUIRED = (1 << 0),
  PARM_OUTPUT = (1 << 1),
  PARM_RNAPTR = (1 << 2),
  PARM_PYFUNC_REGISTER_OPTIONAL = (1 << 3),
};
ENUM_OPERATORS(ParameterFlag, PARM_PYFUNC_REGISTER_OPTIONAL)
 
struct CollectionPropertyIterator;
struct Link;
using IteratorSkipFunc = bool (*)(CollectionPropertyIterator *iter, void *data);
 
struct ListBaseIterator {
  Link *link;
  int flag;
  IteratorSkipFunc skip;
};
 
struct ArrayIterator {
  char *ptr;
  char *endptr;
  void *free_ptr;
  int itemsize;

  int length;

  IteratorSkipFunc skip;
};
 
struct CountIterator {
  void *ptr;
  int item;
};
 
struct CollectionPropertyIterator {
  /* internal */
  PointerRNA parent;
  PointerRNA builtin_parent;
  PropertyRNA *prop;
  union {
    /* Keep biggest object first in the union, for zero-initialization to work properly. */
    ArrayIterator array;
    ListBaseIterator listbase;
    CountIterator count;
    void *custom;
  } internal;
  int idprop;
  int level;
 
  /* external */
  PointerRNA ptr;
  bool valid;
};
 
struct CollectionVector {
  blender::Vector<PointerRNA> items;
};
 
enum RawPropertyType {
  PROP_RAW_UNSET = -1,
  PROP_RAW_INT, /* XXX: abused for types that are not set, eg. MFace.verts, needs fixing. */
  PROP_RAW_SHORT,
  PROP_RAW_CHAR,
  PROP_RAW_BOOLEAN,
  PROP_RAW_DOUBLE,
  PROP_RAW_FLOAT,
  PROP_RAW_UINT8,
  PROP_RAW_UINT16,
  PROP_RAW_INT64,
  PROP_RAW_UINT64,
  PROP_RAW_INT8,
};
 
struct RawArray {
  void *array;
  RawPropertyType type;
  int len;
  int stride;
};

struct EnumPropertyItem {
  int value;
  const char *identifier;
  int icon;
  const char *name;
  const char *description;
};

#define RNA_ENUM_ITEM_HEADING(name, description) {0, "", 0, name, description}

#define RNA_ENUM_ITEM_SEPR {0, "", 0, NULL, NULL}

#define RNA_ENUM_ITEM_SEPR_COLUMN RNA_ENUM_ITEM_HEADING("", NULL)
 
/* Extended versions with PropertyRNA argument. Used in particular by the bpy code to wrap all the
 * py-defined callbacks when defining a property using `bpy.props` module.
 *
 * The 'Transform' ones allow to add a transform step (applied after getting, or before setting the
 * value), which only modifies the value, but does not handle actual storage. Currently only used
 * by `bpy`, more details in the documentation of #BPyPropStore.
 */
using BooleanPropertyGetFunc = bool (*)(PointerRNA *ptr, PropertyRNA *prop);
using BooleanPropertySetFunc = void (*)(PointerRNA *ptr, PropertyRNA *prop, bool value);
using BooleanPropertyGetTransformFunc = bool (*)(PointerRNA *ptr,
                                                 PropertyRNA *prop,
                                                 bool value,
                                                 bool is_set);
using BooleanPropertySetTransformFunc =
    bool (*)(PointerRNA *ptr, PropertyRNA *prop, bool new_value, bool curr_value, bool is_set);
 
using BooleanArrayPropertyGetFunc = void (*)(PointerRNA *ptr, PropertyRNA *prop, bool *r_values);
using BooleanArrayPropertySetFunc = void (*)(PointerRNA *ptr,
                                             PropertyRNA *prop,
                                             const bool *r_values);
using BooleanArrayPropertyGetTransformFunc = void (*)(
    PointerRNA *ptr, PropertyRNA *prop, const bool *curr_values, bool is_set, bool *r_values);
using BooleanArrayPropertySetTransformFunc = void (*)(PointerRNA *ptr,
                                                      PropertyRNA *prop,
                                                      const bool *new_values,
                                                      const bool *curr_values,
                                                      bool is_set,
                                                      bool *r_values);
 
using IntPropertyGetFunc = int (*)(PointerRNA *ptr, PropertyRNA *prop);
using IntPropertySetFunc = void (*)(PointerRNA *ptr, PropertyRNA *prop, int value);
using IntPropertyGetTransformFunc = int (*)(PointerRNA *ptr,
                                            PropertyRNA *prop,
                                            int value,
                                            bool is_set);
using IntPropertySetTransformFunc =
    int (*)(PointerRNA *ptr, PropertyRNA *prop, int new_value, int curr_value, bool is_set);
using IntArrayPropertyGetFunc = void (*)(PointerRNA *ptr, PropertyRNA *prop, int *values);
using IntArrayPropertySetFunc = void (*)(PointerRNA *ptr, PropertyRNA *prop, const int *values);
using IntArrayPropertyGetTransformFunc = void (*)(
    PointerRNA *ptr, PropertyRNA *prop, const int *curr_values, bool is_set, int *r_values);
using IntArrayPropertySetTransformFunc = void (*)(PointerRNA *ptr,
                                                  PropertyRNA *prop,
                                                  const int *new_values,
                                                  const int *curr_values,
                                                  bool is_set,
                                                  int *r_values);
using IntPropertyRangeFunc =
    void (*)(PointerRNA *ptr, PropertyRNA *prop, int *min, int *max, int *softmin, int *softmax);
 
using FloatPropertyGetFunc = float (*)(PointerRNA *ptr, PropertyRNA *prop);
using FloatPropertySetFunc = void (*)(PointerRNA *ptr, PropertyRNA *prop, float value);
using FloatPropertyGetTransformFunc = float (*)(PointerRNA *ptr,
                                                PropertyRNA *prop,
                                                float value,
                                                bool is_set);
using FloatPropertySetTransformFunc =
    float (*)(PointerRNA *ptr, PropertyRNA *prop, float new_value, float curr_value, bool is_set);
using FloatArrayPropertyGetFunc = void (*)(PointerRNA *ptr, PropertyRNA *prop, float *values);
using FloatArrayPropertySetFunc = void (*)(PointerRNA *ptr,
                                           PropertyRNA *prop,
                                           const float *values);
using FloatArrayPropertyGetTransformFunc = void (*)(
    PointerRNA *ptr, PropertyRNA *prop, const float *curr_values, bool is_set, float *r_values);
using FloatArrayPropertySetTransformFunc = void (*)(PointerRNA *ptr,
                                                    PropertyRNA *prop,
                                                    const float *new_values,
                                                    const float *curr_values,
                                                    bool is_set,
                                                    float *r_values);
using FloatPropertyRangeFunc = void (*)(
    PointerRNA *ptr, PropertyRNA *prop, float *min, float *max, float *softmin, float *softmax);
 
using StringPropertyGetFunc = std::string (*)(PointerRNA *ptr, PropertyRNA *prop);
using StringPropertyLengthFunc = int (*)(PointerRNA *ptr, PropertyRNA *prop);
using StringPropertySetFunc = void (*)(PointerRNA *ptr,
                                       PropertyRNA *prop,
                                       const std::string &value);
using StringPropertyGetTransformFunc = std::string (*)(PointerRNA *ptr,
                                                       PropertyRNA *prop,
                                                       const std::string &value,
                                                       bool is_set);
using StringPropertySetTransformFunc = std::string (*)(PointerRNA *ptr,
                                                       PropertyRNA *prop,
                                                       const std::string &new_value,
                                                       const std::string &curr_value,
                                                       bool is_set);
 
struct StringPropertySearchVisitParams {
  std::string text;
  std::optional<std::string> info;
  /* Optional icon instead of #ICON_NONE. */
  std::optional<int> icon_id;
};
 
enum eStringPropertySearchFlag {
  PROP_STRING_SEARCH_SUPPORTED = (1 << 0),
  PROP_STRING_SEARCH_SORT = (1 << 1),
  PROP_STRING_SEARCH_SUGGESTION = (1 << 2),
};
ENUM_OPERATORS(eStringPropertySearchFlag, PROP_STRING_SEARCH_SUGGESTION)
 

using StringPropertySearchFunc =
    void (*)(const bContext *C,
             PointerRNA *ptr,
             PropertyRNA *prop,
             const char *edit_text,
             blender::FunctionRef<void(StringPropertySearchVisitParams)> visit_fn);

using StringPropertyPathFilterFunc = std::optional<std::string> (*)(const bContext *C,
                                                                    PointerRNA *ptr,
                                                                    PropertyRNA *prop);
 
using EnumPropertyGetFunc = int (*)(PointerRNA *ptr, PropertyRNA *prop);
using EnumPropertySetFunc = void (*)(PointerRNA *ptr, PropertyRNA *prop, int value);
using EnumPropertyGetTransformFunc = int (*)(PointerRNA *ptr,
                                             PropertyRNA *prop,
                                             int value,
                                             bool is_set);
using EnumPropertySetTransformFunc =
    int (*)(PointerRNA *ptr, PropertyRNA *prop, int new_value, int curr_value, bool is_set);
/* same as PropEnumItemFunc */
using EnumPropertyItemFunc = const EnumPropertyItem *(*)(bContext * C,
                                                         PointerRNA *ptr,
                                                         PropertyRNA *prop,
                                                         bool *r_free);
 
struct PropertyRNA;
 
/* Parameter List */
 
struct ParameterList {
  void *data;

  FunctionRNA *func;

  int alloc_size;
 
  int arg_count, ret_count;
};
 
struct ParameterIterator {
  ParameterList *parms;
  // PointerRNA funcptr; /* UNUSED */
  void *data;
  int size, offset;
 
  PropertyRNA *parm;
  bool valid;
};

struct ParameterDynAlloc {
  intptr_t array_tot;
  void *array;
};
 
/* Function */

enum FunctionFlag {
  FUNC_USE_SELF_ID = (1 << 11),

  FUNC_SELF_AS_RNA = (1 << 13),
  FUNC_NO_SELF = (1 << 0),
  FUNC_USE_SELF_TYPE = (1 << 1),
 
  /* Pass Main, bContext and/or ReportList. */
  FUNC_USE_MAIN = (1 << 2),
  FUNC_USE_CONTEXT = (1 << 3),
  FUNC_USE_REPORTS = (1 << 4),
 
  /***** Registering of Python subclasses. *****/
  FUNC_REGISTER = (1 << 5),
  FUNC_REGISTER_OPTIONAL = FUNC_REGISTER | (1 << 6),
  FUNC_ALLOW_WRITE = (1 << 12),
 
  /***** Internal flags. *****/
  FUNC_BUILTIN = (1 << 7),
  FUNC_EXPORT = (1 << 8),
  FUNC_RUNTIME = (1 << 9),
  FUNC_FREE_POINTERS = (1 << 10),
};
 
using CallFunc = void (*)(bContext *C, ReportList *reports, PointerRNA *ptr, ParameterList *parms);
 
struct FunctionRNA;
 
/* Struct */
 
enum StructFlag {
  STRUCT_ID = (1 << 0),
  STRUCT_ID_REFCOUNT = (1 << 1),
  STRUCT_UNDO = (1 << 2),
 
  /* internal flags */
  STRUCT_RUNTIME = (1 << 3),
  /* STRUCT_GENERATED = (1 << 4), */ /* UNUSED */
  STRUCT_FREE_POINTERS = (1 << 5),
  STRUCT_NO_IDPROPERTIES = (1 << 6),
  STRUCT_NO_DATABLOCK_IDPROPERTIES = (1 << 7),
  STRUCT_CONTAINS_DATABLOCK_IDPROPERTIES = (1 << 8),
  STRUCT_PUBLIC_NAMESPACE = (1 << 9),
  STRUCT_PUBLIC_NAMESPACE_INHERIT = (1 << 10),
  STRUCT_NO_CONTEXT_WITHOUT_OWNER_ID = (1 << 11),
};
 
using StructValidateFunc = int (*)(PointerRNA *ptr, void *data, bool *have_function);
using StructCallbackFunc = int (*)(bContext *C,
                                   PointerRNA *ptr,
                                   FunctionRNA *func,
                                   ParameterList *list);
using StructFreeFunc = void (*)(void *data);
using StructRegisterFunc = StructRNA *(*)(Main * bmain,
                                          ReportList *reports,
                                          void *data,
                                          const char *identifier,
                                          StructValidateFunc validate,
                                          StructCallbackFunc call,
                                          StructFreeFunc free);
using StructUnregisterFunc = bool (*)(Main *bmain, StructRNA *type);
using StructInstanceFunc = void **(*)(PointerRNA * ptr);
 
struct StructRNA;

struct BlenderRNA;

struct ExtensionRNA {
  void *data;
  StructRNA *srna;
  StructCallbackFunc call;
  StructFreeFunc free;
};

struct DeprecatedRNA {
  const char *note;
  short version;
  short removal_version;
};
 
/* Primitive types. */
 
struct PrimitiveStringRNA {
  const char *value;
};
 
struct PrimitiveIntRNA {
  int value;
};
 
struct PrimitiveFloatRNA {
  float value;
};
 
struct PrimitiveBooleanRNA {
  bool value;
};
 
#endif /* __RNA_TYPES_H__ */