Adonthell 0.4
animation.h
Go to the documentation of this file.
00001 // $Id: animation.h,v 1.44 2001/07/29 16:25:04 gnurou Exp $
00002 
00003 /*
00004   Copyright (C) 1999/2000/2001   Alexandre Courbot.
00005   Part of the Adonthell Project http://adonthell.linuxgames.com
00006   
00007   This program is free software; you can redistribute it and/or modify
00008   it under the terms of the GNU General Public License.
00009   This program is distributed in the hope that it will be useful,
00010   but WITHOUT ANY WARRANTY.
00011   
00012   See the COPYING file for more details.
00013 */
00014 
00015 
00016 /**
00017  * @file   animation.h
00018  * @author Alexandre Courbot <alexandrecourbot@linuxgames.com>
00019  * 
00020  * @brief  Declares the animationframe and animation classes.
00021  *  
00022  */
00023 
00024 
00025 
00026 #ifndef _ANIMATION_H
00027 #define _ANIMATION_H
00028 
00029 
00030 #include "image.h"
00031 #include <vector>
00032 
00033 
00034 /**
00035  * Handles images properties in an animation.
00036  * %Objects of this class have no reason to exist if not affected to an
00037  * animation. The fact is, that often in an animation, you want the
00038  * same image to appear at different times, different positions or with
00039  * different mask and alpha values. An animationframe is a class that
00040  * contains the index of the image to display, the alpha and mask parameters
00041  * to give it, the time (in game cycles) it should be displayed before going
00042  * to the next frame, and the index and the frame to display right after
00043  * this one. As images and animationframes are arranged into an indexed array
00044  * in an animation, the index values only make sense from the animation point
00045  * of view.
00046  * 
00047  */ 
00048 class animationframe
00049 {
00050  public:
00051 
00052     /** 
00053      * Default constructor. 
00054      * 
00055      */
00056     animationframe ();
00057 
00058     /** 
00059      * Destructor.
00060      * 
00061      */
00062     ~animationframe ();
00063 
00064     /** 
00065      * Resets an animationframe to it's initial (i.e post-constructor) state.
00066      * 
00067      */
00068     void clear ();
00069 
00070  
00071     /**
00072      * @name Mask and Alpha Settings.
00073      * 
00074      */ 
00075     //@{ 
00076 
00077     /** 
00078      * Returns whether this frame is masked or not.
00079      * 
00080      * 
00081      * @return true if the surface is masked, false otherwise.
00082      */
00083     bool is_masked () const
00084     {
00085         return is_masked_;
00086     }
00087     
00088     /** 
00089      * Sets the mask parameter of this frame.
00090      * 
00091      * @param mask true if the surface should be masked, false otherwise.
00092      */
00093     void set_mask (bool mask)
00094     {
00095         is_masked_ = mask;
00096     }
00097 
00098     /** 
00099      * Returns the alpha value the this frame.
00100      * 
00101      * 
00102      * @return the alpha value of the frame.
00103      */
00104     u_int8 alpha () const
00105     {
00106         return alpha_;
00107     }     
00108 
00109     /** 
00110      * Sets the alpha value for this frame.
00111      * 
00112      * @param a new alpha value.
00113      */
00114     void set_alpha (u_int8 a)
00115     {
00116         alpha_ = a;
00117     }
00118 
00119     //@}
00120 
00121 
00122     /**
00123      * @name Image, delay and next frame settings.
00124      * 
00125      */ 
00126     //@{ 
00127     
00128     /** 
00129      * Returns the image number this frame points to.
00130      * 
00131      * 
00132      * @return the index of the image this frame points to.
00133      */
00134     u_int16 image_nbr () const
00135     {
00136         return imagenbr;
00137     }
00138     
00139     /** 
00140      * Sets the image this frame should point to.
00141      * 
00142      * @param imnbr the index of the image this frame should point to.
00143      */
00144     void set_image_nbr (u_int16 imnbr)
00145     {
00146         imagenbr = imnbr;
00147     }
00148     
00149     /** 
00150      * Returns the duration of this frame.
00151      * 
00152      * 
00153      * @return the delay (in game cycles) of this frame (0 means infinite).
00154      */
00155     u_int16 delay () const
00156     {
00157         return delay_;
00158     }
00159 
00160     /** 
00161      * Sets the duration of this frame.
00162      * 
00163      * @param d new delay (in game cycles, 0 means infinite).
00164      */
00165     void set_delay (u_int16 d)
00166     {
00167         delay_ = d;
00168     }
00169     
00170     /** 
00171      * Returns the index of the frame that will be displayed once
00172      * the delay of this one expired.
00173      * 
00174      * 
00175      * @return the index of the frame next to this one.
00176      */
00177     u_int16 nextframe () const
00178     {
00179         return nextframe_;
00180     }
00181     
00182     /** 
00183      * Sets the index of the frame that will be displayed right after
00184      * this one.
00185      * 
00186      * @param nf index of the frame that will be next to this one.
00187      */
00188     void set_nextframe (u_int16 nf)
00189     {
00190         nextframe_ = nf;
00191     }
00192     
00193     //@}
00194 
00195 
00196     /**
00197      * @name Individual frames relative position.
00198      * 
00199      */
00200     //@{
00201     
00202     /** 
00203      * Returns the X offset (i.e position relative to the animation's position)
00204      * of this frame.
00205      * 
00206      * 
00207      * @return the X offset of this frame.
00208      */
00209     u_int16 offx () const
00210     {
00211         return gapx;
00212     }
00213      
00214     /** 
00215      * Returns the Y offset (i.e position relative to the animation's position)
00216      * of this frame.
00217      * 
00218      * 
00219      * @return the Y offset of this frame.
00220      */
00221     u_int16 offy () const
00222     {
00223         return gapy;
00224     }
00225     
00226     /** 
00227      * Sets the offset for this frame.
00228      * 
00229      * @param ox new X offset.
00230      * @param ox new Y offset.
00231      */
00232     void set_offset (u_int16 ox,  u_int16 oy)
00233     {
00234         gapx = ox;
00235         gapy = oy;
00236     }
00237 
00238     //@}
00239 
00240     
00241     /**
00242      * @name Saving/Loading Methods.
00243      * 
00244      */
00245     //@{
00246     
00247 
00248     /** 
00249      * Loads an animationframe from an opened file.
00250      * 
00251      * @param file the opened file from which to read.
00252      * 
00253      * @return 0 in case of success, error number in case of error.
00254      */
00255     s_int8 get (igzstream& file);
00256 
00257     /** 
00258      * Saves an animationframe into an opened file.
00259      * 
00260      * @param file the opened file where to save.
00261      * 
00262      * @return 0 in case of success, error number in case of error.
00263      */
00264     s_int8 put (ogzstream& file) const;
00265 
00266     
00267     //@}
00268  
00269     
00270 private:
00271     u_int16 imagenbr;
00272     bool is_masked_;
00273     u_int8 alpha_;
00274     s_int16 gapx;
00275     s_int16 gapy;
00276     u_int16 delay_;
00277     u_int16 nextframe_;     
00278 };
00279 
00280 
00281 
00282 /**
00283  * Whether the animation is currently playing or not.
00284  */ 
00285 typedef enum { PLAY = true, STOP = false } play_state; 
00286 
00287 
00288 
00289 /**
00290  * Class that handles animated elements, their update and their playback.
00291  * Most often, you will want your drawn %objects to be animated. Then you'll
00292  * probably want to use this class. An animation contains:
00293  *   - A set of images arranged in an indexed array.
00294  *   - A set of animation_frames.
00295  *   - A global position offset.
00296  *
00297  * During playback, the animation look at the first animation_frame. Each
00298  * animation_frame refers to an image of the animation, and give it special
00299  * mask and alpha parameters, as well as a position offset. It also have
00300  * a delay parameter, telling how many %game cycles this frame should stay.
00301  * Once the delay expired, the animation jumps to the next frame, which
00302  * is pointed by the current frame. That way, you can easily performs loops or
00303  * others effects. Each image, as well as each animation_frame, can be accessed
00304  * individually, thought you'd better try to avoid as much as possible to mess
00305  * with that.
00306  * 
00307  */ 
00308 class animation : public drawable
00309 {
00310 public:
00311 
00312     /**
00313      * Default constructor.
00314      * 
00315      */
00316     animation ();
00317 
00318     /**
00319      * Destructor.
00320      * 
00321      */ 
00322     ~animation ();
00323 
00324 
00325     /** 
00326      * Clears an animation, that is put it back into the original
00327      * (constructor) state.
00328      * 
00329      */
00330     void clear ();
00331 
00332 
00333     /**
00334      * @name Playback control methods.
00335      * 
00336      */
00337     //@{
00338     
00339 
00340     /** 
00341      * Starts the playback of the animation.
00342      * 
00343      */
00344     void play ()
00345     {
00346         play_flag = PLAY;
00347 #ifdef _EDIT_
00348         if (in_editor)
00349             must_upt_label_status = true;
00350 #endif
00351     }
00352 
00353     /** 
00354      * Stops the playback of the animation.
00355      * 
00356      */
00357     void stop ()
00358     {
00359         play_flag = STOP;
00360 #ifdef _EDIT_
00361         if (in_editor)
00362             must_upt_label_status = true;
00363 #endif
00364     }
00365 
00366     /** 
00367      * Returns whether the animation is currently being played.
00368      * 
00369      * 
00370      * @return PLAY is the animation is currently playing, STOP otherwise.
00371      */
00372     play_state playstate () const
00373     {
00374         return play_flag; 
00375     }
00376     
00377     /** 
00378      * Rewinds the animation to it's beginning.
00379      * 
00380      */
00381     void rewind ()
00382     {
00383         currentframe_ = 0;
00384         speedcounter = 0;
00385     }
00386 
00387 
00388     /** 
00389      * Directly jumps to the next frame.
00390      * 
00391      */
00392     void next_frame ();
00393     
00394     //@}
00395     
00396     
00397 
00398     /**
00399      * @name State updating Methods.
00400      * 
00401      */ 
00402     //@{
00403     
00404     /**
00405      * Updates the animation state.
00406      * 
00407      */ 
00408     bool update ();
00409 
00410     //@}
00411 
00412 
00413     /**
00414      * @name Drawing Methods.
00415      * 
00416      */ 
00417     //@{ 
00418 
00419     void draw (s_int16 x, s_int16 y, const drawing_area * da_opt = NULL,
00420                surface * target = NULL) const;
00421 
00422     //@}
00423 
00424 
00425     /**
00426      * @name Saving/Loading Methods.
00427      * @note There is no way to save animations with this class.
00428      * 
00429      */
00430     //@{
00431     
00432     /**
00433      * Loads an animation from an opened file.
00434      * @param file the opened file from which to load.
00435      * @return 0 in case of success, error code otherwise.
00436      *
00437      * @todo length and height are loaded while they are calculated later.
00438      *       Remove this when format will change.
00439      * 
00440      */ 
00441     s_int8 get (igzstream& file);
00442 
00443     /** 
00444      * Loads an animation from it's filename.
00445      * 
00446      * @param fname the name of the file to load.
00447      * 
00448      * @return 0 in case of success, error code otherwise.
00449      */
00450     s_int8 load (string fname);
00451     
00452     
00453     /** Saves an animation into an opened file, in %game format, with
00454      *  alpha and mask values. 
00455      *  @warning as the animation which is saved comes from a %screen's depth
00456      *           surface, it will be slightly altered during the save.
00457      *           If you want a class capable of saving animations with full
00458      *           truecolor quality, use animation_edit instead.
00459      *  @param file opened file where to save into.
00460      *  @return
00461      *      @li 0 in case of success.
00462      *      @li -1 in case of error.
00463      *  @sa save ()
00464      */
00465     s_int8 put (ogzstream& file) const;
00466 
00467     /** Saves an animation into an file, in %game format, with
00468      *  alpha and mask values.
00469      *  @warning as the animation which is saved comes from a %screen's depth
00470      *           surface, it will be slightly altered during the save.
00471      *           If you want a class capable of saving animations with full
00472      *           truecolor quality, use animation_edit instead.
00473      *  @param fname file name where to save into.
00474      *  @return
00475      *      @li 0 in case of success.
00476      *      @li -1 in case of error.
00477      *  @sa put ()
00478      */
00479     s_int8 save (string fname) const;
00480 
00481     //@}
00482 
00483 
00484     /**
00485      * @name Global animation properties Methods.
00486      * 
00487      */
00488     //@{
00489     
00490     /** 
00491      * Returns the number of frames in this animation.
00492      * 
00493      * 
00494      * @return the number of frames in this animation.
00495      */
00496     u_int16 nbr_of_frames () const
00497     {
00498         return frame.size ();
00499     }
00500  
00501     /** 
00502      * Returns the number of images in this animation.
00503      * 
00504      * 
00505      * @return the number of images in this animation.
00506      */
00507     u_int16 nbr_of_images () const
00508     {
00509         return t_frame.size ();
00510     }
00511      
00512     /** 
00513      * Returns the index of the currently displayed frame.
00514      * 
00515      * 
00516      * @return the index of the frame currently displayed.
00517      */
00518     u_int16 currentframe () const
00519     {
00520         return currentframe_;
00521     }
00522     
00523     /** 
00524      * Sets the current frame.
00525      * 
00526      * @param framenbr the index of the frame to display now.
00527      */
00528     void set_currentframe (u_int16 framenbr)
00529     {
00530         currentframe_ = framenbr;
00531         speedcounter = 0; 
00532     }
00533     
00534     /** 
00535      * Returns the global X offset of the animation.
00536      * 
00537      * 
00538      * @return the global X offset of the animation.
00539      */
00540     s_int16 xoffset () const
00541     {
00542         return xoffset_;
00543     }
00544      
00545     /** 
00546      * Returns the global Y offset of the animation.
00547      * 
00548      * 
00549      * @return the global Y offset of the animation.
00550      */
00551     s_int16 yoffset () const
00552     {
00553         return yoffset_;
00554     }
00555 
00556     /** 
00557      * Set the global offsets of this animation.
00558      * 
00559      * @param x new X global offset.
00560      * @param y new Y global offset.
00561      */
00562     void set_offset (s_int16 x, s_int16 y)
00563     {
00564         xoffset_ = x;
00565         yoffset_ = y;
00566     }
00567 
00568     
00569     //@}
00570     
00571      
00572 
00573     /**
00574      * @name Image and Animationframe control Methods.
00575      * 
00576      */
00577     //@{
00578 
00579     /** 
00580      * Returns a pointer to a desired frame.
00581      * 
00582      * @param nbr the index of the frame to get.
00583      * 
00584      * @return pointer to the nbr frame.
00585      */
00586     animationframe *get_frame (u_int16 nbr)
00587     {
00588         return &(frame[nbr]);
00589     }
00590     
00591     /** 
00592      * Returns a pointer to a desired image.
00593      * 
00594      * @param nbr the index of the image to get.
00595      * 
00596      * @return pointer to the nbr image.
00597      */
00598     image *get_image (u_int16 nbr)
00599     {
00600         return t_frame[nbr];
00601     }
00602     
00603     /** 
00604      * Inserts an image at a given position of the image array.
00605      * All the frames will be updated so the operation doesn't affect
00606      * the animation in any way.
00607      *
00608      * The animation will be responsible for freeing the inserted image.
00609      * 
00610      * @param im pointer to the image to add.
00611      * @param pos index where to add the image.
00612      * 
00613      * @return 0 in case of success, error code otherwise.
00614      */
00615     s_int8 insert_image (const image * im, u_int16 pos);
00616 
00617 
00618     /** 
00619      * Inserts a frame at a given position of the animationframe array.
00620      * All the frames will be updated so the operation doesn't affect
00621      * the animation in any way.
00622      * 
00623      * @param af the animationframe to add.
00624      * @param pos index where to add the frame.
00625      * 
00626      * @return 0 in case of success, error code otherwise.
00627      */
00628     s_int8 insert_frame (const animationframe af, u_int16 pos);
00629 
00630     /** 
00631      * Removes an image at a given position.
00632      * The image itself will also be deleted ().
00633      * All the frames will be updated so the operation doesn't affect
00634      * the animation in any way.
00635      *
00636      * @param pos The index of the image to remove.
00637      * 
00638      * @return 0 in case of success, error code otherwise.
00639      */
00640     s_int8 delete_image (u_int16 pos);
00641  
00642     /** 
00643      * Removes a frame at a given position.
00644      * All the frames will be updated so the operation doesn't affect
00645      * the animation in any way.
00646      * 
00647      * @param pos The index of the animationframe to remove.
00648      * 
00649      * @return 0 in case of success, error code otherwise.
00650      */
00651     s_int8 delete_frame (u_int16 pos); 
00652     
00653     //@}
00654     
00655     /**
00656      * @name Special FX methods.
00657      * 
00658      */
00659     //@{
00660 
00661     /** 
00662      * Zooms an animation.
00663      * 
00664      * @param sx Desired X size.
00665      * @param sy Desired Y size.
00666      * @param src Source animation to zoom.
00667      */
00668     void zoom (u_int16 sx, u_int16 sy, const animation * src);
00669 
00670     //@}
00671 
00672 #ifndef SWIG
00673     /**
00674      * Animation copy (similar to copy ()).
00675      *
00676      * @attention Not available from Python. Use copy () from Python instead.
00677      * @sa copy ()
00678      */ 
00679     animation& operator = (const animation& src);
00680 #endif
00681 
00682     /**
00683      * Synonym of operator = to guarantee its access from Python.
00684      *
00685      * @sa operator = 
00686      */
00687     void copy (const animation& src) 
00688     {
00689         *this = src; 
00690     }
00691 
00692     
00693 private:
00694     /**
00695      * Forbid value passing.
00696      */
00697     animation(const animation& src);
00698 
00699     /** 
00700      * Calculate the real dimensions of the animation, depending
00701      * of it's frames and images.
00702      * 
00703      */
00704     void calculate_dimensions (); 
00705 
00706     mutable vector <image *> t_frame;
00707     mutable vector <animationframe> frame;
00708     u_int16 currentframe_;
00709     u_int16 speedcounter;
00710     play_state play_flag;
00711     s_int16 xoffset_, yoffset_;
00712      
00713 #ifndef SWIG
00714     friend class win_anim;
00715 #endif
00716 };
00717 
00718 #endif