gls_render_effect.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::GlsRenderEffect class.
 
  \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_RENDER_EFFECT_H
#define _GLS_RENDER_EFFECT_H
 
#include "display_types.h"
#include "dynamic_array.h"
#include "material.h"
 
#include "gls_version.h"
 
#ifdef GLES
#    include "gls_state_manager.h"
#endif
 
/// Provides support for creating DLLs.
#if( defined( GLSGEN_EXPORT_GLSADVANCEDMESH ) || defined( GLSGEN_IMPORT_GLSADVANCEDMESH ) || defined( GLS_EXPORT_GENERATED ) || defined( GLS_IMPORT_GENERATED ) ) \
    && defined( _MSC_VER )
#    if defined( GLSGEN_EXPORT_GLSADVANCEDMESH ) || defined( GLS_EXPORT_GENERATED )
#        define GLSGEN_GlsAdvancedMesh_EXPORT __declspec( dllexport )
#    else
#        define GLSGEN_GlsAdvancedMesh_EXPORT __declspec( dllimport )
#    endif
#else
#    define GLSGEN_GlsAdvancedMesh_EXPORT
#endif
///////////////////////////////////////////////////////////////////////////////
 
namespace disti
{
// Forward declarations
class DisplayObject;
class TexturePalette;
class DistiAttribDict;
 
typedef DynamicArray<int> ReferencedTextureArray;  ///< Typedef for a list of texture indices.
typedef DynamicArray<int> ReferencedMaterialArray; ///< Typedef for a list of material indices.
 
/// \details Abstract interface that is needed to tell the GlsGeometryResource which vertex attrib
/// indices to use for a given rendering pass. (e.g. the attribute index to use can vary depending on the shader used).
class VertexAttribIndexLookup
{
public:
    virtual ~VertexAttribIndexLookup() {}
 
    /// \details The AttributeSemanticEnum enumeration.
    /// These are the predefined semantic values from the Cg language.
    /// Users should be able to define their own in the future, but these will be it for now.
    typedef enum
    {
        ATTRIB_UNDEFINED = 0,
        ATTRIB_POSITION  = 0x80000000,
        ATTRIB_NORMAL,
        ATTRIB_BLENDWEIGHT,
        ATTRIB_TANGENT,
        ATTRIB_BINORMAL,
        ATTRIB_BLENDINDICES,
        ATTRIB_PSIZE,
        ATTRIB_TEXCOORD0,
        ATTRIB_TEXCOORD1,
        ATTRIB_TEXCOORD2,
        ATTRIB_TEXCOORD3,
        ATTRIB_TEXCOORD4,
        ATTRIB_TEXCOORD5,
        ATTRIB_TEXCOORD6,
        ATTRIB_TEXCOORD7
    } AttributeSemanticEnum;
 
    /// \returns The attributeIndex that should be used to pass the vertex attributes or -1 if they are not needed (see glVertexAttrib)
    /// \param semanticEnum The sematic value (see AttributeSemanticEnum)
    virtual GLint GetVertexAttribIndexForSemantic( int semanticEnum ) = 0;
};
 
/** Abstract render effect class
  * Encapsulates an effect that can be applied to the OpenGL state to modify the appearance of geometry.
  * This API currently only supports single pass techniques.
  */
class GlsRenderEffect : public VertexAttribIndexLookup
{
protected:
    virtual ~GlsRenderEffect() {}
 
public:
    /// Add to this object's reference count.
    virtual void AddRef() = 0;
 
    /// Release a reference to this object.
    virtual void Release() = 0;
 
    /// Allows for static casting in compare functions
    /// \see RegisterNewClassID
    /// \return A unique identifier associated with this effect type.
    virtual unsigned int GlsRenderEffect_ClassID() const = 0;
 
    /** The TextureSettings class is used to provide the object-level
      * texturing settings to the effect
      */
    class TextureSettings
    {
    public:
        unsigned char _textureRepeat;    /**< GL_TEXTURE_WRAP_* setting (0 or 1) */
        unsigned char _textureMap;       /**< The texturing map mode setting /sa TextureMap_e */
        unsigned char _textureMagFilter; /**< The texturing magnification filter setting /sa TextureFilter_e */
        unsigned char _textureMinFilter; /**< The texturing minification filter setting /sa TextureFilter_e */
 
        /// Initialize the TextureSettings object with the given values
        /// \param textureRepeat GL_TEXTURE_WRAP_* setting (0 or 1)
        /// \param textureMap The texturing map mode setting /sa TextureMap_e
        /// \param textureMagFilter The texturing magnification filter setting /sa TextureFilter_e
        /// \param textureMinFilter The texturing minification filter setting /sa TextureFilter_e
        inline TextureSettings(
            unsigned char textureRepeat    = 1,
            unsigned char textureMap       = TEXTURE_MAP_REPLACE,
            unsigned char textureMagFilter = TEXTURE_FILTER_LINEAR,
            unsigned char textureMinFilter = TEXTURE_FILTER_LINEAR )
            : _textureRepeat( textureRepeat )
            , _textureMap( textureMap )
            , _textureMagFilter( textureMagFilter )
            , _textureMinFilter( textureMinFilter )
        {}
    };
 
