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