OSDLFont.h

Go to the documentation of this file.

#ifndef OSDL_FONT_H_
#define OSDL_FONT_H_



#include "OSDLVideo.h"        // for VideoException
#include "OSDLVideoTypes.h"   // for Length, SignedLength, etc.
#include "OSDLPixel.h"        // for ColorElement, ColorDefinition
#include "OSDLSurface.h"      // for Surface

#include "Ceylan.h"           // for Uint32, inheritance

#include <string>

    


namespace OSDL
{


    namespace Video
    {


        // Fonts are rendered to surfaces.
        class Surface ;


        namespace TwoDimensional
        {
            
            
            
            class OSDL_DLL TextException: public VideoException 
            { 
            
                public: 
                
                    explicit TextException( const std::string & reason ) 
                        throw() ; 
                    virtual ~TextException() throw() ; 
                    
            } ;
                
            
            
            namespace Text
            {   
            

                typedef Length PointSize ;
                
                
                typedef Ceylan::Uint16 FontIndex ;
                
                
                
                typedef Ceylan::Uint16 Height ;
                
                typedef Ceylan::Sint16 SignedHeight ;
                
                
                typedef Ceylan::Uint16 Width ;
                
                typedef Ceylan::Sint16 SignedWidth ;
                
                
                typedef int RenderingStyle ;
                
                                
                typedef Ceylan::Uint16 TextIndex ;
                    
                                    
                typedef Ceylan::Uint16 LineNumber ;
                                    
                                    
                
                enum HorizontalAlignment { Left, WidthCentered, Right } ;
                
                enum VerticalAlignment { Top, HeightCentered, Bottom } ;
                
                
                
                class OSDL_DLL Font : public Ceylan::TextDisplayable
                {
                
                
                    public:
                    


                        enum RenderQuality { Solid, Shaded, Blended } ;
                


                        /*
                         * The Ceylan cache manager allows to reference
                         * resources based on their key. 
                         * 
                         * Here, the resource is a text rendering (a surface)
                         * and the key is made from the corresponding text 
                         * (be it Latin-1 char or std::string) <em>and</em> 
                         * from the text color <em>and</em> from the desired
                         * rendering quality. 
                         *
                         * I.e we request a red 'Solid' 'c', or a blue 'Shaded'
                         * "Some text", and we expect the cache to return a
                         * corresponding already computed rendering, i.e. a
                         * surface, if available.
                         *
                         * The key therefore is a composite type (a text, a
                         * color and a quality), which could be modeled at 
                         * least thanks to two patterns :
                         *   - a triple made from STL : when quality was not
                         * specifically managed, a
                         * std::pair<Latin1Char,ColorDefinition> could be 
                         * used, since the STL pairs have the '<' (less)
                         * operators defined (necessary for the ordering
                         * of the std::map ordering). 
                         * However ColorDefinition is a struct, with no
                         * specific '<' operator defined, which would be 
                         * needed here. 
                         * Moreover, for three parameters, the STL is 
                         * probably less useful
                         *   - a dedicated key class, which defines that same
                         * operator '<' 
                         *
                         * We thus chose the latter solution here.
                         *
                         */

                        
                        class OSDL_DLL CharColorQualityKey
                        {
                        
                        
                            public:
                                
                                
                                CharColorQualityKey( 
                                        Ceylan::Latin1Char character, 
                                        Pixels::ColorDefinition color,
                                        RenderQuality quality ) throw() :
                                    _character( character ),
                                    _color( color ),
                                    _quality( quality )
                                {
                                
                                }
                                
                                
                                inline bool operator < ( 
                                        const CharColorQualityKey & other ) 
                                    const throw() 
                                {

                                    if ( _character < other._character )
                                        return true ;
        
                                    if ( _character > other._character )
                                        return false ;
        
                                    if ( Pixels::isLess( _color, 
                                            other._color ) )
                                        return true ;
                                    
                                    if ( Pixels::isLess( other._color, 
                                            _color ) )
                                        return false ;
                                    
                                    return _quality < other._quality ;
                                                                            
                                }   
                                
                                
                            private:                                
                            
                                Ceylan::Latin1Char _character ;
                                
                                Pixels::ColorDefinition _color ;
                                    
                                RenderQuality _quality ;
                        
                        
                        } ;
                        
                                

                        class OSDL_DLL StringColorQualityKey
                        {
                        

