gls_unicode_font_base.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::GlsUnicodeFontBase 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_UNICODE_FONT_BASE_H
#define _GLS_UNICODE_FONT_BASE_H

#include "gls_font_base.h"

namespace disti
{
// forward ref
class GlsUnicodeFontDBUFReader;

//===========================================================================
/**
* The GlsUnicodeFontBase class provides a specific unicode 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 GlsUnicodeFontBase : public GlsFontBase
{
public:
    /** char index associated with absent glyph */
    static const unsigned short NO_GLYPH;

    //-----------------------------------------------------------------------
    /// Attributes of the specific font
    //-----------------------------------------------------------------------
    struct FontAttrUnicode_t : public FontAttr_t
    {
        unsigned int numberOfTextures;            /** the number of textures used to generate font */
        unsigned int glyphCount;                  /** the number of glyphs rendered for the font */
        unsigned int maxNumberOfGlyphsPerTexture; /** The maximum number of glyphs per texture for the first n textures.
                                                      This does not take into consideration the last texture which
                                                      may contain less than the standard number of glyphs per
                                                      texture */

        /** Default constructor to initialize font data to known values */
        FontAttrUnicode_t()
            : numberOfTextures( 1 )
            , glyphCount( 0 )
            , maxNumberOfGlyphsPerTexture( 1 )
        {
        }
    };

    //-----------------------------------------------------------------------
    /// Character attributes. One item for each character in the set.
    //-----------------------------------------------------------------------
    struct CharAttrUnicode_t : public CharAttr_t
    {
        unsigned int textureIndex; /**< Index of the texture that contains the glyph */
        unsigned int glyphIndex;   /**< Index of the glyph. This is needed since glyphs are not assumed to be contiguous */

        /** Default constructor to initialize character attribute data to known values */
        CharAttrUnicode_t()
            : textureIndex( 0 )
            , glyphIndex( 0 )
        {
        }

        CharAttrUnicode_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_,
            unsigned int textureIndex_,
            unsigned int glyphIndex_ )
            : CharAttr_t( w, h, vTexX1, vTexX2, fTexX1, fTexX2, vTexY1, vTexY2, fTexY1, fTexY2,
                horiBearingX_, horiBearingY_, horiAdvance_, vertBearingX_, vertBearingY_, vertAdvance_ )
            , textureIndex( textureIndex_ )
            , glyphIndex( glyphIndex_ )
        {
        }
    };

    typedef std::vector<CharAttrUnicode_t> AttrContUnicode_t;

    typedef std::vector<Image*> ImageVector_t;

    /** Class Constructor
      * \param dbufReader reader to read BUF data from
      */
    GLS_EXPORT GlsUnicodeFontBase( GlsUnicodeFontDBUFReader& dbufReader );

    /** Determine if font was instantiated correctly
      * \return true if valid else false
      */
    GLS_EXPORT bool IsValid( void ) const;

    /** get the font textures associated with the unicode font
      * \return the font textures associated with the unicode font
      */
    GLS_EXPORT ImageVector_t FontTextures( void ) const;

    /** get the unicode character attribute for the given char
      * \param c The character to retrieve attributes for.
      * \returns The attributes for the character else char attributes for first character
      *         in font if char is not in range for this font
      */
    GLS_EXPORT const CharAttrUnicode_t& CharAttrUnicode( Char_t c ) const;

    /** Get the font texture for the font texture containing the given glyph
      * \param c The character to retrieve attributes for.
      * \return the font texture for the font texture containing the given glyph,
      *         else font texture for first glyph in font if glyph is not in the font
      */
    GLS_EXPORT Image* FontTextureForChar( Char_t c ) const;

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 ~GlsUnicodeFontBase();

    friend class GlsFontMan;

    FontAttrUnicode_t _fontAttrUnicode; /**< unicode font attributes */
    AttrContUnicode_t _charAttrUnicode; /**< unicode char attributes */
    ImageVector_t     _fontTextures;    /**< font textures */
    bool              _isValid;         /**< true if font is valid else false */

    unsigned int    _charAttributeIndexLUTSize; /**< number of entries in the _charAttributeIndexLUT = ( lastChar - firstChar ) + 1 ) */
    unsigned short* _charAttributeIndexLUT;     /**< look up table from glyph index ( minus _fontAttributes.firstChar )
                                                     * to _charAttrUnicode array index else entry has NO_GLYPH to indicate that the given
                                                     * glyph is not in the font ( NOTE : array is _charAttributeIndexLUT long ) */

