0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 3171N/A * (C) Copyright IBM Corp. 1998-2007 - All Rights Reserved 1693N/A * \brief C++ API: Layout Engine Font Instance object 0N/A * Instances of this class are used by <code>LEFontInstance::mapCharsToGlyphs</code> and 0N/A * <code>LEFontInstance::mapCharToGlyph</code> to adjust character codes before the character 0N/A * to glyph mapping process. Examples of this are filtering out control characters 0N/A * and character mirroring - replacing a character which has both a left and a right 0N/A * hand form with the opposite form. 0N/A * This method does the adjustments. 0N/A * @param ch - the input character 0N/A * @return the adjusted character 0N/A * This is a forward reference to the class which holds the per-glyph 0N/A * This is a virtual base class that serves as the interface between a LayoutEngine 0N/A * and the platform font environment. It allows a LayoutEngine to access font tables, do 0N/A * character to glyph mapping, and obtain metrics information without knowing any platform 0N/A * specific details. There are also a few utility methods for converting between points, 0N/A * pixels and funits. (font design units) 0N/A * An instance of an <code>LEFontInstance</code> represents a font at a particular point 0N/A * size. Each instance can represent either a single physical font, or a composite font. 0N/A * A composite font is a collection of physical fonts, each of which contains a subset of 0N/A * the characters contained in the composite font. 0N/A * Note: with the exception of <code>getSubFont</code>, the methods in this class only 0N/A * make sense for a physical font. If you have an <code>LEFontInstance</code> which 0N/A * represents a composite font you should only call the methods below which have 0N/A * an <code>LEGlyphID</code>, an <code>LEUnicode</code> or an <code>LEUnicode32</code> 0N/A * as one of the arguments because these can be used to select a particular subfont. 0N/A * Subclasses which implement composite fonts should supply an implementation of these 0N/A * methods with some default behavior such as returning constant values, or using the 0N/A * values from the first subfont. 0N/A * This virtual destructor is here so that the subclass 0N/A * destructors can be invoked through the base class. 0N/A * Get a physical font which can render the given text. For composite fonts, 0N/A * if there is no single physical font which can render all of the text, 0N/A * return a physical font which can render an initial substring of the text, 0N/A * and set the <code>offset</code> parameter to the end of that substring. 0N/A * Internally, the LayoutEngine works with runs of text all in the same 0N/A * font and script, so it is best to call this method with text which is 0N/A * in a single script, passing the script code in as a hint. If you don't 0N/A * know the script of the text, you can use zero, which is the script code 0N/A * for characters used in more than one script. 0N/A * The default implementation of this method is intended for instances of 0N/A * <code>LEFontInstance</code> which represent a physical font. It returns 0N/A * <code>this</code> and indicates that the entire string can be rendered. 0N/A * This method will return a valid <code>LEFontInstance</code> unless you 0N/A * have passed illegal parameters, or an internal error has been encountered. 0N/A * For composite fonts, it may return the warning <code>LE_NO_SUBFONT_WARNING</code> 0N/A * to indicate that the returned font may not be able to render all of 0N/A * the text. Whenever a valid font is returned, the <code>offset</code> parameter 0N/A * will be advanced by at least one. 0N/A * Subclasses which implement composite fonts must override this method. 0N/A * Where it makes sense, they should use the script code as a hint to render 0N/A * characters from the COMMON script in the font which is used for the given 0N/A * script. For example, if the input text is a series of Arabic words separated 0N/A * by spaces, and the script code passed in is <code>arabScriptCode</code> you 0N/A * should return the font used for Arabic characters for all of the input text, 0N/A * including the spaces. If, on the other hand, the input text contains characters 0N/A * which cannot be rendered by the font used for Arabic characters, but which can 0N/A * be rendered by another font, you should return that font for those characters. 0N/A * @param chars - the array of Unicode characters. 0N/A * @param offset - a pointer to the starting offset in the text. On exit this 0N/A * will be set the the limit offset of the text which can be 0N/A * rendered using the returned font. 0N/A * @param limit - the limit offset for the input text. 0N/A * @param script - the script hint. 0N/A * @param success - set to an error code if the arguments are illegal, or no font 0N/A * can be returned for some reason. May also be set to 0N/A * <code>LE_NO_SUBFONT_WARNING</code> if the subfont which 0N/A * was returned cannot render all of the text. 0N/A * @return an <code>LEFontInstance</code> for the sub font which can render the characters, or 0N/A * <code>NULL</code> if there is an error. 0N/A * This method reads a table from the font. Note that in general, 0N/A * it only makes sense to call this method on an <code>LEFontInstance</code> 0N/A * which represents a physical font - i.e. one which has been returned by 0N/A * <code>getSubFont()</code>. This is because each subfont in a composite font 0N/A * will have different tables, and there's no way to know which subfont to access. 0N/A * Subclasses which represent composite fonts should always return <code>NULL</code>. 0N/A * @param tableTag - the four byte table tag. (e.g. 'cmap') 0N/A * @return the address of the table in memory, or <code>NULL</code> 0N/A * if the table doesn't exist. 5891N/A * This method reads a table from the font. Note that in general, 5891N/A * it only makes sense to call this method on an <code>LEFontInstance</code> 5891N/A * which represents a physical font - i.e. one which has been returned by 5891N/A * <code>getSubFont()</code>. This is because each subfont in a composite font 5891N/A * will have different tables, and there's no way to know which subfont to access. 5891N/A * Subclasses which represent composite fonts should always return <code>NULL</code>. 5891N/A * This version sets a length, for range checking. 5891N/A * @param tableTag - the four byte table tag. (e.g. 'cmap') 5891N/A * @param length - ignored on entry, on exit will be the length of the table if known, or -1 if unknown. 5891N/A * @return the address of the table in memory, or <code>NULL</code> 5891N/A * if the table doesn't exist. 0N/A * This method is used to determine if the font can 0N/A * render the given character. This can usually be done 0N/A * by looking the character up in the font's character 0N/A * The default implementation of this method will return 0N/A * <code>TRUE</code> if <code>mapCharToGlyph(ch)</code> 0N/A * returns a non-zero value. 0N/A * @param ch - the character to be tested 0N/A * @return <code>TRUE</code> if the font can render ch. 0N/A * This method returns the number of design units in 0N/A * the font's EM square. 0N/A * @return the number of design units pre EM. 0N/A * This method maps an array of character codes to an array of glyph 0N/A * indices, using the font's character to glyph map. 0N/A * The default implementation iterates over all of the characters and calls 0N/A * <code>mapCharToGlyph(ch, mapper)</code> on each one. It also handles surrogate 0N/A * characters, storing the glyph ID for the high surrogate, and a deleted glyph (0xFFFF) 0N/A * for the low surrogate. 0N/A * Most sublcasses will not need to implement this method. 0N/A * @param chars - the character array 0N/A * @param offset - the index of the first character 0N/A * @param count - the number of characters 0N/A * @param reverse - if <code>TRUE</code>, store the glyph indices in reverse order. 0N/A * @param mapper - the character mapper. 3171N/A * @param filterZeroWidth - <code>TRUE</code> if ZWJ / ZWNJ characters should map to a glyph w/ no contours. 0N/A * @param glyphStorage - the object which contains the output glyph array 3171N/A * This method maps a single character to a glyph index, using the 3171N/A * font's character to glyph map. The default implementation of this 3171N/A * method calls the mapper, and then calls <code>mapCharToGlyph(mappedCh)</code>. 3171N/A * @param ch - the character 3171N/A * @param mapper - the character mapper 3171N/A * @param filterZeroWidth - <code>TRUE</code> if ZWJ / ZWNJ characters should map to a glyph w/ no contours. 0N/A * This method maps a single character to a glyph index, using the 0N/A * font's character to glyph map. The default implementation of this 0N/A * method calls the mapper, and then calls <code>mapCharToGlyph(mappedCh)</code>. 0N/A * @param ch - the character 0N/A * @param mapper - the character mapper 0N/A * @return the glyph index 0N/A * This method maps a single character to a glyph index, using the 0N/A * font's character to glyph map. There is no default implementation 0N/A * of this method because it requires information about the platform 0N/A * font implementation. 0N/A * @param ch - the character 0N/A * @return the glyph index 0N/A * This method gets the X and Y advance of a particular glyph, in pixels. 0N/A * @param glyph - the glyph index 0N/A * @param advance - the X and Y pixel values will be stored here 0N/A * This method gets the hinted X and Y pixel coordinates of a particular 0N/A * point in the outline of the given glyph. 0N/A * @param glyph - the glyph index 0N/A * @param pointNumber - the number of the point 0N/A * @param point - the point's X and Y pixel values will be stored here 0N/A * @return <code>TRUE</code> if the point coordinates could be stored. 0N/A * This method returns the width of the font's EM square 0N/A * @return the pixel width of the EM square 0N/A * This method returns the height of the font's EM square 0N/A * @return the pixel height of the EM square 0N/A * This method converts font design units in the 0N/A * X direction to points. 0N/A * @param xUnits - design units in the X direction 0N/A * @return points in the X direction 0N/A * This method converts font design units in the 0N/A * Y direction to points. 0N/A * @param yUnits - design units in the Y direction 0N/A * @return points in the Y direction 0N/A * This method converts font design units to points. 0N/A * @param units - X and Y design units 0N/A * @param points - set to X and Y points 0N/A * This method converts pixels in the 0N/A * X direction to font design units. 0N/A * @param xPixels - pixels in the X direction 0N/A * @return font design units in the X direction 0N/A * This method converts pixels in the 0N/A * Y direction to font design units. 0N/A * @param yPixels - pixels in the Y direction 0N/A * @return font design units in the Y direction 0N/A * This method converts pixels to font design units. 0N/A * @param pixels - X and Y pixel 0N/A * @param units - set to X and Y font design units 0N/A * Get the X scale factor from the font's transform. The default 0N/A * implementation of <code>transformFunits()</code> will call this method. 0N/A * @return the X scale factor. 0N/A * @see transformFunits 0N/A * Get the Y scale factor from the font's transform. The default 0N/A * implementation of <code>transformFunits()</code> will call this method. 0N/A * @return the Yscale factor. 0N/A * @see transformFunits 0N/A * This method transforms an X, Y point in font design units to a 0N/A * pixel coordinate, applying the font's transform. The default 0N/A * implementation of this method calls <code>getScaleFactorX()</code> 0N/A * and <code>getScaleFactorY()</code>. 0N/A * @param xFunits - the X coordinate in font design units 0N/A * @param yFunits - the Y coordinate in font design units 0N/A * @param pixels - the tranformed co-ordinate in pixels 0N/A * @see getScaleFactorX 0N/A * @see getScaleFactorY 0N/A * This is a convenience method used to convert 0N/A * values in a 16.16 fixed point format to floating point. 0N/A * @param fixed - the fixed point value 0N/A * @return the floating point value 0N/A * This is a convenience method used to convert 0N/A * floating point values to 16.16 fixed point format. 0N/A * @param theFloat - the floating point value 0N/A * @return the fixed point value 0N/A // These methods won't ever be called by the LayoutEngine, 0N/A // but are useful for clients of <code>LEFontInstance</code> who 0N/A // need to render text. 0N/A * Get the font's ascent. 0N/A * @return the font's ascent, in points. This value 0N/A * will always be positive. 0N/A * Get the font's descent. 0N/A * @return the font's descent, in points. This value 0N/A * will always be positive. 0N/A * Get the font's leading. 0N/A * @return the font's leading, in points. This value 0N/A * will always be positive. 0N/A * Get the line height required to display text in 0N/A * this font. The default implementation of this method 0N/A * returns the sum of the ascent, descent, and leading. 0N/A * @return the line height, in points. This vaule will 0N/A * always be positive. 1693N/A * ICU "poor man's RTTI", returns a UClassID for the actual class. 1693N/A * ICU "poor man's RTTI", returns a UClassID for this class.