OpenSceneGraph/include/osgText/Font

/* -*-c++-*- OpenSceneGraph - Copyright (C) 1998-2006 Robert Osfield 
 *
 * This library is open source and may be redistributed and/or modified under  
 * the terms of the OpenSceneGraph Public License (OSGPL) version 0.0 or 
 * (at your option) any later version.  The full license is in LICENSE file
 * included with this distribution, and on the openscenegraph.org website.
 * 
 * This 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 
 * OpenSceneGraph Public License for more details.
*/

#ifndef OSGTEXT_FONT
#define OSGTEXT_FONT 1

#include <string>
#include <istream>

#include <osg/Vec2>
#include <osg/Image>
#include <osg/Texture2D>
#include <osg/StateSet>
#include <osg/buffered_value>
#include <osg/TexEnv>
#include <osgDB/ReaderWriter>
#include <osgText/Export>

#include <OpenThreads/Mutex>

namespace osgText {

class Font;
class Text;
enum KerningType
{
    KERNING_DEFAULT,    //default locked to integer kerning values
    KERNING_UNFITTED,   //use floating point value for kerning
    KERNING_NONE        //no kerning
};

/** Read a font from specified file. The filename may contain a path.
  * It will search for the font file in the following places in this order: 
  * - In the current directory
  * - All paths defined in OSG_FILE_PATH or OSGFILEPATH environment variable
  * - Filename with path stripped: In the current directory
  * - Filename with path stripped: All paths defined in OSG_FILE_PATH or OSGFILEPATH
  *
  * Then the file will be searched in OS specific directories in the following order:
  * - Again in the current directory
  * - Windows: In C:/winnt/fonts
  * - Windows: In C:/windows/fonts
  * - Windows: In the fonts directory of the windows install directory
  * - Other OS: In /usr/share/fonts/ttf
  * - Other OS: In /usr/share/fonts/ttf/western
  * - Other OS: In /usr/share/fonts/ttf/decoratives
  * 
  * If the given file could not be found, the path part will be stripped and
  * the file will be searched again in the OS specific directories.
  */
extern OSGTEXT_EXPORT Font* readFontFile(const std::string& filename, const osgDB::ReaderWriter::Options* userOptions = 0);

/** read a font from specified stream.*/
extern OSGTEXT_EXPORT Font* readFontStream(std::istream& stream, const osgDB::ReaderWriter::Options* userOptions = 0);

extern OSGTEXT_EXPORT std::string findFontFile(const std::string& str);

/** Pure virtual base class for fonts.
  * Concrete implementation are the DefaultFont found in src/osgText/DefaultFont.cpp
  * and FreeTypeFont found in src/osgPlugins/freetype/FreeTypeFont.cpp*/
class OSGTEXT_EXPORT Font : public osg::Object
{
// declare the interface to a font.
public:

    // forward declare nested classes.
    class Glyph;
    class GlyphTexture;
    class FontImplementation;

public:
    Font(FontImplementation* implementation=0);

    virtual osg::Object* cloneType() const { return 0; } // cloneType() not appropriate
    virtual osg::Object* clone(const osg::CopyOp&) const { return 0; } // clone() not appropriate
    virtual bool isSameKindAs(const osg::Object* obj) const { return dynamic_cast<const Font*>(obj)!=NULL; }
    virtual const char* className() const { return "Font"; }
    virtual const char* libraryName() const { return "osgText"; }

    virtual std::string getFileName() const;

    void setTexEnv(osg::TexEnv* texenv) { if (texenv) _texenv = texenv; }
    inline osg::TexEnv* getTexEnv() {  return _texenv.get(); }
    inline const osg::TexEnv* getTexEnv() const {  return _texenv.get(); }

    void setStateSet(osg::StateSet* stateset) { _stateset = stateset; }
    osg::StateSet* getStateSet() { return _stateset.get(); }
    const osg::StateSet* getStateSet() const { return _stateset.get(); }

    /** Set the pixel width and height hint.*/
    virtual void setFontResolution(unsigned int width, unsigned int height);
    
    unsigned int getFontWidth() const;
    unsigned int getFontHeight() const;

    /** Get a kerning (adjustment of spacing of two adjacent character) for specified charcodes, w.r.t the current font size hint.*/
    virtual osg::Vec2 getKerning(unsigned int leftcharcode,unsigned int rightcharcode, KerningType kerningType);

