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.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

Razor! Engine Developer's Guide. Copyright © by Tilo Christ. All Rights Reserved. Last updated: 17 Dec 2000