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