Adonthell  0.4
animation.h
Go to the documentation of this file.
1 /*
2  Copyright (C) 1999/2000/2001 Alexandre Courbot.
3  Part of the Adonthell Project <http://adonthell.nongnu.org>
4 
5  Adonthell is free software; you can redistribute it and/or modify
6  it under the terms of the GNU General Public License as published by
7  the Free Software Foundation; either version 2 of the License, or
8  (at your option) any later version.
9 
10  Adonthell 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 General Public License for more details.
14 
15  You should have received a copy of the GNU General Public License
16  along with Adonthell. If not, see <http://www.gnu.org/licenses/>.
17 */
18 
19 
20 /**
21  * @file animation.h
22  * @author Alexandre Courbot <alexandrecourbot@linuxgames.com>
23  *
24  * @brief Declares the animationframe and animation classes.
25  *
26  */
27 
28 
29 
30 #ifndef _ANIMATION_H
31 #define _ANIMATION_H
32 
33 
34 #include "image.h"
35 #include <vector>
36 
37 
38 /**
39  * Handles images properties in an animation.
40  * %Objects of this class have no reason to exist if not affected to an
41  * animation. The fact is, that often in an animation, you want the
42  * same image to appear at different times, different positions or with
43  * different mask and alpha values. An animationframe is a class that
44  * contains the index of the image to display, the alpha and mask parameters
45  * to give it, the time (in game cycles) it should be displayed before going
46  * to the next frame, and the index and the frame to display right after
47  * this one. As images and animationframes are arranged into an indexed array
48  * in an animation, the index values only make sense from the animation point
49  * of view.
50  *
51  */
53 {
54  public:
55 
56  /**
57  * Default constructor.
58  *
59  */
60  animationframe ();
61 
62  /**
63  * Destructor.
64  *
65  */
66  ~animationframe ();
67 
68  /**
69  * Resets an animationframe to it's initial (i.e post-constructor) state.
70  *
71  */
72  void clear ();
73 
74 
75  /**
76  * @name Mask and Alpha Settings.
77  *
78  */
79  //@{
80 
81  /**
82  * Returns whether this frame is masked or not.
83  *
84  *
85  * @return true if the surface is masked, false otherwise.
86  */
87  bool is_masked () const
88  {
89  return is_masked_;
90  }
91 
92  /**
93  * Sets the mask parameter of this frame.
94  *
95  * @param mask true if the surface should be masked, false otherwise.
96  */
97  void set_mask (bool mask)
98  {
99  is_masked_ = mask;
100  }
101 
102  /**
103  * Returns the alpha value the this frame.
104  *
105  *
106  * @return the alpha value of the frame.
107  */
108  u_int8 alpha () const
109  {
110  return alpha_;
111  }
112 
113  /**
114  * Sets the alpha value for this frame.
115  *
116  * @param a new alpha value.
117  */
118  void set_alpha (u_int8 a)
119  {
120  alpha_ = a;
121  }
122 
123  //@}
124 
125 
126  /**
127  * @name Image, delay and next frame settings.
128  *
129  */
130  //@{
131 
132  /**
133  * Returns the image number this frame points to.
134  *
135  *
136  * @return the index of the image this frame points to.
137  */
139  {
140  return imagenbr;
141  }
142 
143  /**
144  * Sets the image this frame should point to.
145  *
146  * @param imnbr the index of the image this frame should point to.
147  */
148  void set_image_nbr (u_int16 imnbr)
149  {
150  imagenbr = imnbr;
151  }
152 
153  /**
154  * Returns the duration of this frame.
155  *
156  *
157  * @return the delay (in game cycles) of this frame (0 means infinite).
158  */
159  u_int16 delay () const
160  {
161  return delay_;
162  }
163 
164  /**
165  * Sets the duration of this frame.
166  *
167  * @param d new delay (in game cycles, 0 means infinite).
168  */
170  {
171  delay_ = d;
172  }
173 
174  /**
175  * Returns the index of the frame that will be displayed once
176  * the delay of this one expired.
177  *
178  *
179  * @return the index of the frame next to this one.
180  */
182  {
183  return nextframe_;
184  }
185 
186  /**
187  * Sets the index of the frame that will be displayed right after
188  * this one.
189  *
190  * @param nf index of the frame that will be next to this one.
191  */
193  {
194  nextframe_ = nf;
195  }
196 
197  //@}
198 
199 
200  /**
201  * @name Individual frames relative position.
202  *
203  */
204  //@{
205 
206  /**
207  * Returns the X offset (i.e position relative to the animation's position)
208  * of this frame.
209  *
210  *
211  * @return the X offset of this frame.
212  */
213  u_int16 offx () const
214  {
215  return gapx;
216  }
217 
218  /**
219  * Returns the Y offset (i.e position relative to the animation's position)
220  * of this frame.
221  *
222  *
223  * @return the Y offset of this frame.
224  */
225  u_int16 offy () const
226  {
227  return gapy;
228  }
229 
230  /**
231  * Sets the offset for this frame.
232  *
233  * @param ox new X offset.
234  * @param ox new Y offset.
235  */
236  void set_offset (u_int16 ox, u_int16 oy)
237  {
238  gapx = ox;
239  gapy = oy;
240  }
241 
242  //@}
243 
244 
245  /**
246  * @name Saving/Loading Methods.
247  *
248  */
249  //@{
250 
251 
252  /**
253  * Loads an animationframe from an opened file.
254  *
255  * @param file the opened file from which to read.
256  *
257  * @return 0 in case of success, error number in case of error.
258  */
259  s_int8 get (igzstream& file);
260 
261  /**
262  * Saves an animationframe into an opened file.
263  *
264  * @param file the opened file where to save.
265  *
266  * @return 0 in case of success, error number in case of error.
267  */
268  s_int8 put (ogzstream& file) const;
269 
270 
271  //@}
272 
273 
274 private:
275  u_int16 imagenbr;
276  bool is_masked_;
277  u_int8 alpha_;
278  s_int16 gapx;
279  s_int16 gapy;
280  u_int16 delay_;
281  u_int16 nextframe_;
282 };
283 
284 
285 
286 /**
287  * Whether the animation is currently playing or not.
288  */
289 typedef enum { PLAY = true, STOP = false } play_state;
290 
291 
292 
293 /**
294  * Class that handles animated elements, their update and their playback.
295  * Most often, you will want your drawn %objects to be animated. Then you'll
296  * probably want to use this class. An animation contains:
297  * - A set of images arranged in an indexed array.
298  * - A set of animation_frames.
299  * - A global position offset.
300  *
301  * During playback, the animation look at the first animation_frame. Each
302  * animation_frame refers to an image of the animation, and give it special
303  * mask and alpha parameters, as well as a position offset. It also have
304  * a delay parameter, telling how many %game cycles this frame should stay.
305  * Once the delay expired, the animation jumps to the next frame, which
306  * is pointed by the current frame. That way, you can easily performs loops or
307  * others effects. Each image, as well as each animation_frame, can be accessed
308  * individually, thought you'd better try to avoid as much as possible to mess
309  * with that.
310  *
311  */
312 class animation : public drawable
313 {
314 public:
315 
316  /**
317  * Default constructor.
318  *
319  */
320  animation ();
321 
322  /**
323  * Destructor.
324  *
325  */
326  ~animation ();
327 
328 
329  /**
330  * Clears an animation, that is put it back into the original
331  * (constructor) state.
332  *
333  */
334  void clear ();
335 
336 
337  /**
338  * @name Playback control methods.
339  *
340  */
341  //@{
342 
343 
344  /**
345  * Starts the playback of the animation.
346  *
347  */
348  void play ()
349  {
350  play_flag = PLAY;
351 #ifdef _EDIT_
352  if (in_editor)
353  must_upt_label_status = true;
354 #endif
355  }
356 
357  /**
358  * Stops the playback of the animation.
359  *
360  */
361  void stop ()
362  {
363  play_flag = STOP;
364 #ifdef _EDIT_
365  if (in_editor)
366  must_upt_label_status = true;
367 #endif
368  }
369 
370  /**
371  * Returns whether the animation is currently being played.
372  *
373  *
374  * @return PLAY is the animation is currently playing, STOP otherwise.
375  */
377  {
378  return play_flag;
379  }
380 
381  /**
382  * Rewinds the animation to it's beginning.
383  *
384  */
385  void rewind ()
386  {
387  currentframe_ = 0;
388  speedcounter = 0;
389  }
390 
391 
392  /**
393  * Directly jumps to the next frame.
394  *
395  */
396  void next_frame ();
397 
398  //@}
399 
400 
401 
402  /**
403  * @name State updating Methods.
404  *
405  */
406  //@{
407 
408  /**
409  * Updates the animation state.
410  *
411  */
412  bool update ();
413 
414  //@}
415 
416 
417  /**
418  * @name Drawing Methods.
419  *
420  */
421  //@{
422 
423  void draw (s_int16 x, s_int16 y, const drawing_area * da_opt = NULL,
424  surface * target = NULL) const;
425 
426  //@}
427 
428 
429  /**
430  * @name Saving/Loading Methods.
431  * @note There is no way to save animations with this class.
432  *
433  */
434  //@{
435 
436  /**
437  * Loads an animation from an opened file.
438  * @param file the opened file from which to load.
439  * @return 0 in case of success, error code otherwise.
440  *
441  * @todo length and height are loaded while they are calculated later.
442  * Remove this when format will change.
443  *
444  */
445  s_int8 get (igzstream& file);
446 
447  /**
448  * Loads an animation from it's filename.
449  *
450  * @param fname the name of the file to load.
451  *
452  * @return 0 in case of success, error code otherwise.
453  */
454  s_int8 load (string fname);
455 
456 
457  /** Saves an animation into an opened file, in %game format, with
458  * alpha and mask values.
459  * @warning as the animation which is saved comes from a %screen's depth
460  * surface, it will be slightly altered during the save.
461  * If you want a class capable of saving animations with full
462  * truecolor quality, use animation_edit instead.
463  * @param file opened file where to save into.
464  * @return
465  * @li 0 in case of success.
466  * @li -1 in case of error.
467  * @sa save ()
468  */
469  s_int8 put (ogzstream& file) const;
470 
471  /** Saves an animation into an file, in %game format, with
472  * alpha and mask values.
473  * @warning as the animation which is saved comes from a %screen's depth
474  * surface, it will be slightly altered during the save.
475  * If you want a class capable of saving animations with full
476  * truecolor quality, use animation_edit instead.
477  * @param fname file name where to save into.
478  * @return
479  * @li 0 in case of success.
480  * @li -1 in case of error.
481  * @sa put ()
482  */
483  s_int8 save (string fname) const;
484 
485  //@}
486 
487 
488  /**
489  * @name Global animation properties Methods.
490  *
491  */
492  //@{
493 
494  /**
495  * Returns the number of frames in this animation.
496  *
497  *
498  * @return the number of frames in this animation.
499  */
501  {
502  return frame.size ();
503  }
504 
505  /**
506  * Returns the number of images in this animation.
507  *
508  *
509  * @return the number of images in this animation.
510  */
512  {
513  return t_frame.size ();
514  }
515 
516  /**
517  * Returns the index of the currently displayed frame.
518  *
519  *
520  * @return the index of the frame currently displayed.
521  */
523  {
524  return currentframe_;
525  }
526 
527  /**
528  * Sets the current frame.
529  *
530  * @param framenbr the index of the frame to display now.
531  */
532  void set_currentframe (u_int16 framenbr)
533  {
534  currentframe_ = framenbr;
535  speedcounter = 0;
536  }
537 
538  /**
539  * Returns the global X offset of the animation.
540  *
541  *
542  * @return the global X offset of the animation.
543  */
544  s_int16 xoffset () const
545  {
546  return xoffset_;
547  }
548 
549  /**
550  * Returns the global Y offset of the animation.
551  *
552  *
553  * @return the global Y offset of the animation.
554  */
555  s_int16 yoffset () const
556  {
557  return yoffset_;
558  }
559 
560  /**
561  * Set the global offsets of this animation.
562  *
563  * @param x new X global offset.
564  * @param y new Y global offset.
565  */
567  {
568  xoffset_ = x;
569  yoffset_ = y;
570  }
571 
572 
573  //@}
574 
575 
576 
577  /**
578  * @name Image and Animationframe control Methods.
579  *
580  */
581  //@{
582 
583  /**
584  * Returns a pointer to a desired frame.
585  *
586  * @param nbr the index of the frame to get.
587  *
588  * @return pointer to the nbr frame.
589  */
591  {
592  return &(frame[nbr]);
593  }
594 
595  /**
596  * Returns a pointer to a desired image.
597  *
598  * @param nbr the index of the image to get.
599  *
600  * @return pointer to the nbr image.
601  */
603  {
604  return t_frame[nbr];
605  }
606 
607  /**
608  * Inserts an image at a given position of the image array.
609  * All the frames will be updated so the operation doesn't affect
610  * the animation in any way.
611  *
612  * The animation will be responsible for freeing the inserted image.
613  *
614  * @param im pointer to the image to add.
615  * @param pos index where to add the image.
616  *
617  * @return 0 in case of success, error code otherwise.
618  */
619  s_int8 insert_image (const image * im, u_int16 pos);
620 
621 
622  /**
623  * Inserts a frame at a given position of the animationframe array.
624  * All the frames will be updated so the operation doesn't affect
625  * the animation in any way.
626  *
627  * @param af the animationframe to add.
628  * @param pos index where to add the frame.
629  *
630  * @return 0 in case of success, error code otherwise.
631  */
632  s_int8 insert_frame (const animationframe af, u_int16 pos);
633 
634  /**
635  * Removes an image at a given position.
636  * The image itself will also be deleted ().
637  * All the frames will be updated so the operation doesn't affect
638  * the animation in any way.
639  *
640  * @param pos The index of the image to remove.
641  *
642  * @return 0 in case of success, error code otherwise.
643  */
644  s_int8 delete_image (u_int16 pos);
645 
646  /**
647  * Removes a frame at a given position.
648  * All the frames will be updated so the operation doesn't affect
649  * the animation in any way.
650  *
651  * @param pos The index of the animationframe to remove.
652  *
653  * @return 0 in case of success, error code otherwise.
654  */
655  s_int8 delete_frame (u_int16 pos);
656 
657  //@}
658 
659  /**
660  * @name Special FX methods.
661  *
662  */
663  //@{
664 
665  /**
666  * Zooms an animation.
667  *
668  * @param sx Desired X size.
669  * @param sy Desired Y size.
670  * @param src Source animation to zoom.
671  */
672  void zoom (u_int16 sx, u_int16 sy, const animation * src);
673 
674  //@}
675 
676 #ifndef SWIG
677  /**
678  * Animation copy (similar to copy ()).
679  *
680  * @attention Not available from Python. Use copy () from Python instead.
681  * @sa copy ()
682  */
683  animation& operator = (const animation& src);
684 #endif
685 
686  /**
687  * Synonym of operator = to guarantee its access from Python.
688  *
689  * @sa operator =
690  */
691  void copy (const animation& src)
692  {
693  *this = src;
694  }
695 
696 
697 private:
698  /**
699  * Forbid value passing.
700  */
701  animation(const animation& src);
702 
703  /**
704  * Calculate the real dimensions of the animation, depending
705  * of it's frames and images.
706  *
707  */
708  void calculate_dimensions ();
709 
710  mutable vector <image *> t_frame;
711  mutable vector <animationframe> frame;
712  u_int16 currentframe_;
713  u_int16 speedcounter;
714  play_state play_flag;
715  s_int16 xoffset_, yoffset_;
716 
717 #ifndef SWIG
718  friend class win_anim;
719 #endif
720 };
721 
722 #endif
void set_image_nbr(u_int16 imnbr)
Sets the image this frame should point to.
Definition: animation.h:148
Class to write data from a Gzip compressed file.
Definition: fileops.h:227
Class to read data from a Gzip compressed file.
Definition: fileops.h:135
void stop()
Stops the playback of the animation.
Definition: animation.h:361
play_state
Whether the animation is currently playing or not.
Definition: animation.h:289
bool is_masked() const
Returns whether this frame is masked or not.
Definition: animation.h:87
void set_currentframe(u_int16 framenbr)
Sets the current frame.
Definition: animation.h:532
#define u_int16
16 bits long unsigned integer
Definition: types.h:38
~animationframe()
Destructor.
Definition: animation.cc:49
Class where drawables can actually be drawn to.
Definition: surface.h:85
u_int16 nextframe() const
Returns the index of the frame that will be displayed once the delay of this one expired.
Definition: animation.h:181
void clear()
Resets an animationframe to it&#39;s initial (i.e post-constructor) state.
Definition: animation.cc:53
Image manipulation class.
Definition: image.h:45
void set_offset(u_int16 ox, u_int16 oy)
Sets the offset for this frame.
Definition: animation.h:236
#define u_int8
8 bits long unsigned integer
Definition: types.h:35
s_int8 put(ogzstream &file) const
Saves an animationframe into an opened file.
Definition: animation.cc:78
void copy(const animation &src)
Synonym of operator = to guarantee its access from Python.
Definition: animation.h:691
u_int16 image_nbr() const
Returns the image number this frame points to.
Definition: animation.h:138
void set_delay(u_int16 d)
Sets the duration of this frame.
Definition: animation.h:169
Declares the image class.
u_int8 alpha() const
Returns the alpha value the this frame.
Definition: animation.h:108
u_int16 currentframe() const
Returns the index of the currently displayed frame.
Definition: animation.h:522
void rewind()
Rewinds the animation to it&#39;s beginning.
Definition: animation.h:385
Implements "drawing zones" for drawing operations.
Definition: drawing_area.h:54
void set_nextframe(u_int16 nf)
Sets the index of the frame that will be displayed right after this one.
Definition: animation.h:192
animationframe * get_frame(u_int16 nbr)
Returns a pointer to a desired frame.
Definition: animation.h:590
s_int16 yoffset() const
Returns the global Y offset of the animation.
Definition: animation.h:555
void set_mask(bool mask)
Sets the mask parameter of this frame.
Definition: animation.h:97
Handles images properties in an animation.
Definition: animation.h:52
u_int16 offx() const
Returns the X offset (i.e position relative to the animation&#39;s position) of this frame.
Definition: animation.h:213
#define s_int16
16 bits long signed integer
Definition: types.h:47
void set_alpha(u_int8 a)
Sets the alpha value for this frame.
Definition: animation.h:118
void play()
Starts the playback of the animation.
Definition: animation.h:348
s_int16 xoffset() const
Returns the global X offset of the animation.
Definition: animation.h:544
u_int16 nbr_of_frames() const
Returns the number of frames in this animation.
Definition: animation.h:500
animationframe()
Default constructor.
Definition: animation.cc:44
Abstract class for drawable objects manipulation.
Definition: drawable.h:59
play_state playstate() const
Returns whether the animation is currently being played.
Definition: animation.h:376
Class that handles animated elements, their update and their playback.
Definition: animation.h:312
u_int16 nbr_of_images() const
Returns the number of images in this animation.
Definition: animation.h:511
u_int16 delay() const
Returns the duration of this frame.
Definition: animation.h:159
void set_offset(s_int16 x, s_int16 y)
Set the global offsets of this animation.
Definition: animation.h:566
#define s_int8
8 bits long signed integer
Definition: types.h:44
image * get_image(u_int16 nbr)
Returns a pointer to a desired image.
Definition: animation.h:602
u_int16 offy() const
Returns the Y offset (i.e position relative to the animation&#39;s position) of this frame.
Definition: animation.h:225