2 libanim - hierarchical keyframe animation library
3 Copyright (C) 2012-2023 John Tsiombikas <nuclear@member.fsf.org>
5 This program is free software: you can redistribute it and/or modify
6 it under the terms of the GNU Lesser General Public License as published
7 by the Free Software Foundation, either version 3 of the License, or
8 (at your option) any later version.
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU Lesser General Public License for more details.
15 You should have received a copy of the GNU Lesser General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
19 /* An animation track defines the values of a single scalar over time
20 * and supports various interpolation and extrapolation modes.
22 #ifndef LIBANIM_TRACK_H_
23 #define LIBANIM_TRACK_H_
26 /*#include "config.h"*/
28 enum anm_interpolator {
34 enum anm_extrapolator {
35 ANM_EXTRAP_EXTEND, /* extend to infinity */
36 ANM_EXTRAP_CLAMP, /* clamp to last value */
37 ANM_EXTRAP_REPEAT, /* repeat motion */
38 ANM_EXTRAP_PINGPONG /* repeat with mirroring */
41 typedef long anm_time_t;
42 #define ANM_TIME_MIN LONG_MIN
43 #define ANM_TIME_MAX LONG_MAX
44 #define ANM_TIME_INVAL LONG_MIN
46 #define ANM_SEC2TM(x) ((anm_time_t)((x) * 1000))
47 #define ANM_MSEC2TM(x) ((anm_time_t)(x))
48 #define ANM_TM2SEC(x) ((x) / 1000.0)
49 #define ANM_TM2MSEC(x) (x)
59 struct anm_keyframe *keys;
63 enum anm_interpolator interp;
64 enum anm_extrapolator extrap;
73 /* track constructor and destructor */
74 int anm_init_track(struct anm_track *track);
75 void anm_destroy_track(struct anm_track *track);
77 /* helper functions that use anm_init_track and anm_destroy_track internally */
78 struct anm_track *anm_create_track(void);
79 void anm_free_track(struct anm_track *track);
81 /* copies track src to dest
82 * XXX: dest must have been initialized first
84 void anm_copy_track(struct anm_track *dest, const struct anm_track *src);
86 int anm_set_track_name(struct anm_track *track, const char *name);
87 const char *anm_get_track_name(const struct anm_track *track);
89 void anm_set_track_interpolator(struct anm_track *track, enum anm_interpolator in);
90 void anm_set_track_extrapolator(struct anm_track *track, enum anm_extrapolator ex);
92 anm_time_t anm_remap_time(const struct anm_track *track, anm_time_t tm,
93 anm_time_t start, anm_time_t end);
95 void anm_set_track_default(struct anm_track *track, float def);
97 /* set or update a keyframe */
98 int anm_set_keyframe(struct anm_track *track, struct anm_keyframe *key);
100 /* get the idx-th keyframe, returns null if it doesn't exist */
101 struct anm_keyframe *anm_get_keyframe(const struct anm_track *track, int idx);
103 /* Finds the 0-based index of the intra-keyframe interval which corresponds
104 * to the specified time. If the time falls exactly onto the N-th keyframe
105 * the function returns N.
108 * - if the time is before the first keyframe -1 is returned.
109 * - if the time is after the last keyframe, the index of the last keyframe
112 int anm_get_key_interval(const struct anm_track *track, anm_time_t tm);
114 int anm_set_value(struct anm_track *track, anm_time_t tm, float val);
116 /* evaluates and returns the value of the track for a particular time */
117 float anm_get_value(const struct anm_track *track, anm_time_t tm);
119 /* evaluates a set of 4 tracks treated as a quaternion, to perform slerp instead
120 * of linear interpolation. Result is returned through the last argument, which
121 * is expected to point to an array of 4 floats (x,y,z,w)
123 void anm_get_quat(const struct anm_track *xtrk, const struct anm_track *ytrk,
124 const struct anm_track *ztrk, const struct anm_track *wtrk, anm_time_t tm, float *qres);
131 #endif /* LIBANIM_TRACK_H_ */