gls_font_renderer.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::GlsFontRenderer 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_RENDERER_H
#define _GLS_FONT_RENDERER_H

#include "gls_gl.h"
#include <string>
#include <vector>
#ifdef GLES
#    include "gls_quad_storage.h"
#    include "gls_state_manager.h"
#endif
#include "IFontImage.h"
#include "gls_color.h"
#include "gls_font_base.h"
#include "image.h"
#include "vertex.h"

//===========================================================================
//                         BEGIN NAMESPACE
//===========================================================================
namespace disti
{
//---------------------------------------------------------------------------
//                        FORWARD REFERENCES
//---------------------------------------------------------------------------
class VertexNoColor;
class GlsColor;
class Image;

typedef VertexNoColor Vector;

//===========================================================================
/**
* 
* The GlsFontRenderer object can be used to render characters from a GlsFontBase in 
* Open GL at specific locations and with several different text effects.
* Prior to rendering any characters, InitRendering must be invoked to set
* up the proper drawing environment. Then call Render for each character
* to be drawn.  
*
* \sa GlsFontBase
*
*/
//===========================================================================
class GlsFontRenderer
{
public:
    typedef GlsFontBase::Char_t     Char_t;
    typedef GlsFontBase::CharAttr_t CharAttr_t;

    //----------------------------------------
    // Character rendering state variables
    //----------------------------------------

    /** Returns the minification filter for this font */
    unsigned char TextureMinFilter()
    {
        return _textureMinFilter;
    }

    /** Sets the minification filter for this font */
    void TextureMinFilter( unsigned char val )
    {
        _textureMinFilter = val;
    }

    /** Returns the magnification filter for this font */
    unsigned char TextureMagFilter()
    {
        return _textureMagFilter;
    }

    /** Sets the magnification filter for this font */
    void TextureMagFilter( unsigned char val )
    {
        _textureMagFilter = val;
    }

    //----------------------------------------
    // Setup and cleanup for rendering
    //----------------------------------------

    /** 
    * Set the font to use.
    * The font pointer must be set before calling
    * any rendering methods
    */
    void SetFont( const GlsFontBase* font )
    {
        _font = font;
    }
    const GlsFontBase* GetFont( void )
    {
        return _font;
    }

    /** 
    * Initializes the font to begin rendering characters. This will set up
    * Open GL texture modes, bind the font's texture, set up minification
    * and magnification filters, etc.  This must be called once before 
    * invoking Render to draw characters. This version overwrites the
    * texture minification and magnification filters before initializing.
    * \param textureMinFilter Minification mode for the font texture
    * \param textureMagFilter Magnification mode for the font texture
    */
    void InitRendering(
        unsigned char textureMinFilter,
        unsigned char textureMagFilter
#ifdef GLES
        ,
        IGlsStateManager* stateManager
#endif // GLES
    )
    {
        _textureMinFilter = textureMinFilter;
        _textureMagFilter = textureMagFilter;
        InitRendering(
#ifdef GLES
            stateManager
#endif // GLES
        );
    }

    /** 
    * Initializes the font to begin rendering characters. This will set up
    * Open GL texture modes, bind the font's texture, set up minification
    * and magnification filters, etc.  This must be called before 
    * using any of the Render methods draw characters.
    */

#ifdef GLES

    void InitRendering( IGlsStateManager* stateManager )
    {
        SetupTexture( _font->Texture(), stateManager );
    }

#else // !GLES

    void InitRendering()
    {
        SetupTexture( _font->Texture() );
    }

    /** 
     * Restores the Open GL state as it was before the call to InitRendering.
     * This should be called after all characters have been rendered using
     * the Render methods.
     */
    void TermRendering()
    {
        glDisable( GL_TEXTURE_2D );
        glBlendFunc( GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA );
    } // end GlsFontRenderer::TermRendering

#endif // GLES

    //----------------------------------------
    // Rendering Methods
    //----------------------------------------

#ifdef GLES

