00001 /********************************************************************************* 00002 * 00003 * Razor! Engine - A modular C++ presentation engine 00004 * 00005 * $Id: SpriteEngine.h,v 1.1.1.1 2000/12/09 09:28:40 christ Exp $ 00006 * 00007 * Copyright (c) 2000 Tilo Christ. All Rights Reserved. 00008 * 00009 * This library is free software; you can redistribute it and/or 00010 * modify it under the terms of the GNU Lesser General Public 00011 * License as published by the Free Software Foundation; either 00012 * version 2.1 of the License, or (at your option) any later version. 00013 * 00014 * This library is distributed in the hope that it will be useful, 00015 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00016 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00017 * Lesser General Public License for more details. 00018 * 00019 * You should have received a copy of the GNU Lesser General Public 00020 * License along with this library; if not, write to the Free Software 00021 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 00022 * 00023 **********************************************************************************/ 00024 00025 00026 00027 #ifndef SPRITE_ENGINE_H 00028 #define SPRITE_ENGINE_H 00029 00030 #include <PalmOS.h> 00031 #include "Canvas.h" 00032 00033 00034 class SpriteGroup; 00035 00036 00037 /** 00038 * AnimFrames manages the frames of an animated Sprite. Each Sprite is associated 00039 * with an instance of AnimFrames. Several Sprites may share the same instance of 00040 * AnimFrames if they have the same appearance. This is recommended, since it saves 00041 * valuable resources.<br> 00042 * All frames within an AnimFrames object share the same size, the same hotspot and the same 00043 * mode of optimization. 00044 */ 00045 class AnimFrames 00046 { 00047 public: 00048 00049 enum OptimizationMode 00050 { 00051 optNONE = 0, ///<Do not optimize the frames 00052 optBUFFER = 1, ///<Draw the frames into an offscreen buffer for faster display 00053 optNO_MASK = 2 ///<Make the frames non-transparent. Do this whenever possible! 00054 }; 00055 00056 00057 00058 /** 00059 * Create an instance of AnimFrames. The frames will be constructed from bitmap 00060 * resources in a resource database. The bitmap families for the frames need to 00061 * be stored at IDs bitmapID..(bitmapID + numFrames) - 1. The 1bpp bitmaps for the 00062 * transparency masks need to be stored at IDs maskID..(maskID + numFrames) - 1. 00063 * 00064 * @param numFrames the number of frames 00065 * @param bitmapID the ID of the first image bitmap in the resource database. 00066 * @param maskID the ID of the first mask bitmap in the resource database, or -1 when no masks are desired (optimizationMode == optNO_MASK). 00067 * @param hotSpotX the horizontal offset of the hotspot. 00068 * @param hotSpotY the vertical offset of the hotspot. 00069 * @param optimizationMode which optimizations shall be applied? 00070 */ 00071 AnimFrames(UInt16 numFrames, DmResID bitmapID, DmResID maskID = -1, Coord hotSpotX = 0, Coord hotSpotY = 0, OptimizationMode optimizationMode = optNONE); 00072 00073 00074 /** 00075 * Destroy the AnimFrames and deallocate all used resources. 00076 */ 00077 ~AnimFrames(); 00078 00079 00080 /** 00081 * Get the screen space filled by the AnimFrames when it is placed at the specified coordinates. 00082 * 00083 * @param x the x coordinate 00084 * @param y the y coordinate 00085 * @param bounds a pointer to a rectangle which will be filled with the screen space 00086 * filled by the AnimFrames. 00087 */ 00088 void getBounds(Coord x, Coord y, RectangleType *bounds) const; 00089 00090 00091 private: 00092 00093 00094 /** 00095 * Draw a frame at the specified location. 00096 * Inquire the current draw window and allocate draw buffers as neccessary. 00097 * 00098 * @param index the index of the displayed frame (0..numFrames). 00099 * @param x the x coordinate 00100 * @param y the y coordinate 00101 * @param bounds a pointer to a rectangle which will be filled with the screen space 00102 * filled by the frame, or NULL. 00103 */ 00104 void draw(UInt16 index, Coord x, Coord y, RectangleType *bounds = NULL) const; 00105 00106 00107 /** 00108 * Draw the frame at the specified location into the specified drawWindow 00109 * and use the specified offScreen buffer for internal drawing operations. 00110 * 00111 * @param index the index of the displayed frame (0..numFrames). 00112 * @param x the x coordinate 00113 * @param y the y coordinate 00114 * @param bounds a pointer to a rectangle which will be filled with the screen space 00115 * filled by the frame, or NULL. 00116 */ 00117 void quickDraw(UInt16 index, Coord x, Coord y, WinHandle drawWindow, WinHandle offScreenH, RectangleType *bounds) const; 00118 00119 00120 OptimizationMode getOptimizationMode() const; 00121 00122 00123 UInt16 numFrames; 00124 DmResID bitmapID; 00125 DmResID maskID; 00126 Coord hotSpotX; 00127 Coord hotSpotY; 00128 Int16 width; 00129 Int16 height; 00130 OptimizationMode optimizationMode; 00131 00132 struct FrameDescriptor 00133 { 00134 WinHandle offScreenBitmap; 00135 WinHandle offScreenMask; 00136 }; 00137 00138 FrameDescriptor *frameDescriptors; 00139 00140 friend class Sprite; 00141 }; 00142 00143 00144 00145 /** 00146 * Sprite describes a single sprite, i.e. a movable graphical object 00147 * with a transparent background. 00148 */ 00149 class Sprite 00150 { 00151 public: 00152 00153 /** 00154 * Create a Sprite with no animation. The required AnimFrames object will be created implicitly, and will automatically 00155 * be destroyed when the sprite is destroyed. 00156 * 00157 * @param bitmapID the ID of the image bitmap in the resource database. 00158 * @param maskID the ID of the mask bitmap in the resource database, or -1 when no masks are desired (optimizationMode == optNO_MASK). 00159 * @param hotSpotX the horizontal offset of the hotspot. 00160 * @param hotSpotY the vertical offset of the hotspot. 00161 * @param visible shall the sprite be visible? 00162 * @param optimizationMode which optimizations shall be applied? 00163 */ 00164 Sprite(DmResID bitmapID, DmResID maskID = -1, Coord hotSpotX = 0, Coord hotSpotY = 0, Boolean visible = true, AnimFrames::OptimizationMode optimizationMode = AnimFrames::optNONE); 00165 00166 00167 /** 00168 * Create an animated sprite with the specified AnimFrames. Ownership of the AnimFrames object is <em>NOT</em> 00169 * transferred to the Sprite. It will not automatically be destroyed when the Sprite is destroyed. 00170 * 00171 * @param animFrames a reference to an AnimFrames object 00172 * @param visible shall the sprite be visible? 00173 */ 00174 Sprite(AnimFrames& animFrames, Boolean visible = true); 00175 00176 00177 /** 00178 * Destroy the Sprite and deallocate all used resources. 00179 */ 00180 ~Sprite(); 00181 00182 00183 /** 00184 * Show the sprite during subsequent draws. 00185 */ 00186 void show(); 00187 00188 00189 /** 00190 * Hide the sprite during subsequent draws. 00191 */ 00192 void hide(); 00193 00194 00195 /** 00196 * Set the visibility of the sprite through a flag. 00197 * 00198 * @param visible shall the sprite be visible (true = shown / false = hidden) 00199 */ 00200 Boolean setVisibility(Boolean visible); 00201 00202 00203 /** 00204 * Will the sprite be drawn during subsequent draws? 00205 */ 00206 Boolean isVisible() const; 00207 00208 00209 /** 00210 * Set the displayed frame of the Sprite. 00211 * 00212 * @param frameIndex the index of the displayed frame. Must be between 0..numFrames-1 of the associated AnimFrames. 00213 */ 00214 void setFrame(UInt16 frameIndex); 00215 00216 00217 /** 00218 * Move the sprite (i.e. its hotspot) to the specified coordinates. 00219 */ 00220 void move(Coord x, Coord y); 00221 00222 00223 /** 00224 * Draw the sprite at its current location. 00225 * Inquire the current draw window and allocate draw buffers as neccessary. 00226 * 00227 * @param bounds a pointer to a rectangle which will be filled with the screen space 00228 * filled by the sprite, or NULL. 00229 */ 00230 void draw(RectangleType *bounds = NULL) const; 00231 00232 00233 /** 00234 * Get the screen space filled by the sprite. 00235 * 00236 * @param bounds a pointer to a rectangle which will be filled with the screen space 00237 * filled by the sprite. 00238 */ 00239 void getBounds(RectangleType *bounds) const; 00240 00241 00242 00243 private: 00244 00245 00246 /** 00247 * Draw the sprite at its current location into the specified drawWindow 00248 * and use the specified offScreen buffer for internal drawing operations. 00249 */ 00250 void quickDraw(WinHandle drawWindow, WinHandle offScreenH, RectangleType *bounds) const; 00251 00252 00253 AnimFrames::OptimizationMode getOptimizationMode() const; 00254 00255 00256 AnimFrames *animFrames; 00257 Boolean ownsAnimFrames; 00258 00259 UInt16 frameIndex; 00260 Boolean visible; 00261 Coord x; 00262 Coord y; 00263 00264 00265 // Ain't it nice to have friends... 00266 friend class SpriteGroup; 00267 }; 00268 00269 00270 00271 /** 00272 * SpriteGroup assists in the management of a collection of sprites. 00273 */ 00274 class SpriteGroup 00275 { 00276 public: 00277 00278 00279 /** 00280 * Create the SpriteGroup. The group may contain up to maxSprites Sprites. 00281 * @param maxSprites the maximum number of managed sprites 00282 */ 00283 SpriteGroup(int maxSprites); 00284 00285 00286 /** 00287 * Destroy the SpriteGroup and deallocate all used resources. 00288 */ 00289 ~SpriteGroup(); 00290 00291 00292 /** 00293 * Add a sprite to the group. 00294 * 00295 * @param sprite a reference to the sprite. Ownership of the sprite will remain 00296 * with the caller, i.e. SpriteGroup will not destroy the sprite when the 00297 * group is destroyed. 00298 */ 00299 void addSprite(Sprite& sprite); 00300 00301 00302 /** 00303 * Draw all the sprites in the group. 00304 */ 00305 void draw(RectangleType *bounds); 00306 00307 00308 private: 00309 00310 int maxSprites; 00311 int currSprites; 00312 Sprite* *theSprites; 00313 00314 WinHandle offscreenH; 00315 int maxWidth; 00316 int maxHeight; 00317 int oldMaxWidth; 00318 int oldMaxHeight; 00319 Boolean needBuffer; 00320 }; 00321 00322 00323 00324 #endif