BKE_fcurve.hh

Go to the documentation of this file.

/* SPDX-FileCopyrightText: 2024 Blender Authors
 *
 * SPDX-License-Identifier: GPL-2.0-or-later */
 
#pragma once

 
#include "BLI_math_vector_types.hh"
#include "BLI_span.hh"
#include "BLI_string_ref.hh"
 
#include "DNA_curve_types.h"
 
struct ChannelDriver;
struct FCM_EnvelopeData;
struct FCurve;
struct FModifier;
struct FCurvePathCache;
 
struct AnimData;
struct AnimationEvalContext;
struct BezTriple;
struct BlendDataReader;
struct BlendWriter;
struct LibraryForeachIDData;
struct PathResolvedRNA;
struct PointerRNA;
struct PropertyRNA;
struct StructRNA;
struct bAction;
struct bContext;
 
/* ************** F-Curve Modifiers *************** */

struct FModifierTypeInfo {
  /* Admin/identity. */
  short type;
  short size;
  short acttype;
  short requires_flag;
  char name[64];
  char struct_name[64];
  uint storage_size;
 
  /* data management function pointers - special handling */
  void (*free_data)(FModifier *fcm);
  void (*copy_data)(FModifier *fcm, const FModifier *src);
  void (*new_data)(void *mdata);
  void (*verify_data)(FModifier *fcm);
 
  /* evaluation */
  float (*evaluate_modifier_time)(
      const FCurve *fcu, const FModifier *fcm, float cvalue, float evaltime, void *storage);
  void (*evaluate_modifier)(
      const FCurve *fcu, const FModifier *fcm, float *cvalue, float evaltime, void *storage);
};
 
/* Values which describe the behavior of a FModifier Type */
enum eFMI_Action_Types {
  /* modifier only modifies values outside of data range */
  FMI_TYPE_EXTRAPOLATION = 0,
  /* modifier leaves data-points alone, but adjusts the interpolation between and around them */
  FMI_TYPE_INTERPOLATION,
  /* modifier only modifies the values of points (but times stay the same) */
  FMI_TYPE_REPLACE_VALUES,
  /* modifier generates a curve regardless of what came before */
  FMI_TYPE_GENERATE_CURVE,
};
 
/* Flags for the requirements of a FModifier Type */
enum eFMI_Requirement_Flags {
  /* modifier requires original data-points (kind of beats the purpose of a modifier stack?) */
  FMI_REQUIRES_ORIGINAL_DATA = (1 << 0),
  /* modifier doesn't require on any preceding data (i.e. it will generate a curve).
   * Use in conjunction with FMI_TYPE_GENRATE_CURVE
   */
  FMI_REQUIRES_NOTHING = (1 << 1),
  /* refer to modifier instance */
  FMI_REQUIRES_RUNTIME_CHECK = (1 << 2),
};
 
/* Function Prototypes for FModifierTypeInfo's */

const FModifierTypeInfo *fmodifier_get_typeinfo(const FModifier *fcm);
const FModifierTypeInfo *get_fmodifier_typeinfo(int type);
 
/* ---------------------- */

FModifier *add_fmodifier(ListBase *modifiers, int type, FCurve *owner_fcu);
FModifier *copy_fmodifier(const FModifier *src);
void copy_fmodifiers(ListBase *dst, const ListBase *src);
bool remove_fmodifier(ListBase *modifiers, FModifier *fcm);
void free_fmodifiers(ListBase *modifiers);

FModifier *find_active_fmodifier(ListBase *modifiers);
void set_active_fmodifier(ListBase *modifiers, FModifier *fcm);

bool list_has_suitable_fmodifier(const ListBase *modifiers, int mtype, short acttype);
 
struct FModifiersStackStorage {
  uint modifier_count;
  uint size_per_modifier;
  void *buffer;
};
 
uint evaluate_fmodifiers_storage_size_per_modifier(const ListBase *modifiers);
float evaluate_time_fmodifiers(FModifiersStackStorage *storage,
                               const ListBase *modifiers,
                               const FCurve *fcu,
                               float cvalue,
                               float evaltime);
void evaluate_value_fmodifiers(FModifiersStackStorage *storage,
                               const ListBase *modifiers,
                               const FCurve *fcu,
                               float *cvalue,
                               float evaltime);

