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 ****************************************************************************/ 33 struct 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 ***************************************************************************/ 44 struct 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 ***************************************************************************/ 57 struct 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 ***************************************************************************/ 69 class PVRTPFXEffectDelegate 70 { 71 public: 72 virtual EPVRTError PVRTPFXOnLoadTexture(const CPVRTStringHash& TextureName, GLuint& uiHandle, unsigned int& uiFlags) = 0; /*!< Returns error if texture could not be loaded */ ~PVRTPFXEffectDelegate()73 virtual ~PVRTPFXEffectDelegate() { } /*!< Destructor */ 74 }; 75 76 /*!************************************************************************** 77 @class CPVRTPFXEffect 78 @brief PFX effect 79 ****************************************************************************/ 80 class CPVRTPFXEffect 81 { 82 public: 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 198 private: 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 222 protected: 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 ****************************************************************************/ 246 inline 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