GL Studio C++ Runtime API
gls_render_effect.h
Go to the documentation of this file.
1 /*! \file
2  \brief The disti::GlsRenderEffect class.
3 
4  \par Copyright Information
5 
6  Copyright (c) 2017 by The DiSTI Corporation.<br>
7  11301 Corporate Blvd., Suite 100<br>
8  Orlando, Florida 32817<br>
9  USA<br>
10  <br>
11  All rights reserved.<br>
12 
13  This Software contains proprietary trade secrets of DiSTI and may not be
14 reproduced, in whole or part, in any form, or by any means of electronic,
15 mechanical, or otherwise, without the written permission of DiSTI. Said
16 permission may be derived through the purchase of applicable DiSTI product
17 licenses which detail the distribution rights of this content and any
18 Derivative Works based on this or other copyrighted DiSTI Software.
19 
20  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
21 AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
22 PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
23 AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
24 IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
25 PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.
26 
27  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
28 IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
29 INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
30 DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
31 INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
32 INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
33 OF SUCH DAMAGES. DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
34 EXCEED FIVE DOLLARS (US$5.00).
35 
36  The aforementioned terms and restrictions are governed by the laws of the
37 State of Florida and the United States of America.
38 
39 */
40 #ifndef _GLS_RENDER_EFFECT_H
41 #define _GLS_RENDER_EFFECT_H
42 
43 #include "display_types.h"
44 #include "dynamic_array.h"
45 #include "material.h"
46 
47 #include "gls_version.h"
48 
49 #ifdef GLES
50 # include "gls_state_manager.h"
51 #endif
52 
53 //////////////////// Provides support for creating DLLs ////////////////////////
54 #if( defined( GLSGEN_EXPORT_GLSADVANCEDMESH ) || defined( GLSGEN_IMPORT_GLSADVANCEDMESH ) || defined( GLS_EXPORT_GENERATED ) || defined( GLS_IMPORT_GENERATED ) ) \
55  && defined( _MSC_VER )
56 # if defined( GLSGEN_EXPORT_GLSADVANCEDMESH ) || defined( GLS_EXPORT_GENERATED )
57 # define GLSGEN_GlsAdvancedMesh_EXPORT __declspec( dllexport )
58 # else
59 # define GLSGEN_GlsAdvancedMesh_EXPORT __declspec( dllimport )
60 # endif
61 #else
62 # define GLSGEN_GlsAdvancedMesh_EXPORT
63 #endif
64 ///////////////////////////////////////////////////////////////////////////////
65 
66 namespace disti
67 {
68 // Forward declarations
69 class DisplayObject;
70 class TexturePalette;
71 class DistiAttribDict;
72 
73 typedef DynamicArray<int> ReferencedTextureArray;
74 typedef DynamicArray<int> ReferencedMaterialArray;
75 
76 // Abstract interface that is needed to tell
77 // the GlsGeometryResource which vertex attrib
78 // indices to use for a given rendering pass.
79 // (e.g. the attribute index to use can vary depending on
80 // the shader used).
82 {
83 public:
84  virtual ~VertexAttribIndexLookup() {}
85 
86  // These are the predefined semantic values from the Cg language
87  // Users should be able to define their own in the future, but these will be it for now.
88  typedef enum
89  {
90  ATTRIB_UNDEFINED = 0,
91  ATTRIB_POSITION = 0x80000000,
92  ATTRIB_NORMAL,
93  ATTRIB_BLENDWEIGHT,
94  ATTRIB_TANGENT,
95  ATTRIB_BINORMAL,
96  ATTRIB_BLENDINDICES,
97  ATTRIB_PSIZE,
98  ATTRIB_TEXCOORD0,
99  ATTRIB_TEXCOORD1,
100  ATTRIB_TEXCOORD2,
101  ATTRIB_TEXCOORD3,
102  ATTRIB_TEXCOORD4,
103  ATTRIB_TEXCOORD5,
104  ATTRIB_TEXCOORD6,
105  ATTRIB_TEXCOORD7
106  } AttributeSemanticEnum;
107 
108  /// \returns The attributeIndex that should be used to pass the vertex attributes or -1 if they are not needed (see glVertexAttrib)
109  /// \param semanticEnum The sematic value (see AttributeSemanticEnum)
110  virtual GLint GetVertexAttribIndexForSemantic( int semanticEnum ) = 0;
111 };
112 
113 /** Abstract render effect class
114  * Encapsulates an effect that can be applied to the OpenGL state to modify the appearance of geometry.
115  * This API currently only supports single pass techniques.
116  */
118 {
119 protected:
120  virtual ~GlsRenderEffect() {}
121 
122 public:
123  /** Manage references to the effect
124  */
125  virtual void AddRef() = 0;
126  virtual void Release() = 0;
127 
128  // Allows for static casting in compare functions
129  // See RegisterNewClassID
130  virtual unsigned int GlsRenderEffect_ClassID() const = 0;
131 
132  /** The TextureSettings class is used to provide the object-level
133  * texturing settings to the effect
134  */
136  {
137  public:
138  unsigned char _textureRepeat; /**< GL_TEXTURE_WRAP_* setting (0 or 1) */
139  unsigned char _textureMap; /**< The texturing map mode setting /sa TextureMap_e */
140  unsigned char _textureMagFilter; /**< The texturing magnification filter setting /sa TextureFilter_e */
141  unsigned char _textureMinFilter; /**< The texturing minification filter setting /sa TextureFilter_e */
142 
143  // Initialize the TextureSettings object with the given values
144  inline TextureSettings(
145  unsigned char textureRepeat = 1,
146  unsigned char textureMap = TEXTURE_MAP_REPLACE,
147  unsigned char textureMagFilter = TEXTURE_FILTER_LINEAR,
148  unsigned char textureMinFilter = TEXTURE_FILTER_LINEAR )
149  : _textureRepeat( textureRepeat )
150  , _textureMap( textureMap )
151  , _textureMagFilter( textureMagFilter )
152  , _textureMinFilter( textureMinFilter )
153  {}
154  };
155 
156  /// Apply the effect to the OpenGL state
157  /// \param materialPalette Used to access material settings
158  /// \param texturePalette Used to access texture maps
159  /// \param textureSettings The object-level texture settings
160  /// \param viewToWorld3x3 A 3x3 matrix containing the current viewToWorld transfrom. Used for environment mapping effects.
161  /// \param maxLightNum The number of active lights in the scene. Used to speed up light calculations.
162  /// \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:
163  /// activeLightMask = ...10001101 last 8 bits in binary = 141u)
164  virtual void SetupEffect(
165  DynamicArray<Material>& materialPalette,
166  TexturePalette* texturePalette,
167  const TextureSettings& textureSettings,
168  float* viewToWorld3x3, // 3x3 matrix (float[9])
169  unsigned int maxLightNum,
170  unsigned int activeLightMask )
171  = 0;
172 
173 #if !defined( GLES ) || defined( GLES20 )
174  /// Remove the effect trom the OpenGL state
175  virtual void CleanupEffect() = 0;
176 #endif
177 
178  /** Returns 0 if the effects are equal,
179  * a positive number if this effect should sort after the other effect,
180  * and a negative number if this effect should sort before the other effect.
181  * The rendering system uses this to sort effects.
182  */
183  virtual int Compare( const GlsRenderEffect* other ) const = 0;
184 
185  /** Determine if two GlsRenderEffect instances are equivalent
186  * The rendering system uses this to eliminate redundant effects.
187  */
188  inline bool Equals( const GlsRenderEffect* other ) const { return Compare( other ) == 0; }
189 
190  virtual DistiAttribDict& Attributes() = 0;
191 
192  virtual const std::string& EffectTypeName() = 0;
193 
194  // TODO: Need an API to get / set effect instance parameters without knowing it's type
195  // There may be two classes of parameters:
196  // Initialization parameters: (e.g. Reference to a shader program or CG effect file to load)
197  // 'Runtime' parameters: The vertex attributes, maps, etc. that are an input to the effect.
198 
199  /** Returns a new instance of the effect with the same settings as this one */
200  virtual GlsRenderEffect* Clone() const = 0;
201 
202  /** Checks whether or not the effect is transparent. Implementing is optional */
203  //virtual bool HasTransparency() const {return false;}
204 
205  /** Inserts all referenced textures into the array passed in. Implementing is optional */
206  virtual void GetReferencedMaterials( ReferencedMaterialArray& referencedMaterials ){};
207 
208  /** Inserts all referenced textures into the array passed in. Implementing is optional */
209  virtual void GetReferencedTextures( ReferencedTextureArray& referencedTextures ){};
210 
211  // Enable / Disable a debug mode for all effects that support it
212  // \param modeName name of the mode to enable / disable
213  // \param value true to enable the mode, false to disable
214  // \returns the number of effect callbacks that recognized the mode change
215  static GLSGEN_GlsAdvancedMesh_EXPORT unsigned int SetDebugMode( const char* modeName, bool value );
216 
217  // Returns a new ClassID
218  // Typically only called once by each GlsRenderEffect implementation
219  static GLSGEN_GlsAdvancedMesh_EXPORT unsigned int RegisterNewClassID( const char* debugStr = NULL );
220 
221  // typedef for DebugMode change callbacks
222  // \see RegisterDebugModeChangeCallback
223  // \param user pointer that was provided when the callback was registered
224  // \param modeName name of the mode that is changing
225  // \param value true to enable the mode, false to disable
226  // \param returns true if the callback recognized the mode change, false otherwise
227  typedef bool ( *DebugModeChangeCallback )( void* user, const char* modeName, bool value );
228 
229  // Register for debug mode change notifications
230  // Note: Be sure to also Unregister!
231  // \see UnregisterDebugModeChangeCallback
232  // \param param user pointer that will be passed to the callback
233  // \param func pointer to the callback function
234  // \returns true on success
235  static GLSGEN_GlsAdvancedMesh_EXPORT bool RegisterDebugModeChangeCallback( void* param, DebugModeChangeCallback func );
236 
237  // Unregister for debug mode change notifications
238  // The parameters must match those that were passed when the callback was registered
239  // \see RegisterDebugModeChangeCallback
240  // \param param user pointer that was passed to RegisterDebugModeChangeCallback
241  // \param func function pointer that was passed to RegisterDebugModeChangeCallback
242  // \returns true if the callback was found and unregistered
243  static GLSGEN_GlsAdvancedMesh_EXPORT bool UnregisterDebugModeChangeCallback( void* param, DebugModeChangeCallback func );
244 };
245 
246 } // namespace disti
247 
248 #endif
virtual void GetReferencedMaterials(ReferencedMaterialArray &referencedMaterials)
Definition: gls_render_effect.h:206
The disti::Material class.
virtual void SetupEffect(DynamicArray< Material > &materialPalette, TexturePalette *texturePalette, const TextureSettings &textureSettings, float *viewToWorld3x3, unsigned int maxLightNum, unsigned int activeLightMask)=0
The disti::DynamicArray class. A templated array of objects capable of dynamically growing...
unsigned char _textureMap
Definition: gls_render_effect.h:139
virtual GlsRenderEffect * Clone() const =0
virtual GLint GetVertexAttribIndexForSemantic(int semanticEnum)=0
virtual int Compare(const GlsRenderEffect *other) const =0
bool Equals(const GlsRenderEffect *other) const
Definition: gls_render_effect.h:188
Definition: gls_render_effect.h:81
unsigned char _textureRepeat
Definition: gls_render_effect.h:138
The disti::GlsStateManager factory class. Creates an instance of a state manager that manages the GL ...
virtual void GetReferencedTextures(ReferencedTextureArray &referencedTextures)
Definition: gls_render_effect.h:209
Used for matching version of libraries and headers.
virtual void AddRef()=0
GL Studio Enumerations and constants.
Definition: display_types.h:64
Definition: disti_metadata.h:665
Definition: display_types.h:71
unsigned char _textureMagFilter
Definition: gls_render_effect.h:140
Definition: texture_palette.h:145
unsigned char _textureMinFilter
Definition: gls_render_effect.h:141
Definition: gls_render_effect.h:117
Definition: gls_render_effect.h:135
Definition: bmpimage.h:46
virtual void CleanupEffect()=0
Remove the effect trom the OpenGL state.