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