1 /*
2  * This program is free software; you can redistribute it and/or
3  * modify it under the terms of the GNU General Public License
4  * as published by the Free Software Foundation; either version 2
5  * of the License, or (at your option) any later version.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * along with this program; if not, write to the Free Software Foundation,
14  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
15  */
16 
17 /** \file
18  * \ingroup RNA
19  */
20 
21 #pragma once
22 
23 #include "DNA_listBase.h"
24 
25 #include "RNA_types.h"
26 
27 struct BlenderRNA;
28 struct CollectionPropertyIterator;
29 struct ContainerRNA;
30 struct FunctionRNA;
31 struct GHash;
32 struct IDOverrideLibrary;
33 struct IDOverrideLibraryPropertyOperation;
34 struct IDProperty;
35 struct Main;
36 struct PointerRNA;
37 struct PropertyRNA;
38 struct ReportList;
39 struct Scene;
40 struct StructRNA;
41 struct bContext;
42 
43 typedef struct IDProperty IDProperty;
44 
45 /* store local properties here */
46 #define RNA_IDP_UI "_RNA_UI"
47 
48 /* Function Callbacks */
49 
50 typedef void (*UpdateFunc)(struct Main *main, struct Scene *scene, struct PointerRNA *ptr);
51 typedef void (*ContextPropUpdateFunc)(struct bContext *C,
52                                       struct PointerRNA *ptr,
53                                       struct PropertyRNA *prop);
54 typedef void (*ContextUpdateFunc)(struct bContext *C, struct PointerRNA *ptr);
55 typedef int (*EditableFunc)(struct PointerRNA *ptr, const char **r_info);
56 typedef int (*ItemEditableFunc)(struct PointerRNA *ptr, int index);
57 typedef struct IDProperty *(*IDPropertiesFunc)(struct PointerRNA *ptr, bool create);
58 typedef struct StructRNA *(*StructRefineFunc)(struct PointerRNA *ptr);
59 typedef char *(*StructPathFunc)(struct PointerRNA *ptr);
60 
61 typedef int (*PropArrayLengthGetFunc)(struct PointerRNA *ptr, int length[RNA_MAX_ARRAY_DIMENSION]);
62 typedef bool (*PropBooleanGetFunc)(struct PointerRNA *ptr);
63 typedef void (*PropBooleanSetFunc)(struct PointerRNA *ptr, bool value);
64 typedef void (*PropBooleanArrayGetFunc)(struct PointerRNA *ptr, bool *values);
65 typedef void (*PropBooleanArraySetFunc)(struct PointerRNA *ptr, const bool *values);
66 typedef int (*PropIntGetFunc)(struct PointerRNA *ptr);
67 typedef void (*PropIntSetFunc)(struct PointerRNA *ptr, int value);
68 typedef void (*PropIntArrayGetFunc)(struct PointerRNA *ptr, int *values);
69 typedef void (*PropIntArraySetFunc)(struct PointerRNA *ptr, const int *values);
70 typedef void (*PropIntRangeFunc)(
71     struct PointerRNA *ptr, int *min, int *max, int *softmin, int *softmax);
72 typedef float (*PropFloatGetFunc)(struct PointerRNA *ptr);
73 typedef void (*PropFloatSetFunc)(struct PointerRNA *ptr, float value);
74 typedef void (*PropFloatArrayGetFunc)(struct PointerRNA *ptr, float *values);
75 typedef void (*PropFloatArraySetFunc)(struct PointerRNA *ptr, const float *values);
76 typedef void (*PropFloatRangeFunc)(
77     struct PointerRNA *ptr, float *min, float *max, float *softmin, float *softmax);
78 typedef void (*PropStringGetFunc)(struct PointerRNA *ptr, char *value);
79 typedef int (*PropStringLengthFunc)(struct PointerRNA *ptr);
80 typedef void (*PropStringSetFunc)(struct PointerRNA *ptr, const char *value);
81 typedef int (*PropEnumGetFunc)(struct PointerRNA *ptr);
82 typedef void (*PropEnumSetFunc)(struct PointerRNA *ptr, int value);
83 typedef const EnumPropertyItem *(*PropEnumItemFunc)(struct bContext *C,
84                                                     struct PointerRNA *ptr,
85                                                     struct PropertyRNA *prop,
86                                                     bool *r_free);
87 typedef PointerRNA (*PropPointerGetFunc)(struct PointerRNA *ptr);
88 typedef StructRNA *(*PropPointerTypeFunc)(struct PointerRNA *ptr);
89 typedef void (*PropPointerSetFunc)(struct PointerRNA *ptr,
90                                    const PointerRNA value,
91                                    struct ReportList *reports);
92 typedef bool (*PropPointerPollFunc)(struct PointerRNA *ptr, const PointerRNA value);
93 typedef bool (*PropPointerPollFuncPy)(struct PointerRNA *ptr,
94                                       const PointerRNA value,
95                                       const PropertyRNA *prop);
96 typedef void (*PropCollectionBeginFunc)(struct CollectionPropertyIterator *iter,
97                                         struct PointerRNA *ptr);
98 typedef void (*PropCollectionNextFunc)(struct CollectionPropertyIterator *iter);
99 typedef void (*PropCollectionEndFunc)(struct CollectionPropertyIterator *iter);
100 typedef PointerRNA (*PropCollectionGetFunc)(struct CollectionPropertyIterator *iter);
101 typedef int (*PropCollectionLengthFunc)(struct PointerRNA *ptr);
102 typedef int (*PropCollectionLookupIntFunc)(struct PointerRNA *ptr,
103                                            int key,
104                                            struct PointerRNA *r_ptr);
105 typedef int (*PropCollectionLookupStringFunc)(struct PointerRNA *ptr,
106                                               const char *key,
107                                               struct PointerRNA *r_ptr);
108 typedef int (*PropCollectionAssignIntFunc)(struct PointerRNA *ptr,
109                                            int key,
110                                            const struct PointerRNA *assign_ptr);
111 
112 /* extended versions with PropertyRNA argument */
113 typedef bool (*PropBooleanGetFuncEx)(struct PointerRNA *ptr, struct PropertyRNA *prop);
114 typedef void (*PropBooleanSetFuncEx)(struct PointerRNA *ptr, struct PropertyRNA *prop, bool value);
115 typedef void (*PropBooleanArrayGetFuncEx)(struct PointerRNA *ptr,
116                                           struct PropertyRNA *prop,
117                                           bool *values);
118 typedef void (*PropBooleanArraySetFuncEx)(struct PointerRNA *ptr,
119                                           struct PropertyRNA *prop,
120                                           const bool *values);
121 typedef int (*PropIntGetFuncEx)(struct PointerRNA *ptr, struct PropertyRNA *prop);
122 typedef void (*PropIntSetFuncEx)(struct PointerRNA *ptr, struct PropertyRNA *prop, int value);
123 typedef void (*PropIntArrayGetFuncEx)(struct PointerRNA *ptr,
124                                       struct PropertyRNA *prop,
125                                       int *values);
126 typedef void (*PropIntArraySetFuncEx)(struct PointerRNA *ptr,
127                                       struct PropertyRNA *prop,
128                                       const int *values);
129 typedef void (*PropIntRangeFuncEx)(struct PointerRNA *ptr,
130                                    struct PropertyRNA *prop,
131                                    int *min,
132                                    int *max,
133                                    int *softmin,
134                                    int *softmax);
135 typedef float (*PropFloatGetFuncEx)(struct PointerRNA *ptr, struct PropertyRNA *prop);
136 typedef void (*PropFloatSetFuncEx)(struct PointerRNA *ptr, struct PropertyRNA *prop, float value);
137 typedef void (*PropFloatArrayGetFuncEx)(struct PointerRNA *ptr,
138                                         struct PropertyRNA *prop,
139                                         float *values);
140 typedef void (*PropFloatArraySetFuncEx)(struct PointerRNA *ptr,
141                                         struct PropertyRNA *prop,
142                                         const float *values);
143 typedef void (*PropFloatRangeFuncEx)(struct PointerRNA *ptr,
144                                      struct PropertyRNA *prop,
145                                      float *min,
146                                      float *max,
147                                      float *softmin,
148                                      float *softmax);
149 typedef void (*PropStringGetFuncEx)(struct PointerRNA *ptr, struct PropertyRNA *prop, char *value);
150 typedef int (*PropStringLengthFuncEx)(struct PointerRNA *ptr, struct PropertyRNA *prop);
151 typedef void (*PropStringSetFuncEx)(struct PointerRNA *ptr,
152                                     struct PropertyRNA *prop,
153                                     const char *value);
154 typedef int (*PropEnumGetFuncEx)(struct PointerRNA *ptr, struct PropertyRNA *prop);
155 typedef void (*PropEnumSetFuncEx)(struct PointerRNA *ptr, struct PropertyRNA *prop, int value);
156 
157 /* Handling override operations, and also comparison. */
158 
159 /** Structure storing all needed data to process all three kinds of RNA properties. */
160 typedef struct PropertyRNAOrID {
161   PointerRNA ptr;
162 
163   /** The PropertyRNA passed as parameter, used to generate that structure's content:
164    * - Static RNA: The RNA property (same as `rnaprop`), never NULL.
165    * - Runtime RNA: The RNA property (same as `rnaprop`), never NULL.
166    * - IDProperty: The IDProperty, never NULL.
167    */
168   PropertyRNA *rawprop;
169   /** The real RNA property of this property, never NULL:
170    * - Static RNA: The rna property, also gives direct access to the data (from any matching
171    *               PointerRNA).
172    * - Runtime RNA: The rna property, does not directly gives access to the data.
173    * - IDProperty: The generic PropertyRNA matching its type.
174    */
175   PropertyRNA *rnaprop;
176   /** The IDProperty storing the data of this property, may be NULL:
177    * - Static RNA: Always NULL.
178    * - Runtime RNA: The IDProperty storing the data of that property, may be NULL if never set yet.
179    * - IDProperty: The IDProperty, never NULL.
180    */
181   IDProperty *idprop;
182   /** The name of the property. */
183   const char *identifier;
184 
185   /** Whether this property is a 'pure' IDProperty or not. */
186   bool is_idprop;
187   /** For runtime RNA properties, whether it is set, defined, or not.
188    * WARNING: This DOES take into account the `IDP_FLAG_GHOST` flag, i.e. it matches result of
189    *          `RNA_property_is_set`. */
190   bool is_set;
191 
192   bool is_array;
193   uint array_len;
194 } PropertyRNAOrID;
195 
196 /**
197  * If \a override is NULL, merely do comparison between prop_a and prop_b,
198  * following comparison mode given.
199  * If \a override and \a rna_path are not NULL, it will add a new override operation for
200  * overridable properties that differ and have not yet been overridden
201  * (and set accordingly \a r_override_changed if given).
202  *
203  * \note \a override, \a rna_path and \a r_override_changed may be NULL pointers.
204  */
205 typedef int (*RNAPropOverrideDiff)(struct Main *bmain,
206                                    struct PropertyRNAOrID *prop_a,
207                                    struct PropertyRNAOrID *prop_b,
208                                    const int mode,
209                                    struct IDOverrideLibrary *override,
210                                    const char *rna_path,
211                                    const size_t rna_path_len,
212                                    const int flags,
213                                    bool *r_override_changed);
214 
215 /**
216  * Only used for differential override (add, sub, etc.).
217  * Store into storage the value needed to transform reference's value into local's value.
218  *
219  * \note Given PropertyRNA are final (in case of IDProps...).
220  * \note In non-array cases, \a len values are 0.
221  * \note Might change given override operation (e.g. change 'add' one into 'sub'),
222  * in case computed storage value is out of range
223  * (or even change it to basic 'set' operation if nothing else works).
224  */
225 typedef bool (*RNAPropOverrideStore)(struct Main *bmain,
226                                      struct PointerRNA *ptr_local,
227                                      struct PointerRNA *ptr_reference,
228                                      struct PointerRNA *ptr_storage,
229                                      struct PropertyRNA *prop_local,
230                                      struct PropertyRNA *prop_reference,
231                                      struct PropertyRNA *prop_storage,
232                                      const int len_local,
233                                      const int len_reference,
234                                      const int len_storage,
235                                      struct IDOverrideLibraryPropertyOperation *opop);
236 
237 /**
238  * Apply given override operation from src to dst (using value from storage as second operand
239  * for differential operations).
240  *
241  * \note Given PropertyRNA are final (in case of IDProps...).
242  * \note In non-array cases, \a len values are 0.
243  */
244 typedef bool (*RNAPropOverrideApply)(struct Main *bmain,
245                                      struct PointerRNA *ptr_dst,
246                                      struct PointerRNA *ptr_src,
247                                      struct PointerRNA *ptr_storage,
248                                      struct PropertyRNA *prop_dst,
249                                      struct PropertyRNA *prop_src,
250                                      struct PropertyRNA *prop_storage,
251                                      const int len_dst,
252                                      const int len_src,
253                                      const int len_storage,
254                                      struct PointerRNA *ptr_item_dst,
255                                      struct PointerRNA *ptr_item_src,
256                                      struct PointerRNA *ptr_item_storage,
257                                      struct IDOverrideLibraryPropertyOperation *opop);
258 
259 /* Container - generic abstracted container of RNA properties */
260 typedef struct ContainerRNA {
261   void *next, *prev;
262 
263   struct GHash *prophash;
264   ListBase properties;
265 } ContainerRNA;
266 
267 struct FunctionRNA {
268   /* structs are containers of properties */
269   ContainerRNA cont;
270 
271   /* unique identifier, keep after 'cont' */
272   const char *identifier;
273   /* various options */
274   int flag;
275 
276   /* single line description, displayed in the tooltip for example */
277   const char *description;
278 
279   /* callback to execute the function */
280   CallFunc call;
281 
282   /* parameter for the return value
283    * note: this is only the C return value, rna functions can have multiple return values */
284   PropertyRNA *c_ret;
285 };
286 
287 struct PropertyRNA {
288   struct PropertyRNA *next, *prev;
289 
290   /* magic bytes to distinguish with IDProperty */
291   int magic;
292 
293   /* unique identifier */
294   const char *identifier;
295   /* various options */
296   int flag;
297   /* various override options */
298   int flag_override;
299   /* Function parameters flags. */
300   short flag_parameter;
301   /* Internal ("private") flags. */
302   short flag_internal;
303   /* The subset of StructRNA.prop_tag_defines values that applies to this property. */
304   short tags;
305 
306   /* user readable name */
307   const char *name;
308   /* single line description, displayed in the tooltip for example */
309   const char *description;
310   /* icon ID */
311   int icon;
312   /* context for translation */
313   const char *translation_context;
314 
315   /* property type as it appears to the outside */
316   PropertyType type;
317   /* subtype, 'interpretation' of the property */
318   PropertySubType subtype;
319   /* if non-NULL, overrides arraylength. Must not return 0? */
320   PropArrayLengthGetFunc getlength;
321   /* dimension of array */
322   unsigned int arraydimension;
323   /* array lengths lengths for all dimensions (when arraydimension > 0) */
324   unsigned int arraylength[RNA_MAX_ARRAY_DIMENSION];
325   unsigned int totarraylength;
326 
327   /* callback for updates on change */
328   UpdateFunc update;
329   int noteflag;
330 
331   /* Callback for testing if editable. Its r_info parameter can be used to
332    * return info on editable state that might be shown to user. E.g. tooltips
333    * of disabled buttons can show reason why button is disabled using this. */
334   EditableFunc editable;
335   /* callback for testing if array-item editable (if applicable) */
336   ItemEditableFunc itemeditable;
337 
338   /* Override handling callbacks (diff is also used for comparison). */
339   RNAPropOverrideDiff override_diff;
340   RNAPropOverrideStore override_store;
341   RNAPropOverrideApply override_apply;
342 
343   /* raw access */
344   int rawoffset;
345   RawPropertyType rawtype;
346 
347   /* This is used for accessing props/functions of this property
348    * any property can have this but should only be used for collections and arrays
349    * since python will convert int/bool/pointer's */
350   struct StructRNA *srna; /* attributes attached directly to this collection */
351 
352   /* python handle to hold all callbacks
353    * (in a pointer array at the moment, may later be a tuple) */
354   void *py_data;
355 };
356 
357 /* internal flags WARNING! 16bits only! */
358 typedef enum PropertyFlagIntern {
359   PROP_INTERN_BUILTIN = (1 << 0),
360   PROP_INTERN_RUNTIME = (1 << 1),
361   PROP_INTERN_RAW_ACCESS = (1 << 2),
362   PROP_INTERN_RAW_ARRAY = (1 << 3),
363   PROP_INTERN_FREE_POINTERS = (1 << 4),
364   /* Negative mirror of PROP_PTR_NO_OWNERSHIP, used to prevent automatically setting that one in
365    * makesrna when pointer is an ID... */
366   PROP_INTERN_PTR_OWNERSHIP_FORCED = (1 << 5),
367 } PropertyFlagIntern;
368 
369 /* Property Types */
370 
371 typedef struct BoolPropertyRNA {
372   PropertyRNA property;
373 
374   PropBooleanGetFunc get;
375   PropBooleanSetFunc set;
376   PropBooleanArrayGetFunc getarray;
377   PropBooleanArraySetFunc setarray;
378 
379   PropBooleanGetFuncEx get_ex;
380   PropBooleanSetFuncEx set_ex;
381   PropBooleanArrayGetFuncEx getarray_ex;
382   PropBooleanArraySetFuncEx setarray_ex;
383 
384   bool defaultvalue;
385   const bool *defaultarray;
386 } BoolPropertyRNA;
387 
388 typedef struct IntPropertyRNA {
389   PropertyRNA property;
390 
391   PropIntGetFunc get;
392   PropIntSetFunc set;
393   PropIntArrayGetFunc getarray;
394   PropIntArraySetFunc setarray;
395   PropIntRangeFunc range;
396 
397   PropIntGetFuncEx get_ex;
398   PropIntSetFuncEx set_ex;
399   PropIntArrayGetFuncEx getarray_ex;
400   PropIntArraySetFuncEx setarray_ex;
401   PropIntRangeFuncEx range_ex;
402 
403   int softmin, softmax;
404   int hardmin, hardmax;
405   int step;
406 
407   int defaultvalue;
408   const int *defaultarray;
409 } IntPropertyRNA;
410 
411 typedef struct FloatPropertyRNA {
412   PropertyRNA property;
413 
414   PropFloatGetFunc get;
415   PropFloatSetFunc set;
416   PropFloatArrayGetFunc getarray;
417   PropFloatArraySetFunc setarray;
418   PropFloatRangeFunc range;
419 
420   PropFloatGetFuncEx get_ex;
421   PropFloatSetFuncEx set_ex;
422   PropFloatArrayGetFuncEx getarray_ex;
423   PropFloatArraySetFuncEx setarray_ex;
424   PropFloatRangeFuncEx range_ex;
425 
426   float softmin, softmax;
427   float hardmin, hardmax;
428   float step;
429   int precision;
430 
431   float defaultvalue;
432   const float *defaultarray;
433 } FloatPropertyRNA;
434 
435 typedef struct StringPropertyRNA {
436   PropertyRNA property;
437 
438   PropStringGetFunc get;
439   PropStringLengthFunc length;
440   PropStringSetFunc set;
441 
442   PropStringGetFuncEx get_ex;
443   PropStringLengthFuncEx length_ex;
444   PropStringSetFuncEx set_ex;
445 
446   int maxlength; /* includes string terminator! */
447 
448   const char *defaultvalue;
449 } StringPropertyRNA;
450 
451 typedef struct EnumPropertyRNA {
452   PropertyRNA property;
453 
454   PropEnumGetFunc get;
455   PropEnumSetFunc set;
456   PropEnumItemFunc itemf;
457 
458   PropEnumGetFuncEx get_ex;
459   PropEnumSetFuncEx set_ex;
460   void *py_data; /* store py callback here */
461 
462   const EnumPropertyItem *item;
463   int totitem;
464 
465   int defaultvalue;
466   const char *native_enum_type;
467 } EnumPropertyRNA;
468 
469 typedef struct PointerPropertyRNA {
470   PropertyRNA property;
471 
472   PropPointerGetFunc get;
473   PropPointerSetFunc set;
474   PropPointerTypeFunc typef;
475   /** unlike operators, 'set' can still run if poll fails, used for filtering display. */
476   PropPointerPollFunc poll;
477 
478   struct StructRNA *type;
479 } PointerPropertyRNA;
480 
481 typedef struct CollectionPropertyRNA {
482   PropertyRNA property;
483 
484   PropCollectionBeginFunc begin;
485   PropCollectionNextFunc next;
486   PropCollectionEndFunc end; /* optional */
487   PropCollectionGetFunc get;
488   PropCollectionLengthFunc length;             /* optional */
489   PropCollectionLookupIntFunc lookupint;       /* optional */
490   PropCollectionLookupStringFunc lookupstring; /* optional */
491   PropCollectionAssignIntFunc assignint;       /* optional */
492 
493   struct StructRNA *item_type; /* the type of this item */
494 } CollectionPropertyRNA;
495 
496 /* changes to this struct require updating rna_generate_struct in makesrna.c */
497 struct StructRNA {
498   /* structs are containers of properties */
499   ContainerRNA cont;
500 
501   /* unique identifier, keep after 'cont' */
502   const char *identifier;
503 
504   /** Python type, this is a subtype of #pyrna_struct_Type
505    * but used so each struct can have its own type which is useful for subclassing RNA. */
506   void *py_type;
507   void *blender_type;
508 
509   /* various options */
510   int flag;
511   /* Each StructRNA type can define own tags which properties can set
512    * (PropertyRNA.tags) for changed behavior based on struct-type. */
513   const EnumPropertyItem *prop_tag_defines;
514 
515   /* user readable name */
516   const char *name;
517   /* single line description, displayed in the tooltip for example */
518   const char *description;
519   /* context for translation */
520   const char *translation_context;
521   /* icon ID */
522   int icon;
523 
524   /* property that defines the name */
525   PropertyRNA *nameproperty;
526 
527   /* property to iterate over properties */
528   PropertyRNA *iteratorproperty;
529 
530   /* struct this is derivedfrom */
531   struct StructRNA *base;
532 
533   /* only use for nested structs, where both the parent and child access
534    * the same C Struct but nesting is used for grouping properties.
535    * The parent property is used so we know NULL checks are not needed,
536    * and that this struct will never exist without its parent */
537   struct StructRNA *nested;
538 
539   /* function to give the more specific type */
540   StructRefineFunc refine;
541 
542   /* function to find path to this struct in an ID */
543   StructPathFunc path;
544 
545   /* function to register/unregister subclasses */
546   StructRegisterFunc reg;
547   StructUnregisterFunc unreg;
548   StructInstanceFunc instance;
549 
550   /* callback to get id properties */
551   IDPropertiesFunc idproperties;
552 
553   /* functions of this struct */
554   ListBase functions;
555 };
556 
557 /* Blender RNA
558  *
559  * Root RNA data structure that lists all struct types. */
560 
561 struct BlenderRNA {
562   ListBase structs;
563   /* A map of structs: {StructRNA.identifier -> StructRNA}
564    * These are ensured to have unique names (with STRUCT_PUBLIC_NAMESPACE enabled). */
565   struct GHash *structs_map;
566   /* Needed because types with an empty identifier aren't included in 'structs_map'. */
567   unsigned int structs_len;
568 };
569 
570 #define CONTAINER_RNA_ID(cont) (*(const char **)(((ContainerRNA *)(cont)) + 1))
571