style cleanup / comment formatting for bli/bke/bmesh
[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  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
19  * All rights reserved.
20  *
21  * Contributor(s): Joseph Eagar
22  *
23  * ***** END GPL LICENSE BLOCK *****
24  */
25  
26 #ifndef __BKE_IDPROP_H__
27 #define __BKE_IDPROP_H__
28
29 /** \file BKE_idprop.h
30  *  \ingroup bke
31  *  \author Joseph Eagar
32  */
33
34 #include "DNA_ID.h"
35
36 struct IDProperty;
37 struct ID;
38
39 typedef union IDPropertyTemplate {
40         int i;
41         float f;
42         double d;
43         struct {
44                 char *str;
45                 short len;
46                 char subtype;
47         } string;
48         struct ID *id;
49         struct {
50                 short type;
51                 short len;
52         } array;
53         struct {
54                 int matvec_size;
55                 float *example;
56         } matrix_or_vector;
57 } IDPropertyTemplate;
58
59 /* ----------- Property Array Type ---------- */
60
61 /* note: as a start to move away from the stupid IDP_New function, this type
62  * has it's own allocation function.*/
63 IDProperty *IDP_NewIDPArray(const char *name);
64 IDProperty *IDP_CopyIDPArray(IDProperty *array);
65
66 void IDP_FreeIDPArray(IDProperty *prop);
67
68 /* shallow copies item */
69 void IDP_SetIndexArray(struct IDProperty *prop, int index, struct IDProperty *item);
70 struct IDProperty *IDP_GetIndexArray(struct IDProperty *prop, int index);
71 struct IDProperty *IDP_AppendArray(struct IDProperty *prop, struct IDProperty *item);
72 void IDP_ResizeIDPArray(struct IDProperty *prop, int len);
73
74 /* ----------- Numeric Array Type ----------- */
75 /*this function works for strings too!*/
76 void IDP_ResizeArray(struct IDProperty *prop, int newlen);
77 void IDP_FreeArray(struct IDProperty *prop);
78
79 /* ---------- String Type ------------ */
80 IDProperty *IDP_NewString(const char *st, const char *name, int maxlen);/* maxlen excludes '\0' */
81 void IDP_AssignString(struct IDProperty *prop, const char *st, int maxlen);     /* maxlen excludes '\0' */
82 void IDP_ConcatStringC(struct IDProperty *prop, const char *st);
83 void IDP_ConcatString(struct IDProperty *str1, struct IDProperty *append);
84 void IDP_FreeString(struct IDProperty *prop);
85
86 /*-------- ID Type -------*/
87 void IDP_LinkID(struct IDProperty *prop, ID *id);
88 void IDP_UnlinkID(struct IDProperty *prop);
89
90 /*-------- Group Functions -------*/
91
92 /** Sync values from one group to another, only where they match */
93 void IDP_SyncGroupValues(struct IDProperty *dest, struct IDProperty *src);
94
95 /**
96  * replaces all properties with the same name in a destination group from a source group.
97  */
98 void IDP_ReplaceGroupInGroup(struct IDProperty *dest, struct IDProperty *src);
99
100 /**
101  * Checks if a property with the same name as prop exists, and if so replaces it.
102  * Use this to preserve order!*/
103 void IDP_ReplaceInGroup(struct IDProperty *group, struct IDProperty *prop);
104
105 /**
106  * This function has a sanity check to make sure ID properties with the same name don't
107  * get added to the group.
108  * 
109  * The sanity check just means the property is not added to the group if another property
110  * exists with the same name; the client code using ID properties then needs to detect this 
111  * (the function that adds new properties to groups, IDP_AddToGroup, returns 0 if a property can't
112  * be added to the group, and 1 if it can) and free the property.
113  * 
114  * Currently the code to free ID properties is designesd to leave the actual struct
115  * you pass it un-freed, this is needed for how the system works.  This means
116  * to free an ID property, you first call IDP_FreeProperty then MEM_freeN the
117  * struct.  In the future this will just be IDP_FreeProperty and the code will
118  * be reorganized to work properly.
119  */
120 int IDP_AddToGroup(struct IDProperty *group, struct IDProperty *prop);
121
122 /** this is the same as IDP_AddToGroup, only you pass an item
123  * in the group list to be inserted after. */
124 int IDP_InsertToGroup(struct IDProperty *group, struct IDProperty *previous, 
125                                           struct IDProperty *pnew);
126
127 /** \note this does not free the property!!
128  *
129  * To free the property, you have to do:
130  * IDP_FreeProperty(prop); //free all subdata
131  * MEM_freeN(prop); //free property struct itself
132  */
133 void IDP_RemFromGroup(struct IDProperty *group, struct IDProperty *prop);
134
135 IDProperty *IDP_GetPropertyFromGroup(struct IDProperty *prop, const char *name);
136 /** same as above but ensure type match */
137 IDProperty *IDP_GetPropertyTypeFromGroup(struct IDProperty *prop, const char *name, const char type);
138
139 /**
140  * Get an iterator to iterate over the members of an id property group.
141  * Note that this will automatically free the iterator once iteration is complete;
142  * if you stop the iteration before hitting the end, make sure to call
143  * IDP_FreeIterBeforeEnd(). */
144 void *IDP_GetGroupIterator(struct IDProperty *prop);
145
146 /**
147  * Returns the next item in the iteration.  To use, simple for a loop like the following:
148  * while (IDP_GroupIterNext(iter) != NULL) {
149  *     ...
150  * }
151  */
152 IDProperty *IDP_GroupIterNext(void *vself);
153
154 /**
155  * Frees the iterator pointed to at vself, only use this if iteration is stopped early; 
156  * when the iterator hits the end of the list it'll automatially free itself.*/
157 void IDP_FreeIterBeforeEnd(void *vself);
158
159 /*-------- Main Functions --------*/
160 /** Get the Group property that contains the id properties for ID id.  Set create_if_needed
161  * to create the Group property and attach it to id if it doesn't exist; otherwise
162  * the function will return NULL if there's no Group property attached to the ID.*/
163 struct IDProperty *IDP_GetProperties(struct ID *id, int create_if_needed);
164 struct IDProperty *IDP_CopyProperty(struct IDProperty *prop);
165
166 int IDP_EqualsProperties(struct IDProperty *prop1, struct IDProperty *prop2);
167
168 /**
169  * Allocate a new ID.
170  *
171  * This function takes three arguments: the ID property type, a union which defines
172  * it's initial value, and a name.
173  *
174  * The union is simple to use; see the top of this header file for its definition. 
175  * An example of using this function:
176  *
177  *     IDPropertyTemplate val;
178  *     IDProperty *group, *idgroup, *color;
179  *     group = IDP_New(IDP_GROUP, val, "group1"); //groups don't need a template.
180  *    
181  *     val.array.len = 4
182  *     val.array.type = IDP_FLOAT;
183  *     color = IDP_New(IDP_ARRAY, val, "color1");
184  *    
185  *     idgroup = IDP_GetProperties(some_id, 1);
186  *     IDP_AddToGroup(idgroup, color);
187  *     IDP_AddToGroup(idgroup, group);
188  * 
189  * Note that you MUST either attach the id property to an id property group with 
190  * IDP_AddToGroup or MEM_freeN the property, doing anything else might result in
191  * a memory leak.
192  */
193 struct IDProperty *IDP_New(const int type, const IDPropertyTemplate *val, const char *name);
194
195 /** \note this will free all child properties of list arrays and groups!
196  * Also, note that this does NOT unlink anything!  Plus it doesn't free
197  * the actual struct IDProperty struct either.*/
198 void IDP_FreeProperty(struct IDProperty *prop);
199
200 /** Unlinks any struct IDProperty<->ID linkage that might be going on.*/
201 void IDP_UnlinkProperty(struct IDProperty *prop);
202
203 #define IDP_Int(prop) ((prop)->data.val)
204 #define IDP_Float(prop) (*(float*)&(prop)->data.val)
205 #define IDP_String(prop) ((char*)(prop)->data.pointer)
206 #define IDP_Array(prop) ((prop)->data.pointer)
207 #define IDP_IDPArray(prop) ((IDProperty*)(prop)->data.pointer)
208 #define IDP_Double(prop) (*(double*)&(prop)->data.val)
209
210 #endif /* __BKE_IDPROP_H__ */