doxygen: add newline after \file
[blender.git] / source / blender / blenkernel / BKE_customdata.h
1 /*
2  * This program is free software; you can redistribute it and/or
3  * modify it under the terms of the GNU General Public License
4  * as published by the Free Software Foundation; either version 2
5  * of the License, or (at your option) any later version.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * along with this program; if not, write to the Free Software  Foundation,
14  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
15  *
16  * The Original Code is Copyright (C) 2006 Blender Foundation.
17  * All rights reserved.
18  */
19
20 /** \file
21  * \ingroup bke
22  * \brief CustomData interface, see also DNA_customdata_types.h.
23  */
24
25 #ifndef __BKE_CUSTOMDATA_H__
26 #define __BKE_CUSTOMDATA_H__
27
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31
32 #include "BLI_sys_types.h"
33 #include "BLI_utildefines.h"
34
35 #include "DNA_customdata_types.h"
36
37 struct BMesh;
38 struct CustomData;
39 struct ID;
40 typedef uint64_t CustomDataMask;
41
42 /*a data type large enough to hold 1 element from any customdata layer type*/
43 typedef struct {unsigned char data[64]; } CDBlockBytes;
44
45 extern const CustomDataMask CD_MASK_BAREMESH;
46 extern const CustomDataMask CD_MASK_MESH;
47 extern const CustomDataMask CD_MASK_EDITMESH;
48 extern const CustomDataMask CD_MASK_DERIVEDMESH;
49 extern const CustomDataMask CD_MASK_BMESH;
50 extern const CustomDataMask CD_MASK_FACECORNERS;
51 extern const CustomDataMask CD_MASK_EVERYTHING;
52
53 /* for ORIGINDEX layer type, indicates no original index for this element */
54 #define ORIGINDEX_NONE -1
55
56 /* initializes 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 typedef enum eCDAllocType {
62         CD_ASSIGN    = 0,  /* use the data pointer */
63         CD_CALLOC    = 1,  /* allocate blank memory */
64         CD_DEFAULT   = 2,  /* allocate and set to default */
65         CD_REFERENCE = 3,  /* use data pointers, set layer flag NOFREE */
66         CD_DUPLICATE = 4,  /* do a full copy of all layers, only allowed if source
67                             * has same number of elements */
68 } eCDAllocType;
69
70 #define CD_TYPE_AS_MASK(_type) (CustomDataMask)((CustomDataMask)1 << (CustomDataMask)(_type))
71
72 void customData_mask_layers__print(CustomDataMask mask);
73
74 typedef void (*cd_interp)(const void **sources, const float *weights, const float *sub_weights, int count, void *dest);
75 typedef void (*cd_copy)(const void *source, void *dest, int count);
76 typedef bool (*cd_validate)(void *item, const uint totitems, const bool do_fixes);
77
78 /**
79  * Checks if the layer at physical offset \a layer_n (in data->layers) support math
80  * the below operations.
81  */
82 bool CustomData_layer_has_math(const struct CustomData *data, int layer_n);
83 bool CustomData_layer_has_interp(const struct CustomData *data, int layer_n);
84
85 /**
86  * Checks if any of the customdata layers has math.
87  */
88 bool CustomData_has_math(const struct CustomData *data);
89 bool CustomData_has_interp(const struct CustomData *data);
90 bool CustomData_bmesh_has_free(const struct CustomData *data);
91
92 /**
93  * Checks if any of the customdata layers is referenced.
94  */
95 bool CustomData_has_referenced(const struct CustomData *data);
96
97 /* copies the "value" (e.g. mloopuv uv or mloopcol colors) from one block to
98  * another, while not overwriting anything else (e.g. flags).  probably only
99  * implemented for mloopuv/mloopcol, for now.*/
100 void CustomData_data_copy_value(int type, const void *source, void *dest);
101
102 /* Same as above, but doing advanced mixing. Only available for a few types of data (like colors...). */
103 void CustomData_data_mix_value(int type, const void *source, void *dest, const int mixmode, const float mixfactor);
104
105 /* compares if data1 is equal to data2.  type is a valid CustomData type
106  * enum (e.g. CD_MLOOPUV). the layer type's equal function is used to compare
107  * the data, if it exists, otherwise memcmp is used.*/
108 bool CustomData_data_equals(int type, const void *data1, const void *data2);
109 void CustomData_data_initminmax(int type, void *min, void *max);
110 void CustomData_data_dominmax(int type, const void *data, void *min, void *max);
111 void CustomData_data_multiply(int type, void *data, float fac);
112 void CustomData_data_add(int type, void *data1, const void *data2);
113
114 /* initializes a CustomData object with the same layer setup as source.
115  * mask is a bitfield where (mask & (1 << (layer type))) indicates
116  * if a layer should be copied or not. alloctype must be one of the above. */
117 void CustomData_copy(
118         const struct CustomData *source, struct CustomData *dest,
119         CustomDataMask mask, eCDAllocType alloctype, int totelem);
120
121 /* BMESH_TODO, not really a public function but readfile.c needs it */
122 void CustomData_update_typemap(struct CustomData *data);
123
124 /* same as the above, except that this will preserve existing layers, and only
125  * add the layers that were not there yet */
126 bool CustomData_merge(
127         const struct CustomData *source, struct CustomData *dest,
128         CustomDataMask mask, eCDAllocType alloctype, int totelem);
129
130 /* Reallocate custom data to a new element count.
131  * Only affects on data layers which are owned by the CustomData itself,
132  * referenced data is kept unchanged,
133  *
134  * NOTE: Take care of referenced layers by yourself!
135  */
136 void CustomData_realloc(struct CustomData *data, int totelem);
137
138 /* bmesh version of CustomData_merge; merges the layouts of source and dest,
139  * then goes through the mesh and makes sure all the customdata blocks are
140  * consistent with the new layout.*/
141 bool CustomData_bmesh_merge(
142         const struct CustomData *source, struct CustomData *dest,
143         CustomDataMask mask, eCDAllocType alloctype, struct BMesh *bm, const char htype);
144
145 /** NULL's all members and resets the typemap. */
146 void CustomData_reset(struct CustomData *data);
147
148 /** frees data associated with a CustomData object (doesn't free the object
149  * itself, though)
150  */
151 void CustomData_free(struct CustomData *data, int totelem);
152
153 /* same as above, but only frees layers which matches the given mask. */
154 void CustomData_free_typemask(struct CustomData *data, int totelem, CustomDataMask mask);
155
156 /* frees all layers with CD_FLAG_TEMPORARY */
157 void CustomData_free_temporary(struct CustomData *data, int totelem);
158
159 /* adds a data layer of the given type to the CustomData object, optionally
160  * backed by an external data array. the different allocation types are
161  * defined above. returns the data of the layer.
162  */
163 void *CustomData_add_layer(
164         struct CustomData *data, int type, eCDAllocType alloctype,
165         void *layer, int totelem);
166 /*same as above but accepts a name */
167 void *CustomData_add_layer_named(
168         struct CustomData *data, int type, eCDAllocType alloctype,
169         void *layer, int totelem, const char *name);
170
171 /* frees the active or first data layer with the give type.
172  * returns 1 on success, 0 if no layer with the given type is found
173  *
174  * in editmode, use EDBM_data_layer_free instead of this function
175  */
176 bool CustomData_free_layer(struct CustomData *data, int type, int totelem, int index);
177
178 /* frees the layer index with the give type.
179  * returns 1 on success, 0 if no layer with the given type is found
180  *
181  * in editmode, use EDBM_data_layer_free instead of this function
182  */
183 bool CustomData_free_layer_active(struct CustomData *data, int type, int totelem);
184
185 /* same as above, but free all layers with type */
186 void CustomData_free_layers(struct CustomData *data, int type, int totelem);
187
188 /* returns 1 if a layer with the specified type exists */
189 bool CustomData_has_layer(const struct CustomData *data, int type);
190
191 /* returns the number of layers with this type */
192 int CustomData_number_of_layers(const struct CustomData *data, int type);
193 int CustomData_number_of_layers_typemask(const struct CustomData *data, CustomDataMask mask);
194
195 /* duplicate data of a layer with flag NOFREE, and remove that flag.
196  * returns the layer data */
197 void *CustomData_duplicate_referenced_layer(struct CustomData *data, const int type, const int totelem);
198 void *CustomData_duplicate_referenced_layer_n(struct CustomData *data, const int type, const int n, const int totelem);
199 void *CustomData_duplicate_referenced_layer_named(struct CustomData *data,
200                                                   const int type, const char *name, const int totelem);
201 bool CustomData_is_referenced_layer(struct CustomData *data, int type);
202
203 /* set the CD_FLAG_NOCOPY flag in custom data layers where the mask is
204  * zero for the layer type, so only layer types specified by the mask
205  * will be copied
206  */
207 void CustomData_set_only_copy(const struct CustomData *data,
208                               CustomDataMask mask);
209
210 /* copies data from one CustomData object to another
211  * objects need not be compatible, each source layer is copied to the
212  * first dest layer of correct type (if there is none, the layer is skipped)
213  * return 1 on success, 0 on failure
214  */
215 void CustomData_copy_data(const struct CustomData *source,
216                           struct CustomData *dest, int source_index,
217                           int dest_index, int count);
218 void CustomData_copy_data_named(const struct CustomData *source,
219                                 struct CustomData *dest, int source_index,
220                                 int dest_index, int count);
221 void CustomData_copy_elements(int type, void *src_data_ofs, void *dst_data_ofs, int count);
222 void CustomData_bmesh_copy_data(const struct CustomData *source,
223                                 struct CustomData *dest, void *src_block,
224                                 void **dest_block);
225
226 /* Copies data of a single layer of a given type. */
227 void CustomData_copy_layer_type_data(const struct CustomData *source,
228                                      struct CustomData *destination,
229                                      int type,
230                                      int source_index, int destination_index,
231                                      int count);
232
233 /* frees data in a CustomData object
234  * return 1 on success, 0 on failure
235  */
236 void CustomData_free_elem(struct CustomData *data, int index, int count);
237
238 /* interpolates data from one CustomData object to another
239  * objects need not be compatible, each source layer is interpolated to the
240  * first dest layer of correct type (if there is none, the layer is skipped)
241  * if weights == NULL or sub_weights == NULL, they default to all 1's
242  *
243  * src_indices gives the source elements to interpolate from
244  * weights gives the weight for each source element
245  * sub_weights is an array of matrices of weights for sub-elements (matrices
246  *     should be source->subElems * source->subElems in size)
247  * count gives the number of source elements to interpolate from
248  * dest_index gives the dest element to write the interpolated value to
249  */
250 void CustomData_interp(
251         const struct CustomData *source, struct CustomData *dest,
252         const int *src_indices, const float *weights, const float *sub_weights,
253         int count, int dest_index);
254 void CustomData_bmesh_interp_n(
255         struct CustomData *data, const void **src_blocks, const float *weights,
256         const float *sub_weights, int count, void *dst_block_ofs, int n);
257 void CustomData_bmesh_interp(
258         struct CustomData *data, const void **src_blocks,
259         const float *weights, const float *sub_weights, int count,
260         void *dst_block);
261
262
263 /* swaps the data in the element corners, to new corners with indices as
264  * specified in corner_indices. for edges this is an array of length 2, for
265  * faces an array of length 4 */
266 void CustomData_swap_corners(struct CustomData *data, int index, const int *corner_indices);
267
268 void CustomData_swap(struct CustomData *data, const int index_a, const int index_b);
269
270 /* gets a pointer to the data element at index from the first layer of type
271  * returns NULL if there is no layer of type
272  */
273 void *CustomData_get(const struct CustomData *data, int index, int type);
274 void *CustomData_get_n(const struct CustomData *data, int type, int index, int n);
275 void *CustomData_bmesh_get(const struct CustomData *data, void *block, int type);
276 void *CustomData_bmesh_get_n(const struct CustomData *data, void *block, int type, int n);
277
278 /* gets the layer at physical index n, with no type checking.
279  */
280 void *CustomData_bmesh_get_layer_n(const struct CustomData *data, void *block, int n);
281
282 bool CustomData_set_layer_name(const struct CustomData *data, int type, int n, const char *name);
283 const char *CustomData_get_layer_name(const struct CustomData *data, int type, int n);
284
285 /* gets a pointer to the active or first layer of type
286  * returns NULL if there is no layer of type
287  */
288 void *CustomData_get_layer(const struct CustomData *data, int type);
289 void *CustomData_get_layer_n(const struct CustomData *data, int type, int n);
290 void *CustomData_get_layer_named(const struct CustomData *data, int type, const char *name);
291 int CustomData_get_offset(const struct CustomData *data, int type);
292 int CustomData_get_n_offset(const struct CustomData *data, int type, int n);
293
294 int CustomData_get_layer_index(const struct CustomData *data, int type);
295 int CustomData_get_layer_index_n(const struct CustomData *data, int type, int n);
296 int CustomData_get_named_layer_index(const struct CustomData *data, int type, const char *name);
297 int CustomData_get_active_layer_index(const struct CustomData *data, int type);
298 int CustomData_get_render_layer_index(const struct CustomData *data, int type);
299 int CustomData_get_clone_layer_index(const struct CustomData *data, int type);
300 int CustomData_get_stencil_layer_index(const struct CustomData *data, int type);
301 int CustomData_get_named_layer(const struct CustomData *data, int type, const char *name);
302 int CustomData_get_active_layer(const struct CustomData *data, int type);
303 int CustomData_get_render_layer(const struct CustomData *data, int type);
304 int CustomData_get_clone_layer(const struct CustomData *data, int type);
305 int CustomData_get_stencil_layer(const struct CustomData *data, int type);
306
307 /* copies the data from source to the data element at index in the first
308  * layer of type
309  * no effect if there is no layer of type
310  */
311 void CustomData_set(
312         const struct CustomData *data, int index, int type,
313         const void *source);
314
315 void CustomData_bmesh_set(
316         const struct CustomData *data, void *block, int type,
317         const void *source);
318
319 void CustomData_bmesh_set_n(
320         struct CustomData *data, void *block, int type, int n,
321         const void *source);
322 /* sets the data of the block at physical layer n.  no real type checking
323  * is performed.
324  */
325 void CustomData_bmesh_set_layer_n(
326         struct CustomData *data, void *block, int n,
327         const void *source);
328
329 /* set the pointer of to the first layer of type. the old data is not freed.
330  * returns the value of ptr if the layer is found, NULL otherwise
331  */
332 void *CustomData_set_layer(const struct CustomData *data, int type, void *ptr);
333 void *CustomData_set_layer_n(const struct CustomData *data, int type, int n, void *ptr);
334
335 /* sets the nth layer of type as active */
336 void CustomData_set_layer_active(struct CustomData *data, int type, int n);
337 void CustomData_set_layer_render(struct CustomData *data, int type, int n);
338 void CustomData_set_layer_clone(struct CustomData *data, int type, int n);
339 void CustomData_set_layer_stencil(struct CustomData *data, int type, int n);
340
341 /* same as above but works with an index from CustomData_get_layer_index */
342 void CustomData_set_layer_active_index(struct CustomData *data, int type, int n);
343 void CustomData_set_layer_render_index(struct CustomData *data, int type, int n);
344 void CustomData_set_layer_clone_index(struct CustomData *data, int type, int n);
345 void CustomData_set_layer_stencil_index(struct CustomData *data, int type, int n);
346
347 /* adds flag to the layer flags */
348 void CustomData_set_layer_flag(struct CustomData *data, int type, int flag);
349
350 void CustomData_bmesh_set_default(struct CustomData *data, void **block);
351 void CustomData_bmesh_free_block(struct CustomData *data, void **block);
352 void CustomData_bmesh_free_block_data(struct CustomData *data, void *block);
353
354 /* copy custom data to/from layers as in mesh/derivedmesh, to editmesh
355  * blocks of data. the CustomData's must not be compatible */
356 void CustomData_to_bmesh_block(const struct CustomData *source,
357                                struct CustomData *dest, int src_index, void **dest_block, bool use_default_init);
358 void CustomData_from_bmesh_block(const struct CustomData *source,
359                                  struct CustomData *dest, void *src_block, int dest_index);
360
361 void CustomData_file_write_prepare(
362         struct CustomData *data,
363         struct CustomDataLayer **r_write_layers, struct CustomDataLayer *write_layers_buff, size_t write_layers_size);
364
365 /* query info over types */
366 void CustomData_file_write_info(int type, const char **r_struct_name, int *r_struct_num);
367 int CustomData_sizeof(int type);
368
369 /* get the name of a layer type */
370 const char *CustomData_layertype_name(int type);
371 bool        CustomData_layertype_is_singleton(int type);
372 int         CustomData_layertype_layers_max(const int type);
373
374 /* make sure the name of layer at index is unique */
375 void CustomData_set_layer_unique_name(struct CustomData *data, int index);
376
377 void CustomData_validate_layer_name(const struct CustomData *data, int type, const char *name, char *outname);
378
379 /* for file reading compatibility, returns false if the layer was freed,
380  * only after this test passes, layer->data should be assigned */
381 bool CustomData_verify_versions(struct CustomData *data, int index);
382
383 /*BMesh specific customdata stuff*/
384 void CustomData_to_bmeshpoly(struct CustomData *fdata, struct CustomData *ldata, int totloop);
385 void CustomData_from_bmeshpoly(struct CustomData *fdata, struct CustomData *ldata, int total);
386 void CustomData_bmesh_update_active_layers(struct CustomData *fdata, struct CustomData *ldata);
387 void CustomData_bmesh_do_versions_update_active_layers(struct CustomData *fdata, struct CustomData *ldata);
388 void CustomData_bmesh_init_pool(struct CustomData *data, int totelem, const char htype);
389
390 #ifndef NDEBUG
391 bool CustomData_from_bmeshpoly_test(CustomData *fdata, CustomData *ldata, bool fallback);
392 #endif
393
394 /* Layer data validation. */
395 bool CustomData_layer_validate(struct CustomDataLayer *layer, const uint totitems, const bool do_fixes);
396
397 /* External file storage */
398
399 void CustomData_external_add(struct CustomData *data,
400                              struct ID *id, int type, int totelem, const char *filename);
401 void CustomData_external_remove(struct CustomData *data,
402                                 struct ID *id, int type, int totelem);
403 bool CustomData_external_test(struct CustomData *data, int type);
404
405 void CustomData_external_write(struct CustomData *data,
406                                struct ID *id, CustomDataMask mask, int totelem, int free);
407 void CustomData_external_read(struct CustomData *data,
408                               struct ID *id, CustomDataMask mask, int totelem);
409 void CustomData_external_reload(struct CustomData *data,
410                                 struct ID *id, CustomDataMask mask, int totelem);
411
412 /* Mesh-to-mesh transfer data. */
413
414 struct CustomDataTransferLayerMap;
415 struct MeshPairRemap;
416
417 typedef void (*cd_datatransfer_interp)(
418         const struct CustomDataTransferLayerMap *laymap, void *dest,
419         const void **sources, const float *weights, const int count, const float mix_factor);
420
421 /**
422  * Fake CD_LAYERS (those are actually 'real' data stored directly into elements' structs, or otherwise not (directly)
423  * accessible to usual CDLayer system). */
424 enum {
425         CD_FAKE             = 1 << 8,
426
427         /* Vertices. */
428         CD_FAKE_MDEFORMVERT = CD_FAKE | CD_MDEFORMVERT,  /* *sigh* due to how vgroups are stored :( . */
429         CD_FAKE_SHAPEKEY    = CD_FAKE | CD_SHAPEKEY,  /* Not available as real CD layer in non-bmesh context. */
430
431         /* Edges. */
432         CD_FAKE_SEAM        = CD_FAKE | 100,  /* UV seam flag for edges. */
433         CD_FAKE_CREASE      = CD_FAKE | CD_CREASE,  /* *sigh*. */
434
435         /* Multiple types of mesh elements... */
436         CD_FAKE_BWEIGHT     = CD_FAKE | CD_BWEIGHT,  /* *sigh*. */
437         CD_FAKE_UV          = CD_FAKE | CD_MLOOPUV,  /* UV flag, because we handle both loop's UVs and poly's textures. */
438
439         CD_FAKE_LNOR        = CD_FAKE | CD_CUSTOMLOOPNORMAL,  /* Because we play with clnor and temp lnor layers here. */
440
441         CD_FAKE_SHARP       = CD_FAKE | 200,  /* Sharp flag for edges, smooth flag for faces. */
442 };
443
444 enum {
445         ME_VERT = 1 << 0,
446         ME_EDGE = 1 << 1,
447         ME_POLY = 1 << 2,
448         ME_LOOP = 1 << 3,
449 };
450
451 /**
452  * How to filter out some elements (to leave untouched).
453  * Note those options are highly dependent on type of transferred data! */
454 enum {
455         CDT_MIX_NOMIX                   = -1,  /* Special case, only used because we abuse 'copy' CD callback. */
456         CDT_MIX_TRANSFER                = 0,
457         CDT_MIX_REPLACE_ABOVE_THRESHOLD = 1,
458         CDT_MIX_REPLACE_BELOW_THRESHOLD = 2,
459         CDT_MIX_MIX                     = 16,
460         CDT_MIX_ADD                     = 17,
461         CDT_MIX_SUB                     = 18,
462         CDT_MIX_MUL                     = 19,
463         /* etc. etc. */
464 };
465
466 typedef struct CustomDataTransferLayerMap {
467         struct CustomDataTransferLayerMap *next, *prev;
468
469         int data_type;
470         int mix_mode;
471         float mix_factor;
472         const float *mix_weights;  /* If non-NULL, array of weights, one for each dest item, replaces mix_factor. */
473
474         const void *data_src;  /* Data source array (can be regular CD data, vertices/edges/etc., keyblocks...). */
475         void *data_dst;      /* Data dest array (same type as dat_src). */
476         int   data_src_n;    /* Index to affect in data_src (used e.g. for vgroups). */
477         int   data_dst_n;    /* Index to affect in data_dst (used e.g. for vgroups). */
478         size_t elem_size;    /* Size of one element of data_src/data_dst. */
479
480         size_t data_size;    /* Size of actual data we transfer. */
481         size_t data_offset;  /* Offset of actual data we transfer (in element contained in data_src/dst). */
482         uint64_t data_flag;  /* For bitflag transfer, flag(s) to affect in transferred data. */
483
484         void *interp_data;   /* Opaque pointer, to be used by specific interp callback (e.g. transformspace for normals). */
485
486         cd_datatransfer_interp interp;
487 } CustomDataTransferLayerMap;
488
489 /* Those functions assume src_n and dst_n layers of given type exist in resp. src and dst. */
490 void CustomData_data_transfer(const struct MeshPairRemap *me_remap, const CustomDataTransferLayerMap *laymap);
491
492 #ifdef __cplusplus
493 }
494 #endif
495
496 #endif