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