// Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

// which accompanies this distribution, and is available

// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

// A header for the open font system, which allows

// EPOC32 to use fonts of arbitrary types, including TrueType

// and other outline font formats.

// 

//

#ifndef OPENFONT_H__

#define OPENFONT_H__

#include <e32base.h>

#include <gdi.h>

#include <ecom/ecom.h>

class CFont;

class COpenFontFile;

class COpenFontGlyph;

class COpenFontGlyphCache;

class COpenFontGlyphTreeEntry;

class COpenFontPositioner;

class COpenFontSessionCache;

class COpenFontSessionCacheList;

class RFs;

class TCharacterMetrics;

class TFontSpec;

class TOpenFontFaceAttrib;

class CFontStore;

class TOpenFontFileData;

class TShapeHeader;

class CBitmapFont;

class CShaperFactory;

class CShaper;

class TShapeHeader;

class TFontShapeFunctionParameters;

class TFontShapeDeleteFunctionParameters;

class RShapeInfo;

class TShapeMessageParameters;

/**

The OpenFont ECOM Plug-in Interface Definition UID. 

@internalTechnology

*/

const TInt KUidOpenFontRasterizerPlunginInterface = 0x101F7F5D;

/**

The Shaper Factory ECOM Plug-in Interface Definition UID. 

@internalTechnology

*/

const TInt KUidShaperFactoryPlunginInterface = 0x10279726;

/** 

Replacement character code. 

This is a Unicode private use area codepoint, which is reserved in the Symbian 

OS to represent characters for which a glyph does not exist in a font (either 

a bitmap or scalable font). If a glyph exists in a font with this character 

code, it will be used for nonexistent characters, otherwise, the rasterizer's 

default replacement character glyph will be used. For example, TrueType fonts 

return glyph index 0 for nonexistent characters, and that is usually mapped 

to an empty rectangle.

@internalTechnology

*/

const TUint KReplacementCharacter = 0xF6DB;

/** 

KFillCharacterOffset is a significant offset that is set when a character within a code section is 

not in the font. This means that for these fill characters nothing is stored within the binary

data part of the code section.

@internalTechnology

*/

const TInt KFillCharacterOffset = 0x7FFF;

/**

Supplied to COpenFont::ExtendedInterface() to access the extended

API interface MOpenFontShapingExtension.

@see COpenFont::ExtendedInterface()

@see MOpenFontShapingExtension

@publishedAll

@released

*/

const TUid KUidOpenFontShapingExtension = {0x10274DB9};

/**

Supplied to COpenFont::ExtendedInterface() to access the extended

API interface MOpenFontTrueTypeExtension.

@see COpenFont::ExtendedInterface()

@see MOpenFontTrueTypeExtension

@publishedAll

@released

*/

const TUid KUidOpenFontTrueTypeExtension = {0x1027553E};

/**

Supplied to CShaper::ExtendedInterface() to get the language and script

code with which the current shaper is instatsiated.

@see CShaper::ExtendedInterface()

@publishedAll

@released

*/

const TUid KUidShaperGetScript = {0x20009966};

const TUid KUidShaperGetLang = {0x20009967};

/** 

Font metrics.

@see CFbsFont::GetFontMetrics()

@publishedAll

@released

*/

class TOpenFontMetrics

	{

public:

	inline TOpenFontMetrics();

	IMPORT_C TOpenFontMetrics(const CFont* aFont);

	inline TInt Size() const;

	inline TInt Ascent() const;

	inline TInt Descent() const;

	inline TInt MaxHeight() const;

	inline TInt MaxDepth() const;

	inline TInt MaxWidth() const;

	inline void SetSize(TInt aSize);

	inline void SetAscent(TInt aAscent);

	inline void SetDescent(TInt aDescent);

	inline void SetMaxHeight(TInt aMaxHeight);

	inline void SetMaxDepth(TInt aMaxDepth);

	inline void SetMaxWidth(TInt aMaxWidth);

private:

	TInt16 iDesignHeight;	// size of the font ('pointsize' in pixels)

	TInt16 iAscent;			// typographic ascent

	TInt16 iDescent;		// typographic descent

	TInt16 iMaxHeight;		// maximum height of a character; may be greater than iAscent

	TInt16 iMaxDepth;		// maximum depth of a character; may be greater than iDescent

	TInt16 iMaxWidth;		// maximum width of a character

	TInt32 iReserved;

	};

/** 

Character metrics  includes more information than TCharacterMetrics.

Character metrics allow characters to be placed horizontally or vertically. 

The character metrics encapsulated by this class are: Height, Width, Horizontal 

Bearing X, Horizontal Bearing Y, Horizontal Advance, Vertical Bearing X, 

Vertical Bearing Y, and Vertical Advance. Their meanings are described in the 

associated setter and getter functions.

Note : 

Vertical drawing (in the sense of characters drawn with horizontal baselines, 

but in a vertical line) is not yet supported by Symbian OS.

@see CFont::GetCharacterData()

@see CFbsFont::GetCharacterData() 

@publishedAll

@released

*/

