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

Screen.h

Go to the documentation of this file.
00001 /*********************************************************************************
00002  *
00003  * Razor! Engine - A modular C++ presentation engine
00004  *
00005  * $Id: Screen.h,v 1.5 2003/05/31 20:05:40 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 #ifndef SCREEN_H
00029 #define SCREEN_H
00030 
00031 #include <PalmOS.h>
00032 #include "StateDescriptor.h"
00033 #include "gfx/Display.h"
00034 
00035 
00036 /**
00037  * Screen defines the application specific behavior for a single screen.
00038  * <br>
00039  * Examples could be: A highscore screen, a game play screen, a bonus level screen,
00040  * a weapon shop screen, etc.
00041  * <br>
00042  * The order in which the Screens are to appear is defined by the ActionEngine.
00043  * <br>
00044  * The most important operations are the nextPeriod() operation which
00045  * is invoked in regular intervals and is supposed to update the
00046  * internal state of the Screen. And the drawAction() operation which is
00047  * invoked right afterwards, and is responsible for drawing a
00048  * visual representation of the current state onto the viewport Canvas.
00049  */
00050 class Screen
00051 {
00052     public:
00053 /// @name Lifecycle management
00054 //@{
00055     /**
00056      * Construct a new Screen.
00057      * <br><em>Caution: This is invoked BEFORE any Canvas or Display is properly set up!</em>
00058      * This makes it impossible to initialize graphics assets in the constructor. Use init() instead.
00059      */
00060     Screen() SEC_GAME;
00061 
00062     /**
00063      * Destroy the Screen
00064      */
00065     virtual ~Screen() SEC_GAME = 0;
00066 
00067 
00068     /**
00069      * Initialize the internal state of the Screen, and prepare all assets (bitmaps, etc.)
00070      * <br>
00071      * <em>CAUTION!!! All bitmaps need to be prepared for the Canvas on which they will
00072      * later be painted. No mixing is allowed!</em>
00073      */
00074     virtual void init(const Canvas *displayCanvas, const Canvas *viewportCanvas) SEC_GAME = 0;
00075 //@}
00076 
00077     
00078 /// @name Control flow
00079 //@{
00080     /**
00081      * Progress to the next period. Update the internal state of your
00082      * Screen, but <em>DO NOT DRAW ANYTHING!</em>. Only draw
00083      * in your drawXXX() operations.
00084      *
00085      * @return True - if the Screen wants to be exited
00086      *         False - if the Screen wants to remain the active Screen
00087      */
00088     virtual Boolean nextPeriod() SEC_GAME = 0;
00089 
00090     /**
00091      * In what intervals shall this screen be updated? 
00092      *
00093      * @return the length of the interval in 1/100 seconds (default is 4: 100/4 = 25fps).
00094      */
00095     virtual UInt32 getAdvanceTimeInterval() SEC_GAME;
00096     
00097     /**
00098      * How long shall the engine freeze the screen after resuming from a pause?
00099      *
00100      * @return the duration in 1/100 seconds (default is 0).
00101      */
00102     virtual UInt32 getPauseLengthBeforeResuming() SEC_GAME;
00103 //@}
00104 
00105     
00106 /// @name Visual representation
00107 //@{
00108     virtual void getDisplayProperties(DisplayProperties& displayProperties) const SEC_GAME;
00109 
00110 
00111     /**
00112      * Return the viewport properties that the screen needs to operate.
00113      * <br>
00114      * This is invoked after the Display has been fully initialized, so it is OK to
00115      * query Display properties within this operation.
00116      * <br>
00117      * <b>About the viewport rectangle</b>
00118      * <br>
00119      * Currently, only vertical limits are taken into account. Also, due
00120      * to technical limitations, the height of the viewport needs to be a multiple of 8.
00121      * <em>Ignoring this rule will lead to crashes on greyscale devices!</em>    
00122      * 
00123      * @param displayCanvas the display canvas, which can be queried for information to calculate viewport properties
00124      * @param viewport the viewport properties, which need to be filled in.
00125      */
00126     virtual void getViewportProperties(const Canvas *displayCanvas, ViewportProperties& viewport) const SEC_GAME = 0;
00127 
00128 
00129     /**
00130      * Draw the background of the viewport canvas. 
00131      * It is assumed that this operation fills the entire viewport region with an image.
00132      */
00133     virtual void drawBackground(const Canvas *viewportCanvas) const SEC_GAME = 0;
00134 
00135 
00136     /**
00137      * Draw the visual appearance of the action onto the viewport canvas.
00138      *
00139      * @param dirtyRectangle this needs to be filled in with the coordinates of the area
00140      *               that was actually modified by the paint operations.<br><b>Failing to do so will
00141      *               result in incomplete display updates</b>
00142      */
00143     virtual void drawAction(const Canvas *viewportCanvas, RectangleType *dirtyRectangle) SEC_GAME = 0;  
00144 
00145 
00146     /**
00147      * Draw any static imagery which lies outside the viewport region.
00148      */
00149     virtual void drawFixedOverlays(const Canvas *displayCanvas) const SEC_GAME = 0;
00150     
00151 
00152     /**
00153      * Draw any dynamic imagery which lies outside the viewport region.
00154      */
00155     virtual void drawDynamicOverlays(const Canvas *displayCanvas) const SEC_GAME = 0;
00156 //@}
00157 
00158 
00159 /// @name Input management
00160 //@{
00161     /**
00162      * Receive an input event.
00163      * The Screen can freely decide whether it wants to
00164      * react to it, or not.
00165      */
00166     virtual void receiveEvent(const EventType *evtPtr) SEC_GAME = 0;
00167 //@}
00168 
00169 
00170 /// @name Screen properties
00171 //@{
00172     /**
00173      * Indicates whether the screen wants a menu.
00174      *
00175      * @return true = menu enabled, false = menu disabled
00176      */
00177     virtual bool enableMenu() const SEC_GAME;
00178 //@}
00179 };
00180 
00181 
00182 
00183 #define SCREEN_PUBLIC_OPS(ClassName) \
00184     ClassName(const StateDescriptor *screenState) SEC_GAME; \
00185     virtual ~ClassName() SEC_GAME; \
00186  \
00187     void init(const Canvas *displayCanvas, const Canvas *viewportCanvas) SEC_GAME; \
00188  \
00189     void getViewportProperties(const Canvas *displayCanvas, ViewportProperties& viewport) const SEC_GAME; \
00190  \
00191     Boolean nextPeriod() SEC_GAME; \
00192  \
00193     void drawBackground(const Canvas *viewportCanvas) const SEC_GAME; \
00194     void drawAction(const Canvas *viewportCanvas, RectangleType *dirtyRectangle) SEC_GAME;   \
00195     void drawFixedOverlays(const Canvas *displayCanvas) const SEC_GAME;  \
00196     void drawDynamicOverlays(const Canvas *displayCanvas) const SEC_GAME; \
00197  \
00198     void receiveEvent(const EventType *evtPtr) SEC_GAME; 
00199 
00200 
00201 
00202 
00203 #endif

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