gls_font_base.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::GlsFontBase class and related classes.
 
  \par Copyright Information
 
  Copyright (c) 2017 by The DiSTI Corporation.<br>
  11301 Corporate Blvd; Suite 100<br>
  Orlando, Florida 32817<br>
  USA<br>
  <br>
  All rights reserved.<br>
 
  This Software contains proprietary trade secrets of DiSTI and may not be
reproduced, in whole or part, in any form, or by any means of electronic,
mechanical, or otherwise, without the written permission of DiSTI.  Said
permission may be derived through the purchase of applicable DiSTI product
licenses which detail the distribution rights of this content and any
Derivative Works based on this or other copyrighted DiSTI Software.
 
  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.
 
  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES.  DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
EXCEED FIVE DOLLARS (US$5.00).
 
  The aforementioned terms and restrictions are governed by the laws of the
State of Florida and the United States of America.
 
*/
#ifndef _GLS_FONT_H
#define _GLS_FONT_H
 
#include "gls_gl.h"
#include "vertex.h"
#include <string>
#include <vector>
 
//---------------------------------------------------------------------------
//              MACROS FOR USE IN GENERATED SOURCE CODE
//---------------------------------------------------------------------------
/// \cond INTERNAL
#define BEGIN_CHAR_ATTR AttrCont_t attr
#define ADD_CHAR_ATTR( a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12, a13, a14, a15, a16 ) \
    attr.push_back( CharAttr_t( a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12, a13, a14, a15, a16 ) )
#define END_CHAR_ATTR return attr
/// \endcond
//===========================================================================
//                         BEGIN NAMESPACE
//===========================================================================
namespace disti
{
//---------------------------------------------------------------------------
//                        FORWARD REFERENCES
//---------------------------------------------------------------------------
class VertexNoColor;
class GlsColor;
class Image;
 
typedef VertexNoColor Vector;
 
//===========================================================================
/**
* The GlsFontBase class provides a specific font face for use within the GL 
* Studio.  The font face is determined at construction time by the 
* parameters passed in by the creator of the GlsFontBase instance.  Specific
* instances should be wrapped in a singelton object wrapper, as there is
* no reason to have more than one instance of the exact same face (meaning
* font family, style, and point size.)
*
* Once instanced, a GlsFontRenderer object can be used to render characters in
* Open GL at specific locations and with several different text effects.
* 
* \sa GlsFontRenderer
*/
//===========================================================================
class GlsFontBase
{
public:
    typedef GLuint Char_t; ///< Define the character type to use.
 
    //-----------------------------------------------------------------------
    /// Attributes of the specific font
    //-----------------------------------------------------------------------
    struct FontAttr_t
    {
        std::string family;        ///< Font family name. Eg. Arial.
        std::string style;         ///< Font style. Eg. Bold.
        GLuint      ptSize;        ///< Font point size.
        GLuint      descender;     ///< Font descender in positive pixels.
        Char_t      firstChar;     ///< First character code in the character set.
        Char_t      lastChar;      ///< Last character code in the character set.
        GLuint      maxCharHeight; ///< Maximum character height in pixels.
        GLuint      maxCharWidth;  ///< Maximum character width in pixels.
        GLint       underlinePos;  ///< Position of the underline for underlined text.
        GLuint      underlineSize; ///< thickness of the underline.
 
        /** Default constructor to initialize font data to known values */
        FontAttr_t()
            : ptSize( 0 )
            , descender( 0 )
            , firstChar( 32 )
            , lastChar( 127 )
            , maxCharHeight( 0 )
            , maxCharWidth( 0 )
            , underlinePos( 0 )
            , underlineSize( 0 )
        {
        }
    };
 
    //-----------------------------------------------------------------------
    /// Character attributes. One item for each character in the set.
    //-----------------------------------------------------------------------
    struct CharAttr_t
    {
        GLfloat width;      ///< Character width in pixels/points.
        GLfloat height;     ///< Character height in pixels/points.
        GLfloat varTexX1;   ///< Left most x position in the texture for variable width font spacing. (in texture coordinates).
        GLfloat varTexX2;   ///< Right most x position in the texture for variable width font spacing. (in texture coordinates).
        GLfloat fixedTexX1; ///< Left most x position in the texture for fixed width font spacing. (in texture coordinates).
        GLfloat fixedTexX2; ///< Right most x position in the texture for fixed width font spacing. (in texture coordinates).
        GLfloat varTexY1;   ///< Lowest y position in the texture for variable height font spacing. (in texture coordinates).
        GLfloat varTexY2;   ///< Upper most y position in the texture for variable height font spacing. (in texture coordinates).
        GLfloat fixedTexY1; ///< Lowest y position in the texture for fixed height font spacing. (in texture coordinates).
        GLfloat fixedTexY2; ///< Upper most y position in the texture for fixed height font spacing. (in texture coordinates).
 
