svn merge -r36651:36672 https://svn.blender.org/svnroot/bf-blender/trunk/blender
[blender.git] / source / blender / blenkernel / BKE_customdata.h
1 /*
2 * $Id$
3 *
4 * ***** BEGIN GPL LICENSE BLOCK *****
5 *
6 * This program is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU General Public License
8 * as published by the Free Software Foundation; either version 2
9 * of the License, or (at your option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program; if not, write to the Free Software  Foundation,
18 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
19 *
20 * The Original Code is Copyright (C) 2006 Blender Foundation.
21 * All rights reserved.
22 *
23 * The Original Code is: all of this file.
24 *
25 * Contributor(s): Ben Batt <benbatt@gmail.com>
26 *
27 * ***** END GPL LICENSE BLOCK *****
28 */ 
29
30 /** \file BKE_customdata.h
31  *  \ingroup bke
32  *  \author Ben Batt
33  *  \brief CustomData interface, see also DNA_customdata_types.h.
34  */
35
36 #ifndef BKE_CUSTOMDATA_H
37 #define BKE_CUSTOMDATA_H
38
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42
43 struct BMesh;
44 struct ID;
45 struct CustomData;
46 struct CustomDataLayer;
47 typedef unsigned int CustomDataMask;
48
49 /*a data type large enough to hold 1 element from any customdata layer type*/
50 typedef struct {unsigned char data[64];} CDBlockBytes;
51
52 extern const CustomDataMask CD_MASK_BAREMESH;
53 extern const CustomDataMask CD_MASK_MESH;
54 extern const CustomDataMask CD_MASK_EDITMESH;
55 extern const CustomDataMask CD_MASK_DERIVEDMESH;
56 extern const CustomDataMask CD_MASK_BMESH;
57 extern const CustomDataMask CD_MASK_FACECORNERS;
58
59 /* for ORIGINDEX layer type, indicates no original index for this element */
60 #define ORIGINDEX_NONE -1
61
62 /* initialises a CustomData object with the same layer setup as source and
63  * memory space for totelem elements. mask must be an array of length
64  * CD_NUMTYPES elements, that indicate if a layer can be copied. */
65
66 /* add/copy/merge allocation types */
67 #define CD_ASSIGN    0  /* use the data pointer */
68 #define CD_CALLOC    1  /* allocate blank memory */
69 #define CD_DEFAULT   2  /* allocate and set to default */
70 #define CD_REFERENCE 3  /* use data pointers, set layer flag NOFREE */
71 #define CD_DUPLICATE 4  /* do a full copy of all layers, only allowed if source
72                                                    has same number of elements */
73
74 /* Checks if the layer at physical offset layern (in data->layers) support math
75  * the below operations.
76  */
77 int CustomData_layer_has_math(struct CustomData *data, int layern);
78
79 /*copies the "value" (e.g. mloopuv uv or mloopcol colors) from one block to
80   another, while not overwriting anything else (e.g. flags).  probably only
81   implemented for mloopuv/mloopcol, for now.*/
82 void CustomData_data_copy_value(int type, void *source, void *dest);
83
84 /* compares if data1 is equal to data2.  type is a valid CustomData type
85  * enum (e.g. CD_MLOOPUV). the layer type's equal function is used to compare
86  * the data, if it exists, otherwise memcmp is used.*/
87 int CustomData_data_equals(int type, void *data1, void *data2);
88 void CustomData_data_initminmax(int type, void *min, void *max);
89 void CustomData_data_dominmax(int type, void *data, void *min, void *max);
90 void CustomData_data_multiply(int type, void *data, float fac);
91 void CustomData_data_add(int type, void *data1, void *data2);
92
93 /* initialises a CustomData object with the same layer setup as source.
94  * mask is a bitfield where (mask & (1 << (layer type))) indicates
95  * if a layer should be copied or not. alloctype must be one of the above. */
96 void CustomData_copy(const struct CustomData *source, struct CustomData *dest,
97                                          CustomDataMask mask, int alloctype, int totelem);
98
99 /* TODO, not really a public function but readfile.c needs it */
100 void CustomData_update_typemap(struct CustomData *data);
101
102 /* same as the above, except that this will preserve existing layers, and only
103  * add the layers that were not there yet */
104 void CustomData_merge(const struct CustomData *source, struct CustomData *dest,
105                                           CustomDataMask mask, int alloctype, int totelem);
106
107 /*bmesh version of CustomData_merge; merges the layouts of source and dest,
108   then goes through the mesh and makes sure all the customdata blocks are
109   consistent with the new layout.*/
110 void CustomData_bmesh_merge(struct CustomData *source, struct CustomData *dest, 
111                             int mask, int alloctype, struct BMesh *bm, int type);
112
113 /* frees data associated with a CustomData object (doesn't free the object
114  * itself, though)
115  */
116 void CustomData_free(struct CustomData *data, int totelem);
117
118 /* frees all layers with CD_FLAG_TEMPORARY */
119 void CustomData_free_temporary(struct CustomData *data, int totelem);
120
121 /* adds a data layer of the given type to the CustomData object, optionally
122  * backed by an external data array. the different allocation types are
123  * defined above. returns the data of the layer.
124  *
125  * in editmode, use EM_add_data_layer instead of this function
126  */
127 void *CustomData_add_layer(struct CustomData *data, int type, int alloctype,
128                                                    void *layer, int totelem);
129 /*same as above but accepts a name */
130 void *CustomData_add_layer_named(struct CustomData *data, int type, int alloctype,
131                                                    void *layer, int totelem, const char *name);
132
133 /* frees the active or first data layer with the give type.
134  * returns 1 on succes, 0 if no layer with the given type is found
135  *
136  * in editmode, use EM_free_data_layer instead of this function
137  */
138 int CustomData_free_layer(struct CustomData *data, int type, int totelem, int index);
139
140 /* frees the layer index with the give type.
141  * returns 1 on succes, 0 if no layer with the given type is found
142  *
143  * in editmode, use EM_free_data_layer instead of this function
144  */
145 int CustomData_free_layer_active(struct CustomData *data, int type, int totelem);
146
147 /* same as above, but free all layers with type */
148 void CustomData_free_layers(struct CustomData *data, int type, int totelem);
149
150 /* returns 1 if a layer with the specified type exists */
151 int CustomData_has_layer(const struct CustomData *data, int type);
152
153 /* returns the number of layers with this type */
154 int CustomData_number_of_layers(const struct CustomData *data, int type);
155
156 /* duplicate data of a layer with flag NOFREE, and remove that flag.
157  * returns the layer data */
158 void *CustomData_duplicate_referenced_layer(struct CustomData *data, int type);
159 void *CustomData_duplicate_referenced_layer_named(struct CustomData *data,
160                                                                                                   int type, const char *name);
161
162 /* set the CD_FLAG_NOCOPY flag in custom data layers where the mask is
163  * zero for the layer type, so only layer types specified by the mask
164  * will be copied
165  */
166 void CustomData_set_only_copy(const struct CustomData *data,
167                                                           CustomDataMask mask);
168
169 /* copies data from one CustomData object to another
170  * objects need not be compatible, each source layer is copied to the
171  * first dest layer of correct type (if there is none, the layer is skipped)
172  * return 1 on success, 0 on failure
173  */
174 void CustomData_copy_data(const struct CustomData *source,
175                                                   struct CustomData *dest, int source_index,
176                                                   int dest_index, int count);
177 void CustomData_copy_elements(int type, void *source, void *dest, int count);
178 void CustomData_em_copy_data(const struct CustomData *source,
179                                                         struct CustomData *dest, void *src_block,
180                                                         void **dest_block);
181 void CustomData_bmesh_copy_data(const struct CustomData *source, 
182                                 struct CustomData *dest, void *src_block, 
183                                 void **dest_block);
184 void CustomData_em_validate_data(struct CustomData *data, void *block, int sub_elements);
185
186 /* frees data in a CustomData object
187  * return 1 on success, 0 on failure
188  */
189 void CustomData_free_elem(struct CustomData *data, int index, int count);
190
191 /* interpolates data from one CustomData object to another
192  * objects need not be compatible, each source layer is interpolated to the
193  * first dest layer of correct type (if there is none, the layer is skipped)
194  * if weights == NULL or sub_weights == NULL, they default to all 1's
195  *
196  * src_indices gives the source elements to interpolate from
197  * weights gives the weight for each source element
198  * sub_weights is an array of matrices of weights for sub-elements (matrices
199  *     should be source->subElems * source->subElems in size)
200  * count gives the number of source elements to interpolate from
201  * dest_index gives the dest element to write the interpolated value to
202  *
203  * returns 1 on success, 0 on failure
204  */
205 void CustomData_interp(const struct CustomData *source, struct CustomData *dest,
206                                            int *src_indices, float *weights, float *sub_weights,
207                                            int count, int dest_index);
208 void CustomData_em_interp(struct CustomData *data,  void **src_blocks,
209                                                   float *weights, float *sub_weights, int count,
210                                                   void *dest_block);
211 void CustomData_bmesh_interp(struct CustomData *data, void **src_blocks, 
212                                                          float *weights, float *sub_weights, int count, 
213                                                          void *dest_block);
214
215
216 /* swaps the data in the element corners, to new corners with indices as
217    specified in corner_indices. for edges this is an array of length 2, for
218    faces an array of length 4 */
219 void CustomData_swap(struct CustomData *data, int index, const int *corner_indices);
220
221 /* gets a pointer to the data element at index from the first layer of type
222  * returns NULL if there is no layer of type
223  */
224 void *CustomData_get(const struct CustomData *data, int index, int type);
225 void *CustomData_get_n(const struct CustomData *data, int type, int index, int n);
226 void *CustomData_em_get(const struct CustomData *data, void *block, int type);
227 void *CustomData_em_get_n(const struct CustomData *data, void *block, int type, int n);
228 void *CustomData_bmesh_get(const struct CustomData *data, void *block, int type);
229 void *CustomData_bmesh_get_n(const struct CustomData *data, void *block, int type, int n);
230
231 /* gets the layer at physical index n, with no type checking.
232  */
233 void *CustomData_bmesh_get_layer_n(const struct CustomData *data, void *block, int n);
234
235 int CustomData_set_layer_name(const struct CustomData *data, int type, int n, const char *name);
236
237 /* gets a pointer to the active or first layer of type
238  * returns NULL if there is no layer of type
239  */
240 void *CustomData_get_layer(const struct CustomData *data, int type);
241 void *CustomData_get_layer_n(const struct CustomData *data, int type, int n);
242 void *CustomData_get_layer_named(const struct CustomData *data, int type,
243                                                                  const char *name);
244 int CustomData_get_layer_index(const struct CustomData *data, int type);
245 int CustomData_get_layer_index_n(const struct CustomData *data, int type, int n);
246 int CustomData_get_named_layer_index(const struct CustomData *data, int type, const char *name);
247 int CustomData_get_active_layer_index(const struct CustomData *data, int type);
248 int CustomData_get_render_layer_index(const struct CustomData *data, int type);
249 int CustomData_get_clone_layer_index(const struct CustomData *data, int type);
250 int CustomData_get_stencil_layer_index(const struct CustomData *data, int type);
251 int CustomData_get_active_layer(const struct CustomData *data, int type);
252 int CustomData_get_render_layer(const struct CustomData *data, int type);
253 int CustomData_get_clone_layer(const struct CustomData *data, int type);
254 int CustomData_get_stencil_layer(const struct CustomData *data, int type);
255
256 /* copies the data from source to the data element at index in the first
257  * layer of type
258  * no effect if there is no layer of type
259  */
260 void CustomData_set(const struct CustomData *data, int index, int type,
261                                         void *source);
262 void CustomData_em_set(struct CustomData *data, void *block, int type,
263                                            void *source);
264 void CustomData_em_set_n(struct CustomData *data, void *block, int type, int n,
265                                                  void *source);
266
267 void CustomData_bmesh_set(const struct CustomData *data, void *block, int type, 
268                                                   void *source);
269
270 void CustomData_bmesh_set_n(struct CustomData *data, void *block, int type, int n, 
271                                                         void *source);
272 /*sets the data of the block at physical layer n.  no real type checking 
273  *is performed.
274  */
275 void CustomData_bmesh_set_layer_n(struct CustomData *data, void *block, int n,
276                                                         void *source);
277
278 /* set the pointer of to the first layer of type. the old data is not freed.
279  * returns the value of ptr if the layer is found, NULL otherwise
280  */
281 void *CustomData_set_layer(const struct CustomData *data, int type, void *ptr);
282 void *CustomData_set_layer_n(const struct CustomData *data, int type, int n, void *ptr);
283
284 /* sets the nth layer of type as active */
285 void CustomData_set_layer_active(struct CustomData *data, int type, int n);
286 void CustomData_set_layer_render(struct CustomData *data, int type, int n);
287 void CustomData_set_layer_clone(struct CustomData *data, int type, int n);
288 void CustomData_set_layer_stencil(struct CustomData *data, int type, int n);
289
290 /* same as above but works with an index from CustomData_get_layer_index */
291 void CustomData_set_layer_active_index(struct CustomData *data, int type, int n);
292 void CustomData_set_layer_render_index(struct CustomData *data, int type, int n);
293 void CustomData_set_layer_clone_index(struct CustomData *data, int type, int n);
294 void CustomData_set_layer_stencil_index(struct CustomData *data, int type, int n);
295
296 /* adds flag to the layer flags */
297 void CustomData_set_layer_flag(struct CustomData *data, int type, int flag);
298
299 /* alloc/free a block of custom data attached to one element in editmode */
300 void CustomData_em_set_default(struct CustomData *data, void **block);
301 void CustomData_em_free_block(struct CustomData *data, void **block);
302
303 void CustomData_bmesh_set_default(struct CustomData *data, void **block);
304 void CustomData_bmesh_free_block(struct CustomData *data, void **block);
305
306 /* copy custom data to/from layers as in mesh/derivedmesh, to editmesh
307    blocks of data. the CustomData's must not be compatible  */
308 void CustomData_to_em_block(const struct CustomData *source,
309                                                         struct CustomData *dest, int index, void **block);
310 void CustomData_from_em_block(const struct CustomData *source,
311                                                           struct CustomData *dest, void *block, int index);
312 void CustomData_to_bmesh_block(const struct CustomData *source, 
313                                                         struct CustomData *dest, int src_index, void **dest_block);
314 void CustomData_from_bmesh_block(const struct CustomData *source, 
315                                                         struct CustomData *dest, void *src_block, int dest_index);
316
317
318 /* query info over types */
319 void CustomData_file_write_info(int type, const char **structname, int *structnum);
320 int CustomData_sizeof(int type);
321
322 /* get the name of a layer type */
323 const char *CustomData_layertype_name(int type);
324
325 /* make sure the name of layer at index is unique */
326 void CustomData_set_layer_unique_name(struct CustomData *data, int index);
327
328 /* for file reading compatibility, returns false if the layer was freed,
329    only after this test passes, layer->data should be assigned */
330 int CustomData_verify_versions(struct CustomData *data, int index);
331
332 /*BMesh specific customdata stuff*/
333 void CustomData_to_bmeshpoly(struct CustomData *fdata, struct CustomData *pdata,
334                              struct CustomData *ldata, int totloop, int totpoly);
335 void CustomData_from_bmeshpoly(struct CustomData *fdata, struct CustomData *pdata, struct CustomData *ldata, int total);
336 void CustomData_bmesh_init_pool(struct CustomData *data, int allocsize);
337
338 /* External file storage */
339
340 void CustomData_external_add(struct CustomData *data,
341         struct ID *id, int type, int totelem, const char *filename);
342 void CustomData_external_remove(struct CustomData *data,
343         struct ID *id, int type, int totelem);
344 int CustomData_external_test(struct CustomData *data, int type);
345
346 void CustomData_external_write(struct CustomData *data,
347         struct ID *id, CustomDataMask mask, int totelem, int free);
348 void CustomData_external_read(struct CustomData *data,
349         struct ID *id, CustomDataMask mask, int totelem);
350 void CustomData_external_reload(struct CustomData *data,
351         struct ID *id, CustomDataMask mask, int totelem);
352
353 #ifdef __cplusplus
354 }
355 #endif
356
357 #endif
358