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