class TOpenFontCharMetrics

	{

public:

	enum TUninitialized { EUninitialized };

public:

	/** Default constructor initializes all members to 0. */ 

	inline TOpenFontCharMetrics();

	/** Constructor that does not initialize any members. */ 

	TOpenFontCharMetrics(TUninitialized) {}

	IMPORT_C TOpenFontCharMetrics(const TCharacterMetrics& aMetrics);

	IMPORT_C TBool GetTCharacterMetrics(TCharacterMetrics& aMetrics) const;

	inline TInt Width() const;

	inline TInt Height() const;

	inline TInt HorizBearingX() const;

	inline TInt HorizBearingY() const;

	inline TInt HorizAdvance() const;

	inline TInt VertBearingX() const;

	inline TInt VertBearingY() const;

	inline TInt VertAdvance() const;

	inline void GetHorizBounds(TRect& aBounds) const;

	inline void GetVertBounds(TRect& aBounds) const;

	inline void SetWidth(TInt aWidth);

	inline void SetHeight(TInt aHeight);

	inline void SetHorizBearingX(TInt aHorizBearingX);

	inline void SetHorizBearingY(TInt aHorizBearingY);

	inline void SetHorizAdvance(TInt aHorizAdvance);

	inline void SetVertBearingX(TInt aVertBearingX);

	inline void SetVertBearingY(TInt aVertBearingY);

	inline void SetVertAdvance(TInt aVertAdvance);

private:

	TInt16 iWidth;			// width of the glyph

	TInt16 iHeight;			// height of the glyph

	TInt16 iHorizBearingX;	// x component of horizontal bearing

	TInt16 iHorizBearingY;	// y component of horizontal bearing

	TInt16 iHorizAdvance;	// horizontal advance

	TInt16 iVertBearingX;	// x component of vertical bearing

	TInt16 iVertBearingY;	// y component of vertical bearing

	TInt16 iVertAdvance;	// vertical advance

	TInt32 iReserved;

	};

/** 

Font glyph data.

Objects of this type are used by rasterizers to supply glyph data to font 

and bitmap server clients. Unless you are writing a rasterizer you will not 

need to use an object of this type.

The object cannot be constructed and destroyed by normal means. It resides 

on a specified heap. It is created by New() and deleted by RHeap::Free().

@see COpenFont::RasterizeL()

@publishedAll

@released

*/

class TOpenFontGlyphData

	{

public:

	IMPORT_C static TOpenFontGlyphData* New(RHeap* aHeap,TInt aBufferSize);

	inline TBool Overflow() const;

	inline TInt BytesNeeded() const;

	inline TPtrC8 Bitmap() const;

	inline const TUint8* BitmapPointer() const;

	inline const TOpenFontCharMetrics* Metrics() const;

	inline TInt GlyphIndex() const;

	inline TUint8* BufferStart();

	inline TUint8* BufferEnd();

	inline void SetBytesNeeded(TInt aBytes);

	inline void SetBitmapPointer(const TUint8* aBitmap);

	inline void SetMetricsPointer(const TOpenFontCharMetrics* aMetrics);

	inline void SetPointersToInternalBuffers();

	inline void SetMetrics(TOpenFontCharMetrics& aMetrics);

	inline void SetGlyphIndex(TInt aGlyphIndex);

private:

	/*

	Prevent construction and destruction by normal means; the object resides 

	on a specified heap and is created by New and deleted by RHeap::Free.

	*/

	TOpenFontGlyphData();

	~TOpenFontGlyphData();

private:

	TInt iBitmapBufferSize;					// size of the buffer in bytes

	TInt iBytesNeeded;						// bytes needed for the bitmap

	TOpenFontCharMetrics iMetricsBuffer;	// the metrics

	const TUint8* iBitmap;					// pointer to the bitmap; points either to iBitmapBuffer or to

											// the cache if the character was already rasterized

	const TOpenFontCharMetrics* iMetrics;	// pointer to the metrics; points either to iMetricsBuffer or to

											// the cache if the character was already rasterized

	TInt iGlyphIndex;						// the glyph index

	TAny* iReserved;						// unused; for future expansion

	TUint8 iBitmapBuffer[1];				// buffer used to write the bitmap when it is first rasterized; this

											// is actually of size iBitmapBufferSize.

	};

class COpenFontGlyph;

class CLinkedFontInformation;

