1/*!****************************************************************************
2
3 @file         OGLES2/PVRTPFXParserAPI.h
4 @ingroup      API_OGLES2
5 @copyright    Copyright (c) Imagination Technologies Limited.
6 @brief        Declaration of PFX file parser
7
8******************************************************************************/
9
10#ifndef _PVRTPFXPARSERAPI_H_
11#define _PVRTPFXPARSERAPI_H_
12
13/*!
14 @addtogroup   API_OGLES2
15 @{
16*/
17
18// Everything been documented in OGL/PVRTPFXParserAPI.h. This would cause documentation duplication in the
19// current version of Doxygen.
20#ifndef NO_DOXYGEN
21
22#include "../PVRTError.h"
23
24/****************************************************************************
25** Structures
26****************************************************************************/
27
28/*!**************************************************************************
29 @struct        SPVRTPFXUniformSemantic
30 @brief         Struct to convert a semantic string to a number.
31 @details       The application supplies an array of these so PVRTPFX can translate semantic strings to numbers
32****************************************************************************/
33struct SPVRTPFXUniformSemantic
34{
35	const char		*p;	/*!< String containing semantic */
36	unsigned int	n;	/*!< Application-defined semantic value */
37};
38
39/*!**************************************************************************
40 @struct       SPVRTPFXUniform
41 @brief        A struct containing GL uniform data.
42 @details      PVRTPFX returns an array of these to indicate GL locations & semantics to the application
43 ***************************************************************************/
44struct SPVRTPFXUniform
45{
46	unsigned int	nLocation;		/*!< GL location of the Uniform */
47	unsigned int	nSemantic;		/*!< Application-defined semantic value */
48	unsigned int	nIdx;			/*!< Index; for example two semantics might be LIGHTPOSITION0 and LIGHTPOSITION1 */
49	CPVRTString		sValueName;		/*!< The name of the variable referenced in shader code */
50};
51
52/*!**************************************************************************
53 @struct       SPVRTPFXTexture
54 @brief        A texture data array.
55 @details      An array of these is gained from PVRTPFX so the application can fill in the texture handles
56 ***************************************************************************/
57struct SPVRTPFXTexture
58{
59	CPVRTStringHash		Name;	    /*!< texture name */
60	GLuint				ui;		    /*!< Loaded texture handle */
61	GLuint				unit;	    /*!< The bound texture unit */
62	unsigned int		flags;	    /*!< Texture type i.e 2D, Cubemap */
63};
64
65/*!**************************************************************************
66 @class        PVRTPFXEffectDelegate
67 @brief        Receives callbacks for effects.
68 ***************************************************************************/
69class PVRTPFXEffectDelegate
70{
71public:
72	virtual EPVRTError PVRTPFXOnLoadTexture(const CPVRTStringHash& TextureName, GLuint& uiHandle, unsigned int& uiFlags) = 0; /*!< Returns error if texture could not be loaded */
73	virtual ~PVRTPFXEffectDelegate() { }  /*!< Destructor */
74};
75
76/*!**************************************************************************
77 @class CPVRTPFXEffect
78 @brief PFX effect
79****************************************************************************/
80class CPVRTPFXEffect
81{
82public:
83	/*!***************************************************************************
84	@brief      		Sets the context to NULL and initialises the member variables to zero.
85	*****************************************************************************/
86	CPVRTPFXEffect();
87
88	/*!***************************************************************************
89	@brief      		Sets the context and initialises the member variables to zero.
90	*****************************************************************************/
91	CPVRTPFXEffect(SPVRTContext &sContext);
92
93	/*!***************************************************************************
94	@brief      		Calls Destroy().
95	*****************************************************************************/
96	~CPVRTPFXEffect();
97
98	/*!***************************************************************************
99	@brief		        Loads the specified effect from the CPVRTPFXParser object.
100						Compiles and links the shaders. Initialises texture data.
101	@param[in]			src					PFX Parser Object
102	@param[in]			pszEffect			Effect name
103	@param[in]			pszFileName			Effect file name
104	@param[in]			pDelegate			A delegate which will receive callbacks
105	@param[out]			uiUnknownUniforms	Number of unknown uniforms found
106	@param[out]			pReturnError		Error string
107	@return			    PVR_SUCCESS if load succeeded
108	*****************************************************************************/
109	EPVRTError Load(CPVRTPFXParser &src, const char * const pszEffect, const char * const pszFileName,
110					PVRTPFXEffectDelegate* pDelegate, unsigned int& uiUnknownUniforms, CPVRTString *pReturnError);
111
112	/*!***************************************************************************
113	@brief		        Deletes the gl program object and texture data.
114	*****************************************************************************/
115	void Destroy();
116
117	/*!***************************************************************************
118	@brief		        Selects the gl program object and binds the textures.
119						If the render target texture for the current render pass is required
120						in this effect (and therefore cannot be sampled),
121						load the replacement texture instead.
122	@param[in]			i32RenderTextureId		The ID of the render target of the current task
123	@param[in]			ui32ReplacementTexture	The ID of the texture that should be used instead
124	@return			    EPVRTError				PVR_SUCCESS if activate succeeded
125	*****************************************************************************/
126	EPVRTError Activate(const int i32RenderTextureId=-1, const unsigned int ui32ReplacementTexture=0);
127
128	/*!***************************************************************************
129	@brief		        Gets the texture data array.
130	@return			    SPVRTPFXTexture*		pointer to the texture data array
131	*****************************************************************************/
132	const CPVRTArray<SPVRTPFXTexture>& GetTextureArray() const;
133
134	/*!***************************************************************************
135	@brief	            Returns a list of known semantics.
136	@return			    const CPVRTArray<SPVRTPFXUniform>&
137	*****************************************************************************/
138	const CPVRTArray<SPVRTPFXUniform>& GetUniformArray() const;
139
140	/*!***************************************************************************
141	@brief	            Gets the array of registered semantics which will be used to
142                        match PFX code.
143	@return			    const CPVRTArray<SPVRTPFXUniformSemantic>&
144	*****************************************************************************/
145	const CPVRTArray<SPVRTPFXUniformSemantic>& GetSemanticArray() const;
146
147	/*!***************************************************************************
148	@brief		        Sets the textrue and applys the filtering.
149	@param[in]			nIdx				texture number
150	@param[in]			ui					opengl texture handle
151	@param[in]			u32flags			texture flags
152	*****************************************************************************/
153	void SetTexture(const unsigned int nIdx, const GLuint ui, const unsigned int u32flags=0);
154
155	/*!***************************************************************************
156	@brief		        Sets the dafault value for the uniform semantic.
157	@param[in]			pszName				name of uniform
158	@param[in]			psDefaultValue      pointer to default value
159	*****************************************************************************/
160	void SetDefaultUniformValue(const char *const pszName, const SPVRTSemanticDefaultData *psDefaultValue);
161
162	/*!***************************************************************************
163	@brief	            Registers a user-provided uniform semantic.
164	@param[in]			psUniforms			Array of semantics to register
165	@param[in]			uiNumUniforms		Number provided
166	@param[out]			pReturnError		Human-readable error if any
167	@return			    PVR_SUCCESS on success
168	*****************************************************************************/
169	EPVRTError RegisterUniformSemantic(const SPVRTPFXUniformSemantic* const psUniforms, unsigned int uiNumUniforms, CPVRTString* pReturnError);
170
171	/*!***************************************************************************
172	@brief	            Removes a given semantic ID from the 'known' semantic list and
173                        re-parses the effect to update the uniform table.
174	@param[in]			uiSemanticID
175	@param[out]			pReturnError
176	@return			    PVR_SUCCESS on success
177	*****************************************************************************/
178	EPVRTError RemoveUniformSemantic(unsigned int uiSemanticID, CPVRTString* pReturnError);
179
180	/*!***************************************************************************
181	 @brief		        Sets the context for this effect.
182	 @param[in]			pContext			context pointer
183	 *****************************************************************************/
184	void SetContext(SPVRTContext * const pContext);
185
186	/*!***************************************************************************
187	@brief	            Returns the OGL program handle.
188	@return			    unsigned int
189	*****************************************************************************/
190	unsigned int GetProgramHandle() const;
191
192	/*!***************************************************************************
193	@brief	            Gets the active effect index within the PFX file.
194	@return			    unsigned int
195	*****************************************************************************/
196	unsigned int GetEffectIndex() const;
197
198private:
199	/*!***************************************************************************
200	@brief	            Loads all of the GLSL shaders for an effect.
201	@param[in]			pszFileName
202	@param[out]			pReturnError
203	@return			    EPVRTError
204	*****************************************************************************/
205	EPVRTError LoadShadersForEffect(CPVRTPFXParser &src, const char * const pszFileName, CPVRTString *pReturnError);
206
207	/*!***************************************************************************
208	@brief	            Loads all of the textures for this effect.
209	@param[out]			pReturnError
210	@return			    EPVRTError
211	*****************************************************************************/
212	EPVRTError LoadTexturesForEffect(PVRTPFXEffectDelegate* pDelegate, CPVRTString *pReturnError);
213
214	/*!***************************************************************************
215	@brief	            Builds the uniform table from a list of known semantics.
216	@param[out]			uiUnknownSemantics
217	@param[out]			pReturnError
218	@return			    EPVRTError
219	*****************************************************************************/
220	EPVRTError RebuildUniformTable(unsigned int& uiUnknownSemantics, CPVRTString* pReturnError);
221
222protected:
223	bool									m_bLoaded;
224	SPVRTContext*							m_psContext;
225	CPVRTPFXParser*							m_pParser;
226	unsigned int							m_nEffect;
227
228	GLuint									m_uiProgram;		// Loaded program
229
230	CPVRTArray<SPVRTPFXTexture>				m_Textures;			// Array of loaded textures
231	CPVRTArray<SPVRTPFXUniform>				m_Uniforms;			// Array of found uniforms
232
233	CPVRTArray<SPVRTPFXUniformSemantic>		m_Semantics;		// An array of registered semantics.
234};
235
236/****************************************************************************
237** Auxiliary functions
238****************************************************************************/
239
240/*!**************************************************************************
241 @brief                 'Equivalent to' operator
242 @param[in]             lhs     First SPVRTPFXUniformSemantic
243 @param[in]             rhs     Second SPVRTPFXUniformSemantic
244 @return                True if the numbers in the two SPVRTPFXUniformSemantics are equivalent.
245****************************************************************************/
246inline bool operator==(const SPVRTPFXUniformSemantic& lhs, const SPVRTPFXUniformSemantic& rhs)
247{
248	return (lhs.n == rhs.n);
249}
250
251 #endif
252
253/*! @} */
254
255#endif /* _PVRTPFXPARSERAPI_H_ */
256
257/*****************************************************************************
258 End of file (PVRTPFXParserAPI.h)
259*****************************************************************************/
260
261