Cleanup: remove redundant doxygen \file argument
[blender.git] / source / blender / blenkernel / BKE_fcurve.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 #ifndef __BKE_FCURVE_H__
21 #define __BKE_FCURVE_H__
22
23 /** \file \ingroup bke
24  */
25
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29
30 struct ChannelDriver;
31 struct DriverTarget;
32 struct DriverVar;
33 struct FCM_EnvelopeData;
34 struct FCurve;
35 struct FModifier;
36
37 struct AnimData;
38 struct BezTriple;
39 struct PathResolvedRNA;
40 struct PointerRNA;
41 struct PropertyRNA;
42 struct StructRNA;
43 struct bAction;
44 struct bContext;
45
46 #include "DNA_curve_types.h"
47
48 /* ************** Keyframe Tools ***************** */
49
50 typedef struct CfraElem {
51         struct CfraElem *next, *prev;
52         float cfra;
53         int sel;
54 } CfraElem;
55
56 void bezt_add_to_cfra_elem(ListBase *lb, struct BezTriple *bezt);
57
58 /* ************** F-Curve Drivers ***************** */
59
60 /* With these iterators for convenience, the variables "tarIndex" and "dtar" can be
61  * accessed directly from the code using them, but it is not recommended that their
62  * values be changed to point at other slots...
63  */
64
65 /* convenience looper over ALL driver targets for a given variable (even the unused ones) */
66 #define DRIVER_TARGETS_LOOPER_BEGIN(dvar) \
67         { \
68                 DriverTarget *dtar = &dvar->targets[0]; \
69                 int tarIndex = 0; \
70                 for (; tarIndex < MAX_DRIVER_TARGETS; tarIndex++, dtar++)
71
72 /* convenience looper over USED driver targets only */
73 #define DRIVER_TARGETS_USED_LOOPER_BEGIN(dvar) \
74         { \
75                 DriverTarget *dtar = &dvar->targets[0]; \
76                 int tarIndex = 0; \
77                 for (; tarIndex < dvar->num_targets; tarIndex++, dtar++)
78
79 /* tidy up for driver targets loopers */
80 #define DRIVER_TARGETS_LOOPER_END \
81 } ((void)0)
82
83 /* ---------------------- */
84
85 void fcurve_free_driver(struct FCurve *fcu);
86 struct ChannelDriver *fcurve_copy_driver(const struct ChannelDriver *driver);
87
88 void driver_variables_copy(struct ListBase *dst_list, const struct ListBase *src_list);
89
90 void driver_free_variable(struct ListBase *variables, struct DriverVar *dvar);
91 void driver_free_variable_ex(struct ChannelDriver *driver, struct DriverVar *dvar);
92
93 void driver_change_variable_type(struct DriverVar *dvar, int type);
94 void driver_variable_name_validate(struct DriverVar *dvar);
95 struct DriverVar *driver_add_new_variable(struct ChannelDriver *driver);
96
97 float driver_get_variable_value(struct ChannelDriver *driver, struct DriverVar *dvar);
98 bool  driver_get_variable_property(
99         struct ChannelDriver *driver, struct DriverTarget *dtar,
100         struct PointerRNA *r_ptr, struct PropertyRNA **r_prop, int *r_index);
101
102 bool BKE_driver_has_simple_expression(struct ChannelDriver *driver);
103 void BKE_driver_invalidate_expression(struct ChannelDriver *driver, bool expr_changed, bool varname_changed);
104
105 float evaluate_driver(struct PathResolvedRNA *anim_rna, struct ChannelDriver *driver,
106                       struct ChannelDriver *driver_orig, const float evaltime);
107
108 /* ************** F-Curve Modifiers *************** */
109
110 typedef struct GHash FModifierStackStorage;
111
112 /* F-Curve Modifier Type-Info (fmi):
113  *  This struct provides function pointers for runtime, so that functions can be
114  *  written more generally (with fewer/no special exceptions for various modifiers).
115  *
116  *  Callers of these functions must check that they actually point to something useful,
117  *  as some constraints don't define some of these.
118  *
119  *  Warning: it is not too advisable to reorder order of members of this struct,
120  *           as you'll have to edit quite a few ($FMODIFIER_NUM_TYPES) of these
121  *           structs.
122  */
123 typedef struct FModifierTypeInfo {
124         /* admin/ident */
125         short type;             /* FMODIFIER_TYPE_### */
126         short size;             /* size in bytes of the struct */
127         short acttype;          /* eFMI_Action_Types */
128         short requires;         /* eFMI_Requirement_Flags */
129         char  name[64];          /* name of modifier in interface */
130         char  structName[64];    /* name of struct for SDNA */
131
132         /* data management function pointers - special handling */
133         /* free any data that is allocated separately (optional) */
134         void (*free_data)(struct FModifier *fcm);
135         /* copy any special data that is allocated separately (optional) */
136         void (*copy_data)(struct FModifier *fcm, const struct FModifier *src);
137         /* set settings for data that will be used for FCuModifier.data (memory already allocated using MEM_callocN) */
138         void (*new_data)(void *mdata);
139         /* verifies that the modifier settings are valid */
140         void (*verify_data)(struct FModifier *fcm);
141
142         /* evaluation */
143         /* evaluate time that the modifier requires the F-Curve to be evaluated at */
144         float (*evaluate_modifier_time)(struct FCurve *fcu, struct FModifier *fcm, float cvalue, float evaltime);
145         /* evaluate the modifier for the given time and 'accumulated' value */
146         void (*evaluate_modifier)(struct FCurve *fcu, struct FModifier *fcm, float *cvalue, float evaltime);
147
148         /* Same as above but for modifiers which requires storage */
149         float (*evaluate_modifier_time_storage)(FModifierStackStorage *storage, struct FCurve *fcu, struct FModifier *fcm, float cvalue, float evaltime);
150         void (*evaluate_modifier_storage)(FModifierStackStorage *storage, struct FCurve *fcu, struct FModifier *fcm, float *cvalue, float evaltime);
151 } FModifierTypeInfo;
152
153 /* Values which describe the behavior of a FModifier Type */
154 typedef enum eFMI_Action_Types {
155         /* modifier only modifies values outside of data range */
156         FMI_TYPE_EXTRAPOLATION = 0,
157         /* modifier leaves data-points alone, but adjusts the interpolation between and around them */
158         FMI_TYPE_INTERPOLATION,
159         /* modifier only modifies the values of points (but times stay the same) */
160         FMI_TYPE_REPLACE_VALUES,
161         /* modifier generates a curve regardless of what came before */
162         FMI_TYPE_GENERATE_CURVE
163 } eFMI_Action_Types;
164
165 /* Flags for the requirements of a FModifier Type */
166 typedef enum eFMI_Requirement_Flags {
167         /* modifier requires original data-points (kindof beats the purpose of a modifier stack?) */
168         FMI_REQUIRES_ORIGINAL_DATA      = (1 << 0),
169         /* modifier doesn't require on any preceding data (i.e. it will generate a curve).
170          * Use in conjunction with FMI_TYPE_GENRATE_CURVE
171          */
172         FMI_REQUIRES_NOTHING            = (1 << 1),
173         /* refer to modifier instance */
174         FMI_REQUIRES_RUNTIME_CHECK      = (1 << 2),
175
176         /* Requires to store data shared between time and valua evaluation */
177         FMI_REQUIRES_STORAGE            = (1 << 3),
178 } eFMI_Requirement_Flags;
179
180 /* Function Prototypes for FModifierTypeInfo's */
181 const FModifierTypeInfo *fmodifier_get_typeinfo(const struct FModifier *fcm);
182 const FModifierTypeInfo *get_fmodifier_typeinfo(const int type);
183
184 /* ---------------------- */
185
186 struct FModifier *add_fmodifier(ListBase *modifiers, int type, struct FCurve *owner_fcu);
187 struct FModifier *copy_fmodifier(const struct FModifier *src);
188 void copy_fmodifiers(ListBase *dst, const ListBase *src);
189 bool remove_fmodifier(ListBase *modifiers, struct FModifier *fcm);
190 void free_fmodifiers(ListBase *modifiers);
191
192 struct FModifier *find_active_fmodifier(ListBase *modifiers);
193 void set_active_fmodifier(ListBase *modifiers, struct FModifier *fcm);
194
195 bool list_has_suitable_fmodifier(ListBase *modifiers, int mtype, short acttype);
196
197 FModifierStackStorage *evaluate_fmodifiers_storage_new(ListBase *modifiers);
198 void evaluate_fmodifiers_storage_free(FModifierStackStorage *storage);
199 float evaluate_time_fmodifiers(FModifierStackStorage *storage, ListBase *modifiers, struct FCurve *fcu, float cvalue, float evaltime);
200 void evaluate_value_fmodifiers(FModifierStackStorage *storage, ListBase *modifiers, struct FCurve *fcu, float *cvalue, float evaltime);
201
202 void fcurve_bake_modifiers(struct FCurve *fcu, int start, int end);
203
204 int BKE_fcm_envelope_find_index(struct FCM_EnvelopeData *array, float frame, int arraylen, bool *r_exists);
205
206 /* ************** F-Curves API ******************** */
207
208 /* threshold for binary-searching keyframes - threshold here should be good enough for now, but should become userpref */
209 #define BEZT_BINARYSEARCH_THRESH   0.01f /* was 0.00001, but giving errors */
210
211 /* -------- Data Management  --------  */
212
213 void free_fcurve(struct FCurve *fcu);
214 struct FCurve *copy_fcurve(const struct FCurve *fcu);
215
216 void free_fcurves(ListBase *list);
217 void copy_fcurves(ListBase *dst, ListBase *src);
218
219 /* find matching F-Curve in the given list of F-Curves */
220 struct FCurve *list_find_fcurve(ListBase *list, const char rna_path[], const int array_index);
221
222 struct FCurve *iter_step_fcurve(struct FCurve *fcu_iter, const char rna_path[]);
223
224 /* high level function to get an fcurve from C without having the rna */
225 struct FCurve *id_data_find_fcurve(ID *id, void *data, struct StructRNA *type, const char *prop_name, int index, bool *r_driven);
226
227 /* Get list of LinkData's containing pointers to the F-Curves which control the types of data indicated
228  * e.g.  numMatches = list_find_data_fcurves(matches, &act->curves, "pose.bones[", "MyFancyBone");
229  */
230 int list_find_data_fcurves(ListBase *dst, ListBase *src, const char *dataPrefix, const char *dataName);
231
232 /* Find an f-curve based on an rna property. */
233 struct FCurve *rna_get_fcurve(
234         struct PointerRNA *ptr, struct PropertyRNA *prop, int rnaindex,
235         struct AnimData **r_adt, struct bAction **r_action,
236         bool *r_driven, bool *r_special);
237 /* Same as above, but takes a context data, temp hack needed for complex paths like texture ones. */
238 struct FCurve *rna_get_fcurve_context_ui(
239         struct bContext *C, struct PointerRNA *ptr, struct PropertyRNA *prop, int rnaindex,
240         struct AnimData **r_adt, struct bAction **r_action, bool *r_driven, bool *r_special);
241
242 /* Binary search algorithm for finding where to 'insert' BezTriple with given frame number.
243  * Returns the index to insert at (data already at that index will be offset if replace is 0)
244  */
245 int binarysearch_bezt_index(struct BezTriple array[], float frame, int arraylen, bool *r_replace);
246
247 /* get the time extents for F-Curve */
248 bool calc_fcurve_range(struct FCurve *fcu, float *min, float *max,
249                        const bool do_sel_only, const bool do_min_length);
250
251 /* get the bounding-box extents for F-Curve */
252 bool calc_fcurve_bounds(struct FCurve *fcu, float *xmin, float *xmax, float *ymin, float *ymax,
253                         const bool do_sel_only, const bool include_handles);
254
255 /* .............. */
256
257 /* Are keyframes on F-Curve of any use (to final result, and to show in editors)? */
258 bool fcurve_are_keyframes_usable(struct FCurve *fcu);
259
260 /* Can keyframes be added to F-Curve? */
261 bool fcurve_is_keyframable(struct FCurve *fcu);
262 bool BKE_fcurve_is_protected(struct FCurve *fcu);
263
264 /* The curve is an infinite cycle via Cycles modifier */
265 bool BKE_fcurve_is_cyclic(struct FCurve *fcu);
266
267 /* Type of infinite cycle for a curve. */
268 typedef enum eFCU_Cycle_Type {
269         FCU_CYCLE_NONE = 0,
270         /* The cycle repeats identically to the base range. */
271         FCU_CYCLE_PERFECT,
272         /* The cycle accumulates the change between start and end keys. */
273         FCU_CYCLE_OFFSET
274 } eFCU_Cycle_Type;
275
276 eFCU_Cycle_Type BKE_fcurve_get_cycle_type(struct FCurve *fcu);
277
278 /* -------- Curve Sanity --------  */
279
280 void calchandles_fcurve(struct FCurve *fcu);
281 void testhandles_fcurve(struct FCurve *fcu, const bool use_handle);
282 void sort_time_fcurve(struct FCurve *fcu);
283 short test_time_fcurve(struct FCurve *fcu);
284
285 void correct_bezpart(float v1[2], float v2[2], float v3[2], float v4[2]);
286
287 /* -------- Evaluation --------  */
288
289 /* evaluate fcurve */
290 float evaluate_fcurve(struct FCurve *fcu, float evaltime);
291 float evaluate_fcurve_only_curve(struct FCurve *fcu, float evaltime);
292 float evaluate_fcurve_driver(struct PathResolvedRNA *anim_rna, struct FCurve *fcu,
293                              struct ChannelDriver *driver_orig, float evaltime);
294 /* evaluate fcurve and store value */
295 float calculate_fcurve(struct PathResolvedRNA *anim_rna, struct FCurve *fcu, float evaltime);
296
297 /* ************* F-Curve Samples API ******************** */
298
299 /* -------- Defines --------  */
300
301 /* Basic signature for F-Curve sample-creation function
302  * - fcu: the F-Curve being operated on
303  * - data: pointer to some specific data that may be used by one of the callbacks
304  */
305 typedef float (*FcuSampleFunc)(struct FCurve *fcu, void *data, float evaltime);
306
307 /* ----- Sampling Callbacks ------  */
308
309 /* Basic sampling callback which acts as a wrapper for evaluate_fcurve() */
310 float fcurve_samplingcb_evalcurve(struct FCurve *fcu, void *data, float evaltime);
311
312 /* -------- Main Methods --------  */
313
314 /* Main API function for creating a set of sampled curve data, given some callback function
315  * used to retrieve the values to store.
316  */
317 void fcurve_store_samples(struct FCurve *fcu, void *data, int start, int end, FcuSampleFunc sample_cb);
318
319 #ifdef __cplusplus
320 }
321 #endif
322
323 #endif /* __BKE_FCURVE_H__*/