                            public:
                                
                                
                                StringColorQualityKey( 
                                    const std::string & text, 
                                    Pixels::ColorDefinition color, 
                                    RenderQuality quality )
                                        throw() :
                                    _text( text ),
                                    _color( color ),
                                    _quality( quality )
                                {
                                
                                }

                                
                                inline bool operator < ( 
                                        const StringColorQualityKey & other ) 
                                    const throw() 
                                {   
                                    
                                    /*
                                     * Comparisons between strings are done
                                     * lexicographically.
                                     *
                                     */
                                    
                                    if ( _text < other._text )
                                        return true ;
        
                                    if ( _text > other._text )
                                        return false ;
        
                                    if ( Pixels::isLess( _color, 
                                            other._color ) )
                                        return true ;
                                    
                                    if ( Pixels::isLess( other._color,
                                             _color ) )
                                        return false ;
                                    
                                    return _quality < other._quality ;
        
                                }   
                                
                                
                            private:                                
                            
                                std::string _text ;
                                Pixels::ColorDefinition _color ;    
                                RenderQuality _quality ;
                                
                        
                        } ;
                        


                    
                        enum RenderCache { 
                            None, GlyphCached, WordCached, TextCached } ;
                        
                    
                        enum AllowedCachePolicy { 
                            NeverDrop, DropLessRequestedFirst } ;
                        
                        
                        explicit Font( 
                            bool convertToDisplay = true, 
                            RenderCache cacheSettings = GlyphCached, 
                            AllowedCachePolicy cachePolicy 
                                = DropLessRequestedFirst,
                            Ceylan::System::Size quota = 0 ) throw() ;
                        
                        
                        virtual ~Font() throw() ;

                        
                        virtual RenderingStyle getRenderingStyle() const
                            throw() ;
                        
                        
                        virtual void setRenderingStyle( 
                            RenderingStyle newStyle ) throw( TextException ) ;
                        

                        virtual void setBackgroundColor( 
                                Pixels::ColorDefinition newBackgroundColor ) 
                            throw() ;   
                            
                    
                        Pixels::ColorDefinition getBackgroundColor() 
                            const throw() ;
                                                
                        
                        virtual Width getWidth( Ceylan::Latin1Char character ) 
                            const throw( TextException) = 0 ;
                         
                         
                        virtual SignedWidth getWidthOffset( 
                                Ceylan::Latin1Char character ) 
                            const throw( TextException ) = 0 ;


                        virtual SignedHeight getHeightAboveBaseline(
                                Ceylan::Latin1Char character )
                            const throw( TextException ) = 0 ;

                         
                        virtual SignedLength getAdvance( 
                                Ceylan::Latin1Char character ) 
                            const throw( TextException ) = 0 ;
                         
                         
                        virtual Width getInterGlyphWidth() const throw() ;
                         
                                                
                        virtual Height getHeight() const throw() = 0 ;
                        
                        
                         
                        virtual SignedHeight getAscent() const throw() = 0 ;
                         
                         
                        virtual SignedHeight getDescent() const throw() = 0 ;
                         
                         
                        virtual Height getLineSkip() const throw() = 0 ;
                        
                        
                        
                        virtual Width getAlineaWidth() const throw() ;
                        
                        
                        virtual void setAlineaWidth( Width newAlineaWidth )
                            throw() ;   
                         
                         
                         
                        virtual std::string describeGlyphFor( 
                                Ceylan::Latin1Char character )
                            const throw() ;
                        
                        
                        
                        // Render section.
                                                         

                        virtual Surface & renderLatin1Glyph( 
                                Ceylan::Latin1Char character, 
                                RenderQuality quality = Solid, 
                                Pixels::ColorDefinition glyphColor 
                                    = Pixels::White ) 
                            throw( TextException ) = 0 ;


                        virtual void blitLatin1Glyph( 
                                Surface & targetSurface,
                                Coordinate x, 
                                Coordinate y, 
                                Ceylan::Latin1Char character, 
                                RenderQuality quality = Solid, 
                                Pixels::ColorDefinition glyphColor 
                                    = Pixels::White )  
                            throw( TextException )= 0 ;
                            
                                
                                
                        virtual Surface & renderLatin1Text( 
                                const std::string & text, 
                                RenderQuality quality = Solid,
                                Pixels::ColorDefinition textColor 
                                    = Pixels::White ) 
                            throw( TextException ) ;
                            
                            
                            