/** 

Open Font System font abstract base class.

Derive a class from this class to represent an instance of a typeface at a 

particular size, provide bitmaps of the glyphs, and determine whether 

characters exist in the typeface.

Writing derived classes construction: 

You must call the constructor of this class when creating your derived object, 

passing the arguments aHeap and aSessionCacheList supplied to 

COpenFontFile::GetNearestFontInPixelsL(), and the address of the COpenFontFile 

object that creates the object as aFile.

The derived object must be created on the shared heap aHeap because it is 

shared by several processes: the font and bitmap server and its clients. 

To do this, use aHeap->AllocL() to obtain memory, then construct in place 

using a placement argument to new.

Derived classes must implement the pure virtual function RasterizeL(). 

Information about this function is provided in the function definition below. 

Information about deriving from this class is also provided in the API guide.

@see COpenFontFile::GetNearestFontInPixelsL()

@publishedAll

@released

*/

class COpenFont: public CBase

	{

public:

	/** Creates a bitmap for the specified Unicode character.

	Implementations of this function should put the bitmap in 

	aGlyphData->iBitmapBuffer, and the character metrics are placed in 

	aGlyphData->iMetricsBuffer. The other parts of aGlyphData should be left 

	alone. 

	There are a number of strategies for achieving this, e.g. pass the 

	rasterization task all the way up to the rasterizer engine. These are 

	discussed in the API guide.

	At present you must write the bitmap in the Symbian platform's 

	run-length-encoded format. This is a packed binary format starting on a 

	byte boundary and made up of a number of sections. Each section starts 

	with a five-bit header. If the first bit of the header is 0 the next four 

	bits are a repeat count, starting with the least significant bit, and a 

	single row of bits (the number of bits in a row is specified by 

	aGlyphData->iMetricsBuffer.Width()) follows. If the first bit of the header 

	is 1 the next four bits are a count of non-repeating rows, again starting 

	with the least significant bit, and that many rows of bits follow.

	@param aCode The character code of the Unicode character for which the 

	bitmap is required.

	@param aGlyphData On return, contains a pointer to a TOpenFontGlyphData 

	containing the character's bitmap and metrics. */

	virtual void RasterizeL(TInt aCode,TOpenFontGlyphData* aGlyphData) = 0;

	IMPORT_C virtual void ExtendedInterface(TUid aUid, TAny*& aParam);

	IMPORT_C COpenFont(RHeap* aHeap,COpenFontSessionCacheList* aSessionCacheList,COpenFontFile* aFile);

	IMPORT_C COpenFont(RHeap* aHeap,COpenFontSessionCacheList* aSessionCacheList,COpenFontFile* aFile,TInt aFaceIndex);

	IMPORT_C ~COpenFont();

	IMPORT_C void operator delete(TAny*);

	inline const TOpenFontMetrics& Metrics() const;

	inline const TOpenFontFaceAttrib* FaceAttrib() const;

	inline COpenFontFile* File() const;

	inline TInt FaceIndex() const;

	inline TBool CharacterNeedsToBeRasterized(TInt aSessionHandle,TInt aCode) const;

	void SetShaper(CShaper* aShaper);

	CShaper* GetShaper();

	TBool HasShaper() const;

	TShapeHeader* GetShapedData(TInt aSessionHandle,TFontShapeFunctionParameters* aParams);

	TShapeHeader* InsertShapedDataIntoCache(TInt aSessionHandle,TFontShapeFunctionParameters* aParams, TShapeHeader* aShapeHeader);

	TInt FreeShaperCacheMemory(TInt aBytesNeeded);

	TInt DecrementCachedRefCount(TInt aSessionHandle,TShapeHeader* aShapeHeader,TBool aResetAll=EFalse);

	TBool Rasterize(TInt aSessionHandle,TInt aCode,TOpenFontGlyphData* aGlyphData);

	TBool HasCharacterL(TInt aCode) const;

	TBool GetCharacterData(TInt aSessionHandle,TInt aCode,const TOpenFontCharMetrics*& aMetrics,const TUint8*& aBitmap) const;

	void OnFileDeleted();

	COpenFontGlyphCache* GetGlyphCache();

	inline TInt FontCapitalAscent() const;

	inline TInt FontMaxAscent() const;

	inline TInt FontStandardDescent() const;

	inline TInt FontMaxDescent() const;

	inline TInt FontLineGap() const;

	inline TInt FontMaxHeight() const;

	void DeleteShaper() const;

protected:

	RHeap* iHeap;

	TOpenFontMetrics iMetrics;

private:

	/** The shaper for performing complex character positioning and

	substitution, if available. Null otherwise.

	@internalComponent */

	CShaper* iShaper;

protected:

	/** The positive distance in pixels from the baseline to

		the top of an ANSI capital (whether or not there are

		ANSI capitals in the font) */

	TInt iFontCapitalAscent;								

	/** The positive distance in pixels from the baseline to

		the top of the highest pre-composed glyph in the font */

	TInt iFontMaxAscent;									

	/** The positive distance in pixels from the baseline to

		the bottom of the lowest ANSI descender (whether or

		not there are ANSI chars in the font)*/

	TInt iFontStandardDescent;								

	/** The positive distance in pixels from the baseline to

		the bottom of the lowest pre-composed glyph in the font */

	TInt iFontMaxDescent;									

	/** The recommended baseline to baseline gap for successive

		lines of text in the font */

	TInt iFontLineGap;										

private:

	const COpenFontGlyph* Glyph(TInt aSessionHandle,TInt aCode) const;

protected:

	/**

	@internalTechnology

	*/

	const COpenFontGlyph* FontCacheGlyph(TInt aCode,COpenFontGlyphTreeEntry**& aNode);

private:	

	const COpenFontGlyph* SessionCacheGlyph(RHeap* aHeap,TInt aSessionHandle,TInt aCode,

											COpenFontSessionCache*& aCache,TInt& aIndex,TBool aCreate) const;

	void RasterizeHelperL(TInt aCode,TOpenFontGlyphData* aGlyphData,TOpenFontGlyphData*& aTempGlyphData);

private:

	COpenFontFile* iFile;									// the file used by this font; null if it has been deleted

															// or cannot be used

	TInt iFaceIndex;										// index of the face in the font file

protected:

	/**

	@internalTechnology

	*/	

	COpenFontGlyphCache* iGlyphCache;						// the per-font glyph cache; owned by the font

private:	

	COpenFontSessionCacheList* iSessionCacheList;			// the list of per-session glyph caches; owned by CFontStore

	TAny* iReserved; // unused; for future expansion

	};

