SDLmm::Display(3)                                            SDLmm::Display(3)



NAME
       SDLmm::Display - The video frame buffer surface.

SYNOPSIS
       #include <sdlmm_display.h>

       Inherits SDLmm::BaseSurface.

   Public Methods
       ~Display ()
       bool SetVideoMode (int w, int h, int bpp=0, Uint32 flags=0)
           Setup the video mode with the specified width, height and color
           depth.
       bool SetDisplayFormat ()
           Convert the surface to the display format.
       bool SetDisplayFormatAlpha ()
           Convert the surface to the display format.

       Methods updating the screen

           void UpdateRect (Sint32 x=0, Sint32 y=0, Sint32 w=0, Sint32 h=0)
               Makes sure the given area is updated on the screen.
           void Update ()
               Makes sure the entire screen is updated.
           void UpdateRect (SDL_Rect &rect)
               Makes sure the given area is updated on the display.
           void UpdateRects (int numrects, SDL_Rect *rects)
               Makes sure the given list of rectangles is updated on the
               display.
           bool Flip ()
               Swaps screen buffers.

       Window Management

           void SetCaption (const char *title, const char *icon)
               Sets the window title and icon name of the application.
           void SetCaption (const std::string &title, const std::string &icon)
               Sets the window title and icon name of the application.
           void GetCaption (char **title, char **icon)
               Gets the window title and icon name.
           void GetCaption (std::string &title, std::string &icon)
               Gets the window title and icon name.
           void SetIcon (BaseSurface &icon, Uint8 *mask=0)
               Sets the icon for the display window.
           bool Iconify ()
               Iconify / minimize the application.
           bool ToggleFullScreen ()
               Toggles between fullscreen and windowed mode.
           SDL_GrabMode GrabInput (SDL_GrabMode mode)
               Grabs mouse and keyboard input.

   Static Public Methods
       Display& GetDisplay ()
           The one and only display.

       Video Modes / Setup

           bool Init ()
               Initializes the video subsystem.
           void Quit ()
               Shut down the video subsystem.
           int VideoModeOK (int w, int h, int bpp, Uint32 flags)
               Check to see if a particular video mode is supported.
           SDL_Rect** ListModes (SDL_PixelFormat *format=0, Uint32 flags=0)
               Returns a pointer to an array of available screen dimensions
               for the given format and video flags.

   Protected Methods
       Display& operator= (Display &)
           Dummy implementation of operator=() to stop initialization.
       Display (Display &)
       Display ()
           A NOOP constructor.

DETAILED DESCRIPTION
       The video frame buffer surface.

       This class represents the actual video frame buffer memory. If you are
       using hardware video support, the actual memory is stored on the
       graphics card. Please note that if you create more than one Display
       instance, they will all reference the same actual surface (i.e the
       current display).

       Note:
           Since the actual SDL_Surface representation is shared among all
           Display instances, they will always reference the correct surface.

CONSTRUCTOR & DESTRUCTOR DOCUMENTATION
   SDLmm::Display::Display (Display &) [protected]
   SDLmm::Display::Display () [inline, protected]
       A NOOP constructor.

   SDLmm::Display::~Display () [inline]
