gls_render_object.h

Go to the documentation of this file.

#ifndef _GLS_RENDER_OBJECT_H
#define _GLS_RENDER_OBJECT_H

/*! \file gls_render_object.h
\brief  This header defines an abstract class for a display object that is
        directly rendered to OpenGL (not a composite of other objects) and
        maintains its own draw settings.
        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_display_object.h"
#include "gls_render_settings.h"
#include "gls_texture_palette.h"

/** Defines an abstract class for a display object that is
  * directly rendered to OpenGL (not a composite of other objects) and
  * maintains its own draw settings
  * \invariant base class invariant holds,
  *           _texturePalette.Invariant();
  *           GlsTextureMapModeIsValid( _textureMapMode ),
  *           GlsTextureFilterModeIsValid( _textureMagFilterMode ),
  *           GlsTextureFilterModeIsValid( _textureMinFilterMode ),
  *           GlsDepthBufferModeIsValid( _depthBufferMode ),
  *           GlsPolygonEndModeIsValid( _polygonEndMode ),
  *           GlsAlphaModeIsValid( _alphaMode ),
  *           _lineColor.IsValid(),
  *           ( GlsTexturePalette::NO_TEXTURE == _textureIndex ) ||
  *                ( _textureIndex < _texturePalette.GetSize() ),
  *           GlsPolygonModeIsValid( _polygonMode ),
  *           GlsShadingModeIsValid( _shadingMode ),
  *           _fillColor.IsValid(),
  *           GlsLineWidthIsValid( _lineWidth )
  */
class GlsRenderObject : public GlsDisplayObject
{
public:
    GLS_CLASS_INVARIANT_DECLARATION( GlsRenderObject )

    #if defined( GLS_DEBUG )
        /** minimum allowable line width */
        static const GlsFloat32 LINE_WIDTH_MIN;
        /** maximum allowable line width */
        static const GlsFloat32 LINE_WIDTH_MAX;
    #endif // GLS_DEBUG

    /** initialization parameters for a GlsRenderObject */
    struct InitParameters
    {
        const GlsDisplayObject::InitParameters displayInitParameters; /**< init parameters for base class */

        const GlsAlphaMode              alphaMode;            /**< initial alpha mode */
        const GlsBool                   antiAlias;            /**< GLS_TRUE if object is antialiased
                                                                * else GLS_FALSE */
        const GlsBool                   cullBackFace;         /**< GLS_TRUE if backface culling is enabled
                                                                * else GLS_FALSE */
        const GlsDepthBufferMode        depthBufferMode;      /**< Depth buffer test / write mode */
        const GlsColor                  fillColor;            /**< initial fill color */
        const GlsColor                  lineColor;            /**< initial line color */
        const GlsFloat32                lineWidth;            /**< initial line width in pixels,
                                                                * GlsRenderObject::LINE_WIDTH_MIN <= lineWidth,
                                                                * lineWidth <= GlsRenderObject::LINE_WIDTH_MAX */
        const GlsPolygonMode            polygonMode;          /**< initial polygon mode */
        const GlsPolygonEndMode         polygonEndMode;       /**< Polygon end mode */
        const GlsShadingMode            shadingMode;          /**< Shading mode */
        const GlsUInt32                 textureIndex;         /**< initial texture index into palette
                                                                * else GlsTexturePalette::NO_TEXTURE */
        const GlsTextureMapMode         textureMapMode;       /**< texture mapping mode */
        const GlsTextureFilterMode      textureMagFilterMode; /**< texture magnification filtering mode */
        const GlsTextureFilterMode      textureMinFilterMode; /**< texture minification filtering mode */
        const GlsTexturePalette* const *texturePalette;       /**< palette of textures available */
        const GlsBool                   textureRepeat;        /**< GLS_TRUE to enable texture repeat
                                                                * else GLS_FALSE for texture clamp */

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

    /** 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 ) = 0;

protected:
    static const GLclampf       ALPHA_MODE_2_LEVEL_REF; /**< alpha function reference value when in 2 level alpha mode */

    const GlsBool               _antiAlias;            /**< GLS_TRUE if antialiasing is enabled else GLS_FALSE */
    const GlsTexturePalette    &_texturePalette;       /**< palette with textures available to object */
    const GlsBool               _textureRepeat;        /**< GLS_TRUE to enable texture repeat
                                                         * else GLS_FALSE for texture clamp */
    const GlsTextureMapMode     _textureMapMode;       /**< texture mapping mode */
    const GlsTextureFilterMode  _textureMagFilterMode; /**< texture magnification filter mode */
    const GlsTextureFilterMode  _textureMinFilterMode; /**< texture minification filter mode */
    const GlsBool               _cullBackFace;         /**< GLS_TRUE if backface culling is enabled else GLS_FALSE */
    const GlsDepthBufferMode    _depthBufferMode;      /**< depth buffer test / write mode */
    const GlsPolygonEndMode     _polygonEndMode;       /**< Polygon close mode */
    const GlsShadingMode        _shadingMode;          /**< shading mode */

