Code cleanup: use r_ prefix for return args
[blender.git] / source / blender / blenkernel / BKE_idprop.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): Joseph Eagar
19  *
20  * ***** END GPL LICENSE BLOCK *****
21  */
22  
23 #ifndef __BKE_IDPROP_H__
24 #define __BKE_IDPROP_H__
25
26 /** \file BKE_idprop.h
27  *  \ingroup bke
28  *  \author Joseph Eagar
29  */
30
31 #include "DNA_ID.h"
32
33 #include "BLI_compiler_attrs.h"
34
35 struct IDProperty;
36 struct ID;
37
38 typedef union IDPropertyTemplate {
39         int i;
40         float f;
41         double d;
42         struct {
43                 char *str;
44                 short len;
45                 char subtype;
46         } string;
47         struct ID *id;
48         struct {
49                 short type;
50                 short len;
51         } array;
52         struct {
53                 int matvec_size;
54                 float *example;
55         } matrix_or_vector;
56 } IDPropertyTemplate;
57
58 /* ----------- Property Array Type ---------- */
59
60 IDProperty *IDP_NewIDPArray(const char *name) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
61 IDProperty *IDP_CopyIDPArray(const IDProperty *array) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
62
63 void IDP_FreeIDPArray(IDProperty *prop);
64
65 /* shallow copies item */
66 void IDP_SetIndexArray(struct IDProperty *prop, int index, struct IDProperty *item) ATTR_NONNULL();
67 struct IDProperty *IDP_GetIndexArray(struct IDProperty *prop, int index) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
68 void IDP_AppendArray(struct IDProperty *prop, struct IDProperty *item);
69 void IDP_ResizeIDPArray(struct IDProperty *prop, int len);
70
71 /* ----------- Numeric Array Type ----------- */
72 /*this function works for strings too!*/
73 void IDP_ResizeArray(struct IDProperty *prop, int newlen);
74 void IDP_FreeArray(struct IDProperty *prop);
75
76 /* ---------- String Type ------------ */
77 IDProperty *IDP_NewString(const char *st, const char *name, int maxlen) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(2 /* 'name 'arg */); /* maxlen excludes '\0' */
78 void IDP_AssignString(struct IDProperty *prop, const char *st, int maxlen) ATTR_NONNULL(); /* maxlen excludes '\0' */
79 void IDP_ConcatStringC(struct IDProperty *prop, const char *st) ATTR_NONNULL();
80 void IDP_ConcatString(struct IDProperty *str1, struct IDProperty *append) ATTR_NONNULL();
81 void IDP_FreeString(struct IDProperty *prop) ATTR_NONNULL();
82
83 /*-------- ID Type -------*/
84 void IDP_LinkID(struct IDProperty *prop, ID *id);
85 void IDP_UnlinkID(struct IDProperty *prop);
86
87 /*-------- Group Functions -------*/
88
89 /** Sync values from one group to another, only where they match */
90 void IDP_SyncGroupValues(struct IDProperty *dest, const struct IDProperty *src) ATTR_NONNULL();
91 void IDP_SyncGroupTypes(struct IDProperty *dest, const struct IDProperty *src, const bool do_arraylen) ATTR_NONNULL();
92 void IDP_ReplaceGroupInGroup(struct IDProperty *dest, const struct IDProperty *src) ATTR_NONNULL();
93 void IDP_ReplaceInGroup(struct IDProperty *group, struct IDProperty *prop) ATTR_NONNULL();
94 void IDP_MergeGroup(IDProperty *dest, const IDProperty *src, const bool do_overwrite) ATTR_NONNULL();
95 bool IDP_AddToGroup(struct IDProperty *group, struct IDProperty *prop) ATTR_NONNULL();
96 bool IDP_InsertToGroup(struct IDProperty *group, struct IDProperty *previous,
97                       struct IDProperty *pnew) ATTR_NONNULL(1 /* group */, 3 /* pnew */);
98 void IDP_RemoveFromGroup(struct IDProperty *group, struct IDProperty *prop) ATTR_NONNULL();
99 void IDP_FreeFromGroup(struct IDProperty *group, struct IDProperty *prop) ATTR_NONNULL();
100
101 IDProperty *IDP_GetPropertyFromGroup(struct IDProperty *prop, const char *name) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
102 IDProperty *IDP_GetPropertyTypeFromGroup(struct IDProperty *prop, const char *name, const char type) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
103 void *IDP_GetGroupIterator(struct IDProperty *prop) ATTR_WARN_UNUSED_RESULT;
104 IDProperty *IDP_GroupIterNext(void *vself) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
105 void IDP_FreeIterBeforeEnd(void *vself) ATTR_NONNULL();
106
107 /*-------- Main Functions --------*/
108 struct IDProperty *IDP_GetProperties(struct ID *id, const bool create_if_needed) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
109 struct IDProperty *IDP_CopyProperty(const struct IDProperty *prop) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
110
111 bool IDP_EqualsProperties_ex(IDProperty *prop1, IDProperty *prop2, const bool is_strict) ATTR_WARN_UNUSED_RESULT;
112
113 bool IDP_EqualsProperties(struct IDProperty *prop1, struct IDProperty *prop2) ATTR_WARN_UNUSED_RESULT;
114
115 struct IDProperty *IDP_New(const int type, const IDPropertyTemplate *val, const char *name) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
116
117 void IDP_FreeProperty(struct IDProperty *prop);
118
119 void IDP_ClearProperty(IDProperty *prop);
120
121 void IDP_UnlinkProperty(struct IDProperty *prop);
122
123 #define IDP_Int(prop)                     ((prop)->data.val)
124 #define IDP_Float(prop)        (*(float *)&(prop)->data.val)
125 #define IDP_Double(prop)      (*(double *)&(prop)->data.val)
126 #define IDP_String(prop)         ((char *) (prop)->data.pointer)
127 #define IDP_Array(prop)                   ((prop)->data.pointer)
128 #define IDP_IDPArray(prop) ((IDProperty *) (prop)->data.pointer)
129
130 #ifdef DEBUG
131 /* for printout only */
132 void IDP_spit(IDProperty *prop);
133 #endif
134
135 #endif /* __BKE_IDPROP_H__ */