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