SDLmm::BaseSurface(3)                                    SDLmm::BaseSurface(3)



NAME
       SDLmm::BaseSurface - An abstract base class for graphical surfaces.

SYNOPSIS
       #include <sdlmm_basesurface.h>

       Inherited by SDLmm::Display, and SDLmm::Surface.

   Public Methods
       virtual ~BaseSurface ()
           The destructor.
       SDL_Surface* GetSurface ()
       const SDL_Surface* GetSurface () const
       bool Lock ()
           Lock the surface to allow direct access to the surface pixels.
           Returns true if lock succeeded, false otherwise.
       void Unlock ()
           Unlock the surface.
       void SetPixel (int x, int y, Color color)
           Set the pixel to the color.
       void SetPixel1 (int x, int y, Color color)
           Set the pixel to the color.
       void SetPixel2 (int x, int y, Color color)
           Set the pixel to the color.
       void SetPixel3 (int x, int y, Color color)
           Set the pixel to the color.
       void SetPixel4 (int x, int y, Color color)
           Set the pixel to the color.
       void SetPixel (const SRect &point, Color color)
           Set the pixel to the color.
       Color GetPixel (int x, int y) const
           Get the color of the pixel.
       Color GetPixel (const SRect &point) const
           Get the color of the pixel.
       bool SetColorKey (Uint32 flag, Color key)
           Sets the color key (transparent pixel) in a blittable surface and
           enables or disables RLE blit acceleration.
       bool SetAlpha (Uint32 flag, Uint8 alpha)
           Adjust the alpha properties of this surface.
       virtual bool SetDisplayFormat ()=0
           Convert the surface to the display format.
       virtual bool SetDisplayFormatAlpha ()=0
           Convert the surface to the display format.
       bool SaveBMP (const char *file) const
           Save a BaseSurface object as a Windows bitmap file.
       bool SaveBMP (const std::string &file) const
           Save a BaseSurface object as a Windows bitmap file.

       Informational methods

           bool valid () const
               Returns true if this surface is initialized, false otherwise.
           Uint32 flags () const
               Returns the surface flags.
           const PixelFormat GetPixelFormat () const
               Returns the pixel format.
           PixelFormat GetPixelFormat ()
           int w () const
               Returns the width of the surface.
           int h () const
               Returns the height of the surface.
           Uint16 pitch () const
               Returns the scanline length in bytes.
           const SRect clip_rect () const
               Returns the surface clip rectangle.
           void* pixels ()
               Returns the pixel data, which can be used for low-level
               manipulation.
           const void* pixels () const
               Returns the pixel data, which can be used for low-level
               manipulation.
           struct private_hwdata* hwdata () const
               Returns the hardware-specific surface info.

       Clipping Methods

           void ResetClipRect ()
               Resets the clipping rectangle for the surface.
           void SetClipRect (const SDL_Rect &rect)
               Sets the clipping rectangle for the surface.
           void GetClipRect (SDL_Rect &rect) const
               Gets the clipping rectangle for the surface.

       Blitting / Filling

           int Blit (const BaseSurface &src)
               Fast blit the entire source surface onto this surface.
           int Blit (const BaseSurface &src, SDL_Rect &dstrect)
               Fast blit the entire source surface onto this surface at the
               specified coordinates.
           int Blit (const BaseSurface &src, const SPoint &dstpoint, SDL_Rect
               &dstrect)
               Fast blit the entire source surface onto this surface at the
               specified coordinates.
           int Blit (const BaseSurface &src, const SPoint &dstpoint)
               Fast blit the entire source surface onto this surface at the
               specified coordinates.
           int Blit (const BaseSurface &src, const SDL_Rect &srcrect, SDL_Rect
               &dstrect)
               Fast blit the specified area part of the source surface onto
               this surface at the specified coordinates.
           int Blit (const BaseSurface &src, const SDL_Rect &srcrect, const
               SPoint &dstpoint, SDL_Rect &dstrect)
               Fast blit the specified area part of the source surface onto
               this surface at the specified coordinates.
           int Blit (const BaseSurface &src, const SDL_Rect &srcrect, const
               SPoint &dstpoint)
               Fast blit the specified area part of the source surface onto
               this surface at the specified coordinates.
           bool Fill (Color color)
               Fast fill the surface with the specified color.
           bool Fill (Uint8 r, Uint8 g, Uint8 b)
               Fast fill the surface with the specified color.
           bool Fill (Uint8 r, Uint8 g, Uint8 b, Uint8 a)
               Fast fill the surface with the specified color.
           bool FillRect (SDL_Rect &dstrect, Color color)
               Performs a fast fill of the given rectangle with the specified
               color.
           bool FillRect (SDL_Rect &dstrect, Uint8 r, Uint8 g, Uint8 b)
               Performs a fast fill of the given rectangle with the specified
               color.
           bool FillRect (SDL_Rect &dstrect, Uint8 r, Uint8 g, Uint8 b, Uint8
               a)
               Performs a fast fill of the given rectangle with the specified
               color.

   Protected Methods
       virtual void SetSurface (SDL_Surface *surface)
       BaseSurface (SDL_Surface *surface)
           Constructor from an SDL_Surface*.
       BaseSurface (const BaseSurface &other)
       BaseSurface& operator= (const BaseSurface &other)

   Protected Attributes
       SDL_Surface* me
           The actual SDL_Surface allocated for this BaseSurface.