    /** Get a Glyph for specified charcode, and the font size nearest to the current font size hint.*/
    virtual Glyph* getGlyph(unsigned int charcode);
    
    /** Return true if this font provides vertical alignments and spacing or glyphs.*/
    virtual bool hasVertical() const;

    /** Set the margin around each glyph, 
      * to ensure that texture filtering doesn't bleed adjacent glyph's into each other.
      * Default margin is 1 texels.*/    
    void setGlyphImageMargin(unsigned int margin);
    unsigned int getGlyphImageMargin() const;

    /** Set the margin ratio around each glyph, relative to the glyph's size.
      * to ensure that texture filtering doesn't bleed adjacent glyph's into each other.
      * Default margin is 0.05.*/    
    void setGlyphImageMarginRatio(float margin);
    float getGlyphImageMarginRatio() const;


    /** Set the size of texture to create to store the glyph images when rendering.
      * Note, this doesn't affect already created Texture Glhph's.*/
    void setTextureSizeHint(unsigned int width,unsigned int height);
    
    unsigned int getTextureWidthHint() const;
    unsigned int getTextureHeightHint() const;

    /** Set the minification texture filter to use when creating the texture to store the glyph images when rendering.
      * Note, this doesn't affect already created Texture Glhph's.*/
    void setMinFilterHint(osg::Texture::FilterMode mode);
    osg::Texture::FilterMode getMinFilterHint() const;
    
    /** Set the magnification texture filter to use when creating the texture to store the glyph images when rendering.
      * Note, this doesn't affect already created Texture Glhph's.*/
    void setMagFilterHint(osg::Texture::FilterMode mode);
    osg::Texture::FilterMode getMagFilterHint() const;

    // make Text a friend to allow it add and remove its entry in the Font's _textList.
    friend class FontImplementation;

    void setImplementation(FontImplementation* implementation);

    FontImplementation* getImplementation();
    const FontImplementation* getImplementation() const;

    /** Set whether to use a mutex to ensure ref() and unref() are thread safe.*/
    virtual void setThreadSafeRefUnref(bool threadSafe);

    /** Resize any per context GLObject buffers to specified size. */
    virtual void resizeGLObjectBuffers(unsigned int maxSize);

     /** If State is non-zero, this function releases OpenGL objects for
       * the specified graphics context. Otherwise, releases OpenGL objexts
       * for all graphics contexts. */
    virtual void releaseGLObjects(osg::State* state=0) const;

    typedef OpenThreads::Mutex FontMutex;
    
    /** Get the mutex that enables the serialization of calls to this font.*/
    static FontMutex* getSerializeFontCallsMutex();

protected:

    virtual ~Font();
    
    void addGlyph(unsigned int width, unsigned int height, unsigned int charcode, Glyph* glyph);
    
    typedef std::vector< osg::ref_ptr<GlyphTexture> >       GlyphTextureList;
    typedef std::vector< osg::ref_ptr<osg::StateSet> >      StateSetList;
    typedef std::map< unsigned int, osg::ref_ptr<Glyph> >   GlyphMap;
    
    typedef std::pair< unsigned int, unsigned int >         SizePair;
    typedef std::map< SizePair, GlyphMap >                  SizeGlyphMap;
    
    mutable FontMutex               _serializeFontCallsMutex;

    osg::ref_ptr<osg::TexEnv>       _texenv;
    osg::ref_ptr<osg::StateSet>     _stateset;
    SizeGlyphMap                    _sizeGlyphMap;
    GlyphTextureList                _glyphTextureList;
    
    // current active size of font
    unsigned int                    _width;
    unsigned int                    _height;
    unsigned int                    _margin;
    float                           _marginRatio;

    unsigned int                    _textureWidthHint;
    unsigned int                    _textureHeightHint;   
    osg::Texture::FilterMode        _minFilterHint;
    osg::Texture::FilterMode        _magFilterHint;
    
    osg::ref_ptr<FontImplementation> _implementation;

    
// declare the nested classes.
public:

    class FontImplementation : public osg::Referenced
    {
    public:
    
        FontImplementation():
            osg::Referenced(true) {}
    
        virtual std::string getFileName() const = 0;

        /** Set the pixel width and height hint.*/
        virtual void setFontResolution(unsigned int width, unsigned int height) = 0;

        /** Get a Glyph for specified charcode, and the font size nearest to the current font size hint.*/
        virtual Glyph* getGlyph(unsigned int charcode) = 0;

