Cleanup: commas at the end of enums
[blender.git] / source / blender / makesdna / DNA_anim_types.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 Copyright (C) 2009 Blender Foundation, Joshua Leung
19  * All rights reserved.
20  *
21  * Contributor(s): Joshua Leung (full recode)
22  *
23  * ***** END GPL LICENSE BLOCK *****
24  */
25
26 /** \file DNA_anim_types.h
27  *  \ingroup DNA
28  */
29
30 #ifndef __DNA_ANIM_TYPES_H__
31 #define __DNA_ANIM_TYPES_H__
32
33 #ifdef __cplusplus
34 extern "C" {
35 #endif
36
37 #include "DNA_ID.h"
38 #include "DNA_listBase.h"
39 #include "DNA_action_types.h"
40 #include "DNA_curve_types.h"
41
42 /* ************************************************ */
43 /* F-Curve DataTypes */
44
45 /* Modifiers -------------------------------------- */
46
47 /* F-Curve Modifiers (fcm)
48  *
49  * These alter the way F-Curves behave, by altering the value that is returned
50  * when evaluating the curve's data at some time (t).
51  */
52 typedef struct FModifier {
53         struct FModifier *next, *prev;
54
55         struct FCurve *curve;  /* containing curve, only used for updates to CYCLES */
56         void *data;                     /* pointer to modifier data */
57
58         char name[64];          /* user-defined description for the modifier - MAX_ID_NAME-2 */
59         short type;                     /* type of f-curve modifier */
60         short flag;                     /* settings for the modifier */
61
62         float influence;        /* the amount that the modifier should influence the value */
63
64         float sfra;                     /* start frame of restricted frame-range */
65         float efra;                     /* end frame of restricted frame-range */
66         float blendin;          /* number of frames from sfra before modifier takes full influence */
67         float blendout;         /* number of frames from efra before modifier fades out */
68 } FModifier;
69
70 /* Types of F-Curve modifier
71  * WARNING: order here is important!
72  */
73 typedef enum eFModifier_Types {
74         FMODIFIER_TYPE_NULL = 0,
75         FMODIFIER_TYPE_GENERATOR = 1,
76         FMODIFIER_TYPE_FN_GENERATOR = 2,
77         FMODIFIER_TYPE_ENVELOPE = 3,
78         FMODIFIER_TYPE_CYCLES = 4,
79         FMODIFIER_TYPE_NOISE = 5,
80         /** unimplemented - for applying: fft, high/low pass filters, etc. */
81         FMODIFIER_TYPE_FILTER = 6,
82         FMODIFIER_TYPE_PYTHON = 7,
83         FMODIFIER_TYPE_LIMITS = 8,
84         FMODIFIER_TYPE_STEPPED = 9,
85
86         /* NOTE: all new modifiers must be added above this line */
87         FMODIFIER_NUM_TYPES
88 } eFModifier_Types;
89
90 /* F-Curve Modifier Settings */
91 typedef enum eFModifier_Flags {
92                 /* modifier is not able to be evaluated for some reason, and should be skipped (internal) */
93         FMODIFIER_FLAG_DISABLED          = (1<<0),
94                 /* modifier's data is expanded (in UI) */
95         FMODIFIER_FLAG_EXPANDED          = (1<<1),
96                 /* modifier is active one (in UI) for editing purposes */
97         FMODIFIER_FLAG_ACTIVE            = (1<<2),
98                 /* user wants modifier to be skipped */
99         FMODIFIER_FLAG_MUTED             = (1<<3),
100                 /* restrict range that F-Modifier can be considered over */
101         FMODIFIER_FLAG_RANGERESTRICT = (1<<4),
102                 /* use influence control */
103         FMODIFIER_FLAG_USEINFLUENCE  = (1<<5),
104 } eFModifier_Flags;
105
106 /* --- */
107
108 /* Generator modifier data */
109 typedef struct FMod_Generator {
110                 /* general generator information */
111         float *coefficients;            /* coefficients array */
112         unsigned int arraysize;         /* size of the coefficients array */
113
114         int poly_order;                         /* order of polynomial generated (i.e. 1 for linear, 2 for quadratic) */
115         int mode;                                       /* which 'generator' to use eFMod_Generator_Modes */
116
117                 /* settings */
118         int flag;                                       /* settings */
119 } FMod_Generator;
120
121 /* generator modes */
122 typedef enum eFMod_Generator_Modes {
123         FCM_GENERATOR_POLYNOMIAL        = 0,
124         FCM_GENERATOR_POLYNOMIAL_FACTORISED = 1,
125 } eFMod_Generator_Modes;
126
127
128 /* generator flags
129  * - shared by Generator and Function Generator
130  */
131 typedef enum eFMod_Generator_Flags {
132                 /* generator works in conjunction with other modifiers (i.e. doesn't replace those before it) */
133         FCM_GENERATOR_ADDITIVE  = (1<<0),
134 } eFMod_Generator_Flags;
135
136
137 /* 'Built-In Function' Generator modifier data
138  *
139  * This uses the general equation for equations:
140  * y = amplitude * fn(phase_multiplier*x + phase_offset) + y_offset
141  *
142  * where amplitude, phase_multiplier/offset, y_offset are user-defined coefficients,
143  * x is the evaluation 'time', and 'y' is the resultant value
144  */
145 typedef struct FMod_FunctionGenerator {
146                 /* coefficients for general equation (as above) */
147         float amplitude;
148         float phase_multiplier;
149         float phase_offset;
150         float value_offset;
151
152                 /* flags */
153         int type;                               /* eFMod_Generator_Functions */
154         int flag;                               /* eFMod_Generator_flags */
155 } FMod_FunctionGenerator;
156
157 /* 'function' generator types */
158 typedef enum eFMod_Generator_Functions {
159         FCM_GENERATOR_FN_SIN    = 0,
160         FCM_GENERATOR_FN_COS    = 1,
161         FCM_GENERATOR_FN_TAN    = 2,
162         FCM_GENERATOR_FN_SQRT   = 3,
163         FCM_GENERATOR_FN_LN     = 4,
164         FCM_GENERATOR_FN_SINC   = 5,
165 } eFMod_Generator_Functions;
166
167
168 /* envelope modifier - envelope data */
169 typedef struct FCM_EnvelopeData {
170         float min, max;                         /* min/max values for envelope at this point (absolute values)  */
171         float time;                                     /* time for that this sample-point occurs */
172
173         short f1;                                       /* settings for 'min' control point */
174         short f2;                                       /* settings for 'max' control point */
175 } FCM_EnvelopeData;
176
177 /* envelope-like adjustment to values (for fade in/out) */
178 typedef struct FMod_Envelope {
179         FCM_EnvelopeData *data;         /* data-points defining envelope to apply (array)  */
180         int totvert;                            /* number of envelope points */
181
182         float midval;                           /* value that envelope's influence is centered around / based on */
183         float min, max;                         /* distances from 'middle-value' for 1:1 envelope influence */
184 } FMod_Envelope;
185
186
187 /* cycling/repetition modifier data */
188 // TODO: we can only do complete cycles...
189 typedef struct FMod_Cycles {
190         short   before_mode;            /* extrapolation mode to use before first keyframe */
191         short   after_mode;                     /* extrapolation mode to use after last keyframe */
192         short   before_cycles;          /* number of 'cycles' before first keyframe to do */
193         short   after_cycles;           /* number of 'cycles' after last keyframe to do */
194 } FMod_Cycles;
195
196 /* cycling modes */
197 typedef enum eFMod_Cycling_Modes {
198         /** don't do anything */
199         FCM_EXTRAPOLATE_NONE = 0,
200         /** repeat keyframe range as-is */
201         FCM_EXTRAPOLATE_CYCLIC,
202         /** repeat keyframe range, but with offset based on gradient between values */
203         FCM_EXTRAPOLATE_CYCLIC_OFFSET,
204         /** alternate between forward and reverse playback of keyframe range */
205         FCM_EXTRAPOLATE_MIRROR
206 } eFMod_Cycling_Modes;
207
208
209 /* Python-script modifier data */
210 typedef struct FMod_Python {
211         struct Text *script;            /* text buffer containing script to execute */
212         IDProperty *prop;                       /* ID-properties to provide 'custom' settings */
213 } FMod_Python;
214
215
216 /* limits modifier data */
217 typedef struct FMod_Limits {
218         rctf rect;                                      /* rect defining the min/max values */
219         int flag;                                       /* settings for limiting */
220         int pad;
221 } FMod_Limits;
222
223 /* limiting flags */
224 typedef enum eFMod_Limit_Flags {
225         FCM_LIMIT_XMIN          = (1<<0),
226         FCM_LIMIT_XMAX          = (1<<1),
227         FCM_LIMIT_YMIN          = (1<<2),
228         FCM_LIMIT_YMAX          = (1<<3),
229 } eFMod_Limit_Flags;
230
231
232 /* noise modifier data */
233 typedef struct FMod_Noise {
234         float size;
235         float strength;
236         float phase;
237         float offset;
238
239         short depth;
240         short modification;
241 } FMod_Noise;
242
243 /* modification modes */
244 typedef enum eFMod_Noise_Modifications {
245         FCM_NOISE_MODIF_REPLACE = 0,    /* Modify existing curve, matching it's shape */
246         FCM_NOISE_MODIF_ADD,                    /* Add noise to the curve */
247         FCM_NOISE_MODIF_SUBTRACT,               /* Subtract noise from the curve */
248         FCM_NOISE_MODIF_MULTIPLY                /* Multiply the curve by noise */
249 } eFMod_Noise_Modifications;
250
251
252 /* stepped modifier data */
253 typedef struct FMod_Stepped {
254         float step_size;                /* Number of frames each interpolated value should be held */
255         float offset;                   /* Reference frame number that stepping starts from */
256
257         float start_frame;              /* start frame of the frame range that modifier works in */
258         float end_frame;                /* end frame of the frame range that modifier works in */
259
260         int flag;                       /* various settings */
261 } FMod_Stepped;
262
263 /* stepped modifier range flags */
264 typedef enum eFMod_Stepped_Flags {
265         FCM_STEPPED_NO_BEFORE   = (1<<0),       /* don't affect frames before the start frame */
266         FCM_STEPPED_NO_AFTER    = (1<<1),       /* don't affect frames after the end frame */
267 } eFMod_Stepped_Flags;
268
269 /* Drivers -------------------------------------- */
270
271 /* Driver Target (dtar)
272  *
273  * Defines how to access a dependency needed for a driver variable.
274  */
275 typedef struct DriverTarget {
276         ID      *id;                            /* ID-block which owns the target, no user count */
277
278         char *rna_path;                 /* RNA path defining the setting to use (for DVAR_TYPE_SINGLE_PROP) */
279
280         char pchan_name[64];    /* name of the posebone to use (for vars where DTAR_FLAG_STRUCT_REF is used) - MAX_ID_NAME-2 */
281         short transChan;                /* transform channel index (for DVAR_TYPE_TRANSFORM_CHAN)*/
282
283         short flag;                             /* flags for the validity of the target (NOTE: these get reset every time the types change) */
284         int idtype;                             /* type of ID-block that this target can use */
285 } DriverTarget;
286
287 /* Driver Target flags */
288 typedef enum eDriverTarget_Flag {
289                 /* used for targets that use the pchan_name instead of RNA path
290                  * (i.e. rotation difference)
291                  */
292         DTAR_FLAG_STRUCT_REF    = (1 << 0),
293                 /* idtype can only be 'Object' */
294         DTAR_FLAG_ID_OB_ONLY    = (1 << 1),
295
296         /* "localspace" flags */
297                 /* base flag - basically "pre parent+constraints" */
298         DTAR_FLAG_LOCALSPACE    = (1 << 2),
299                 /* include constraints transformed to space including parents */
300         DTAR_FLAG_LOCAL_CONSTS  = (1 << 3),
301
302         /* error flags */
303         DTAR_FLAG_INVALID               = (1 << 4),
304 } eDriverTarget_Flag;
305
306 /* Transform Channels for Driver Targets */
307 typedef enum eDriverTarget_TransformChannels {
308         DTAR_TRANSCHAN_LOCX = 0,
309         DTAR_TRANSCHAN_LOCY,
310         DTAR_TRANSCHAN_LOCZ,
311         DTAR_TRANSCHAN_ROTX,
312         DTAR_TRANSCHAN_ROTY,
313         DTAR_TRANSCHAN_ROTZ,
314         DTAR_TRANSCHAN_SCALEX,
315         DTAR_TRANSCHAN_SCALEY,
316         DTAR_TRANSCHAN_SCALEZ,
317
318         MAX_DTAR_TRANSCHAN_TYPES
319 } eDriverTarget_TransformChannels;
320
321 /* --- */
322
323 /* maximum number of driver targets per variable */
324 #define MAX_DRIVER_TARGETS      8
325
326
327 /* Driver Variable (dvar)
328  *
329  * A 'variable' for use as an input for the driver evaluation.
330  * Defines a way of accessing some channel to use, that can be
331  * referred to in the expression as a variable, thus simplifying
332  * expressions and also Depsgraph building.
333  */
334 typedef struct DriverVar {
335         struct DriverVar *next, *prev;
336
337         char name[64];              /* name of the variable to use in py-expression (must be valid python identifier) - MAX_ID_NAME-2 */
338
339         DriverTarget targets[8];    /* MAX_DRIVER_TARGETS, target slots */
340
341         char num_targets;           /* number of targets actually used by this variable */
342         char type;                  /* type of driver variable (eDriverVar_Types) */
343
344         short flag;                 /* validation tags, etc. (eDriverVar_Flags) */
345         float curval;               /* result of previous evaluation */
346 } DriverVar;
347
348 /* Driver Variable Types */
349 typedef enum eDriverVar_Types {
350                 /* single RNA property */
351         DVAR_TYPE_SINGLE_PROP   = 0,
352                 /* rotation difference (between 2 bones) */
353         DVAR_TYPE_ROT_DIFF,
354                 /* distance between objects/bones */
355         DVAR_TYPE_LOC_DIFF,
356                 /* 'final' transform for object/bones */
357         DVAR_TYPE_TRANSFORM_CHAN,
358
359         /* maximum number of variable types
360          * NOTE: this must always be th last item in this list,
361          *       so add new types above this line.
362          */
363         MAX_DVAR_TYPES
364 } eDriverVar_Types;
365
366 /* Driver Variable Flags */
367 typedef enum eDriverVar_Flags {
368         /* variable is not set up correctly */
369         DVAR_FLAG_ERROR               = (1 << 0),
370
371         /* variable name doesn't pass the validation tests */
372         DVAR_FLAG_INVALID_NAME        = (1 << 1),
373         /* name starts with a number */
374         DVAR_FLAG_INVALID_START_NUM   = (1 << 2),
375         /* name starts with a special character (!, $, @, #, _, etc.) */
376         DVAR_FLAG_INVALID_START_CHAR  = (1 << 3),
377         /* name contains a space */
378         DVAR_FLAG_INVALID_HAS_SPACE   = (1 << 4),
379         /* name contains a dot */
380         DVAR_FLAG_INVALID_HAS_DOT     = (1 << 5),
381         /* name contains invalid chars */
382         DVAR_FLAG_INVALID_HAS_SPECIAL = (1 << 6),
383         /* name is a reserved keyword */
384         DVAR_FLAG_INVALID_PY_KEYWORD  = (1 << 7),
385         /* name is zero-length */
386         DVAR_FLAG_INVALID_EMPTY       = (1 << 8),
387 } eDriverVar_Flags;
388
389 /* All invalid dvar name flags */
390 #define DVAR_ALL_INVALID_FLAGS (   \
391         DVAR_FLAG_INVALID_NAME |       \
392         DVAR_FLAG_INVALID_START_NUM | \
393         DVAR_FLAG_INVALID_START_CHAR | \
394         DVAR_FLAG_INVALID_HAS_SPACE |  \
395         DVAR_FLAG_INVALID_HAS_DOT |    \
396         DVAR_FLAG_INVALID_HAS_SPECIAL |  \
397         DVAR_FLAG_INVALID_PY_KEYWORD  | \
398         DVAR_FLAG_INVALID_EMPTY  \
399 )
400
401 /* --- */
402
403 /* Channel Driver (i.e. Drivers / Expressions) (driver)
404  *
405  * Channel Drivers are part of the dependency system, and are executed in addition to
406  * normal user-defined animation. They take the animation result of some channel(s), and
407  * use that (optionally combined with its own F-Curve for modification of results) to define
408  * the value of some setting semi-procedurally.
409  *
410  * Drivers are stored as part of F-Curve data, so that the F-Curve's RNA-path settings (for storing
411  * what setting the driver will affect). The order in which they are stored defines the order that they're
412  * evaluated in. This order is set by the Depsgraph's sorting stuff.
413  */
414 typedef struct ChannelDriver {
415         ListBase variables;     /* targets for this driver (i.e. list of DriverVar) */
416
417         /* python expression to execute (may call functions defined in an accessory file)
418          * which relates the target 'variables' in some way to yield a single usable value
419          */
420         char expression[256];   /* expression to compile for evaluation */
421         void *expr_comp;                /* PyObject - compiled expression, don't save this */
422
423         float curval;           /* result of previous evaluation */
424         float influence;        /* influence of driver on result */ // XXX to be implemented... this is like the constraint influence setting
425
426                 /* general settings */
427         int type;                       /* type of driver */
428         int flag;                       /* settings of driver */
429 } ChannelDriver;
430
431 /* driver type */
432 typedef enum eDriver_Types {
433                 /* target values are averaged together */
434         DRIVER_TYPE_AVERAGE     = 0,
435                 /* python expression/function relates targets */
436         DRIVER_TYPE_PYTHON,
437                 /* sum of all values */
438         DRIVER_TYPE_SUM,
439                 /* smallest value */
440         DRIVER_TYPE_MIN,
441                 /* largest value */
442         DRIVER_TYPE_MAX
443 } eDriver_Types;
444
445 /* driver flags */
446 typedef enum eDriver_Flags {
447                 /* driver has invalid settings (internal flag)  */
448         DRIVER_FLAG_INVALID             = (1<<0),
449                 /* driver needs recalculation (set by depsgraph) */
450         DRIVER_FLAG_RECALC              = (1<<1),
451                 /* driver does replace value, but overrides (for layering of animation over driver) */
452                 // TODO: this needs to be implemented at some stage or left out...
453         //DRIVER_FLAG_LAYERING  = (1<<2),
454                 /* use when the expression needs to be recompiled */
455         DRIVER_FLAG_RECOMPILE   = (1<<3),
456                 /* the names are cached so they don't need have python unicode versions created each time */
457         DRIVER_FLAG_RENAMEVAR   = (1<<4),
458                 /* intermediate values of driver should be shown in the UI for debugging purposes */
459         DRIVER_FLAG_SHOWDEBUG   = (1<<5),
460                 /* include 'self' in the drivers namespace. */
461         DRIVER_FLAG_USE_SELF    = (1<<6),
462 } eDriver_Flags;
463
464 /* F-Curves -------------------------------------- */
465
466 /* FPoint (fpt)
467  *
468  * This is the bare-minimum data required storing motion samples. Should be more efficient
469  * than using BPoints, which contain a lot of other unnecessary data...
470  */
471 typedef struct FPoint {
472         float vec[2];           /* time + value */
473         int flag;                       /* selection info */
474         int pad;
475 } FPoint;
476
477 /* 'Function-Curve' - defines values over time for a given setting (fcu) */
478 typedef struct FCurve {
479         struct FCurve *next, *prev;
480
481                 /* group */
482         bActionGroup *grp;              /* group that F-Curve belongs to */
483
484                 /* driver settings */
485         ChannelDriver *driver;  /* only valid for drivers (i.e. stored in AnimData not Actions) */
486                 /* evaluation settings */
487         ListBase modifiers;             /* FCurve Modifiers */
488
489                 /* motion data */
490         BezTriple *bezt;                /* user-editable keyframes (array) */
491         FPoint *fpt;                    /* 'baked/imported' motion samples (array) */
492         unsigned int totvert;   /* total number of points which define the curve (i.e. size of arrays in FPoints) */
493
494                 /* value cache + settings */
495         float curval;                   /* value stored from last time curve was evaluated (not threadsafe, debug display only!) */
496         short flag;                             /* user-editable settings for this curve */
497         short extend;                   /* value-extending mode for this curve (does not cover  */
498         char auto_smoothing;    /* auto-handle smoothing mode */
499
500         char pad[7];
501
502                 /* RNA - data link */
503         int array_index;                /* if applicable, the index of the RNA-array item to get */
504         char *rna_path;                 /* RNA-path to resolve data-access */
505
506                 /* curve coloring (for editor) */
507         int color_mode;                 /* coloring method to use (eFCurve_Coloring) */
508         float color[3];                 /* the last-color this curve took */
509
510         float prev_norm_factor, prev_offset;
511 } FCurve;
512
513
514 /* user-editable flags/settings */
515 typedef enum eFCurve_Flags {
516         /** curve/keyframes are visible in editor */
517         FCURVE_VISIBLE          = (1<<0),
518         /** curve is selected for editing  */
519         FCURVE_SELECTED         = (1<<1),
520         /** curve is active one */
521         FCURVE_ACTIVE           = (1<<2),
522         /** keyframes (beztriples) cannot be edited */
523         FCURVE_PROTECTED        = (1<<3),
524         /** fcurve will not be evaluated for the next round */
525         FCURVE_MUTED            = (1<<4),
526
527         /** fcurve uses 'auto-handles', which stay horizontal... */
528         // DEPRECATED
529         FCURVE_AUTO_HANDLES     = (1<<5),
530         FCURVE_MOD_OFF          = (1<<6),
531         /** skip evaluation, as RNA-path cannot be resolved
532          * (similar to muting, but cannot be set by user) */
533         FCURVE_DISABLED                 = (1<<10),
534         /** curve can only have whole-number values (integer types) */
535         FCURVE_INT_VALUES               = (1<<11),
536         /** curve can only have certain discrete-number values
537          * (no interpolation at all, for enums/booleans) */
538         FCURVE_DISCRETE_VALUES  = (1<<12),
539
540         /** temporary tag for editing */
541         FCURVE_TAGGED                   = (1<<15),
542 } eFCurve_Flags;
543
544 /* extrapolation modes (only simple value 'extending') */
545 typedef enum eFCurve_Extend {
546         /** just extend min/max keyframe value  */
547         FCURVE_EXTRAPOLATE_CONSTANT     = 0,
548         /** just extend gradient of segment between first segment keyframes */
549         FCURVE_EXTRAPOLATE_LINEAR
550 } eFCurve_Extend;
551
552 /* curve coloring modes */
553 typedef enum eFCurve_Coloring {
554         /** automatically determine color using rainbow (calculated at drawtime) */
555         FCURVE_COLOR_AUTO_RAINBOW = 0,
556         /** automatically determine color using XYZ (array index) <-> RGB */
557         FCURVE_COLOR_AUTO_RGB     = 1,
558         /** automatically determine color where XYZ <-> RGB, but index(X) != 0 */
559         FCURVE_COLOR_AUTO_YRGB    = 3,
560         /** custom color */
561         FCURVE_COLOR_CUSTOM       = 2,
562 } eFCurve_Coloring;
563
564 /* curve smoothing modes */
565 typedef enum eFCurve_Smoothing {
566         /** legacy mode: auto handles only consider adjacent points */
567         FCURVE_SMOOTH_NONE             = 0,
568         /** maintain continuity of the acceleration */
569         FCURVE_SMOOTH_CONT_ACCEL       = 1,
570 } eFCurve_Smoothing;
571
572 /* ************************************************ */
573 /* 'Action' Datatypes */
574
575 /* NOTE: Although these are part of the Animation System,
576  * they are not stored here... see DNA_action_types.h instead
577  */
578
579
580 /* ************************************************ */
581 /* Animation Reuse - i.e. users of Actions */
582
583 /* Retargetting ----------------------------------- */
584
585 /* Retargetting Pair
586  *
587  * Defines what parts of the paths should be remapped from 'abc' to 'xyz'.
588  * TODO:
589  * - Regrex (possibly provided through PY, though having our own module might be faster)
590  *   would be important to have at some point. Current replacements are just simple
591  *   string matches...
592  */
593 typedef struct AnimMapPair {
594         char from[128];         /* part of path to bed replaced */
595         char to[128];           /* part of path to replace with */
596 } AnimMapPair;
597
598 /* Retargetting Information for Actions
599  *
600  * This should only be used if it is strictly necessary (i.e. user will need to explicitly
601  * add this when they find that some channels do not match, or motion is not going to right
602  * places). When executing an action, this will be checked to see if it provides any useful
603  * remaps for the given paths.
604  *
605  * NOTE: we currently don't store this in the Action itself, as that causes too many problems.
606  */
607 // FIXME: will this be too clumsy or slow? If we're using RNA paths anyway, we'll have to accept
608 // such consequences...
609 typedef struct AnimMapper {
610         struct AnimMapper *next, *prev;
611
612         bAction *target;                /* target action */
613         ListBase mappings;              /* remapping table (bAnimMapPair) */
614 } AnimMapper;
615
616 /* ************************************************ */
617 /* NLA - Non-Linear Animation */
618
619 /* NLA Strips ------------------------------------- */
620
621 /* NLA Strip (strip)
622  *
623  * A NLA Strip is a container for the reuse of Action data, defining parameters
624  * to control the remapping of the Action data to some destination.
625  */
626 typedef struct NlaStrip {
627         struct NlaStrip *next, *prev;
628
629         ListBase strips;            /* 'Child' strips (used for 'meta' strips) */
630         bAction *act;               /* Action that is referenced by this strip (strip is 'user' of the action) */
631         AnimMapper *remap;          /* Remapping info this strip (for tweaking correspondence of action with context) */
632
633         ListBase fcurves;           /* F-Curves for controlling this strip's influence and timing */    // TODO: move out?
634         ListBase modifiers;         /* F-Curve modifiers to be applied to the entire strip's referenced F-Curves */
635
636         char name[64];              /* User-Visible Identifier for Strip - MAX_ID_NAME-2 */
637
638         float influence;            /* Influence of strip */
639         float strip_time;           /* Current 'time' within action being used (automatically evaluated, but can be overridden) */
640
641         float start, end;           /* extents of the strip */
642         float actstart, actend;     /* range of the action to use */
643
644         float repeat;               /* The number of times to repeat the action range (only when no F-Curves) */
645         float scale;                /* The amount the action range is scaled by (only when no F-Curves) */
646
647         float blendin, blendout;    /* strip blending length (only used when there are no F-Curves) */
648         short blendmode;            /* strip blending mode (layer-based mixing) */
649
650         short extendmode;           /* strip extrapolation mode (time-based mixing) */
651         short pad1;
652
653         short type;                 /* type of NLA strip */
654
655         void *speaker_handle;       /* handle for speaker objects */
656
657         int flag;                   /* settings */
658         int pad2;
659 } NlaStrip;
660
661 /* NLA Strip Blending Mode */
662 typedef enum eNlaStrip_Blend_Mode {
663         NLASTRIP_MODE_REPLACE = 0,
664         NLASTRIP_MODE_ADD,
665         NLASTRIP_MODE_SUBTRACT,
666         NLASTRIP_MODE_MULTIPLY
667 } eNlaStrip_Blend_Mode;
668
669 /* NLA Strip Extrpolation Mode */
670 typedef enum eNlaStrip_Extrapolate_Mode {
671         /* extend before first frame if no previous strips in track,
672          * and always hold+extend last frame */
673         NLASTRIP_EXTEND_HOLD = 0,
674         /* only hold+extend last frame */
675         NLASTRIP_EXTEND_HOLD_FORWARD = 1,
676         /* don't contribute at all */
677         NLASTRIP_EXTEND_NOTHING = 2,
678 } eNlaStrip_Extrapolate_Mode;
679
680 /* NLA Strip Settings */
681 typedef enum eNlaStrip_Flag {
682         /* UI selection flags */
683                 /* NLA strip is the active one in the track (also indicates if strip is being tweaked) */
684         NLASTRIP_FLAG_ACTIVE        = (1<<0),
685                 /* NLA strip is selected for editing */
686         NLASTRIP_FLAG_SELECT        = (1<<1),
687 //  NLASTRIP_FLAG_SELECT_L      = (1<<2),   // left handle selected
688 //  NLASTRIP_FLAG_SELECT_R      = (1<<3),   // right handle selected
689
690         /* NLA strip uses the same action that the action being tweaked uses
691          * (not set for the twaking one though) */
692         NLASTRIP_FLAG_TWEAKUSER     = (1<<4),
693
694         /* controls driven by local F-Curves */
695                 /* strip influence is controlled by local F-Curve */
696         NLASTRIP_FLAG_USR_INFLUENCE = (1<<5),
697         NLASTRIP_FLAG_USR_TIME      = (1<<6),
698         NLASTRIP_FLAG_USR_TIME_CYCLIC = (1<<7),
699
700                 /* NLA strip length is synced to the length of the referenced action */
701         NLASTRIP_FLAG_SYNC_LENGTH   = (1<<9),
702
703         /* playback flags (may be overridden by F-Curves) */
704                 /* NLA strip blendin/out values are set automatically based on overlaps */
705         NLASTRIP_FLAG_AUTO_BLENDS   = (1<<10),
706                 /* NLA strip is played back in reverse order */
707         NLASTRIP_FLAG_REVERSE       = (1<<11),
708                 /* NLA strip is muted (i.e. doesn't contribute in any way) */
709         NLASTRIP_FLAG_MUTED         = (1<<12),
710                 /* NLA Strip is played back in 'ping-pong' style */
711         NLASTRIP_FLAG_MIRROR        = (1<<13),
712
713         /* temporary editing flags */
714                 /* NLA-Strip is really just a temporary meta used to facilitate easier transform code */
715         NLASTRIP_FLAG_TEMP_META     = (1<<30),
716         NLASTRIP_FLAG_EDIT_TOUCHED  = (1u << 31),
717 } eNlaStrip_Flag;
718
719 /* NLA Strip Type */
720 typedef enum eNlaStrip_Type {
721                 /* 'clip' - references an Action */
722         NLASTRIP_TYPE_CLIP      = 0,
723                 /* 'transition' - blends between the adjacent strips */
724         NLASTRIP_TYPE_TRANSITION,
725                 /* 'meta' - a strip which acts as a container for a few others */
726         NLASTRIP_TYPE_META,
727
728                 /* 'emit sound' - a strip which is used for timing when speaker emits sounds */
729         NLASTRIP_TYPE_SOUND
730 } eNlaStrip_Type;
731
732 /* NLA Tracks ------------------------------------- */
733
734 /* NLA Track (nlt)
735  *
736  * A track groups a bunch of 'strips', which should form a continuous set of
737  * motion, on top of which other such groups can be layered. This should allow
738  * for animators to work in a non-destructive manner, layering tweaks, etc. over
739  * 'rough' blocks of their work.
740  */
741 typedef struct NlaTrack {
742         struct NlaTrack *next, *prev;
743
744         ListBase strips;                /* bActionStrips in this track */
745
746         int flag;                               /* settings for this track */
747         int index;                              /* index of the track in the stack (NOTE: not really useful, but we need a pad var anyways!) */
748
749         char name[64];                  /* short user-description of this track - MAX_ID_NAME-2 */
750 } NlaTrack;
751
752 /* settings for track */
753 typedef enum eNlaTrack_Flag {
754         /** track is the one that settings can be modified on,
755          * also indicates if track is being 'tweaked' */
756         NLATRACK_ACTIVE         = (1<<0),
757         /** track is selected in UI for relevant editing operations */
758         NLATRACK_SELECTED       = (1<<1),
759         /** track is not evaluated */
760         NLATRACK_MUTED          = (1<<2),
761         /** track is the only one evaluated (must be used in conjunction with adt->flag) */
762         NLATRACK_SOLO           = (1<<3),
763         /** track's settings (and strips) cannot be edited (to guard against unwanted changes) */
764         NLATRACK_PROTECTED      = (1<<4),
765
766         /** track is not allowed to execute,
767          * usually as result of tweaking being enabled (internal flag) */
768         NLATRACK_DISABLED       = (1<<10),
769 } eNlaTrack_Flag;
770
771
772 /* ************************************ */
773 /* KeyingSet Datatypes */
774
775 /* Path for use in KeyingSet definitions (ksp)
776  *
777  * Paths may be either specific (specifying the exact sub-ID
778  * dynamic data-block - such as PoseChannels - to act upon, ala
779  * Maya's 'Character Sets' and XSI's 'Marking Sets'), or they may
780  * be generic (using various placeholder template tags that will be
781  * replaced with appropriate information from the context).
782  */
783 typedef struct KS_Path {
784         struct KS_Path *next, *prev;
785
786         ID *id;                                 /* ID block that keyframes are for */
787         char group[64];                 /* name of the group to add to - MAX_ID_NAME-2 */
788
789         int idtype;                             /* ID-type that path can be used on */
790
791         short groupmode;                /* group naming (eKSP_Grouping) */
792         short flag;                             /* various settings, etc. */
793
794         char *rna_path;                 /* dynamically (or statically in the case of predefined sets) path */
795         int array_index;                /* index that path affects */
796
797         short keyingflag;               /* (eInsertKeyFlags) settings to supply insertkey() with */
798         short keyingoverride;   /* (eInsertKeyFlags) for each flag set, the relevant keyingflag bit overrides the default */
799 } KS_Path;
800
801 /* KS_Path->flag */
802 typedef enum eKSP_Settings {
803                 /* entire array (not just the specified index) gets keyframed */
804         KSP_FLAG_WHOLE_ARRAY    = (1<<0),
805 } eKSP_Settings;
806
807 /* KS_Path->groupmode */
808 typedef enum eKSP_Grouping {
809                 /* path should be grouped using group name stored in path */
810         KSP_GROUP_NAMED = 0,
811                 /* path should not be grouped at all */
812         KSP_GROUP_NONE,
813                 /* path should be grouped using KeyingSet's name */
814         KSP_GROUP_KSNAME,
815                 /* path should be grouped using name of inner-most context item from templates
816                  * - this is most useful for relative KeyingSets only
817                  */
818         KSP_GROUP_TEMPLATE_ITEM
819 } eKSP_Grouping;
820
821 /* ---------------- */
822
823 /* KeyingSet definition (ks)
824  *
825  * A KeyingSet defines a group of properties that should
826  * be keyframed together, providing a convenient way for animators
827  * to insert keyframes without resorting to Auto-Keyframing.
828  *
829  * A few 'generic' (non-absolute and dependent on templates) KeyingSets
830  * are defined 'built-in' to facilitate easy animating for the casual
831  * animator without the need to add extra steps to the rigging process.
832  */
833 typedef struct KeyingSet {
834         struct KeyingSet *next, *prev;
835
836         ListBase paths;                 /* (KS_Path) paths to keyframe to */
837
838         char idname[64];                /* unique name (for search, etc.) - MAX_ID_NAME-2  */
839         char name[64];                  /* user-viewable name for KeyingSet (for menus, etc.) - MAX_ID_NAME-2 */
840         char description[240];  /* (RNA_DYN_DESCR_MAX) short help text. */
841         char typeinfo[64];              /* name of the typeinfo data used for the relative paths - MAX_ID_NAME-2 */
842
843         int active_path;                /* index of the active path */
844
845         short flag;                             /* settings for KeyingSet */
846
847         short keyingflag;               /* (eInsertKeyFlags) settings to supply insertkey() with */
848         short keyingoverride;   /* (eInsertKeyFlags) for each flag set, the relevant keyingflag bit overrides the default */
849
850         char pad[6];
851 } KeyingSet;
852
853 /* KeyingSet settings */
854 typedef enum eKS_Settings {
855                 /* keyingset cannot be removed (and doesn't need to be freed) */
856         KEYINGSET_BUILTIN               = (1<<0),
857                 /* keyingset does not depend on context info (i.e. paths are absolute) */
858         KEYINGSET_ABSOLUTE              = (1<<1),
859 } eKS_Settings;
860
861 /* Flags for use by keyframe creation/deletion calls */
862 typedef enum eInsertKeyFlags {
863         INSERTKEY_NOFLAGS       = 0,
864         /** only insert keyframes where they're needed */
865         INSERTKEY_NEEDED        = (1<<0),
866         /** insert 'visual' keyframes where possible/needed */
867         INSERTKEY_MATRIX        = (1<<1),
868         /** don't recalculate handles,etc. after adding key */
869         INSERTKEY_FAST          = (1<<2),
870         /** don't realloc mem (or increase count, as array has already been set out) */
871         INSERTKEY_FASTR         = (1<<3),
872         /** only replace an existing keyframe (this overrides INSERTKEY_NEEDED) */
873         INSERTKEY_REPLACE       = (1<<4),
874         /** transform F-Curves should have XYZ->RGB color mode */
875         INSERTKEY_XYZ2RGB       = (1<<5),
876         /** ignore user-prefs (needed for predictable API use) */
877         INSERTKEY_NO_USERPREF   = (1<<6),
878         /** Allow to make a full copy of new key into existing one, if any,
879          * instead of 'reusing' existing handles.
880          * Used by copy/paste code. */
881         INSERTKEY_OVERWRITE_FULL = (1<<7),
882         INSERTKEY_DRIVER         = (1<<8),      /* for driver FCurves, use driver's "input" value - for easier corrective driver setup */
883 } eInsertKeyFlags;
884
885 /* ************************************************ */
886 /* Animation Data */
887
888 /* AnimOverride ------------------------------------- */
889
890 /* Animation Override (aor)
891  *
892  * This is used to as temporary storage of values which have been changed by the user, but not
893  * yet keyframed (thus, would get overwritten by the animation system before the user had a chance
894  * to see the changes that were made).
895  *
896  * It is probably not needed for overriding keyframed values in most cases, as those will only get
897  * evaluated on frame-change now. That situation may change in future.
898  */
899 typedef struct AnimOverride {
900         struct AnimOverride *next, *prev;
901
902         char *rna_path;                 /* RNA-path to use to resolve data-access */
903         int array_index;                /* if applicable, the index of the RNA-array item to get */
904
905         float value;                    /* value to override setting with */
906 } AnimOverride;
907
908 /* AnimData ------------------------------------- */
909
910 /* Animation data for some ID block (adt)
911  *
912  * This block of data is used to provide all of the necessary animation data for a datablock.
913  * Currently, this data will not be reusable, as there shouldn't be any need to do so.
914  *
915  * This information should be made available for most if not all ID-blocks, which should
916  * enable all of its settings to be animatable locally. Animation from 'higher-up' ID-AnimData
917  * blocks may override local settings.
918  *
919  * This datablock should be placed immediately after the ID block where it is used, so that
920  * the code which retrieves this data can do so in an easier manner.
921  * See blenkernel/intern/anim_sys.c for details.
922  */
923 typedef struct AnimData {
924         /** active action - acts as the 'tweaking track' for the NLA */
925         bAction     *action;
926         /** temp-storage for the 'real' active action (i.e. the one used before the tweaking-action
927          * took over to be edited in the Animation Editors)
928          */
929         bAction     *tmpact;
930                 /* remapping-info for active action - should only be used if needed
931                  * (for 'foreign' actions that aren't working correctly)
932                  */
933         AnimMapper  *remap;
934
935                 /* nla-tracks */
936         ListBase    nla_tracks;
937                 /* active NLA-track (only set/used during tweaking, so no need to worry about dangling pointers) */
938         NlaTrack        *act_track;
939                 /* active NLA-strip (only set/used during tweaking, so no need to worry about dangling pointers) */
940         NlaStrip    *actstrip;
941
942         /* 'drivers' for this ID-block's settings - FCurves, but are completely
943          * separate from those for animation data
944          */
945         ListBase    drivers;    /* standard user-created Drivers/Expressions (used as part of a rig) */
946         ListBase    overrides;  /* temp storage (AnimOverride) of values for settings that are animated (but the value hasn't been keyframed) */
947
948                 /* settings for animation evaluation */
949         int flag;               /* user-defined settings */
950         int recalc;             /* depsgraph recalculation flags */
951
952                 /* settings for active action evaluation (based on NLA strip settings) */
953         short act_blendmode;    /* accumulation mode for active action */
954         short act_extendmode;   /* extrapolation mode for active action */
955         float act_influence;    /* influence for active action */
956 } AnimData;
957
958 /* Animation Data settings (mostly for NLA) */
959 typedef enum eAnimData_Flag {
960                 /* only evaluate a single track in the NLA */
961         ADT_NLA_SOLO_TRACK      = (1<<0),
962                 /* don't use NLA */
963         ADT_NLA_EVAL_OFF        = (1<<1),
964                 /* NLA is being 'tweaked' (i.e. in EditMode) */
965         ADT_NLA_EDIT_ON         = (1<<2),
966                 /* active Action for 'tweaking' does not have mapping applied for editing */
967         ADT_NLA_EDIT_NOMAP      = (1<<3),
968                 /* NLA-Strip F-Curves are expanded in UI */
969         ADT_NLA_SKEYS_COLLAPSED = (1<<4),
970
971                 /* drivers expanded in UI */
972         ADT_DRIVERS_COLLAPSED   = (1<<10),
973                 /* don't execute drivers */
974         ADT_DRIVERS_DISABLED    = (1<<11),
975
976                 /* AnimData block is selected in UI */
977         ADT_UI_SELECTED         = (1<<14),
978                 /* AnimData block is active in UI */
979         ADT_UI_ACTIVE           = (1<<15),
980
981                 /* F-Curves from this AnimData block are not visible in the Graph Editor */
982         ADT_CURVES_NOT_VISIBLE  = (1<<16),
983
984                 /* F-Curves from this AnimData block are always visible */
985         ADT_CURVES_ALWAYS_VISIBLE = (1<<17),
986 } eAnimData_Flag;
987
988 /* Animation Data recalculation settings (to be set by depsgraph) */
989 typedef enum eAnimData_Recalc {
990         ADT_RECALC_DRIVERS      = (1 << 0),
991         ADT_RECALC_ANIM         = (1 << 1),
992         ADT_RECALC_ALL          = (ADT_RECALC_DRIVERS | ADT_RECALC_ANIM),
993 } eAnimData_Recalc;
994
995 /* Base Struct for Anim ------------------------------------- */
996
997 /* Used for BKE_animdata_from_id()
998  * All ID-datablocks which have their own 'local' AnimData
999  * should have the same arrangement in their structs.
1000  */
1001 typedef struct IdAdtTemplate {
1002         ID id;
1003         AnimData *adt;
1004 } IdAdtTemplate;
1005
1006 /* ************************************************ */
1007
1008 #ifdef __cplusplus
1009 };
1010 #endif
1011
1012 #endif /* __DNA_ANIM_TYPES_H__ */