ED_keyframes_edit.hh

Go to the documentation of this file.

/* SPDX-FileCopyrightText: 2008 Blender Authors
 *
 * SPDX-License-Identifier: GPL-2.0-or-later */

 
#pragma once
 
#include "BLI_array.hh"
#include "BLI_math_vector_types.hh"
 
#include "ED_anim_api.hh" /* for enum eAnimFilter_Flags */
 
#include "DNA_curve_types.h"
 
struct BezTriple;
struct ButterworthCoefficients;
struct FCurve;
struct Scene;
struct bAnimContext;
struct bAnimListElem;
struct bDopeSheet;
 
/* ************************************************ */
/* Common Macros and Defines */
 
/* -------------------------------------------------------------------- */

enum eEditKeyframes_Validate {
  /* Frame range */
  BEZT_OK_FRAME = 1,
  BEZT_OK_FRAMERANGE,
  /* Selection status (any of f1, f2, f3)  */
  BEZT_OK_SELECTED,
  /* Selection status (f2 is enough) */
  BEZT_OK_SELECTED_KEY,
  /* Values (y-val) only */
  BEZT_OK_VALUE,
  BEZT_OK_VALUERANGE,
  /* For graph editor keyframes (2D tests) */
  BEZT_OK_REGION,
  BEZT_OK_REGION_LASSO,
  BEZT_OK_REGION_CIRCLE,
  /* Only for keyframes a certain Dope-sheet channel. */
  BEZT_OK_CHANNEL_LASSO,
  BEZT_OK_CHANNEL_CIRCLE,
};

 
/* select modes */
enum eEditKeyframes_Select {
  /* SELECT_SUBTRACT for all, followed by SELECT_ADD for some */
  SELECT_REPLACE = (1 << 0),
  /* add ok keyframes to selection */
  SELECT_ADD = (1 << 1),
  /* remove ok keyframes from selection */
  SELECT_SUBTRACT = (1 << 2),
  /* flip ok status of keyframes based on key status */
  SELECT_INVERT = (1 << 3),
  SELECT_EXTEND_RANGE = (1 << 4),
};
 
/* "selection map" building modes. */
enum eEditKeyframes_SelMap {
  SELMAP_MORE = 0,
  SELMAP_LESS,
};
 
/* snapping tools */
enum eEditKeyframes_Snap {
  SNAP_KEYS_CURFRAME = 1,
  SNAP_KEYS_NEARFRAME,
  SNAP_KEYS_NEARSEC,
  SNAP_KEYS_NEARMARKER,
  SNAP_KEYS_HORIZONTAL,
  SNAP_KEYS_VALUE,
  SNAP_KEYS_TIME,
};
 
/* equalizing tools */
enum eEditKeyframes_Equalize {
  EQUALIZE_HANDLES_LEFT = (1 << 0),
  EQUALIZE_HANDLES_RIGHT = (1 << 1),
  EQUALIZE_HANDLES_BOTH = (EQUALIZE_HANDLES_LEFT | EQUALIZE_HANDLES_RIGHT),
};
 
/* mirroring tools */
enum eEditKeyframes_Mirror {
  MIRROR_KEYS_CURFRAME = 1,
  MIRROR_KEYS_YAXIS,
  MIRROR_KEYS_XAXIS,
  MIRROR_KEYS_MARKER,
  MIRROR_KEYS_VALUE,
  MIRROR_KEYS_TIME,
};
 
/* use with BEZT_OK_REGION_LASSO */
struct KeyframeEdit_LassoData {
  rctf *rectf_scaled;
  const rctf *rectf_view;
  blender::Array<blender::int2> mcoords;
};
 
/* use with BEZT_OK_REGION_CIRCLE */
struct KeyframeEdit_CircleData {
  rctf *rectf_scaled;
  const rctf *rectf_view;
  float mval[2];
  float radius_squared;
};
 
