GL Studio C++ Runtime API
gls_render_effect.h
Go to the documentation of this file.
1/// \file gls_render_effect.h
2/// \brief The disti::GlsRenderEffect class.
3///
4/// \par Copyright Information
5///
6/// Copyright (c) 2017 by The DiSTI Corporation.<br>
7/// 12249 Science Drive; Suite 300<br>
8/// Orlando, Florida 32826<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#ifndef DISTI_INCLUDED_GLS_RENDER_EFFECT_H
40#define DISTI_INCLUDED_GLS_RENDER_EFFECT_H
41
42#include "display_types.h"
43#include "dynamic_array.h"
44#include "material.h"
45
46#include "gls_version.h"
47
48#ifdef GLES
49# include "gls_state_manager.h"
50#endif
51
52/// Provides support for creating DLLs.
53#if( defined( GLSGEN_EXPORT_GLSADVANCEDMESH ) || defined( GLSGEN_IMPORT_GLSADVANCEDMESH ) || defined( GLS_EXPORT_GENERATED ) || defined( GLS_IMPORT_GENERATED ) ) \
54 && defined( _MSC_VER )
55# if defined( GLSGEN_EXPORT_GLSADVANCEDMESH ) || defined( GLS_EXPORT_GENERATED )
56# define GLSGEN_GlsAdvancedMesh_EXPORT __declspec( dllexport )
57# else
58# define GLSGEN_GlsAdvancedMesh_EXPORT __declspec( dllimport )
59# endif
60#else
61# define GLSGEN_GlsAdvancedMesh_EXPORT
62#endif
63///////////////////////////////////////////////////////////////////////////////
64
65namespace disti
66{
67// Forward declarations
68class DisplayObject;
69class TexturePalette;
70class DistiAttribDict;
71
72typedef DynamicArray<int> ReferencedTextureArray; ///< Typedef for a list of texture indices.
73typedef DynamicArray<int> ReferencedMaterialArray; ///< Typedef for a list of material indices.
74
75/// \details Abstract interface that is needed to tell the GlsGeometryResource which vertex attrib
76/// indices to use for a given rendering pass. (e.g. the attribute index to use can vary depending on the shader used).
78{
79public:
80 virtual ~VertexAttribIndexLookup() {}
81
82 /// \details The AttributeSemanticEnum enumeration.
83 /// These are the predefined semantic values from the Cg language.
84 /// Users should be able to define their own in the future, but these will be it for now.
85 typedef enum
86 {
87 ATTRIB_UNDEFINED = 0,
88 ATTRIB_POSITION = 0x80000000,
89 ATTRIB_NORMAL,
90 ATTRIB_BLENDWEIGHT,
91 ATTRIB_TANGENT,
92 ATTRIB_BINORMAL,
93 ATTRIB_BLENDINDICES,
94 ATTRIB_PSIZE,
95 ATTRIB_TEXCOORD0,
96 ATTRIB_TEXCOORD1,
97 ATTRIB_TEXCOORD2,
98 ATTRIB_TEXCOORD3,
99 ATTRIB_TEXCOORD4,
100 ATTRIB_TEXCOORD5,
101 ATTRIB_TEXCOORD6,
102 ATTRIB_TEXCOORD7
104
105 /// \returns The attributeIndex that should be used to pass the vertex attributes or -1 if they are not needed (see glVertexAttrib)
106 /// \param semanticEnum The sematic value (see AttributeSemanticEnum)
107 virtual GLint GetVertexAttribIndexForSemantic( int semanticEnum ) = 0;
108};
109
110/** Abstract render effect class
111 * Encapsulates an effect that can be applied to the OpenGL state to modify the appearance of geometry.
112 * This API currently only supports single pass techniques.
113 */
115{
116protected:
117 virtual ~GlsRenderEffect() {}
118
119public:
120 /// Add to this object's reference count.
121 virtual void AddRef() = 0;
122
123 /// Release a reference to this object.
124 virtual void Release() = 0;
125
126 /// Allows for static casting in compare functions
127 /// \see RegisterNewClassID
128 /// \return A unique identifier associated with this effect type.
129 virtual unsigned int GlsRenderEffect_ClassID() const = 0;
130
131 /** The TextureSettings class is used to provide the object-level
132 * texturing settings to the effect
133 */
135 {
136 public:
137 unsigned char _textureRepeat; /**< GL_TEXTURE_WRAP_* setting (0 or 1) */
138 unsigned char _textureMap; /**< The texturing map mode setting /sa TextureMap_e */
139 unsigned char _textureMagFilter; /**< The texturing magnification filter setting /sa TextureFilter_e */
140 unsigned char _textureMinFilter; /**< The texturing minification filter setting /sa TextureFilter_e */
141
142 /// Initialize the TextureSettings object with the given values
143 /// \param textureRepeat GL_TEXTURE_WRAP_* setting (0 or 1)
144 /// \param textureMap The texturing map mode setting /sa TextureMap_e
145 /// \param textureMagFilter The texturing magnification filter setting /sa TextureFilter_e
146 /// \param textureMinFilter The texturing minification filter setting /sa TextureFilter_e
148 unsigned char textureRepeat = 1,
149 unsigned char textureMap = TEXTURE_MAP_REPLACE,
150 unsigned char textureMagFilter = TEXTURE_FILTER_LINEAR,
151 unsigned char textureMinFilter = TEXTURE_FILTER_LINEAR )
152 : _textureRepeat( textureRepeat )
153 , _textureMap( textureMap )
154 , _textureMagFilter( textureMagFilter )
155 , _textureMinFilter( textureMinFilter )
156 {}
157 };
158
159 /// Apply the effect to the OpenGL state
160 /// \param materialPalette Used to access material settings
161 /// \param texturePalette Used to access texture maps
162 /// \param textureSettings The object-level texture settings
163 /// \param viewToWorld3x3 A 3x3 matrix containing the current viewToWorld transfrom. Used for environment mapping effects.
164 /// \param maxLightNum The number of active lights in the scene. Used to speed up light calculations.
165 /// \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:
166 /// activeLightMask = ...10001101 last 8 bits in binary = 141u)
167 virtual void SetupEffect(
168 DynamicArray<Material>& materialPalette,
169 TexturePalette* texturePalette,
170 const TextureSettings& textureSettings,
171 float* viewToWorld3x3, // 3x3 matrix (float[9])
172 unsigned int maxLightNum,
173 unsigned int activeLightMask )
174 = 0;
175
176#if !defined( GLES ) || defined( GLES20 )
177 /// Remove the effect from the OpenGL state.
178 virtual void CleanupEffect() = 0;
179#endif
180
181 /// \return 0 if the effects are equal,
182 /// a positive number if this effect should sort after the other effect,
183 /// or a negative number if this effect should sort before the other effect.
184 /// The rendering system uses this to sort effects.
185 /// \param other The effect to compare with.
186 virtual int Compare( const GlsRenderEffect* other ) const = 0;
187
188 /// Determine if two GlsRenderEffect instances are equivalent
189 /// The rendering system uses this to eliminate redundant effects.
190 /// \param other The effect to compare with.
191 /// \return True if the compared effects are equivalent.
192 bool Equals( const GlsRenderEffect* other ) const { return Compare( other ) == 0; }
193
194 /// \return A reference to the attribute dictionary for this object.
196
197 /// \return The human readable type name associated with this effect.
198 virtual const std::string& EffectTypeName() = 0;
199
200 // TODO: Need an API to get / set effect instance parameters without knowing it's type
201 // There may be two classes of parameters:
202 // Initialization parameters: (e.g. Reference to a shader program or CG effect file to load)
203 // 'Runtime' parameters: The vertex attributes, maps, etc. that are an input to the effect.
204
205 /// \return A new instance of the effect with the same settings as this one.
206 virtual GlsRenderEffect* Clone() const = 0;
207
208 /** Checks whether or not the effect is transparent. Implementing is optional */
209 //virtual bool HasTransparency() const {return false;}
210
211 /// Inserts all referenced textures into the array passed in. Implementing is optional.
212 /// \param referencedMaterials A returned array of material indices.
213 virtual void GetReferencedMaterials( ReferencedMaterialArray& referencedMaterials ){};
214
215 /// Inserts all referenced textures into the array passed in. Implementing is optional.
216 /// \param referencedTextures A returned array of texture indices.
217 virtual void GetReferencedTextures( ReferencedTextureArray& referencedTextures ){};
218
219 /// Enable / Disable a debug mode for all effects that support it.
220 /// \param modeName Name of the mode to enable / disable.
221 /// \param value True to enable the mode, false to disable.
222 /// \returns The number of effect callbacks that recognized the mode change.
223 static GLSGEN_GlsAdvancedMesh_EXPORT unsigned int SetDebugMode( const char* modeName, bool value );
224
225 /// \return A new ClassID.
226 /// Typically only called once by each GlsRenderEffect implementation.
227 /// \param debugStr Unused, kept for backward compatibility.
228 static GLSGEN_GlsAdvancedMesh_EXPORT unsigned int RegisterNewClassID( const char* debugStr = NULL );
229
230 /// Typedef for DebugMode change callbacks.
231 /// \see RegisterDebugModeChangeCallback
232 /// \param user Pointer that was provided when the callback was registered.
233 /// \param modeName Name of the mode that is changing.
234 /// \param value True to enable the mode, false to disable.
235 /// \param returns True if the callback recognized the mode change, false otherwise.
236 typedef bool ( *DebugModeChangeCallback )( void* user, const char* modeName, bool value );
237
238 /// Register for debug mode change notifications.
239 /// \note Be sure to also Unregister!
240 /// \see UnregisterDebugModeChangeCallback
241 /// \param param User pointer that will be passed to the callback.
242 /// \param func Pointer to the callback function.
243 /// \returns True on success.
245
246 /// Unregister for debug mode change notifications.
247 /// The parameters must match those that were passed when the callback was registered.
248 /// \see RegisterDebugModeChangeCallback
249 /// \param param User pointer that was passed to RegisterDebugModeChangeCallback.
250 /// \param func Function pointer that was passed to RegisterDebugModeChangeCallback.
251 /// \returns True if the callback was found and unregistered.
253};
254
255} // namespace disti
256
257#endif
Definition: disti_metadata.h:750
Definition: gls_render_effect.h:135
TextureSettings(unsigned char textureRepeat=1, unsigned char textureMap=TEXTURE_MAP_REPLACE, unsigned char textureMagFilter=TEXTURE_FILTER_LINEAR, unsigned char textureMinFilter=TEXTURE_FILTER_LINEAR)
Definition: gls_render_effect.h:147
unsigned char _textureMinFilter
Definition: gls_render_effect.h:140
unsigned char _textureMagFilter
Definition: gls_render_effect.h:139
unsigned char _textureMap
Definition: gls_render_effect.h:138
unsigned char _textureRepeat
Definition: gls_render_effect.h:137
Definition: gls_render_effect.h:115
virtual void GetReferencedMaterials(ReferencedMaterialArray &referencedMaterials)
Definition: gls_render_effect.h:213
bool(* DebugModeChangeCallback)(void *user, const char *modeName, bool value)
Definition: gls_render_effect.h:236
static bool UnregisterDebugModeChangeCallback(void *param, DebugModeChangeCallback func)
virtual void Release()=0
Release a reference to this object.
virtual int Compare(const GlsRenderEffect *other) const =0
virtual void GetReferencedTextures(ReferencedTextureArray &referencedTextures)
Definition: gls_render_effect.h:217
static unsigned int SetDebugMode(const char *modeName, bool value)
virtual GlsRenderEffect * Clone() const =0
bool Equals(const GlsRenderEffect *other) const
Definition: gls_render_effect.h:192
virtual void CleanupEffect()=0
Remove the effect from the OpenGL state.
virtual void AddRef()=0
Add to this object's reference count.
virtual const std::string & EffectTypeName()=0
virtual unsigned int GlsRenderEffect_ClassID() const =0
static bool RegisterDebugModeChangeCallback(void *param, DebugModeChangeCallback func)
virtual DistiAttribDict & Attributes()=0
virtual void SetupEffect(DynamicArray< Material > &materialPalette, TexturePalette *texturePalette, const TextureSettings &textureSettings, float *viewToWorld3x3, unsigned int maxLightNum, unsigned int activeLightMask)=0
static unsigned int RegisterNewClassID(const char *debugStr=NULL)
Definition: texture_palette.h:185
Definition: gls_render_effect.h:78
virtual GLint GetVertexAttribIndexForSemantic(int semanticEnum)=0
AttributeSemanticEnum
Definition: gls_render_effect.h:86
GL Studio Enumerations and constants.
The disti::DynamicArray class. A templated array of objects capable of dynamically growing.
#define GLSGEN_GlsAdvancedMesh_EXPORT
Provides support for creating DLLs.
Definition: gls_render_effect.h:61
The disti::GlsStateManager factory class. Creates an instance of a state manager that manages the GL ...
Used for matching version of libraries and headers.
The disti::Material class.
Definition: bmpimage.h:46
@ TEXTURE_MAP_REPLACE
Definition: display_types.h:56
@ TEXTURE_FILTER_LINEAR
Definition: display_types.h:63
DynamicArray< int > ReferencedTextureArray
Typedef for a list of texture indices.
Definition: gls_render_effect.h:72
DynamicArray< int > ReferencedMaterialArray
Typedef for a list of material indices.
Definition: gls_render_effect.h:73