[#34013] [video sequence editor] Offset and crop of strips are wrong
[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 #ifdef __GNUC__
65 __attribute__((warn_unused_result))
66 __attribute__((nonnull))
67 #endif
68 ;
69 IDProperty *IDP_CopyIDPArray(IDProperty *array)
70 #ifdef __GNUC__
71 __attribute__((warn_unused_result))
72 __attribute__((nonnull))
73 #endif
74 ;
75
76 void IDP_FreeIDPArray(IDProperty *prop);
77
78 /* shallow copies item */
79 void IDP_SetIndexArray(struct IDProperty *prop, int index, struct IDProperty *item);
80 #ifdef __GNUC__
81 __attribute__((nonnull))
82 #endif
83 struct IDProperty *IDP_GetIndexArray(struct IDProperty *prop, int index)
84 #ifdef __GNUC__
85 __attribute__((warn_unused_result))
86 __attribute__((nonnull))
87 #endif
88 ;
89 void IDP_AppendArray(struct IDProperty *prop, struct IDProperty *item);
90 void IDP_ResizeIDPArray(struct IDProperty *prop, int len);
91
92 /* ----------- Numeric Array Type ----------- */
93 /*this function works for strings too!*/
94 void IDP_ResizeArray(struct IDProperty *prop, int newlen);
95 void IDP_FreeArray(struct IDProperty *prop);
96
97 /* ---------- String Type ------------ */
98 IDProperty *IDP_NewString(const char *st, const char *name, int maxlen) /* maxlen excludes '\0' */
99 #ifdef __GNUC__
100 __attribute__((warn_unused_result))
101 __attribute__((nonnull (2))) /* 'name' arg */
102 #endif
103 ;
104
105 void IDP_AssignString(struct IDProperty *prop, const char *st, int maxlen) /* maxlen excludes '\0' */
106 #ifdef __GNUC__
107 __attribute__((nonnull))
108 #endif
109 ;
110 void IDP_ConcatStringC(struct IDProperty *prop, const char *st)
111 #ifdef __GNUC__
112 __attribute__((nonnull))
113 #endif
114 ;
115 void IDP_ConcatString(struct IDProperty *str1, struct IDProperty *append)
116 #ifdef __GNUC__
117 __attribute__((nonnull))
118 #endif
119 ;
120 void IDP_FreeString(struct IDProperty *prop)
121 #ifdef __GNUC__
122 __attribute__((nonnull))
123 #endif
124 ;
125
126 /*-------- ID Type -------*/
127 void IDP_LinkID(struct IDProperty *prop, ID *id);
128 void IDP_UnlinkID(struct IDProperty *prop);
129
130 /*-------- Group Functions -------*/
131
132 /** Sync values from one group to another, only where they match */
133 void IDP_SyncGroupValues(struct IDProperty *dest, struct IDProperty *src)
134 #ifdef __GNUC__
135 __attribute__((nonnull))
136 #endif
137 ;
138
139 /**
140  * replaces all properties with the same name in a destination group from a source group.
141  */
142 void IDP_ReplaceGroupInGroup(struct IDProperty *dest, struct IDProperty *src)
143 #ifdef __GNUC__
144 __attribute__((nonnull))
145 #endif
146 ;
147
148 /**
149  * Checks if a property with the same name as prop exists, and if so replaces it.
150  * Use this to preserve order!*/
151 void IDP_ReplaceInGroup(struct IDProperty *group, struct IDProperty *prop)
152 #ifdef __GNUC__
153 __attribute__((nonnull))
154 #endif
155 ;
156
157 void IDP_MergeGroup(IDProperty *dest, IDProperty *src, const int do_overwrite)
158 #ifdef __GNUC__
159 __attribute__((nonnull))
160 #endif
161 ;
162
163 /**
164  * This function has a sanity check to make sure ID properties with the same name don't
165  * get added to the group.
166  * 
167  * The sanity check just means the property is not added to the group if another property
168  * exists with the same name; the client code using ID properties then needs to detect this 
169  * (the function that adds new properties to groups, IDP_AddToGroup, returns 0 if a property can't
170  * be added to the group, and 1 if it can) and free the property.
171  * 
172  * Currently the code to free ID properties is designed to leave the actual struct
173  * you pass it un-freed, this is needed for how the system works.  This means
174  * to free an ID property, you first call IDP_FreeProperty then MEM_freeN the
175  * struct.  In the future this will just be IDP_FreeProperty and the code will
176  * be reorganized to work properly.
177  */
178 int IDP_AddToGroup(struct IDProperty *group, struct IDProperty *prop)
179 #ifdef __GNUC__
180 __attribute__((nonnull))
181 #endif
182 ;
183
184 /** this is the same as IDP_AddToGroup, only you pass an item
185  * in the group list to be inserted after. */
186 int IDP_InsertToGroup(struct IDProperty *group, struct IDProperty *previous, 
187                       struct IDProperty *pnew)
188 #ifdef __GNUC__
189 __attribute__((nonnull  (1, 3))) /* 'group', 'pnew' */
190 #endif
191 ;
192
193 /** \note this does not free the property!!
194  *
195  * To free the property, you have to do:
196  * IDP_FreeProperty(prop); //free all subdata
197  * MEM_freeN(prop); //free property struct itself
198  */
199 void IDP_RemFromGroup(struct IDProperty *group, struct IDProperty *prop)
200 #ifdef __GNUC__
201 __attribute__((nonnull))
202 #endif
203 ;
204
205 IDProperty *IDP_GetPropertyFromGroup(struct IDProperty *prop, const char *name)
206 #ifdef __GNUC__
207 __attribute__((warn_unused_result))
208 __attribute__((nonnull))
209 #endif
210 ;
211 /** same as above but ensure type match */
212 IDProperty *IDP_GetPropertyTypeFromGroup(struct IDProperty *prop, const char *name, const char type)
213 #ifdef __GNUC__
214 __attribute__((warn_unused_result))
215 __attribute__((nonnull))
216 #endif
217 ;
218
219 /**
220  * Get an iterator to iterate over the members of an id property group.
221  * Note that this will automatically free the iterator once iteration is complete;
222  * if you stop the iteration before hitting the end, make sure to call
223  * IDP_FreeIterBeforeEnd(). */
224 void *IDP_GetGroupIterator(struct IDProperty *prop)
225 #ifdef __GNUC__
226 __attribute__((warn_unused_result))
227 #endif
228 ;
229
230 /**
231  * Returns the next item in the iteration.  To use, simple for a loop like the following:
232  * while (IDP_GroupIterNext(iter) != NULL) {
233  *     ...
234  * }
235  */
236 IDProperty *IDP_GroupIterNext(void *vself)
237 #ifdef __GNUC__
238 __attribute__((warn_unused_result))
239 __attribute__((nonnull))
240 #endif
241 ;
242
243 /**
244  * Frees the iterator pointed to at vself, only use this if iteration is stopped early; 
245  * when the iterator hits the end of the list it'll automatically free itself.*/
246 void IDP_FreeIterBeforeEnd(void *vself)
247 #ifdef __GNUC__
248 __attribute__((nonnull))
249 #endif
250 ;
251
252 /*-------- Main Functions --------*/
253 /** Get the Group property that contains the id properties for ID id.  Set create_if_needed
254  * to create the Group property and attach it to id if it doesn't exist; otherwise
255  * the function will return NULL if there's no Group property attached to the ID.*/
256 struct IDProperty *IDP_GetProperties(struct ID *id, int create_if_needed)
257 #ifdef __GNUC__
258 __attribute__((warn_unused_result))
259 __attribute__((nonnull))
260 #endif
261 ;
262 struct IDProperty *IDP_CopyProperty(struct IDProperty *prop)
263 #ifdef __GNUC__
264 __attribute__((warn_unused_result))
265 __attribute__((nonnull))
266 #endif
267 ;
268
269 int IDP_EqualsProperties_ex(IDProperty *prop1, IDProperty *prop2, const int is_strict)
270 #ifdef __GNUC__
271 __attribute__((warn_unused_result))
272 #endif
273 ;
274
275 int IDP_EqualsProperties(struct IDProperty *prop1, struct IDProperty *prop2)
276 #ifdef __GNUC__
277 __attribute__((warn_unused_result))
278 #endif
279 ;
280
281 /**
282  * Allocate a new ID.
283  *
284  * This function takes three arguments: the ID property type, a union which defines
285  * it's initial value, and a name.
286  *
287  * The union is simple to use; see the top of this header file for its definition. 
288  * An example of using this function:
289  *
290  *     IDPropertyTemplate val;
291  *     IDProperty *group, *idgroup, *color;
292  *     group = IDP_New(IDP_GROUP, val, "group1"); //groups don't need a template.
293  *    
294  *     val.array.len = 4
295  *     val.array.type = IDP_FLOAT;
296  *     color = IDP_New(IDP_ARRAY, val, "color1");
297  *    
298  *     idgroup = IDP_GetProperties(some_id, 1);
299  *     IDP_AddToGroup(idgroup, color);
300  *     IDP_AddToGroup(idgroup, group);
301  * 
302  * Note that you MUST either attach the id property to an id property group with 
303  * IDP_AddToGroup or MEM_freeN the property, doing anything else might result in
304  * a memory leak.
305  */
306 struct IDProperty *IDP_New(const int type, const IDPropertyTemplate *val, const char *name)
307 #ifdef __GNUC__
308 __attribute__((warn_unused_result))
309 __attribute__((nonnull))
310 #endif
311 ;
312
313 /** \note this will free all child properties of list arrays and groups!
314  * Also, note that this does NOT unlink anything!  Plus it doesn't free
315  * the actual struct IDProperty struct either.*/
316 void IDP_FreeProperty(struct IDProperty *prop);
317
318 void IDP_ClearProperty(IDProperty *prop);
319
320 /** Unlinks any struct IDProperty<->ID linkage that might be going on.*/
321 void IDP_UnlinkProperty(struct IDProperty *prop);
322
323 #define IDP_Int(prop)                     ((prop)->data.val)
324 #define IDP_Float(prop)        (*(float *)&(prop)->data.val)
325 #define IDP_Double(prop)      (*(double *)&(prop)->data.val)
326 #define IDP_String(prop)         ((char *) (prop)->data.pointer)
327 #define IDP_Array(prop)                   ((prop)->data.pointer)
328 #define IDP_IDPArray(prop) ((IDProperty *) (prop)->data.pointer)
329
330 #ifdef DEBUG
331 /* for printout only */
332 void IDP_spit(IDProperty *prop);
333 #endif
334
335 #endif /* __BKE_IDPROP_H__ */