gls_font_base.h

Go to the documentation of this file.

#ifndef _GLS_FONT_BASE_H
#define _GLS_FONT_BASE_H

/*! \file gls_font_base.h

\brief  This header defines the GlsFontBase class
        in the GL Studio DO-178B Runtime Library.

\par Copyright Information
Copyright (C) 1999-2012 The DiSTI Corporation<br>
Orlando, FL USA<br>
All rights reserved.<br>

  This file is copyrighted software and contains proprietary trade secrets of
DiSTI, and embodies substantial creative efforts as well as confidential
information, ideas, and expressions.

  Permission to use, and copy this software and its documentation for any
purpose is hereby granted per the Distribution Agreement and/or the Licensing
Agreement signed with DiSTI. This permission is granted provided that:
    1.  The above copyright notice appears in all copies.
    2.  That both the copyright notice and this permission notice appear in
        the supporting documentation.
    3.  That the names DiSTI and GL Studio not be used in advertising or
        publicity pertaining to distribution of the software without specific,
        written prior permission of DiSTI.
 
  Permission to modify the software is granted, but not the right to
distribute the source code whether modified, or non-modified.  Modifying the
software might invalidate the DO-178B certification package.

  Permission to distribute binaries produced by compiling source code, or
modified source code is granted, provided you:
    1.  Provide your name and address as the primary contact for the support
        of your modified version.
    2.  Retain our contact information in regard to use of the base software. 

   DiSTI does not provide warranty for this software or guarantee that it
satisfies any specification or requirement unless otherwise stated in a
specific contractual arrangement between the customer and DiSTI.

*/

#include "gls_include.h"
#include "gls_types.h"
#include "gls_vertex.h"
#include "gls_color.h"
#include "gls_image.h"
#include "gls_class_invariant.h"

/** This class serves as the base class for all fonts
  * \invariant _fontAttributes.IsValid(), _numGlyphAttributes > 0, 
  *            _glyphAttributes != GLS_NULL and array contains valid elements,
  *            _fontImage invariant holds
  */
class GlsFontBase
{
public:
    GLS_CLASS_INVARIANT_DECLARATION( GlsFontBase )

    /** code associated with a character in the font */
    typedef GlsUInt32 CharCode;

    /** tab character constant */
    static const GlsChar TAB_CHAR;

    /** describes basic attributes for the font */
    struct FontAttributes
    {
        const CharCode  firstChar;     /**< First character code in the character set */
        const CharCode  lastChar;      /**< Last character code in the character set */
        const GlsUInt32 maxCharHeight; /**< Maximum character height in pixels */
        const GlsUInt32 maxCharWidth;  /**< Maximum character width in pixels */
        const GlsUInt32 underlinePos;  /**< Position of the underline for underlined text */
        const GlsUInt32 underlineSize; /**< thickness of the underline */

        #if defined( GLS_DEBUG )
            /** Determine if the attributes are valid ( GLS_DEBUG only )
              * \return GLS_TRUE if valid else GLS_FALSE
              * \pre none
              * \post none
              */
            GlsBool IsValid( void ) const;
        #endif // GLS_DEBUG
    };

    /** describes attributes for one glyph in the font */
    struct GlyphAttribute
    {
        GlsFloat32  width;        /**< Glyph width in pixels */
        GlsFloat32  varTexX1;     /**< Left most x position in the texture for variable width font spacing.
                                    * (in texture coordinates) */
        GlsFloat32  varTexX2;     /**< Right most x position in the texture for variable width font spacing.
                                    * (in texture coordinates) */
        GlsFloat32  fixedTexX1;   /**< Left most x position in the texture for fixed width font spacing.
                                    * (in texture coordinates) */
        GlsFloat32  fixedTexX2;   /**< Right most x position in the texture for fixed width font spacing.
                                    * (in texture coordinates) */
        GlsFloat32  texY1;        /**< Lowest y position in the texture (in texture coordinates) */
        GlsFloat32  texY2;        /**< Upper most y position in the texture (in texture coordinates) */
        // Glyph metrics for placement
        GlsFloat32  horiBearingX; /**< Distance from pen position to the left edge of the glyph (varTexX1) for horizontal strings. */
        GlsFloat32  horiAdvance;  /**< Distance to advance the pen position after drawing this glyph for horizontal strings. */

        #if defined( GLS_DEBUG )
            /** Determine if the attributes are valid ( GLS_DEBUG only )
              * \return GLS_TRUE if valid else GLS_FALSE
              * \pre none
              * \post none
              */
            GlsBool IsValid( void ) const;
        #endif // GLS_DEBUG
    };