/* ************************************************ */
/* Non-Destructive Editing API (keyframes_edit.cc) */
 
/* -------------------------------------------------------------------- */
 
/* which verts of a keyframe is active (after polling) */
enum eKeyframeVertOk {
  KEYFRAME_NONE = 0,
  /* 'key' itself is ok */
  KEYFRAME_OK_KEY = (1 << 0),
  /* 'handle 1' is ok */
  KEYFRAME_OK_H1 = (1 << 1),
  /* 'handle 2' is ok */
  KEYFRAME_OK_H2 = (1 << 2),
  /* all flags */
  KEYFRAME_OK_ALL = (KEYFRAME_OK_KEY | KEYFRAME_OK_H1 | KEYFRAME_OK_H2),
};
 
/* Flags for use during iteration */
enum eKeyframeIterFlags {
  /* Consider handles in addition to key itself. Used in #keyframe_ok_checks, #select_bezier_add,
   * #select_bezier_subtract. If set, treat key and handles separately (e.g (de)select them
   * individually, and do additional visibility checks on the handles if necessary), otherwise
   * always treat key and handles the same (e.g. (de)select all of them).
   */
  KEYFRAME_ITER_INCL_HANDLES = (1 << 0),
 
  /* Perform NLA time remapping (global -> strip) for the "f1" parameter
   * (e.g. used for selection tools on summary tracks)
   */
  KED_F1_NLA_UNMAP = (1 << 1),
 
  /* Perform NLA time remapping (global -> strip) for the "f2" parameter */
  KED_F2_NLA_UNMAP = (1 << 2),
 
  /* Set this when handles aren't visible by default and you want to perform additional checks to
   * get the actual visibility state. E.g. in some cases handles are only drawn if either a handle
   * or their control point is selected. The selection state will have to be checked in the
   * iterator callbacks then. */
  /* Represents "Only Selected Keyframes" option (SIPO_SELVHANDLESONLY). */
  KEYFRAME_ITER_HANDLES_DEFAULT_INVISIBLE = (1 << 3),
 
  /* Represents "Show Handles" option (SIPO_NOHANDLES). */
  KEYFRAME_ITER_HANDLES_INVISIBLE = (1 << 4),
};
ENUM_OPERATORS(eKeyframeIterFlags, KEYFRAME_ITER_HANDLES_DEFAULT_INVISIBLE)
 

 
/* -------------------------------------------------------------------- */
 

struct CfraElem {
  CfraElem *next, *prev;
  /* Expected to be in global scene time (e.g. not NLA unmapped). */
  float cfra;
  int sel;
};
 
struct KeyframeEditData {
  /* generic properties/data access */
  ListBase list;
  Scene *scene;
  void *data;
  float f1, f2;
  int i1, i2;
 
  /* current iteration data */
  FCurve *fcu;
  int curIndex;
  float channel_y;
 
  /* flags */
  eKeyframeVertOk curflags;
  eKeyframeIterFlags iterflags;
};

 
/* -------------------------------------------------------------------- */

using FcuEditFunc = void (*)(FCurve *fcu);
using KeyframeEditFunc = short (*)(KeyframeEditData *ked, BezTriple *bezt);

 
/* -------------------------------------------------------------------- */

struct KeyframeEditCD_Remap {
  float oldMin, oldMax; /* old range */
  float newMin, newMax; /* new range */
};

enum eKeyPasteOffset {
  KEYFRAME_PASTE_OFFSET_CFRA_START,
  KEYFRAME_PASTE_OFFSET_CFRA_END,
  KEYFRAME_PASTE_OFFSET_CFRA_RELATIVE,
  KEYFRAME_PASTE_OFFSET_NONE,
};
 
enum eKeyPasteValueOffset {
  KEYFRAME_PASTE_VALUE_OFFSET_LEFT_KEY,
  KEYFRAME_PASTE_VALUE_OFFSET_RIGHT_KEY,
  KEYFRAME_PASTE_VALUE_OFFSET_CFRA,
  KEYFRAME_PASTE_VALUE_OFFSET_CURSOR,
  KEYFRAME_PASTE_VALUE_OFFSET_NONE,
};
 
