OSDLFont.h

Go to the documentation of this file.

/* 
 * Copyright (C) 2003-2009 Olivier Boudeville
 *
 * This file is part of the OSDL library.
 *
 * The OSDL library is free software: you can redistribute it and/or modify
 * it under the terms of either the GNU Lesser General Public License or
 * the GNU General Public License, as they are published by the Free Software
 * Foundation, either version 3 of these Licenses, or (at your option) 
 * any later version.
 *
 * The OSDL library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License and the GNU General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License and of the GNU General Public License along with the OSDL library.
 * If not, see <http://www.gnu.org/licenses/>.
 *
 * Author: Olivier Boudeville (olivier.boudeville@esperide.com)
 *
 */


#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 inheritance, Uint32, CountedPointer, etc.


#include <string>


#if ! defined(OSDL_USES_SDL) || OSDL_USES_SDL 
#include "SDL.h"              // for SDL_Color and al
#endif // OSDL_USES_SDL
    



namespace OSDL
{



    namespace Video
    {



        // Fonts are rendered to surfaces.
        class Surface ;



        namespace TwoDimensional
        {
            
            
                
            class OSDL_DLL FontException: public VideoException 
            { 
            
                public: 
                
                    explicit FontException( const std::string & reason )  ;
                     
                    virtual ~FontException() 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 Ceylan::Uint32 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 ) :
                                    _character( character ),
                                    _color( color ),
                                    _quality( quality )
                                {
                                
                                }
                                
                                
                                
                                inline bool operator < ( 
                                    const CharColorQualityKey & other ) const
                                {

                                    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 ) :
                                    _text( text ),
                                    _color( color ),
                                    _quality( quality )
                                {
                                
                                }


                                
                                inline bool operator < ( 
                                    const StringColorQualityKey & other ) const 
                                {   
                                    
                                    /*
                                     * 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 ) ;
                        
                        
                        
                        virtual ~Font() throw() ;

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


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



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

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


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



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

                                
                        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 ) ;



                        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 ) ;



                        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 ) ;



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

                        
                        
                        
                        
                        // Static section.
                        
                        
                                                
                        static std::string FontPathEnvironmentVariable  ;
                        
                        
                        
                        static Ceylan::System::FileLocator FontFileLocator ;
                        
                        
                        
                        static std::string InterpretRenderingStyle(
                            RenderingStyle style ) ;
                        
                        
                        
                        /*
                         * 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 ) ;
                            
                            
                            
                        Surface & renderLatin1TextWithTextCached( 
                            const std::string & text,
                            RenderQuality quality, 
                            Pixels::ColorDefinition textColor ) ;
                            

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


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


                            
                        Surface & basicRenderLatin1Text( 
                            const std::string & text,
                            RenderQuality quality, 
                            Pixels::ColorDefinition textColor ) ;
                            
                            
                            
                            
                        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 ) ;
            
            
            
                        Font & operator = ( const Font & source ) ;
                        
                        
                } ;                         
                

                
            } 
            
        }   
            
    }
    
}       



#endif // OSDL_FONT_H_

---