gls_text.h

Go to the documentation of this file.

#ifndef _GLS_TEXT_H
#define _GLS_TEXT_H

/*! \file gls_text.h

\brief  This header defines the GlsText base 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_render_object.h"
#include "gls_texture_vertex_array.h"
#include "gls_string.h"
#include "gls_font_base.h"
#include "gls_class_invariant.h"

// forward ref
class GlsPolygon;

/** This class serves as a base class for text displays
  * \invariant base class invariant holds,
  *            _rows > 0u, _cellWidth >= 0.0f, _cellHeight >= 0.0f,
  *            _font invariant holds, 
  *            _haloColor.IsValid(),
  *            GlsTextJustificationIsValid( _justification ),
  *            ( -1.0f <= _shadowDistance ) && ( _shadowDistance <= 1.0f ),
  *            _shadowColor.IsValid(),
  *            _str invariant holds,
  *            GlsFloatIsValid( _rowOffset ), GlsFloatIsValid( _textWidth ),
  *            GlsFloatIsValid( _textHeight ),
  *            GLS_NULL != _backgroundPoly, _backgroundPoly invariant holds,
  *            GLMatrixAffineFIsValid( _textRotationMatrix ),
  *            _underlineStrikeThruRenderers invariant holds,
  *            invariant holds for each element in the _underlineStrikeThruRenderers array
  *            GLS_NULL != _rowInfo,
  *            Each element in the _rowInfo array has valid members
  */
class GlsText : public GlsRenderObject
{
public:
    GLS_CLASS_INVARIANT_DECLARATION( GlsText )

    /** text justification modes */
    enum Justification
    {
        JUSTIFICATION_LEFT,         /**< left justify text */
        JUSTIFICATION_CENTER,       /**< center justify text */
        JUSTIFICATION_RIGHT,        /**< right justify text */

        #if defined( GLS_DEBUG )
            JUSTIFICATION_INVALID   /**< invalid text justification ( GLS_DEBUG only ) */
        #endif // GLS_DEBUG
    };

    /** Attributes for a character in the text display */
    struct CharAttribute
    {
        GlsFloat32    baselineShift;  /**< amount of cell height to baseline shift,
                                        * -1.0f <= baselineShift <= 1.0f */
        GlsColor      bgColor;        /**< background color */
        GlsColor      fgColor;        /**< text color */
        GlsBool       fauxBold;       /**< GLS_TRUE if bold is enabled GLS_FALSE */
        GlsBool       inverse;        /**< GLS_TRUE if inverse video enabled else GLS_FALSE */
        GlsFloat32    scale;          /**< scale for character cell, 0.0f < scale <= 1.0f */
        GlsFloat32    spacing;        /**< amount of character width to space the char, spacing >= 0.0f */
        GlsBool       strikeThru;     /**< GLS_TRUE if strike thru is enabled else GLS_FALSE */
        GlsBool       underline;      /**< GLS_TRUE if underline is enabled */

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

    /** initialization parameters for a GlsText object */
    struct InitParameters
    {
        const GlsRenderObject::InitParameters renderInitParameters; /**< base class initialization parameters */

        const GlsTextureVertexArray::InitParameters verticesInitParameters; /**< vertices for background poly */

        const GlsUInt32           rows;           /**< number of rows of text ( > 0 ) */
        const GlsUInt32           border;         /**< size of border in logical units */
        const GlsFloat32          cellWidth;      /**< width of character cell in logical units ( >= 0.0f ) */
        const GlsFloat32          cellHeight;     /**< height of character cell in logical units ( >= 0.0f ) */
        const GlsFontBase* const *font;           /**< font for text display */
        const GlsBool             halo;           /**< GLS_TRUE if halo is enabled else GLS_FALSE */
        const GlsColor            haloColor;      /**< initial halo color */
        const Justification       justification;  /**< text justification mode */
        const GlsFloat32          lineSpacing;    /**< amount of cell height used to space lines of text,
                                                    * ( lineSpacing >= 0.0f ) */
        const GlsUInt32           numChars;       /**< number of characters the text object can hold */
        const GlsChar* const      str;            /**< initial string value for text */
        const GlsBool             shadow;         /**< GLS_TRUE if shadow effect is on else GLS_FALSE */
        const GlsFloat32          shadowDistance; /**< amount of cell width for offset of shadow effect,
                                                    * ( -1.0f <= shadowDistance <= 1.0f ) */
        const GlsColor            shadowColor;    /**< initial color of the shadow effect behind the characters */

