gls_state_manager.h

Go to the documentation of this file.

#ifndef _GLS_STATE_MANAGER_H
#define _GLS_STATE_MANAGER_H

/*! \file gls_state_manager.h
\brief  This header defines the GL State Manager class for managing the GL
        state 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_gl.h"
#include "gls_color.h"
#include "gls_class_invariant.h"

/** This class manages OpenGL context state and allows for minimizing calls to OpenGL.
  * \invariant 
  *    GlsGLAlphaFuncIsValid( _alphaFunc ),
  *    ( 0.0f <= _alphaRef ) && ( _alphaRef <= 1.0f ),
  *    GlsGLBlendFuncSFactorIsValid( _alphaBlendSFactor ),
  *    GlsGLBlendFuncDFactorIsValid( _alphaBlendDFactor ),
  *    GlsGLDepthFuncIsValid( _depthFunc ),
  *    GlsGLShadeModelIsValid( _shadeModel ),
  *    _color.IsValid(),
  *    ( ( GlsStateManager::LINE_WIDTH_MIN <= _lineWidth ) && ( _lineWidth <= GlsStateManager::LINE_WIDTH_MAX ) ),
  *    GlsGLPolygonModeIsValid( _polygonMode ) ),
  *    ( ( 0 == _glBeginCount ) || ( 1 == _glBeginCount ) ),
  *    ( 1 == _numInstCreated ),
  *    OpenGL state is synchronized with the state manager
  */
class GlsStateManager
{
public:
    GLS_CLASS_INVARIANT_DECLARATION( GlsStateManager )

    #if defined( GLS_DEBUG )
        static const GLfloat LINE_WIDTH_MIN; /**< mimimum line width */
        static const GLfloat LINE_WIDTH_MAX; /**< maximum line width */
    #endif // GLS_DEBUG

    /** invalid GL texture index */
    static const GLuint INVALID_GL_TEXTURE_INDEX    =   0u;

    /** Get the singleton GlsStateManager instance
      * \pre precondition for constructor must hold first time this method is called
      * \post postcondition for constructor holds after the first time this method is called
      * \return the singleton GlsStateManager instance
      */
    static GlsStateManager& GetStateManager( void );

    /** Reset the cached GL state variables and set them into the GL state
      * \pre none
      * \post cached GL state variables are set to default values and 
      *       GL is synchronized with state manager
      */
    void ResetOpenGLState( void );

    /** equivalent to glBegin() call
     * \param mode primitive mode to begin
     * \pre must not be within a begin/end pair,
     *      mode is a valid GL primitive mode
     * \post a new primitive is started
     */
    void Begin( const GLenum mode );

    /** equivalent to glEnd() call
      * \pre must be called within a begin/end pair
      * \post primitive is ended
      */
    void End( void );

    /** equivalent to glBindTexture( GL_TEXTURE_2D, .. ) call
      * \param textureIndex GL texture index of texture to bind ( >0 )
      * \pre textureIndex > 0, textureIndex is a valid GL texture index,
      *      not within a begin/end pair
      * \post desired 2D texture is bound to GL 
      */
    void BindTexture2D( const GLuint textureIndex );

    /** equivalent to glLineWidth() call
      * \param lineWidth new line width ( GlsStateManager::LINE_WIDTH_MIN <= width <= GlsStateManager::LINE_WIDTH_MAX )
      * \pre GlsStateManager::LINE_WIDTH_MIN <= width <= GlsStateManager::LINE_WIDTH_MAX,
      *      not within a begin/end pair
      * \post GL has new line width
      */
    void LineWidth( const GLfloat lineWidth );

    /** equivalent to glAlphaFunc() call
      * \param func GL alpha comparison mode
      * \param ref GL alpha reference value
      * \pre GlsGLAlphaFuncIsValid( func ),
             0.0f <= ref <= 1.0f, not within a begin/end pair
      * \post new GL alpha mode and reference are set
      */
    void AlphaFunc( const GLenum func, const GLclampf ref );

    /** equivalent to glColor() call
      * \param color new color
      * \pre color.IsValid()
      * \post new GL color is set
      */
    void Color( const GlsColor &color );

