source/blender/python/intern/bpy_rna.hh

   1 /* SPDX-FileCopyrightText: 2023 Blender Authors
   2  *
   3  * SPDX-License-Identifier: GPL-2.0-or-later */
   4
   5 /** \file
   6  * \ingroup pythonintern
   7  */
   8
   9 #pragma once
  10
  11 #include <Python.h>
  12
  13 #include <optional>
  14
  15 /* --- bpy build options --- */
  16 #include "intern/rna_internal_types.hh"
  17 #ifdef WITH_PYTHON_SAFETY
  18
  19 /**
  20  * Play it safe and keep optional for now,
  21  * need to test further now this affects looping on 10000's of verts for eg.
  22  */
  23 #  define USE_WEAKREFS
  24
  25 /* method to invalidate removed py data, XXX, slow to remove objects, otherwise no overhead */
  26 // #define USE_PYRNA_INVALIDATE_GC
  27
  28 /* different method */
  29 #  define USE_PYRNA_INVALIDATE_WEAKREF
  30
  31 /* support for inter references, currently only needed for corner case */
  32 #  define USE_PYRNA_STRUCT_REFERENCE
  33
  34 #else /* WITH_PYTHON_SAFETY */
  35
  36 /* default, no defines! */
  37
  38 #endif /* !WITH_PYTHON_SAFETY */
  39
  40 /* Sanity checks on above defines. */
  41 #if defined(USE_PYRNA_INVALIDATE_WEAKREF) && !defined(USE_WEAKREFS)
  42 #  define USE_WEAKREFS
  43 #endif
  44
  45 #if defined(USE_PYRNA_INVALIDATE_GC) && defined(USE_PYRNA_INVALIDATE_WEAKREF)
  46 #  error "Only 1 reference check method at a time!"
  47 #endif
  48
  49 /* only used by operator introspection get_rna(), this is only used for doc gen
  50  * so prefer the leak to the memory bloat for now. */
  51 // #define PYRNA_FREE_SUPPORT
  52
  53 /* use real collection iterators rather than faking with a list
  54  * this is needed so enums can be iterated over without crashing,
  55  * since finishing the iteration frees temp allocated enums */
  56 #define USE_PYRNA_ITER
  57
  58 /* --- end bpy build options --- */
  59
  60 struct ID;
  61
  62 /**
  63  * Sub-classes of #pyrna_struct_Type which support idprop definitions use this as a meta-class.
  64  * \note tp_base member is set to `&PyType_Type` on initialization.
  65  */
  66 extern PyTypeObject pyrna_struct_meta_idprop_Type;
  67 extern PyTypeObject pyrna_struct_Type;
  68 extern PyTypeObject pyrna_prop_Type;
  69 extern PyTypeObject pyrna_prop_array_Type;
  70 extern PyTypeObject pyrna_prop_collection_Type;
  71 extern PyTypeObject pyrna_func_Type;
  72
  73 #define BPy_StructRNA_Check(v) (PyObject_TypeCheck(v, &pyrna_struct_Type))
  74 #define BPy_StructRNA_CheckExact(v) (Py_TYPE(v) == &pyrna_struct_Type)
  75 #define BPy_PropertyRNA_Check(v) (PyObject_TypeCheck(v, &pyrna_prop_Type))
  76 #define BPy_PropertyRNA_CheckExact(v) (Py_TYPE(v) == &pyrna_prop_Type)
  77
  78 #define PYRNA_STRUCT_CHECK_OBJ(obj) \
  79   if (UNLIKELY(pyrna_struct_validity_check(obj) == -1)) { \
  80     return NULL; \
  81   } \
  82   (void)0
  83 #define PYRNA_STRUCT_CHECK_INT(obj) \
  84   if (UNLIKELY(pyrna_struct_validity_check(obj) == -1)) { \
  85     return -1; \
  86   } \
  87   (void)0
  88
  89 #define PYRNA_PROP_CHECK_OBJ(obj) \
  90   if (UNLIKELY(pyrna_prop_validity_check(obj) == -1)) { \
  91     return NULL; \
  92   } \
  93   (void)0
  94 #define PYRNA_PROP_CHECK_INT(obj) \
  95   if (UNLIKELY(pyrna_prop_validity_check(obj) == -1)) { \
  96     return -1; \
  97   } \
  98   (void)0
  99
 100 #define PYRNA_STRUCT_CHECK_OBJ_UNLESS(obj, unless) \
 101   { \
 102     const BPy_StructRNA *_obj = obj; \
 103     if (UNLIKELY(pyrna_struct_validity_check_only(_obj) == -1) && !(unless)) { \
 104       pyrna_struct_validity_exception_only(_obj); \
 105       return NULL; \
 106     } \
 107   } \
 108   (void)0
 109
 110 #define PYRNA_STRUCT_IS_VALID(pysrna) (LIKELY(((BPy_StructRNA *)(pysrna))->ptr->type != NULL))
 111 #define PYRNA_PROP_IS_VALID(pysrna) (LIKELY(((BPy_PropertyRNA *)(pysrna))->ptr->type != NULL))
 112
 113 /* 'in_weakreflist' MUST be aligned */
 114
 115 struct BPy_DummyPointerRNA {
 116   PyObject_HEAD /* Required Python macro. */
 117 #ifdef USE_WEAKREFS
 118   PyObject *in_weakreflist;
 119 #endif
 120
 121   std::optional<PointerRNA> ptr;
 122 };
 123
 124 struct BPy_StructRNA {
 125   PyObject_HEAD /* Required Python macro. */
 126 #ifdef USE_WEAKREFS
 127   PyObject *in_weakreflist;
 128 #endif
 129
 130   std::optional<PointerRNA> ptr;
 131
 132 #ifdef USE_PYRNA_STRUCT_REFERENCE
 133   /* generic PyObject we hold a reference to, example use:
 134    * hold onto the collection iterator to prevent it from freeing allocated data we may use */
 135   PyObject *reference;
 136 #endif /* !USE_PYRNA_STRUCT_REFERENCE */
 137
 138 #ifdef PYRNA_FREE_SUPPORT
 139   /** Needed in some cases if ptr.data is created on the fly, free when deallocating. */
 140   bool freeptr;
 141 #endif /* PYRNA_FREE_SUPPORT */
 142 };
 143
 144 struct BPy_PropertyRNA {
 145   PyObject_HEAD /* Required Python macro. */
 146 #ifdef USE_WEAKREFS
 147   PyObject *in_weakreflist;
 148 #endif
 149
 150   std::optional<PointerRNA> ptr;
 151   PropertyRNA *prop;
 152 };
 153
 154 struct BPy_PropertyArrayRNA {
 155   PyObject_HEAD /* Required Python macro. */
 156
 157   /* START Must match #BPy_PropertyRNA. */
 158
 159 #ifdef USE_WEAKREFS
 160   PyObject *in_weakreflist;
 161 #endif
 162
 163   std::optional<PointerRNA> ptr;
 164   PropertyRNA *prop;
 165
 166   /* END Must match #BPy_PropertyRNA. */
 167
 168   /* Arystan: this is a hack to allow sub-item r/w access like: face.uv[n][m] */
 169   /** Array dimension, e.g: 0 for face.uv, 2 for face.uv[n][m], etc. */
 170   int arraydim;
 171   /** Array first item offset, e.g. if face.uv is [4][2], arrayoffset for face.uv[n] is 2n. */
 172   int arrayoffset;
 173 };
 174
 175 struct BPy_PropertyCollectionIterRNA {
 176   PyObject_HEAD /* Required Python macro. */
 177 #ifdef USE_WEAKREFS
 178   PyObject *in_weakreflist;
 179 #endif
 180
 181   /* collection iterator specific parts */
 182   std::optional<CollectionPropertyIterator> iter;
 183 };
 184
 185 struct BPy_FunctionRNA {
 186   PyObject_HEAD /* Required Python macro. */
 187 #ifdef USE_WEAKREFS
 188   PyObject *in_weakreflist;
 189 #endif
 190
 191   std::optional<PointerRNA> ptr;
 192   FunctionRNA *func;
 193 };
 194
 195 StructRNA *srna_from_self(PyObject *self, const char *error_prefix);
 196 StructRNA *pyrna_struct_as_srna(PyObject *self, bool parent, const char *error_prefix);
 197
 198 void BPY_rna_init();
 199 void BPY_rna_exit();
 200 PyObject *BPY_rna_module();
 201 void BPY_update_rna_module();
 202 // PyObject *BPY_rna_doc();
 203 PyObject *BPY_rna_types();
 204 void BPY_rna_types_finalize_external_types(PyObject *submodule);
 205
 206 PyObject *pyrna_struct_CreatePyObject_with_primitive_support(PointerRNA *ptr);
 207 PyObject *pyrna_struct_CreatePyObject(PointerRNA *ptr);
 208 PyObject *pyrna_prop_CreatePyObject(PointerRNA *ptr, PropertyRNA *prop);
 209
 210 /* Made public for other modules which don't deal closely with RNA. */
 211 PyObject *pyrna_id_CreatePyObject(ID *id);
 212 bool pyrna_id_FromPyObject(PyObject *obj, ID **id);
 213 bool pyrna_id_CheckPyObject(PyObject *obj);
 214
 215 /* operators also need this to set args */
 216 int pyrna_pydict_to_props(PointerRNA *ptr, PyObject *kw, bool all_args, const char *error_prefix);
 217 PyObject *pyrna_prop_to_py(PointerRNA *ptr, PropertyRNA *prop);
 218
 219 int pyrna_deferred_register_class(StructRNA *srna, PyTypeObject *py_class);
 220
 221 const PointerRNA *pyrna_struct_as_ptr(PyObject *py_obj, const StructRNA *srna);
 222 const PointerRNA *pyrna_struct_as_ptr_or_null(PyObject *py_obj, const StructRNA *srna);
 223
 224 /**
 225  * Struct used for RNA argument parsing functions:
 226  * - #pyrna_struct_as_ptr_parse
 227  * - #pyrna_struct_as_ptr_or_null_parse
 228  */
 229 struct BPy_StructRNA_Parse {
 230   /** The struct RNA must match this type. */
 231   StructRNA *type;
 232   /** Result, may be `PointerRNA_NULL` if #pyrna_struct_as_ptr_or_null_parse is used. */
 233   const PointerRNA *ptr;
 234 };
 235
 236 /**
 237  * Sets #BPy_StructRNA_Parse.ptr to the value in the #BPy_StructRNA.ptr (from `o`)
 238  * or raise an error if the type isn't a #BPy_StructRNA.
 239  *
 240  * Use with #PyArg_ParseTuple's `O&` formatting.
 241  */
 242 int pyrna_struct_as_ptr_parse(PyObject *o, void *p);
 243 /**
 244  * A version of #pyrna_struct_as_ptr_parse that maps Python's `None` to #PointerRNA_NULL.
 245  */
 246 int pyrna_struct_as_ptr_or_null_parse(PyObject *o, void *p);
 247
 248 void pyrna_struct_type_extend_capi(StructRNA *srna, PyMethodDef *method, PyGetSetDef *getset);
 249
 250 void pyrna_alloc_types();
 251
 252 /* Primitive type conversion. */
 253
 254 int pyrna_py_to_array(
 255     PointerRNA *ptr, PropertyRNA *prop, char *param_data, PyObject *py, const char *error_prefix);
 256 int pyrna_py_to_array_index(PointerRNA *ptr,
 257                             PropertyRNA *prop,
 258                             int arraydim,
 259                             int arrayoffset,
 260                             int index,
 261                             PyObject *py,
 262                             const char *error_prefix);
 263 PyObject *pyrna_array_index(PointerRNA *ptr, PropertyRNA *prop, int index);
 264
 265 PyObject *pyrna_py_from_array(PointerRNA *ptr, PropertyRNA *prop);
 266 PyObject *pyrna_py_from_array_index(BPy_PropertyArrayRNA *self,
 267                                     PointerRNA *ptr,
 268                                     PropertyRNA *prop,
 269                                     int index);
 270 PyObject *pyrna_math_object_from_array(PointerRNA *ptr, PropertyRNA *prop);
 271 int pyrna_array_contains_py(PointerRNA *ptr, PropertyRNA *prop, PyObject *value);
 272
 273 bool pyrna_write_check();
 274 void pyrna_write_set(bool val);
 275
 276 void pyrna_invalidate(BPy_DummyPointerRNA *self);
 277
 278 int pyrna_struct_validity_check_only(const BPy_StructRNA *pysrna);
 279 void pyrna_struct_validity_exception_only(const BPy_StructRNA *pysrna);
 280 int pyrna_struct_validity_check(const BPy_StructRNA *pysrna);
 281
 282 int pyrna_prop_validity_check(const BPy_PropertyRNA *self);
 283
 284 /* bpy.utils.(un)register_class */
 285 extern PyMethodDef meth_bpy_register_class;
 286 extern PyMethodDef meth_bpy_unregister_class;
 287
 288 /* bpy.utils._bl_owner_(get/set) */
 289 extern PyMethodDef meth_bpy_owner_id_set;
 290 extern PyMethodDef meth_bpy_owner_id_get;
 291
 292 extern BPy_StructRNA *bpy_context_module;