DETAILED DESCRIPTION
       An abstract base class for graphical surfaces.

       Surfaces represent areas of 'graphical' memory, memory that can be
       drawn to. The video framebuffer is returned as a VideoSurface by
       SetVideoMode() and GetVideoSurface(). Ordinary (non-framebuffer
       surfaces) are represented by a Surface. The clipping rectangle returned
       by clip_rect() can be set with SetClipRect() method.

       Author:
           David Hedbor <david@hedbor.org>

CONSTRUCTOR & DESTRUCTOR DOCUMENTATION
   SDLmm::BaseSurface::BaseSurface (SDL_Surface * surface) [inline, explicit,
       protected]
       Constructor from an SDL_Surface*.

       This creates a new BaseSurface object from an existing SDL_Surface.
       Note that ownership of the SDL_Surface is passed on to the BaseSurface.
       It's very important not to free the original surface since that will
       cause a problem when the object is destructed (SDL_Surface storage
       freed twice). Use with caution.

   SDLmm::BaseSurface::BaseSurface (const BaseSurface & other) [inline,
       protected]
   SDLmm::BaseSurface::~BaseSurface () [inline, virtual]
       The destructor.

MEMBER FUNCTION DOCUMENTATION
   int SDLmm::BaseSurface::Blit (const BaseSurface & src, const SDL_Rect &
       srcrect, const SPoint & dstpoint)
       Fast blit the specified area part of the source surface onto this
       surface at the specified coordinates.

       The choosen rectangle of the source surface will be blitted to this
       surface. If the source area is larger than the destination, clipping
       will occur. No scaling will be performed. Blitting should not be used
       on a locked surface. The entire surface will be copied to this surface
       using this function.

       Returns:
           If the blit is successful, it returns 0, otherwise it returns -1.
           If either of the surfaces were in video memory, and the blit
           returns -2, the video memory was lost. It should be reloaded with
           artwork and re-blitted.

       Parameters:

       src    the surface to blit from.

       srcrect
              the rectangular area to copy from the source surface.

       dstpoint
              the destination coordinates.

   int SDLmm::BaseSurface::Blit (const BaseSurface & src, const SDL_Rect &
       srcrect, const SPoint & dstpoint, SDL_Rect & dstrect) [inline]
       Fast blit the specified area part of the source surface onto this
       surface at the specified coordinates.

       The choosen rectangle of the source surface will be blitted to this
       surface. If the source area is larger than the destination, clipping
       will occur. No scaling will be performed. Blitting should not be used
       on a locked surface. The entire surface will be copied to this surface
       using this function. The final blit rectangle is saved in dstrect after
       all clipping is performed (srcrect is not modified).

       Returns:
           If the blit is successful, it returns 0, otherwise it returns -1.
           If either of the surfaces were in video memory, and the blit
           returns -2, the video memory was lost. It should be reloaded with
           artwork and re-blitted.

       Parameters:

       src    the surface to blit from.

       srcrect
              the rectangular area to copy from the source surface.

       dstpoint
              the destination coordinates.

       dstrect
              the final position and size is set upon returning.

   int SDLmm::BaseSurface::Blit (const BaseSurface & src, const SDL_Rect &
       srcrect, SDL_Rect & dstrect)
       Fast blit the specified area part of the source surface onto this
       surface at the specified coordinates.

       The choosen rectangle of the source surface will be blitted to this
       surface. If the source area is larger than the destination, clipping
       will occur. No scaling will be performed. Blitting should not be used
       on a locked surface. The entire surface will be copied to this surface
       using this function. The final blit rectangle is saved in dstrect after
       all clipping is performed (srcrect is not modified).

       Returns:
           If the blit is successful, it returns 0, otherwise it returns -1.
           If either of the surfaces were in video memory, and the blit
           returns -2, the video memory was lost. It should be reloaded with
           artwork and re-blitted.

       Parameters:

       src    the surface to blit from.

       srcrect
              the rectangular area to copy from the source surface.

       dstrect
              the destination coordinates. Only the position  is used (i.e
              width and height are ignored). The width and height are set upon
              returning.

   int SDLmm::BaseSurface::Blit (const BaseSurface & src, const SPoint &
       dstpoint)
       Fast blit the entire source surface onto this surface at the specified
       coordinates.

       The source surface will be blitted to this surface. If the source area
       is larger than the destination, clipping will occur. No scaling will be
       performed. Blitting should not be used on a locked surface. The entire
       surface will be copied to this surface using this function.

       Returns:
           If the blit is successful, it returns 0, otherwise it returns -1.
           If either of the surfaces were in video memory, and the blit
           returns -2, the video memory was lost. It should be reloaded with
           artwork and re-blitted.

       Parameters:

       src    the surface to blit from.

       dstpoint
              the destination coordinates.

   int SDLmm::BaseSurface::Blit (const BaseSurface & src, const SPoint &
       dstpoint, SDL_Rect & dstrect) [inline]
       Fast blit the entire source surface onto this surface at the specified
       coordinates.

       The source surface will be blitted to this surface. If the source area
       is larger than the destination, clipping will occur. No scaling will be
       performed. Blitting should not be used on a locked surface. The entire
       surface will be copied to this surface using this function. The final
       blit rectangle is saved in dstrect after all clipping is performed.

       Returns:
           If the blit is successful, it returns 0, otherwise it returns -1.
           If either of the surfaces were in video memory, and the blit
           returns -2, the video memory was lost. It should be reloaded with
           artwork and re-blitted.

       Parameters:

       src    the surface to blit from.

       dstpoint
              the destination coordinates.

       dstrect
              the final position and size is set upon returning.

   int SDLmm::BaseSurface::Blit (const BaseSurface & src, SDL_Rect & dstrect)
       Fast blit the entire source surface onto this surface at the specified
       coordinates.

       The source surface will be blitted to this surface. If the source area
       is larger than the destination, clipping will occur. No scaling will be
       performed. Blitting should not be used on a locked surface. The entire
       surface will be copied to this surface using this function. The final
       blit rectangle is saved in dstrect after all clipping is performed.

       Returns:
           If the blit is successful, it returns 0, otherwise it returns -1.
           If either of the surfaces were in video memory, and the blit
           returns -2, the video memory was lost. It should be reloaded with
           artwork and re-blitted.

       Parameters:

       src    the surface to blit from.

       dstrect
              the destination coordinates. Only the position  is used (i.e
              width and height are ignored). The width and height are set upon
              returning.

   int SDLmm::BaseSurface::Blit (const BaseSurface & src)
       Fast blit the entire source surface onto this surface.

       The source surface will be blitted to this surface. If the source area
       is larger than the destination, clipping will occur. No scaling will be
       performed. Blitting should not be used on a locked surface. The entire
       surface will be copied to this surface using this function.

       Returns:
           If the blit is successful, it returns 0, otherwise it returns -1.
           If either of the surfaces were in video memory, and the blit
           returns -2, the video memory was lost. It should be reloaded with
           artwork and re-blitted.

       Parameters:

       src    the surface to blit from.

   bool SDLmm::BaseSurface::Fill (Uint8 r, Uint8 g, Uint8 b, Uint8 a) [inline]
       Fast fill the surface with the specified color.

       If a clipping rectangle has been set using SetClipRect(), only the area
       within that rectangle will be filled.

       Returns:
           Returns true for success, false if there was an error.

       Parameters:

       r, g, b
              the red, green and blue color values.

       a      the alpha value

   bool SDLmm::BaseSurface::Fill (Uint8 r, Uint8 g, Uint8 b) [inline]
       Fast fill the surface with the specified color.

       If a clipping rectangle has been set using SetClipRect(), only the area
       within that rectangle will be filled.

       Returns:
           Returns true for success, false if there was an error.

       Parameters:

       r, g, b
              the red, green and blue color values.

   bool SDLmm::BaseSurface::Fill (Color color)
       Fast fill the surface with the specified color.

       If a clipping rectangle has been set using SetClipRect(), only the area
       within that rectangle will be filled.

       Returns:
           Returns true for success, false if there was an error.

       Parameters:

       color  the color to fill with, generated by MapRGB() or MapRGBA().

   bool SDLmm::BaseSurface::FillRect (SDL_Rect & dstrect, Uint8 r, Uint8 g,
       Uint8 b, Uint8 a) [inline]
       Performs a fast fill of the given rectangle with the specified color.

       If a clipping rectangle has been set using SetClipRect(), the area
       filled will be the intersection of the clipping rectangle and dstrect.

       Returns:
           Returns true for success, false if there was an error.

       Parameters:

       dstrect
              the rectangle to fill, upon returning it contains the  clipped
              rectangle that was actually filled.

       r, g, b
              the red, green and blue color values.

       a      the alpha value

   bool SDLmm::BaseSurface::FillRect (SDL_Rect & dstrect, Uint8 r, Uint8 g,
       Uint8 b) [inline]
       Performs a fast fill of the given rectangle with the specified color.

       If a clipping rectangle has been set using SetClipRect(), the area
       filled will be the intersection of the clipping rectangle and dstrect.

       Returns:
           Returns true for success, false if there was an error.

       Parameters:

       dstrect
              the rectangle to fill, upon returning it contains the  clipped
              rectangle that was actually filled.

       r, g, b
              the red, green and blue color values.

   bool SDLmm::BaseSurface::FillRect (SDL_Rect & dstrect, Color color)
       Performs a fast fill of the given rectangle with the specified color.

       If a clipping rectangle has been set using SetClipRect(), the area
       filled will be the intersection of the clipping rectangle and dstrect.

       Returns:
           Returns true for success, false if there was an error.

       Parameters:

       dstrect
              the rectangle to fill, upon returning it contains the  clipped
              rectangle that was actually filled.

       color  the color to fill with, generated by MapRGB() or MapRGBA().

   void SDLmm::BaseSurface::GetClipRect (SDL_Rect & rect) const
       Gets the clipping rectangle for the surface.

       Gets the clipping rectangle for a surface. When this surface is the
       destination of a blit, only the area within the clip rectangle is drawn
       into.

       Parameters:

       rect   reference to a rectangle which will be filled with the clipping
              rectangle of this surface.

       See also:
           SetClipRect, ResetClipRect, Blit

   Color SDLmm::BaseSurface::GetPixel (const SRect & point) const [inline]
       Get the color of the pixel.

       Warning:
           You can only use this function when the surface is locked.

   Color SDLmm::BaseSurface::GetPixel (int x, int y) const
       Get the color of the pixel.

       Warning:
           You can only use this function when the surface is locked.

   PixelFormat SDLmm::BaseSurface::GetPixelFormat () [inline]
   const PixelFormat SDLmm::BaseSurface::GetPixelFormat () const [inline]
       Returns the pixel format.

   const SDL_Surface * SDLmm::BaseSurface::GetSurface () const [inline]
   SDL_Surface * SDLmm::BaseSurface::GetSurface () [inline]
   bool SDLmm::BaseSurface::Lock ()
       Lock the surface to allow direct access to the surface pixels. Returns
       true if lock succeeded, false otherwise.

   void SDLmm::BaseSurface::ResetClipRect ()
       Resets the clipping rectangle for the surface.

       This functions resets the clipping to the full size of the surface.

       See also:
           GetClipRect, SetClipRect, Blit

   bool SDLmm::BaseSurface::SaveBMP (const std::string & file) const [inline]
       Save a BaseSurface object as a Windows bitmap file.

       Parameters:

       file   the file name to save to.

       Returns:
           True if the loading succeeded, false otherwise.

   bool SDLmm::BaseSurface::SaveBMP (const char * file) const
       Save a BaseSurface object as a Windows bitmap file.

       Parameters:

       file   the file name to save to.

       Returns:
           True if the loading succeeded, false otherwise.

   bool SDLmm::BaseSurface::SetAlpha (Uint32 flag, Uint8 alpha)
       Adjust the alpha properties of this surface.

       SetAlpha is used for setting the surface alpha value and / or enabling
       and disabling alpha blending.

       Parameters:

       flag   used to specify whether alpha blending should be used
              (SDL_SRCALPHA) and whether the surface should use RLE
              acceleration for blitting (SDL_RLEACCEL). flag can be an OR'd
              combination of these two options, one of these options or 0. If
              SDL_SRCALPHA is not passed as a flag then all alpha information
              is ignored when blitting the surface.

       alpha  the per-surface alpha value; a surface need not have an alpha
              channel to use per-surface alpha and blitting can still be
              accelerated with SDL_RLEACCEL.

       Note:
           The per-surface alpha value of 128 is considered a special case and
           is optimised, so it's much faster than other per-surface values.

       Returns:
           true for success or false if there was an error.

   void SDLmm::BaseSurface::SetClipRect (const SDL_Rect & rect)
       Sets the clipping rectangle for the surface.

       Sets the clipping rectangle for a surface. When this surface is the
       destination of a blit, only the area within the clip rectangle will be
       drawn into.

       Parameters:

       rect   The rectangle pointed to by rect will be clipped to the edges of
              the surface so that the clip rectangle for a surface can never
              fall outside the edges of the surface.

       See also:
           GetClipRect, ResetClipRect, Blit

   bool SDLmm::BaseSurface::SetColorKey (Uint32 flag, Color key)
       Sets the color key (transparent pixel) in a blittable surface and
       enables or disables RLE blit acceleration.

       RLE acceleration can substantially speed up blitting of images with
       large horizontal runs of transparent pixels (i.e., pixels that match
       the key value). The key must be of the same pixel format as the
       surface, MapRGB() is often useful for obtaining an acceptable value.

       Returns:
           Returns true for success, false if there was an error.

       Parameters:

       flag   If

   bool SDLmm::BaseSurface::SetDisplayFormat () [pure 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 in SDLmm::Display, and SDLmm::Surface.

   bool SDLmm::BaseSurface::SetDisplayFormatAlpha () [pure 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 in SDLmm::Display, and SDLmm::Surface.

   void SDLmm::BaseSurface::SetPixel (const SRect & point, Color color)
       [inline]
       Set the pixel to the color.

       Warning:
           You can only use this function when the surface is locked.

   void SDLmm::BaseSurface::SetPixel (int x, int y, Color color)
       Set the pixel to the color.

       Warning:
           You can only use this function when the surface is locked.

   void SDLmm::BaseSurface::SetPixel1 (int x, int y, Color color)
       Set the pixel to the color.

       Warning:
           You can only use this function when the surface is locked and when
           the bytes per pixel is 1.

   void SDLmm::BaseSurface::SetPixel2 (int x, int y, Color color)
       Set the pixel to the color.

       Warning:
           You can only use this function when the surface is locked and when
           the bytes per pixel is 2.

   void SDLmm::BaseSurface::SetPixel3 (int x, int y, Color color)
       Set the pixel to the color.

       Warning:
           You can only use this function when the surface is locked and when
           the bytes per pixel is 3.

   void SDLmm::BaseSurface::SetPixel4 (int x, int y, Color color)
       Set the pixel to the color.

       Warning:
           You can only use this function when the surface is locked and when
           the bytes per pixel is 4.

   void SDLmm::BaseSurface::SetSurface (SDL_Surface * surface) [inline,
       protected, virtual]
   void SDLmm::BaseSurface::Unlock ()
       Unlock the surface.

   const SRect SDLmm::BaseSurface::clip_rect () const [inline]
       Returns the surface clip rectangle.

   Uint32 SDLmm::BaseSurface::flags () const [inline]
       Returns the surface flags.

   int SDLmm::BaseSurface::h () const [inline]
       Returns the height of the surface.

   struct private_hwdata * SDLmm::BaseSurface::hwdata () const [inline]
       Returns the hardware-specific surface info.

   BaseSurface & SDLmm::BaseSurface::operator= (const BaseSurface & other)
       [inline, protected]
   Uint16 SDLmm::BaseSurface::pitch () const [inline]
       Returns the scanline length in bytes.

   const void * SDLmm::BaseSurface::pixels () const [inline]
       Returns the pixel data, which can be used for low-level manipulation.

       Warning:
           You can only modify this surface when the surface is locked.

   void * SDLmm::BaseSurface::pixels () [inline]
       Returns the pixel data, which can be used for low-level manipulation.

       Warning:
           You can only modify this surface when the surface is locked.

   bool SDLmm::BaseSurface::valid () const [inline]
       Returns true if this surface is initialized, false otherwise.

       Warning:
           Using an uninitialzied surface can cause many problems.

   int SDLmm::BaseSurface::w () const [inline]
       Returns the width of the surface.

MEMBER DATA DOCUMENTATION
   SDL_Surface * SDLmm::BaseSurface::me [protected]
       The actual SDL_Surface allocated for this BaseSurface.

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



SDLmm                             16 Jul 2001            SDLmm::BaseSurface(3)