        // Glyph metrics for character placement
        // Additional information on the meaning of these parameters can
        // be found in the freetype library documentation.
        GLfloat horiBearingX; ///< Distance from pen position to the left edge of the character (varTexX1) for horizontal strings.
        GLfloat horiBearingY; ///< Distance from pen position (ie the baseline) to the top edge of the character (varTexY2) for horizontal strings.
        GLfloat horiAdvance;  ///< Distance to advance the pen position after drawing this character for horizontal strings.
        GLfloat vertBearingX; ///< Distance from pen position (ie the center line) to the left edge of the character (varTexX1) for vertical strings.
        GLfloat vertBearingY; ///< Distance from pen position to the top edge of the character (varTexY2) for vertical strings.
        GLfloat vertAdvance;  ///< Distance to advance the pen position after drawing this character for vertical strings.
 
        /// Default constructor to initialize character attribute data to known values
        CharAttr_t()
            : width( 0 )
            , height( 0 )
            , varTexX1( 0 )
            , varTexX2( 0 )
            , fixedTexX1( 0 )
            , fixedTexX2( 0 )
            , varTexY1( 0 )
            , varTexY2( 0 )
            , fixedTexY1( 0 )
            , fixedTexY2( 0 )
            , horiBearingX( 0 )
            , horiBearingY( 0 )
            , horiAdvance( 0 )
            , vertBearingX( 0 )
            , vertBearingY( 0 )
            , vertAdvance( 0 )
        {
        }
 
        /// Constructor
        /// \param w Character width in pixels/points.
        /// \param h Character height in pixels/points.
        /// \param vTexX1 Left most x position in the texture for variable width font spacing. (in texture coordinates)
        /// \param vTexX2 Right most x position in the texture for variable width font spacing. (in texture coordinates)
        /// \param fTexX1 Left most x position in the texture for fixed width font spacing. (in texture coordinates)
        /// \param fTexX2 Right most x position in the texture for fixed width font spacing. (in texture coordinates)
        /// \param vTexY1 Lowest y position in the texture for variable height font spacing. (in texture coordinates)
        /// \param vTexY2 Upper most y position in the texture for variable height font spacing. (in texture coordinates)
        /// \param fTexY1 Lowest y position in the texture for fixed height font spacing. (in texture coordinates)
        /// \param fTexY2 Upper most y position in the texture for fixed height font spacing. (in texture coordinates)
        /// \param horiBearingX_ Distance from pen position to the left edge of the character (varTexX1) for horizontal strings.
        /// \param horiBearingY_ Distance from pen position (ie the baseline) to the top edge of the character (varTexY2) for horizontal strings.
        /// \param horiAdvance_ Distance to advance the pen position after drawing this character for horizontal strings.
        /// \param vertBearingX_ Distance from pen position (ie the center line) to the left edge of the character (varTexX1) for vertical strings.
        /// \param vertBearingY_ Distance from pen position to the top edge of the character (varTexY2) for vertical strings.
        /// \param vertAdvance_ Distance to advance the pen position after drawing this character for vertical strings.
        CharAttr_t( GLfloat w,
            GLfloat         h,
            GLfloat         vTexX1,
            GLfloat         vTexX2,
            GLfloat         fTexX1,
            GLfloat         fTexX2,
            GLfloat         vTexY1,
            GLfloat         vTexY2,
            GLfloat         fTexY1,
            GLfloat         fTexY2,
            GLfloat         horiBearingX_,
            GLfloat         horiBearingY_,
            GLfloat         horiAdvance_,
            GLfloat         vertBearingX_,
            GLfloat         vertBearingY_,
            GLfloat         vertAdvance_ )
            : width( w )
            , height( h )
            , varTexX1( vTexX1 )
            , varTexX2( vTexX2 )
            , fixedTexX1( fTexX1 )
            , fixedTexX2( fTexX2 )
            , varTexY1( vTexY1 )
            , varTexY2( vTexY2 )
            , fixedTexY1( fTexY1 )
            , fixedTexY2( fTexY2 )
            , horiBearingX( horiBearingX_ )
            , horiBearingY( horiBearingY_ )
            , horiAdvance( horiAdvance_ )
            , vertBearingX( vertBearingX_ )
            , vertBearingY( vertBearingY_ )
            , vertAdvance( vertAdvance_ )
        {
        }
    }; // end struct CharAttr_t
 
