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
17struct MetaDataBlock;
18template <typename KeyType, typename DataType>
19class 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*****************************************************************************/
30typedef enum {
31	ePVRTPrint3DLogoNone	= 0x00,
32	ePVRTPrint3DLogoPowerVR = 0x02,
33	ePVRTPrint3DLogoIMG		= 0x04,
34	ePVRTPrint3DSDKLogo		= ePVRTPrint3DLogoPowerVR
35} EPVRTPrint3DLogo;
36
37/****************************************************************************
38** Constants
39****************************************************************************/
40const PVRTuint32 PVRTPRINT3D_HEADER			= 0xFCFC0050;
41const PVRTuint32 PVRTPRINT3D_CHARLIST		= 0xFCFC0051;
42const PVRTuint32 PVRTPRINT3D_RECTS			= 0xFCFC0052;
43const PVRTuint32 PVRTPRINT3D_METRICS		= 0xFCFC0053;
44const PVRTuint32 PVRTPRINT3D_YOFFSET		= 0xFCFC0054;
45const PVRTuint32 PVRTPRINT3D_KERNING		= 0xFCFC0055;
46
47const PVRTuint32 PVRTPRINT3D_VERSION		= 1;
48
49/****************************************************************************
50** Structures
51****************************************************************************/
52/*!**************************************************************************
53 @struct    SPVRTPrint3DHeader
54 @brief     A structure for information describing the loaded font.
55****************************************************************************/
56struct 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****************************************************************************/
70struct SPVRTPrint3DAPIVertex
71{
72	VERTTYPE		sx, sy, sz, rhw;
73	unsigned int	color;
74	VERTTYPE		tu, tv;
75};
76
77struct PVRTextureHeaderV3;
78struct SPVRTPrint3DAPI;
79struct SPVRTContext;
80
81/*!***************************************************************************
82 @class CPVRTPrint3D
83 @brief Display text/logos on the screen
84*****************************************************************************/
85class CPVRTPrint3D
86{
87public:
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
267private:
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//*****************************************************************************/
369private:
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
417private:
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//*****************************************************************************/
471private:
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