enum eKeyMergeMode {
  KEYFRAME_PASTE_MERGE_MIX,
  KEYFRAME_PASTE_MERGE_OVER,
  KEYFRAME_PASTE_MERGE_OVER_RANGE,
  KEYFRAME_PASTE_MERGE_OVER_RANGE_ALL,
};

enum eKeyPasteError {
  KEYFRAME_PASTE_OK,
  KEYFRAME_PASTE_NOTHING_TO_PASTE,
  KEYFRAME_PASTE_NOWHERE_TO_PASTE
};

 
/* -------------------------------------------------------------------- */

short ANIM_fcurve_keyframes_loop(KeyframeEditData *ked,
                                 FCurve *fcu,
                                 KeyframeEditFunc key_ok,
                                 KeyframeEditFunc key_cb,
                                 FcuEditFunc fcu_cb);
void ANIM_fcurve_equalize_keyframes_loop(FCurve *fcu,
                                         eEditKeyframes_Equalize mode,
                                         float handle_length,
                                         bool flatten);

short ANIM_animchannel_keyframes_loop(KeyframeEditData *ked,
                                      bDopeSheet *ads,
                                      bAnimListElem *ale,
                                      KeyframeEditFunc key_ok,
                                      KeyframeEditFunc key_cb,
                                      FcuEditFunc fcu_cb);
short ANIM_animchanneldata_keyframes_loop(KeyframeEditData *ked,
                                          bDopeSheet *ads,
                                          void *data,
                                          int keytype,
                                          KeyframeEditFunc key_ok,
                                          KeyframeEditFunc key_cb,
                                          FcuEditFunc fcu_cb);

void ANIM_animdata_keyframe_callback(bAnimContext *ac,
                                     eAnimFilter_Flags filter,
                                     KeyframeEditFunc callback_fn);

void ANIM_editkeyframes_refresh(bAnimContext *ac);

 
/* -------------------------------------------------------------------- */
 
/* accessories */
KeyframeEditFunc ANIM_editkeyframes_ok(short mode);
 
/* edit */
KeyframeEditFunc ANIM_editkeyframes_snap(short mode);
KeyframeEditFunc ANIM_editkeyframes_mirror(short mode);
KeyframeEditFunc ANIM_editkeyframes_select(eEditKeyframes_Select selectmode);
KeyframeEditFunc ANIM_editkeyframes_handles(short mode);
KeyframeEditFunc ANIM_editkeyframes_ipo(short mode);
KeyframeEditFunc ANIM_editkeyframes_keytype(eBezTriple_KeyframeType keyframe_type);
KeyframeEditFunc ANIM_editkeyframes_easing(short mode);

 
/* -------------------------------------------------------------------- */

KeyframeEditFunc ANIM_editkeyframes_buildselmap(short mode);

short bezt_selmap_flush(KeyframeEditData *ked, BezTriple *bezt);

 
/* -------------------------------------------------------------------- */

short bezt_calc_average(KeyframeEditData *ked, BezTriple *bezt);

short bezt_to_cfraelem(KeyframeEditData *ked, BezTriple *bezt);

void bezt_remap_times(KeyframeEditData *ked, BezTriple *bezt);

 
/* -------------------------------------------------------------------- */
 
/* XXX: These are temporary,
 * until we can unify GP/Mask Keyframe handling and standard FCurve Keyframe handling */
 
bool keyframe_region_lasso_test(const KeyframeEdit_LassoData *data_lasso, const float xy[2]);
 
bool keyframe_region_circle_test(const KeyframeEdit_CircleData *data_circle, const float xy[2]);
 
/* ************************************************ */
/* Destructive Editing API `keyframes_general.cc`. */
 
