Code cleanup: use r_ prefix for return args
[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 #include "BLI_sys_types.h"
42 #include "BLI_utildefines.h"
43
44 struct BMesh;
45 struct ID;
46 struct CustomData;
47 struct CustomDataLayer;
48 typedef uint64_t CustomDataMask;
49
50 /*a data type large enough to hold 1 element from any customdata layer type*/
51 typedef struct {unsigned char data[64]; } CDBlockBytes;
52
53 extern const CustomDataMask CD_MASK_BAREMESH;
54 extern const CustomDataMask CD_MASK_MESH;
55 extern const CustomDataMask CD_MASK_EDITMESH;
56 extern const CustomDataMask CD_MASK_DERIVEDMESH;
57 extern const CustomDataMask CD_MASK_BMESH;
58 extern const CustomDataMask CD_MASK_FACECORNERS;
59 extern const CustomDataMask CD_MASK_EVERYTHING;
60
61 /* for ORIGINDEX layer type, indicates no original index for this element */
62 #define ORIGINDEX_NONE -1
63
64 /* initializes a CustomData object with the same layer setup as source and
65  * memory space for totelem elements. mask must be an array of length
66  * CD_NUMTYPES elements, that indicate if a layer can be copied. */
67
68 /* add/copy/merge allocation types */
69 #define CD_ASSIGN    0  /* use the data pointer */
70 #define CD_CALLOC    1  /* allocate blank memory */
71 #define CD_DEFAULT   2  /* allocate and set to default */
72 #define CD_REFERENCE 3  /* use data pointers, set layer flag NOFREE */
73 #define CD_DUPLICATE 4  /* do a full copy of all layers, only allowed if source
74                          * has same number of elements */
75
76 #define CD_TYPE_AS_MASK(_type) (CustomDataMask)((CustomDataMask)1 << (CustomDataMask)(_type))
77
78 void customData_mask_layers__print(CustomDataMask mask);
79
80 /**
81  * Checks if the layer at physical offset \a layer_n (in data->layers) support math
82  * the below operations.
83  */
84 bool CustomData_layer_has_math(struct CustomData *data, int layer_n);
85 bool CustomData_layer_has_interp(struct CustomData *data, int layer_n);
86
87 /**
88  * Checks if any of the customdata layers has math.
89  */
90 bool CustomData_has_math(struct CustomData *data);
91 bool CustomData_has_interp(struct CustomData *data);
92 bool CustomData_bmesh_has_free(struct CustomData *data);
93
94 /* copies the "value" (e.g. mloopuv uv or mloopcol colors) from one block to
95  * another, while not overwriting anything else (e.g. flags).  probably only
96  * implemented for mloopuv/mloopcol, for now.*/
97 void CustomData_data_copy_value(int type, void *source, void *dest);
98
99 /* compares if data1 is equal to data2.  type is a valid CustomData type
100  * enum (e.g. CD_MLOOPUV). the layer type's equal function is used to compare
101  * the data, if it exists, otherwise memcmp is used.*/
102 bool CustomData_data_equals(int type, void *data1, void *data2);
103 void CustomData_data_initminmax(int type, void *min, void *max);
104 void CustomData_data_dominmax(int type, void *data, void *min, void *max);
105 void CustomData_data_multiply(int type, void *data, float fac);
106 void CustomData_data_add(int type, void *data1, void *data2);
107
108 /* initializes a CustomData object with the same layer setup as source.
109  * mask is a bitfield where (mask & (1 << (layer type))) indicates
110  * if a layer should be copied or not. alloctype must be one of the above. */
111 void CustomData_copy(const struct CustomData *source, struct CustomData *dest,
112                      CustomDataMask mask, int alloctype, int totelem);
113
114 /* BMESH_TODO, not really a public function but readfile.c needs it */
115 void CustomData_update_typemap(struct CustomData *data);
116
117 /* same as the above, except that this will preserve existing layers, and only
118  * add the layers that were not there yet */
119 bool CustomData_merge(const struct CustomData *source, struct CustomData *dest,
120                       CustomDataMask mask, int alloctype, int totelem);
121
122 /* bmesh version of CustomData_merge; merges the layouts of source and dest,
123  * then goes through the mesh and makes sure all the customdata blocks are
124  * consistent with the new layout.*/
125 bool CustomData_bmesh_merge(struct CustomData *source, struct CustomData *dest,
126                             CustomDataMask mask, int alloctype, struct BMesh *bm, const char htype);
127
128 /** NULL's all members and resets the typemap. */
129 void CustomData_reset(struct CustomData *data);
130
131 /** frees data associated with a CustomData object (doesn't free the object
132  * itself, though)
133  */
134 void CustomData_free(struct CustomData *data, int totelem);
135
136 /* frees all layers with CD_FLAG_TEMPORARY */
137 void CustomData_free_temporary(struct CustomData *data, int totelem);
138
139 /* adds a data layer of the given type to the CustomData object, optionally
140  * backed by an external data array. the different allocation types are
141  * defined above. returns the data of the layer.
142  */
143 void *CustomData_add_layer(struct CustomData *data, int type, int alloctype,
144                            void *layer, int totelem);
145 /*same as above but accepts a name */
146 void *CustomData_add_layer_named(struct CustomData *data, int type, int alloctype,
147                                  void *layer, int totelem, const char *name);
148
149 /* frees the active or first data layer with the give type.
150  * returns 1 on success, 0 if no layer with the given type is found
151  *
152  * in editmode, use EDBM_data_layer_free instead of this function
153  */
154 bool CustomData_free_layer(struct CustomData *data, int type, int totelem, int index);
155
156 /* frees the layer index with the give type.
157  * returns 1 on success, 0 if no layer with the given type is found
158  *
159  * in editmode, use EDBM_data_layer_free instead of this function
160  */
161 bool CustomData_free_layer_active(struct CustomData *data, int type, int totelem);
162
163 /* same as above, but free all layers with type */
164 void CustomData_free_layers(struct CustomData *data, int type, int totelem);
165
166 /* returns 1 if a layer with the specified type exists */
167 bool CustomData_has_layer(const struct CustomData *data, int type);
168
169 /* returns the number of layers with this type */
170 int CustomData_number_of_layers(const struct CustomData *data, int type);
171 int CustomData_number_of_layers_typemask(const struct CustomData *data, CustomDataMask mask);
172
173 /* duplicate data of a layer with flag NOFREE, and remove that flag.
174  * returns the layer data */
175 void *CustomData_duplicate_referenced_layer(struct CustomData *data, const int type, const int totelem);
176 void *CustomData_duplicate_referenced_layer_named(struct CustomData *data,
177                                                   const int type, const char *name, const int totelem);
178 bool CustomData_is_referenced_layer(struct CustomData *data, int type);
179
180 /* set the CD_FLAG_NOCOPY flag in custom data layers where the mask is
181  * zero for the layer type, so only layer types specified by the mask
182  * will be copied
183  */
184 void CustomData_set_only_copy(const struct CustomData *data,
185                               CustomDataMask mask);
186
187 /* copies data from one CustomData object to another
188  * objects need not be compatible, each source layer is copied to the
189  * first dest layer of correct type (if there is none, the layer is skipped)
190  * return 1 on success, 0 on failure
191  */
192 void CustomData_copy_data(const struct CustomData *source,
193                           struct CustomData *dest, int source_index,
194                           int dest_index, int count);
195 void CustomData_copy_data_named(const struct CustomData *source,
196                           struct CustomData *dest, int source_index,
197                           int dest_index, int count);
198 void CustomData_copy_elements(int type, void *source, void *dest, int count);
199 void CustomData_bmesh_copy_data(const struct CustomData *source, 
200                                 struct CustomData *dest, void *src_block, 
201                                 void **dest_block);
202
203 /* frees data in a CustomData object
204  * return 1 on success, 0 on failure
205  */
206 void CustomData_free_elem(struct CustomData *data, int index, int count);
207
208 /* interpolates data from one CustomData object to another
209  * objects need not be compatible, each source layer is interpolated to the
210  * first dest layer of correct type (if there is none, the layer is skipped)
211  * if weights == NULL or sub_weights == NULL, they default to all 1's
212  *
213  * src_indices gives the source elements to interpolate from
214  * weights gives the weight for each source element
215  * sub_weights is an array of matrices of weights for sub-elements (matrices
216  *     should be source->subElems * source->subElems in size)
217  * count gives the number of source elements to interpolate from
218  * dest_index gives the dest element to write the interpolated value to
219  */
220 void CustomData_interp(const struct CustomData *source, struct CustomData *dest,
221                        int *src_indices, float *weights, float *sub_weights,
222                        int count, int dest_index);
223 void CustomData_bmesh_interp_n(struct CustomData *data, void **src_blocks, const float *weights,
224                                const float *sub_weights, int count, void *dest_block, int n);
225 void CustomData_bmesh_interp(struct CustomData *data, void **src_blocks,
226                              const float *weights, const float *sub_weights, int count,
227                              void *dest_block);
228
229
230 /* swaps the data in the element corners, to new corners with indices as
231  * specified in corner_indices. for edges this is an array of length 2, for
232  * faces an array of length 4 */
233 void CustomData_swap(struct CustomData *data, int index, const int *corner_indices);
234
235 /* gets a pointer to the data element at index from the first layer of type
236  * returns NULL if there is no layer of type
237  */
238 void *CustomData_get(const struct CustomData *data, int index, int type);
239 void *CustomData_get_n(const struct CustomData *data, int type, int index, int n);
240 void *CustomData_bmesh_get(const struct CustomData *data, void *block, int type);
241 void *CustomData_bmesh_get_n(const struct CustomData *data, void *block, int type, int n);
242
243 /* gets the layer at physical index n, with no type checking.
244  */
245 void *CustomData_bmesh_get_layer_n(const struct CustomData *data, void *block, int n);
246
247 bool CustomData_set_layer_name(const struct CustomData *data, int type, int n, const char *name);
248
249 /* gets a pointer to the active or first layer of type
250  * returns NULL if there is no layer of type
251  */
252 void *CustomData_get_layer(const struct CustomData *data, int type);
253 void *CustomData_get_layer_n(const struct CustomData *data, int type, int n);
254 void *CustomData_get_layer_named(const struct CustomData *data, int type,
255                                  const char *name);
256 int CustomData_get_offset(const struct CustomData *data, int type);
257 int CustomData_get_n_offset(const struct CustomData *data, int type, int n);
258
259 int CustomData_get_layer_index(const struct CustomData *data, int type);
260 int CustomData_get_layer_index_n(const struct CustomData *data, int type, int n);
261 int CustomData_get_named_layer_index(const struct CustomData *data, int type, const char *name);
262 int CustomData_get_active_layer_index(const struct CustomData *data, int type);
263 int CustomData_get_render_layer_index(const struct CustomData *data, int type);
264 int CustomData_get_clone_layer_index(const struct CustomData *data, int type);
265 int CustomData_get_stencil_layer_index(const struct CustomData *data, int type);
266 int CustomData_get_named_layer(const struct CustomData *data, int type, const char *name);
267 int CustomData_get_active_layer(const struct CustomData *data, int type);
268 int CustomData_get_render_layer(const struct CustomData *data, int type);
269 int CustomData_get_clone_layer(const struct CustomData *data, int type);
270 int CustomData_get_stencil_layer(const struct CustomData *data, int type);
271
272 /* copies the data from source to the data element at index in the first
273  * layer of type
274  * no effect if there is no layer of type
275  */
276 void CustomData_set(const struct CustomData *data, int index, int type,
277                     void *source);
278
279 void CustomData_bmesh_set(const struct CustomData *data, void *block, int type, 
280                           void *source);
281
282 void CustomData_bmesh_set_n(struct CustomData *data, void *block, int type, int n, 
283                             void *source);
284 /* sets the data of the block at physical layer n.  no real type checking
285  * is performed.
286  */
287 void CustomData_bmesh_set_layer_n(struct CustomData *data, void *block, int n,
288                                   void *source);
289
290 /* set the pointer of to the first layer of type. the old data is not freed.
291  * returns the value of ptr if the layer is found, NULL otherwise
292  */
293 void *CustomData_set_layer(const struct CustomData *data, int type, void *ptr);
294 void *CustomData_set_layer_n(const struct CustomData *data, int type, int n, void *ptr);
295
296 /* sets the nth layer of type as active */
297 void CustomData_set_layer_active(struct CustomData *data, int type, int n);
298 void CustomData_set_layer_render(struct CustomData *data, int type, int n);
299 void CustomData_set_layer_clone(struct CustomData *data, int type, int n);
300 void CustomData_set_layer_stencil(struct CustomData *data, int type, int n);
301
302 /* same as above but works with an index from CustomData_get_layer_index */
303 void CustomData_set_layer_active_index(struct CustomData *data, int type, int n);
304 void CustomData_set_layer_render_index(struct CustomData *data, int type, int n);
305 void CustomData_set_layer_clone_index(struct CustomData *data, int type, int n);
306 void CustomData_set_layer_stencil_index(struct CustomData *data, int type, int n);
307
308 /* adds flag to the layer flags */
309 void CustomData_set_layer_flag(struct CustomData *data, int type, int flag);
310
311 void CustomData_bmesh_set_default(struct CustomData *data, void **block);
312 void CustomData_bmesh_free_block(struct CustomData *data, void **block);
313 void CustomData_bmesh_free_block_data(struct CustomData *data, void **block);
314
315 /* copy custom data to/from layers as in mesh/derivedmesh, to editmesh
316  * blocks of data. the CustomData's must not be compatible */
317 void CustomData_to_bmesh_block(const struct CustomData *source, 
318                                struct CustomData *dest, int src_index, void **dest_block, bool use_default_init);
319 void CustomData_from_bmesh_block(const struct CustomData *source, 
320                                  struct CustomData *dest, void *src_block, int dest_index);
321
322
323 /* query info over types */
324 void CustomData_file_write_info(int type, const char **structname, int *structnum);
325 int CustomData_sizeof(int type);
326
327 /* get the name of a layer type */
328 const char *CustomData_layertype_name(int type);
329 bool        CustomData_layertype_is_singleton(int type);
330
331 /* make sure the name of layer at index is unique */
332 void CustomData_set_layer_unique_name(struct CustomData *data, int index);
333
334 void CustomData_validate_layer_name(const struct CustomData *data, int type, const char *name, char *outname);
335
336 /* for file reading compatibility, returns false if the layer was freed,
337  * only after this test passes, layer->data should be assigned */
338 bool CustomData_verify_versions(struct CustomData *data, int index);
339
340 /*BMesh specific customdata stuff*/
341 void CustomData_to_bmeshpoly(struct CustomData *fdata, struct CustomData *pdata,
342                              struct CustomData *ldata, int totloop, int totpoly);
343 void CustomData_from_bmeshpoly(struct CustomData *fdata, struct CustomData *pdata, struct CustomData *ldata, int total);
344 void CustomData_bmesh_update_active_layers(struct CustomData *fdata, struct CustomData *pdata, struct CustomData *ldata);
345 void CustomData_bmesh_do_versions_update_active_layers(struct CustomData *fdata, struct CustomData *pdata, struct CustomData *ldata);
346 void CustomData_bmesh_init_pool(struct CustomData *data, int totelem, const char htype);
347
348 /* External file storage */
349
350 void CustomData_external_add(struct CustomData *data,
351                              struct ID *id, int type, int totelem, const char *filename);
352 void CustomData_external_remove(struct CustomData *data,
353                                 struct ID *id, int type, int totelem);
354 bool CustomData_external_test(struct CustomData *data, int type);
355
356 void CustomData_external_write(struct CustomData *data,
357                                struct ID *id, CustomDataMask mask, int totelem, int free);
358 void CustomData_external_read(struct CustomData *data,
359                               struct ID *id, CustomDataMask mask, int totelem);
360 void CustomData_external_reload(struct CustomData *data,
361                                 struct ID *id, CustomDataMask mask, int totelem);
362
363 #ifdef __cplusplus
364 }
365 #endif
366
367 #endif
368