Panda3D
animInterface.I
1 // Filename: animInterface.I
2 // Created by: drose (20Sep05)
3 //
4 ////////////////////////////////////////////////////////////////////
5 //
6 // PANDA 3D SOFTWARE
7 // Copyright (c) Carnegie Mellon University. All rights reserved.
8 //
9 // All use of this software is subject to the terms of the revised BSD
10 // license. You should have received a copy of this license along
11 // with this source code in a file named "LICENSE."
12 //
13 ////////////////////////////////////////////////////////////////////
14 
15 
16 ////////////////////////////////////////////////////////////////////
17 // Function: AnimInterface::play
18 // Access: Published
19 // Description: Runs the entire animation from beginning to end and
20 // stops.
21 ////////////////////////////////////////////////////////////////////
22 INLINE void AnimInterface::
23 play() {
24  play(0, get_num_frames() - 1);
25 }
26 
27 ////////////////////////////////////////////////////////////////////
28 // Function: AnimInterface::play
29 // Access: Published
30 // Description: Runs the animation from the frame "from" to and
31 // including the frame "to", at which point the
32 // animation is stopped. Both "from" and "to" frame
33 // numbers may be outside the range (0,
34 // get_num_frames()) and the animation will follow the
35 // range correctly, reporting numbers modulo
36 // get_num_frames(). For instance, play(0,
37 // get_num_frames() * 2) will play the animation twice
38 // and then stop.
39 ////////////////////////////////////////////////////////////////////
40 INLINE void AnimInterface::
41 play(double from, double to) {
42  {
43  CDWriter cdata(_cycler);
44  cdata->play(from, to);
45  }
46  animation_activated();
47 }
48 
49 ////////////////////////////////////////////////////////////////////
50 // Function: AnimInterface::loop
51 // Access: Published
52 // Description: Starts the entire animation looping. If restart is
53 // true, the animation is restarted from the beginning;
54 // otherwise, it continues from the current frame.
55 ////////////////////////////////////////////////////////////////////
56 INLINE void AnimInterface::
57 loop(bool restart) {
58  loop(restart, 0, get_num_frames() - 1);
59 }
60 
61 ////////////////////////////////////////////////////////////////////
62 // Function: AnimInterface::loop
63 // Access: Published
64 // Description: Loops the animation from the frame "from" to and
65 // including the frame "to", indefinitely. If restart
66 // is true, the animation is restarted from the
67 // beginning; otherwise, it continues from the current
68 // frame.
69 ////////////////////////////////////////////////////////////////////
70 INLINE void AnimInterface::
71 loop(bool restart, double from, double to) {
72  {
73  CDWriter cdata(_cycler);
74  cdata->loop(restart, from, to);
75  }
76  animation_activated();
77 }
78 
79 ////////////////////////////////////////////////////////////////////
80 // Function: AnimInterface::pingpong
81 // Access: Published
82 // Description: Starts the entire animation bouncing back and forth
83 // between its first frame and last frame. If restart
84 // is true, the animation is restarted from the
85 // beginning; otherwise, it continues from the current
86 // frame.
87 ////////////////////////////////////////////////////////////////////
88 INLINE void AnimInterface::
89 pingpong(bool restart) {
90  pingpong(restart, 0, get_num_frames() - 1);
91 }
92 
93 ////////////////////////////////////////////////////////////////////
94 // Function: AnimInterface::pingpong
95 // Access: Published
96 // Description: Loops the animation from the frame "from" to and
97 // including the frame "to", and then back in the
98 // opposite direction, indefinitely.
99 ////////////////////////////////////////////////////////////////////
100 INLINE void AnimInterface::
101 pingpong(bool restart, double from, double to) {
102  {
103  CDWriter cdata(_cycler);
104  cdata->pingpong(restart, from, to);
105  }
106  animation_activated();
107 }
108 
109 ////////////////////////////////////////////////////////////////////
110 // Function: AnimInterface::stop
111 // Access: Published
112 // Description: Stops a currently playing or looping animation right
113 // where it is. The animation remains posed at the
114 // current frame.
115 ////////////////////////////////////////////////////////////////////
116 INLINE void AnimInterface::
117 stop() {
118  CDWriter cdata(_cycler);
119  cdata->pose(cdata->get_full_fframe());
120 
121  // Don't call animation_activated() here; stopping an animation
122  // should not activate it.
123 }
124 
125 ////////////////////////////////////////////////////////////////////
126 // Function: AnimInterface::pose
127 // Access: Published
128 // Description: Sets the animation to the indicated frame and holds
129 // it there.
130 ////////////////////////////////////////////////////////////////////
131 INLINE void AnimInterface::
132 pose(double frame) {
133  {
134  CDWriter cdata(_cycler);
135  cdata->pose(frame);
136  }
137  animation_activated();
138 }
139 
140 ////////////////////////////////////////////////////////////////////
141 // Function: AnimInterface::set_play_rate
142 // Access: Published
143 // Description: Changes the rate at which the animation plays. 1.0
144 // is the normal speed, 2.0 is twice normal speed, and
145 // 0.5 is half normal speed. 0.0 is legal to pause the
146 // animation, and a negative value will play the
147 // animation backwards.
148 ////////////////////////////////////////////////////////////////////
149 INLINE void AnimInterface::
150 set_play_rate(double play_rate) {
151  CDWriter cdata(_cycler);
152  cdata->internal_set_rate(cdata->_frame_rate, play_rate);
153 }
154 
155 ////////////////////////////////////////////////////////////////////
156 // Function: AnimInterface::get_play_rate
157 // Access: Published
158 // Description: Returns the rate at which the animation plays. See
159 // set_play_rate().
160 ////////////////////////////////////////////////////////////////////
161 INLINE double AnimInterface::
162 get_play_rate() const {
163  CDReader cdata(_cycler);
164  return cdata->_play_rate;
165 }
166 
167 ////////////////////////////////////////////////////////////////////
168 // Function: AnimInterface::get_frame_rate
169 // Access: Published
170 // Description: Returns the native frame rate of the animation. This
171 // is the number of frames per second that will elapse
172 // when the play_rate is set to 1.0. It is a fixed
173 // property of the animation and may not be adjusted by
174 // the user.
175 ////////////////////////////////////////////////////////////////////
176 INLINE double AnimInterface::
177 get_frame_rate() const {
178  CDReader cdata(_cycler);
179  return cdata->_frame_rate;
180 }
181 
182 ////////////////////////////////////////////////////////////////////
183 // Function: AnimInterface::get_frame
184 // Access: Published
185 // Description: Returns the current integer frame number.
186 // This number will be in the range 0 <= f <
187 // get_num_frames().
188 ////////////////////////////////////////////////////////////////////
189 INLINE int AnimInterface::
190 get_frame() const {
191  int num_frames = get_num_frames();
192  if (num_frames <= 0) {
193  return 0;
194  }
195  CDReader cdata(_cycler);
196  return cmod(cdata->get_full_frame(0), num_frames);
197 }
198 
199 ////////////////////////////////////////////////////////////////////
200 // Function: AnimInterface::get_next_frame
201 // Access: Published
202 // Description: Returns the current integer frame number + 1,
203 // constrained to the range 0 <= f < get_num_frames().
204 //
205 // If the play mode is PM_play, this will clamp to the
206 // same value as get_frame() at the end of the
207 // animation. If the play mode is any other value, this
208 // will wrap around to frame 0 at the end of the
209 // animation.
210 ////////////////////////////////////////////////////////////////////
211 INLINE int AnimInterface::
212 get_next_frame() const {
213  int num_frames = get_num_frames();
214  if (num_frames <= 0) {
215  return 0;
216  }
217  CDReader cdata(_cycler);
218  return cmod(cdata->get_full_frame(1), num_frames);
219 }
220 
221 ////////////////////////////////////////////////////////////////////
222 // Function: AnimInterface::get_frac
223 // Access: Published
224 // Description: Returns the fractional part of the current frame.
225 // Normally, this is in the range 0.0 <= f < 1.0, but in
226 // the one special case of an animation playing to its
227 // end frame and stopping, it might exactly equal 1.0.
228 //
229 // It will always be true that get_full_frame() +
230 // get_frac() == get_full_fframe().
231 ////////////////////////////////////////////////////////////////////
232 INLINE double AnimInterface::
233 get_frac() const {
234  CDReader cdata(_cycler);
235  return cdata->get_frac();
236 }
237 
238 ////////////////////////////////////////////////////////////////////
239 // Function: AnimInterface::get_full_frame
240 // Access: Published
241 // Description: Returns the current integer frame number.
242 //
243 // Unlike the value returned by get_frame(), this frame
244 // number may extend beyond the range of
245 // get_num_frames() if the frame range passed to play(),
246 // loop(), etc. did.
247 //
248 // Unlike the value returned by get_full_fframe(), this
249 // return value will never exceed the value passed to
250 // to_frame in the play() method.
251 ////////////////////////////////////////////////////////////////////
252 INLINE int AnimInterface::
253 get_full_frame() const {
254  CDReader cdata(_cycler);
255  return cdata->get_full_frame(0);
256 }
257 
258 ////////////////////////////////////////////////////////////////////
259 // Function: AnimInterface::get_full_fframe
260 // Access: Published
261 // Description: Returns the current floating-point frame number.
262 //
263 // Unlike the value returned by get_frame(), this frame
264 // number may extend beyond the range of
265 // get_num_frames() if the frame range passed to play(),
266 // loop(), etc. did.
267 //
268 // Unlike the value returned by get_full_frame(), this
269 // return value may equal (to_frame + 1.0), when the
270 // animation has played to its natural end. However, in
271 // this case the return value of get_full_frame() will
272 // be to_frame, not (to_frame + 1).
273 ////////////////////////////////////////////////////////////////////
274 INLINE double AnimInterface::
276  CDReader cdata(_cycler);
277  return cdata->get_full_fframe();
278 }
279 
280 ////////////////////////////////////////////////////////////////////
281 // Function: AnimInterface::is_playing
282 // Access: Published
283 // Description: Returns true if the animation is currently playing,
284 // false if it is stopped (e.g. because stop() or pose()
285 // was called, or because it reached the end of the
286 // animation after play() was called).
287 ////////////////////////////////////////////////////////////////////
288 INLINE bool AnimInterface::
289 is_playing() const {
290  CDReader cdata(_cycler);
291  return cdata->is_playing();
292 }
293 
294 ////////////////////////////////////////////////////////////////////
295 // Function: AnimInterface::set_frame_rate
296 // Access: Protected
297 // Description: Should be called by a derived class to specify the
298 // native frame rate of the animation. It is legal to
299 // call this after the animation has already started.
300 ////////////////////////////////////////////////////////////////////
301 INLINE void AnimInterface::
302 set_frame_rate(double frame_rate) {
303  CDWriter cdata(_cycler);
304  cdata->internal_set_rate(frame_rate, cdata->_play_rate);
305 }
306 
307 ////////////////////////////////////////////////////////////////////
308 // Function: AnimInterface::set_num_frames
309 // Access: Protected
310 // Description: Should be called by a derived class to specify the
311 // number of frames of the animation. It is legal to
312 // call this after the animation has already started,
313 // but doing so may suddenly change the apparent current
314 // frame number.
315 ////////////////////////////////////////////////////////////////////
316 INLINE void AnimInterface::
317 set_num_frames(int num_frames) {
318  _num_frames = num_frames;
319 }
320 
321 ////////////////////////////////////////////////////////////////////
322 // Function: AnimInterface::CData::get_frac
323 // Access: Published
324 // Description: Returns the fractional part of the current frame.
325 // Normally, this is in the range 0.0 <= f < 1.0, but in
326 // the one special case of an animation playing to its
327 // end frame and stopping, it might exactly equal 1.0.
328 //
329 // It will always be true that get_full_frame() +
330 // get_frac() == get_full_fframe().
331 ////////////////////////////////////////////////////////////////////
332 INLINE double AnimInterface::CData::
333 get_frac() const {
334  return get_full_fframe() - (double)get_full_frame(0);
335 }
336 
337 INLINE ostream &
338 operator << (ostream &out, const AnimInterface &ai) {
339  ai.output(out);
340  return out;
341 }
double get_frame_rate() const
Returns the native frame rate of the animation.
int get_full_frame() const
Returns the current integer frame number.
bool is_playing() const
Returns true if the animation is currently playing, false if it is stopped (e.g.
void loop(bool restart)
Starts the entire animation looping.
Definition: animInterface.I:57
void pingpong(bool restart)
Starts the entire animation bouncing back and forth between its first frame and last frame...
Definition: animInterface.I:89
void stop()
Stops a currently playing or looping animation right where it is.
This is the fundamental interface for things that have a play/loop/stop type interface for frame-base...
Definition: animInterface.h:39
void set_play_rate(double play_rate)
Changes the rate at which the animation plays.
This template class calls PipelineCycler::read_unlocked(), and then provides a transparent read-only ...
double get_full_fframe() const
Returns the current floating-point frame number.
This template class calls PipelineCycler::write() in the constructor and PipelineCycler::release_writ...
int get_next_frame() const
Returns the current integer frame number + 1, constrained to the range 0 <= f < get_num_frames().
virtual int get_num_frames() const
Returns the number of frames in the animation.
void pose(double frame)
Sets the animation to the indicated frame and holds it there.
double get_play_rate() const
Returns the rate at which the animation plays.
void play()
Runs the entire animation from beginning to end and stops.
Definition: animInterface.I:23
int get_frame() const
Returns the current integer frame number.
double get_frac() const
Returns the fractional part of the current frame.