1 /* 2 * SDmm - a C++ wrapper for SDL and related libraries 3 * Copyright � 2001 David Hedbor <david@hedbor.org> 4 * 5 * This program is free software; you can redistribute it and/or 6 * modify it under the terms of the GNU General Public License as 7 * published by the Free Software Foundation; either version 2 of the 8 * License, or (at your option) any later version. 9 * 10 * This program is distributed in the hope that it will be useful, but 11 * WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 * General Public License for more details. 14 * 15 * You should have received a copy of the GNU General Public License 16 * along with this program; if not, write to the Free Software 17 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 18 * 19 */ 20 21 22 #ifndef SDLMM_DISPLAY_H 23 #define SDLMM_DISPLAY_H 24 25 #include "sdlmm_basesurface.h" 26 27 namespace SDLmm { 28 //! The video frame buffer surface. 29 /*! 30 This class represents the actual video frame buffer memory. If you 31 are using hardware video support, the actual memory is stored on 32 the graphics card. Please note that if you create more than one 33 Display instance, they will all reference the same actual surface 34 (i.e the current display). 35 36 \note Since the actual SDL_Surface representation is shared among all 37 Display instances, they will always reference the correct surface. 38 */ 39 class DECLSPEC Display : public BaseSurface { 40 protected: 41 //! Dummy implementation of operator=() to stop initialization. 42 Display& operator= (Display&); 43 Display(Display&); 44 Display()45 Display() : BaseSurface(NULL) { } //!< A NOOP constructor. 46 47 public: ~Display()48 ~Display() { 49 me = 0; // Or it will be destroyed by the BaseSurface destructor... 50 } 51 52 //! The one and only display. 53 static Display& GetDisplay(); 54 55 //! \name Methods updating the screen 56 //@{ 57 //! Makes sure the given area is updated on the screen. 58 /*! 59 If '\a x', '\a y', '\a w' and '\a h' are all 0 (the default), 60 UpdateRect() will update the entire display. 61 62 This function should not be called if Display is locked! 63 64 \param x, y the top left corner of the rectangle to update 65 \param w, h the width and height of the rectangle. 66 67 \sa UpdateRect(SDL_Rect& rect), UpdateRects, SRect 68 */ 69 void UpdateRect(Sint32 x = 0, Sint32 y = 0, Sint32 w = 0, Sint32 h = 0); 70 71 //! Makes sure the entire screen is updated 72 /*! 73 This call is identical to calling UpdateRect() without arguments. 74 75 This function should not be called if Display is locked! 76 77 \sa UpdateRect, UpdateRects, SRect 78 */ Update()79 void Update() { UpdateRect(); } 80 81 //! Makes sure the given area is updated on the display. 82 /*! 83 This function should not be called if Display is locked! 84 85 \param rect the rectangle to update. 86 \sa UpdateRects, SRect 87 */ 88 void UpdateRect(SDL_Rect& rect); 89 90 //! Makes sure the given list of rectangles is updated on the display 91 /*! 92 This function should not be called if Display is locked! 93 94 \note It is adviced to call this function only once per frame, 95 since each call has some processing overhead. This is no 96 restriction since you can pass any number of rectangles each 97 time. 98 99 The rectangles are not automatically merged or checked for 100 overlap. In general, the programmer can use his knowledge about 101 his particular rectangles to merge them in an efficient way, to 102 avoid overdraw. 103 104 \param numrects the number of rectangles in the array. 105 \param rects the array of rectangles to update 106 \sa UpdateRect, SRect, Update 107 */ 108 void UpdateRects(int numrects, SDL_Rect *rects); 109 110 //! Swaps screen buffers. 111 /*! 112 On hardware that supports double-buffering, this function sets 113 up a flip and returns. The hardware will wait for vertical 114 retrace, and then swap video buffers before the next video 115 surface Blit or Lock will return. On hardware that doesn't 116 support double-buffering, this is equivalent to calling 117 UpdateRect() (i.e w/o parameters). 118 119 The SDL_DOUBLEBUF flag must have been passed to SetVideoMode, 120 when setting the video mode for this function to perform 121 hardware flipping. 122 \return true for success, false for failure. 123 */ 124 Flip()125 bool Flip() { return SDL_Flip(me) == 0; } 126 //@} 127 128 //! Setup the video mode with the specified width, height and 129 //! color depth. 130 /*! 131 If bpp is zero, the color depth uses is that of the current 132 display. 133 134 \returns Returns true for success and false for failure. 135 \param w, h width and height 136 \param bpp color depth in bits-per-pixel 137 \param flags the video flags 138 */ 139 bool SetVideoMode(int w, int h, int bpp = 0, Uint32 flags = 0); 140 141 //! \name Video Modes / Setup 142 //@{ 143 //! Initializes the video subsystem 144 /*! 145 Call this method to setup the video subsystem. 146 \return true on success, false on error */ 147 static bool Init(); 148 149 //! Shut down the video subsystem 150 static void Quit(); 151 152 //! Check to see if a particular video mode is supported. 153 /*! 154 155 VideoModeOK returns 0 if the requested mode is not supported 156 under any bit depth, or returns the bits-per-pixel of the 157 closest available mode with the given width, height and 158 requested surface flags (see SetVideoMode). 159 160 The bits-per-pixel value returned is only a suggested mode. You 161 can usually request any bpp you want when setting the video mode 162 and SDL will emulate that color depth with a shadow video 163 surface. 164 165 The arguments to VideoModeOK are the same ones you would pass to 166 SetVideoMode. 167 168 \sa SetVideoMode, VideoInfo 169 */ 170 static int VideoModeOK(int w, int h, int bpp, Uint32 flags); 171 172 //! Returns a pointer to an array of available screen dimensions 173 //! for the given format and video flags. 174 /*! 175 Return a pointer to an array of available screen dimensions for 176 the given format and video flags, sorted largest to 177 smallest. Returns 0 if there are no dimensions available for 178 a particular format, or -1 if any dimension is okay for the 179 given format. 180 181 If \a format is 0, the mode list will be for the format returned 182 by VideoInfo()->vfmt(). The \a flag parameter is an OR'd 183 combination of surface flags. The flags are the same as those 184 used SetVideoMode and they play a strong role in deciding what 185 modes are valid. For instance, if you pass SDL_HWSURFACE as a 186 flag only modes that support hardware video surfaces will be 187 returned. 188 189 \sa SetVideoMode, VideoInfo, SRect 190 */ 191 static SDL_Rect **ListModes(SDL_PixelFormat *format = 0, Uint32 flags = 0); 192 //@} 193 194 195 //! \name Window Management 196 //@{ 197 //! Sets the window title and icon name of the application. 198 /*! 199 \param title the new title 200 \param icon the new icon title 201 */ 202 void SetCaption(const char *title, const char *icon); 203 204 //! Sets the window title and icon name of the application. 205 /*! 206 \param title the new title 207 \param icon the new icon title 208 */ 209 void SetCaption(const std::string& title, const std::string& icon); 210 //! Gets the window title and icon name. 211 /*! 212 \param title, icons pointers to char * which will be set to the 213 title and icon titles. 214 */ 215 void GetCaption(char **title, char **icon); 216 217 //! Gets the window title and icon name. 218 /*! 219 \param title, icons references to strings which will be set to 220 the title and icon titles. 221 */ 222 void GetCaption(std::string &title, std::string &icon); 223 224 //! Sets the icon for the display window. 225 /*! 226 This function must be called before the first call to 227 SetVideoMode(). 228 229 It takes an \a icon surface, and a \a mask in MSB format. 230 231 If mask is zero (default), the entire icon surface will be used 232 as the icon. 233 */ 234 void SetIcon(BaseSurface& icon, Uint8 *mask = 0); 235 236 //! Iconify / minimize the application. 237 238 /*! 239 If the application is running in a window managed environment 240 SDL attempts to iconify / minimize it. If Iconify() is 241 successful, the application will receive a SDL_APPACTIVE loss 242 event. 243 244 \sa EventHandler::HandleActiveEvent() 245 246 \returns true on success or false if iconification isn't 247 supported or was refused by the window manager. 248 */ 249 bool Iconify(); 250 251 //! Toggles between fullscreen and windowed mode. 252 /*! 253 Toggles the application between windowed and fullscreen mode, if 254 supported. (X11 is the only target currently supported, BeOS 255 support is experimental). 256 257 \returns true on success, false on failure. 258 */ 259 bool ToggleFullScreen(); 260 261 //! Grabs mouse and keyboard input. 262 /*! 263 264 Grabbing means that the mouse is confined to the application 265 window, and nearly all keyboard input is passed directly to the 266 application, and not interpreted by a window manager, if any. 267 268 When mode is SDL_GRAB_QUERY the grab mode is not changed, but 269 the current grab mode is returned. 270 271 \param mode one of the following: 272 \code 273 typedef enum { 274 SDL_GRAB_QUERY, // Query the current mode 275 SDL_GRAB_OFF, // Ungrab the mouse and keyboard 276 SDL_GRAB_ON // Grab the mouse and keyboard 277 } SDL_GrabMode; 278 \endcode 279 */ 280 SDL_GrabMode GrabInput(SDL_GrabMode mode); 281 //@} 282 283 // Documented in BaseSurface. Just return true since the display is always 284 // in the display format. Naturally. :-) SetDisplayFormat()285 bool SetDisplayFormat() { return true; } SetDisplayFormatAlpha()286 bool SetDisplayFormatAlpha() { return true; } 287 }; 288 } 289 290 #endif // SDLMM_DISPLAY_H 291