1 /*!**************************************************************************** 2 3 @file PVRTPrint3D.h 4 @copyright Copyright (c) Imagination Technologies Limited. 5 @brief Code to print text through the 3D interface. 6 7 ******************************************************************************/ 8 #ifndef _PVRTPRINT3D_H_ 9 #define _PVRTPRINT3D_H_ 10 11 #include "PVRTGlobal.h" 12 #include "PVRTError.h" 13 #include "PVRTMatrix.h" 14 #include "PVRTVector.h" 15 #include "PVRTArray.h" 16 17 struct MetaDataBlock; 18 template <typename KeyType, typename DataType> 19 class CPVRTMap; 20 21 /**************************************************************************** 22 ** Enums 23 ****************************************************************************/ 24 #define PVRTPRINT3D_MAX_RENDERABLE_LETTERS (0xFFFF >> 2) 25 26 /*!*************************************************************************** 27 @enum EPVRTPrint3DLogo 28 @brief Logo flags for DisplayDefaultTitle 29 *****************************************************************************/ 30 typedef enum { 31 ePVRTPrint3DLogoNone = 0x00, 32 ePVRTPrint3DLogoPowerVR = 0x02, 33 ePVRTPrint3DLogoIMG = 0x04, 34 ePVRTPrint3DSDKLogo = ePVRTPrint3DLogoPowerVR 35 } EPVRTPrint3DLogo; 36 37 /**************************************************************************** 38 ** Constants 39 ****************************************************************************/ 40 const PVRTuint32 PVRTPRINT3D_HEADER = 0xFCFC0050; 41 const PVRTuint32 PVRTPRINT3D_CHARLIST = 0xFCFC0051; 42 const PVRTuint32 PVRTPRINT3D_RECTS = 0xFCFC0052; 43 const PVRTuint32 PVRTPRINT3D_METRICS = 0xFCFC0053; 44 const PVRTuint32 PVRTPRINT3D_YOFFSET = 0xFCFC0054; 45 const PVRTuint32 PVRTPRINT3D_KERNING = 0xFCFC0055; 46 47 const PVRTuint32 PVRTPRINT3D_VERSION = 1; 48 49 /**************************************************************************** 50 ** Structures 51 ****************************************************************************/ 52 /*!************************************************************************** 53 @struct SPVRTPrint3DHeader 54 @brief A structure for information describing the loaded font. 55 ****************************************************************************/ 56 struct SPVRTPrint3DHeader // 12 bytes 57 { 58 PVRTuint8 uVersion; /*!< Version of PVRFont. */ 59 PVRTuint8 uSpaceWidth; /*!< The width of the 'Space' character. */ 60 PVRTint16 wNumCharacters; /*!< Total number of characters contained in this file. */ 61 PVRTint16 wNumKerningPairs; /*!< Number of characters which kern against each other. */ 62 PVRTint16 wAscent; /*!< The height of the character, in pixels, from the base line. */ 63 PVRTint16 wLineSpace; /*!< The base line to base line dimension, in pixels. */ 64 PVRTint16 wBorderWidth; /*!< px Border around each character. */ 65 }; 66 /*!************************************************************************** 67 @struct SPVRTPrint3DAPIVertex 68 @brief A structure for Print3Ds vertex type 69 ****************************************************************************/ 70 struct SPVRTPrint3DAPIVertex 71 { 72 VERTTYPE sx, sy, sz, rhw; 73 unsigned int color; 74 VERTTYPE tu, tv; 75 }; 76 77 struct PVRTextureHeaderV3; 78 struct SPVRTPrint3DAPI; 79 struct SPVRTContext; 80 81 /*!*************************************************************************** 82 @class CPVRTPrint3D 83 @brief Display text/logos on the screen 84 *****************************************************************************/ 85 class CPVRTPrint3D 86 { 87 public: 88 /*!*************************************************************************** 89 @fn CPVRTPrint3D 90 @brief Init some values. 91 *****************************************************************************/ 92 CPVRTPrint3D(); 93 /*!*************************************************************************** 94 @fn ~CPVRTPrint3D 95 @brief De-allocate the working memory 96 *****************************************************************************/ 97 ~CPVRTPrint3D(); 98 99 /*!*************************************************************************** 100 @brief Initialization and texture upload of default font data. 101 Should be called only once for a Print3D object. 102 @param[in] pContext Context 103 @param[in] dwScreenX Screen resolution along X 104 @param[in] dwScreenY Screen resolution along Y 105 @param[in] bRotate Rotate print3D by 90 degrees 106 @param[in] bMakeCopy This instance of Print3D creates a copy 107 of it's data instead of sharing with previous 108 contexts. Set this parameter if you require 109 thread safety. 110 @return PVR_SUCCESS or PVR_FAIL 111 *****************************************************************************/ 112 EPVRTError SetTextures( 113 const SPVRTContext * const pContext, 114 const unsigned int dwScreenX, 115 const unsigned int dwScreenY, 116 const bool bRotate = false, 117 const bool bMakeCopy = false); 118 119 /*!*************************************************************************** 120 @brief Initialization and texture upload of user-provided font 121 data. Should be called only once for a Print3D object. 122 @param[in] pContext Context 123 @param[in] pTexData User-provided font texture 124 @param[in] dwScreenX Screen resolution along X 125 @param[in] dwScreenY Screen resolution along Y 126 @param[in] bRotate Rotate print3D by 90 degrees 127 @param[in] bMakeCopy This instance of Print3D creates a copy 128 of it's data instead of sharing with previous 129 contexts. Set this parameter if you require 130 thread safety. 131 @return PVR_SUCCESS or PVR_FAIL 132 *****************************************************************************/ 133 EPVRTError SetTextures( 134 const SPVRTContext * const pContext, 135 const void * const pTexData, 136 const unsigned int dwScreenX, 137 const unsigned int dwScreenY, 138 const bool bRotate = false, 139 const bool bMakeCopy = false); 140 141 /*!*************************************************************************** 142 @fn SetProjection 143 @param[in] mProj Projection matrix 144 @brief Sets the projection matrix for the proceeding flush(). 145 *****************************************************************************/ 146 void SetProjection(const PVRTMat4& mProj); 147 148 /*!*************************************************************************** 149 @fn SetModelView 150 @param[in] mModelView Model View matrix 151 @brief Sets the model view matrix for the proceeding flush(). 152 *****************************************************************************/ 153 void SetModelView(const PVRTMat4& mModelView); 154 155 /*!*************************************************************************** 156 @fn SetFiltering 157 @param[in] eMin The method of texture filtering for minification 158 @param[in] eMag The method of texture filtering for minification 159 @param[in] eMip The method of texture filtering for minification 160 @brief Sets the method of texture filtering for the font texture. 161 Print3D will attempt to pick the best method by default 162 but this method allows the user to override this. 163 *****************************************************************************/ 164 void SetFiltering(ETextureFilter eMin, ETextureFilter eMag, ETextureFilter eMip); 165 166 /*!*************************************************************************** 167 @brief Display 3D text on screen. 168 CPVRTPrint3D::SetTextures(...) must have been called 169 beforehand. 170 This function accepts formatting in the printf way. 171 @param[in] fPosX Position of the text along X 172 @param[in] fPosY Position of the text along Y 173 @param[in] fScale Scale of the text 174 @param[in] Colour Colour of the text 175 @param[in] pszFormat Format string for the text 176 @return PVR_SUCCESS or PVR_FAIL 177 *****************************************************************************/ 178 EPVRTError Print3D(float fPosX, float fPosY, const float fScale, unsigned int Colour, const char * const pszFormat, ...); 179 180 181 /*!*************************************************************************** 182 @brief Display wide-char 3D text on screen. 183 CPVRTPrint3D::SetTextures(...) must have been called 184 beforehand. 185 This function accepts formatting in the printf way. 186 @param[in] fPosX Position of the text along X 187 @param[in] fPosY Position of the text along Y 188 @param[in] fScale Scale of the text 189 @param[in] Colour Colour of the text 190 @param[in] pszFormat Format string for the text 191 @return PVR_SUCCESS or PVR_FAIL 192 *****************************************************************************/ 193 EPVRTError Print3D(float fPosX, float fPosY, const float fScale, unsigned int Colour, const wchar_t * const pszFormat, ...); 194 195 /*!*************************************************************************** 196 @fn DisplayDefaultTitle 197 @param[in] pszTitle Title to display 198 @param[in] pszDescription Description to display 199 @param[in] uDisplayLogo 1 = Display the logo 200 @return PVR_SUCCESS or PVR_FAIL 201 @brief Creates a default title with predefined position and colours. 202 It displays as well company logos when requested: 203 0 = No logo 204 1 = PowerVR logo 205 2 = Img Tech logo 206 *****************************************************************************/ 207 EPVRTError DisplayDefaultTitle(const char * const pszTitle, const char * const pszDescription, const unsigned int uDisplayLogo); 208 209 /*!*************************************************************************** 210 @brief Returns the size of a string in pixels. 211 @param[out] pfWidth Width of the string in pixels 212 @param[out] pfHeight Height of the string in pixels 213 @param[in] fScale A value to scale the font by 214 @param[in] pszUTF8 UTF8 string to take the size of 215 *****************************************************************************/ 216 void MeasureText( 217 float * const pfWidth, 218 float * const pfHeight, 219 float fScale, 220 const char * const pszUTF8); 221 222 /*!*************************************************************************** 223 @brief Returns the size of a string in pixels. 224 @param[out] pfWidth Width of the string in pixels 225 @param[out] pfHeight Height of the string in pixels 226 @param[in] fScale A value to scale the font by 227 @param[in] pszUnicode Wide character string to take the 228 length of. 229 *****************************************************************************/ 230 void MeasureText( 231 float * const pfWidth, 232 float * const pfHeight, 233 float fScale, 234 const wchar_t* const pszUnicode); 235 236 /*!*************************************************************************** 237 @brief Returns the 'ascent' of the font. This is typically the 238 height from the baseline of the larget glyph in the set. 239 @return The ascent. 240 *****************************************************************************/ 241 unsigned int GetFontAscent(); 242 243 /*!*************************************************************************** 244 @brief Returns the default line spacing (i.e baseline to baseline) 245 for the font. 246 @return The line spacing. 247 *****************************************************************************/ 248 unsigned int GetFontLineSpacing(); 249 250 /*!*************************************************************************** 251 @brief Returns the current resolution used by Print3D 252 @param[out] dwScreenX Screen resolution X 253 @param[out] dwScreenY Screen resolution Y 254 *****************************************************************************/ 255 void GetAspectRatio(unsigned int *dwScreenX, unsigned int *dwScreenY); 256 257 /*!*************************************************************************** 258 @brief Deallocate the memory allocated in SetTextures(...) 259 *****************************************************************************/ 260 void ReleaseTextures(); 261 262 /*!*************************************************************************** 263 @brief Flushes all the print text commands 264 *****************************************************************************/ 265 int Flush(); 266 267 private: 268 /*!*************************************************************************** 269 @brief Update a single line 270 @param[in] fZPos 271 @param[in] XPos 272 @param[in] YPos 273 @param[in] fScale 274 @param[in] Colour 275 @param[in] Text 276 @param[in] pVertices 277 @return Number of vertices affected 278 *****************************************************************************/ 279 unsigned int UpdateLine(const float fZPos, float XPos, float YPos, const float fScale, const unsigned int Colour, const CPVRTArray<PVRTuint32>& Text, SPVRTPrint3DAPIVertex * const pVertices); 280 281 /*!*************************************************************************** 282 @brief Draw a single line of text. 283 @return true or false 284 *****************************************************************************/ 285 bool DrawLine(SPVRTPrint3DAPIVertex *pVtx, unsigned int nVertices); 286 287 /*!*************************************************************************** 288 @fn LoadFontData 289 @param[in] texHeader 290 @param[in] MetaDataMap 291 @return bool true if successful. 292 @brief Loads font data bundled with the texture file. 293 *****************************************************************************/ 294 bool LoadFontData(const PVRTextureHeaderV3* texHeader, CPVRTMap<PVRTuint32, CPVRTMap<PVRTuint32, MetaDataBlock> >& MetaDataMap); 295 296 /*!*************************************************************************** 297 @fn ReadMetaBlock 298 @param[in] pDataCursor 299 @return bool true if successful. 300 @brief Reads a single meta data block from the data file. 301 *****************************************************************************/ 302 bool ReadMetaBlock(const PVRTuint8** pDataCursor); 303 304 /*!*************************************************************************** 305 @fn FindCharacter 306 @param[in] character 307 @return The character index, or PVRPRINT3D_INVALID_CHAR if not found. 308 @brief Finds a given character in the binary data and returns its 309 index. 310 *****************************************************************************/ 311 PVRTuint32 FindCharacter(PVRTuint32 character) const; 312 313 /*!*************************************************************************** 314 @fn CharacterCompareFunc 315 @param[in] pA 316 @param[in] pB 317 @return PVRTint32 318 @brief Compares two characters for binary search. 319 *****************************************************************************/ 320 static PVRTint32 CharacterCompareFunc(const void* pA, const void* pB); 321 322 /*!*************************************************************************** 323 @fn KerningCompareFunc 324 @param[in] pA 325 @param[in] pB 326 @return VRTint32 327 @brief Compares two kerning pairs for binary search. 328 *****************************************************************************/ 329 static PVRTint32 KerningCompareFunc(const void* pA, const void* pB); 330 331 /*!*************************************************************************** 332 @fn ApplyKerning 333 @param[in] cA 334 @param[in] cB 335 @param[out] fOffset 336 @brief Calculates kerning offset. 337 *****************************************************************************/ 338 void ApplyKerning(const PVRTuint32 cA, const PVRTuint32 cB, float& fOffset) const; 339 340 /*!*************************************************************************** 341 @brief Returns the size of a string in pixels. 342 @param[out] pfWidth Width of the string in pixels 343 @param[out] pfHeight Height of the string in pixels 344 @param[in] fScale Font size 345 @param[in] utf32 UTF32 string to take the size of. 346 *****************************************************************************/ 347 void MeasureText( 348 float * const pfWidth, 349 float * const pfHeight, 350 float fScale, 351 const CPVRTArray<PVRTuint32>& utf32); 352 353 /*!*************************************************************************** 354 @brief Takes an array of UTF32 characters and generates the required mesh. 355 @param[in] fPosX X Position 356 @param[in] fPosY Y Position 357 @param[in] fScale Text scale 358 @param[in] Colour ARGB colour 359 @param[in] UTF32 Array of UTF32 characters 360 @param[in] bUpdate Whether to update the vertices 361 @return EPVRTError Success of failure 362 *****************************************************************************/ 363 EPVRTError Print3D(float fPosX, float fPosY, const float fScale, unsigned int Colour, const CPVRTArray<PVRTuint32>& UTF32, bool bUpdate); 364 365 //*************************************************************************** 366 // Structures and enums for font data 367 // The following structures are used to provide layout information for associated fonts. 368 //*****************************************************************************/ 369 private: 370 struct CharacterUV 371 { 372 PVRTfloat32 fUL; 373 PVRTfloat32 fVT; 374 PVRTfloat32 fUR; 375 PVRTfloat32 fVB; 376 }; 377 378 struct Rectanglei 379 { 380 PVRTint32 nX; 381 PVRTint32 nY; 382 PVRTint32 nW; 383 PVRTint32 nH; 384 }; 385 386 #pragma pack(push, 4) // Force 4byte alignment. 387 struct KerningPair 388 { 389 PVRTuint64 uiPair; /*!< OR'd pair for 32bit characters */ 390 PVRTint32 iOffset; /*!< Kerning offset (in pixels) */ 391 }; 392 #pragma pack(pop) 393 394 struct CharMetrics 395 { 396 PVRTint16 nXOff; /*!< Prefix offset */ 397 PVRTuint16 nAdv; /*!< Character width */ 398 }; 399 400 enum 401 { 402 eFilterProc_Min, 403 eFilterProc_Mag, 404 eFilterProc_Mip, 405 406 eFilterProc_Size 407 }; 408 409 enum ELogoPos 410 { 411 eBottom = 0x01, 412 eTop = 0x02, 413 eLeft = 0x04, 414 eRight = 0x08 415 }; 416 417 private: 418 // Mesh parameters 419 SPVRTPrint3DAPI *m_pAPI; 420 unsigned int m_uLogoToDisplay; 421 unsigned short *m_pwFacesFont; 422 SPVRTPrint3DAPIVertex *m_pPrint3dVtx; 423 float m_fScreenScale[2]; 424 unsigned int m_ui32ScreenDim[2]; 425 bool m_bTexturesSet; 426 SPVRTPrint3DAPIVertex *m_pVtxCache; 427 int m_nVtxCache; 428 int m_nVtxCacheMax; 429 bool m_bRotate; 430 431 // Cached memory 432 CPVRTArray<PVRTuint32> m_CachedUTF32; 433 int m_nCachedNumVerts; 434 wchar_t* m_pwzPreviousString; 435 char* m_pszPreviousString; 436 float m_fPrevScale; 437 float m_fPrevX; 438 float m_fPrevY; 439 unsigned int m_uiPrevCol; 440 441 // Font parameters 442 CharacterUV* m_pUVs; 443 KerningPair* m_pKerningPairs; 444 CharMetrics* m_pCharMatrics; 445 446 float m_fTexW; 447 float m_fTexH; 448 449 Rectanglei* m_pRects; 450 int* m_pYOffsets; 451 int m_uiNextLineH; 452 453 unsigned int m_uiSpaceWidth; 454 unsigned int m_uiNumCharacters; 455 unsigned int m_uiNumKerningPairs; 456 unsigned int m_uiAscent; 457 PVRTuint32* m_pszCharacterList; 458 bool m_bHasMipmaps; 459 460 // View parameters 461 PVRTMat4 m_mProj; 462 PVRTMat4 m_mModelView; 463 bool m_bUsingProjection; 464 ETextureFilter m_eFilterMethod[eFilterProc_Size]; 465 466 //*************************************************************************** 467 // API specific code 468 // The following functions are API specific. Their implementation 469 // can be found in the directory *CurrentAPI*\PVRTPrint3DAPI 470 //*****************************************************************************/ 471 private: 472 /*!*************************************************************************** 473 @fn APIInit 474 @param[in] pContext 475 @param[in] bMakeCopy 476 @return true or false 477 @brief Initialization and texture upload. Should be called only once 478 for a given context. 479 *****************************************************************************/ 480 bool APIInit(const SPVRTContext * const pContext, bool bMakeCopy); 481 482 /*!*************************************************************************** 483 @fn APIRelease 484 @brief Deinitialization. 485 *****************************************************************************/ 486 void APIRelease(); 487 488 /*!*************************************************************************** 489 @fn APIUpLoadIcons 490 @param[in] pIMG 491 @return true or false 492 @brief Initialization and texture upload. Should be called only once 493 for a given context. 494 *****************************************************************************/ 495 bool APIUpLoadIcons(const PVRTuint8 * const pIMG, const PVRTuint8 * const pPowerVR); 496 497 /*!*************************************************************************** 498 @fn APIUpLoadTexture 499 @param[in] pSource 500 @param[in] header 501 @param[in] MetaDataMap 502 @return true if successful, false otherwise. 503 @brief Reads texture data from *.dat and loads it in 504 video memory. 505 *****************************************************************************/ 506 bool APIUpLoadTexture(const PVRTuint8* pSource, const PVRTextureHeaderV3* header, CPVRTMap<PVRTuint32, CPVRTMap<PVRTuint32, MetaDataBlock> >& MetaDataMap); 507 508 509 /*!*************************************************************************** 510 @fn APIRenderStates 511 @param[in] nAction 512 @brief Stores, writes and restores Render States 513 *****************************************************************************/ 514 void APIRenderStates(int nAction); 515 516 /*!*************************************************************************** 517 @fn APIDrawLogo 518 @param[in] uLogoToDisplay 519 @param[in] nPod 520 @brief nPos = -1 to the left 521 nPos = +1 to the right 522 *****************************************************************************/ 523 void APIDrawLogo(const EPVRTPrint3DLogo uLogoToDisplay, const int ePos); 524 }; 525 526 527 #endif /* _PVRTPRINT3D_H_ */ 528 529 /***************************************************************************** 530 End of file (PVRTPrint3D.h) 531 *****************************************************************************/ 532