private:
    //-----------------------------------------------------------------------
    // Prevent copies
    //-----------------------------------------------------------------------
    GlsUnicodeFontBase( const GlsUnicodeFontBase& );
    GlsUnicodeFontBase& operator=( const GlsUnicodeFontBase& );

}; // end class GlsUnicodeFontBase

/** helper class for reading a binary unicode font (DBUF) */
class GlsUnicodeFontDBUFReader
{
public:
    /** ctor -- construct from inline data (optionally compressed)
      * \param inlineDBUFData inline DBUF data to read
      * \param lineLength length of lines in inline data
      * \param totalInlineSize total number of bytes (not including NULL terminators) of inline data
      * \param isCompressed true if dbuf data is zlib compressed else false
      * \param uncompressedSize uncompressed size of data if isCompressed else ignored
      */
    GLS_EXPORT GlsUnicodeFontDBUFReader( const unsigned char* const* inlineDBUFData, const unsigned int lineLength,
        const unsigned int totalInlineSize, const bool isCompressed, unsigned long uncompressedSize );

    /** ctor -- construct from noninline data (not compressed)
      * \param dbufData DBUF data to read
      * \param dbufDataLength number of bytes of data in dbufData
      */
    GLS_EXPORT GlsUnicodeFontDBUFReader( const unsigned char* const dbufData, const unsigned int dbufDataLength );

    /** dtor */
    GLS_EXPORT ~GlsUnicodeFontDBUFReader();

    /** Get the GlsFontBase::FontAttr_t associated with the unicode font
      * \return the GlsFontBase::FontAttr_t associated with the unicode font
      */
    GLS_EXPORT GlsFontBase::FontAttr_t GetGlsFontBaseFontAttributes( void );

    /** Get the GlsFontBase::AttrCont_t associated with the unicode font
      * \return the GlsFontBase::AttrCont_t associated with the unicode font
      */
    GLS_EXPORT GlsFontBase::AttrCont_t GetGlsFontBaseCharAttributes( void );

    /** Get the first image associated with the unicode font (suitable for use by GlsFontBase)
      * \return the first image associated with the unicode font (suitable for use by GlsFontBase)
      * \note will increase usage count on texture by one so caller should call DeleteUsage when texture is no longer needed
      */
    GLS_EXPORT Image* GetGlsFontBaseTexture( void );

    /** Get the GlsUnicodeFontBase::FontAttrUnicode_t associated with the unicode font
      * \return the GlsFontBase::FontAttrUnicode_t associated with the unicode font
      */
    GLS_EXPORT GlsUnicodeFontBase::FontAttrUnicode_t GetGlsUnicodeFontBaseFontAttributes( void );

    /** Get the GlsUnicodeFontBase::AttrContUnicode_t associated with the unicode font
      * \return the GlsFontBase::AttrContUnicode_t associated with the unicode font
      */
    GLS_EXPORT GlsUnicodeFontBase::AttrContUnicode_t GetGlsUnicodeFontBaseCharAttributes( void );

    /** Get the textures associated with the unicode font
      * \return the textures associated with the unicode font
      * \note each texture will have its usage count increased by one so caller should call DeleteUsage on each texture
      *       when they are no longer needed
      */
    GLS_EXPORT std::vector<Image*> GetGlsUnicodeFontBaseTextures( void );

    /** Determine if a valid DBUF was read
      * \return true if a valid DBUF was read else false
      */
    GLS_EXPORT bool IsValid( void ) const;

    /** Get an error message if !IsValid()
      * \return an error message if !IsValid()
      */
    GLS_EXPORT std::string GetErrorMsg( void ) const;

protected:
    /** initialize the reader from the given DBUF data
      * \param dbufData DBUF data to read
      * \param dbufDataLength number of bytes of data in dbufData
      */
    GLS_EXPORT void InitializeFromDBUF( const unsigned char* const dbufData, const unsigned int dbufDataLength );

    bool        _isValid; /**< true if a valid DBUF was read else false */
    std::string _errMsg;  /**< error message if !IsValid() */

    GlsUnicodeFontBase::FontAttrUnicode_t _fontAttrUnicode; /**< unicode font attributes read from DBUF data */
    GlsUnicodeFontBase::AttrContUnicode_t _charAttrUnicode; /**< unicode char attributes read from DBUF data */
    std::vector<Image*>                   _fontTextures;    /**< font textures read from DBUF data */

private:
    //-----------------------------------------------------------------------
    // Prevent copies
    //-----------------------------------------------------------------------
    GlsUnicodeFontDBUFReader( const GlsUnicodeFontDBUFReader& src );
    GlsUnicodeFontDBUFReader& operator=( const GlsUnicodeFontDBUFReader& ths );
};

} // end namespace disti

#endif