MEMBER FUNCTION DOCUMENTATION
   bool SDLmm::Display::Flip () [inline]
       Swaps screen buffers.

       On hardware that supports double-buffering, this function sets up a
       flip and returns. The hardware will wait for vertical retrace, and then
       swap video buffers before the next video surface Blit or Lock will
       return. On hardware that doesn't support double-buffering, this is
       equivalent to calling UpdateRect() (i.e w/o parameters).

       The SDL_DOUBLEBUF flag must have been passed to SetVideoMode, when
       setting the video mode for this function to perform hardware flipping.

       Returns:
           true for success, false for failure.

   void SDLmm::Display::GetCaption (std::string & title, std::string & icon)
       Gets the window title and icon name.

       Parameters:

       title, icons
              references to strings which will be set to the title and icon
              titles.

   void SDLmm::Display::GetCaption (char ** title, char ** icon)
       Gets the window title and icon name.

       Parameters:

       title, icons
              pointers to char * which will be set to the title and icon
              titles.

   Display & SDLmm::Display::GetDisplay () [static]
       The one and only display.

   SDL_GrabMode SDLmm::Display::GrabInput (SDL_GrabMode mode)
       Grabs mouse and keyboard input.

       Grabbing means that the mouse is confined to the application window,
       and nearly all keyboard input is passed directly to the application,
       and not interpreted by a window manager, if any.

       When mode is SDL_GRAB_QUERY the grab mode is not changed, but the
       current grab mode is returned.

       Parameters:

       mode   one of the following:

             typedef enum {
               SDL_GRAB_QUERY,   // Query the current mode
               SDL_GRAB_OFF,     // Ungrab the mouse and keyboard
               SDL_GRAB_ON       // Grab the mouse and keyboard
             } SDL_GrabMode;


   bool SDLmm::Display::Iconify ()
       Iconify / minimize the application.

       If the application is running in a window managed environment SDL
       attempts to iconify / minimize it. If Iconify() is successful, the
       application will receive a SDL_APPACTIVE loss event.

       See also:
           EventHandler::HandleActiveEvent()

       Returns:
           true on success or false if iconification isn't supported or was
           refused by the window manager.

   bool SDLmm::Display::Init () [static]
       Initializes the video subsystem.

       Call this method to setup the video subsystem.

       Returns:
           true on success, false on error

   SDL_Rect ** SDLmm::Display::ListModes (SDL_PixelFormat * format = 0, Uint32
       flags = 0) [static]
       Returns a pointer to an array of available screen dimensions for the
       given format and video flags.

       Return a pointer to an array of available screen dimensions for the
       given format and video flags, sorted largest to smallest. Returns 0 if
       there are no dimensions available for a particular format, or -1 if any
       dimension is okay for the given format.

       If format is 0, the mode list will be for the format returned by
       VideoInfo()->vfmt(). The flag parameter is an OR'd combination of
       surface flags. The flags are the same as those used SetVideoMode and
       they play a strong role in deciding what modes are valid. For instance,
       if you pass SDL_HWSURFACE as a flag only modes that support hardware
       video surfaces will be returned.

       See also:
           SetVideoMode, VideoInfo, SRect

   void SDLmm::Display::Quit () [static]
       Shut down the video subsystem.

   void SDLmm::Display::SetCaption (const std::string & title, const
       std::string & icon)
       Sets the window title and icon name of the application.

       Parameters:

       title  the new title

       icon   the new icon title

   void SDLmm::Display::SetCaption (const char * title, const char * icon)
       Sets the window title and icon name of the application.

       Parameters:

       title  the new title

       icon   the new icon title

   bool SDLmm::Display::SetDisplayFormat () [inline, virtual]
       Convert the surface to the display format.

       This function converts the surface to the pixel format and colors of
       the video framebuffer, making it suitable for fast blitting onto the
       display surface.

       If you want to take advantage of hardware colorkey or alpha blit
       acceleration, you should set the colorkey and alpha value before
       calling this function.

       Returns:
           The functions returns true if the conversion succeeded or false
           otherwise. If the conversion failed, the BaseSurface object will
           not have changed.

       Note:
           Please note that this function doesn't return a new, modified
           object like the SDL_DisplayFormat() function does. Thus there is no
           need to manually free the old surface.

       See also:
           SetDisplayFormatAlpha(), SetAlpha(), SetColorKey()

       Reimplemented from SDLmm::BaseSurface.

   bool SDLmm::Display::SetDisplayFormatAlpha () [inline, virtual]
       Convert the surface to the display format.

       This function converts the surface to the pixel format and colors of
       the video framebuffer plus an alpha channel, making it suitable for
       fast blitting onto the display surface.

       If you want to take advantage of hardware colorkey or alpha blit
       acceleration, you should set the colorkey and alpha value before
       calling this function.

       Returns:
           The functions returns true if the conversion succeeded or false
           otherwise. If the conversion failed, the BaseSurface object will
           not have changed.

       Note:
           Please note that this function doesn't return a new, modified
           object like the SDL_DisplayFormatAlpha() function does. Thus there
           is no need to manually free the old surface.

       See also:
           SetDisplayFormat(), SetAlpha(), SetColorKey()

       Reimplemented from SDLmm::BaseSurface.

   void SDLmm::Display::SetIcon (BaseSurface & icon, Uint8 * mask = 0)
       Sets the icon for the display window.

       This function must be called before the first call to SetVideoMode().

       It takes an icon surface, and a mask in MSB format.

       If mask is zero (default), the entire icon surface will be used as the
       icon.

   bool SDLmm::Display::SetVideoMode (int w, int h, int bpp = 0, Uint32 flags
       = 0)
       Setup the video mode with the specified width, height and color depth.

       If bpp is zero, the color depth uses is that of the current display.

       Returns:
           Returns true for success and false for failure.

       Parameters:

       w, h   width and height

       bpp    color depth in bits-per-pixel

       flags  the video flags

   bool SDLmm::Display::ToggleFullScreen ()
       Toggles between fullscreen and windowed mode.

       Toggles the application between windowed and fullscreen mode, if
       supported. (X11 is the only target currently supported, BeOS support is
       experimental).

       Returns:
           true on success, false on failure.

   void SDLmm::Display::Update () [inline]
       Makes sure the entire screen is updated.

       This call is identical to calling UpdateRect() without arguments.

       This function should not be called if Display is locked!

       See also:
           UpdateRect, UpdateRects, SRect

   void SDLmm::Display::UpdateRect (SDL_Rect & rect)
       Makes sure the given area is updated on the display.

       This function should not be called if Display is locked!

       Parameters:

       rect   the rectangle to update.

       See also:
           UpdateRects, SRect

   void SDLmm::Display::UpdateRect (Sint32 x = 0, Sint32 y = 0, Sint32 w = 0,
       Sint32 h = 0)
       Makes sure the given area is updated on the screen.

       If 'x', 'y', 'w' and 'h' are all 0 (the default), UpdateRect() will
       update the entire display.

       This function should not be called if Display is locked!

       Parameters:

       x, y   the top left corner of the rectangle to update

       w, h   the width and height of the rectangle.

       See also:
           UpdateRect(SDL_Rect& rect), UpdateRects, SRect

   void SDLmm::Display::UpdateRects (int numrects, SDL_Rect * rects)
       Makes sure the given list of rectangles is updated on the display.

       This function should not be called if Display is locked!

       Note:
           It is adviced to call this function only once per frame, since each
           call has some processing overhead. This is no restriction since you
           can pass any number of rectangles each time.

       The rectangles are not automatically merged or checked for overlap. In
       general, the programmer can use his knowledge about his particular
       rectangles to merge them in an efficient way, to avoid overdraw.

       Parameters:

       numrects
              the number of rectangles in the array.

       rects  the array of rectangles to update

       See also:
           UpdateRect, SRect, Update

   int SDLmm::Display::VideoModeOK (int w, int h, int bpp, Uint32 flags)
       [static]
       Check to see if a particular video mode is supported.

       VideoModeOK returns 0 if the requested mode is not supported under any
       bit depth, or returns the bits-per-pixel of the closest available mode
       with the given width, height and requested surface flags (see
       SetVideoMode).

       The bits-per-pixel value returned is only a suggested mode. You can
       usually request any bpp you want when setting the video mode and SDL
       will emulate that color depth with a shadow video surface.

       The arguments to VideoModeOK are the same ones you would pass to
       SetVideoMode.

       See also:
           SetVideoMode, VideoInfo

   Display & SDLmm::Display::operator= (Display &) [protected]
       Dummy implementation of operator=() to stop initialization.

AUTHOR
       Generated automatically by Doxygen for SDLmm from the source code.



SDLmm                             16 Jul 2001                SDLmm::Display(3)