                        virtual void blitLatin1Text( 
                                Surface & targetSurface,
                                Coordinate x, 
                                Coordinate y, 
                                const std::string & text, 
                                RenderQuality quality = Solid,
                                Pixels::ColorDefinition textColor 
                                    = Pixels::White ) 
                            throw( TextException ) ;
                            

                                
                        virtual Surface & renderLatin1MultiLineText( 
                                Length width, 
                                Length height,
                                const std::string & text,
                                TextIndex & renderIndex,
                                Coordinate & lastOrdinateUsed,
                                RenderQuality quality = Solid,
                                Pixels::ColorDefinition textColor 
                                    = Pixels::White,
                                bool justified = true ) 
                            throw( TextException ) ;


                        virtual void blitLatin1MultiLineText( 
                                Surface & targetSurface,
                                const UprightRectangle & clientArea, 
                                const std::string & text,
                                TextIndex & renderIndex,
                                RenderQuality quality = Solid,
                                Pixels::ColorDefinition textColor 
                                    = Pixels::White,
                                bool justified = true ) 
                            throw( TextException ) ;


                        virtual void blitLatin1MultiLineText( 
                                Surface & targetSurface,
                                Coordinate x, 
                                Coordinate y,
                                Length width, 
                                Length height,
                                const std::string & text,
                                TextIndex & renderIndex,
                                RenderQuality quality = Solid,
                                Pixels::ColorDefinition textColor 
                                    = Pixels::White,
                                bool justified = true ) 
                            throw( TextException ) ;



                        virtual const std::string toString( 
                                Ceylan::VerbosityLevels level = Ceylan::high ) 
                            const throw() ;

                        
                        
                        
                        // Static section.
                        
                                                
                        static std::string FontPathEnvironmentVariable  ;
                        
                        
                        static Ceylan::System::FileLocator FontFileLocator ;
                        
                        
                        static std::string InterpretRenderingStyle(
                            RenderingStyle style ) throw() ;
                        
                        
                        /*
                         * Rendering styles can be combined for some fonts : 
                         * 'Bold | Italic' selects for example a bold italic
                         * rendering style.
                         * 
                         */
                        
                        static const RenderingStyle Normal ;
                
                                
                        static const RenderingStyle Bold ;
                
                        
                        static const RenderingStyle Italic ;
                
                        
                        static const RenderingStyle Underline ;


                        static const Ceylan::System::Size
                            DefaultGlyphCachedQuota ;
                        
                        
                        static const Ceylan::System::Size 
                            DefaultWordCachedQuota ;
                        
                        
                        static const Ceylan::System::Size 
                            DefaultTextCachedQuota ;
                        
                                                
                        static const Ceylan::Uint8 
                            DefaultSpaceBasedAlineaWidth ;
                        
                        
                        
                        
                    protected:


                        
                        Surface & renderLatin1TextWithWordCached( 
                                const std::string & text,
                                RenderQuality quality, 
                                Pixels::ColorDefinition textColor ) 
                            throw( TextException ) ;
                            
                            
                            
                        Surface & renderLatin1TextWithTextCached( 
                                const std::string & text,
                                RenderQuality quality, 
                                Pixels::ColorDefinition textColor ) 
                            throw( TextException ) ;
                            

                        
                        virtual void blitLatin1Word( 
                                Surface & targetSurface,
                                Coordinate x, 
                                Coordinate y, 
                                const std::string & word, 
                                RenderQuality quality = Solid, 
                                Pixels::ColorDefinition wordColor 
                                    = Pixels::White ) 
                            throw( TextException ) ;
                        


                        virtual const Surface & getConstLatin1WordFromCache( 
                                const std::string & word, 
                                RenderQuality quality,
                                Pixels::ColorDefinition wordColor )
                            throw( TextException ) ;

                            
                        Surface & basicRenderLatin1Text( 
                                const std::string & text,
                                RenderQuality quality, 
                                Pixels::ColorDefinition textColor ) 
                            throw( TextException ) ;
                            
                            
                        RenderingStyle _renderingStyle ;
                    
                    
                        bool _convertToDisplay ;
                        
                                                                        
                        RenderCache _cacheSettings ;

                         
                        Ceylan::SmartResourceManager<CharColorQualityKey> *
                            _glyphCache ;
                        
                        
                        Ceylan::SmartResourceManager<StringColorQualityKey> *
                            _textCache ;

                        
                        Pixels::ColorDefinition _backgroundColor ;
                        
                        
                        Width _spaceWidth ;
                            
                            
                        Width _alineaWidth ;
                            
                
                
                    private:
                    
                
                                    
                        Font( const Font & source ) throw() ;
            
            
                        Font & operator = ( const Font & source ) throw() ;
                        
                        
                } ;                         
                
            } 
            
        }   
            
    }
    
}       



#endif // OSDL_FONT_H_

---