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 DerivedMesh;
37 struct DagForest;
38 struct DagNode;
39 struct EvaluationContext;
40 struct Object;
41 struct Scene;
42 struct SceneLayer;
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 ModifierTypeInfo {
133         /* The user visible name for this modifier */
134         char name[32];
135
136         /* The DNA struct name for the modifier data type, used to
137          * write the DNA data out.
138          */
139         char structName[32];
140
141         /* The size of the modifier data type, used by allocation. */
142         int structSize;
143
144         ModifierTypeType type;
145         ModifierTypeFlag flags;
146
147
148         /********************* Non-optional functions *********************/
149
150         /* Copy instance data for this modifier type. Should copy all user
151          * level settings to the target modifier.
152          */
153         void (*copyData)(struct ModifierData *md, struct ModifierData *target);
154
155         /********************* Deform modifier functions *********************/
156
157         /* Only for deform types, should apply the deformation
158          * to the given vertex array. If the deformer requires information from
159          * the object it can obtain it from the derivedData argument if non-NULL,
160          * and otherwise the ob argument.
161          */
162         void (*deformVerts)(struct ModifierData *md, const struct EvaluationContext *eval_ctx,
163                             struct Object *ob, struct DerivedMesh *derivedData,
164                             float (*vertexCos)[3], int numVerts,
165                             ModifierApplyFlag flag);
166
167         /* Like deformMatricesEM but called from object mode (for supporting modifiers in sculpt mode) */
168         void (*deformMatrices)(struct ModifierData *md, const struct EvaluationContext *eval_ctx,
169                                struct Object *ob, struct DerivedMesh *derivedData,
170                                float (*vertexCos)[3], float (*defMats)[3][3], int numVerts);
171
172         /* Like deformVerts but called during editmode (for supporting modifiers)
173          */
174         void (*deformVertsEM)(struct ModifierData *md, const struct EvaluationContext *eval_ctx,
175                               struct Object *ob, struct BMEditMesh *editData,
176                               struct DerivedMesh *derivedData,
177                               float (*vertexCos)[3], int numVerts);
178
179         /* Set deform matrix per vertex for crazyspace correction */
180         void (*deformMatricesEM)(struct ModifierData *md, const struct EvaluationContext *eval_ctx,
181                                  struct Object *ob, struct BMEditMesh *editData,
182                                  struct DerivedMesh *derivedData,
183                                  float (*vertexCos)[3], float (*defMats)[3][3], int numVerts);
184
185         /********************* Non-deform modifier functions *********************/
186
187         /* For non-deform types: apply the modifier and return a derived
188          * data object (type is dependent on object type).
189          *
190          * The derivedData argument should always be non-NULL; the modifier
191          * should read the object data from the derived object instead of the
192          * actual object data. 
193          *
194          * The useRenderParams argument indicates if the modifier is being
195          * applied in the service of the renderer which may alter quality
196          * settings.
197          *
198          * The isFinalCalc parameter indicates if the modifier is being
199          * calculated for a final result or for something temporary
200          * (like orcos). This is a hack at the moment, it is meant so subsurf
201          * can know if it is safe to reuse its internal cache.
202          *
203          * The modifier may reuse the derivedData argument (i.e. return it in
204          * modified form), but must not release it.
205          */
206         struct DerivedMesh *(*applyModifier)(struct ModifierData *md, const struct EvaluationContext *eval_ctx,
207                                              struct Object *ob, struct DerivedMesh *derivedData,
208                                              ModifierApplyFlag flag);
209
210         /* Like applyModifier but called during editmode (for supporting
211          * modifiers).
212          * 
213          * The derived object that is returned must support the operations that
214          * are expected from editmode objects. The same qualifications regarding
215          * derivedData apply as for applyModifier.
216          */
217         struct DerivedMesh *(*applyModifierEM)(struct ModifierData *md, const struct EvaluationContext *eval_ctx,
218                                                struct Object *ob, struct BMEditMesh *editData,
219                                                struct DerivedMesh *derivedData, ModifierApplyFlag flag);
220
221
222         /********************* Optional functions *********************/
223
224         /* Initialize new instance data for this modifier type, this function
225          * should set modifier variables to their default values.
226          * 
227          * This function is optional.
228          */
229         void (*initData)(struct ModifierData *md);
230
231         /* Should return a CustomDataMask indicating what data this
232          * modifier needs. If (mask & (1 << (layer type))) != 0, this modifier
233          * needs that custom data layer. This function's return value can change
234          * depending on the modifier's settings.
235          *
236          * Note that this means extra data (e.g. vertex groups) - it is assumed
237          * that all modifiers need mesh data and deform modifiers need vertex
238          * coordinates.
239          *
240          * Note that this limits the number of custom data layer types to 32.
241          *
242          * If this function is not present or it returns 0, it is assumed that
243          * no extra data is needed.
244          *
245          * This function is optional.
246          */
247         CustomDataMask (*requiredDataMask)(struct Object *ob, struct ModifierData *md);
248
249         /* Free internal modifier data variables, this function should
250          * not free the md variable itself.
251          *
252          * This function is optional.
253          */
254         void (*freeData)(struct ModifierData *md);
255
256         /* Return a boolean value indicating if this modifier is able to be
257          * calculated based on the modifier data. This is *not* regarding the
258          * md->flag, that is tested by the system, this is just if the data
259          * validates (for example, a lattice will return false if the lattice
260          * object is not defined).
261          *
262          * This function is optional (assumes never disabled if not present).
263          */
264         bool (*isDisabled)(struct ModifierData *md, int userRenderParams);
265
266         /* Add the appropriate relations to the dependency graph.
267          *
268          * This function is optional.
269          */
270         void (*updateDepsgraph)(struct ModifierData *md,
271                                 struct Main *bmain,
272                                 struct Scene *scene,
273                                 struct Object *ob,
274                                 struct DepsNodeHandle *node);
275
276         /* Should return true if the modifier needs to be recalculated on time
277          * changes.
278          *
279          * This function is optional (assumes false if not present).
280          */
281         bool (*dependsOnTime)(struct ModifierData *md);
282
283
284         /* True when a deform modifier uses normals, the requiredDataMask
285          * cant be used here because that refers to a normal layer where as
286          * in this case we need to know if the deform modifier uses normals.
287          * 
288          * this is needed because applying 2 deform modifiers will give the
289          * second modifier bogus normals.
290          * */
291         bool (*dependsOnNormals)(struct ModifierData *md);
292
293
294         /* Should call the given walk function on with a pointer to each Object
295          * pointer that the modifier data stores. This is used for linking on file
296          * load and for unlinking objects or forwarding object references.
297          *
298          * This function is optional.
299          */
300         void (*foreachObjectLink)(struct ModifierData *md, struct Object *ob,
301                                   ObjectWalkFunc walk, void *userData);
302
303         /* Should call the given walk function with a pointer to each ID
304          * pointer (i.e. each datablock pointer) that the modifier data
305          * stores. This is used for linking on file load and for
306          * unlinking datablocks or forwarding datablock references.
307          *
308          * This function is optional. If it is not present, foreachObjectLink
309          * will be used.
310          */
311         void (*foreachIDLink)(struct ModifierData *md, struct Object *ob,
312                               IDWalkFunc walk, void *userData);
313
314         /* Should call the given walk function for each texture that the
315          * modifier data stores. This is used for finding all textures in
316          * the context for the UI.
317          *
318          * This function is optional. If it is not present, it will be
319          * assumed the modifier has no textures.
320          */
321         void (*foreachTexLink)(struct ModifierData *md, struct Object *ob,
322                                TexWalkFunc walk, void *userData);
323 } ModifierTypeInfo;
324
325 /* Initialize modifier's global data (type info and some common global storages). */
326 void BKE_modifier_init(void);
327
328 const ModifierTypeInfo *modifierType_getInfo(ModifierType type);
329
330 /* Modifier utility calls, do call through type pointer and return
331  * default values if pointer is optional.
332  */
333 struct ModifierData  *modifier_new(int type);
334 void          modifier_free(struct ModifierData *md);
335
336 bool          modifier_unique_name(struct ListBase *modifiers, struct ModifierData *md);
337
338 void          modifier_copyData_generic(const struct ModifierData *md, struct ModifierData *target);
339 void          modifier_copyData(struct ModifierData *md, struct ModifierData *target);
340 void          modifier_copyData_ex(struct ModifierData *md, struct ModifierData *target, const int flag);
341 bool          modifier_dependsOnTime(struct ModifierData *md);
342 bool          modifier_supportsMapping(struct ModifierData *md);
343 bool          modifier_supportsCage(struct Scene *scene, struct ModifierData *md);
344 bool          modifier_couldBeCage(struct Scene *scene, struct ModifierData *md);
345 bool          modifier_isCorrectableDeformed(struct ModifierData *md);
346 bool          modifier_isSameTopology(ModifierData *md);
347 bool          modifier_isNonGeometrical(ModifierData *md);
348 bool          modifier_isEnabled(struct Scene *scene, struct ModifierData *md, int required_mode);
349 void          modifier_setError(struct ModifierData *md, const char *format, ...) ATTR_PRINTF_FORMAT(2, 3);
350 bool          modifier_isPreview(struct ModifierData *md);
351
352 void          modifiers_foreachObjectLink(struct Object *ob,
353                                           ObjectWalkFunc walk,
354                                           void *userData);
355 void          modifiers_foreachIDLink(struct Object *ob,
356                                       IDWalkFunc walk,
357                                       void *userData);
358 void          modifiers_foreachTexLink(struct Object *ob,
359                                        TexWalkFunc walk,
360                                        void *userData);
361
362 struct ModifierData  *modifiers_findByType(struct Object *ob, ModifierType type);
363 struct ModifierData  *modifiers_findByName(struct Object *ob, const char *name);
364 void          modifiers_clearErrors(struct Object *ob);
365 int           modifiers_getCageIndex(struct Scene *scene, struct Object *ob,
366                                      int *r_lastPossibleCageIndex, bool is_virtual);
367
368 bool          modifiers_isModifierEnabled(struct Object *ob, int modifierType);
369 bool          modifiers_isSoftbodyEnabled(struct Object *ob);
370 bool          modifiers_isClothEnabled(struct Object *ob);
371 bool          modifiers_isParticleEnabled(struct Object *ob);
372
373 struct Object *modifiers_isDeformedByArmature(struct Object *ob);
374 struct Object *modifiers_isDeformedByLattice(struct Object *ob);
375 struct Object *modifiers_isDeformedByCurve(struct Object *ob);
376 bool          modifiers_usesArmature(struct Object *ob, struct bArmature *arm);
377 bool          modifiers_isCorrectableDeformed(struct Scene *scene, struct Object *ob);
378 void          modifier_freeTemporaryData(struct ModifierData *md);
379 bool          modifiers_isPreview(struct Object *ob);
380
381 typedef struct CDMaskLink {
382         struct CDMaskLink *next;
383         CustomDataMask mask;
384 } CDMaskLink;
385
386 /* Calculates and returns a linked list of CustomDataMasks indicating the
387  * data required by each modifier in the stack pointed to by md for correct
388  * evaluation, assuming the data indicated by dataMask is required at the
389  * end of the stack.
390  */
391 struct CDMaskLink *modifiers_calcDataMasks(struct Scene *scene,
392                                            struct Object *ob,
393                                            struct ModifierData *md,
394                                            CustomDataMask dataMask,
395                                            int required_mode,
396                                            ModifierData *previewmd, CustomDataMask previewmask);
397 struct ModifierData *modifiers_getLastPreview(struct Scene *scene,
398                                               struct ModifierData *md,
399                                               int required_mode);
400
401 typedef struct VirtualModifierData {
402         ArmatureModifierData amd;
403         CurveModifierData cmd;
404         LatticeModifierData lmd;
405         ShapeKeyModifierData smd;
406 } VirtualModifierData;
407
408 struct ModifierData  *modifiers_getVirtualModifierList(struct Object *ob, struct VirtualModifierData *data);
409
410 /* ensure modifier correctness when changing ob->data */
411 void test_object_modifiers(struct Object *ob);
412
413 /* here for do_versions */
414 void modifier_mdef_compact_influences(struct ModifierData *md);
415
416 void        modifier_path_init(char *path, int path_maxlen, const char *name);
417 const char *modifier_path_relbase(struct Object *ob);
418
419
420 /* wrappers for modifier callbacks */
421
422 struct DerivedMesh *modwrap_applyModifier(
423         ModifierData *md, const struct EvaluationContext *eval_ctx,
424         struct Object *ob, struct DerivedMesh *dm,
425         ModifierApplyFlag flag);
426
427 struct DerivedMesh *modwrap_applyModifierEM(
428         ModifierData *md, const struct EvaluationContext *eval_ctx,
429         struct Object *ob, struct BMEditMesh *em,
430         struct DerivedMesh *dm,
431         ModifierApplyFlag flag);
432
433 void modwrap_deformVerts(
434         ModifierData *md, const struct EvaluationContext *eval_ctx,
435         struct Object *ob, struct DerivedMesh *dm,
436         float (*vertexCos)[3], int numVerts,
437         ModifierApplyFlag flag);
438
439 void modwrap_deformVertsEM(
440         ModifierData *md, const struct EvaluationContext *eval_ctx, struct Object *ob,
441         struct BMEditMesh *em, struct DerivedMesh *dm,
442         float (*vertexCos)[3], int numVerts);
443
444 #endif
445