2362N/A * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved. 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 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * @author Charlton Innovations, Inc. 0N/A * A <code>GlyphVector</code> object is a collection of glyphs 0N/A * containing geometric information for the placement of each glyph 0N/A * in a transformed coordinate space which corresponds to the 0N/A * device on which the <code>GlyphVector</code> is ultimately 0N/A * The <code>GlyphVector</code> does not attempt any interpretation of 0N/A * the sequence of glyphs it contains. Relationships between adjacent 0N/A * glyphs in sequence are solely used to determine the placement of 0N/A * the glyphs in the visual coordinate space. 0N/A * Instances of <code>GlyphVector</code> are created by a {@link Font}. 0N/A * In a text processing application that can cache intermediate 0N/A * representations of text, creation and subsequent caching of a 0N/A * <code>GlyphVector</code> for use during rendering is the fastest 0N/A * method to present the visual representation of characters to a user. 0N/A * A <code>GlyphVector</code> is associated with exactly one 0N/A * <code>Font</code>, and can provide data useful only in relation to 0N/A * this <code>Font</code>. In addition, metrics obtained from a 0N/A * <code>GlyphVector</code> are not generally geometrically scaleable 0N/A * since the pixelization and spacing are dependent on grid-fitting 0N/A * algorithms within a <code>Font</code>. To facilitate accurate 0N/A * measurement of a <code>GlyphVector</code> and its component 0N/A * glyphs, you must specify a scaling transform, anti-alias mode, and 0N/A * fractional metrics mode when creating the <code>GlyphVector</code>. 0N/A * These characteristics can be derived from the destination device. 0N/A * For each glyph in the <code>GlyphVector</code>, you can obtain: 0N/A * <li>the position of the glyph 0N/A * <li>the transform associated with the glyph 0N/A * <li>the metrics of the glyph in the context of the 0N/A * <code>GlyphVector</code>. The metrics of the glyph may be 0N/A * different under different transforms, application specified 0N/A * rendering hints, and the specific instance of the glyph within 0N/A * the <code>GlyphVector</code>. 0N/A * Altering the data used to create the <code>GlyphVector</code> does not 0N/A * alter the state of the <code>GlyphVector</code>. 0N/A * Methods are provided to adjust the positions of the glyphs 0N/A * within the <code>GlyphVector</code>. These methods are most 0N/A * appropriate for applications that are performing justification 0N/A * operations for the presentation of the glyphs. 0N/A * Methods are provided to transform individual glyphs within the 0N/A * <code>GlyphVector</code>. These methods are primarily useful for 0N/A * Methods are provided to return both the visual, logical, and pixel bounds 0N/A * of the entire <code>GlyphVector</code> or of individual glyphs within 0N/A * the <code>GlyphVector</code>. 0N/A * Methods are provided to return a {@link Shape} for the 0N/A * <code>GlyphVector</code>, and for individual glyphs within the 0N/A * <code>GlyphVector</code>. 0N/A * @author Charlton Innovations, Inc. 0N/A // methods associated with creation-time state 0N/A * Returns the <code>Font</code> associated with this 0N/A * <code>GlyphVector</code>. 0N/A * @return <code>Font</code> used to create this 0N/A * <code>GlyphVector</code>. 0N/A * Returns the {@link FontRenderContext} associated with this 0N/A * <code>GlyphVector</code>. 0N/A * @return <code>FontRenderContext</code> used to create this 0N/A * <code>GlyphVector</code>. 0N/A * @see FontRenderContext 0N/A // methods associated with the GlyphVector as a whole 0N/A * Assigns default positions to each glyph in this 0N/A * <code>GlyphVector</code>. This can destroy information 0N/A * generated during initial layout of this <code>GlyphVector</code>. 0N/A * Returns the number of glyphs in this <code>GlyphVector</code>. 0N/A * @return number of glyphs in this <code>GlyphVector</code>. 0N/A * Returns the glyphcode of the specified glyph. 0N/A * This return value is meaningless to anything other 0N/A * than the <code>Font</code> object that created this 0N/A * <code>GlyphVector</code>. 0N/A * @param glyphIndex the index into this <code>GlyphVector</code> 0N/A * that corresponds to the glyph from which to retrieve the 0N/A * @return the glyphcode of the glyph at the specified 0N/A * <code>glyphIndex</code>. 0N/A * @throws IndexOutOfBoundsException if <code>glyphIndex</code> 0N/A * is less than 0 or greater than or equal to the 0N/A * number of glyphs in this <code>GlyphVector</code> 0N/A * Returns an array of glyphcodes for the specified glyphs. 0N/A * The contents of this return value are meaningless to anything other 0N/A * than the <code>Font</code> used to create this 0N/A * <code>GlyphVector</code>. This method is used 0N/A * for convenience and performance when processing glyphcodes. 0N/A * If no array is passed in, a new array is created. 0N/A * @param beginGlyphIndex the index into this 0N/A * <code>GlyphVector</code> at which to start retrieving glyphcodes 0N/A * @param numEntries the number of glyphcodes to retrieve 0N/A * @param codeReturn the array that receives the glyphcodes and is 0N/A * @return an array of glyphcodes for the specified glyphs. 0N/A * @throws IllegalArgumentException if <code>numEntries</code> is 0N/A * @throws IndexOutOfBoundsException if <code>beginGlyphIndex</code> 0N/A * @throws IndexOutOfBoundsException if the sum of 0N/A * <code>beginGlyphIndex</code> and <code>numEntries</code> is 0N/A * greater than the number of glyphs in this 0N/A * <code>GlyphVector</code> 0N/A * Returns the character index of the specified glyph. 0N/A * The character index is the index of the first logical 0N/A * character represented by the glyph. The default 0N/A * implementation assumes a one-to-one, left-to-right mapping 0N/A * of glyphs to characters. 0N/A * @param glyphIndex the index of the glyph 0N/A * @return the index of the first character represented by the glyph 0N/A * Returns the character indices of the specified glyphs. 0N/A * The character index is the index of the first logical 0N/A * character represented by the glyph. Indices are returned 0N/A * in glyph order. The default implementation invokes 0N/A * getGlyphCharIndex for each glyph, and subclassers will probably 0N/A * want to override this implementation for performance reasons. 0N/A * Use this method for convenience and performance 0N/A * in processing of glyphcodes. If no array is passed in, 0N/A * a new array is created. 0N/A * @param beginGlyphIndex the index of the first glyph 0N/A * @param numEntries the number of glyph indices 0N/A * @param codeReturn the array into which to return the character indices 0N/A * @return an array of character indices, one per glyph. 0N/A * Returns the logical bounds of this <code>GlyphVector</code>. 0N/A * This method is used when positioning this <code>GlyphVector</code> 0N/A * in relation to visually adjacent <code>GlyphVector</code> objects. 0N/A * @return a {@link Rectangle2D} that is the logical bounds of this 0N/A * <code>GlyphVector</code>. 0N/A * Returns the visual bounds of this <code>GlyphVector</code> 0N/A * The visual bounds is the bounding box of the outline of this 0N/A * <code>GlyphVector</code>. Because of rasterization and 0N/A * alignment of pixels, it is possible that this box does not 0N/A * enclose all pixels affected by rendering this <code>GlyphVector</code>. 0N/A * @return a <code>Rectangle2D</code> that is the bounding box 0N/A * of this <code>GlyphVector</code>. 0N/A * Returns the pixel bounds of this <code>GlyphVector</code> when 0N/A * rendered in a graphics with the given 0N/A * <code>FontRenderContext</code> at the given location. The 0N/A * renderFRC need not be the same as the 0N/A * <code>FontRenderContext</code> of this 0N/A * <code>GlyphVector</code>, and can be null. If it is null, the 0N/A * <code>FontRenderContext</code> of this <code>GlyphVector</code> 0N/A * is used. The default implementation returns the visual bounds, 0N/A * offset to x, y and rounded out to the next integer value (i.e. returns an 0N/A * integer rectangle which encloses the visual bounds) and 0N/A * ignores the FRC. Subclassers should override this method. 0N/A * @param renderFRC the <code>FontRenderContext</code> of the <code>Graphics</code>. 0N/A * @param x the x-coordinate at which to render this <code>GlyphVector</code>. 0N/A * @param y the y-coordinate at which to render this <code>GlyphVector</code>. 0N/A * @return a <code>Rectangle</code> bounding the pixels that would be affected. 0N/A * Returns a <code>Shape</code> whose interior corresponds to the 0N/A * visual representation of this <code>GlyphVector</code>. 0N/A * @return a <code>Shape</code> that is the outline of this 0N/A * <code>GlyphVector</code>. 0N/A * Returns a <code>Shape</code> whose interior corresponds to the 0N/A * visual representation of this <code>GlyphVector</code> when 0N/A * rendered at x, y. 0N/A * @param x the X coordinate of this <code>GlyphVector</code>. 0N/A * @param y the Y coordinate of this <code>GlyphVector</code>. 0N/A * @return a <code>Shape</code> that is the outline of this 0N/A * <code>GlyphVector</code> when rendered at the specified 0N/A * Returns a <code>Shape</code> whose interior corresponds to the 0N/A * visual representation of the specified glyph 0N/A * within this <code>GlyphVector</code>. 0N/A * The outline returned by this method is positioned around the 0N/A * origin of each individual glyph. 0N/A * @param glyphIndex the index into this <code>GlyphVector</code> 0N/A * @return a <code>Shape</code> that is the outline of the glyph 0N/A * at the specified <code>glyphIndex</code> of this 0N/A * <code>GlyphVector</code>. 0N/A * @throws IndexOutOfBoundsException if <code>glyphIndex</code> 0N/A * is less than 0 or greater than or equal to the number 0N/A * of glyphs in this <code>GlyphVector</code> 0N/A * Returns a <code>Shape</code> whose interior corresponds to the 0N/A * visual representation of the specified glyph 0N/A * within this <code>GlyphVector</code>, offset to x, y. 0N/A * The outline returned by this method is positioned around the 0N/A * origin of each individual glyph. 0N/A * @param glyphIndex the index into this <code>GlyphVector</code> 0N/A * @param x the X coordinate of the location of this {@code GlyphVector} 0N/A * @param y the Y coordinate of the location of this {@code GlyphVector} 0N/A * @return a <code>Shape</code> that is the outline of the glyph 0N/A * at the specified <code>glyphIndex</code> of this 0N/A * <code>GlyphVector</code> when rendered at the specified 0N/A * @throws IndexOutOfBoundsException if <code>glyphIndex</code> 0N/A * is less than 0 or greater than or equal to the number 0N/A * of glyphs in this <code>GlyphVector</code> 0N/A * Returns the position of the specified glyph relative to the 0N/A * origin of this <code>GlyphVector</code>. 0N/A * If <code>glyphIndex</code> equals the number of of glyphs in 0N/A * this <code>GlyphVector</code>, this method returns the position after 0N/A * the last glyph. This position is used to define the advance of 0N/A * the entire <code>GlyphVector</code>. 0N/A * @param glyphIndex the index into this <code>GlyphVector</code> 0N/A * @return a {@link Point2D} object that is the position of the glyph 0N/A * at the specified <code>glyphIndex</code>. 0N/A * @throws IndexOutOfBoundsException if <code>glyphIndex</code> 0N/A * is less than 0 or greater than the number of glyphs 0N/A * in this <code>GlyphVector</code> 0N/A * @see #setGlyphPosition 0N/A * Sets the position of the specified glyph within this 0N/A * <code>GlyphVector</code>. 0N/A * If <code>glyphIndex</code> equals the number of of glyphs in 0N/A * this <code>GlyphVector</code>, this method sets the position after 0N/A * the last glyph. This position is used to define the advance of 0N/A * the entire <code>GlyphVector</code>. 0N/A * @param glyphIndex the index into this <code>GlyphVector</code> 0N/A * @param newPos the <code>Point2D</code> at which to position the 0N/A * glyph at the specified <code>glyphIndex</code> 0N/A * @throws IndexOutOfBoundsException if <code>glyphIndex</code> 0N/A * is less than 0 or greater than the number of glyphs 0N/A * in this <code>GlyphVector</code> 0N/A * @see #getGlyphPosition 0N/A * Returns the transform of the specified glyph within this 0N/A * <code>GlyphVector</code>. The transform is relative to the 0N/A * glyph position. If no special transform has been applied, 0N/A * <code>null</code> can be returned. A null return indicates 0N/A * an identity transform. 0N/A * @param glyphIndex the index into this <code>GlyphVector</code> 0N/A * @return an {@link AffineTransform} that is the transform of 0N/A * the glyph at the specified <code>glyphIndex</code>. 0N/A * @throws IndexOutOfBoundsException if <code>glyphIndex</code> 0N/A * is less than 0 or greater than or equal to the number 0N/A * of glyphs in this <code>GlyphVector</code> 0N/A * @see #setGlyphTransform 0N/A * Sets the transform of the specified glyph within this 0N/A * <code>GlyphVector</code>. The transform is relative to the glyph 0N/A * position. A <code>null</code> argument for <code>newTX</code> 0N/A * indicates that no special transform is applied for the specified 0N/A * This method can be used to rotate, mirror, translate and scale the 0N/A * glyph. Adding a transform can result in signifant performance changes. 0N/A * @param glyphIndex the index into this <code>GlyphVector</code> 0N/A * @param newTX the new transform of the glyph at <code>glyphIndex</code> 0N/A * @throws IndexOutOfBoundsException if <code>glyphIndex</code> 0N/A * is less than 0 or greater than or equal to the number 0N/A * of glyphs in this <code>GlyphVector</code> 0N/A * @see #getGlyphTransform 0N/A * Returns flags describing the global state of the GlyphVector. 0N/A * Flags not described below are reserved. The default 0N/A * implementation returns 0 (meaning false) for the position adjustments, 0N/A * transforms, rtl, and complex flags. 0N/A * Subclassers should override this method, and make sure 0N/A * it correctly describes the GlyphVector and corresponds 0N/A * to the results of related calls. 0N/A * @return an int containing the flags describing the state 0N/A * @see #FLAG_HAS_POSITION_ADJUSTMENTS 0N/A * @see #FLAG_HAS_TRANSFORMS 0N/A * @see #FLAG_RUN_RTL 0N/A * @see #FLAG_COMPLEX_GLYPHS 0N/A * A flag used with getLayoutFlags that indicates that this <code>GlyphVector</code> has 0N/A * per-glyph transforms. 0N/A * A flag used with getLayoutFlags that indicates that this <code>GlyphVector</code> has 0N/A * position adjustments. When this is true, the glyph positions don't match the 0N/A * accumulated default advances of the glyphs (for example, if kerning has been done). 0N/A * A flag used with getLayoutFlags that indicates that this <code>GlyphVector</code> has 0N/A * a right-to-left run direction. This refers to the glyph-to-char mapping and does 0N/A * not imply that the visual locations of the glyphs are necessarily in this order, 0N/A * although generally they will be. 0N/A * A flag used with getLayoutFlags that indicates that this <code>GlyphVector</code> has 0N/A * a complex glyph-to-char mapping (one that does not map glyphs to chars one-to-one in 0N/A * strictly ascending or descending order matching the run direction). 0N/A * A mask for supported flags from getLayoutFlags. Only bits covered by the mask 0N/A * Returns an array of glyph positions for the specified glyphs. 0N/A * This method is used for convenience and performance when 0N/A * processing glyph positions. 0N/A * If no array is passed in, a new array is created. 0N/A * Even numbered array entries beginning with position zero are the X 0N/A * coordinates of the glyph numbered <code>beginGlyphIndex + position/2</code>. 0N/A * Odd numbered array entries beginning with position one are the Y 0N/A * coordinates of the glyph numbered <code>beginGlyphIndex + (position-1)/2</code>. 0N/A * If <code>beginGlyphIndex</code> equals the number of of glyphs in 0N/A * this <code>GlyphVector</code>, this method gets the position after 0N/A * the last glyph and this position is used to define the advance of 0N/A * the entire <code>GlyphVector</code>. 0N/A * @param beginGlyphIndex the index at which to begin retrieving 0N/A * @param numEntries the number of glyphs to retrieve 0N/A * @param positionReturn the array that receives the glyph positions 0N/A * and is then returned. 0N/A * @return an array of glyph positions specified by 0N/A * <code>beginGlyphIndex</code> and <code>numEntries</code>. 0N/A * @throws IllegalArgumentException if <code>numEntries</code> is 0N/A * @throws IndexOutOfBoundsException if <code>beginGlyphIndex</code> 0N/A * @throws IndexOutOfBoundsException if the sum of 0N/A * <code>beginGlyphIndex</code> and <code>numEntries</code> 0N/A * is greater than the number of glyphs in this 0N/A * <code>GlyphVector</code> plus one 0N/A * Returns the logical bounds of the specified glyph within this 0N/A * <code>GlyphVector</code>. 0N/A * These logical bounds have a total of four edges, with two edges 0N/A * parallel to the baseline under the glyph's transform and the other two 0N/A * edges are shared with adjacent glyphs if they are present. This 0N/A * method is useful for hit-testing of the specified glyph, 0N/A * positioning of a caret at the leading or trailing edge of a glyph, 0N/A * and for drawing a highlight region around the specified glyph. 0N/A * @param glyphIndex the index into this <code>GlyphVector</code> 0N/A * that corresponds to the glyph from which to retrieve its logical 0N/A * @return a <code>Shape</code> that is the logical bounds of the 0N/A * glyph at the specified <code>glyphIndex</code>. 0N/A * @throws IndexOutOfBoundsException if <code>glyphIndex</code> 0N/A * is less than 0 or greater than or equal to the number 0N/A * of glyphs in this <code>GlyphVector</code> 0N/A * @see #getGlyphVisualBounds 0N/A * Returns the visual bounds of the specified glyph within the 0N/A * <code>GlyphVector</code>. 0N/A * The bounds returned by this method is positioned around the 0N/A * origin of each individual glyph. 0N/A * @param glyphIndex the index into this <code>GlyphVector</code> 0N/A * that corresponds to the glyph from which to retrieve its visual 0N/A * @return a <code>Shape</code> that is the visual bounds of the 0N/A * glyph at the specified <code>glyphIndex</code>. 0N/A * @throws IndexOutOfBoundsException if <code>glyphIndex</code> 0N/A * is less than 0 or greater than or equal to the number 0N/A * of glyphs in this <code>GlyphVector</code> 0N/A * @see #getGlyphLogicalBounds 0N/A * Returns the pixel bounds of the glyph at index when this 0N/A * <code>GlyphVector</code> is rendered in a <code>Graphics</code> with the 0N/A * given <code>FontRenderContext</code> at the given location. The 0N/A * renderFRC need not be the same as the 0N/A * <code>FontRenderContext</code> of this 0N/A * <code>GlyphVector</code>, and can be null. If it is null, the 0N/A * <code>FontRenderContext</code> of this <code>GlyphVector</code> 0N/A * is used. The default implementation returns the visual bounds of the glyph, 0N/A * offset to x, y and rounded out to the next integer value, and 0N/A * ignores the FRC. Subclassers should override this method. 0N/A * @param index the index of the glyph. 0N/A * @param renderFRC the <code>FontRenderContext</code> of the <code>Graphics</code>. 0N/A * @param x the X position at which to render this <code>GlyphVector</code>. 0N/A * @param y the Y position at which to render this <code>GlyphVector</code>. 0N/A * @return a <code>Rectangle</code> bounding the pixels that would be affected. 0N/A * Returns the metrics of the glyph at the specified index into 0N/A * this <code>GlyphVector</code>. 0N/A * @param glyphIndex the index into this <code>GlyphVector</code> 0N/A * that corresponds to the glyph from which to retrieve its metrics 0N/A * @return a {@link GlyphMetrics} object that represents the 0N/A * metrics of the glyph at the specified <code>glyphIndex</code> 0N/A * into this <code>GlyphVector</code>. 0N/A * @throws IndexOutOfBoundsException if <code>glyphIndex</code> 0N/A * is less than 0 or greater than or equal to the number 0N/A * of glyphs in this <code>GlyphVector</code> 0N/A * Returns the justification information for the glyph at 0N/A * the specified index into this <code>GlyphVector</code>. 0N/A * @param glyphIndex the index into this <code>GlyphVector</code> 0N/A * that corresponds to the glyph from which to retrieve its 0N/A * justification properties 0N/A * @return a {@link GlyphJustificationInfo} object that 0N/A * represents the justification properties of the glyph at the 0N/A * specified <code>glyphIndex</code> into this 0N/A * <code>GlyphVector</code>. 0N/A * @throws IndexOutOfBoundsException if <code>glyphIndex</code> 0N/A * is less than 0 or greater than or equal to the number 0N/A * of glyphs in this <code>GlyphVector</code> 0N/A // general utility methods 0N/A * Tests if the specified <code>GlyphVector</code> exactly 0N/A * equals this <code>GlyphVector</code>. 0N/A * @param set the specified <code>GlyphVector</code> to test 0N/A * @return <code>true</code> if the specified 0N/A * <code>GlyphVector</code> equals this <code>GlyphVector</code>; 0N/A * <code>false</code> otherwise.