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