bool duplicate_fcurve_keys(FCurve *fcu);
float get_default_rna_value(const FCurve *fcu, PropertyRNA *prop, PointerRNA *ptr);
 
struct FCurveSegment {
  FCurveSegment *next, *prev;
  int start_index, length;
};

ListBase find_fcurve_segments(FCurve *fcu);
void clean_fcurve(bAnimListElem *ale, float thresh, bool cleardefault, bool only_selected_keys);
void blend_to_neighbor_fcurve_segment(FCurve *fcu, FCurveSegment *segment, float factor);
void breakdown_fcurve_segment(FCurve *fcu, FCurveSegment *segment, float factor);
void scale_average_fcurve_segment(FCurve *fcu, FCurveSegment *segment, float factor);
void push_pull_fcurve_segment(FCurve *fcu, FCurveSegment *segment, float factor);
enum class FCurveSegmentAnchor { LEFT, RIGHT };
void scale_from_fcurve_segment_neighbor(FCurve *fcu,
                                        FCurveSegment *segment,
                                        float factor,
                                        FCurveSegmentAnchor anchor);
void ED_ANIM_get_1d_gauss_kernel(const float sigma, int kernel_size, double *r_kernel);
 
ButterworthCoefficients *ED_anim_allocate_butterworth_coefficients(const int filter_order);
void ED_anim_free_butterworth_coefficients(ButterworthCoefficients *bw_coeff);
void ED_anim_calculate_butterworth_coefficients(float cutoff_frequency,
                                                float sampling_frequency,
                                                ButterworthCoefficients *bw_coeff);
void butterworth_smooth_fcurve_segment(FCurve *fcu,
                                       FCurveSegment *segment,
                                       float *samples,
                                       int sample_count,
                                       float factor,
                                       int blend_in_out,
                                       int sample_rate,
                                       ButterworthCoefficients *bw_coeff);
void smooth_fcurve_segment(FCurve *fcu,
                           FCurveSegment *segment,
                           const float *original_values,
                           float *samples,
                           const int sample_count,
                           float factor,
                           int kernel_size,
                           const double *kernel);
void ease_fcurve_segment(FCurve *fcu, FCurveSegment *segment, float factor, float width);
 
enum tShearDirection {
  SHEAR_FROM_LEFT = 1,
  SHEAR_FROM_RIGHT,
};
void shear_fcurve_segment(FCurve *fcu,
                          FCurveSegment *segment,
                          float factor,
                          tShearDirection direction);
void blend_offset_fcurve_segment(FCurve *fcu, FCurveSegment *segment, float factor);
void blend_to_ease_fcurve_segment(FCurve *fcu, FCurveSegment *segment, float factor);
void time_offset_fcurve_segment(FCurve *fcu, FCurveSegment *segment, float frame_offset);
bool decimate_fcurve(bAnimListElem *ale, float remove_ratio, float error_sq_max);
bool match_slope_fcurve_segment(FCurve *fcu, FCurveSegment *segment, float factor);

void blend_to_default_fcurve(PointerRNA *id_ptr, FCurve *fcu, float factor);
void smooth_fcurve(FCurve *fcu);
 
/* ----------- */

void ANIM_fcurves_copybuf_reset();

void ANIM_fcurves_copybuf_free();

bool copy_animedit_keys(bAnimContext *ac, ListBase *anim_data);
 
struct KeyframePasteContext {
  eKeyPasteOffset offset_mode;
  eKeyPasteValueOffset value_offset_mode;
  eKeyMergeMode merge_mode;
  bool flip;
 
  int num_slots_selected;   /* Number of selected Action Slots to paste into. */
  int num_fcurves_selected; /* Number of selected F-Curves to paste into. */
};
 
eKeyPasteError paste_animedit_keys(bAnimContext *ac,
                                   ListBase *anim_data,
                                   const KeyframePasteContext &paste_context);
 
/* ************************************************ */