void fcurve_bake_modifiers(FCurve *fcu, int start, int end);
 
int BKE_fcm_envelope_find_index(FCM_EnvelopeData *array,
                                float frame,
                                int arraylen,
                                bool *r_exists);
 
/* ************** F-Curves API ******************** */
 
/* threshold for binary-searching keyframes - threshold here should be good enough for now,
 * but should become userpref */
#define BEZT_BINARYSEARCH_THRESH 0.01f /* was 0.00001, but giving errors */
 
/* -------- Data Management  -------- */
FCurve *BKE_fcurve_create();
void BKE_fcurve_free(FCurve *fcu);
FCurve *BKE_fcurve_copy(const FCurve *fcu);
void BKE_fcurves_free(ListBase *list);
void BKE_fcurves_copy(ListBase *dst, ListBase *src);

void BKE_fcurve_rnapath_set(FCurve &fcu, blender::StringRef rna_path);
 
/* Set fcurve modifier name and ensure uniqueness.
 * Pass new name string when it's been edited otherwise pass empty string. */
void BKE_fmodifier_name_set(FModifier *fcm, const char *name);

void BKE_fcurve_foreach_id(FCurve *fcu, LibraryForeachIDData *data);

FCurve *BKE_fcurve_find(ListBase *list, const char rna_path[], int array_index);

FCurve *BKE_fcurve_iter_step(FCurve *fcu_iter, const char rna_path[]);

FCurve *id_data_find_fcurve(
    ID *id, void *data, StructRNA *type, const char *prop_name, int index, bool *r_driven);

FCurve *BKE_animadata_fcurve_find_by_rna_path(AnimData *animdata,
                                              const char *rna_path,
                                              const int rna_index,
                                              bAction **r_action,
                                              bool *r_driven);

FCurve *BKE_fcurve_find_by_rna(PointerRNA *ptr,
                               PropertyRNA *prop,
                               int rnaindex,
                               AnimData **r_adt,
                               bAction **r_action,
                               bool *r_driven,
                               bool *r_special);
FCurve *BKE_fcurve_find_by_rna_context_ui(bContext *C,
                                          const PointerRNA *ptr,
                                          PropertyRNA *prop,
                                          int rnaindex,
                                          AnimData **r_animdata,
                                          bAction **r_action,
                                          bool *r_driven,
                                          bool *r_special);

int BKE_fcurve_bezt_binarysearch_index(const BezTriple array[],
                                       float frame,
                                       int arraylen,
                                       bool *r_replace);
 
/* `fcurve_cache.cc` */

FCurvePathCache *BKE_fcurve_pathcache_create(blender::Span<FCurve *> fcurves);
void BKE_fcurve_pathcache_destroy(FCurvePathCache *fcache);
FCurve *BKE_fcurve_pathcache_find(const FCurvePathCache *fcache,
                                  const char rna_path[],
                                  int array_index);
int BKE_fcurve_pathcache_find_array(const FCurvePathCache *fcache,
                                    const char *rna_path,
                                    FCurve **fcurve_result,
                                    int fcurve_result_len);

bool BKE_fcurve_calc_range(const FCurve *fcu, float *r_min, float *r_max, bool selected_keys_only);

bool BKE_fcurve_calc_bounds(const FCurve *fcu,
                            bool selected_keys_only,
                            bool include_handles,
                            const float frame_range[2],
                            rctf *r_bounds);

float *BKE_fcurves_calc_keyed_frames_ex(FCurve **fcurve_array,
                                        int fcurve_array_len,
                                        float interval,
                                        int *r_frames_len);
float *BKE_fcurves_calc_keyed_frames(FCurve **fcurve_array,
                                     int fcurve_array_len,
                                     int *r_frames_len);

void BKE_fcurve_active_keyframe_set(FCurve *fcu, const BezTriple *active_bezt);
int BKE_fcurve_active_keyframe_index(const FCurve *fcu);

void BKE_fcurve_keyframe_move_time_with_handles(BezTriple *keyframe, const float new_time);
void BKE_fcurve_keyframe_move_value_with_handles(BezTriple *keyframe, float new_value);
 
/* .............. */

bool BKE_fcurve_are_keyframes_usable(const FCurve *fcu);