        const GlsBool             uppercase;      /**< GLS_TRUE if all text is displayed in uppercase else GLS_FALSE */
        const GlsBool             wrapText;       /**< GLS_TRUE if text is wrapped else GLS_FALSE */
        const CharAttribute       charAttribute;  /**< initial character attribute for all characters */

        #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
    };

    /** Draws the text object
      * \param gl GL State manager for OpenGL into which text object is drawn
      * \param time the elaspsed time in seconds since program start
      * \pre time >= 0.0
      * \post text object is drawn to OpenGL if visible and not blinked off
      */
    virtual void Draw( GlsStateManager &gl, const GlsFloat64 time );

    /** Set the alpha mode
      * \param alphaMode desired alpha mode
      * \pre GlsAlphaModeIsValid( alphaMode )
      * \post object has new alpha mode
      */
    virtual void SetAlphaMode( const GlsAlphaMode alphaMode );

     /** Set the fill color
       * \param fillColor desired fill color
       * \pre fillColor.IsValid()
       * \post object has new fill color
       */
    virtual void SetFillColor( const GlsColor &fillColor );

    /** Set the line color
      * \param lineColor desired line color
      * \pre lineColor.IsValid()
      * \post object has new line color
      */
    virtual void SetLineColor( const GlsColor &lineColor );

    /** Set the line width
      * \param lineWidth new line width,
      *        GlsRenderObject::LINE_WIDTH_MIN <= lineWidth <= GlsRenderObject::LINE_WIDTH_MAX
      * \pre GlsLineWidthIsValid( lineWidth )
      * \post object has new line width
      */
    virtual void SetLineWidth( const GlsFloat32 lineWidth );

    /** Set the polygon mode 
      * \param polygonMode new polygon mode
      * \pre GlsPolygonModeIsValid( polygonMode )
      * \post object has new polygon mode
      */
    virtual void SetPolygonMode( const GlsPolygonMode polygonMode );

    /** Set the desired texture index
      * \param textureIndex desired texture index into palette else GlsTexturePalette::NO_TEXTURE
      * \pre textureIndex is less than the size of the texture palette, else GlsTexturePalette::NO_TEXTURE,
      *      object's texture palette must have a valid texture (not an empty palette entry) at textureIndex
      *      if textureIndex != GlsTexturePalette::NO_TEXTURE
      * \post object has new texture index or is untextured if textureIndex == GlsTexturePalette::NO_TEXTURE
      */
    virtual void SetTextureIndex( const GlsUInt32 textureIndex );

    /** Offset the texture on the object
      * \param offset x, y offset for texture
      * \pre offset.IsValid()
      * \post offset is added to the texture coordinates
      */
    virtual void OffsetTexture( const GlsVector2D &offset );

    /** Set the display string.  Will truncate to size of string buffer if str will not fit
      *  in buffer.
      * \param str desired display string
      * \pre str != GLS_NULL
      * \post display string updated
      */
    void SetString( const GlsChar* const str );

    /** Set the halo color
      * \param haloColor new halo color
      * \pre haloColor.IsValid()
      * \post object has new halo olor
      */
    void SetHaloColor( const GlsColor &haloColor );

    /** Set the shadow color
      * \param shadowColor new shadow color
      * \pre shadowColor.IsValid()
      * \post object has new shadow color
      */
    void SetShadowColor( const GlsColor &shadowColor );

    /** Set the character attributes for the text ( pure virtual )
      * \param charAttribute new character attributes for the text
      * \pre charAttribue.IsValid()
      * \post text has new character attribute
      */
    virtual void SetCharAttributes( const CharAttribute &charAttribute ) = 0;

protected:
    static const GlsUInt32 NUM_VERTS_BACKGROUND_POLY = 4u; /**< required number of verts in background poly */
    static const GlsChar   NEW_LINE_CHAR;                  /**< new line character constant */
    static const GlsChar   SPACE_CHAR;                     /**< space character constant */

