/*

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

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

* A header for the open font system, which allows SymbianOS

* to use fonts of arbitrary types, including TrueType/OpenType

* and other outline font formats.

*

*/

#ifndef __OPENFONT_H__

#define __OPENFONT_H__

#include <e32base.h>

#include <gdi.h>

#include <ecom/ecom.h>

#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS

#include <linkedfonts.h>

#include <graphics/openfontconstants.h>

#include <graphics/openfontrasterizer.h>

#include <openfontlinkedtypefaceelementspec.h>

#include <graphics/openfontlinkedtypefacespecification.h>

#include <graphics/openfontlinkedtypefaceextension.h>

#endif

class CFont;

class COpenFontFile;

class COpenFontGlyph;

class COpenFontGlyphCache;

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;

class CRasterizerLinkedTypefaceSpecification;

class TLinkedTypefaceSpecificationArgs;

/**

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);

	/** WARNING: Function for internal and partner use ONLY. Compatibility is not guaranteed in future releases.*/

	IMPORT_C void SetBaselineCorrection(TInt aBaselineCorrection);

	IMPORT_C TInt BaselineCorrection();

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

	TInt16 iBaselineCorrection;

	TInt16 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);

	IMPORT_C void  SetGlyphType(TGlyphBitmapType);

	IMPORT_C TGlyphBitmapType GlyphType() const;

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

	TUint16  iGlyphBitmapType;// Glyph bitmap type; TGlyphBitmapType

	TInt16 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.

	};

/**

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();

	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.

	WARNING: Member variable for internal use ONLY. Compatibility is not guaranteed in future releases. Please access using the provided get/set APIs only. 

    */

	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;

	void SetGlyphCache(COpenFontGlyphCache* aGlyphCache);

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

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

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

	COpenFontSessionCacheList* SessionCacheList()const;

    void SetSessionCacheList(COpenFontSessionCacheList* aSessionCacheList);

    void SetFile(COpenFontFile* aFile);

private:

    // Offset from the address of the file used by this font.

    // If the file has been deleted or cannot be used, the offest will be zero.

    TInt iFileOffset;

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

	// Offset from the address of this font of the per-font glyph cache which is owned by the font

    TInt iGlyphCacheOffset;

    // Offset from the address of this font of the list of per-session glyph

    // caches which are owned by CFontStore

    TInt iSessionCacheListOffset;

	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.

	@param aOut Font metrics returned. */

	virtual void GetExtensionFontMetrics(TExtensionFontMetrics& aOut) = 0;

	};

/** TrueType extension for Open Fonts.

If an open font is able to load TrueType or OpenType tables it should derive

from this class.

This class will be used by 

This interface should be returned by the overridden

COpenFont::ExtendedInterface function when KUidOpenFontTrueTypeExtension is

supplied as the UID.

@see	KUidOpenFontTrueTypeExtension

@publishedAll

@released

*/

class MOpenFontTrueTypeExtension

	{

public:

	/** Returns the specified table. The table need not be released by the

	caller, so the deriver is responsible for ensuring that any memory

	allocated is ultimately cleaned up. The caller must not delete or modify

	the data returned.

	@param aError

		Returns KErrNone if successful or one of the system-wide error codes if

		unsuccessful. Returns KErrNotSupported if the table does not exist in

		the font file.

	@param aTag

		The tag of the table, with the first character in the most significant

		byte. For example, the "vhea" table is obtained by passing in 'v'<<24 |

		'h'<<16 | 'e'<<8 | 'a'.

	@param aLength

		The length of the table in bytes that has been returned or 0 if

		unsuccessful.

	@return The table, if successful.

	@see ReleaseTrueTypeTable */

	virtual TAny* GetTrueTypeTable(TInt& aError, TUint32 aTag, TInt* aLength) = 0;

	/** Releases a table obtained by GetTrueTypeTable. The caller must not

	use the table after this call.