00001 /********************************************************************************* 00002 * 00003 * Razor! Engine - A modular C++ presentation engine 00004 * 00005 * $Id: SpriteEngine.h,v 1.2 2003/02/15 12:02:04 teacy Exp $ 00006 * 00007 * Copyright (c) 2000-2003 Tilo Christ. All Rights Reserved. 00008 * 00009 * Permission is hereby granted, free of charge, to any person obtaining a 00010 * copy of this software and associated documentation files (the "Software"), 00011 * to deal in the Software without restriction, including without limitation 00012 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 00013 * and/or sell copies of the Software, and to permit persons to whom the Software 00014 * is furnished to do so, subject to the following conditions: 00015 * 00016 * The above copyright notice and this permission notice shall be included in all 00017 * copies or substantial portions of the Software. 00018 * 00019 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, 00020 * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR 00021 * PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE 00022 * FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 00023 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 00024 * 00025 **********************************************************************************/ 00026 00027 00028 00029 #ifndef SPRITE_ENGINE_H 00030 #define SPRITE_ENGINE_H 00031 00032 #include <PalmOS.h> 00033 00034 #include "RazorSections.h" 00035 #include "gfx/Canvas.h" 00036 00037 00038 /** 00039 * AnimFrames manages the frames of an animated Sprite. Each Sprite is associated 00040 * with an instance of AnimFrames. Several Sprites may share the same instance of 00041 * AnimFrames if they have the same appearance. This is recommended, since it saves 00042 * valuable resources.<br> 00043 * All frames within an AnimFrames object share the same size, the same hotspot and the same 00044 * mode of drawing. 00045 */ 00046 class AnimFrames 00047 { 00048 public: 00049 00050 /** 00051 * Create an instance of a transparent AnimFrames. 00052 * The frames will be constructed from bitmap 00053 * resources in a resource database. The bitmap families for the frames need to 00054 * be stored at IDs bitmapID..(bitmapID + numFrames) - 1. The 1bpp bitmaps for the 00055 * transparency masks need to be stored at IDs maskID..(maskID + numFrames) - 1. 00056 * 00057 * @param numFrames the number of frames 00058 * @param bitmapID the ID of the first image bitmap in the resource database. 00059 * @param maskID the ID of the first mask bitmap in the resource database 00060 * @param hotSpotX the horizontal offset of the hotspot. 00061 * @param hotSpotY the vertical offset of the hotspot. 00062 */ 00063 AnimFrames(const Canvas *canvas, UInt16 numFrames, DmResID bitmapID, DmResID maskID, Coord hotSpotX = 0, Coord hotSpotY = 0) SEC_RAZOR_INIT; 00064 00065 00066 /** 00067 * Create an instance of an opaque (not transparent) AnimFrames. 00068 * The frames will be constructed from bitmap 00069 * resources in a resource database. The bitmap families for the frames need to 00070 * be stored at IDs bitmapID..(bitmapID + numFrames) - 1. 00071 * 00072 * @param numFrames the number of frames 00073 * @param bitmapID the ID of the first image bitmap in the resource database. 00074 * @param hotSpotX the horizontal offset of the hotspot. 00075 * @param hotSpotY the vertical offset of the hotspot. 00076 */ 00077 AnimFrames(const Canvas *canvas, UInt16 numFrames, DmResID bitmapID, Coord hotSpotX = 0, Coord hotSpotY = 0) SEC_RAZOR_INIT; 00078 00079 00080 /** 00081 * Destroy the AnimFrames and deallocate all used resources. 00082 */ 00083 ~AnimFrames() SEC_RAZOR_INIT; 00084 00085 00086 /** 00087 * Get the screen space filled by the AnimFrames when it is placed at the specified coordinates. 00088 * 00089 * @param x the x coordinate 00090 * @param y the y coordinate 00091 * @param bounds a pointer to a rectangle which will be filled with the screen space 00092 * filled by the AnimFrames. 00093 * @return True, if the frame is completely off the screen, False if it is at least partially on the screen 00094 */ 00095 Boolean getBounds(Coord x, Coord y, RectangleType *bounds) const; 00096 00097 00098 /** 00099 * Draw a frame at the specified location. 00100 * <em>Caution: Although this operation is publically accessible, you should 00101 * know exactly what you are doing when you attempt to use it directly!!!</em> 00102 * 00103 * @param index the index of the displayed frame (0..numFrames). 00104 * @param x the x coordinate 00105 * @param y the y coordinate 00106 * @param bounds a pointer to a rectangle which will be filled with the screen space 00107 * filled by the frame, or NULL. 00108 */ 00109 void draw(UInt16 index, Coord x, Coord y, RectangleType *bounds = NULL) const SEC_RAZOR; 00110 00111 00112 private: 00113 00114 enum DrawingMode 00115 { 00116 drawMASK = 0, ///<Draw the frame with a mask for transparency 00117 drawNO_MASK = 1 ///<Draw the frames without transparency. 00118 }; 00119 00120 00121 void init(const Canvas *canvas, UInt16 numFrames, DmResID bitmapID, DmResID maskID, Coord hotSpotX, Coord hotSpotY, DrawingMode drawingMode) SEC_RAZOR_INIT; 00122 00123 Coord hotSpotX; 00124 Coord hotSpotY; 00125 DrawingMode drawingMode; 00126 00127 const BitmapArray *bitmapArray; 00128 00129 const Canvas *canvas; 00130 00131 friend class Sprite; 00132 }; 00133 00134 00135 00136 /** 00137 * Sprite describes a single sprite, i.e. a movable graphical object 00138 * with a transparent background. 00139 */ 00140 class Sprite 00141 { 00142 public: 00143 00144 /** @name Lifecycle management 00145 */ 00146 //@{ 00147 /** 00148 * Create a single new sprite. 00149 * <br> 00150 * Look at SpriteGroup if you wish to create a multitude of sprites. 00151 * 00152 * @param animFrames the animation frames for this sprite 00153 * @param visible shall the sprite be visible? 00154 * @param saveBackground shall the sprite be able to save and restore its background? 00155 */ 00156 Sprite(const AnimFrames *animFrames, Boolean visible, Boolean saveBackground) SEC_RAZOR_INIT; 00157 00158 00159 /** 00160 * Destroy the Sprite and deallocate all used resources. 00161 */ 00162 ~Sprite() SEC_RAZOR_INIT; 00163 //@} 00164 00165 /** @name State management (visibility, position, etc.) 00166 */ 00167 //@{ 00168 /** 00169 * Show the sprite during subsequent draws. 00170 */ 00171 void show(); 00172 00173 00174 /** 00175 * Hide the sprite during subsequent draws. 00176 */ 00177 void hide(); 00178 00179 00180 /** 00181 * Set the visibility of the sprite through a flag. 00182 * 00183 * @param visible shall the sprite be visible (true = shown / false = hidden) 00184 */ 00185 Boolean setVisibility(Boolean visible); 00186 00187 00188 /** 00189 * Will the sprite be drawn during subsequent draws? 00190 */ 00191 Boolean isVisible() const; 00192 00193 00194 /** 00195 * Set the displayed frame of the Sprite. 00196 * 00197 * @param frameIndex the index of the displayed frame. Must be between 0..numFrames-1 of the associated AnimFrames. 00198 */ 00199 void setFrame(UInt16 frameIndex); 00200 00201 00202 /** 00203 * Move the sprite (i.e. its hotspot) to the specified coordinates. 00204 */ 00205 void move(Coord x, Coord y); 00206 //@} 00207 00208 00209 /// @name Visual representation 00210 //@{ 00211 /** 00212 * Draw the sprite at its current location. 00213 * If the sprite has been set to save its background, the background will be 00214 * saved before the sprite will be drawn. 00215 * 00216 * @param bounds a pointer to a rectangle which will be filled with the screen space 00217 * filled by the sprite, or NULL. 00218 */ 00219 void draw(RectangleType *bounds = NULL) SEC_RAZOR; 00220 00221 00222 /** 00223 * Restore the saved background of the sprite. 00224 * This operation will not do anything if the sprite has been either not drawn, or the 00225 * background has been discarded since the last draw operation. 00226 */ 00227 void restoreBackground() const SEC_RAZOR; 00228 00229 00230 /** 00231 * Throw away the background of a sprite. 00232 */ 00233 void discardBackground() SEC_RAZOR; 00234 00235 00236 /** 00237 * Get the screen space filled by the sprite. 00238 * 00239 * @param bounds a pointer to a rectangle which will be filled with the screen space 00240 * filled by the sprite. 00241 * @return True, if the Sprite is completely off the screen, False if it is at least partially on the screen 00242 */ 00243 Boolean getBounds(RectangleType *bounds) const; 00244 //@} 00245 00246 00247 00248 private: 00249 /** 00250 * Create a new, disabled sprite 00251 */ 00252 Sprite() SEC_RAZOR_INIT; 00253 00254 /** 00255 * Initialize an existing instance with new parameters. 00256 */ 00257 void init(const AnimFrames *animFrames, Boolean visible = true, Boolean saveBackground = false) SEC_RAZOR_INIT; 00258 00259 /** 00260 * Save the background of the sprite. 00261 */ 00262 void saveBackground() SEC_RAZOR; 00263 00264 00265 const AnimFrames *animFrames; 00266 00267 UInt16 frameIndex; 00268 Boolean visible; 00269 Coord x; 00270 Coord y; 00271 00272 00273 enum BgSaveState 00274 { 00275 bgDONT_SAVE = 0, ///<Do not save the background during draw operation 00276 bgNOT_SAVED = 1, ///<The background shall be saved during draw operation, but this has not been done yet 00277 bgSAVED = 2 ///<A saved background is available 00278 }; 00279 00280 00281 BgSaveState bgSaveState; 00282 SaveBufferArray *bgSaveBuffer; 00283 00284 00285 // Ain't it nice to have friends... 00286 friend class SpriteGroup; 00287 }; 00288 00289 00290 00291 /** 00292 * SpriteGroup assists in the management of a collection of sprites. 00293 */ 00294 class SpriteGroup 00295 { 00296 public: 00297 00298 00299 /** 00300 * Create a SpriteGroup. 00301 * 00302 * @param numSprites the number of managed sprites 00303 */ 00304 SpriteGroup(UInt16 numSprites) SEC_RAZOR_INIT; 00305 00306 00307 /** 00308 * Destroy the SpriteGroup and deallocate all used resources. 00309 */ 00310 ~SpriteGroup() SEC_RAZOR_INIT; 00311 00312 00313 /** 00314 * Create an animated sprite with the specified AnimFrames. Ownership of the AnimFrames object is <em>NOT</em> 00315 * transferred to the Sprite. It will not automatically be destroyed when the Sprite is destroyed. 00316 * 00317 * @param animFrames a reference to an AnimFrames object 00318 * @param visible shall the sprite be visible? 00319 * @param saveBackground shall the sprite's background be preserved during a draw operation? 00320 */ 00321 void createSprite(UInt16 spriteIdx, const AnimFrames *animFrames, Boolean visible = true, Boolean saveBackground = false) SEC_RAZOR_INIT; 00322 00323 /** 00324 * Create a group of identical animated sprites with the specified AnimFrames. 00325 * All Sprites in the SpriteGroup will be set to the specified properties. 00326 * Ownership of the AnimFrames object is <em>NOT</em> 00327 * transferred to the Sprite. It will not automatically be destroyed when the Sprite is destroyed. 00328 * 00329 * @param animFrames a reference to an AnimFrames object 00330 * @param visible shall the sprite be visible? 00331 * @param saveBackground shall the sprite's background be preserved during a draw operation? 00332 */ 00333 void createSprites(const AnimFrames *animFrames, Boolean visible = true, Boolean saveBackground = false) SEC_RAZOR_INIT; 00334 00335 /** @name State management (visibility, position, etc.) 00336 */ 00337 //@{ 00338 /** 00339 * Show the sprite during subsequent draws. 00340 */ 00341 void show(UInt16 spriteIdx); 00342 00343 00344 /** 00345 * Hide the sprite during subsequent draws. 00346 */ 00347 void hide(UInt16 spriteIdx); 00348 00349 00350 /** 00351 * Set the visibility of the sprite through a flag. 00352 * 00353 * @param visible shall the sprite be visible (true = shown / false = hidden) 00354 */ 00355 Boolean setVisibility(UInt16 spriteIdx, Boolean visible); 00356 00357 00358 /** 00359 * Will the sprite be drawn during subsequent draws? 00360 */ 00361 Boolean isVisible(UInt16 spriteIdx) const; 00362 00363 00364 /** 00365 * Set the displayed frame of the Sprite. 00366 * 00367 * @param frameIndex the index of the displayed frame. Must be between 0..numFrames-1 of the associated AnimFrames. 00368 */ 00369 void setFrame(UInt16 spriteIdx, UInt16 frameIndex); 00370 00371 00372 /** 00373 * Move the sprite (i.e. its hotspot) to the specified coordinates. 00374 */ 00375 void move(UInt16 spriteIdx, Coord x, Coord y); 00376 //@} 00377 00378 00379 /** 00380 * Draw all the sprites in the group. 00381 */ 00382 void draw(RectangleType *bounds = NULL) SEC_RAZOR; 00383 00384 /** 00385 * Restore the background of all sprites in the group. 00386 */ 00387 void restoreBackground() const SEC_RAZOR; 00388 00389 00390 private: 00391 00392 UInt16 numSprites; 00393 Sprite *sprites; 00394 }; 00395 00396 00397 00398 #endif