OSDLSurface.h

Go to the documentation of this file.

#ifndef OSDL_SURFACE_H_
#define OSDL_SURFACE_H_


#include "OSDLImage.h"              // for ImageException
#include "OSDLUprightRectangle.h"   // for UprightRectangle
#include "OSDLPalette.h"            // for ColorCount


#include "Ceylan.h"                 // for EventSource, Lockable, SmartResource

#include <string>
#include <list>



// The internal actual surface.
struct SDL_Surface ;



namespace OSDL
{

    namespace Video 
    {
    

        namespace TwoDimensional
        {
        
            // Necessary for many drawing operations on surfaces.
            class Point2D ;
            
            // A surface can have widgets.
            class Widget ;
        
        }
        
        
        // Surfaces can be palettized.
        class Palette ;
        
        using namespace Pixels ;
        
        
        class OSDL_DLL SurfaceEvent : public Ceylan::Event
        {
        
            public:
        
                explicit SurfaceEvent( Ceylan::EventSource & source ) throw() ;
                SurfaceEvent() throw() ;
            
                virtual ~SurfaceEvent() throw() ;
                
        } ;
        
    
        
        class OSDL_DLL VideoMemoryLostException : public VideoException
        {
        
            public:
            
                VideoMemoryLostException( const std::string & message ) 
                    throw() ;
                
                VideoMemoryLostException() throw() ;
                
                virtual ~VideoMemoryLostException() throw() ;
            
        } ;
        
        
                