    /** Helper class for processing underline and strike-thru when drawing text 
      * \invariant GlsFloatIsValid( _cellWidth ), GlsFloatIsValid( _cellHeight ),
      *            GlsFloatIsValid( _shadowDistance ), 
      *            _shadowColor.IsValid(),
      *            GlsFloatIsValid( _underlineOffset ), GlsFloatIsValid( _underlineSize ),
      *            GlsFloatIsValid( _underlineX1 ), GlsFloatIsValid( _underlineX2 ),
      *            GlsFloatIsValid( _underlineY ), GlsFloatIsValid( _underlineScale ),
      *            _underlineColor.IsValid(), 
      *            GlsFloatIsValid( _strikeX1 ), GlsFloatIsValid( _strikeX2 ),
      *            GlsFloatIsValid( _strikeY ), GlsFloatIsValid( _strikeScale ),
      *            _strikeColor.IsValid(), 
      *            _maxNumLineSegments > 0u, _numLineSegments <= _maxNumLineSegments,
      *             GLS_NULL != _lineSegments,
      *             each element in the _lineSegments array is valid
      */
    class UnderlineStrikeThruRenderer
    {
    public:
        GLS_CLASS_INVARIANT_DECLARATION( UnderlineStrikeThruRenderer )

        /** describes one line segment in an underline or strikethru */
        struct LineSegment
        {
            GlsFloat32 x1;           /**< starting x coordinate of line segment */
            GlsFloat32 x2;           /**< ending x coordinate of line segment */
            GlsFloat32 y;            /**< y coordinate of line segment */
            GlsFloat32 thickness;    /**< thickness of line segment */
            GlsFloat32 shadowOffset; /**< y offset of shadowed version of line segment */
            GlsColor   segmentColor; /**< color of the line segment */

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


        /** Constructor - create an instance
          * \param numLineSegments number of line segments supported by renderer (>0)
          * \param cellWidth width of a character cell
          * \param cellHeight height of a character cell
          * \param shadow GLS_TRUE if text has shadow enabled else GLS_FALSE
          * \param shadowDistance distance for shadow
          * \param shadowColor color of shadow
          * \param underlineOffset offset of underline
          * \param underlineSize size of underline
          * \pre numLineSegments > 0,  GlsFloatIsValid() for all floating point arguments,
          *      shadowColor.IsValid()
          * \post instance created
          */
        UnderlineStrikeThruRenderer( const GlsUInt32 numLineSegments, const GlsFloat32 cellWidth,
                                     const GlsFloat32 cellHeight, const GlsBool shadow,
                                     const GlsFloat32 shadowDistance, const GlsColor &shadowColor,
                                     const GlsFloat32 underlineOffset, const GlsFloat32 underlineSize );

        /** Set the shadow color associated with the renderer
          * \param shadowColor new shadow color
          * \pre shadowColor.IsValid()
          * \post renderer has new shadow color
          */
        void SetShadowColor( const GlsColor &shadowColor );

        /** Invalidate all line segments in the renderer
          * \pre none
          * \post all line segments are invalidated, IsUpToDate() == GLS_FALSE
          */
        void Reset( void );

        /** Pre Process the given character attribute
          * \param charAttribute character attribute in question
          * \param cellX x coord of character 
          * \param charY y coord of character
          * \pre charAttribute.IsValid(), GlsFloatIsValid( cellX ), GlsFloatIsValid( charY ),
          *      IsUpToDate() == GLS_FALSE
          * \post given character attribute is preprocessed for underline / strikethru processing
          */
        void PreProcessCharacter( const GlsText::CharAttribute &charAttribute, const GlsFloat32 cellX,
                                  const GlsFloat32 charY );

        /** Post Process the given character attributes
          * \param charAttribute character attribute in question
          * \param cellX x coord of character cell one past the given character
          * \param charY y coord of character
          * \param endOfLine GLS_TRUE if character is the end of the current line else GLS_FALSE
          * \pre charAttribute.IsValid(), GlsFloatIsValid( cellX ), GlsFloatIsValid( charY ),
          *      IsUpToDate() == GLS_FALSE
          * \post given character attribute is postprocessed for underline / strikethru processing,
          *       if endOfLine then IsUpToDate() == GLS_TRUE
          */
        void PostProcessCharacter( const GlsText::CharAttribute& charAttribute, 
                                   const GlsFloat32 cellX, const GlsFloat32 charY, const GlsBool endOfLine );

