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