        class OSDL_DLL Surface : 
            public TwoDimensional::UprightRectangle, 
            public Ceylan::EventSource,
            public Ceylan::Lockable, 
            public Ceylan::SmartResource
        {
    
    
            public:
            
            
                enum DisplayType { 
                    BackBuffer, 
                    ClassicalScreenSurface, 
                    OpenGLScreenSurface 
                } ;
            
            
            
                /*
                 * These flags can apply to all Surfaces.
                 *
                 */


                static const Ceylan::Flags Software ;              


                static const Ceylan::Flags Hardware ;              
                
                
                static const Ceylan::Flags AsynchronousBlit ;
                    
                                    
                static const Ceylan::Flags ExclusivePalette ;   
                
                
                static const Ceylan::Flags HardwareAcceleratedBlit ;
                
                
                static const Ceylan::Flags ColorkeyBlit ;          
                
                
                static const Ceylan::Flags RLEColorkeyBlit  ;      
                
                
                static const Ceylan::Flags AlphaBlendingBlit ;     

                static const Ceylan::Flags Preallocated ;      


                static const Ceylan::Flags RLEColorkeyBlitAvailable ;      



                /*
                 * These flags can only apply to <b>display</b> Surfaces.
                 *
                 */


                static const Ceylan::Flags AnyPixelFormat ;
                
                
                static const Ceylan::Flags DoubleBuffered ;
                
                
                static const Ceylan::Flags FullScreen ;
                
                
                static const Ceylan::Flags OpenGL ;
                
                static const Ceylan::Flags Resizable ;
    

                explicit Surface( SDL_Surface & surface, 
                    DisplayType displayType = BackBuffer ) throw() ;
                
                
                
                Surface( Ceylan::Flags flags, Length width, Length height, 
                    BitsPerPixel depth = 32,
                    Pixels::ColorMask redMask   = 0, 
                    Pixels::ColorMask greenMask = 0,
                    Pixels::ColorMask blueMask  = 0, 
                    Pixels::ColorMask alphaMask = 0 ) 
                        throw( VideoException ) ;
                    
                             
                 
                virtual ~Surface() throw() ;
    
                
                virtual Clonable & clone() const 
                    throw( Ceylan::ClonableException ) ;
                

                virtual SDL_Surface & getSDLSurface() const throw() ;
                
                
                virtual void setSDLSurface( SDL_Surface & newSurface, 
                    DisplayType displayType = BackBuffer ) throw() ;
    
    
    
                virtual DisplayType getDisplayType() const throw() ;
    
    
                virtual void setDisplayType( DisplayType newDisplayType )
                    throw() ;
                
                            
                virtual Ceylan::Flags getFlags() const throw() ;

                
                virtual void setFlags( Ceylan::Flags newFlags ) throw() ;
    
    
                virtual void convertToDisplay( bool alphaChannelWanted = true ) 
                    throw( VideoException ) ;
    
    
                virtual void setAlpha( Ceylan::Flags flags, 
                    Pixels::ColorElement newAlpha ) throw( VideoException ) ;
                
                
                virtual void setColorKey( Ceylan::Flags flags, 
                    Pixels::PixelColor keyPixelColor ) throw( VideoException ) ;
                
                
                virtual void setColorKey( Ceylan::Flags flags, 
                        Pixels::ColorDefinition keyColorDef ) 
                    throw( VideoException ) ;
                
                
                virtual void convertFromColorKeyToAlphaChannel() 
                    throw( VideoException ) ; 
                
                
                virtual bool setPalette( Palette & newPalette, 
                    ColorCount startingColorIndex = 0,
                    ColorCount numberOfColors = 0, 
                    Ceylan::Flags targettedPalettes = 
                        Palette::Logical | Palette::Physical ) 
                    throw() ;
                
                
                
                virtual PixelFormat & getPixelFormat() const throw() ;
                
                virtual void setPixelFormat( PixelFormat & newFormat ) throw() ;


    
                virtual Pitch getPitch() const throw() ;
                
                virtual void setPitch( Pitch newPitch ) throw() ;


                virtual Length getWidth() const throw() ;
                
                
                virtual void setWidth( Length newWidth ) throw() ;
    
    
    
                virtual Length getHeight() const throw() ;
                
                
                virtual void setHeight( Length newHeight ) throw() ;
                
                
                virtual void resize( Length newWidth, Length newHeight, 
                    bool scaleContent = false ) throw() ;


                virtual BitsPerPixel getBitsPerPixel() const throw() ;
                
                
                virtual void setBitsPerPixel( BitsPerPixel newBitsPerPixel )
                    throw() ;
                
                
                virtual BytesPerPixel getBytesPerPixel() const throw() ;
                
                
                virtual void setBytesPerPixel( BytesPerPixel newBytesPerPixel )
                    throw() ;
                
                
                                                
                virtual void * getPixels() const throw() ;              
                
                
                virtual void setPixels( void * newPixels ) throw()  ;
                        
                                                        
                                     
                virtual bool fill( 
                        Pixels::ColorDefinition colorDef = Pixels::Black ) 
                    throw() ; 

                
                virtual bool clear() throw() ; 


                virtual Surface & flipVertical() const throw() ; 


                virtual Surface & flipHorizontal() const throw() ; 



                virtual std::string describePixelAt( 
                    Coordinate x, Coordinate y ) throw() ;
                
                

                virtual Pixels::PixelColor getPixelColorAt( 
                        Coordinate x, Coordinate y ) const
                    throw ( VideoException ) ;


                virtual Pixels::ColorDefinition getColorDefinitionAt( 
                        Coordinate x, Coordinate y ) 
                    const throw ( VideoException ) ;
                 
                 
                virtual void putRGBAPixelAt( 
                    Coordinate x, Coordinate y, 
                    ColorElement red, ColorElement green, ColorElement blue, 
                    ColorElement alpha = AlphaOpaque, 
                    bool blending = true, bool clipping = true, 
                    bool locking = false ) throw( VideoException ) ;


                virtual void putColorDefinitionAt( Coordinate x, Coordinate y, 
                    ColorDefinition colorDef, 
                    bool blending = true, bool clipping = true, 
                    bool locking = false ) throw( VideoException ) ;


                virtual void putPixelColorAt( Coordinate x, Coordinate y, 
                    PixelColor convertedColor, ColorElement alpha,
                    bool blending = true, bool clipping = true, 
                    bool locking = false ) throw( VideoException ) ;
                
                
                virtual bool setAlphaForColor( Pixels::ColorDefinition colorDef,
                    Pixels::ColorElement newAlpha ) throw() ;
                    
                    
                virtual bool drawHorizontalLine( 
                    Coordinate xStart, Coordinate xStop, Coordinate y, 
                    Pixels::ColorElement red, Pixels::ColorElement green, 
                    Pixels::ColorElement blue, 
                    Pixels::ColorElement alpha = Pixels::AlphaOpaque )
                        throw() ;
            
                    
                virtual bool drawHorizontalLine( 
                    Coordinate xStart, Coordinate xStop, Coordinate y, 
                    Pixels::PixelColor actualColor ) throw() ;
            
                    
                virtual bool drawHorizontalLine( 
                    Coordinate xStart, Coordinate xStop, Coordinate y, 
                    Pixels::ColorDefinition colorDef = Pixels::White )
                        throw() ;
                    
                    
                virtual bool drawVerticalLine(
                    Coordinate x, Coordinate yStart, Coordinate yStop, 
                    Pixels::ColorElement red, Pixels::ColorElement green, 
                    Pixels::ColorElement blue, 
                    Pixels::ColorElement alpha = Pixels::AlphaOpaque )
                        throw() ;                               
                    
                    
                virtual bool drawVerticalLine(
                        Coordinate x, Coordinate yStart, Coordinate yStop, 
                        Pixels::ColorDefinition colorDef = Pixels::White )
                    throw() ;                               


                virtual bool drawLine(
                    Coordinate xStart, Coordinate yStart, 
                    Coordinate xStop, Coordinate yStop, 
                    Pixels::ColorElement red, Pixels::ColorElement green, 
                    Pixels::ColorElement blue, 
                    Pixels::ColorElement alpha = Pixels::AlphaOpaque )
                        throw() ;
        
                    
                virtual bool drawLine(
                    Coordinate xStart, Coordinate yStart, 
                    Coordinate xStop, Coordinate yStop, 
                    Pixels::ColorDefinition = Pixels::White )
                        throw() ;
                
                    
                virtual bool drawCross( const TwoDimensional::Point2D & center, 
                        Pixels::ColorDefinition colorDef = Pixels::White, 
                        Length squareEdge = 5 )
                    throw() ;
                    
                    
                virtual bool drawCross( Coordinate xCenter, Coordinate yCenter, 
                        Pixels::ColorDefinition colorDef = Pixels::White, 
                        Length squareEdge = 5 )
                    throw() ;
                    
                    
                virtual bool drawEdges( 
                    Pixels::ColorDefinition edgeColor = Pixels::White, 
                    Length edgeWidth = 1 ) throw() ;
                    
                        
                virtual bool drawBox( const UprightRectangle & rectangle, 
                    Pixels::ColorElement red, Pixels::ColorElement green, 
                    Pixels::ColorElement blue, 
                    Pixels::ColorElement alpha = Pixels::AlphaOpaque,
                    bool filled = true ) throw() ;
                
                
                virtual bool drawBox( const UprightRectangle & rectangle, 
                        Pixels::ColorDefinition colorDef = Pixels::White, 
                        bool filled = true ) 
                    throw() ;
                

                virtual bool drawCircle( 
                    Coordinate xCenter, Coordinate yCenter, 
                    Length radius, 
                    Pixels::ColorElement red, Pixels::ColorElement green, 
                    Pixels::ColorElement blue, 
                    Pixels::ColorElement alpha = Pixels::AlphaOpaque,
                    bool filled = true, bool blended = true ) throw() ;
                
                
                
                virtual bool drawCircle( 
                    Coordinate xCenter, Coordinate yCenter, 
                    Length radius, 
                    Pixels::ColorDefinition colorDef = Pixels::White, 
                    bool filled = true, bool blended = true ) throw() ;
                
                
                virtual bool drawDiscWithEdge( 
                    Coordinate xCenter, Coordinate yCenter, 
                    Length outerRadius, Length innerRadius, 
                    Pixels::ColorDefinition ringColorDef = Pixels::Blue, 
                    Pixels::ColorDefinition discColorDef = Pixels::White, 
                    bool blended = true )
                        throw() ;
                


                virtual bool drawEllipse( 
                    Coordinate xCenter, Coordinate yCenter,
                    Length horizontalRadius, Length verticalRadius,             
                    Pixels::ColorElement red, Pixels::ColorElement green, 
                    Pixels::ColorElement blue, 
                    Pixels::ColorElement alpha = Pixels::AlphaOpaque,
                    bool filled = true ) throw() ;



                virtual bool drawEllipse( 
                    Coordinate xCenter, Coordinate yCenter, 
                    Length horizontalRadius, Length verticalRadius,
                    Pixels::ColorDefinition colorDef, bool filled = true )
                        throw() ;

                            
                                                        
                virtual bool drawPie( 
                    Coordinate xCenter, Coordinate yCenter, 
                    Length radius, 
                    Ceylan::Maths::AngleInDegrees angleStart, 
                    Ceylan::Maths::AngleInDegrees angleStop,
                    Pixels::ColorElement red, Pixels::ColorElement green, 
                    Pixels::ColorElement blue, 
                    Pixels::ColorElement alpha = Pixels::AlphaOpaque ) 
                        throw() ;
            
            
                    
                virtual bool drawPie( 
                    Coordinate xCenter, Coordinate yCenter, 
                    Length radius,
                    Ceylan::Maths::AngleInDegrees angleStart, 
                    Ceylan::Maths::AngleInDegrees angleStop, 
                    Pixels::ColorDefinition colorDef ) throw() ;



                virtual bool drawTriangle( 
                    Coordinate x1, Coordinate y1, 
                    Coordinate x2, Coordinate y2, 
                    Coordinate x3, Coordinate y3, 
                    Pixels::ColorElement red, Pixels::ColorElement green, 
                    Pixels::ColorElement blue, 
                    Pixels::ColorElement alpha = Pixels::AlphaOpaque,
                    bool filled = true ) throw() ;



                virtual bool drawTriangle( 
                    Coordinate x1, Coordinate y1, 
                    Coordinate x2, Coordinate y2, 
                    Coordinate x3, Coordinate y3, 
                    Pixels::ColorDefinition colorDef, 
                    bool filled = true ) throw() ;
                    


                virtual bool drawTriangle( 
                    const TwoDimensional::Point2D & p1, 
                    const TwoDimensional::Point2D & p2, 
                    const TwoDimensional::Point2D & p3,
                    Pixels::ColorElement red, Pixels::ColorElement green, 
                    Pixels::ColorElement blue, 
                    Pixels::ColorElement alpha = Pixels::AlphaOpaque,
                    bool filled = true ) throw() ;



                virtual bool drawTriangle( 
                    const TwoDimensional::Point2D & p1, 
                    const TwoDimensional::Point2D & p2, 
                    const TwoDimensional::Point2D & p3, 
                    Pixels::ColorDefinition colorDef, bool filled = true )
                        throw() ;
                    
                    
                    
                virtual bool drawPolygon( 
                    const std::list<TwoDimensional::Point2D *> summits,
                    Coordinate x, Coordinate y,
                    Pixels::ColorElement red, Pixels::ColorElement green, 
                    Pixels::ColorElement blue, 
                    Pixels::ColorElement alpha = Pixels::AlphaOpaque,
                    bool filled = true ) throw() ;              



                virtual bool drawPolygon( 
                    const std::list<TwoDimensional::Point2D *> summits, 
                    Coordinate x, Coordinate y,
                    Pixels::ColorDefinition colorDef, bool filled = true )
                        throw() ;   
                    
                        
                 virtual bool drawGrid( 
                    Length columnStride = 20, 
                    Length rowStride = 20, 
                    Pixels::ColorDefinition lineColor = Pixels::White,
                    bool fillBackground = false,  
                    Pixels::ColorDefinition backgroundColor = Pixels::Black )
                        throw() ; 
                        
                        
                        
                virtual bool printText( const std::string & text,
                    Coordinate x, Coordinate y, 
                    Pixels::ColorElement red, Pixels::ColorElement green, 
                    Pixels::ColorElement blue, 
                    Pixels::ColorElement alpha = Pixels::AlphaOpaque )
                        throw() ; 
                    
                    
                virtual bool printText( const std::string & text,
                        Coordinate x, Coordinate y, 
                        ColorDefinition colorDef = Pixels::White ) 
                    throw() ;
                    
                
                
                    
                // Blit section.
                
                    
                 virtual bool blitTo( Surface & targetSurface ) 
                    const throw( VideoException ) ;
                    
                    
                 virtual bool blitTo( Surface & targetSurface, 
                    Coordinate x, Coordinate y ) const throw( VideoException ) ;
                    
                    
                 virtual bool blitTo( Surface & targetSurface, 
                    const TwoDimensional::Point2D & location ) const 
                        throw( VideoException ) ;
        
                 
                 virtual bool blitTo( 
                        Surface & targetSurface, 
                        const TwoDimensional::UprightRectangle 
                            & sourceRectangle, 
                        const TwoDimensional::Point2D & destinationLocation ) 
                    const throw( VideoException ) ;
                 
                
                
                /*
                 * Rotozoom section.
                 *
                 * With antialiasing not enabled, rotozoom primitives are fast
                 * enough even for some realtime effects, if the CPU is fast 
                 * or bitmaps are small. 
                 *
                 * With antialiasing, the routines are typically used for
                 * pre-rendering content in higher quality (i.e. smoothing),
                 * hence a new render surface is created each time rotozoom 
                 * is called.
                 *
                 */
                 
                
                
                virtual Surface & zoom( 
                        Ceylan::Maths::Real abscissaZoomFactor, 
                        Ceylan::Maths::Real ordinateZoomFactor, 
                        bool antialiasing = true ) 
                    const throw( VideoException ) ; 
                
                
                
                virtual Surface & rotoZoom( 
                        Ceylan::Maths::AngleInDegrees angle, 
                        Ceylan::Maths::Real zoomFactor, 
                        bool antialiasing = true ) 
                    const throw( VideoException ) ; 
                
                
                
                virtual Surface & rotoZoom( 
                        Ceylan::Maths::AngleInDegrees angle, 
                        Ceylan::Maths::Real abscissaZoomFactor, 
                        Ceylan::Maths::Real ordinateZoomFactor,
                        bool antialiasing = true ) 
                    const throw( VideoException ) ; 
                
                
                
                    
                // Image section.
                    
                    
                virtual UprightRectangle & getClippingArea() const throw() ;
                
    
                virtual void setClippingArea( 
                    UprightRectangle & newClippingArea ) throw() ;
                    
                    
                    
                virtual void loadImage( const std::string & filename,
                        bool blitOnly = false,
                        bool convertToDisplayFormat = true,
                        bool convertWithAlpha = true ) 
                    throw( TwoDimensional::ImageException ) ;
                
                 
                 
                virtual void loadJPG( const std::string & filename,
                        bool blitOnly = false,
                        bool convertToDisplayFormat = true,
                        bool convertWithAlpha = true ) 
                    throw( TwoDimensional::ImageException ) ;
                
                    
                                
                virtual void loadPNG( const std::string & filename,
                        bool blitOnly = false,
                        bool convertToDisplayFormat = true,
                        bool convertWithAlpha = true ) 
                    throw( TwoDimensional::ImageException ) ;
                
                
                                
                virtual void loadBMP( const std::string & filename,
                        bool blitOnly = false,
                        bool convertToDisplayFormat = true,
                        bool convertWithAlpha = true ) 
                    throw( TwoDimensional::ImageException ) ;
                
                
                                
                virtual void loadGIF( const std::string & filename,
                        bool blitOnly = false,
                        bool convertToDisplayFormat = true,
                        bool convertWithAlpha = true ) 
                    throw( TwoDimensional::ImageException ) ;
                
                
                                
                virtual void loadLBM( const std::string & filename,
                        bool blitOnly = false,
                        bool convertToDisplayFormat = true,
                        bool convertWithAlpha = true ) 
                    throw( TwoDimensional::ImageException ) ;
                
                
                                
                virtual void loadPCX( const std::string & filename,
                        bool blitOnly = false,
                        bool convertToDisplayFormat = true,
                        bool convertWithAlpha = true ) 
                    throw( TwoDimensional::ImageException ) ;
                
                        
                                
                virtual void loadPNM( const std::string & filename,
                        bool blitOnly = false,
                        bool convertToDisplayFormat = true,
                        bool convertWithAlpha = true ) 
                    throw( TwoDimensional::ImageException ) ;
                
                
                                
                virtual void loadTGA( const std::string & filename,
                        bool blitOnly = false,
                        bool convertToDisplayFormat = true,
                        bool convertWithAlpha = true ) 
                    throw( TwoDimensional::ImageException ) ;
                
                                
                                
                virtual void loadXPM( const std::string & filename,
                        bool blitOnly = false,
                        bool convertToDisplayFormat = true,
                        bool convertWithAlpha = true ) 
                    throw( TwoDimensional::ImageException ) ;
            


                virtual void savePNG( const std::string & filename, 
                        bool overwrite = true ) 
                    throw( TwoDimensional::ImageException ) ;
                                
                
                
                virtual void saveBMP( const std::string & filename, 
                        bool overwrite = true ) 
                    throw( TwoDimensional::ImageException ) ;
                
                
                
                virtual void update() throw( VideoException ) ;
            
            
            
                 virtual void updateRectangles( 
                        const std::list<UprightRectangle *> & listRects )
                    throw( VideoException ) ;
                    
                    
                 virtual void updateRectangle( const UprightRectangle & rect )  
                    throw( VideoException ) ;
                
                    
                 virtual void updateRectangle( 
                    Coordinate x, Coordinate y, Length width, Length height )
                        throw( VideoException ) ;
                    


                virtual void setRedrawState( bool needsToBeRedrawn ) throw() ;

                
                virtual bool getRedrawState() const throw() ;
                
                        
                                
                virtual void redraw() throw() ;
                
                
                virtual void redrawInternal() throw() ;
                 
            
                virtual bool isInternalSurfaceAvailable() const throw() ;
                 
                 
                virtual void addWidget( TwoDimensional::Widget & widget ) 
                    throw( VideoException ) ;
        
        
                Surface & getWidgetRenderTarget() throw() ; 
        
                         
                virtual void putWidgetToFront( TwoDimensional::Widget & widget )
                    throw( VideoException ) ;
    

                virtual void putWidgetToBack( TwoDimensional::Widget & widget ) 
                   throw( VideoException ) ;
    
    
                virtual void centerMousePosition() throw() ;
                
                
                virtual void setMousePosition( 
                    Coordinate newX = 0, Coordinate newY = 0 ) throw() ;


    
                // Lockable section.
    
    
                 virtual bool mustBeLocked() const throw() ;
        
        
    
                // Measurable section.


                virtual Ceylan::System::Size getSizeInMemory() const throw() ;
            
            
                
                virtual bool displayData( 
                    const Ceylan::Maths::IntegerData * dataArray, 
                    Ceylan::Uint32 dataCount,
                    Pixels::ColorDefinition pencilColor, 
                    Pixels::ColorDefinition captionColor,
                    Pixels::ColorDefinition backgroundColor,
                    const std::string & caption = "", 
                    const UprightRectangle * inBox = 0 ) 
                        throw() ;
                    
                
                virtual const std::string toString( 
                        Ceylan::VerbosityLevels level = Ceylan::high ) 
                    const throw() ;



                // Static section.

                
                static Surface & LoadImage( const std::string & filename,
                        bool convertToDisplayFormat = true,
                        bool convertWithAlpha = true ) 
                    throw( TwoDimensional::ImageException ) ;
    
    
        
                static std::string InterpretFlags( Ceylan::Flags flags ) 
                    throw() ;
    
    
                static const Length graphAbscissaOffset ;
                
                static const Length graphOrdinateOffset ;

                
                static const Length captionAbscissaOffset ;
                
                static const Length captionOrdinateOffset ;
                
                
                
                    
            protected:



                virtual void preUnlock() throw() ;
                
                
                virtual void postLock() throw() ;
                                 
    
    
                typedef Ceylan::Sint16 Offset ;

                    
                explicit Surface() throw() ;
        
        
                 
                inline Offset getOffset() const throw() ;
                
                inline void setOffset( Offset offset ) throw() ;
                
                                
                virtual void flush() throw() ;
                            
                
                virtual void inconsistencyDetected( 
                    const std::string & message ) const throw() ;
                
                
                SDL_Surface * _surface ;
    
    
                DisplayType _displayType ;
                                
    
                bool _mustBeLocked ;
                
            
        
            private:
                
                
                bool _needsRedraw ;


                                    
                Surface( const Surface & source ) throw() ;
            
            
                Surface & operator = ( const Surface & source ) throw() ;
                
                
        } ;
                    
    }
    
}



OSDL_DLL std::ostream & operator << ( std::ostream & os, 
    OSDL::Video::Surface & s ) throw() ;


#endif // OSDL_SURFACE_H_

---