    /** equivalent to glBlendFunc() call
      * \param sfactor alpha source mode
      * \param dfactor alpha destination mode
      * \pre GlsGLBlendFuncSFactorIsValid( sfactor ),
      *      GlsGLBlendFuncDFactorIsValid( dfactor ),
      *      not within a begin/end pair
      * \post new GL alpha blend mode is set
      */
    void BlendFunc( const GLenum sfactor, const GLenum dfactor );

    /** equivalent to glShadeModel() call
      * \param mode new GL shade mode
      * \pre GlsGLShadeModelIsValid( mode ), not within a begin/end pair
      * \post new GL shade model is set
      */
    void ShadeModel( const GLenum mode );

    /** equivalent to glDepthFunc() call
      * \param func new GL depth function
      * \pre GlsGLDepthFuncIsValid( func ), not within a begin/end pair
      * \post new GL depth function is set
      */
    void DepthFunc( const GLenum func );

    /** equivalent to glEnable(GL_ALPHA_TEST)/glDisable(GL_ALPHA_TEST) call
      * \param enable GLS_TRUE to enable else GLS_FALSE
      * \pre not within a begin/end pair
      * \post GL_ALPHA_TEST is enabled if enable == GLS_TRUE else,
      *       GL_ALPHA_TEST is disabled 
      */
    void EnableAlphaTest( const GlsBool enable );

    /** equivalent to glEnable(GL_BLEND)/glDisable(GL_BLEND) call
      * \param enable GLS_TRUE to enable else GLS_FALSE
      * \pre not within a begin/end pair
      * \post GL_BLEND is enabled if enable == GLS_TRUE else,
      *       GL_BLEND is disabled 
      */
    void EnableBlend( const GlsBool enable );

    /** equivalent to glEnable(GL_CULL_FACE)/glDisable(GL_CULL_FACE) call
      * \param enable GLS_TRUE to enable else GLS_FALSE
      * \pre not within a begin/end pair
      * \post GL_CULL_FACE is enabled if enable == GLS_TRUE else,
      *       GL_CULL_FACE is disabled 
      */
    void EnableCullFace( const GlsBool enable );

    /** equivalent to glEnable(GL_DEPTH_TEST)/glDisable(GL_DEPTH_TEST) call
      * \param enable GLS_TRUE to enable else GLS_FALSE
      * \pre not within a begin/end pair
      * \post GL_DEPTH_TEST is enabled if enable == GLS_TRUE else,
      *       GL_DEPTH_TEST is disabled 
      */
    void EnableDepthTest( const GlsBool enable );

    /** equivalent to glEnable(GL_LINE_SMOOTH)/glDisable(GL_LINE_SMOOTH) call
      * \param enable GLS_TRUE to enable else GLS_FALSE
      * \pre not within a begin/end pair
      * \post GL_LINE_SMOOTH is enabled if enable == GLS_TRUE else,
      *       GL_LINE_SMOOTH is disabled 
      */
    void EnableLineSmooth( const GlsBool enable );

    /** equivalent to glEnable(GL_TEXTURE_2D)/glDisable(GL_TEXTURE_2D) call
      * \param enable GLS_TRUE to enable else GLS_FALSE
      * \pre not within a begin/end pair
      * \post GL_TEXTURE_2D is enabled if enable == GLS_TRUE else,
      *       GL_TEXTURE_2D is disabled 
      */
    void EnableTexture2D( const GlsBool enable );

    /** equivalent to glTexParameteri(GL_TEXTURE_2D,...) call
      * \param pname GL texture parameter name
      * \param param new value for indicated parameter
      * \pre GlsGLTextureParameterIsValid( pname ),
      *      pname == GL_TEXTURE_MIN_FILTER -> GlsGLTextureMinFilterIsValid( param ),
      *      pname == GL_TEXTURE_MAG_FITLER -> GlsGLTextureMagFilterIsValid( param ),
      *      pname == GL_TEXTURE_WRAP_S     -> GlsGLTextureWrapIsValid( param ),
      *      pname == GL_TEXTURE_WRAP_T     -> GlsGLTextureWrapIsValid( param ),
      *      not within a begin/end pair
      * \post given GL texture parameter is set to new value
      */
    void TexParameteri2D( const GLenum pname, const GLint param );

    /** equivalent to glTexEnvi(GL_TEXTURE_ENV,GL_TEXTURE_ENV_MODE,...) call
      * \param param new value for texture environment mode
      * \pre GlsGLTetxureEnvModeIsValid( param ),
      *      not within a begin/end pair
      * \post GL texture environment mode is set to new value
      */
    void TexEnvi( const GLint param );

