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