    /** attributes describing how a character will be rendered */
    struct RenderAttributes
    {
        GlsVector2D startPosition;  /**< position where rendering will begin */
        GlsVector2D cellSize;       /**< size of character cell to render */
        GlsFloat32  baselineShift;  /**< amount of character height to shift the character baseline,
                                      * ( -1.0f <= baselineShift <= 1.0f ) */
        GlsFloat32  scale;          /**< amount of character height to scale the char,
                                      * ( 0.0f < scale <= 1.0f ) */
        GlsFloat32  spacing;        /**< amount of character width to space the char, spacing >= 0.0f */
        GlsBool     emphasize;      /**< GLS_TRUE if char is drawn with emphasis ( bold ) else GLS_FALSE */
        GlsBool     haloEffect;     /**< GLS_TRUE if char is drawn with a halo effect else GLS_FALSE */
        GlsBool     inverse;        /**< GLS_TRUE if char is rendered with inverse video effect else GLS_FALSE */
        GlsBool     shadow;         /**< GLS_TRUE if char is rendered with a shadow */
        GlsFloat32  shadowDistance; /**< amount of cell width to offset shadow if shadow == GLS_TRUE,
                                      * ( -1.0f <= shadowDistance <= 1.0f ) */
        GlsColor    fgColor;        /**< foreground color (actual character color) */
        GlsColor    bgColor;        /**< background color */
        GlsColor    haloColor;      /**< color of halo around text if haloEffect == GLS_TRUE */
        GlsColor    shadowColor;    /**< color of shadow behind text if shadow == GLS_TRUE */
        GlsBool     uppercase;      /**< GLS_TRUE to render characters all in uppercase else GLS_FALSE */
        GlsBool     proportional;   /**< GLS_TRUE to render characters with proportional spacing else
                                      * GLS_FALSE for fixed width spacing */
        GlsBool     expandTabs;     /**< GLS_TRUE to expand tab characters width by multiplying by tabSpacing 
                                      * else GLS_FALSE */
        GlsFloat32  tabSpacing;     /**< number of tab widths to use when expanding tabs */

        #if defined( GLS_DEBUG )
            /** Determine if the render attributes are valid ( GLS_DEBUG only )
              * \return GLS_TRUE if valid else GLS_FALSE
              * \pre none
              * \post none
              */
            GlsBool IsValid( void ) const;
        #endif // GLS_DEBUG
    };

    /** initialization parameters for GlsFontBase */
    struct InitParameters
    {
        const FontAttributes            fontAttributes;     /**< font attributes */
        const GlsUInt32                 numGlyphAttributes; /**< number of glyph attribues
                                                              * in glyphAttributes array (>0)*/
        const GlyphAttribute* const     glyphAttributes;    /**< array of glyph attributes */
        const GlsImage::InlineImage     fontInlineImage;    /**< font inline image */
        
        #if defined( GLS_DEBUG )
            /** Determine if the initialization parameteres are valid ( GLS_DEBUG only )
              * \return GLS_TRUE if valid else GLS_FALSE
              * \pre none
              * \post none
              */
            GlsBool IsValid( void ) const;
        #endif // GLS_DEBUG
    };

    /** Initializes the font to begin rendering characters. This will
      * bind the font's texture.  This must be called once before
      * invoking RenderString to draw characters.
      * \param gl state manager for OpenGL
      * \pre none
      * \post 2D texturing is enabled in GL and 
      *       the font texture is bound to OpenGL with
      *       the GL_MODULATE texture env mode
      */
    void BindFontTexture( GlsStateManager &gl ) const;

    /** Renders the specified character string with the given render attributes.
      * \param gl State Manager for OpenGL where character will be drawn
      * \param str string to render ( must contain at least numChars characters )
      * \param numChars number of characters in str to render (>0)
      * \param renderAttributes desired render attributes for character 
      * \pre str != GLS_NULL, numChars > 0, renderAttributues.IsValid(),
      *      font texture is bound to GL using BindFontTexture() and setup with
      *      the desired texture filter modes
      * \post string is drawn to OpenGL
      */
    void RenderString( GlsStateManager &gl, const GlsChar* const str, const GlsUInt32 numChars,
                       const RenderAttributes &renderAttributes ) const;

    /** Get the font attributes for this font
      * \return font attributes for this font
      * \pre none
      * \post none
      */
    const FontAttributes& GetFontAttributes( void ) const;

    /** Get the glyph attributes for a given char
      * \param c char in question
      * \param uppercase GLS_TRUE to use uppercase version of char else GLS_FALSE
      * \return glyph attributes for c else glyph attributes for first character
      *         in font if c is not in range for this font
      * \pre none
      * \post none
      */
    const GlyphAttribute& GetGlyphAttribute( const GlsChar c, const GlsBool uppercase ) const;

protected:
    /** Constructor - called by derived font classes
      * \param initParameters initialization parameters
      * \pre initParameters.IsValid(), a GlsStateManager instance does not yet exist
      * \post object is constructed
      */
    GlsFontBase( const InitParameters &initParameters );

    /**  Issue the GL vertex and texture coordinates for the quad described by the given points
      * and texture coordinates
      * \param p1 first corner of quad
      * \param p2 opposite corner of quad
      * \param t1 texture coord for first corner
      * \param t2 texture coord for opposite corner
      * \pre p1.IsValid(), p2.IsValid(), t1.IsValid(), t2.IsValid()
      * \post GL vertex and texture coordinates for the quad are issued to GL
      */
    void DrawMappedQuad( const GlsVector2D &p1, const GlsVector2D &p2, const GlsVector2D &t1, const GlsVector2D &t2 ) const;

    /** Destructor - shall never be called
      * \pre none
      * \post none
      */
    virtual ~GlsFontBase();

    const FontAttributes       _fontAttributes;     /**< font attributes */
    const GlsUInt32            _numGlyphAttributes; /**< number of glyph attribues in glyphAttributes array */
    GlyphAttribute* const      _glyphAttributes;    /**< array of glyph attributes */
    const GlsImage* const      _fontImage;          /**< font texture */

private:
    // Disable implicit generated Members
    GlsFontBase& operator=( const GlsFontBase &rhs );
    GlsFontBase( const GlsFontBase &src );
};

#endif // _GLS_FONT_BASE_H