    #if defined( GLS_DEBUG )
        /** Determine how many state manager instances that have been created ( GLS_DEBUG only )
          * \return numner of state manager instances that have been created
          * \pre none
          * \post none
          */
        static GlsUInt32 GetNumberOfInstancesCreated( void );
    #endif // GLS_DEBUG

protected:
    /** Constructor - create an instance
      * \pre not within a begin/end pair, glGetError() == GL_NO_ERROR,
      *      no other state manager has been created
      * \post instance created, OpenGL state is synchronized with state manager
      */
    GlsStateManager( void );

    GLenum      _alphaFunc;         /**< current GL alpha function */
    GLclampf    _alphaRef;          /**< current GL alpha reference value */
    GlsBool     _alphaTest;         /**< current GL Alpha Testing state (Screen door transparency) */

    GlsBool     _alphaBlend;        /**< current GL Alpha Blending state */
    GLenum      _alphaBlendSFactor; /**< current GL Alpha Blending source factor */
    GLenum      _alphaBlendDFactor; /**< current GL Alpha Blending destination factor */

    GlsBool     _depthTest;         /**< current GL Depth Testing state */
    GLenum      _depthFunc;         /**< current GL Depth Testing function */

    GlsBool     _lineSmooth;        /**< current GL Line anti-aliasing */

    GlsBool     _cullFace;          /**< current GL Backface culling state */

    GLenum      _shadeModel;        /**< current GL shading model */

    GlsColor    _color;             /**< current GL Drawing color */

    GlsBool     _texture2D;         /**< current GL 2D texture state */

    GLuint      _textureIndex2D;    /**< current index of GL 2D bound texture else
                                      * GlsStateManager::INVALID_GL_TEXTURE_INDEX if no texture is bound */

    GLfloat     _lineWidth;         /**< current GL Line width */

    GLenum      _polygonMode;       /**< current GL Polygon Draw Mode */

