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