/** Open Font System Extension Interface abstract base class.

COpenFont derivers should also derive from this interface to enable complex

font "shaping".

This interface should be returned by the overridden

COpenFont::ExtendedInterface function when KUidOpenFontShapingExtension is

supplied as the UID.

@see COpenFont

@see KUidOpenFontShapingExtension 

@publishedAll

@released

*/

class MOpenFontShapingExtension

	{

public:

	/** Various font metrics. */

	class TExtensionFontMetrics

		{

	public:

		/** The number of font design units per em. */

		TInt iUnitsPerEm;

		/** The width of the font's em square in pixels. */

		TReal iXPixelsPerEm;

		/** The height of the font's em square in pixels. */

		TReal iYPixelsPerEm;

		/** The horizontal scaling factor from the font's transform;

		the number of horizontal pixels per font unit. */

		TReal iXScaleFactor;

		/** The vertical scaling factor from the font's transform;

		the number of vertical pixels per font unit. */

		TReal iYScaleFactor;

	private:

		/** Reserved for future expansion. */

		TInt iReserved[4];

		};

	/** Creates a bitmap for the specified Glyph code.

	Implementations of this function should put the bitmap in

	aGlyphData->iBitmapBuffer, and the character metrics are placed in

	aGlyphData->iMetricsBuffer. The other parts of aGlyphData should be left

	alone.

	This function provides the same functionality as the

	COpenFont::RasterizeL() except that the glyph code is supplied rather than

	the unicode.

	For more information:

	@see COpenFont::RasterizeL()

	@param aCode

		The glyph code of the character for which the bitmap is required.

	@param aGlyphData

		The function puts its output here.

	*/

	virtual void RasterizeGlyphL(TInt aCode,TOpenFontGlyphData* aGlyphData) = 0;

	/** Maps a character to a glyph index.

	@param aUnicodeCharacter Unicode character code to be mapped.

	@return Glyph code corresponding to aUnicodeCharacter. */

	virtual TInt GlyphIndex(TInt aUnicodeCharacter) const = 0;

	/** Returns the hinted pixel coordinates of a particular point in the

	outline of the given glyph.

	@param aGlyphPoint The glyph index.

	@param aPointNumber The number of the point.

	@param aX Returns the point's X pixel value.

	@param aY Returns the point's Y pixel value.

	@return True on success, false otherwise. */

	virtual TBool GlyphPointInHintedPixels(TInt aGlyphIndex, TInt aPointNumber,

		TReal& aX, TReal& aY) const = 0;

	/** Returns the coordinates of a particular (unhinted) point in the outline

	of the given glyph in font units.

	@param aGlyphPoint The glyph index.

	@param aPointNumber The number of the point.

	@param aX Returns the point's X co-ordinate in font units.

	@param aY Returns the point's Y co-ordinate in font units.

	@return True on success, false otherwise. */

	virtual TBool GlyphPointInFontUnits(TInt aGlyphIndex, TInt aPointNumber,

		TInt& aX, TInt& aY) const = 0;

	/** Returns font metrics.