Merge branch 'master' into blender2.8
[blender.git] / source / blender / blenkernel / BKE_modifier.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: all of this file.
19  *
20  * Contributor(s): none yet.
21  *
22  * ***** END GPL LICENSE BLOCK *****
23  */
24 #ifndef __BKE_MODIFIER_H__
25 #define __BKE_MODIFIER_H__
26
27 /** \file BKE_modifier.h
28  *  \ingroup bke
29  */
30
31 #include "DNA_modifier_types.h"     /* needed for all enum typdefs */
32 #include "BLI_compiler_attrs.h"
33 #include "BKE_customdata.h"
34
35 struct ID;
36 struct Depsgraph;
37 struct DerivedMesh;
38 struct Mesh;
39 struct Object;
40 struct Scene;
41 struct ViewLayer;
42 struct ListBase;
43 struct bArmature;
44 struct Main;
45 struct ModifierData;
46 struct BMEditMesh;
47 struct DepsNodeHandle;
48
49 typedef enum {
50         /* Should not be used, only for None modifier type */
51         eModifierTypeType_None,
52
53         /* Modifier only does deformation, implies that modifier
54          * type should have a valid deformVerts function. OnlyDeform
55          * style modifiers implicitly accept either mesh or CV
56          * input but should still declare flags appropriately.
57          */
58         eModifierTypeType_OnlyDeform,
59
60         eModifierTypeType_Constructive,
61         eModifierTypeType_Nonconstructive,
62
63         /* both deformVerts & applyModifier are valid calls
64          * used for particles modifier that doesn't actually modify the object
65          * unless it's a mesh and can be exploded -> curve can also emit particles
66          */
67         eModifierTypeType_DeformOrConstruct,
68
69         /* Like eModifierTypeType_Nonconstructive, but does not affect the geometry
70          * of the object, rather some of its CustomData layers.
71          * E.g. UVProject and WeightVG modifiers. */
72         eModifierTypeType_NonGeometrical,
73 } ModifierTypeType;
74
75 typedef enum {
76         eModifierTypeFlag_AcceptsMesh          = (1 << 0),
77         eModifierTypeFlag_AcceptsCVs           = (1 << 1),
78         eModifierTypeFlag_SupportsMapping      = (1 << 2),
79         eModifierTypeFlag_SupportsEditmode     = (1 << 3),
80
81         /* For modifiers that support editmode this determines if the
82          * modifier should be enabled by default in editmode. This should
83          * only be used by modifiers that are relatively speedy and
84          * also generally used in editmode, otherwise let the user enable
85          * it by hand.
86          */
87         eModifierTypeFlag_EnableInEditmode     = (1 << 4),
88
89         /* For modifiers that require original data and so cannot
90          * be placed after any non-deformative modifier.
91          */
92         eModifierTypeFlag_RequiresOriginalData = (1 << 5),
93
94         /* For modifiers that support pointcache, so we can check to see if it has files we need to deal with
95          */
96         eModifierTypeFlag_UsesPointCache = (1 << 6),
97
98         /* For physics modifiers, max one per type */
99         eModifierTypeFlag_Single = (1 << 7),
100
101         /* Some modifier can't be added manually by user */
102         eModifierTypeFlag_NoUserAdd = (1 << 8),
103
104         /* For modifiers that use CD_PREVIEW_MCOL for preview. */
105         eModifierTypeFlag_UsesPreview = (1 << 9),
106         eModifierTypeFlag_AcceptsLattice = (1 << 10),
107 } ModifierTypeFlag;
108
109 /* IMPORTANT! Keep ObjectWalkFunc and IDWalkFunc signatures compatible. */
110 typedef void (*ObjectWalkFunc)(void *userData, struct Object *ob, struct Object **obpoin, int cb_flag);
111 typedef void (*IDWalkFunc)(void *userData, struct Object *ob, struct ID **idpoin, int cb_flag);
112 typedef void (*TexWalkFunc)(void *userData, struct Object *ob, struct ModifierData *md, const char *propname);
113
114 typedef enum ModifierApplyFlag {
115         MOD_APPLY_RENDER = 1 << 0,       /* Render time. */
116         MOD_APPLY_USECACHE = 1 << 1,     /* Result of evaluation will be cached, so modifier might
117                                           * want to cache data for quick updates (used by subsurf) */
118         MOD_APPLY_ORCO = 1 << 2,         /* Modifier evaluated for undeformed texture coordinates */
119         MOD_APPLY_IGNORE_SIMPLIFY = 1 << 3, /* Ignore scene simplification flag and use subdivisions
120                                              * level set in multires modifier.
121                                              */
122         MOD_APPLY_ALLOW_GPU = 1 << 4,  /* Allow modifier to be applied and stored in the GPU.
123                                         * Used by the viewport in order to be able to have SS
124                                         * happening on GPU.
125                                         * Render pipeline (including viewport render) should
126                                         * have DM on the CPU.
127                                         */
128 } ModifierApplyFlag;
129
130 typedef struct ModifierUpdateDepsgraphContext {
131         struct Scene *scene;
132         struct Object *object;
133         struct DepsNodeHandle *node;
134 } ModifierUpdateDepsgraphContext;
135
136 /* Contains the information for deformXXX and applyXXX functions below that
137  * doesn't change between consecutive modifiers. */
138 typedef struct ModifierEvalContext {
139         struct Depsgraph *depsgraph;
140         struct Object *object;
141         ModifierApplyFlag flag;
142 } ModifierEvalContext;
143
144
145 typedef struct ModifierTypeInfo {
146         /* The user visible name for this modifier */
147         char name[32];
148
149         /* The DNA struct name for the modifier data type, used to
150          * write the DNA data out.
151          */
152         char structName[32];
153
154         /* The size of the modifier data type, used by allocation. */
155         int structSize;
156
157         ModifierTypeType type;
158         ModifierTypeFlag flags;
159
160
161         /********************* Non-optional functions *********************/
162
163         /* Copy instance data for this modifier type. Should copy all user
164          * level settings to the target modifier.
165          */
166         void (*copyData)(const struct ModifierData *md, struct ModifierData *target);
167
168
169         /********************* Deform modifier functions *********************/ /* DEPRECATED */
170
171         /* Only for deform types, should apply the deformation
172          * to the given vertex array. If the deformer requires information from
173          * the object it can obtain it from the derivedData argument if non-NULL,
174          * and otherwise the ob argument.
175          */
176         void (*deformVerts_DM)(struct ModifierData *md, const struct ModifierEvalContext *ctx,
177                                struct DerivedMesh *derivedData,
178                                float (*vertexCos)[3], int numVerts);
179
180         /* Like deformMatricesEM but called from object mode (for supporting modifiers in sculpt mode) */
181         void (*deformMatrices_DM)(struct ModifierData *md, const struct ModifierEvalContext *ctx,
182                                   struct DerivedMesh *derivedData,
183                                   float (*vertexCos)[3], float (*defMats)[3][3], int numVerts);
184
185         /* Like deformVerts but called during editmode (for supporting modifiers)
186          */
187         void (*deformVertsEM_DM)(struct ModifierData *md, const struct ModifierEvalContext *ctx,
188                                  struct BMEditMesh *editData,
189                                  struct DerivedMesh *derivedData,
190                                  float (*vertexCos)[3], int numVerts);
191
192         /* Set deform matrix per vertex for crazyspace correction */
193         void (*deformMatricesEM_DM)(struct ModifierData *md, const struct ModifierEvalContext *ctx,
194                                  struct BMEditMesh *editData,
195                                  struct DerivedMesh *derivedData,
196                                  float (*vertexCos)[3], float (*defMats)[3][3], int numVerts);
197
198         /********************* Non-deform modifier functions *********************/ /* DEPRECATED */
199
200         /* For non-deform types: apply the modifier and return a derived
201          * data object (type is dependent on object type).
202          *
203          * The derivedData argument should always be non-NULL; the modifier
204          * should read the object data from the derived object instead of the
205          * actual object data. 
206          *
207          * The modifier may reuse the derivedData argument (i.e. return it in
208          * modified form), but must not release it.
209          */
210         struct DerivedMesh *(*applyModifier_DM)(struct ModifierData *md, const struct ModifierEvalContext *ctx,
211                                                 struct DerivedMesh *derivedData);
212
213         /* Like applyModifier but called during editmode (for supporting
214          * modifiers).
215          * 
216          * The derived object that is returned must support the operations that
217          * are expected from editmode objects. The same qualifications regarding
218          * derivedData apply as for applyModifier.
219          */
220         struct DerivedMesh *(*applyModifierEM_DM)(struct ModifierData *md, const struct ModifierEvalContext *ctx,
221                                                   struct BMEditMesh *editData,
222                                                   struct DerivedMesh *derivedData);
223
224
225         /********************* Deform modifier functions *********************/
226
227         /* Only for deform types, should apply the deformation
228          * to the given vertex array. If the deformer requires information from
229          * the object it can obtain it from the mesh argument if non-NULL,
230          * and otherwise the ob argument.
231          */
232         void (*deformVerts)(struct ModifierData *md,  const struct ModifierEvalContext *ctx,
233                             struct Mesh *mesh, float (*vertexCos)[3], int numVerts);
234
235         /* Like deformMatricesEM but called from object mode (for supporting modifiers in sculpt mode) */
236         void (*deformMatrices)(struct ModifierData *md,  const struct ModifierEvalContext *ctx,
237                                struct Mesh *mesh, float (*vertexCos)[3], float (*defMats)[3][3], int numVerts);
238
239         /* Like deformVerts but called during editmode (for supporting modifiers)
240          */
241         void (*deformVertsEM)(struct ModifierData *md,  const struct ModifierEvalContext *ctx,
242                               struct BMEditMesh *editData,
243                               struct Mesh *mesh, float (*vertexCos)[3], int numVerts);
244
245         /* Set deform matrix per vertex for crazyspace correction */
246         void (*deformMatricesEM)(struct ModifierData *md,  const struct ModifierEvalContext *ctx,
247                                  struct BMEditMesh *editData,
248                                  struct Mesh *mesh, float (*vertexCos)[3], float (*defMats)[3][3], int numVerts);
249
250         /********************* Non-deform modifier functions *********************/
251
252         /* For non-deform types: apply the modifier and return a mesh object.
253          *
254          * The mesh argument should always be non-NULL; the modifier
255          * should read the object data from the mesh object instead of the
256          * actual object data. 
257          *
258          * The modifier may reuse the mesh argument (i.e. return it in
259          * modified form), but must not release it.
260          */
261         struct Mesh *(*applyModifier)(struct ModifierData *md, const struct ModifierEvalContext *ctx,
262                                       struct Mesh *mesh);
263
264         /* Like applyModifier but called during editmode (for supporting
265          * modifiers).
266          * 
267          * The mesh object that is returned must support the operations that
268          * are expected from editmode objects. The same qualifications regarding
269          * mesh apply as for applyModifier.
270          */
271         struct Mesh *(*applyModifierEM)(struct ModifierData *md, const struct ModifierEvalContext *ctx,
272                                         struct BMEditMesh *editData,
273                                         struct Mesh *mesh);
274
275
276         /********************* Optional functions *********************/
277
278         /* Initialize new instance data for this modifier type, this function
279          * should set modifier variables to their default values.
280          * 
281          * This function is optional.
282          */
283         void (*initData)(struct ModifierData *md);
284
285         /* Should return a CustomDataMask indicating what data this
286          * modifier needs. If (mask & (1 << (layer type))) != 0, this modifier
287          * needs that custom data layer. This function's return value can change
288          * depending on the modifier's settings.
289          *
290          * Note that this means extra data (e.g. vertex groups) - it is assumed
291          * that all modifiers need mesh data and deform modifiers need vertex
292          * coordinates.
293          *
294          * Note that this limits the number of custom data layer types to 32.
295          *
296          * If this function is not present or it returns 0, it is assumed that
297          * no extra data is needed.
298          *
299          * This function is optional.
300          */
301         CustomDataMask (*requiredDataMask)(struct Object *ob, struct ModifierData *md);
302
303         /* Free internal modifier data variables, this function should
304          * not free the md variable itself.
305          *
306          * This function is optional.
307          */
308         void (*freeData)(struct ModifierData *md);
309
310         /* Return a boolean value indicating if this modifier is able to be
311          * calculated based on the modifier data. This is *not* regarding the
312          * md->flag, that is tested by the system, this is just if the data
313          * validates (for example, a lattice will return false if the lattice
314          * object is not defined).
315          *
316          * This function is optional (assumes never disabled if not present).
317          */
318         bool (*isDisabled)(struct ModifierData *md, int userRenderParams);
319
320         /* Add the appropriate relations to the dependency graph.
321          *
322          * This function is optional.
323          */
324         void (*updateDepsgraph)(struct ModifierData *md,
325                                 const ModifierUpdateDepsgraphContext *ctx);
326  
327         /* Should return true if the modifier needs to be recalculated on time
328          * changes.
329          *
330          * This function is optional (assumes false if not present).
331          */
332         bool (*dependsOnTime)(struct ModifierData *md);
333
334
335         /* True when a deform modifier uses normals, the requiredDataMask
336          * cant be used here because that refers to a normal layer where as
337          * in this case we need to know if the deform modifier uses normals.
338          * 
339          * this is needed because applying 2 deform modifiers will give the
340          * second modifier bogus normals.
341          * */
342         bool (*dependsOnNormals)(struct ModifierData *md);
343
344
345         /* Should call the given walk function on with a pointer to each Object
346          * pointer that the modifier data stores. This is used for linking on file
347          * load and for unlinking objects or forwarding object references.
348          *
349          * This function is optional.
350          */
351         void (*foreachObjectLink)(struct ModifierData *md, struct Object *ob,
352                                   ObjectWalkFunc walk, void *userData);
353
354         /* Should call the given walk function with a pointer to each ID
355          * pointer (i.e. each datablock pointer) that the modifier data
356          * stores. This is used for linking on file load and for
357          * unlinking datablocks or forwarding datablock references.
358          *
359          * This function is optional. If it is not present, foreachObjectLink
360          * will be used.
361          */
362         void (*foreachIDLink)(struct ModifierData *md, struct Object *ob,
363                               IDWalkFunc walk, void *userData);
364
365         /* Should call the given walk function for each texture that the
366          * modifier data stores. This is used for finding all textures in
367          * the context for the UI.
368          *
369          * This function is optional. If it is not present, it will be
370          * assumed the modifier has no textures.
371          */
372         void (*foreachTexLink)(struct ModifierData *md, struct Object *ob,
373                                TexWalkFunc walk, void *userData);
374 } ModifierTypeInfo;
375
376 /* Initialize modifier's global data (type info and some common global storages). */
377 void BKE_modifier_init(void);
378
379 const ModifierTypeInfo *modifierType_getInfo(ModifierType type);
380
381 /* Modifier utility calls, do call through type pointer and return
382  * default values if pointer is optional.
383  */
384 struct ModifierData  *modifier_new(int type);
385 void          modifier_free_ex(struct ModifierData *md, const int flag);
386 void          modifier_free(struct ModifierData *md);
387
388 bool          modifier_unique_name(struct ListBase *modifiers, struct ModifierData *md);
389
390 void          modifier_copyData_generic(const struct ModifierData *md, struct ModifierData *target);
391 void          modifier_copyData(struct ModifierData *md, struct ModifierData *target);
392 void          modifier_copyData_ex(struct ModifierData *md, struct ModifierData *target, const int flag);
393 bool          modifier_dependsOnTime(struct ModifierData *md);
394 bool          modifier_supportsMapping(struct ModifierData *md);
395 bool          modifier_supportsCage(struct Scene *scene, struct ModifierData *md);
396 bool          modifier_couldBeCage(struct Scene *scene, struct ModifierData *md);
397 bool          modifier_isCorrectableDeformed(struct ModifierData *md);
398 bool          modifier_isSameTopology(ModifierData *md);
399 bool          modifier_isNonGeometrical(ModifierData *md);
400 bool          modifier_isEnabled(struct Scene *scene, struct ModifierData *md, int required_mode);
401 void          modifier_setError(struct ModifierData *md, const char *format, ...) ATTR_PRINTF_FORMAT(2, 3);
402 bool          modifier_isPreview(struct ModifierData *md);
403
404 void          modifiers_foreachObjectLink(struct Object *ob,
405                                           ObjectWalkFunc walk,
406                                           void *userData);
407 void          modifiers_foreachIDLink(struct Object *ob,
408                                       IDWalkFunc walk,
409                                       void *userData);
410 void          modifiers_foreachTexLink(struct Object *ob,
411                                        TexWalkFunc walk,
412                                        void *userData);
413
414 struct ModifierData  *modifiers_findByType(struct Object *ob, ModifierType type);
415 struct ModifierData  *modifiers_findByName(struct Object *ob, const char *name);
416 void          modifiers_clearErrors(struct Object *ob);
417 int           modifiers_getCageIndex(struct Scene *scene, struct Object *ob,
418                                      int *r_lastPossibleCageIndex, bool is_virtual);
419
420 bool          modifiers_isModifierEnabled(struct Object *ob, int modifierType);
421 bool          modifiers_isSoftbodyEnabled(struct Object *ob);
422 bool          modifiers_isClothEnabled(struct Object *ob);
423 bool          modifiers_isParticleEnabled(struct Object *ob);
424
425 struct Object *modifiers_isDeformedByArmature(struct Object *ob);
426 struct Object *modifiers_isDeformedByLattice(struct Object *ob);
427 struct Object *modifiers_isDeformedByCurve(struct Object *ob);
428 bool          modifiers_usesArmature(struct Object *ob, struct bArmature *arm);
429 bool          modifiers_isCorrectableDeformed(struct Scene *scene, struct Object *ob);
430 void          modifier_freeTemporaryData(struct ModifierData *md);
431 bool          modifiers_isPreview(struct Object *ob);
432
433 typedef struct CDMaskLink {
434         struct CDMaskLink *next;
435         CustomDataMask mask;
436 } CDMaskLink;
437
438 /* Calculates and returns a linked list of CustomDataMasks indicating the
439  * data required by each modifier in the stack pointed to by md for correct
440  * evaluation, assuming the data indicated by dataMask is required at the
441  * end of the stack.
442  */
443 struct CDMaskLink *modifiers_calcDataMasks(struct Scene *scene,
444                                            struct Object *ob,
445                                            struct ModifierData *md,
446                                            CustomDataMask dataMask,
447                                            int required_mode,
448                                            ModifierData *previewmd, CustomDataMask previewmask);
449 struct ModifierData *modifiers_getLastPreview(struct Scene *scene,
450                                               struct ModifierData *md,
451                                               int required_mode);
452
453 typedef struct VirtualModifierData {
454         ArmatureModifierData amd;
455         CurveModifierData cmd;
456         LatticeModifierData lmd;
457         ShapeKeyModifierData smd;
458 } VirtualModifierData;
459
460 struct ModifierData  *modifiers_getVirtualModifierList(struct Object *ob, struct VirtualModifierData *data);
461
462 /* ensure modifier correctness when changing ob->data */
463 void test_object_modifiers(struct Object *ob);
464
465 /* here for do_versions */
466 void modifier_mdef_compact_influences(struct ModifierData *md);
467
468 void        modifier_path_init(char *path, int path_maxlen, const char *name);
469 const char *modifier_path_relbase(struct Object *ob);
470
471
472 /* wrappers for modifier callbacks that ensure valid normals */
473
474 struct DerivedMesh *modwrap_applyModifier(
475         ModifierData *md, const struct ModifierEvalContext *ctx,
476         struct DerivedMesh *dm);
477
478 struct DerivedMesh *modwrap_applyModifierEM(
479         ModifierData *md, const struct ModifierEvalContext *ctx,
480         struct BMEditMesh *em, struct DerivedMesh *dm);
481
482 void modwrap_deformVerts(
483         ModifierData *md, const struct ModifierEvalContext *ctx,
484         struct DerivedMesh *dm,
485         float (*vertexCos)[3], int numVerts);
486
487 void modwrap_deformVertsEM(
488         ModifierData *md, const struct ModifierEvalContext *ctx,
489         struct BMEditMesh *em, struct DerivedMesh *dm,
490         float (*vertexCos)[3], int numVerts);
491
492 /* wrappers for modifier callbacks that accept Mesh and select the proper implementation
493  * depending on if the modifier has been ported to Mesh or is still using DerivedMesh
494  */
495
496 void modifier_deformVerts(
497         struct ModifierData *md, const struct ModifierEvalContext *ctx,
498         struct Mesh *mesh, float (*vertexCos)[3], int numVerts);
499
500 void modifier_deformMatrices(
501         struct ModifierData *md, const struct ModifierEvalContext *ctx,
502         struct Mesh *mesh, float (*vertexCos)[3], float (*defMats)[3][3], int numVerts);
503
504 void modifier_deformVertsEM(
505         struct ModifierData *md, const struct ModifierEvalContext *ctx,
506         struct BMEditMesh *editData, struct Mesh *mesh,
507         float (*vertexCos)[3], int numVerts);
508
509 void modifier_deformMatricesEM(
510         struct ModifierData *md, const struct ModifierEvalContext *ctx,
511         struct BMEditMesh *editData, struct Mesh *mesh,
512         float (*vertexCos)[3], float (*defMats)[3][3], int numVerts);
513
514 struct Mesh *modifier_applyModifier(
515         struct ModifierData *md, const struct ModifierEvalContext *ctx,
516         struct Mesh *mesh);
517
518 struct Mesh *modifier_applyModifierEM(
519         struct ModifierData *md, const struct ModifierEvalContext *ctx,
520         struct BMEditMesh *editData, struct Mesh *mesh);
521
522 /* depricated variants of above that accept DerivedMesh */
523
524 void modifier_deformVerts_DM_deprecated(
525         struct ModifierData *md, const struct ModifierEvalContext *ctx,
526         struct DerivedMesh *dm, float (*vertexCos)[3], int numVerts);
527
528 void modifier_deformMatrices_DM_deprecated(
529         struct ModifierData *md, const struct ModifierEvalContext *ctx,
530         struct DerivedMesh *dm,
531         float (*vertexCos)[3], float (*defMats)[3][3], int numVerts);
532
533 void modifier_deformVertsEM_DM_deprecated(
534         struct ModifierData *md, const struct ModifierEvalContext *ctx,
535         struct BMEditMesh *editData, struct DerivedMesh *dm,
536         float (*vertexCos)[3], int numVerts);
537
538 void modifier_deformMatricesEM_DM_deprecated(
539         struct ModifierData *md, const struct ModifierEvalContext *ctx,
540         struct BMEditMesh *editData, struct DerivedMesh *dm,
541         float (*vertexCos)[3], float (*defMats)[3][3], int numVerts);
542
543 struct DerivedMesh *modifier_applyModifier_DM_deprecated(
544         struct ModifierData *md, const struct ModifierEvalContext *ctx,
545         struct DerivedMesh *dm);
546
547 struct DerivedMesh *modifier_applyModifierEM_DM_deprecated(
548         struct ModifierData *md, const struct ModifierEvalContext *ctx,
549         struct BMEditMesh *editData, struct DerivedMesh *dm);
550
551 struct Mesh *BKE_modifier_get_evaluated_mesh_from_object(struct Object *ob, const ModifierApplyFlag flag);
552
553 #endif
554