    /** Draw a character by adding it into the supplied QuadStorage object
     * \param emphasize         Whether to draw with emphasize or not
     * \param emphasisOffset   If drawing with emphasize, the offset in logical units
     * \param inverse           Whether to draw in inverse mode or not
     * \param quadStorage       The quad storage object to render the characters into
     * \param x1                lower left corner x coordinate of the polygon
     * \param y1                lower left corner y coordinate of the polygon
     * \param x2                upper right corner x coordinate of the polygon
     * \param y2                upper right corner y coordinate of the polygon
     */
    void DrawCharacter(
        const bool         emphasize,
        const float        emphasisOffset,
        const bool         inverse,
        GlsQuadListVCT_2D& quadStorage,
        const GLfloat      x1,
        const GLfloat      y1,
        const GLfloat      x2,
        const GLfloat      y2 ) const
    {
        // character color
        quadStorage.AddQuad2D( x1, y1, x2, y2 );

        // Character emphasis. Draw two more cells offset a little so
        // character appears bolded.
        if( emphasize && !inverse )
        {
            GLfloat offsetY1( y1 + emphasisOffset );
            GLfloat offsetY2( y2 + emphasisOffset );

            quadStorage.AddQuad2D( x1 - emphasisOffset, offsetY1, x2 - emphasisOffset, offsetY2 );
            quadStorage.AddQuad2D( x1 + emphasisOffset, offsetY1, x2 + emphasisOffset, offsetY2 );
        }

    } // end GlsFontRenderer::DrawCharacter

    /**
    * Draws a halo effect for the given character.
    *
    * \param c          the character code to render
    * \param haloOffset Controls the size of the halo
    *                   GlsTextGrid uses: (emphasize ? 0.05f : 0.03f) * (character_width) (x2 - x1)
    * \param _vertArray Pointer to the currently bound vertex array
    * \param x1         lower left corner x coordinate of the polygon
    * \param y1         lower left corner y coordinate of the polygon
    * \param x2         upper right corner x coordinate of the polygon
    * \param y2         upper right corner y coordinate of the polygon
    */
    void DrawHalo(
        const float        haloOffset,
        GlsQuadListVCT_2D& quadStorage,
        const GLfloat      x1,
        const GLfloat      y1,
        const GLfloat      x2,
        const GLfloat      y2 ) const
    {
        const GLfloat x1right( x1 + haloOffset );
        const GLfloat x1left( x1 - haloOffset );
        const GLfloat x2right( x2 + haloOffset );
        const GLfloat x2left( x2 - haloOffset );
        const GLfloat y1up( y1 + haloOffset );
        const GLfloat y1down( y1 - haloOffset );
        const GLfloat y2up( y2 + haloOffset );
        const GLfloat y2down( y2 - haloOffset );

        quadStorage.AddQuad2D( x1left, y1up, x2left, y2up );
        quadStorage.AddQuad2D( x1left, y1down, x2left, y2down );
        quadStorage.AddQuad2D( x1right, y1up, x2right, y2up );
        quadStorage.AddQuad2D( x1right, y1down, x2right, y2down );
    }

#else // !GLES

