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