        /** Get a kerning (adjustment of spacing of two adjacent character) for specified charcodes, w.r.t the current font size hint.*/
        virtual osg::Vec2 getKerning(unsigned int leftcharcode,unsigned int rightcharcode, KerningType kerningType) = 0;

        /** Return true if this font provides vertical alignments and spacing or glyphs.*/
        virtual bool hasVertical() const = 0;
        
        void setFontWidth(unsigned int width) { _facade->_width = width; }

        void setFontHeight(unsigned int height) { _facade->_height = height; }
        
        void addGlyph(unsigned int width, unsigned int height, unsigned int charcode, Glyph* glyph)
        {
            _facade->addGlyph(width, height, charcode, glyph);
        }

        Font* _facade;
    };

    class OSGTEXT_EXPORT GlyphTexture : public osg::Texture2D
    {
    public:

        GlyphTexture();
        
        const char* className() const { return "GlyphTexture"; }

        /** return -1 if *this < *rhs, 0 if *this==*rhs, 1 if *this>*rhs.*/
        virtual int compare(const osg::StateAttribute& rhs) const;

        /** Set the margin around each glyph, to ensure that texture filtering doesn't bleed adjacent glyph's into each other.*/    
        void setGlyphImageMargin(unsigned int margin) { _margin = margin; }
        unsigned int getGlyphImageMargin() const { return _margin; }

        void setGlyphImageMarginRatio(float margin) { _marginRatio = margin; }
        float getGlyphImageMarginRatio() const { return _marginRatio; }

        bool getSpaceForGlyph(Glyph* glyph, int& posX, int& posY);
        
        void addGlyph(Glyph* glyph,int posX, int posY);
        
        virtual void apply(osg::State& state) const;

        /** Set whether to use a mutex to ensure ref() and unref() are thread safe.*/
        virtual void setThreadSafeRefUnref(bool threadSafe);

        /** Resize any per context GLObject buffers to specified size. */
        virtual void resizeGLObjectBuffers(unsigned int maxSize);

    protected:
    
        virtual ~GlyphTexture();


        // parameter used to compute the size and position of empty space
        // in the texture which could accomodate new glyphs.
        int _margin;
        float _marginRatio;
        int _usedY;
        int _partUsedX;
        int _partUsedY;

        typedef std::vector< osg::ref_ptr<Glyph> > GlyphRefList;
        typedef std::vector< const Glyph* > GlyphPtrList;
        typedef osg::buffered_object< GlyphPtrList > GlyphBuffer;
        
        GlyphRefList                _glyphs;
        mutable GlyphBuffer         _glyphsToSubload;
        
        mutable OpenThreads::Mutex  _mutex;

    };

    class OSGTEXT_EXPORT Glyph : public osg::Image
    {
    public:

        Glyph();

        unsigned int getGlyphCode() const;

        void setHorizontalBearing(const osg::Vec2& bearing);
        const osg::Vec2& getHorizontalBearing() const;

        void setHorizontalAdvance(float advance);
        float getHorizontalAdvance() const;

        void setVerticalBearing(const osg::Vec2& bearing);
        const osg::Vec2& getVerticalBearing() const;

        void setVerticalAdvance(float advance);
        float getVerticalAdvance() const;


        void setTexture(GlyphTexture* texture);
        GlyphTexture* getTexture();
        const GlyphTexture* getTexture() const;

        void setTexturePosition(int posX,int posY);
        int getTexturePositionX() const;
        int getTexturePositionY() const;

        void setMinTexCoord(const osg::Vec2& coord);
        const osg::Vec2& getMinTexCoord() const;

        void setMaxTexCoord(const osg::Vec2& coord);
        const osg::Vec2& getMaxTexCoord() const;
        
        void subload() const;
        
        void draw(osg::State& state) const;

    protected:

        virtual ~Glyph();

        Font*                       _font;
        unsigned int                _glyphCode;

        osg::Vec2                   _horizontalBearing;
        float                       _horizontalAdvance;

        osg::Vec2                   _verticalBearing;
        float                       _verticalAdvance;

        GlyphTexture*               _texture;
        int                         _texturePosX;
        int                         _texturePosY;
        osg::Vec2                   _minTexCoord;
        osg::Vec2                   _maxTexCoord;
        
        typedef osg::buffered_value<GLuint> GLObjectList;
        mutable GLObjectList _globjList;

    };


};

}


#endif