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