Main Page   Class Hierarchy   Compound List   File List   Compound Members   File Members

SpriteEngine.h

Go to the documentation of this file.
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

Razor! Engine Developer's Guide. Copyright © by Tilo Christ. All Rights Reserved. Last updated: 31 May 2003