    /**
    * Draws a character.
    *
    * \param emphasize  true if the rendered character should be emphasized.
    *                   This will essentially bold the character. If a bold
    *                   font is being used, the character will appear even
    *                   more bolded.
    * \param emphasisOffset Magnitude of the emhpasis offset.  A good value to try is (0.2 * character_width).
    * \param inverse    true if the rendered character should be inverse 
    *                   video. This makes the text see-through and it's
    *                   background the text foreground color.
    * \param x1         lower left corner x coordinate of the polygon
    * \param y1         lower left corner y coordinate of the polygon
    * \param x2         upper right corner x coordinate of the polygon
    * \param y2         upper right corner y coordinate of the polygon
    * \param tx1        lower left corner x texture coordinate
    * \param ty1        lower left corner y texture coordinate
    * \param tx2        upper right corner x texture coordinate
    * \param ty2        upper right corner y texture coordinate
    */
    void DrawCharacter(
        const bool    emphasize,
        const float   emphasisOffset,
        const bool    inverse,
        const GLfloat x1,
        const GLfloat y1,
        const GLfloat x2,
        const GLfloat y2,
        const GLfloat tx1,
        const GLfloat ty1,
        const GLfloat tx2,
        const GLfloat ty2 ) const
    {
        // character color
        glBlendFunc( inverse ? GL_ONE_MINUS_SRC_ALPHA : GL_SRC_ALPHA,
            inverse ? GL_SRC_ALPHA : GL_ONE_MINUS_SRC_ALPHA );

        glBegin( GL_QUADS );

        MapTexture( x1, y1, x2, y2, tx1, ty1, tx2, ty2 );
        // Character emphasis. Draw two more cells offset a little so
        // character appears bolded.
        if( emphasize && !inverse )
        {
            GLfloat offsetY1( y1 + emphasisOffset );
            GLfloat offsetY2( y2 + emphasisOffset );

            MapTexture(
                x1 - emphasisOffset, offsetY1, x2 - emphasisOffset, offsetY2,
                tx1, ty1, tx2, ty2 );

            MapTexture(
                x1 + emphasisOffset, offsetY1, x2 + emphasisOffset, offsetY2,
                tx1, ty1, tx2, ty2 );
        }

        glEnd();
    } // end GlsFontRenderer::DrawCharacter

    /**
    * Draws a halo effect for the given character.
    *
    * \param haloOffset Controls the size of the halo
    *                   GlsTextGrid uses: (emphasize ? 0.05f : 0.03f) * (character_width) (x2 - x1)
    * \param x1         lower left corner x coordinate of the polygon
    * \param y1         lower left corner y coordinate of the polygon
    * \param x2         upper right corner x coordinate of the polygon
    * \param y2         upper right corner y coordinate of the polygon
    * \param tx1        lower left corner x texture coordinate
    * \param ty1        lower left corner y texture coordinate
    * \param tx2        upper right corner x texture coordinate
    * \param ty2        upper right corner y texture coordinate
    */
    void DrawHalo(
        const float   haloOffset,
        const GLfloat x1,
        const GLfloat y1,
        const GLfloat x2,
        const GLfloat y2,
        const GLfloat tx1,
        const GLfloat ty1,
        const GLfloat tx2,
        const GLfloat ty2 ) const
    {
        // Halo effect.
        GLfloat x1right( x1 + haloOffset );
        GLfloat x1left( x1 - haloOffset );
        GLfloat x2right( x2 + haloOffset );
        GLfloat x2left( x2 - haloOffset );
        GLfloat y1up( y1 + haloOffset );
        GLfloat y1down( y1 - haloOffset );
        GLfloat y2up( y2 + haloOffset );
        GLfloat y2down( y2 - haloOffset );

        glBegin( GL_QUADS );

        // Shift left and up
        MapTexture(
            x1left, y1up, x2left, y2up,
            tx1, ty1, tx2, ty2 );

        // Shift left and down
        MapTexture(
            x1left, y1down, x2left, y2down,
            tx1, ty1, tx2, ty2 );

        // Shift right and up
        MapTexture(
            x1right, y1up, x2right, y2up,
            tx1, ty1, tx2, ty2 );

        // Shift right and down
        MapTexture(
            x1right, y1down, x2right, y2down,
            tx1, ty1, tx2, ty2 );

        glEnd();
    } // end GlsFontRenderer::DrawHalo