    #if defined( GLS_DEBUG )
        GlsInt32         _glBeginCount;     /**< begin / end pair indicator ( GLS_DEBUG only ) */
        static GlsUInt32 _numInstCreated;   /**< number of state managers that have been instantiated
                                              * ( GLS_DEBUG only ) */
    #endif

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

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

#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given GL alpha function enum is valid ( GLS_DEBUG only )
  * \param alphaFunc GL alpha function enum in question
  * \return GLS_TRUE if valid else GLS_FALSE
  * \pre none
  * \post none
  */
inline GlsBool GlsGLAlphaFuncIsValid( const GLenum alphaFunc )
{
    return( ( GL_NEVER  == alphaFunc ) || ( GL_LESS    == alphaFunc ) || ( GL_EQUAL    == alphaFunc ) ||
            ( GL_LEQUAL == alphaFunc ) || ( GL_GREATER == alphaFunc ) || ( GL_NOTEQUAL == alphaFunc ) ||
            ( GL_GEQUAL == alphaFunc ) || ( GL_ALWAYS  == alphaFunc ) );
}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG


#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given GL blend source factor enum is valid ( GLS_DEBUG only )
  * \param sfactor GL blend source factor enum in question
  * \return GLS_TRUE if valid else GLS_FALSE
  */
inline GlsBool GlsGLBlendFuncSFactorIsValid( const GLenum sfactor )
{
    return( ( GL_ZERO               == sfactor ) || ( GL_ONE                 == sfactor ) ||
            ( GL_DST_COLOR          == sfactor ) || ( GL_ONE_MINUS_DST_COLOR == sfactor ) ||
            ( GL_SRC_ALPHA          == sfactor ) || ( GL_ONE_MINUS_SRC_ALPHA == sfactor ) ||
            ( GL_DST_ALPHA          == sfactor ) || ( GL_ONE_MINUS_DST_ALPHA == sfactor ) ||
            ( GL_SRC_ALPHA_SATURATE == sfactor ) );
}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG

#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given GL blend dest factor enum is valid ( GLS_DEBUG only )
  * \param dfactor GL blend dest factor enum in question
  * \return GLS_TRUE if valid else GLS_FALSE
  */
inline GlsBool GlsGLBlendFuncDFactorIsValid( const GLenum dfactor )
{
    return( ( GL_ZERO      == dfactor ) || ( GL_ONE                 == dfactor ) || 
            ( GL_SRC_COLOR == dfactor ) || ( GL_ONE_MINUS_SRC_COLOR == dfactor ) ||
            ( GL_SRC_ALPHA == dfactor ) || ( GL_ONE_MINUS_SRC_ALPHA == dfactor ) ||
            ( GL_DST_ALPHA == dfactor ) || ( GL_ONE_MINUS_DST_ALPHA == dfactor ) );
}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG

#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given GL depth function enum is valid ( GLS_DEBUG only )
  * \param func GL depth function enum in question
  * \return GLS_TRUE if valid else GLS_FALSE
  */
inline GlsBool GlsGLDepthFuncIsValid( const GLenum func )
{
    return( ( GL_NEVER  == func ) || ( GL_LESS    == func ) || ( GL_LEQUAL   == func ) ||
            ( GL_EQUAL  == func ) || ( GL_GREATER == func ) || ( GL_NOTEQUAL == func ) ||
            ( GL_GEQUAL == func ) || ( GL_ALWAYS  == func ) );
}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG

#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given GL shade model enum is valid ( GLS_DEBUG only )
  * \param mode GL shade model in question
  * \return GLS_TRUE if valid else GLS_FALSE
  */
inline GlsBool GlsGLShadeModelIsValid( const GLenum mode )
{
    return( ( GL_FLAT == mode ) || ( GL_SMOOTH == mode ) );
}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG

#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given GL texture environment mode is valid ( GLS_DEBUG only )
  * \param mode GL texture environment mode in question
  * \return GLS_TRUE if valid else GLS_FALSE
  */
inline GlsBool GlsGLTetxureEnvModeIsValid( const GLint mode )
{
    return( ( GL_MODULATE == mode ) || ( GL_DECAL   == mode ) ||
            ( GL_BLEND    == mode ) || ( GL_REPLACE == mode ) );
}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG

#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given GL texture parameter is valid ( GLS_DEBUG only )
  * \param pname GL texture parameter in question
  * \return GLS_TRUE if valid else GLS_FALSE
  */
inline GlsBool GlsGLTextureParameterIsValid( const GLenum pname )
{
    return( ( GL_TEXTURE_MIN_FILTER == pname ) || ( GL_TEXTURE_MAG_FILTER == pname ) ||
            ( GL_TEXTURE_WRAP_S     == pname ) || ( GL_TEXTURE_WRAP_T     == pname ) );
}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG

#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given GL texture minification mode is valid ( GLS_DEBUG only )
  * \param param GL texture minification mode in question
  * \return GLS_TRUE if valid else GLS_FALSE
  */
inline GlsBool GlsGLTextureMinFilterIsValid( const GLint param )
{
    return( ( GL_NEAREST                == param ) || ( GL_LINEAR                == param ) ||
            ( GL_NEAREST_MIPMAP_NEAREST == param ) || ( GL_LINEAR_MIPMAP_NEAREST == param ) ||
            ( GL_NEAREST_MIPMAP_LINEAR  == param ) || ( GL_LINEAR_MIPMAP_LINEAR  == param ) );
}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG

#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given GL texture magnification mode is valid ( GLS_DEBUG only )
  * \param param GL texture magnification mode in quesion
  * \return GLS_TRUE if valid else GLS_FALSE
  */
inline GlsBool GlsGLTextureMagFilterIsValid( const GLint param )
{
    return( ( GL_NEAREST == param ) || ( GL_LINEAR == param ) );
}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG

#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given GL texture wrap mode is valid ( GLS_DEBUG only )
  * \param param GL texture wrap mode in question
  * \return GLS_TRUE if valid else GLS_FALSE
  */
inline GlsBool GlsGLTextureWrapIsValid( const GLint param )
{
    return( ( GL_CLAMP == param ) || ( GL_REPEAT == param ) );
}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG

#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given GL polygon mode is valid ( GLS_DEBUG only )
  * \param mode GL polygon mode in question
  * \return GLS_TRUE if valid else GLS_FALSE
  */
inline GlsBool GlsGLPolygonModeIsValid( const GLenum mode )
{
    return( ( GL_POINT == mode ) || ( GL_LINE == mode ) || ( GL_FILL == mode ) );
}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG

#endif // _GLS_STATE_MANAGER_H