source/layout/OpenTypeLayoutEngine.h - incubator-pagespeed-icu - Git at Google

 /*
  * (C) Copyright IBM Corp. 1998-2009 - All Rights Reserved
  *
  */

 #ifndef __OPENTYPELAYOUTENGINE_H
 #define __OPENTYPELAYOUTENGINE_H

 #include "LETypes.h"
 #include "LEGlyphFilter.h"
 #include "LEFontInstance.h"
 #include "LayoutEngine.h"

 #include "GlyphSubstitutionTables.h"
 #include "GlyphDefinitionTables.h"
 #include "GlyphPositioningTables.h"

 U_NAMESPACE_BEGIN

 /**
  * OpenTypeLayoutEngine implements complex text layout for OpenType fonts - that is
  * fonts which have GSUB and GPOS tables associated with them. In order to do this,
  * the glyph processsing step described for LayoutEngine is further broken into three
  * steps:
  *
  * 1) Character processing - this step analyses the characters and assigns a list of OpenType
  *    feature tags to each one. It may also change, remove or add characters, and change
  *    their order.
  *
  * 2) Glyph processing - This step performs character to glyph mapping,and uses the GSUB
  *    table associated with the font to perform glyph substitutions, such as ligature substitution.
  *
  * 3) Glyph post processing - in cases where the font doesn't directly contain a GSUB table,
  *    the previous two steps may have generated "fake" glyph indices to use with a "canned" GSUB
  *    table. This step turns those glyph indices into actual font-specific glyph indices, and may
  *    perform any other adjustments requried by the previous steps.
  *
  * OpenTypeLayoutEngine will also use the font's GPOS table to apply position adjustments
  * such as kerning and accent positioning.
  *
  * @see LayoutEngine
  *
  * @internal
  */
 class U_LAYOUT_API OpenTypeLayoutEngine : public LayoutEngine
 {
 public:
     /**
      * This is the main constructor. It constructs an instance of OpenTypeLayoutEngine for
      * a particular font, script and language. It takes the GSUB table as a parameter since
      * LayoutEngine::layoutEngineFactory has to read the GSUB table to know that it has an
      * OpenType font.
      *
      * @param fontInstance - the font
      * @param scriptCode - the script
      * @param langaugeCode - the language
      * @param gsubTable - the GSUB table
      * @param success - set to an error code if the operation fails
      *
      * @see LayoutEngine::layoutEngineFactory
      * @see ScriptAndLangaugeTags.h for script and language codes
      *
      * @internal
      */
     OpenTypeLayoutEngine(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode,
                             le_int32 typoFlags, const GlyphSubstitutionTableHeader *gsubTable, LEErrorCode &success);

     /**
      * This constructor is used when the font requires a "canned" GSUB table which can't be known
      * until after this constructor has been invoked.
      *
      * @param fontInstance - the font
      * @param scriptCode - the script
      * @param langaugeCode - the language
      * @param success - set to an error code if the operation fails
      *
      * @internal
      */
     OpenTypeLayoutEngine(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode,
 			 le_int32 typoFlags, LEErrorCode &success);

     /**
      * The destructor, virtual for correct polymorphic invocation.
      *
      * @internal
      */
     virtual ~OpenTypeLayoutEngine();

     /**
      * A convenience method used to convert the script code into
      * the four byte script tag required by OpenType.
 	 * For Indic languages where multiple script tags exist,
 	 * the version 1 (old style) tag is returned.
      *
      * @param scriptCode - the script code
      *
      * @return the four byte script tag
      *
      * @internal
      */
     static LETag getScriptTag(le_int32 scriptCode);
     /**
      * A convenience method used to convert the script code into
      * the four byte script tag required by OpenType.
 	 * For Indic languages where multiple script tags exist,
 	 * the version 2 tag is returned.
      *
      * @param scriptCode - the script code
      *
      * @return the four byte script tag
      *
      * @internal
      */
     static LETag getV2ScriptTag(le_int32 scriptCode);

     /**
      * A convenience method used to convert the langauge code into
      * the four byte langauge tag required by OpenType.
      *
      * @param languageCode - the language code
      *
      * @return the four byte language tag
      *
      * @internal
      */
     static LETag getLangSysTag(le_int32 languageCode);

     /**
      * ICU "poor man's RTTI", returns a UClassID for the actual class.
      *
      * @stable ICU 2.8
      */
     virtual UClassID getDynamicClassID() const;

     /**
      * ICU "poor man's RTTI", returns a UClassID for this class.
      *
      * @stable ICU 2.8
      */
     static UClassID getStaticClassID();

     /**
      * The array of language tags, indexed by language code.
      *
      * @internal
      */
     static const LETag languageTags[];

 private:

     /**
      * This method is used by the constructors to convert the script
      * and language codes to four byte tags and save them.
      */
     void setScriptAndLanguageTags();

     /**
      * The array of script tags, indexed by script code.
      */
     static const LETag scriptTags[];

 protected:
     /**
      * A set of "default" features. The default characterProcessing method
      * will apply all of these features to every glyph.
      *
      * @internal
      */
     FeatureMask fFeatureMask;

     /**
      * A set of mappings from feature tags to feature masks. These may
      * be in the order in which the featues should be applied, but they
      * don't need to be.
      *
      * @internal
      */
     const FeatureMap *fFeatureMap;

     /**
      * The length of the feature map.
      *
      * @internal
      */
     le_int32 fFeatureMapCount;

     /**
      * <code>TRUE</code> if the features in the
      * feature map are in the order in which they
      * must be applied.
      *
      * @internal
      */
     le_bool fFeatureOrder;

     /**
      * The address of the GSUB table.
      *
      * @internal
      */
     const GlyphSubstitutionTableHeader *fGSUBTable;

     /**
      * The address of the GDEF table.
      *
      * @internal
      */
     const GlyphDefinitionTableHeader   *fGDEFTable;

     /**
      * The address of the GPOS table.
      *
      * @internal
      */
     const GlyphPositioningTableHeader  *fGPOSTable;

     /**
      * An optional filter used to inhibit substitutions
      * preformed by the GSUB table. This is used for some
      * "canned" GSUB tables to restrict substitutions to
      * glyphs that are in the font.
      *
      * @internal
      */
     LEGlyphFilter *fSubstitutionFilter;

     /**
      * The four byte script tag.
      *
      * @internal
      */
     LETag fScriptTag;

     /**
      * The four byte script tag for V2 fonts.
      *
      * @internal
      */
     LETag fScriptTagV2;

     /**
      * The four byte language tag
      *
      * @internal
      */
     LETag fLangSysTag;

     /**
      * This method does the OpenType character processing. It assigns the OpenType feature
      * tags to the characters, and may generate output characters that differ from the input
      * charcters due to insertions, deletions, or reorderings. In such cases, it will also
      * generate an output character index array reflecting these changes.
      *
      * Subclasses must override this method.
      *
      * Input parameters:
      * @param chars - the input character context
      * @param offset - the index of the first character to process
      * @param count - the number of characters to process
      * @param max - the number of characters in the input context
      * @param rightToLeft - TRUE if the characters are in a right to left directional run
      *
      * Output parameters:
      * @param outChars - the output character array, if different from the input
      * @param charIndices - the output character index array
      * @param featureTags - the output feature tag array
      * @param success - set to an error code if the operation fails
      *
      * @return the output character count (input character count if no change)
      *
      * @internal
      */
     virtual le_int32 characterProcessing(const LEUnicode /*chars*/[], le_int32 offset, le_int32 count, le_int32 max, le_bool /*rightToLeft*/,
             LEUnicode *&/*outChars*/, LEGlyphStorage &glyphStorage, LEErrorCode &success);

     /**
      * This method does character to glyph mapping, and applies the GSUB table. The
      * default implementation calls mapCharsToGlyphs and then applies the GSUB table,
      * if there is one.
      *
      * Note that in the case of "canned" GSUB tables, the output glyph indices may be
      * "fake" glyph indices that need to be converted to "real" glyph indices by the
      * glyphPostProcessing method.
      *
      * Input parameters:
      * @param chars - the input character context
      * @param offset - the index of the first character to process
      * @param count - the number of characters to process
      * @param max - the number of characters in the input context
      * @param rightToLeft - TRUE if the characters are in a right to left directional run
      * @param featureTags - the feature tag array
      *
      * Output parameters:
      * @param glyphs - the output glyph index array
      * @param charIndices - the output character index array
      * @param success - set to an error code if the operation fails
      *
      * @return the number of glyphs in the output glyph index array
      *
      * Note: if the character index array was already set by the characterProcessing
      * method, this method won't change it.
      *
      * @internal
      */
     virtual le_int32 glyphProcessing(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft,
             LEGlyphStorage &glyphStorage, LEErrorCode &success);

     virtual le_int32 glyphSubstitution(le_int32 count, le_int32 max, le_bool rightToLeft, LEGlyphStorage &glyphStorage, LEErrorCode &success);

     /**
      * This method does any processing necessary to convert "fake"
      * glyph indices used by the glyphProcessing method into "real" glyph
      * indices which can be used to render the text. Note that in some
      * cases, such as CDAC Indic fonts, several "real" glyphs may be needed
      * to render one "fake" glyph.
      *
      * The default implementation of this method just returns the input glyph
      * index and character index arrays, assuming that no "fake" glyph indices
      * were needed to do GSUB processing.
      *
      * Input paramters:
      * @param tempGlyphs - the input "fake" glyph index array
      * @param tempCharIndices - the input "fake" character index array
      * @param tempGlyphCount - the number of "fake" glyph indices
      *
      * Output parameters:
      * @param glyphs - the output glyph index array
      * @param charIndices - the output character index array
      * @param success - set to an error code if the operation fails
      *
      * @return the number of glyph indices in the output glyph index array
      *
      * @internal
      */
     virtual le_int32 glyphPostProcessing(LEGlyphStorage &tempGlyphStorage, LEGlyphStorage &glyphStorage, LEErrorCode &success);

     /**
      * This method applies the characterProcessing, glyphProcessing and glyphPostProcessing
      * methods. Most subclasses will not need to override this method.
      *
      * Input parameters:
      * @param chars - the input character context
      * @param offset - the index of the first character to process
      * @param count - the number of characters to process
      * @param max - the number of characters in the input context
      * @param rightToLeft - TRUE if the text is in a right to left directional run
      *
      * Output parameters:
      * @param glyphs - the glyph index array
      * @param charIndices - the character index array
      * @param success - set to an error code if the operation fails
      *
      * @return the number of glyphs in the glyph index array
      *
      * @see LayoutEngine::computeGlyphs
      *
      * @internal
      */
     virtual le_int32 computeGlyphs(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft, LEGlyphStorage &glyphStorage, LEErrorCode &success);

     /**
      * This method uses the GPOS table, if there is one, to adjust the glyph positions.
      *
      * Input parameters:
      * @param glyphs - the input glyph array
      * @param glyphCount - the number of glyphs in the glyph array
      * @param x - the starting X position
      * @param y - the starting Y position
      *
      * Output parameters:
      * @param positions - the output X and Y positions (two entries per glyph)
      * @param success - set to an error code if the operation fails
      *
      * @internal
      */
     virtual void adjustGlyphPositions(const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, LEGlyphStorage &glyphStorage, LEErrorCode &success);

     /**
      * This method frees the feature tag array so that the
      * OpenTypeLayoutEngine can be reused for different text.
      * It is also called from our destructor.
      *
      * @internal
      */
     virtual void reset();
 };

 U_NAMESPACE_END
 #endif
	/*
	* (C) Copyright IBM Corp. 1998-2009 - All Rights Reserved
	*
	*/

	#ifndef __OPENTYPELAYOUTENGINE_H
	#define __OPENTYPELAYOUTENGINE_H

	#include "LETypes.h"
	#include "LEGlyphFilter.h"
	#include "LEFontInstance.h"
	#include "LayoutEngine.h"

	#include "GlyphSubstitutionTables.h"
	#include "GlyphDefinitionTables.h"
	#include "GlyphPositioningTables.h"

	U_NAMESPACE_BEGIN

	/**
	* OpenTypeLayoutEngine implements complex text layout for OpenType fonts - that is
	* fonts which have GSUB and GPOS tables associated with them. In order to do this,
	* the glyph processsing step described for LayoutEngine is further broken into three
	* steps:
	*
	* 1) Character processing - this step analyses the characters and assigns a list of OpenType
	* feature tags to each one. It may also change, remove or add characters, and change
	* their order.
	*
	* 2) Glyph processing - This step performs character to glyph mapping,and uses the GSUB
	* table associated with the font to perform glyph substitutions, such as ligature substitution.
	*
	* 3) Glyph post processing - in cases where the font doesn't directly contain a GSUB table,
	* the previous two steps may have generated "fake" glyph indices to use with a "canned" GSUB
	* table. This step turns those glyph indices into actual font-specific glyph indices, and may
	* perform any other adjustments requried by the previous steps.
	*
	* OpenTypeLayoutEngine will also use the font's GPOS table to apply position adjustments
	* such as kerning and accent positioning.
	*
	* @see LayoutEngine
	*
	* @internal
	*/
	class U_LAYOUT_API OpenTypeLayoutEngine : public LayoutEngine
	{
	public:
	/**
	* This is the main constructor. It constructs an instance of OpenTypeLayoutEngine for
	* a particular font, script and language. It takes the GSUB table as a parameter since
	* LayoutEngine::layoutEngineFactory has to read the GSUB table to know that it has an
	* OpenType font.
	*
	* @param fontInstance - the font
	* @param scriptCode - the script
	* @param langaugeCode - the language
	* @param gsubTable - the GSUB table
	* @param success - set to an error code if the operation fails
	*
	* @see LayoutEngine::layoutEngineFactory
	* @see ScriptAndLangaugeTags.h for script and language codes
	*
	* @internal
	*/
	OpenTypeLayoutEngine(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode,
	le_int32 typoFlags, const GlyphSubstitutionTableHeader *gsubTable, LEErrorCode &success);

	/**
	* This constructor is used when the font requires a "canned" GSUB table which can't be known
	* until after this constructor has been invoked.
	*
	* @param fontInstance - the font
	* @param scriptCode - the script
	* @param langaugeCode - the language
	* @param success - set to an error code if the operation fails
	*
	* @internal
	*/
	OpenTypeLayoutEngine(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode,
	le_int32 typoFlags, LEErrorCode &success);

	/**
	* The destructor, virtual for correct polymorphic invocation.
	*
	* @internal
	*/
	virtual ~OpenTypeLayoutEngine();

	/**
	* A convenience method used to convert the script code into
	* the four byte script tag required by OpenType.
	* For Indic languages where multiple script tags exist,
	* the version 1 (old style) tag is returned.
	*
	* @param scriptCode - the script code
	*
	* @return the four byte script tag
	*
	* @internal
	*/
	static LETag getScriptTag(le_int32 scriptCode);
	/**
	* A convenience method used to convert the script code into
	* the four byte script tag required by OpenType.
	* For Indic languages where multiple script tags exist,
	* the version 2 tag is returned.
	*
	* @param scriptCode - the script code
	*
	* @return the four byte script tag
	*
	* @internal
	*/
	static LETag getV2ScriptTag(le_int32 scriptCode);

	/**
	* A convenience method used to convert the langauge code into
	* the four byte langauge tag required by OpenType.
	*
	* @param languageCode - the language code
	*
	* @return the four byte language tag
	*
	* @internal
	*/
	static LETag getLangSysTag(le_int32 languageCode);

	/**
	* ICU "poor man's RTTI", returns a UClassID for the actual class.
	*
	* @stable ICU 2.8
	*/
	virtual UClassID getDynamicClassID() const;

	/**
	* ICU "poor man's RTTI", returns a UClassID for this class.
	*
	* @stable ICU 2.8
	*/
	static UClassID getStaticClassID();

	/**
	* The array of language tags, indexed by language code.
	*
	* @internal
	*/
	static const LETag languageTags[];

	private:

	/**
	* This method is used by the constructors to convert the script
	* and language codes to four byte tags and save them.
	*/
	void setScriptAndLanguageTags();

	/**
	* The array of script tags, indexed by script code.
	*/
	static const LETag scriptTags[];

	protected:
	/**
	* A set of "default" features. The default characterProcessing method
	* will apply all of these features to every glyph.
	*
	* @internal
	*/
	FeatureMask fFeatureMask;

	/**
	* A set of mappings from feature tags to feature masks. These may
	* be in the order in which the featues should be applied, but they
	* don't need to be.
	*
	* @internal
	*/
	const FeatureMap *fFeatureMap;

	/**
	* The length of the feature map.
	*
	* @internal
	*/
	le_int32 fFeatureMapCount;

	/**
	* <code>TRUE</code> if the features in the
	* feature map are in the order in which they
	* must be applied.
	*
	* @internal
	*/
	le_bool fFeatureOrder;

	/**
	* The address of the GSUB table.
	*
	* @internal
	*/
	const GlyphSubstitutionTableHeader *fGSUBTable;

	/**
	* The address of the GDEF table.
	*
	* @internal
	*/
	const GlyphDefinitionTableHeader *fGDEFTable;

	/**
	* The address of the GPOS table.
	*
	* @internal
	*/
	const GlyphPositioningTableHeader *fGPOSTable;

	/**
	* An optional filter used to inhibit substitutions
	* preformed by the GSUB table. This is used for some
	* "canned" GSUB tables to restrict substitutions to
	* glyphs that are in the font.
	*
	* @internal
	*/
	LEGlyphFilter *fSubstitutionFilter;

	/**
	* The four byte script tag.
	*
	* @internal
	*/
	LETag fScriptTag;

	/**
	* The four byte script tag for V2 fonts.
	*
	* @internal
	*/
	LETag fScriptTagV2;

	/**
	* The four byte language tag
	*
	* @internal
	*/
	LETag fLangSysTag;

	/**
	* This method does the OpenType character processing. It assigns the OpenType feature
	* tags to the characters, and may generate output characters that differ from the input
	* charcters due to insertions, deletions, or reorderings. In such cases, it will also
	* generate an output character index array reflecting these changes.
	*
	* Subclasses must override this method.
	*
	* Input parameters:
	* @param chars - the input character context
	* @param offset - the index of the first character to process
	* @param count - the number of characters to process
	* @param max - the number of characters in the input context
	* @param rightToLeft - TRUE if the characters are in a right to left directional run
	*
	* Output parameters:
	* @param outChars - the output character array, if different from the input
	* @param charIndices - the output character index array
	* @param featureTags - the output feature tag array
	* @param success - set to an error code if the operation fails
	*
	* @return the output character count (input character count if no change)
	*
	* @internal
	*/
	virtual le_int32 characterProcessing(const LEUnicode /chars/[], le_int32 offset, le_int32 count, le_int32 max, le_bool /rightToLeft/,
	LEUnicode &/outChars*/, LEGlyphStorage &glyphStorage, LEErrorCode &success);

	/**
	* This method does character to glyph mapping, and applies the GSUB table. The
	* default implementation calls mapCharsToGlyphs and then applies the GSUB table,
	* if there is one.
	*
	* Note that in the case of "canned" GSUB tables, the output glyph indices may be
	* "fake" glyph indices that need to be converted to "real" glyph indices by the
	* glyphPostProcessing method.
	*
	* Input parameters:
	* @param chars - the input character context
	* @param offset - the index of the first character to process
	* @param count - the number of characters to process
	* @param max - the number of characters in the input context
	* @param rightToLeft - TRUE if the characters are in a right to left directional run
	* @param featureTags - the feature tag array
	*
	* Output parameters:
	* @param glyphs - the output glyph index array
	* @param charIndices - the output character index array
	* @param success - set to an error code if the operation fails
	*
	* @return the number of glyphs in the output glyph index array
	*
	* Note: if the character index array was already set by the characterProcessing
	* method, this method won't change it.
	*
	* @internal
	*/
	virtual le_int32 glyphProcessing(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft,
	LEGlyphStorage &glyphStorage, LEErrorCode &success);

	virtual le_int32 glyphSubstitution(le_int32 count, le_int32 max, le_bool rightToLeft, LEGlyphStorage &glyphStorage, LEErrorCode &success);

	/**
	* This method does any processing necessary to convert "fake"
	* glyph indices used by the glyphProcessing method into "real" glyph
	* indices which can be used to render the text. Note that in some
	* cases, such as CDAC Indic fonts, several "real" glyphs may be needed
	* to render one "fake" glyph.
	*
	* The default implementation of this method just returns the input glyph
	* index and character index arrays, assuming that no "fake" glyph indices
	* were needed to do GSUB processing.
	*
	* Input paramters:
	* @param tempGlyphs - the input "fake" glyph index array
	* @param tempCharIndices - the input "fake" character index array
	* @param tempGlyphCount - the number of "fake" glyph indices
	*
	* Output parameters:
	* @param glyphs - the output glyph index array
	* @param charIndices - the output character index array
	* @param success - set to an error code if the operation fails
	*
	* @return the number of glyph indices in the output glyph index array
	*
	* @internal
	*/
	virtual le_int32 glyphPostProcessing(LEGlyphStorage &tempGlyphStorage, LEGlyphStorage &glyphStorage, LEErrorCode &success);

	/**
	* This method applies the characterProcessing, glyphProcessing and glyphPostProcessing
	* methods. Most subclasses will not need to override this method.
	*
	* Input parameters:
	* @param chars - the input character context
	* @param offset - the index of the first character to process
	* @param count - the number of characters to process
	* @param max - the number of characters in the input context
	* @param rightToLeft - TRUE if the text is in a right to left directional run
	*
	* Output parameters:
	* @param glyphs - the glyph index array
	* @param charIndices - the character index array
	* @param success - set to an error code if the operation fails
	*
	* @return the number of glyphs in the glyph index array
	*
	* @see LayoutEngine::computeGlyphs
	*
	* @internal
	*/
	virtual le_int32 computeGlyphs(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft, LEGlyphStorage &glyphStorage, LEErrorCode &success);

	/**
	* This method uses the GPOS table, if there is one, to adjust the glyph positions.
	*
	* Input parameters:
	* @param glyphs - the input glyph array
	* @param glyphCount - the number of glyphs in the glyph array
	* @param x - the starting X position
	* @param y - the starting Y position
	*
	* Output parameters:
	* @param positions - the output X and Y positions (two entries per glyph)
	* @param success - set to an error code if the operation fails
	*
	* @internal
	*/
	virtual void adjustGlyphPositions(const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, LEGlyphStorage &glyphStorage, LEErrorCode &success);

	/**
	* This method frees the feature tag array so that the
	* OpenTypeLayoutEngine can be reused for different text.
	* It is also called from our destructor.
	*
	* @internal
	*/
	virtual void reset();
	};

	U_NAMESPACE_END
	#endif