source/blender/makesrna/RNA_types.h

   1 /*
   2  * ***** BEGIN GPL LICENSE BLOCK *****
   3  *
   4  * This program is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU General Public License
   6  * as published by the Free Software Foundation; either version 2
   7  * of the License, or (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program; if not, write to the Free Software Foundation,
  16  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  17  *
  18  * Contributor(s): Blender Foundation (2008).
  19  *
  20  * ***** END GPL LICENSE BLOCK *****
  21  */
  22
  23 /** \file blender/makesrna/RNA_types.h
  24  *  \ingroup RNA
  25  */
  26
  27
  28 #include "../blenlib/BLI_sys_types.h"
  29
  30 #ifndef __RNA_TYPES_H__
  31 #define __RNA_TYPES_H__
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 struct ParameterList;
  38 struct FunctionRNA;
  39 struct PropertyRNA;
  40 struct StructRNA;
  41 struct BlenderRNA;
  42 struct bContext;
  43 struct Main;
  44 struct ReportList;
  45
  46 /** Pointer
  47  *
  48  * RNA pointers are not a single C pointer but include the type,
  49  * and a pointer to the ID struct that owns the struct, since
  50  * in some cases this information is needed to correctly get/set
  51  * the properties and validate them. */
  52
  53 typedef struct PointerRNA {
  54         struct {
  55                 void *data;
  56         } id;
  57
  58         struct StructRNA *type;
  59         void *data;
  60 } PointerRNA;
  61
  62 typedef struct PropertyPointerRNA {
  63         PointerRNA ptr;
  64         struct PropertyRNA *prop;
  65 } PropertyPointerRNA;
  66
  67 /**
  68  * Stored result of a RNA path lookup (as used by anim-system)
  69  */
  70 typedef struct PathResolvedRNA {
  71         struct PointerRNA ptr;
  72         struct PropertyRNA *prop;
  73         /* -1 for non-array access */
  74         int prop_index;
  75 } PathResolvedRNA;
  76
  77 /* Property */
  78
  79 typedef enum PropertyType {
  80         PROP_BOOLEAN      = 0,
  81         PROP_INT          = 1,
  82         PROP_FLOAT        = 2,
  83         PROP_STRING       = 3,
  84         PROP_ENUM         = 4,
  85         PROP_POINTER      = 5,
  86         PROP_COLLECTION   = 6,
  87 } PropertyType;
  88
  89 /* also update rna_property_subtype_unit when you change this */
  90 typedef enum PropertyUnit {
  91         PROP_UNIT_NONE         = (0 << 16),
  92         PROP_UNIT_LENGTH       = (1 << 16),   /* m */
  93         PROP_UNIT_AREA         = (2 << 16),   /* m^2 */
  94         PROP_UNIT_VOLUME       = (3 << 16),   /* m^3 */
  95         PROP_UNIT_MASS         = (4 << 16),   /* kg */
  96         PROP_UNIT_ROTATION     = (5 << 16),   /* radians */
  97         PROP_UNIT_TIME         = (6 << 16),   /* frame */
  98         PROP_UNIT_VELOCITY     = (7 << 16),   /* m/s */
  99         PROP_UNIT_ACCELERATION = (8 << 16),   /* m/(s^2) */
 100         PROP_UNIT_CAMERA       = (9 << 16),   /* mm */
 101 } PropertyUnit;
 102
 103 #define RNA_SUBTYPE_UNIT(subtype)       ((subtype) &  0x00FF0000)
 104 #define RNA_SUBTYPE_VALUE(subtype)      ((subtype) & ~0x00FF0000)
 105 #define RNA_SUBTYPE_UNIT_VALUE(subtype) ((subtype) >> 16)
 106
 107 #define RNA_ENUM_BITFLAG_SIZE 32
 108
 109 #define RNA_TRANSLATION_PREC_DEFAULT 5
 110
 111 /* also update enums in bpy_props.c when adding items here
 112  * watch it: these values are written to files as part of
 113  * node socket button subtypes!
 114  */
 115 typedef enum PropertySubType {
 116         PROP_NONE              = 0,
 117
 118         /* strings */
 119         PROP_FILEPATH          = 1,
 120         PROP_DIRPATH           = 2,
 121         PROP_FILENAME          = 3,
 122         PROP_BYTESTRING        = 4, /* a string which should be represented as bytes in python, NULL terminated though. */
 123         /* 5 was used by "PROP_TRANSLATE" sub-type, which is now a flag. */
 124         PROP_PASSWORD          = 6, /* a string which should not be displayed in UI */
 125
 126         /* numbers */
 127         PROP_PIXEL             = 12,
 128         PROP_UNSIGNED          = 13,
 129         PROP_PERCENTAGE        = 14,
 130         PROP_FACTOR            = 15,
 131         PROP_ANGLE             = 16 | PROP_UNIT_ROTATION,
 132         PROP_TIME              = 17 | PROP_UNIT_TIME,
 133         /* distance in 3d space, don't use for pixel distance for eg. */
 134         PROP_DISTANCE          = 18 | PROP_UNIT_LENGTH,
 135         PROP_DISTANCE_CAMERA   = 19 | PROP_UNIT_CAMERA,
 136
 137         /* number arrays */
 138         PROP_COLOR             = 20,
 139         PROP_TRANSLATION       = 21 | PROP_UNIT_LENGTH,
 140         PROP_DIRECTION         = 22,
 141         PROP_VELOCITY          = 23 | PROP_UNIT_VELOCITY,
 142         PROP_ACCELERATION      = 24 | PROP_UNIT_ACCELERATION,
 143         PROP_MATRIX            = 25,
 144         PROP_EULER             = 26 | PROP_UNIT_ROTATION,
 145         PROP_QUATERNION        = 27,
 146         PROP_AXISANGLE         = 28,
 147         PROP_XYZ               = 29,
 148         PROP_XYZ_LENGTH        = 29 | PROP_UNIT_LENGTH,
 149         PROP_COLOR_GAMMA       = 30, /* used for colors which would be color managed before display */
 150         PROP_COORDS            = 31, /* generic array, no units applied, only that x/y/z/w are used (python vec) */
 151
 152         /* booleans */
 153         PROP_LAYER             = 40,
 154         PROP_LAYER_MEMBER      = 41,
 155 } PropertySubType;
 156
 157 /* Make sure enums are updated with these */
 158 /* HIGHEST FLAG IN USE: 1 << 31
 159  * FREE FLAGS: 2, 3, 7, 9, 11, 13, 14, 15, 30 */
 160 typedef enum PropertyFlag {
 161         /* editable means the property is editable in the user
 162          * interface, properties are editable by default except
 163          * for pointers and collections. */
 164         PROP_EDITABLE                = (1 << 0),
 165
 166         /* this property is editable even if it is lib linked,
 167          * meaning it will get lost on reload, but it's useful
 168          * for editing. */
 169         PROP_LIB_EXCEPTION           = (1 << 16),
 170
 171         /* animatable means the property can be driven by some
 172          * other input, be it animation curves, expressions, ..
 173          * properties are animatable by default except for pointers
 174          * and collections */
 175         PROP_ANIMATABLE              = (1 << 1),
 176
 177         /* This flag means when the property's widget is in 'textedit' mode, it will be updated
 178          * after every typed char, instead of waiting final validation. Used e.g. for text searchbox.
 179          * It will also cause UI_BUT_VALUE_CLEAR to be set for text buttons. We could add an own flag
 180          * for search/filter properties, but this works just fine for now. */
 181         PROP_TEXTEDIT_UPDATE         = (1 << 31),
 182
 183         /* icon */
 184         PROP_ICONS_CONSECUTIVE       = (1 << 12),
 185
 186         /* hidden in  the user interface */
 187         PROP_HIDDEN                  = (1 << 19),
 188         /* do not write in presets */
 189         PROP_SKIP_SAVE               = (1 << 28),
 190
 191         /* numbers */
 192
 193         /* each value is related proportionally (object scale, image size) */
 194         PROP_PROPORTIONAL            = (1 << 26),
 195
 196         /* pointers */
 197         PROP_ID_REFCOUNT             = (1 << 6),
 198
 199         /* disallow assigning a variable to its self, eg an object tracking its self
 200          * only apply this to types that are derived from an ID ()*/
 201         PROP_ID_SELF_CHECK           = (1 << 20),
 202         /* use for...
 203          * - pointers: in the UI and python so unsetting or setting to None won't work
 204          * - strings: so our internal generated get/length/set functions know to do NULL checks before access [#30865] */
 205         PROP_NEVER_NULL              = (1 << 18),
 206         /* currently only used for UI, this is similar to PROP_NEVER_NULL
 207          * except that the value may be NULL at times, used for ObData, where an Empty's will be NULL
 208          * but setting NULL on a mesh object is not possible. So, if its not NULL, setting NULL cant be done! */
 209         PROP_NEVER_UNLINK            = (1 << 25),
 210
 211         /* flag contains multiple enums.
 212          * note: not to be confused with prop->enumbitflags
 213          * this exposes the flag as multiple options in python and the UI.
 214          *
 215          * note: these can't be animated so use with care.
 216          */
 217         PROP_ENUM_FLAG               = (1 << 21),
 218
 219         /* need context for update function */
 220         PROP_CONTEXT_UPDATE          = (1 << 22),
 221         PROP_CONTEXT_PROPERTY_UPDATE = PROP_CONTEXT_UPDATE | (1 << 27),
 222
 223         /* registering */
 224         PROP_REGISTER                = (1 << 4),
 225         PROP_REGISTER_OPTIONAL       = PROP_REGISTER | (1 << 5),
 226
 227         /* Use for arrays or for any data that should not have a reference kept
 228          * most common case is functions that return arrays where the array */
 229         PROP_THICK_WRAP              = (1 << 23),
 230
 231         PROP_EXPORT                  = (1 << 8),  /* XXX Is this still used? makesrna.c seems to ignore it currently... */
 232         PROP_IDPROPERTY              = (1 << 10), /* This is an IDProperty, not a DNA one. */
 233         PROP_DYNAMIC                 = (1 << 17), /* for dynamic arrays, and retvals of type string */
 234         PROP_ENUM_NO_CONTEXT         = (1 << 24), /* for enum that shouldn't be contextual */
 235         PROP_ENUM_NO_TRANSLATE       = (1 << 29), /* for enums not to be translated (e.g. renderlayers' names in nodes) */
 236 } PropertyFlag;
 237
 238 /* Function parameters flags.
 239  * WARNING: 16bits only. */
 240 typedef enum ParameterFlag {
 241         PARM_REQUIRED                = (1 << 0),
 242         PARM_OUTPUT                  = (1 << 1),
 243         PARM_RNAPTR                  = (1 << 2),
 244         /* This allows for non-breaking API updates, when adding non-critical new parameter to a callback function.
 245          * This way, old py code defining funcs without that parameter would still work.
 246          * WARNING: any parameter after the first PYFUNC_OPTIONAL one will be considered as optional!
 247          * NOTE: only for input parameters!
 248          */
 249         PARM_PYFUNC_OPTIONAL         = (1 << 3),
 250 } ParameterFlag;
 251
 252 struct CollectionPropertyIterator;
 253 struct Link;
 254 typedef int (*IteratorSkipFunc)(struct CollectionPropertyIterator *iter, void *data);
 255
 256 typedef struct ListBaseIterator {
 257         struct Link *link;
 258         int flag;
 259         IteratorSkipFunc skip;
 260 } ListBaseIterator;
 261
 262 typedef struct ArrayIterator {
 263         char *ptr;
 264         char *endptr;  /* past the last valid pointer, only for comparisons, ignores skipped values */
 265         void *free_ptr; /* will be freed if set */
 266         int itemsize;
 267
 268         /* array length with no skip functions applied, take care not to compare against index from animsys
 269          * or python indices */
 270         int length;
 271
 272         /* optional skip function, when set the array as viewed by rna can contain only a subset of the members.
 273          * this changes indices so quick array index lookups are not possible when skip function is used. */
 274         IteratorSkipFunc skip;
 275 } ArrayIterator;
 276
 277 typedef struct CollectionPropertyIterator {
 278         /* internal */
 279         PointerRNA parent;
 280         PointerRNA builtin_parent;
 281         struct PropertyRNA *prop;
 282         union {
 283                 ArrayIterator array;
 284                 ListBaseIterator listbase;
 285                 void *custom;
 286         } internal;
 287         int idprop;
 288         int level;
 289
 290         /* external */
 291         PointerRNA ptr;
 292         int valid;
 293 } CollectionPropertyIterator;
 294
 295 typedef struct CollectionPointerLink {
 296         struct CollectionPointerLink *next, *prev;
 297         PointerRNA ptr;
 298 } CollectionPointerLink;
 299
 300 /* Copy of ListBase for RNA... */
 301 typedef struct CollectionListBase {
 302         struct CollectionPointerLink *first, *last;
 303 } CollectionListBase;
 304
 305 typedef enum RawPropertyType {
 306         PROP_RAW_UNSET = -1,
 307         PROP_RAW_INT, // XXX - abused for types that are not set, eg. MFace.verts, needs fixing.
 308         PROP_RAW_SHORT,
 309         PROP_RAW_CHAR,
 310         PROP_RAW_DOUBLE,
 311         PROP_RAW_FLOAT
 312 } RawPropertyType;
 313
 314 typedef struct RawArray {
 315         void *array;
 316         RawPropertyType type;
 317         int len;
 318         int stride;
 319 } RawArray;
 320
 321 /**
 322  * This struct is are typically defined in arrays which define an *enum* for RNA,
 323  * which is used by the RNA API both for user-interface and the Python API.
 324  */
 325 typedef struct EnumPropertyItem {
 326         /** The internal value of the enum, not exposed to users. */
 327         int value;
 328         /**
 329          * Note that identifiers must be unique within the array,
 330          * by convention they're upper case with underscores for separators.
 331          * - An empty string is used to define menu separators.
 332          * - NULL denotes the end of the array of items.
 333          */
 334         const char *identifier;
 335         /** Optional icon, typically 'ICON_NONE' */
 336         int icon;
 337         /** Name displayed in the interface. */
 338         const char *name;
 339         /** Longer description used in the interface. */
 340         const char *description;
 341 } EnumPropertyItem;
 342
 343 /* extended versions with PropertyRNA argument */
 344 typedef int (*BooleanPropertyGetFunc)(struct PointerRNA *ptr, struct PropertyRNA *prop);
 345 typedef void (*BooleanPropertySetFunc)(struct PointerRNA *ptr, struct PropertyRNA *prop, int value);
 346 typedef void (*BooleanArrayPropertyGetFunc)(struct PointerRNA *ptr, struct PropertyRNA *prop, int *values);
 347 typedef void (*BooleanArrayPropertySetFunc)(struct PointerRNA *ptr, struct PropertyRNA *prop, const int *values);
 348 typedef int (*IntPropertyGetFunc)(struct PointerRNA *ptr, struct PropertyRNA *prop);
 349 typedef void (*IntPropertySetFunc)(struct PointerRNA *ptr, struct PropertyRNA *prop, int value);
 350 typedef void (*IntArrayPropertyGetFunc)(struct PointerRNA *ptr, struct PropertyRNA *prop, int *values);
 351 typedef void (*IntArrayPropertySetFunc)(struct PointerRNA *ptr, struct PropertyRNA *prop, const int *values);
 352 typedef void (*IntPropertyRangeFunc)(struct PointerRNA *ptr, struct PropertyRNA *prop, int *min, int *max, int *softmin, int *softmax);
 353 typedef float (*FloatPropertyGetFunc)(struct PointerRNA *ptr, struct PropertyRNA *prop);
 354 typedef void (*FloatPropertySetFunc)(struct PointerRNA *ptr, struct PropertyRNA *prop, float value);
 355 typedef void (*FloatArrayPropertyGetFunc)(struct PointerRNA *ptr, struct PropertyRNA *prop, float *values);
 356 typedef void (*FloatArrayPropertySetFunc)(struct PointerRNA *ptr, struct PropertyRNA *prop, const float *values);
 357 typedef void (*FloatPropertyRangeFunc)(struct PointerRNA *ptr, struct PropertyRNA *prop, float *min, float *max, float *softmin, float *softmax);
 358 typedef void (*StringPropertyGetFunc)(struct PointerRNA *ptr, struct PropertyRNA *prop, char *value);
 359 typedef int (*StringPropertyLengthFunc)(struct PointerRNA *ptr, struct PropertyRNA *prop);
 360 typedef void (*StringPropertySetFunc)(struct PointerRNA *ptr, struct PropertyRNA *prop, const char *value);
 361 typedef int (*EnumPropertyGetFunc)(struct PointerRNA *ptr, struct PropertyRNA *prop);
 362 typedef void (*EnumPropertySetFunc)(struct PointerRNA *ptr, struct PropertyRNA *prop, int value);
 363 /* same as PropEnumItemFunc */
 364 typedef EnumPropertyItem *(*EnumPropertyItemFunc)(struct bContext *C, PointerRNA *ptr, struct PropertyRNA *prop, bool *r_free);
 365
 366 typedef struct PropertyRNA PropertyRNA;
 367
 368 /* Parameter List */
 369
 370 typedef struct ParameterList {
 371         /* storage for parameters */
 372         void *data;
 373
 374         /* function passed at creation time */
 375         struct FunctionRNA *func;
 376
 377         /* store the parameter size */
 378         int alloc_size;
 379
 380         int arg_count, ret_count;
 381 } ParameterList;
 382
 383 typedef struct ParameterIterator {
 384         struct ParameterList *parms;
 385         /* PointerRNA funcptr; */ /*UNUSED*/
 386         void *data;
 387         int size, offset;
 388
 389         PropertyRNA *parm;
 390         int valid;
 391 } ParameterIterator;
 392
 393 /* mainly to avoid confusing casts */
 394 typedef struct ParameterDynAlloc {
 395         intptr_t array_tot; /* important, this breaks when set to an int */
 396         void *array;
 397 } ParameterDynAlloc;
 398
 399 /* Function */
 400
 401 typedef enum FunctionFlag {
 402         FUNC_NO_SELF           = (1 << 0), /* for static functions */
 403         FUNC_USE_SELF_TYPE     = (1 << 1), /* for class methods, only used when FUNC_NO_SELF is set */
 404         FUNC_USE_MAIN          = (1 << 2),
 405         FUNC_USE_CONTEXT       = (1 << 3),
 406         FUNC_USE_REPORTS       = (1 << 4),
 407         FUNC_USE_SELF_ID       = (1 << 11),
 408         FUNC_ALLOW_WRITE       = (1 << 12),
 409
 410         /* registering */
 411         FUNC_REGISTER          = (1 << 5),
 412         FUNC_REGISTER_OPTIONAL = FUNC_REGISTER | (1 << 6),
 413
 414         /* internal flags */
 415         FUNC_BUILTIN           = (1 << 7),
 416         FUNC_EXPORT            = (1 << 8),
 417         FUNC_RUNTIME           = (1 << 9),
 418         FUNC_FREE_POINTERS     = (1 << 10),
 419 } FunctionFlag;
 420
 421 typedef void (*CallFunc)(struct bContext *C, struct ReportList *reports, PointerRNA *ptr, ParameterList *parms);
 422
 423 typedef struct FunctionRNA FunctionRNA;
 424
 425 /* Struct */
 426
 427 typedef enum StructFlag {
 428         /* indicates that this struct is an ID struct, and to use refcounting */
 429         STRUCT_ID              = (1 << 0),
 430         STRUCT_ID_REFCOUNT     = (1 << 1),
 431         STRUCT_UNDO            = (1 << 2), /* defaults on, clear for user preferences and similar */
 432
 433         /* internal flags */
 434         STRUCT_RUNTIME         = (1 << 3),
 435         STRUCT_GENERATED       = (1 << 4),
 436         STRUCT_FREE_POINTERS   = (1 << 5),
 437         STRUCT_NO_IDPROPERTIES = (1 << 6), /* Menus and Panels don't need properties */
 438         STRUCT_NO_DATABLOCK_IDPROPERTIES = (1 << 7), /* e.g. for Operator */
 439         STRUCT_CONTAINS_DATABLOCK_IDPROPERTIES = (1 << 8), /* for PropertyGroup which contains pointers to datablocks */
 440 } StructFlag;
 441
 442 typedef int (*StructValidateFunc)(struct PointerRNA *ptr, void *data, int *have_function);
 443 typedef int (*StructCallbackFunc)(struct bContext *C, struct PointerRNA *ptr, struct FunctionRNA *func, ParameterList *list);
 444 typedef void (*StructFreeFunc)(void *data);
 445 typedef struct StructRNA *(*StructRegisterFunc)(
 446         struct Main *bmain, struct ReportList *reports, void *data, const char *identifier,
 447         StructValidateFunc validate, StructCallbackFunc call, StructFreeFunc free);
 448
 449 typedef void (*StructUnregisterFunc)(struct Main *bmain, struct StructRNA *type);
 450 typedef void **(*StructInstanceFunc)(PointerRNA *ptr);
 451
 452 typedef struct StructRNA StructRNA;
 453
 454 /* Blender RNA
 455  *
 456  * Root RNA data structure that lists all struct types. */
 457
 458 typedef struct BlenderRNA BlenderRNA;
 459
 460 /* Extending
 461  *
 462  * This struct must be embedded in *Type structs in
 463  * order to make then definable through RNA. */
 464
 465 typedef struct ExtensionRNA {
 466         void *data;
 467         StructRNA *srna;
 468         StructCallbackFunc call;
 469         StructFreeFunc free;
 470
 471 } ExtensionRNA;
 472
 473 #ifdef __cplusplus
 474 }
 475 #endif
 476
 477 #endif /* __RNA_TYPES_H__ */