        /** Render the line segments for the underline / strikethru
          * \param gl OpenGL state manager to render into
          * \pre none
          * \post line segments are rendered to GL
          */
        void RenderLineSegments( GlsStateManager &gl ) const;

        /** Determine if the line segments in the renderer are up to date
          * \pre none
          * \post none
          * \return GLS_TRUE if the line segments are up to date,
          *         GLS_FALSE if the line segments need to be recomputed
          */
        GlsBool IsUpToDate( void ) const;

    protected:
        const GlsFloat32  _cellWidth;       /**< width of one character cell */
        const GlsFloat32  _cellHeight;      /**< height of one character cell */
        const GlsBool     _shadow;          /**< GLS_TRUE if shadowing is enabled else GLS_FALSE */
        const GlsFloat32  _shadowDistance;  /**< distance of shadow line segment from primary line segment */
        GlsColor          _shadowColor;     /**< color of shadow */
        const GlsFloat32  _underlineOffset; /**< offset of underline line segment */
        const GlsFloat32  _underlineSize;   /**< size of underline segment */

        // state vars for underline processing
        GlsFloat32    _underlineX1;         /**< starting x coord for next underline line segment */
        GlsFloat32    _underlineX2;         /**< ending x x coord for next underline line segment */
        GlsFloat32    _underlineY;          /**< y coord for next underline line segment */
        GlsFloat32    _underlineScale;      /**< character scaling applied to the next underline line segment */
        GlsColor      _underlineColor;      /**< color of next underline line segment */
        GlsBool       _underlineOn;         /**< GLS_TRUE if underlining is currently on when processing characters */

        // state vars for strike-thru processing
        GlsFloat32    _strikeX1;            /**< starting x coord for next strikethru line segment */
        GlsFloat32    _strikeX2;            /**< ending x x coord for next strikethru line segment */
        GlsFloat32    _strikeY;             /**< y coord for next strikethru line segment */
        GlsFloat32    _strikeScale;         /**< character scaling applied to the next strikethru line segment */
        GlsColor      _strikeColor;         /**< color of next strikethru line segment */
        GlsBool       _strikeOn;            /**< GLS_TRUE if strikethru is currently on when processing characters */

        // line segments to draw
        const GlsUInt32    _maxNumLineSegments; /**< maximum number of line segments the renderer can hold */
        GlsUInt32          _numLineSegments;    /**< current number of line segments in the _lineSegments array
                                                  * ( <= _maxNumLineSegments ) */
        LineSegment* const _lineSegments;       /**< array of line segments to render
                                                  * ( _maxNumLineSegments number of elements )*/
        GlsBool            _isUpToDate;         /**< GLS_TRUE if _lineSegments is up to date,
                                                  *  else GLS_FALSE if the line segments need to be recomputed */

        /** Draw a line by rendering a filled polygon with a line around it so that the thickness
         * of the line can be varied and antialiasing occurs if enabled
         * \param gl GL state manager to draw into
         * \param x1 x coord of first corner of the line poly
         * \param y1 y coord of first corner of the line poly
         * \param x2 x coord of opposite corner of the line poly
         * \param y2 y coord of opposite corner of the line poly
         * \pre GlsFloatIsValid( x1 ), GlsFloatIsValid( y1 ),
         *      GlsFloatIsValid( x2 ), GlsFloatIsValid( y2 )
         * \post line is drawn to OpenGL
         */
        void DrawScalableLine( GlsStateManager &gl, const GlsFloat32 x1, const GlsFloat32 y1,
                                                    const GlsFloat32 x2, const GlsFloat32 y2 ) const;

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

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

    /** info for one row of text in the display */
    struct RowInfo
    {
        GlsUInt32  startingIndex; /**< starting text index into the display for row
                                    * else GLSUINT32_MAX if row has no characters */
        GlsUInt32  length;        /**< the number of characters in row */
        GlsFloat32 pixelWidth;    /**< the width of row in pixels */
    };

