1d344c6e81091e7a2daa88d63c26ce7a2bcfd24d
[blender.git] / source / blender / blenkernel / BKE_customdata.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) 2006 Blender Foundation.
19  * All rights reserved.
20  *
21  * The Original Code is: all of this file.
22  *
23  * Contributor(s): Ben Batt <benbatt@gmail.com>
24  *
25  * ***** END GPL LICENSE BLOCK *****
26  */
27
28 /** \file BKE_customdata.h
29  *  \ingroup bke
30  *  \author Ben Batt
31  *  \brief CustomData interface, see also DNA_customdata_types.h.
32  */
33
34 #ifndef BKE_CUSTOMDATA_H
35 #define BKE_CUSTOMDATA_H
36
37 #ifdef __cplusplus
38 extern "C" {
39 #endif
40
41 struct ID;
42 struct CustomData;
43 struct CustomDataLayer;
44 typedef unsigned int CustomDataMask;
45
46 extern const CustomDataMask CD_MASK_BAREMESH;
47 extern const CustomDataMask CD_MASK_MESH;
48 extern const CustomDataMask CD_MASK_EDITMESH;
49 extern const CustomDataMask CD_MASK_DERIVEDMESH;
50 extern const CustomDataMask CD_MASK_BMESH;
51 extern const CustomDataMask CD_MASK_FACECORNERS;
52
53 /* for ORIGINDEX layer type, indicates no original index for this element */
54 #define ORIGINDEX_NONE -1
55
56 /* initialises a CustomData object with the same layer setup as source and
57  * memory space for totelem elements. mask must be an array of length
58  * CD_NUMTYPES elements, that indicate if a layer can be copied. */
59
60 /* add/copy/merge allocation types */
61 #define CD_ASSIGN    0  /* use the data pointer */
62 #define CD_CALLOC    1  /* allocate blank memory */
63 #define CD_DEFAULT   2  /* allocate and set to default */
64 #define CD_REFERENCE 3  /* use data pointers, set layer flag NOFREE */
65 #define CD_DUPLICATE 4  /* do a full copy of all layers, only allowed if source
66                                                    has same number of elements */
67
68 /* initialises a CustomData object with the same layer setup as source.
69  * mask is a bitfield where (mask & (1 << (layer type))) indicates
70  * if a layer should be copied or not. alloctype must be one of the above. */
71 void CustomData_copy(const struct CustomData *source, struct CustomData *dest,
72                                          CustomDataMask mask, int alloctype, int totelem);
73
74 /* same as the above, except that this will preserve existing layers, and only
75  * add the layers that were not there yet */
76 void CustomData_merge(const struct CustomData *source, struct CustomData *dest,
77                                           CustomDataMask mask, int alloctype, int totelem);
78
79 /* frees data associated with a CustomData object (doesn't free the object
80  * itself, though)
81  */
82 void CustomData_free(struct CustomData *data, int totelem);
83
84 /* frees all layers with CD_FLAG_TEMPORARY */
85 void CustomData_free_temporary(struct CustomData *data, int totelem);
86
87 /* adds a data layer of the given type to the CustomData object, optionally
88  * backed by an external data array. the different allocation types are
89  * defined above. returns the data of the layer.
90  *
91  * in editmode, use EM_add_data_layer instead of this function
92  */
93 void *CustomData_add_layer(struct CustomData *data, int type, int alloctype,
94                                                    void *layer, int totelem);
95 /*same as above but accepts a name */
96 void *CustomData_add_layer_named(struct CustomData *data, int type, int alloctype,
97                                                    void *layer, int totelem, const char *name);
98
99 /* frees the active or first data layer with the give type.
100  * returns 1 on succes, 0 if no layer with the given type is found
101  *
102  * in editmode, use EM_free_data_layer instead of this function
103  */
104 int CustomData_free_layer(struct CustomData *data, int type, int totelem, int index);
105
106 /* frees the layer index with the give type.
107  * returns 1 on succes, 0 if no layer with the given type is found
108  *
109  * in editmode, use EM_free_data_layer instead of this function
110  */
111 int CustomData_free_layer_active(struct CustomData *data, int type, int totelem);
112
113 /* same as above, but free all layers with type */
114 void CustomData_free_layers(struct CustomData *data, int type, int totelem);
115
116 /* returns 1 if a layer with the specified type exists */
117 int CustomData_has_layer(const struct CustomData *data, int type);
118
119 /* returns the number of layers with this type */
120 int CustomData_number_of_layers(const struct CustomData *data, int type);
121
122 /* duplicate data of a layer with flag NOFREE, and remove that flag.
123  * returns the layer data */
124 void *CustomData_duplicate_referenced_layer(struct CustomData *data, const int type, const int totelem);
125 void *CustomData_duplicate_referenced_layer_named(struct CustomData *data,
126                                                                                                   const int type, const char *name, const int totelem);
127
128 /* set the CD_FLAG_NOCOPY flag in custom data layers where the mask is
129  * zero for the layer type, so only layer types specified by the mask
130  * will be copied
131  */
132 void CustomData_set_only_copy(const struct CustomData *data,
133                                                           CustomDataMask mask);
134
135 /* copies data from one CustomData object to another
136  * objects need not be compatible, each source layer is copied to the
137  * first dest layer of correct type (if there is none, the layer is skipped)
138  * return 1 on success, 0 on failure
139  */
140 void CustomData_copy_data(const struct CustomData *source,
141                                                   struct CustomData *dest, int source_index,
142                                                   int dest_index, int count);
143 void CustomData_em_copy_data(const struct CustomData *source,
144                                                         struct CustomData *dest, void *src_block,
145                                                         void **dest_block);
146 void CustomData_bmesh_copy_data(const struct CustomData *source, 
147                                                         struct CustomData *dest,void *src_block, 
148                                                         void **dest_block);
149 void CustomData_em_validate_data(struct CustomData *data, void *block, int sub_elements);
150
151 /* frees data in a CustomData object
152  * return 1 on success, 0 on failure
153  */
154 void CustomData_free_elem(struct CustomData *data, int index, int count);
155
156 /* interpolates data from one CustomData object to another
157  * objects need not be compatible, each source layer is interpolated to the
158  * first dest layer of correct type (if there is none, the layer is skipped)
159  * if weights == NULL or sub_weights == NULL, they default to all 1's
160  *
161  * src_indices gives the source elements to interpolate from
162  * weights gives the weight for each source element
163  * sub_weights is an array of matrices of weights for sub-elements (matrices
164  *     should be source->subElems * source->subElems in size)
165  * count gives the number of source elements to interpolate from
166  * dest_index gives the dest element to write the interpolated value to
167  *
168  * returns 1 on success, 0 on failure
169  */
170 void CustomData_interp(const struct CustomData *source, struct CustomData *dest,
171                                            int *src_indices, float *weights, float *sub_weights,
172                                            int count, int dest_index);
173 void CustomData_em_interp(struct CustomData *data,  void **src_blocks,
174                                                   float *weights, float *sub_weights, int count,
175                                                   void *dest_block);
176 void CustomData_bmesh_interp(struct CustomData *data, void **src_blocks, 
177                                                          float *weights, float *sub_weights, int count, 
178                                                          void *dest_block);
179
180
181 /* swaps the data in the element corners, to new corners with indices as
182    specified in corner_indices. for edges this is an array of length 2, for
183    faces an array of length 4 */
184 void CustomData_swap(struct CustomData *data, int index, const int *corner_indices);
185
186 /* gets a pointer to the data element at index from the first layer of type
187  * returns NULL if there is no layer of type
188  */
189 void *CustomData_get(const struct CustomData *data, int index, int type);
190 void *CustomData_em_get(const struct CustomData *data, void *block, int type);
191 void *CustomData_em_get_n(const struct CustomData *data, void *block, int type, int n);
192 void *CustomData_bmesh_get(const struct CustomData *data, void *block, int type);
193 void *CustomData_bmesh_get_n(const struct CustomData *data, void *block, int type, int n);
194
195 /* gets a pointer to the active or first layer of type
196  * returns NULL if there is no layer of type
197  */
198 void *CustomData_get_layer(const struct CustomData *data, int type);
199 void *CustomData_get_layer_n(const struct CustomData *data, int type, int n);
200 void *CustomData_get_layer_named(const struct CustomData *data, int type,
201                                                                  const char *name);
202
203 int CustomData_get_layer_index(const struct CustomData *data, int type);
204 int CustomData_get_named_layer_index(const struct CustomData *data, int type, const char *name);
205 int CustomData_get_active_layer_index(const struct CustomData *data, int type);
206 int CustomData_get_render_layer_index(const struct CustomData *data, int type);
207 int CustomData_get_clone_layer_index(const struct CustomData *data, int type);
208 int CustomData_get_stencil_layer_index(const struct CustomData *data, int type);
209 int CustomData_get_active_layer(const struct CustomData *data, int type);
210 int CustomData_get_render_layer(const struct CustomData *data, int type);
211 int CustomData_get_clone_layer(const struct CustomData *data, int type);
212 int CustomData_get_stencil_layer(const struct CustomData *data, int type);
213
214 /* copies the data from source to the data element at index in the first
215  * layer of type
216  * no effect if there is no layer of type
217  */
218 void CustomData_set(const struct CustomData *data, int index, int type,
219                                         void *source);
220 void CustomData_em_set(struct CustomData *data, void *block, int type,
221                                            void *source);
222 void CustomData_em_set_n(struct CustomData *data, void *block, int type, int n,
223                                                  void *source);
224
225 void CustomData_bmesh_set(const struct CustomData *data, void *block, int type, 
226                                                   void *source);
227
228 void CustomData_bmesh_set_n(struct CustomData *data, void *block, int type, int n, 
229                                                         void *source);
230
231 /* set the pointer of to the first layer of type. the old data is not freed.
232  * returns the value of ptr if the layer is found, NULL otherwise
233  */
234 void *CustomData_set_layer(const struct CustomData *data, int type, void *ptr);
235 void *CustomData_set_layer_n(const struct CustomData *data, int type, int n, void *ptr);
236
237 /* sets the nth layer of type as active */
238 void CustomData_set_layer_active(struct CustomData *data, int type, int n);
239 void CustomData_set_layer_render(struct CustomData *data, int type, int n);
240 void CustomData_set_layer_clone(struct CustomData *data, int type, int n);
241 void CustomData_set_layer_stencil(struct CustomData *data, int type, int n);
242
243 /* same as above but works with an index from CustomData_get_layer_index */
244 void CustomData_set_layer_active_index(struct CustomData *data, int type, int n);
245 void CustomData_set_layer_render_index(struct CustomData *data, int type, int n);
246 void CustomData_set_layer_clone_index(struct CustomData *data, int type, int n);
247 void CustomData_set_layer_stencil_index(struct CustomData *data, int type, int n);
248
249 /* adds flag to the layer flags */
250 void CustomData_set_layer_flag(struct CustomData *data, int type, int flag);
251
252 /* alloc/free a block of custom data attached to one element in editmode */
253 void CustomData_em_set_default(struct CustomData *data, void **block);
254 void CustomData_em_free_block(struct CustomData *data, void **block);
255
256 void CustomData_bmesh_set_default(struct CustomData *data, void **block);
257 void CustomData_bmesh_free_block(struct CustomData *data, void **block);
258
259 /* copy custom data to/from layers as in mesh/derivedmesh, to editmesh
260    blocks of data. the CustomData's must not be compatible  */
261 void CustomData_to_em_block(const struct CustomData *source,
262                                                         struct CustomData *dest, int index, void **block);
263 void CustomData_from_em_block(const struct CustomData *source,
264                                                           struct CustomData *dest, void *block, int index);
265 void CustomData_to_bmesh_block(const struct CustomData *source, 
266                                                         struct CustomData *dest, int src_index, void **dest_block);
267 void CustomData_from_bmesh_block(const struct CustomData *source, 
268                                                         struct CustomData *dest, void *src_block, int dest_index);
269
270
271 /* query info over types */
272 void CustomData_file_write_info(int type, const char **structname, int *structnum);
273 int CustomData_sizeof(int type);
274
275 /* get the name of a layer type */
276 const char *CustomData_layertype_name(int type);
277
278 /* make sure the name of layer at index is unique */
279 void CustomData_set_layer_unique_name(struct CustomData *data, int index);
280
281 void CustomData_validate_layer_name(const struct CustomData *data, int type, char *name, char *outname);
282
283 /* for file reading compatibility, returns false if the layer was freed,
284    only after this test passes, layer->data should be assigned */
285 int CustomData_verify_versions(struct CustomData *data, int index);
286
287 /*BMesh specific customdata stuff*/
288 void CustomData_to_bmeshpoly(struct CustomData *fdata, struct CustomData *pdata,
289                              struct CustomData *ldata);
290 void CustomData_from_bmeshpoly(struct CustomData *fdata, struct CustomData *pdata, struct CustomData *ldata, int total);
291 void CustomData_bmesh_init_pool(struct CustomData *data, int allocsize);
292
293 /* External file storage */
294
295 void CustomData_external_add(struct CustomData *data,
296         struct ID *id, int type, int totelem, const char *filename);
297 void CustomData_external_remove(struct CustomData *data,
298         struct ID *id, int type, int totelem);
299 int CustomData_external_test(struct CustomData *data, int type);
300
301 void CustomData_external_write(struct CustomData *data,
302         struct ID *id, CustomDataMask mask, int totelem, int free);
303 void CustomData_external_read(struct CustomData *data,
304         struct ID *id, CustomDataMask mask, int totelem);
305 void CustomData_external_reload(struct CustomData *data,
306         struct ID *id, CustomDataMask mask, int totelem);
307
308 #ifdef __cplusplus
309 }
310 #endif
311
312 #endif
313