    /// Apply the effect to the OpenGL state
    /// \param materialPalette  Used to access material settings
    /// \param texturePalette  Used to access texture maps
    /// \param textureSettings  The object-level texture settings
    /// \param viewToWorld3x3  A 3x3 matrix containing the current viewToWorld transfrom.  Used for environment mapping effects.
    /// \param maxLightNum The number of active lights in the scene. Used to speed up light calculations.
    /// \param activeLightMask A bit mask of which lights are active in the scene (Ex. GL_LIGHT0, GL_LIGHT2, GL_LIGHT3 and GL_LIGHT7 are active:
    ///        activeLightMask = ...10001101 last 8 bits in binary = 141u)
    virtual void SetupEffect(
        DynamicArray<Material>& materialPalette,
        TexturePalette*         texturePalette,
        const TextureSettings&  textureSettings,
        float*                  viewToWorld3x3, // 3x3 matrix (float[9])
        unsigned int            maxLightNum,
        unsigned int            activeLightMask )
        = 0;
 
#if !defined( GLES ) || defined( GLES20 )
    /// Remove the effect trom the OpenGL state
    virtual void CleanupEffect() = 0;
#endif
 
    /// \return 0 if the effects are equal,
    /// a positive number if this effect should sort after the other effect,
    /// or a negative number if this effect should sort before the other effect.
    /// The rendering system uses this to sort effects.
    /// \param other The effect to compare with.
    virtual int Compare( const GlsRenderEffect* other ) const = 0;
 
    /// Determine if two GlsRenderEffect instances are equivalent
    /// The rendering system uses this to eliminate redundant effects.
    /// \param other The effect to compare with.
    /// \return True if the compared effects are equivalent.
    inline bool Equals( const GlsRenderEffect* other ) const { return Compare( other ) == 0; }
 
    /// \return A reference to the attribute dictionary for this object.
    virtual DistiAttribDict& Attributes() = 0;
 
    /// \return The human readable type name associated with this effect.
    virtual const std::string& EffectTypeName() = 0;
 
    // TODO: Need an API to get / set effect instance parameters without knowing it's type
    // There may be two classes of parameters:
    //  Initialization parameters: (e.g. Reference to a shader program or CG effect file to load)
    //  'Runtime' parameters: The vertex attributes, maps, etc. that are an input to the effect.
 
    /// \return A new instance of the effect with the same settings as this one.
    virtual GlsRenderEffect* Clone() const = 0;
 
    /** Checks whether or not the effect is transparent.  Implementing is optional */
    //virtual bool HasTransparency() const {return false;}
 
    /// Inserts all referenced textures into the array passed in. Implementing is optional.
    /// \param referencedMaterials A returned array of material indices.
    virtual void GetReferencedMaterials( ReferencedMaterialArray& referencedMaterials ){};
 
    /// Inserts all referenced textures into the array passed in. Implementing is optional.
    /// \param referencedTextures A returned array of texture indices.
    virtual void GetReferencedTextures( ReferencedTextureArray& referencedTextures ){};
 
    /// Enable / Disable a debug mode for all effects that support it.
    /// \param modeName Name of the mode to enable / disable.
    /// \param value True to enable the mode, false to disable.
    /// \returns The number of effect callbacks that recognized the mode change.
    static GLSGEN_GlsAdvancedMesh_EXPORT unsigned int SetDebugMode( const char* modeName, bool value );
 
    /// \return A new ClassID.
    /// Typically only called once by each GlsRenderEffect implementation.
    /// \param debugStr Unused, kept for backward compatibility.
    static GLSGEN_GlsAdvancedMesh_EXPORT unsigned int RegisterNewClassID( const char* debugStr = NULL );
 
    /// Typedef for DebugMode change callbacks.
    /// \see RegisterDebugModeChangeCallback
    /// \param user Pointer that was provided when the callback was registered.
    /// \param modeName Name of the mode that is changing.
    /// \param value True to enable the mode, false to disable.
    /// \param returns True if the callback recognized the mode change, false otherwise.
    typedef bool ( *DebugModeChangeCallback )( void* user, const char* modeName, bool value );
 
    /// Register for debug mode change notifications.
    /// \note Be sure to also Unregister!
    /// \see UnregisterDebugModeChangeCallback
    /// \param param User pointer that will be passed to the callback.
    /// \param func Pointer to the callback function.
    /// \returns True on success.
    static GLSGEN_GlsAdvancedMesh_EXPORT bool RegisterDebugModeChangeCallback( void* param, DebugModeChangeCallback func );
 
    /// Unregister for debug mode change notifications.
    /// The parameters must match those that were passed when the callback was registered.
    /// \see RegisterDebugModeChangeCallback
    /// \param param User pointer that was passed to RegisterDebugModeChangeCallback.
    /// \param func Function pointer that was passed to RegisterDebugModeChangeCallback.
    /// \returns True if the callback was found and unregistered.
    static GLSGEN_GlsAdvancedMesh_EXPORT bool UnregisterDebugModeChangeCallback( void* param, DebugModeChangeCallback func );
};
 
} // namespace disti
 
#endif