    /**
    * Draws a drop shadow effect for a character.
    * \param shadowOffset distance to offset the shadow from the character
    * \param x1         lower left corner x coordinate of the polygon
    * \param y1         lower left corner y coordinate of the polygon
    * \param x2         upper right corner x coordinate of the polygon
    * \param y2         upper right corner y coordinate of the polygon
    * \param tx1        lower left corner x texture coordinate
    * \param ty1        lower left corner y texture coordinate
    * \param tx2        upper right corner x texture coordinate
    * \param ty2        upper right corner y texture coordinate
    */
    void DrawShadow(
        const float   shadowOffset,
        const GLfloat x1,
        const GLfloat y1,
        const GLfloat x2,
        const GLfloat y2,
        const GLfloat tx1,
        const GLfloat ty1,
        const GLfloat tx2,
        const GLfloat ty2 ) const
    {
        // Shadow effect.
        glBegin( GL_QUADS );

        // Shift right and down
        MapTexture(
            x1 + shadowOffset,
            y1 - shadowOffset,
            x2 + shadowOffset,
            y2 - shadowOffset,
            tx1, ty1, tx2, ty2 );

        glEnd();

    } // end GlsFontRenderer::DrawShadow

    /** 
    * Map a square piece of a texture onto a quad ( assumed to be called 
between glBegin(GL_QUADS)...glEnd() pair )
    * \param x1  the lower left corner x of the quad
    * \param y1  the lower left corner y of the quad
    * \param x2  the upper right corner x of the quad
    * \param y2  the upper right corner  of the quad
    * \param tx1 lower left corner x texture coordinate
    * \param ty1 lower left corner y texture coordinate
    * \param tx2 upper right corner x texture coordinate
    * \param ty2 upper right corner y texture coordinate
    */
    static void MapTexture(
        const GLfloat x1,
        const GLfloat y1,
        const GLfloat x2,
        const GLfloat y2,
        const GLfloat tx1,
        const GLfloat ty1,
        const GLfloat tx2,
        const GLfloat ty2 )
    {
        glTexCoord2f( tx1, ty1 );
        glVertex2f( x1, y1 );
        glTexCoord2f( tx2, ty1 );
        glVertex2f( x2, y1 );
        glTexCoord2f( tx2, ty2 );
        glVertex2f( x2, y2 );
        glTexCoord2f( tx1, ty2 );
        glVertex2f( x1, y2 );
    }

#endif // GLES

    /**
    * Create a GlsFontRenderer with the default settings.
    * \param font The font to use for rendering.  This may be NULL on creation, but it must be set before rendering.
    */
    GlsFontRenderer( const GlsFontBase* font )
        : _font( font )
        , _textureMinFilter( TEXTURE_FILTER_LINEAR )
        , _textureMagFilter( TEXTURE_FILTER_LINEAR )
    {
    }

protected:
#ifndef GLES
    /** Current drawing color is kept so we don't have to make an OpenGL call if the color is the same */
    GlsColor _currentColor;
#endif

    /** Pointer to the font to use for rendering */
    const GlsFontBase* _font;

    /** Minification mode for the font texture */
    unsigned char _textureMinFilter;

    /** Magnification mode for the font texture */
    unsigned char _textureMagFilter;

    /** 
    * Helper method to set up Open GL texture modes, bind the font's texture,
    * set up minification and magnification filters, etc.
    */

#ifdef GLES