    const GlsUInt32          _rows;            /**< number of rows of text( > 0 ) */
    const GlsUInt32          _border;          /**< size of border in logical units */
    const GlsFloat32         _cellWidth;       /**< width of character cell in logical units ( >= 0.0f ) */
    const GlsFloat32         _cellHeight;      /**< height of character cell in logical units ( >= 0.0f ) */
    const GlsFontBase       &_font;            /**< font for text display */
    const GlsBool            _halo;            /**< GLS_TRUE if halo is enabled else GLS_FALSE */
    GlsColor                 _haloColor;       /**< halo color */
    const Justification      _justification;   /**< text justification mode */
    const GlsBool            _shadow;          /**< GLS_TRUE if shadow effect is on else GLS_FALSE */
    const GlsFloat32         _shadowDistance;  /**< amount of cell width for offset of shadow effect,
                                                 * ( -1.0f <= shadowDistance <= 1.0f ) */
    GlsColor                 _shadowColor;     /**< color of the shadow effect behind the characters */
    GlsString                _str;             /**< string value to display */
    const GlsBool            _uppercase;       /**< GLS_TRUE if all characters will display as uppercase 
                                                 * else GLS_FALSE */
    const GlsBool            _wrapText;        /**< GLS_TRUE if text wrapping is enabled else GLS_FALSE */
    const GlsFloat32         _rowOffset;       /**< row offset when drawing chars */
    const GlsFloat32         _textWidth;       /**< text object width when drawing */
    const GlsFloat32         _textHeight;      /**< text object height when drawing */

    GlsPolygon              *_backgroundPoly;  /**< background polygon */
    GlsMatrixAffineD::GLMatrixAffineF _textRotationMatrix;   /**< additional rotation matrix for text cells */
    GlsBool                  _textRotationMatrixIsIdentity;  /**< GLS_TRUE if _textRotationMatrix is identity 
                                                               * else GLS_FALSE */
    RowInfo* const           _rowInfo;                       /**< array ( _rows number of elements ) of RowInfo */
    GlsPointerArray          _underlineStrikeThruRenderers;  /**< array ( _rows number of elements ) where element i is
                                                               * the underline strike thru renderer for row i */

    /** Constructor - create an instance
      * \param initParameters initialization parameters
      * \param maxNumLineSegmentsPerRow maximum nubmer of line segments required per row to render
      *                                underline / strike thru line segments (>0)
      * \param eventDispatcher event dispatcher for this object else GLS_NULL
      * \pre initParameters.IsValid(), maxNumLineSegmentsPerRow > 0
      * \post instance created
      */
    GlsText( const InitParameters &initParameters, const GlsUInt32 maxNumLineSegmentsPerRow,
             GlsEventDispatcher* const eventDispatcher ); 

    /** Get the justification offset in pixels for the given row
      * \param row row in question
      * \return the justification offset in pixels for the given row
      * \pre row < _rows
      * \post none
      */
    GlsFloat32 JustificationOffset( const GlsUInt32 row ) const;

    /** Draw the characters associated with the text object
      * \param gl GL state manager to draw into
      * \pre all necessary GL matrix adjustments have been applied,
      *      the font texture has been bound to GL with GlsFontBase::BindFontTexture()
      *      and its texture filter settings have been setup
      * \post text characters are drawn to GL
      */
    virtual void DrawCharacters( GlsStateManager &gl ) = 0;

    /** Populate the _rowInfo array based on the current display string
      * \pre none
      * \post _rowInfo array is populated based on the current display string
      */
    virtual void CalculateRowData( void ) = 0;

    /** Reset all of the line underline / strikethru renderers in the text objecy
      * all of the underline and strikethru line segments to be recomputed the next time
      * the text object is drawn
      * \pre none
      * \post all of the underline / strikethru renderers are reset
      */
    void ResetUnderineStrikeThruRenderers( void );

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

private:
    typedef GlsRenderObject _BaseClass; /**< base class alias */

    // Disable implicit generated Members
    GlsText& operator=( const GlsText &rhs );
    GlsText( const GlsText &src );
};

#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given text justification mode is valid ( GLS_DEBUG only )
  * \param justification justification mode in question
  * \return GLS_TRUE if valid else GLS_FALSE
  * \pre none
  * \post none
  */
inline GlsBool GlsTextJustificationIsValid( const GlsText::Justification justification )
{
    return( ( GlsText::JUSTIFICATION_LEFT   == justification ) ||
            ( GlsText::JUSTIFICATION_CENTER == justification ) ||
            ( GlsText::JUSTIFICATION_RIGHT  == justification ) );
}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG

#endif // _GLS_TEXT_H