-
/*
- * %W% %W%
- *
- * (C) Copyright IBM Corp. 1998-2003 - All Rights Reserved
- *
+ * (C) Copyright IBM Corp. and others 1998-2014 - All Rights Reserved
*/
#ifndef __LAYOUTENGINE_H
#define __LAYOUTENGINE_H
-#ifndef __LETYPES_H
#include "LETypes.h"
-#endif
-#include <string.h>
+/**
+ * \file
+ * \brief C++ API: DEPRECATED: Virtual base class for complex text layout.
+ */
U_NAMESPACE_BEGIN
class LEFontInstance;
class LEGlyphFilter;
+class LEGlyphStorage;
/**
+ * NOTE: This class is deprecated, please instead use HarfBuzz.
+ * See: http://www.freedesktop.org/wiki/Software/HarfBuzz/
+ * and http://userguide.icu-project.org/layoutengine
+ *
* This is a virtual base class used to do complex text layout. The text must all
* be in a single font, script, and language. An instance of a LayoutEngine can be
* created by calling the layoutEngineFactory method. Fonts are identified by
* @see LEFontInstance
* @see ScriptAndLanguageTags.h
*
- * @draft ICU 2.2
+ * @deprecated ICU 54. See {@link icu::LayoutEngine}
+ * Instead, please use HarfBuzz.
+ * see http://www.freedesktop.org/wiki/Software/HarfBuzz/
+ * and http://userguide.icu-project.org/layoutengine
*/
class U_LAYOUT_API LayoutEngine : public UObject {
-protected:
- /**
- * The number of glyphs in the output
- *
- * @internal
- */
- le_int32 fGlyphCount;
-
- /**
- * The output glyph array
- *
- * @internal
- */
- LEGlyphID *fGlyphs;
-
- /**
- * The character index array. One entry for each output glyph, giving the index
- * in the input character array of the character which corresponds to this glyph.
- *
- * @internal
- */
- le_int32 *fCharIndices;
+public:
+#ifndef U_HIDE_INTERNAL_API
+ /** @internal Flag to request kerning. Use LE_Kerning_FEATURE_FLAG instead. */
+ static const le_int32 kTypoFlagKern;
+ /** @internal Flag to request ligatures. Use LE_Ligatures_FEATURE_FLAG instead. */
+ static const le_int32 kTypoFlagLiga;
+#endif /* U_HIDE_INTERNAL_API */
+protected:
/**
- * The glyph position array. There are two entries for each glyph giving the
- * X and Y positions of the glyph. Thus, for glyph i, the X position is at index
- * 2i, and the Y position is at index 2i + 1. There are also two entries for the
- * X and Y position of the advance of the last glyph.
+ * The object which holds the glyph storage
*
* @internal
*/
- float *fPositions;
+ LEGlyphStorage *fGlyphStorage;
/**
* The font instance for the text font.
*/
le_int32 fLanguageCode;
+ /**
+ * The typographic control flags
+ *
+ * @internal
+ */
+ le_int32 fTypoFlags;
+
+ /**
+ * <code>TRUE</code> if <code>mapCharsToGlyphs</code> should replace ZWJ / ZWNJ with a glyph
+ * with no contours.
+ *
+ * @internal
+ */
+ le_bool fFilterZeroWidth;
+
+#ifndef U_HIDE_INTERNAL_API
/**
* This constructs an instance for a given font, script and language. Subclass constructors
* must call this constructor.
*
* @param fontInstance - the font for the text
* @param scriptCode - the script for the text
- * @param langaugeCode - the language for the text
+ * @param languageCode - the language for the text
+ * @param typoFlags - the typographic control flags for the text (a bitfield). Use kTypoFlagKern
+ * if kerning is desired, kTypoFlagLiga if ligature formation is desired. Others are reserved.
+ * @param success - set to an error code if the operation fails
*
* @see LEFontInstance
* @see ScriptAndLanguageTags.h
*
* @internal
*/
- LayoutEngine(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode);
-
+ LayoutEngine(const LEFontInstance *fontInstance,
+ le_int32 scriptCode,
+ le_int32 languageCode,
+ le_int32 typoFlags,
+ LEErrorCode &success);
+#endif /* U_HIDE_INTERNAL_API */
+
+ // Do not enclose the protected default constructor with #ifndef U_HIDE_INTERNAL_API
+ // or else the compiler will create a public default constructor.
/**
* This overrides the default no argument constructor to make it
* difficult for clients to call it. Clients are expected to call
*/
LayoutEngine();
+ /**
+ * This method does any required pre-processing to the input characters. It
+ * 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
+ * @param outChars - the output character array, if different from the input
+ * @param glyphStorage - the object that holds the per-glyph storage. The character index array may be set.
+ * @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 the glyph processing. It converts an array of characters
* into an array of glyph indices and character indices. The characters to be
* @param offset - the offset of the first character to process
* @param count - the number of characters to process
* @param max - the number of characters in the context.
- * @param rightToLeft - true if the text is in a right to left directional run
+ * @param rightToLeft - TRUE if the text is in a right to left directional run
+ * @param glyphStorage - the object which holds the per-glyph storage. The glyph and char indices arrays
+ * will be set.
*
* 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
*
* @internal
*/
- virtual le_int32 computeGlyphs(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft, LEGlyphID *&glyphs, le_int32 *&charIndices, LEErrorCode &success);
+ 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 does basic glyph positioning. The default implementation positions
* is not expected that many subclasses will override this method.
*
* Input parameters:
- * @param glyphs - the input glyph array
- * @param glyphCount - the number of glyphs in the glyph array
+ * @param glyphStorage - the object which holds the per-glyph storage. The glyph position array will be set.
* @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 positionGlyphs(const LEGlyphID glyphs[], le_int32 glyphCount, float x, float y, float *&positions, LEErrorCode &success);
+ virtual void positionGlyphs(LEGlyphStorage &glyphStorage, float x, float y, LEErrorCode &success);
/**
* This method does positioning adjustments like accent positioning and
* @param chars - the input character context
* @param offset - the offset of the first character to process
* @param count - the number of characters to process
- * @param reverse - true if the glyphs in the glyph array have been reordered
- * @param glyphs - the input glyph array
- * @param glyphCount - the number of glyphs
- * @param positions - the position array, will be updated as needed
+ * @param reverse - <code>TRUE</code> if the glyphs in the glyph array have been reordered
+ * @param glyphStorage - the object which holds the per-glyph storage. The glyph positions will be
+ * adjusted as needed.
* @param success - output parameter set to an error code if the operation fails
*
- * Note: the positions are passed as a plain array because this method should
- * not need to reallocate them.
- *
* @internal
*/
- virtual void adjustGlyphPositions(const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool /*reverse*/, LEGlyphID glyphs[], le_int32 glyphCount, float positions[], LEErrorCode &success)
- {
- if (LE_FAILURE(success)) {
- return;
- }
-
- if (chars == NULL || glyphs == NULL || positions == NULL || offset < 0 || count < 0 || glyphCount < 0) {
- success = LE_ILLEGAL_ARGUMENT_ERROR;
- return;
- }
-
- // default is no adjustments
- return;
- };
+ virtual void adjustGlyphPositions(const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, LEGlyphStorage &glyphStorage, LEErrorCode &success);
/**
* This method gets a table from the font associated with
* some other way must override this method.
*
* @param tableTag - the four byte table tag.
+ * @param length - length to use
*
* @return the address of the table.
*
* @internal
*/
- virtual const void *getFontTable(LETag tableTag) const;
+ virtual const void *getFontTable(LETag tableTag, size_t &length) const;
+
+ /**
+ * @deprecated ICU 54. See {@link icu::LayoutEngine}
+ */
+ virtual const void *getFontTable(LETag tableTag) const { size_t ignored; return getFontTable(tableTag, ignored); }
/**
* This method does character to glyph mapping. The default implementation
* @param chars - the input character context
* @param offset - the offset of the first character to be mapped
* @param count - the number of characters to be mapped
- * @param reverse - if true, the output will be in reverse order
- * @param mirror - if true, do character mirroring
- *
- * Output parameters:
- * @param glyphs - the glyph array
- * @param charIndices - the character index array
+ * @param reverse - if <code>TRUE</code>, the output will be in reverse order
+ * @param mirror - if <code>TRUE</code>, do character mirroring
+ * @param glyphStorage - the object which holds the per-glyph storage. The glyph and char
+ * indices arrays will be filled in.
* @param success - set to an error code if the operation fails
*
* @see LEFontInstance
*
* @internal
*/
- virtual void mapCharsToGlyphs(const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, le_bool mirror, LEGlyphID *&glyphs, le_int32 *&charIndices, LEErrorCode &success);
+ virtual void mapCharsToGlyphs(const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, le_bool mirror, LEGlyphStorage &glyphStorage, LEErrorCode &success);
+
+#ifndef U_HIDE_INTERNAL_API
+ /**
+ * This is a convenience method that forces the advance width of mark
+ * glyphs to be zero, which is required for proper selection and highlighting.
+ *
+ * @param glyphStorage - the object containing the per-glyph storage. The positions array will be modified.
+ * @param markFilter - used to identify mark glyphs
+ * @param success - output parameter set to an error code if the operation fails
+ *
+ * @see LEGlyphFilter
+ *
+ * @internal
+ */
+ static void adjustMarkGlyphs(LEGlyphStorage &glyphStorage, LEGlyphFilter *markFilter, LEErrorCode &success);
+
/**
* This is a convenience method that forces the advance width of mark
* glyphs to be zero, which is required for proper selection and highlighting.
+ * This method uses the input characters to identify marks. This is required in
+ * cases where the font does not contain enough information to identify them based
+ * on the glyph IDs.
*
- * @param glyphs - the glyph array
- * @param glyphCount - the number of glyphs
- * @param reverse - true if the glyph array has been reordered
+ * @param chars - the array of input characters
+ * @param charCount - the number of input characers
+ * @param glyphStorage - the object containing the per-glyph storage. The positions array will be modified.
+ * @param reverse - <code>TRUE</code> if the glyph array has been reordered
* @param markFilter - used to identify mark glyphs
- * @param positions - the glyph position array - updated as required
* @param success - output parameter set to an error code if the operation fails
*
* @see LEGlyphFilter
*
* @internal
*/
- static void adjustMarkGlyphs(const LEGlyphID glyphs[], le_int32 glyphCount, le_bool reverse, LEGlyphFilter *markFilter, float positions[], LEErrorCode &success);
+ static void adjustMarkGlyphs(const LEUnicode chars[], le_int32 charCount, le_bool reverse, LEGlyphStorage &glyphStorage, LEGlyphFilter *markFilter, LEErrorCode &success);
+#endif /* U_HIDE_INTERNAL_API */
public:
/**
* method. It is declared virtual so that it will be invoked by the
* subclass destructors.
*
- * @draft ICU 2.2
+ * @deprecated ICU 54. See {@link icu::LayoutEngine}
*/
virtual ~LayoutEngine();
/**
* This method will invoke the layout steps in their correct order by calling
- * the computeGlyphs, positionGlyphs and adjustGlyphPosition methods.. It will
+ * the computeGlyphs, positionGlyphs and adjustGlyphPosition methods. It will
* compute the glyph, character index and position arrays.
*
* @param chars - the input character context
* @param offset - the offset 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 characers are in a right to left directional run
+ * @param rightToLeft - TRUE if the characers are in a right to left directional run
* @param x - the initial X position
* @param y - the initial Y position
* @param success - output parameter set to an error code if the operation fails
*
* @return the number of glyphs in the glyph array
*
- * Note; the glyph, character index and position array can be accessed
- * using the getter method below.
+ * Note: The glyph, character index and position array can be accessed
+ * using the getter methods below.
+ *
+ * Note: If you call this method more than once, you must call the reset()
+ * method first to free the glyph, character index and position arrays
+ * allocated by the previous call.
*
- * @draft ICU 2.2
+ * @deprecated ICU 54. See {@link icu::LayoutEngine}
*/
virtual le_int32 layoutChars(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft, float x, float y, LEErrorCode &success);
*
* @return the number of glyphs in the glyph array
*
- * @draft ICU 2.2
+ * @deprecated ICU 54. See {@link icu::LayoutEngine}
*/
- le_int32 getGlyphCount() const
- {
- return fGlyphCount;
- };
+ le_int32 getGlyphCount() const;
/**
* This method copies the glyph array into a caller supplied array.
* @param glyphs - the destiniation glyph array
* @param success - set to an error code if the operation fails
*
- * @draft ICU 2.2
+ * @deprecated ICU 54. See {@link icu::LayoutEngine}
*/
void getGlyphs(LEGlyphID glyphs[], LEErrorCode &success) const;
* @param extraBits - this value will be ORed with each glyph index
* @param success - set to an error code if the operation fails
*
- * @draft ICU 2.2
+ * @deprecated ICU 54. See {@link icu::LayoutEngine}
*/
virtual void getGlyphs(le_uint32 glyphs[], le_uint32 extraBits, LEErrorCode &success) const;
* @param charIndices - the destiniation character index array
* @param success - set to an error code if the operation fails
*
- * @draft ICU 2.2
+ * @deprecated ICU 54. See {@link icu::LayoutEngine}
*/
void getCharIndices(le_int32 charIndices[], LEErrorCode &success) const;
* @param indexBase - an offset which will be added to each index
* @param success - set to an error code if the operation fails
*
- * @draft ICU 2.2
+ * @deprecated ICU 54. See {@link icu::LayoutEngine}
*/
void getCharIndices(le_int32 charIndices[], le_int32 indexBase, LEErrorCode &success) const;
* X and Y position for each glyph, plus an extra X and Y for the
* advance of the last glyph.
*
- * @param glyphs - the destiniation position array
+ * @param positions - the destiniation position array
* @param success - set to an error code if the operation fails
*
- * @draft ICU 2.2
+ * @deprecated ICU 54. See {@link icu::LayoutEngine}
*/
void getGlyphPositions(float positions[], LEErrorCode &success) const;
* @param y - the glyph's Y position
* @param success - set to an error code if the operation fails
*
- * @draft ICU 2.2
+ * @deprecated ICU 54. See {@link icu::LayoutEngine}
*/
void getGlyphPosition(le_int32 glyphIndex, float &x, float &y, LEErrorCode &success) const;
* so that the LayoutEngine can be reused to layout a different
* characer array. (This method is also called by the destructor)
*
- * @draft ICU 2.2
+ * @deprecated ICU 54. See {@link icu::LayoutEngine}
*/
virtual void reset();
*
* @param fontInstance - the font of the text
* @param scriptCode - the script of the text
- * @param langaugeCode - the language of the text
+ * @param languageCode - the language of the text
* @param success - output parameter set to an error code if the operation fails
*
* @return a LayoutEngine which can layout text in the given font.
*
* @see LEFontInstance
*
- * @draft ICU 2.2
+ * @deprecated ICU 54. See {@link icu::LayoutEngine}
*/
static LayoutEngine *layoutEngineFactory(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode, LEErrorCode &success);
+ /**
+ * Override of existing call that provides flags to control typography.
+ * @deprecated ICU 54. See {@link icu::LayoutEngine}
+ */
+ static LayoutEngine *layoutEngineFactory(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode, le_int32 typo_flags, LEErrorCode &success);
+
/**
* ICU "poor man's RTTI", returns a UClassID for the actual class.
*
- * @draft ICU 2.2
+ * @deprecated ICU 54. See {@link icu::LayoutEngine}
*/
- virtual inline UClassID getDynamicClassID() const { return getStaticClassID(); }
+ virtual UClassID getDynamicClassID() const;
/**
* ICU "poor man's RTTI", returns a UClassID for this class.
*
- * @draft ICU 2.2
+ * @deprecated ICU 54. See {@link icu::LayoutEngine}
*/
- static inline UClassID getStaticClassID() { return (UClassID)&fgClassID; }
-
-private:
+ static UClassID getStaticClassID();
- /**
- * The address of this static class variable serves as this class's ID
- * for ICU "poor man's RTTI".
- */
- static const char fgClassID;
};
U_NAMESPACE_END
#endif
-
projects / apple / icu.git / blobdiff