    typedef std::vector<CharAttr_t> AttrCont_t; ///< Typedef for a list of character attributes.
 
    /// Class Constructor.
    /// \param fontAttr Font attributes for this font.
    /// \param charAttributes Attributes for each glyph of this font.
    /// \param texture The generated texture atlas associated with this font.
    GLS_EXPORT GlsFontBase( const FontAttr_t& fontAttr, const AttrCont_t& charAttributes, Image* texture );
 
    /** 
    * Access the attributes of the font.
    * \return all the attributes of the font.
    */
    const FontAttr_t& Attributes() const
    {
        return _attr;
    }
 
    /**
    * NOTE: This function will only return char attributes for pre-generated ASCII fonts.
    * Users should call CharAttrUnicode for GlsUnicodeFontBase fonts or CharAttrRuntime for GlsRuntimeFontBase fonts.
    * \param c The character to retrieve attributes for.
    * \returns The attributes for the character. 
    */
    const CharAttr_t& CharAttr( Char_t c ) const
    {
        return _charAttr[ CharAttrIndex( c ) ];
    }
 
    /** 
    * Calculates an index for the specified character depending on the set of characters the texture map was generated for.
    * NOTE: This function will only return char attributes for pre-generated ASCII fonts.
    * Users should call CharAttrUnicode for GlsUnicodeFontBase fonts or CharAttrRuntime for GlsRuntimeFontBase fonts.
    * \param c  specifies for which character the index is calculated for
    * \return the index of the specified character
    */
    GLuint CharAttrIndex( Char_t c ) const
    {
        return ( _attr.firstChar <= c && c <= _attr.lastChar )
                   ? GLuint( c - _attr.firstChar )
                   : 0;
    }
 
    /** 
    * Access the character attributes of the font.
    * \return the attributes of all the characters in the font.
    */
    const AttrCont_t& CharAttributes() const
    {
        return _charAttr;
    }
 
    /** 
    * \return The font family string
    */
    std::string Family() const
    {
        return _attr.family;
    }
 
    /**
    * \return The unique lookup key for this font.
    */
    std::string Key() const
    {
        return _key;
    }
 
    /// Builds a unique lookup key for a specific font, style, and size.
    /// \param name Name of the font.
    /// \param style Style of the font.
    /// \param ptSize Point size of the font.
    /// \return The associated unique key for this combination.
    static GLS_EXPORT std::string Key(
        const std::string& name,
        const std::string& style,
        GLuint             ptSize );
 
    /**
    * \return maximum height in pixels of the characters in the set
    */
    GLfloat MaxCharHeight() const
    {
        return GLfloat( _attr.maxCharHeight );
    }
 
    /**
    * \return maximum width in pixels of the characters in the set
    */
    GLfloat MaxCharWidth() const
    {
        return GLfloat( _attr.maxCharWidth );
    }
 
    /**
    * \return maximum height in pixels of the characters in the set
    */
    GLuint PtSize() const
    {
        return _attr.ptSize;
    }
 
    /// \return The style description for this font.
    std::string Style() const
    {
        return _attr.style;
    }
 
    /**
    * \return a pointer to the font's texture image.
    */
    Image* Texture() const
    {
        return _texture;
    }
 
protected:
    /** 
    * Class Destructor. This is protected so that no one can delete a font
    * except via the font manager GlsFontMan.
    * It is not vitual because we want to avoid calling destructors on unloaded font code, 
    * and it is not needed.
    */
    GLS_EXPORT ~GlsFontBase();
 
    friend class GlsFontMan;
 
    /** Attributes of the font. */
    FontAttr_t _attr;
 
    /** Proportional character attributes used when proportional character spacing is turned on. */
    AttrCont_t _charAttr;
 
    /** Unique key used as a lookup key to find fonts within maps. */
    std::string _key;
 
    /** Texture of all characters in the set. */
    Image* _texture;
 
private:
    //-----------------------------------------------------------------------
    // Prevent copies
    //-----------------------------------------------------------------------
    GlsFontBase( const GlsFontBase& );
    GlsFontBase& operator=( const GlsFontBase& );
 
}; // end class GlsFontBase
 
} // end namespace disti
 
#endif