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