Cleanup: comments (long lines) in blenkernel
[blender.git] / source / blender / blenkernel / BKE_modifier.h
1 /*
2  * This program is free software; you can redistribute it and/or
3  * modify it under the terms of the GNU General Public License
4  * as published by the Free Software Foundation; either version 2
5  * of the License, or (at your option) any later version.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * along with this program; if not, write to the Free Software Foundation,
14  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
15  */
16 #ifndef __BKE_MODIFIER_H__
17 #define __BKE_MODIFIER_H__
18
19 /** \file
20  * \ingroup bke
21  */
22
23 #include "DNA_modifier_types.h" /* needed for all enum typdefs */
24 #include "BLI_compiler_attrs.h"
25 #include "BKE_customdata.h"
26
27 struct BMEditMesh;
28 struct CustomData_MeshMasks;
29 struct DepsNodeHandle;
30 struct Depsgraph;
31 struct ID;
32 struct ListBase;
33 struct Main;
34 struct Mesh;
35 struct ModifierData;
36 struct Object;
37 struct Scene;
38 struct ViewLayer;
39 struct bArmature;
40
41 typedef enum {
42   /* Should not be used, only for None modifier type */
43   eModifierTypeType_None,
44
45   /* Modifier only does deformation, implies that modifier
46    * type should have a valid deformVerts function. OnlyDeform
47    * style modifiers implicitly accept either mesh or CV
48    * input but should still declare flags appropriately.
49    */
50   eModifierTypeType_OnlyDeform,
51
52   eModifierTypeType_Constructive,
53   eModifierTypeType_Nonconstructive,
54
55   /* both deformVerts & applyModifier are valid calls
56    * used for particles modifier that doesn't actually modify the object
57    * unless it's a mesh and can be exploded -> curve can also emit particles
58    */
59   eModifierTypeType_DeformOrConstruct,
60
61   /* Like eModifierTypeType_Nonconstructive, but does not affect the geometry
62    * of the object, rather some of its CustomData layers.
63    * E.g. UVProject and WeightVG modifiers. */
64   eModifierTypeType_NonGeometrical,
65 } ModifierTypeType;
66
67 typedef enum {
68   eModifierTypeFlag_AcceptsMesh = (1 << 0),
69   eModifierTypeFlag_AcceptsCVs = (1 << 1),
70   eModifierTypeFlag_SupportsMapping = (1 << 2),
71   eModifierTypeFlag_SupportsEditmode = (1 << 3),
72
73   /* For modifiers that support editmode this determines if the
74    * modifier should be enabled by default in editmode. This should
75    * only be used by modifiers that are relatively speedy and
76    * also generally used in editmode, otherwise let the user enable
77    * it by hand.
78    */
79   eModifierTypeFlag_EnableInEditmode = (1 << 4),
80
81   /* For modifiers that require original data and so cannot
82    * be placed after any non-deformative modifier.
83    */
84   eModifierTypeFlag_RequiresOriginalData = (1 << 5),
85
86   /* For modifiers that support pointcache,
87    * so we can check to see if it has files we need to deal with. */
88   eModifierTypeFlag_UsesPointCache = (1 << 6),
89
90   /* For physics modifiers, max one per type */
91   eModifierTypeFlag_Single = (1 << 7),
92
93   /* Some modifier can't be added manually by user */
94   eModifierTypeFlag_NoUserAdd = (1 << 8),
95
96   /* For modifiers that use CD_PREVIEW_MCOL for preview. */
97   eModifierTypeFlag_UsesPreview = (1 << 9),
98   eModifierTypeFlag_AcceptsLattice = (1 << 10),
99 } ModifierTypeFlag;
100
101 /* IMPORTANT! Keep ObjectWalkFunc and IDWalkFunc signatures compatible. */
102 typedef void (*ObjectWalkFunc)(void *userData,
103                                struct Object *ob,
104                                struct Object **obpoin,
105                                int cb_flag);
106 typedef void (*IDWalkFunc)(void *userData, struct Object *ob, struct ID **idpoin, int cb_flag);
107 typedef void (*TexWalkFunc)(void *userData,
108                             struct Object *ob,
109                             struct ModifierData *md,
110                             const char *propname);
111
112 typedef enum ModifierApplyFlag {
113   /** Render time. */
114   MOD_APPLY_RENDER = 1 << 0,
115   /** Result of evaluation will be cached, so modifier might
116    * want to cache data for quick updates (used by subsurf) */
117   MOD_APPLY_USECACHE = 1 << 1,
118   /** Modifier evaluated for undeformed texture coordinates */
119   MOD_APPLY_ORCO = 1 << 2,
120   /** Ignore scene simplification flag and use subdivisions
121    * level set in multires modifier. */
122   MOD_APPLY_IGNORE_SIMPLIFY = 1 << 3,
123 } ModifierApplyFlag;
124
125 typedef struct ModifierUpdateDepsgraphContext {
126   struct Scene *scene;
127   struct Object *object;
128   struct DepsNodeHandle *node;
129 } ModifierUpdateDepsgraphContext;
130
131 /* Contains the information for deformXXX and applyXXX functions below that
132  * doesn't change between consecutive modifiers. */
133 typedef struct ModifierEvalContext {
134   struct Depsgraph *depsgraph;
135   struct Object *object;
136   ModifierApplyFlag flag;
137 } ModifierEvalContext;
138
139 typedef struct ModifierTypeInfo {
140   /* The user visible name for this modifier */
141   char name[32];
142
143   /* The DNA struct name for the modifier data type, used to
144    * write the DNA data out.
145    */
146   char structName[32];
147
148   /* The size of the modifier data type, used by allocation. */
149   int structSize;
150
151   ModifierTypeType type;
152   ModifierTypeFlag flags;
153
154   /********************* Non-optional functions *********************/
155
156   /* Copy instance data for this modifier type. Should copy all user
157    * level settings to the target modifier.
158    *
159    * \param flag: Copying options (see BKE_library.h's LIB_ID_COPY_... flags for more).
160    */
161   void (*copyData)(const struct ModifierData *md, struct ModifierData *target, const int flag);
162
163   /********************* Deform modifier functions *********************/
164
165   /* Only for deform types, should apply the deformation
166    * to the given vertex array. If the deformer requires information from
167    * the object it can obtain it from the mesh argument if non-NULL,
168    * and otherwise the ob argument.
169    */
170   void (*deformVerts)(struct ModifierData *md,
171                       const struct ModifierEvalContext *ctx,
172                       struct Mesh *mesh,
173                       float (*vertexCos)[3],
174                       int numVerts);
175
176   /* Like deformMatricesEM but called from object mode (for supporting modifiers in sculpt mode) */
177   void (*deformMatrices)(struct ModifierData *md,
178                          const struct ModifierEvalContext *ctx,
179                          struct Mesh *mesh,
180                          float (*vertexCos)[3],
181                          float (*defMats)[3][3],
182                          int numVerts);
183
184   /* Like deformVerts but called during editmode (for supporting modifiers)
185    */
186   void (*deformVertsEM)(struct ModifierData *md,
187                         const struct ModifierEvalContext *ctx,
188                         struct BMEditMesh *editData,
189                         struct Mesh *mesh,
190                         float (*vertexCos)[3],
191                         int numVerts);
192
193   /* Set deform matrix per vertex for crazyspace correction */
194   void (*deformMatricesEM)(struct ModifierData *md,
195                            const struct ModifierEvalContext *ctx,
196                            struct BMEditMesh *editData,
197                            struct Mesh *mesh,
198                            float (*vertexCos)[3],
199                            float (*defMats)[3][3],
200                            int numVerts);
201
202   /********************* Non-deform modifier functions *********************/
203
204   /* For non-deform types: apply the modifier and return a mesh object.
205    *
206    * The mesh argument should always be non-NULL; the modifier
207    * should read the object data from the mesh object instead of the
208    * actual object data.
209    *
210    * The modifier may reuse the mesh argument (i.e. return it in
211    * modified form), but must not release it.
212    */
213   struct Mesh *(*applyModifier)(struct ModifierData *md,
214                                 const struct ModifierEvalContext *ctx,
215                                 struct Mesh *mesh);
216
217   /********************* Optional functions *********************/
218
219   /* Initialize new instance data for this modifier type, this function
220    * should set modifier variables to their default values.
221    *
222    * This function is optional.
223    */
224   void (*initData)(struct ModifierData *md);
225
226   /* Should add to passed \a r_cddata_masks the data types that this
227    * modifier needs. If (mask & (1 << (layer type))) != 0, this modifier
228    * needs that custom data layer. It can change required layers
229    * depending on the modifier's settings.
230    *
231    * Note that this means extra data (e.g. vertex groups) - it is assumed
232    * that all modifiers need mesh data and deform modifiers need vertex
233    * coordinates.
234    *
235    * If this function is not present, it is assumed that no extra data is needed.
236    *
237    * This function is optional.
238    */
239   void (*requiredDataMask)(struct Object *ob,
240                            struct ModifierData *md,
241                            struct CustomData_MeshMasks *r_cddata_masks);
242
243   /* Free internal modifier data variables, this function should
244    * not free the md variable itself.
245    *
246    * This function is responsible for freeing the runtime data as well.
247    *
248    * This function is optional.
249    */
250   void (*freeData)(struct ModifierData *md);
251
252   /* Return a boolean value indicating if this modifier is able to be
253    * calculated based on the modifier data. This is *not* regarding the
254    * md->flag, that is tested by the system, this is just if the data
255    * validates (for example, a lattice will return false if the lattice
256    * object is not defined).
257    *
258    * This function is optional (assumes never disabled if not present).
259    */
260   bool (*isDisabled)(const struct Scene *scene, struct ModifierData *md, bool userRenderParams);
261
262   /* Add the appropriate relations to the dependency graph.
263    *
264    * This function is optional.
265    */
266   void (*updateDepsgraph)(struct ModifierData *md, const ModifierUpdateDepsgraphContext *ctx);
267
268   /* Should return true if the modifier needs to be recalculated on time
269    * changes.
270    *
271    * This function is optional (assumes false if not present).
272    */
273   bool (*dependsOnTime)(struct ModifierData *md);
274
275   /* True when a deform modifier uses normals, the requiredDataMask
276    * cant be used here because that refers to a normal layer whereas
277    * in this case we need to know if the deform modifier uses normals.
278    *
279    * this is needed because applying 2 deform modifiers will give the
280    * second modifier bogus normals.
281    * */
282   bool (*dependsOnNormals)(struct ModifierData *md);
283
284   /* Should call the given walk function on with a pointer to each Object
285    * pointer that the modifier data stores. This is used for linking on file
286    * load and for unlinking objects or forwarding object references.
287    *
288    * This function is optional.
289    */
290   void (*foreachObjectLink)(struct ModifierData *md,
291                             struct Object *ob,
292                             ObjectWalkFunc walk,
293                             void *userData);
294
295   /* Should call the given walk function with a pointer to each ID
296    * pointer (i.e. each datablock pointer) that the modifier data
297    * stores. This is used for linking on file load and for
298    * unlinking datablocks or forwarding datablock references.
299    *
300    * This function is optional. If it is not present, foreachObjectLink
301    * will be used.
302    */
303   void (*foreachIDLink)(struct ModifierData *md,
304                         struct Object *ob,
305                         IDWalkFunc walk,
306                         void *userData);
307
308   /* Should call the given walk function for each texture that the
309    * modifier data stores. This is used for finding all textures in
310    * the context for the UI.
311    *
312    * This function is optional. If it is not present, it will be
313    * assumed the modifier has no textures.
314    */
315   void (*foreachTexLink)(struct ModifierData *md,
316                          struct Object *ob,
317                          TexWalkFunc walk,
318                          void *userData);
319
320   /* Free given runtime data.
321    *
322    * This data is coming from a modifier of the corresponding type, but actual
323    * modifier data is not known here.
324    *
325    * Notes:
326    *  - The data itself is to be de-allocated as well.
327    *  - This calback is allowed to receive NULL pointer as a data, so it's
328    *    more like "ensure the data is freed".
329    */
330   void (*freeRuntimeData)(void *runtime_data);
331 } ModifierTypeInfo;
332
333 /* Initialize modifier's global data (type info and some common global storages). */
334 void BKE_modifier_init(void);
335
336 const ModifierTypeInfo *modifierType_getInfo(ModifierType type);
337
338 /* Modifier utility calls, do call through type pointer and return
339  * default values if pointer is optional.
340  */
341 struct ModifierData *modifier_new(int type);
342 void modifier_free_ex(struct ModifierData *md, const int flag);
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,
348                                struct ModifierData *target,
349                                const int flag);
350 void modifier_copyData(struct ModifierData *md, struct ModifierData *target);
351 void modifier_copyData_ex(struct ModifierData *md, struct ModifierData *target, const int flag);
352 bool modifier_dependsOnTime(struct ModifierData *md);
353 bool modifier_supportsMapping(struct ModifierData *md);
354 bool modifier_supportsCage(struct Scene *scene, struct ModifierData *md);
355 bool modifier_couldBeCage(struct Scene *scene, struct ModifierData *md);
356 bool modifier_isCorrectableDeformed(struct ModifierData *md);
357 bool modifier_isSameTopology(ModifierData *md);
358 bool modifier_isNonGeometrical(ModifierData *md);
359 bool modifier_isEnabled(const struct Scene *scene, struct ModifierData *md, int required_mode);
360 void modifier_setError(struct ModifierData *md, const char *format, ...) ATTR_PRINTF_FORMAT(2, 3);
361 bool modifier_isPreview(struct ModifierData *md);
362
363 void modifiers_foreachObjectLink(struct Object *ob, ObjectWalkFunc walk, void *userData);
364 void modifiers_foreachIDLink(struct Object *ob, IDWalkFunc walk, void *userData);
365 void modifiers_foreachTexLink(struct Object *ob, TexWalkFunc walk, void *userData);
366
367 struct ModifierData *modifiers_findByType(struct Object *ob, ModifierType type);
368 struct ModifierData *modifiers_findByName(struct Object *ob, const char *name);
369 void modifiers_clearErrors(struct Object *ob);
370 int modifiers_getCageIndex(struct Scene *scene,
371                            struct Object *ob,
372                            int *r_lastPossibleCageIndex,
373                            bool is_virtual);
374
375 bool modifiers_isModifierEnabled(struct Object *ob, int modifierType);
376 bool modifiers_isSoftbodyEnabled(struct Object *ob);
377 bool modifiers_isClothEnabled(struct Object *ob);
378 bool modifiers_isParticleEnabled(struct Object *ob);
379
380 struct Object *modifiers_isDeformedByArmature(struct Object *ob);
381 struct Object *modifiers_isDeformedByMeshDeform(struct Object *ob);
382 struct Object *modifiers_isDeformedByLattice(struct Object *ob);
383 struct Object *modifiers_isDeformedByCurve(struct Object *ob);
384 bool modifiers_usesArmature(struct Object *ob, struct bArmature *arm);
385 bool modifiers_isCorrectableDeformed(struct Scene *scene, struct Object *ob);
386 void modifier_freeTemporaryData(struct ModifierData *md);
387 bool modifiers_isPreview(struct Object *ob);
388
389 typedef struct CDMaskLink {
390   struct CDMaskLink *next;
391   struct CustomData_MeshMasks mask;
392 } CDMaskLink;
393
394 /* Calculates and returns a linked list of CustomData_MeshMasks indicating the
395  * data required by each modifier in the stack pointed to by md for correct
396  * evaluation, assuming the data indicated by dataMask is required at the
397  * end of the stack.
398  */
399 struct CDMaskLink *modifiers_calcDataMasks(struct Scene *scene,
400                                            struct Object *ob,
401                                            struct ModifierData *md,
402                                            const struct CustomData_MeshMasks *dataMask,
403                                            int required_mode,
404                                            ModifierData *previewmd,
405                                            const struct CustomData_MeshMasks *previewmask);
406 struct ModifierData *modifiers_getLastPreview(struct Scene *scene,
407                                               struct ModifierData *md,
408                                               int required_mode);
409
410 typedef struct VirtualModifierData {
411   ArmatureModifierData amd;
412   CurveModifierData cmd;
413   LatticeModifierData lmd;
414   ShapeKeyModifierData smd;
415 } VirtualModifierData;
416
417 struct ModifierData *modifiers_getVirtualModifierList(struct Object *ob,
418                                                       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 Main *bmain, struct Object *ob);
428 const char *modifier_path_relbase_from_global(struct Object *ob);
429
430 /* Accessors of original/evaluated modifiers. */
431
432 /* For a given modifier data, get corresponding original one.
433  * If the modifier data is already original, return it as-is. */
434 struct ModifierData *modifier_get_original(struct ModifierData *md);
435 struct ModifierData *modifier_get_evaluated(struct Depsgraph *depsgraph,
436                                             struct Object *object,
437                                             struct ModifierData *md);
438
439 /* wrappers for modifier callbacks that ensure valid normals */
440
441 struct Mesh *modwrap_applyModifier(ModifierData *md,
442                                    const struct ModifierEvalContext *ctx,
443                                    struct Mesh *me);
444
445 void modwrap_deformVerts(ModifierData *md,
446                          const struct ModifierEvalContext *ctx,
447                          struct Mesh *me,
448                          float (*vertexCos)[3],
449                          int numVerts);
450
451 void modwrap_deformVertsEM(ModifierData *md,
452                            const struct ModifierEvalContext *ctx,
453                            struct BMEditMesh *em,
454                            struct Mesh *me,
455                            float (*vertexCos)[3],
456                            int numVerts);
457
458 struct Mesh *BKE_modifier_get_evaluated_mesh_from_evaluated_object(struct Object *ob_eval,
459                                                                    const bool get_cage_mesh);
460
461 #endif