Merge branch 'blender-v2.91-release'
[blender.git] / source / blender / makesrna / RNA_define.h
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 #pragma once
18
19 /** \file
20  * \ingroup RNA
21  *
22  * Functions used during preprocess and runtime, for defining the RNA.
23  */
24
25 #include <float.h>
26 #include <inttypes.h>
27 #include <limits.h>
28
29 #include "DNA_listBase.h"
30 #include "RNA_types.h"
31
32 #ifdef __cplusplus
33 extern "C" {
34 #endif
35
36 #ifdef UNIT_TEST
37 #  define RNA_MAX_ARRAY_LENGTH 64
38 #else
39 #  define RNA_MAX_ARRAY_LENGTH 32
40 #endif
41
42 #define RNA_MAX_ARRAY_DIMENSION 3
43
44 /* Blender RNA */
45
46 BlenderRNA *RNA_create(void);
47 void RNA_define_free(BlenderRNA *brna);
48 void RNA_free(BlenderRNA *brna);
49 void RNA_define_verify_sdna(bool verify);
50 void RNA_define_animate_sdna(bool animate);
51 void RNA_define_fallback_property_update(int noteflag, const char *updatefunc);
52 void RNA_define_lib_overridable(const bool make_overridable);
53
54 void RNA_init(void);
55 void RNA_exit(void);
56
57 /* Struct */
58
59 StructRNA *RNA_def_struct_ptr(BlenderRNA *brna, const char *identifier, StructRNA *srnafrom);
60 StructRNA *RNA_def_struct(BlenderRNA *brna, const char *identifier, const char *from);
61 void RNA_def_struct_sdna(StructRNA *srna, const char *structname);
62 void RNA_def_struct_sdna_from(StructRNA *srna, const char *structname, const char *propname);
63 void RNA_def_struct_name_property(StructRNA *srna, PropertyRNA *prop);
64 void RNA_def_struct_nested(BlenderRNA *brna, StructRNA *srna, const char *structname);
65 void RNA_def_struct_flag(StructRNA *srna, int flag);
66 void RNA_def_struct_clear_flag(StructRNA *srna, int flag);
67 void RNA_def_struct_property_tags(StructRNA *srna, const EnumPropertyItem *prop_tag_defines);
68 void RNA_def_struct_refine_func(StructRNA *srna, const char *refine);
69 void RNA_def_struct_idprops_func(StructRNA *srna, const char *idproperties);
70 void RNA_def_struct_register_funcs(StructRNA *srna,
71                                    const char *reg,
72                                    const char *unreg,
73                                    const char *instance);
74 void RNA_def_struct_path_func(StructRNA *srna, const char *path);
75 void RNA_def_struct_identifier_no_struct_map(StructRNA *srna, const char *identifier);
76 void RNA_def_struct_identifier(BlenderRNA *brna, StructRNA *srna, const char *identifier);
77 void RNA_def_struct_ui_text(StructRNA *srna, const char *name, const char *description);
78 void RNA_def_struct_ui_icon(StructRNA *srna, int icon);
79 void RNA_struct_free_extension(StructRNA *srna, ExtensionRNA *rna_ext);
80 void RNA_struct_free(BlenderRNA *brna, StructRNA *srna);
81
82 void RNA_def_struct_translation_context(StructRNA *srna, const char *context);
83
84 /* Compact Property Definitions */
85
86 typedef void StructOrFunctionRNA;
87
88 PropertyRNA *RNA_def_boolean(StructOrFunctionRNA *cont,
89                              const char *identifier,
90                              bool default_value,
91                              const char *ui_name,
92                              const char *ui_description);
93 PropertyRNA *RNA_def_boolean_array(StructOrFunctionRNA *cont,
94                                    const char *identifier,
95                                    int len,
96                                    bool *default_value,
97                                    const char *ui_name,
98                                    const char *ui_description);
99 PropertyRNA *RNA_def_boolean_layer(StructOrFunctionRNA *cont,
100                                    const char *identifier,
101                                    int len,
102                                    bool *default_value,
103                                    const char *ui_name,
104                                    const char *ui_description);
105 PropertyRNA *RNA_def_boolean_layer_member(StructOrFunctionRNA *cont,
106                                           const char *identifier,
107                                           int len,
108                                           bool *default_value,
109                                           const char *ui_name,
110                                           const char *ui_description);
111 PropertyRNA *RNA_def_boolean_vector(StructOrFunctionRNA *cont,
112                                     const char *identifier,
113                                     int len,
114                                     bool *default_value,
115                                     const char *ui_name,
116                                     const char *ui_description);
117
118 PropertyRNA *RNA_def_int(StructOrFunctionRNA *cont,
119                          const char *identifier,
120                          int default_value,
121                          int hardmin,
122                          int hardmax,
123                          const char *ui_name,
124                          const char *ui_description,
125                          int softmin,
126                          int softmax);
127 PropertyRNA *RNA_def_int_vector(StructOrFunctionRNA *cont,
128                                 const char *identifier,
129                                 int len,
130                                 const int *default_value,
131                                 int hardmin,
132                                 int hardmax,
133                                 const char *ui_name,
134                                 const char *ui_description,
135                                 int softmin,
136                                 int softmax);
137 PropertyRNA *RNA_def_int_array(StructOrFunctionRNA *cont,
138                                const char *identifier,
139                                int len,
140                                const int *default_value,
141                                int hardmin,
142                                int hardmax,
143                                const char *ui_name,
144                                const char *ui_description,
145                                int softmin,
146                                int softmax);
147
148 PropertyRNA *RNA_def_string(StructOrFunctionRNA *cont,
149                             const char *identifier,
150                             const char *default_value,
151                             int maxlen,
152                             const char *ui_name,
153                             const char *ui_description);
154 PropertyRNA *RNA_def_string_file_path(StructOrFunctionRNA *cont,
155                                       const char *identifier,
156                                       const char *default_value,
157                                       int maxlen,
158                                       const char *ui_name,
159                                       const char *ui_description);
160 PropertyRNA *RNA_def_string_dir_path(StructOrFunctionRNA *cont,
161                                      const char *identifier,
162                                      const char *default_value,
163                                      int maxlen,
164                                      const char *ui_name,
165                                      const char *ui_description);
166 PropertyRNA *RNA_def_string_file_name(StructOrFunctionRNA *cont,
167                                       const char *identifier,
168                                       const char *default_value,
169                                       int maxlen,
170                                       const char *ui_name,
171                                       const char *ui_description);
172
173 PropertyRNA *RNA_def_enum(StructOrFunctionRNA *cont,
174                           const char *identifier,
175                           const EnumPropertyItem *items,
176                           int default_value,
177                           const char *ui_name,
178                           const char *ui_description);
179 PropertyRNA *RNA_def_enum_flag(StructOrFunctionRNA *cont,
180                                const char *identifier,
181                                const EnumPropertyItem *items,
182                                int default_value,
183                                const char *ui_name,
184                                const char *ui_description);
185 void RNA_def_enum_funcs(PropertyRNA *prop, EnumPropertyItemFunc itemfunc);
186
187 PropertyRNA *RNA_def_float(StructOrFunctionRNA *cont,
188                            const char *identifier,
189                            float default_value,
190                            float hardmin,
191                            float hardmax,
192                            const char *ui_name,
193                            const char *ui_description,
194                            float softmin,
195                            float softmax);
196 PropertyRNA *RNA_def_float_vector(StructOrFunctionRNA *cont,
197                                   const char *identifier,
198                                   int len,
199                                   const float *default_value,
200                                   float hardmin,
201                                   float hardmax,
202                                   const char *ui_name,
203                                   const char *ui_description,
204                                   float softmin,
205                                   float softmax);
206 PropertyRNA *RNA_def_float_vector_xyz(StructOrFunctionRNA *cont,
207                                       const char *identifier,
208                                       int len,
209                                       const float *default_value,
210                                       float hardmin,
211                                       float hardmax,
212                                       const char *ui_name,
213                                       const char *ui_description,
214                                       float softmin,
215                                       float softmax);
216 PropertyRNA *RNA_def_float_color(StructOrFunctionRNA *cont,
217                                  const char *identifier,
218                                  int len,
219                                  const float *default_value,
220                                  float hardmin,
221                                  float hardmax,
222                                  const char *ui_name,
223                                  const char *ui_description,
224                                  float softmin,
225                                  float softmax);
226 PropertyRNA *RNA_def_float_matrix(StructOrFunctionRNA *cont,
227                                   const char *identifier,
228                                   int rows,
229                                   int columns,
230                                   const float *default_value,
231                                   float hardmin,
232                                   float hardmax,
233                                   const char *ui_name,
234                                   const char *ui_description,
235                                   float softmin,
236                                   float softmax);
237 PropertyRNA *RNA_def_float_translation(StructOrFunctionRNA *cont,
238                                        const char *identifier,
239                                        int len,
240                                        const float *default_value,
241                                        float hardmin,
242                                        float hardmax,
243                                        const char *ui_name,
244                                        const char *ui_description,
245                                        float softmin,
246                                        float softmax);
247 PropertyRNA *RNA_def_float_rotation(StructOrFunctionRNA *cont,
248                                     const char *identifier,
249                                     int len,
250                                     const float *default_value,
251                                     float hardmin,
252                                     float hardmax,
253                                     const char *ui_name,
254                                     const char *ui_description,
255                                     float softmin,
256                                     float softmax);
257 PropertyRNA *RNA_def_float_distance(StructOrFunctionRNA *cont,
258                                     const char *identifier,
259                                     float default_value,
260                                     float hardmin,
261                                     float hardmax,
262                                     const char *ui_name,
263                                     const char *ui_description,
264                                     float softmin,
265                                     float softmax);
266 PropertyRNA *RNA_def_float_array(StructOrFunctionRNA *cont,
267                                  const char *identifier,
268                                  int len,
269                                  const float *default_value,
270                                  float hardmin,
271                                  float hardmax,
272                                  const char *ui_name,
273                                  const char *ui_description,
274                                  float softmin,
275                                  float softmax);
276
277 #if 0
278 PropertyRNA *RNA_def_float_dynamic_array(StructOrFunctionRNA *cont,
279                                          const char *identifier,
280                                          float hardmin,
281                                          float hardmax,
282                                          const char *ui_name,
283                                          const char *ui_description,
284                                          float softmin,
285                                          float softmax,
286                                          unsigned int dimension,
287                                          unsigned short dim_size[]);
288 #endif
289
290 PropertyRNA *RNA_def_float_percentage(StructOrFunctionRNA *cont,
291                                       const char *identifier,
292                                       float default_value,
293                                       float hardmin,
294                                       float hardmax,
295                                       const char *ui_name,
296                                       const char *ui_description,
297                                       float softmin,
298                                       float softmax);
299 PropertyRNA *RNA_def_float_factor(StructOrFunctionRNA *cont,
300                                   const char *identifier,
301                                   float default_value,
302                                   float hardmin,
303                                   float hardmax,
304                                   const char *ui_name,
305                                   const char *ui_description,
306                                   float softmin,
307                                   float softmax);
308
309 PropertyRNA *RNA_def_pointer(StructOrFunctionRNA *cont,
310                              const char *identifier,
311                              const char *type,
312                              const char *ui_name,
313                              const char *ui_description);
314 PropertyRNA *RNA_def_pointer_runtime(StructOrFunctionRNA *cont,
315                                      const char *identifier,
316                                      StructRNA *type,
317                                      const char *ui_name,
318                                      const char *ui_description);
319
320 PropertyRNA *RNA_def_collection(StructOrFunctionRNA *cont,
321                                 const char *identifier,
322                                 const char *type,
323                                 const char *ui_name,
324                                 const char *ui_description);
325 PropertyRNA *RNA_def_collection_runtime(StructOrFunctionRNA *cont,
326                                         const char *identifier,
327                                         StructRNA *type,
328                                         const char *ui_name,
329                                         const char *ui_description);
330
331 /* Extended Property Definitions */
332
333 PropertyRNA *RNA_def_property(StructOrFunctionRNA *cont,
334                               const char *identifier,
335                               int type,
336                               int subtype);
337
338 void RNA_def_property_boolean_sdna(PropertyRNA *prop,
339                                    const char *structname,
340                                    const char *propname,
341                                    int64_t bit);
342 void RNA_def_property_boolean_negative_sdna(PropertyRNA *prop,
343                                             const char *structname,
344                                             const char *propname,
345                                             int64_t bit);
346 void RNA_def_property_int_sdna(PropertyRNA *prop, const char *structname, const char *propname);
347 void RNA_def_property_float_sdna(PropertyRNA *prop, const char *structname, const char *propname);
348 void RNA_def_property_string_sdna(PropertyRNA *prop, const char *structname, const char *propname);
349 void RNA_def_property_enum_sdna(PropertyRNA *prop, const char *structname, const char *propname);
350 void RNA_def_property_enum_bitflag_sdna(PropertyRNA *prop,
351                                         const char *structname,
352                                         const char *propname);
353 void RNA_def_property_pointer_sdna(PropertyRNA *prop,
354                                    const char *structname,
355                                    const char *propname);
356 void RNA_def_property_collection_sdna(PropertyRNA *prop,
357                                       const char *structname,
358                                       const char *propname,
359                                       const char *lengthpropname);
360
361 void RNA_def_property_flag(PropertyRNA *prop, PropertyFlag flag);
362 void RNA_def_property_clear_flag(PropertyRNA *prop, PropertyFlag flag);
363 void RNA_def_property_override_flag(PropertyRNA *prop, PropertyOverrideFlag flag);
364 void RNA_def_property_override_clear_flag(PropertyRNA *prop, PropertyOverrideFlag flag);
365 void RNA_def_property_tags(PropertyRNA *prop, int tags);
366 void RNA_def_property_subtype(PropertyRNA *prop, PropertySubType subtype);
367 void RNA_def_property_array(PropertyRNA *prop, int length);
368 void RNA_def_property_multi_array(PropertyRNA *prop, int dimension, const int length[]);
369 void RNA_def_property_range(PropertyRNA *prop, double min, double max);
370
371 void RNA_def_property_enum_items(PropertyRNA *prop, const EnumPropertyItem *item);
372 void RNA_def_property_enum_native_type(PropertyRNA *prop, const char *native_enum_type);
373 void RNA_def_property_string_maxlength(PropertyRNA *prop, int maxlength);
374 void RNA_def_property_struct_type(PropertyRNA *prop, const char *type);
375 void RNA_def_property_struct_runtime(PropertyRNA *prop, StructRNA *type);
376
377 void RNA_def_property_boolean_default(PropertyRNA *prop, bool value);
378 void RNA_def_property_boolean_array_default(PropertyRNA *prop, const bool *array);
379 void RNA_def_property_int_default(PropertyRNA *prop, int value);
380 void RNA_def_property_int_array_default(PropertyRNA *prop, const int *array);
381 void RNA_def_property_float_default(PropertyRNA *prop, float value);
382 void RNA_def_property_float_array_default(PropertyRNA *prop, const float *array);
383 void RNA_def_property_enum_default(PropertyRNA *prop, int value);
384 void RNA_def_property_string_default(PropertyRNA *prop, const char *value);
385
386 void RNA_def_property_ui_text(PropertyRNA *prop, const char *name, const char *description);
387 void RNA_def_property_ui_range(
388     PropertyRNA *prop, double min, double max, double step, int precision);
389 void RNA_def_property_ui_icon(PropertyRNA *prop, int icon, int consecutive);
390
391 void RNA_def_property_update(PropertyRNA *prop, int noteflag, const char *updatefunc);
392 void RNA_def_property_editable_func(PropertyRNA *prop, const char *editable);
393 void RNA_def_property_editable_array_func(PropertyRNA *prop, const char *editable);
394
395 void RNA_def_property_override_funcs(PropertyRNA *prop,
396                                      const char *diff,
397                                      const char *store,
398                                      const char *apply);
399
400 void RNA_def_property_update_runtime(PropertyRNA *prop, const void *func);
401 void RNA_def_property_poll_runtime(PropertyRNA *prop, const void *func);
402
403 void RNA_def_property_dynamic_array_funcs(PropertyRNA *prop, const char *getlength);
404 void RNA_def_property_boolean_funcs(PropertyRNA *prop, const char *get, const char *set);
405 void RNA_def_property_int_funcs(PropertyRNA *prop,
406                                 const char *get,
407                                 const char *set,
408                                 const char *range);
409 void RNA_def_property_float_funcs(PropertyRNA *prop,
410                                   const char *get,
411                                   const char *set,
412                                   const char *range);
413 void RNA_def_property_enum_funcs(PropertyRNA *prop,
414                                  const char *get,
415                                  const char *set,
416                                  const char *item);
417 void RNA_def_property_string_funcs(PropertyRNA *prop,
418                                    const char *get,
419                                    const char *length,
420                                    const char *set);
421 void RNA_def_property_pointer_funcs(
422     PropertyRNA *prop, const char *get, const char *set, const char *typef, const char *poll);
423 void RNA_def_property_collection_funcs(PropertyRNA *prop,
424                                        const char *begin,
425                                        const char *next,
426                                        const char *end,
427                                        const char *get,
428                                        const char *length,
429                                        const char *lookupint,
430                                        const char *lookupstring,
431                                        const char *assignint);
432 void RNA_def_property_srna(PropertyRNA *prop, const char *type);
433 void RNA_def_py_data(PropertyRNA *prop, void *py_data);
434
435 void RNA_def_property_boolean_funcs_runtime(PropertyRNA *prop,
436                                             BooleanPropertyGetFunc getfunc,
437                                             BooleanPropertySetFunc setfunc);
438 void RNA_def_property_boolean_array_funcs_runtime(PropertyRNA *prop,
439                                                   BooleanArrayPropertyGetFunc getfunc,
440                                                   BooleanArrayPropertySetFunc setfunc);
441 void RNA_def_property_int_funcs_runtime(PropertyRNA *prop,
442                                         IntPropertyGetFunc getfunc,
443                                         IntPropertySetFunc setfunc,
444                                         IntPropertyRangeFunc rangefunc);
445 void RNA_def_property_int_array_funcs_runtime(PropertyRNA *prop,
446                                               IntArrayPropertyGetFunc getfunc,
447                                               IntArrayPropertySetFunc setfunc,
448                                               IntPropertyRangeFunc rangefunc);
449 void RNA_def_property_float_funcs_runtime(PropertyRNA *prop,
450                                           FloatPropertyGetFunc getfunc,
451                                           FloatPropertySetFunc setfunc,
452                                           FloatPropertyRangeFunc rangefunc);
453 void RNA_def_property_float_array_funcs_runtime(PropertyRNA *prop,
454                                                 FloatArrayPropertyGetFunc getfunc,
455                                                 FloatArrayPropertySetFunc setfunc,
456                                                 FloatPropertyRangeFunc rangefunc);
457 void RNA_def_property_enum_funcs_runtime(PropertyRNA *prop,
458                                          EnumPropertyGetFunc getfunc,
459                                          EnumPropertySetFunc setfunc,
460                                          EnumPropertyItemFunc itemfunc);
461 void RNA_def_property_string_funcs_runtime(PropertyRNA *prop,
462                                            StringPropertyGetFunc getfunc,
463                                            StringPropertyLengthFunc lengthfunc,
464                                            StringPropertySetFunc setfunc);
465
466 void RNA_def_property_enum_py_data(PropertyRNA *prop, void *py_data);
467
468 void RNA_def_property_translation_context(PropertyRNA *prop, const char *context);
469
470 /* Function */
471
472 FunctionRNA *RNA_def_function(StructRNA *srna, const char *identifier, const char *call);
473 FunctionRNA *RNA_def_function_runtime(StructRNA *srna, const char *identifier, CallFunc call);
474 void RNA_def_function_return(FunctionRNA *func, PropertyRNA *ret);
475 void RNA_def_function_output(FunctionRNA *func, PropertyRNA *ret);
476 void RNA_def_function_flag(FunctionRNA *func, int flag);
477 void RNA_def_function_ui_description(FunctionRNA *func, const char *description);
478
479 void RNA_def_parameter_flags(PropertyRNA *prop,
480                              PropertyFlag flag_property,
481                              ParameterFlag flag_parameter);
482 void RNA_def_parameter_clear_flags(PropertyRNA *prop,
483                                    PropertyFlag flag_property,
484                                    ParameterFlag flag_parameter);
485
486 /* Dynamic Enums
487  * strings are not freed, assumed pointing to static location. */
488
489 void RNA_enum_item_add(EnumPropertyItem **items, int *totitem, const EnumPropertyItem *item);
490 void RNA_enum_item_add_separator(EnumPropertyItem **items, int *totitem);
491 void RNA_enum_items_add(EnumPropertyItem **items, int *totitem, const EnumPropertyItem *item);
492 void RNA_enum_items_add_value(EnumPropertyItem **items,
493                               int *totitem,
494                               const EnumPropertyItem *item,
495                               int value);
496 void RNA_enum_item_end(EnumPropertyItem **items, int *totitem);
497
498 /* Memory management */
499
500 void RNA_def_struct_duplicate_pointers(BlenderRNA *brna, StructRNA *srna);
501 void RNA_def_struct_free_pointers(BlenderRNA *brna, StructRNA *srna);
502 void RNA_def_func_duplicate_pointers(FunctionRNA *func);
503 void RNA_def_func_free_pointers(FunctionRNA *func);
504 void RNA_def_property_duplicate_pointers(StructOrFunctionRNA *cont_, PropertyRNA *prop);
505 void RNA_def_property_free_pointers(PropertyRNA *prop);
506 int RNA_def_property_free_identifier(StructOrFunctionRNA *cont_, const char *identifier);
507
508 /* utilities */
509 const char *RNA_property_typename(PropertyType type);
510 #define IS_DNATYPE_FLOAT_COMPAT(_str) (strcmp(_str, "float") == 0 || strcmp(_str, "double") == 0)
511 #define IS_DNATYPE_INT_COMPAT(_str) \
512   (strcmp(_str, "int") == 0 || strcmp(_str, "short") == 0 || strcmp(_str, "char") == 0 || \
513    strcmp(_str, "uchar") == 0 || strcmp(_str, "ushort") == 0)
514 #define IS_DNATYPE_BOOLEAN_COMPAT(_str) \
515   (IS_DNATYPE_INT_COMPAT(_str) || strcmp(_str, "int64_t") == 0 || strcmp(_str, "uint64_t") == 0)
516
517 void RNA_identifier_sanitize(char *identifier, int property);
518
519 extern const int rna_matrix_dimsize_3x3[];
520 extern const int rna_matrix_dimsize_4x4[];
521 extern const int rna_matrix_dimsize_4x2[];
522
523 extern const float rna_default_axis_angle[4];
524 extern const float rna_default_quaternion[4];
525 extern const float rna_default_scale_3d[3];
526
527 /* max size for dynamic defined type descriptors,
528  * this value is arbitrary */
529 #define RNA_DYN_DESCR_MAX 240
530
531 #ifdef __cplusplus
532 }
533 #endif