bool BKE_fcurve_is_keyframable(const FCurve *fcu);
bool BKE_fcurve_is_protected(const FCurve *fcu);

bool BKE_fcurve_has_selected_control_points(const FCurve *fcu);

void BKE_fcurve_deselect_all_keys(FCurve &fcu);

bool BKE_fcurve_is_cyclic(const FCurve *fcu);
 
/* Type of infinite cycle for a curve. */
enum eFCU_Cycle_Type {
  FCU_CYCLE_NONE = 0,
  /* The cycle repeats identically to the base range. */
  FCU_CYCLE_PERFECT,
  /* The cycle accumulates the change between start and end keys. */
  FCU_CYCLE_OFFSET,
};

eFCU_Cycle_Type BKE_fcurve_get_cycle_type(const FCurve *fcu);

bool BKE_fcurve_bezt_subdivide_handles(BezTriple *bezt,
                                       BezTriple *prev,
                                       BezTriple *next,
                                       float *r_pdelta);

void BKE_fcurve_bezt_resize(FCurve *fcu, int new_totvert);

BezTriple *BKE_bezier_array_merge(
    const BezTriple *a, int size_a, const BezTriple *b, int size_b, int *r_merged_size);

void BKE_fcurve_delete_key(FCurve *fcu, int index);

void BKE_fcurve_delete_keys(FCurve *fcu, blender::uint2 index_range);

bool BKE_fcurve_delete_keys_selected(FCurve *fcu);

void BKE_fcurve_delete_keys_all(FCurve *fcu);

void BKE_fcurve_merge_duplicate_keys(FCurve *fcu, const int sel_flag, const bool use_handle);

void BKE_fcurve_deduplicate_keys(FCurve *fcu);
 
/* -------- Curve Sanity -------- */

void BKE_fcurve_handles_recalc(FCurve *fcu);
void BKE_fcurve_handles_recalc_ex(FCurve *fcu, eBezTriple_Flag handle_sel_flag);
void testhandles_fcurve(FCurve *fcu, eBezTriple_Flag sel_flag, bool use_handle);
void sort_time_fcurve(FCurve *fcu);
bool test_time_fcurve(FCurve *fcu);

void BKE_fcurve_correct_bezpart(const float v1[2], float v2[2], float v3[2], const float v4[2]);
 
/* -------- Evaluation -------- */
 
/* evaluate fcurve */
float evaluate_fcurve(const FCurve *fcu, float evaltime);
float evaluate_fcurve_only_curve(const FCurve *fcu, float evaltime);
float evaluate_fcurve_driver(PathResolvedRNA *anim_rna,
                             FCurve *fcu,
                             ChannelDriver *driver_orig,
                             const AnimationEvalContext *anim_eval_context);
bool BKE_fcurve_is_empty(const FCurve *fcu);
float calculate_fcurve(PathResolvedRNA *anim_rna,
                       FCurve *fcu,
                       const AnimationEvalContext *anim_eval_context);
 
/* ************* F-Curve Samples API ******************** */
 
/* -------- Defines -------- */

typedef float (*FcuSampleFunc)(FCurve *fcu, void *data, float evaltime);
 
/* ----- Sampling Callbacks ------ */

float fcurve_samplingcb_evalcurve(FCurve *fcu, void *data, float evaltime);
 
/* -------- Main Methods -------- */

void fcurve_store_samples(FCurve *fcu, void *data, int start, int end, FcuSampleFunc sample_cb);

void fcurve_samples_to_keyframes(FCurve *fcu, int start, int end);
 
/* ************* F-Curve .blend file API ******************** */
 
void BKE_fmodifiers_blend_write(BlendWriter *writer, ListBase *fmodifiers);
void BKE_fmodifiers_blend_read_data(BlendDataReader *reader, ListBase *fmodifiers, FCurve *curve);

void BKE_fcurve_blend_write_data(BlendWriter *writer, FCurve *fcu);
void BKE_fcurve_blend_write_listbase(BlendWriter *writer, ListBase *fcurves);
void BKE_fcurve_blend_read_data(BlendDataReader *reader, FCurve *fcu);
void BKE_fcurve_blend_read_data_listbase(BlendDataReader *reader, ListBase *fcurves);