    GlsAlphaMode                _alphaMode;            /**< alpha mode */
    GlsColor                    _lineColor;            /**< line color */
    GlsUInt32                   _textureIndex;         /**< texture index into palette
                                                         * else GlsTexturePalette::NO_TEXTURE */
    GlsPolygonMode              _polygonMode;          /**< polygon mode */
    GlsColor                    _fillColor;            /**< fill color */
    GlsFloat32                  _lineWidth;            /**< line width in pixels,
                                                         * GlsRenderObject::LINE_WIDTH_MIN <= lineWidth <= GlsRenderObject::LINE_WIDTH_MAX */

    /** Construct with given initialization parameters
      * \param initParameters initialization parameters
      * \param eventDispatcher event dispatcher for this object else GLS_NULL
      * \pre initParameters.IsValid()
      * \post object constructed
      */
    GlsRenderObject( const InitParameters &initParameters, GlsEventDispatcher* const eventDispatcher );

    /** Get the GL texture filter enum for the correspoding GlsTextureFilterMode
      * \param mode GlsTextureFilterMode in question
      * \return GL texture filer enum for the given GlsTextureFilterMode
      * \pre GlsTextureFilterModeIsValid( mode )
      * \post none
      */
    GLint GlsTextureFilterModeToGL( const GlsTextureFilterMode mode ) const;

    /** Setup the GL depth settings based on current object settings
      * \param gl GL state manager to setup
      * \pre GlsDepthBufferModeIsValid( _depthBufferMode )
      * \post GL depth settings are set based on current object settings
      */
    void SetupDepthTest( GlsStateManager &gl ) const;

    /** Setup the GL alpha test and blend settings based on the current object settings
      * \param gl GL state manager to setup
      * \pre GlsAlphaModeIsValid( _alphaMode )
      * \post GL alpha test and blend settings are set based on current object settings
      */
    void SetupAlpha( GlsStateManager &gl ) const;

    /** Setup GL with the proper texture binding and parameters as indicated by the current
      *   object settings and the given texture index
      * \param gl GL state manager to setup
      * \param textureIndex index of texture to setup
      * \return GLS_TRUE if this object has a texture else GLS_FALSE
      * \pre ( textureIndex == GlsTexturePalette::NO_TEXTURE ) else ( textureIndex < _texturePalette.GetSize() 
      *        and _texturePalette does not have an empty slot at textureIndex ),
      *      GlsTextureMapModeIsValid( _textureMapMode ), GlsTextureFilterModeIsValid( _textureMagFilterMode ),
      *      GlsTextureFilterModeIsValid( _textureMinFilterMode ),
      * \post GL texture binding and parameters are setup as indicated by the current object settings
      */
    GlsBool SetupTexture( GlsStateManager &gl, const GlsUInt32 textureIndex ) const;

    /** Setup GL with the proper texture filter settings based on the current object settings.
      * \param gl GL state manager to setup
      * \pre GlsTextureFilterModeIsValid( _textureMagFilterMode ), GlsTextureFilterModeIsValid( _textureMinFilterMode )
      * \post GL texture filter settings are setup based on the current object settings
      */
    void SetupTextureFilterSettings( GlsStateManager &gl ) const;

    /** Setup GL with the proper backface culling mode based on the current object settings
      * \param gl GL state manager to setup
      * \pre none
      * \post GL backface culling mode is setup based on the current object settings
      */
    void SetupBackfaceCulling( GlsStateManager &gl ) const;

    /** Setup GL with the proper shading settings based on the current object settings
      * \param gl GL state manager to setup
      * \pre GlsShadingModeIsValid( _shadingMode )
      * \post GL shading settings are setup based on the current object settings
      */
    void SetupShading( GlsStateManager &gl ) const;

    /** Setup GL with the proper line style settings based on the current object settings
      * \param gl GL state manager to setup
      * \pre GlsLineWidthIsValid( _lineWidth )
      * \post GL line style settings are setup based on the current object settings
      */
    void SetupLineStyle( GlsStateManager &gl ) const;

    /** Setup GL with the proper antialias settings based on the current object settings
      * \param gl GL state manager to setup
      * \pre none
      * \post GL antialias settings are setup based on the current object settings
      */
    void SetupAntiAlias( GlsStateManager &gl ) const;

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

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

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

#if defined( GLS_DEBUG )
#pragma BullseyeCoverage save off
/** Determine if the given line width is valid ( GLS_DEBUG only )
  * \param lineWidth line width in question
  * \return GLS_TRUE if valid else GLS_FALSE
  * \pre none
  * \post none 
  */
inline GlsBool GlsLineWidthIsValid( const GlsFloat32 lineWidth )
{
    return( ( GlsRenderObject::LINE_WIDTH_MIN <= lineWidth ) && ( lineWidth <= GlsRenderObject::LINE_WIDTH_MAX ) );
}
#pragma BullseyeCoverage restore
#endif // GLS_DEBUG

#endif // _GLS_RENDER_OBJECT_H