    void SetupTexture( IFontImage* texture, IGlsStateManager* stateManager )
    {
        const bool mipMap = ( ( TEXTURE_FILTER_NEAREST_MIPMAP_NEAREST == _textureMinFilter ) || ( TEXTURE_FILTER_LINEAR_MIPMAP_LINEAR == _textureMinFilter ) || ( TEXTURE_FILTER_NEAREST_MIPMAP_LINEAR == _textureMinFilter ) || ( TEXTURE_FILTER_LINEAR_MIPMAP_NEAREST == _textureMinFilter ) );
        if( mipMap )
        {
            // This will force the image to create the mipmap images
            texture->MipMap( true );
        }

        // Initialize the font texture
        stateManager->Texture2DEnabled( true );
        stateManager->BindTexture( texture );

        // Set up mip mapping for magnification
        if( _textureMagFilter == TEXTURE_FILTER_NEAREST )
        {
            stateManager->SetTextureMagFilter( GL_NEAREST );
        }
        else if( _textureMagFilter == TEXTURE_FILTER_LINEAR )
        {
            stateManager->SetTextureMagFilter( GL_LINEAR );
        }

        // Set up mip mapping for minification
        switch( _textureMinFilter )
        {
        case TEXTURE_FILTER_NEAREST:
            stateManager->SetTextureMinFilter( GL_NEAREST );
            break;

        case TEXTURE_FILTER_LINEAR:
            stateManager->SetTextureMinFilter( GL_LINEAR );
            break;

        case TEXTURE_FILTER_NEAREST_MIPMAP_NEAREST:
            stateManager->SetTextureMinFilter( GL_NEAREST_MIPMAP_NEAREST );
            break;

        case TEXTURE_FILTER_LINEAR_MIPMAP_LINEAR:
            stateManager->SetTextureMinFilter( GL_LINEAR_MIPMAP_LINEAR );
            break;

        case TEXTURE_FILTER_NEAREST_MIPMAP_LINEAR:
            stateManager->SetTextureMinFilter( GL_NEAREST_MIPMAP_LINEAR );
            break;

        case TEXTURE_FILTER_LINEAR_MIPMAP_NEAREST:
            stateManager->SetTextureMinFilter( GL_LINEAR_MIPMAP_NEAREST );
            break;
        }

        stateManager->SetTextureEnvMode( IGlsStateManager::GLS_TEXTURE_MAP_MODE_MODULATE );

    } // end GlsFontRenderer::SetupTexture

#else // !GLES

    void SetupTexture( IFontImage* texture )
    {
        const bool mipMap = ( ( TEXTURE_FILTER_NEAREST_MIPMAP_NEAREST == _textureMinFilter ) || ( TEXTURE_FILTER_LINEAR_MIPMAP_LINEAR == _textureMinFilter ) || ( TEXTURE_FILTER_NEAREST_MIPMAP_LINEAR == _textureMinFilter ) || ( TEXTURE_FILTER_LINEAR_MIPMAP_NEAREST == _textureMinFilter ) );
        if( mipMap )
        {
            // This will force the image to create the mipmap images
            texture->MipMap( true );
        }

        // Initialize the drawing color
        glColor4ubv( _currentColor.RGBA() );

        // Initialize the font texture
        glEnable( GL_TEXTURE_2D );
        texture->BindTexture();

        // Set up mip mapping for magnification
        if( _textureMagFilter == TEXTURE_FILTER_NEAREST )
        {
            glTexParameteri( GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_NEAREST );
        }
        else if( _textureMagFilter == TEXTURE_FILTER_LINEAR )
        {
            glTexParameteri( GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR );
        }

        // Set up mip mapping for minification
        switch( _textureMinFilter )
        {
        case TEXTURE_FILTER_NEAREST:
            glTexParameteri( GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST );
            break;
        case TEXTURE_FILTER_LINEAR:
            glTexParameteri( GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR );
            break;
        case TEXTURE_FILTER_NEAREST_MIPMAP_NEAREST:
            glTexParameteri( GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST_MIPMAP_NEAREST );
            break;
        case TEXTURE_FILTER_LINEAR_MIPMAP_LINEAR:
            glTexParameteri( GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR_MIPMAP_LINEAR );
            break;
        case TEXTURE_FILTER_NEAREST_MIPMAP_LINEAR:
            glTexParameteri( GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST_MIPMAP_LINEAR );
            break;
        case TEXTURE_FILTER_LINEAR_MIPMAP_NEAREST:
            glTexParameteri( GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR_MIPMAP_NEAREST );
            break;
        }

        glTexEnvi( GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_MODULATE );

    } // end GlsFontRenderer::SetupTexture

#endif // GLES

}; // end class GlsFontRenderer

} // end namespace disti

#endif