1. /*

  2.  * @(#)GlyphMetrics.java	1.39 03/01/23

  3.  *

  4.  * Copyright 2003 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. /*

  9.  * (C) Copyright Taligent, Inc. 1996 - 1997, All Rights Reserved

  10.  * (C) Copyright IBM Corp. 1996 - 1998, All Rights Reserved

  11.  *

  12.  * The original version of this source code and documentation is

  13.  * copyrighted and owned by Taligent, Inc., a wholly-owned subsidiary

  14.  * of IBM. These materials are provided under terms of a License

  15.  * Agreement between Taligent and Sun. This technology is protected

  16.  * by multiple US and International patents.

  17.  *

  18.  * This notice and attribution to Taligent may not be removed.

  19.  * Taligent is a registered trademark of Taligent, Inc.

  20.  *

  21.  */

  22. 

  23. package java.awt.font;

  24. 

  25. import java.awt.geom.Rectangle2D;

  26. 

  27. /**

  28.  * The <code>GlyphMetrics</code> class represents infomation for a

  29.  * single glyph.   A glyph is the visual representation of one or more

  30.  * characters.  Many different glyphs can be used to represent a single

  31.  * character or combination of characters.  <code>GlyphMetrics</code>

  32.  * instances are produced by {@link java.awt.Font Font} and are applicable 

  33.  * to a specific glyph in a particular <code>Font</code>.

  34.  * <p>

  35.  * Glyphs are either STANDARD, LIGATURE, COMBINING, or COMPONENT.

  36.  * <ul>

  37.  * <li>STANDARD glyphs are commonly used to represent single characters.

  38.  * <li>LIGATURE glyphs are used to represent sequences of characters.

  39.  * <li>COMPONENT glyphs in a {@link GlyphVector} do not correspond to a

  40.  * particular character in a text model. Instead, COMPONENT glyphs are

  41.  * added for typographical reasons, such as Arabic justification.

  42.  * <li>COMBINING glyphs embellish STANDARD or LIGATURE glyphs, such

  43.  * as accent marks.  Carets do not appear before COMBINING glyphs.

  44.  * </ul>

  45.  * <p>

  46.  * Other metrics available through <code>GlyphMetrics</code> are the

  47.  * components of the advance, the visual bounds, and the left and right

  48.  * side bearings.

  49.  * <p>

  50.  * Glyphs for a rotated font, or obtained from a <code>GlyphVector</code>

  51.  * which has applied a rotation to the glyph, can have advances that

  52.  * contain both X and Y components.  Usually the advance only has one

  53.  * component.

  54.  * <p>

  55.  * The advance of a glyph is the distance from the glyph's origin to the

  56.  * origin of the next glyph along the baseline, which is either vertical

  57.  * or horizontal.  Note that, in a <code>GlyphVector</code>, 

  58.  * the distance from a glyph to its following glyph might not be the 

  59.  * glyph's advance, because of kerning or other positioning adjustments.  

  60.  * <p>

  61.  * The bounds is the smallest rectangle that completely contains the

  62.  * outline of the glyph.  The bounds rectangle is relative to the

  63.  * glyph's origin.  The left-side bearing is the distance from the glyph

  64.  * origin to the left of its bounds rectangle. If the left-side bearing is

  65.  * negative, part of the glyph is drawn to the left of its origin.  The

  66.  * right-side bearing is the distance from the right side of the bounds

  67.  * rectangle to the next glyph origin (the origin plus the advance).  If

  68.  * negative, part of the glyph is drawn to the right of the next glyph's

  69.  * origin.  Note that the bounds does not necessarily enclose all the pixels

  70.  * affected when rendering the glyph, because of rasterization and pixel

  71.  * adjustment effects.

  72.  * <p>

  73.  * Although instances of <code>GlyphMetrics</code> can be directly

  74.  * constructed, they are almost always obtained from a 

  75.  * <code>GlyphVector</code>.  Once constructed, <code>GlyphMetrics</code>

  76.  * objects are immutable.

  77.  * <p>

  78.  * <strong>Example</strong>:<p>

  79.  * Querying a <code>Font</code> for glyph information

  80.  * <blockquote><pre>

  81.  * Font font = ...;

  82.  * int glyphIndex = ...;

  83.  * GlyphMetrics metrics = GlyphVector.getGlyphMetrics(glyphIndex);

  84.  * int isStandard = metrics.isStandard();

  85.  * float glyphAdvance = metrics.getAdvance();

  86.  * </pre></blockquote>

  87.  * @see java.awt.Font

  88.  * @see GlyphVector

  89.  */

  90. 

  91. public final class GlyphMetrics {

  92.     /** 

  93.      * Indicates whether the metrics are for a horizontal or vertical baseline.

  94.      */

  95.     private boolean horizontal;

  96. 

  97.     /**

  98.      * The x-component of the advance. 

  99.      */

  100.     private float advanceX;

  101. 

  102.     /** 

  103.      * The y-component of the advance. 

  104.      */

  105.     private float advanceY;

  106. 

  107.     /**

  108.      * The bounds of the associated glyph.

  109.      */

  110.     private Rectangle2D.Float bounds;

  111. 

  112.     /**

  113.      * Additional information about the glyph encoded as a byte.

  114.      */

  115.     private byte glyphType;

  116. 

  117.     /**

  118.      * Indicates a glyph that represents a single standard

  119.      * character.

  120.      */

  121.     public static final byte STANDARD = 0;

  122. 

  123.     /**

  124.      * Indicates a glyph that represents multiple characters

  125.      * as a ligature, for example 'fi' or 'ffi'.  It is followed by

  126.      * filler glyphs for the remaining characters. Filler and combining

  127.      * glyphs can be intermixed to control positioning of accent marks

  128.      * on the logically preceeding ligature.

  129.      */

  130.     public static final byte LIGATURE = 1;

  131. 

  132.     /**

  133.      * Indicates a glyph that represents a combining character,

  134.      * such as an umlaut.  There is no caret position between this glyph

  135.      * and the preceeding glyph.

  136.      */

  137.     public static final byte COMBINING = 2;

  138. 

  139.     /**

  140.      * Indicates a glyph with no corresponding character in the

  141.      * backing store.  The glyph is associated with the character

  142.      * represented by the logicaly preceeding non-component glyph.  This

  143.      * is used for kashida justification or other visual modifications to

  144.      * existing glyphs.  There is no caret position between this glyph

  145.      * and the preceeding glyph.

  146.      */

  147.     public static final byte COMPONENT = 3;

  148. 

  149.     /**

  150.      * Indicates a glyph with no visual representation. It can

  151.      * be added to the other code values to indicate an invisible glyph.

  152.      */

  153.     public static final byte WHITESPACE = 4;

  154. 

  155.     /**

  156.      * Constructs a <code>GlyphMetrics</code> object.

  157.      * @param advance the advance width of the glyph

  158.      * @param bounds the black box bounds of the glyph

  159.      * @param glyphType the type of the glyph

  160.      */

  161.     public GlyphMetrics(float advance, Rectangle2D bounds, byte glyphType) {

  162. 	this.horizontal = true;

  163.         this.advanceX = advance;

  164. 	this.advanceY = 0;

  165.         this.bounds = new Rectangle2D.Float();

  166.         this.bounds.setRect(bounds);

  167.         this.glyphType = glyphType;

  168.     }

  169. 

  170.     /**

  171.      * Constructs a <code>GlyphMetrics</code> object.

  172.      * @param horizontal if true, metrics are for a horizontal baseline, 

  173.      *   otherwise they are for a vertical baseline

  174.      * @param advanceX the X-component of the glyph's advance

  175.      * @param advanceY the Y-component of the glyph's advance

  176.      * @param bounds the visual bounds of the glyph

  177.      * @param glyphType the type of the glyph

  178.      */

  179.     public GlyphMetrics(boolean horizontal, float advanceX, float advanceY,

  180. 			Rectangle2D bounds, byte glyphType) {

  181. 	

  182. 	this.horizontal = horizontal;

  183.         this.advanceX = advanceX;

  184. 	this.advanceY = advanceY;

  185.         this.bounds = new Rectangle2D.Float();

  186.         this.bounds.setRect(bounds);

  187.         this.glyphType = glyphType;

  188.     }

  189. 

  190.     /**

  191.      * Returns the advance of the glyph along the baseline (either 

  192.      * horizontal or vertical).

  193.      * @return the advance of the glyph

  194.      */

  195.     public float getAdvance() {

  196.         return horizontal ? advanceX : advanceY;

  197.     }

  198. 

  199.     /**

  200.      * Returns the x-component of the advance of the glyph.

  201.      * @return the x-component of the advance of the glyph

  202.      */

  203.     public float getAdvanceX() {

  204.         return advanceX;

  205.     }

  206. 

  207.     /**

  208.      * Returns the y-component of the advance of the glyph.

  209.      * @return the y-component of the advance of the glyph

  210.      */

  211.     public float getAdvanceY() {

  212.         return advanceY;

  213.     }

  214. 

  215.     /**

  216.      * Returns the bounds of the glyph. This is the bounding box of the glyph outline.

  217.      * Because of rasterization and pixel alignment effects, it does not necessarily

  218.      * enclose the pixels that are affected when rendering the glyph.

  219.      * @return a {@link Rectangle2D} that is the bounds of the glyph.

  220.      */

  221.     public Rectangle2D getBounds2D() {

  222.         return new Rectangle2D.Float(bounds.x, bounds.y, bounds.width, bounds.height);

  223.     }

  224. 

  225.     /**

  226.      * Returns the left (top) side bearing of the glyph.

  227.      * <p>

  228.      * This is the distance from 0, 0 to the left (top) of the glyph

  229.      * bounds.  If the bounds of the glyph is to the left of (above) the

  230.      * origin, the LSB is negative.

  231.      * @return the left side bearing of the glyph.

  232.      */

  233.     public float getLSB() {

  234.         return horizontal ? bounds.x : bounds.y;

  235.     }

  236. 

  237.     /**

  238.      * Returns the right (bottom) side bearing of the glyph.

  239.      * <p>

  240.      * This is the distance from the right (bottom) of the glyph bounds to

  241.      * the advance. If the bounds of the glyph is to the right of (below)

  242.      * the advance, the RSB is negative.

  243.      * @return the right side bearing of the glyph.

  244.      */

  245.     public float getRSB() {

  246.         return horizontal ?

  247. 	    advanceX - bounds.x - bounds.width :

  248. 	    advanceY - bounds.y - bounds.height;

  249.     }

  250. 

  251.     /**

  252.      * Returns the raw glyph type code.

  253.      * @return the raw glyph type code.

  254.      */

  255.     public int getType() {

  256.         return glyphType;

  257.     }

  258. 

  259.     /**

  260.      * Returns <code>true</code> if this is a standard glyph.

  261.      * @return <code>true</code> if this is a standard glyph;

  262.      *		<code>false</code> otherwise.

  263.      */

  264.     public boolean isStandard() {

  265.         return (glyphType & 0x3) == STANDARD;

  266.     }

  267. 

  268.     /**

  269.      * Returns <code>true</code> if this is a ligature glyph.

  270.      * @return <code>true</code> if this is a ligature glyph;

  271.      *		<code>false</code> otherwise.

  272.      */

  273.     public boolean isLigature() {

  274.         return (glyphType & 0x3) == LIGATURE;

  275.     }

  276. 

  277.     /**

  278.      * Returns <code>true</code> if this is a combining glyph.

  279.      * @return <code>true</code> if this is a combining glyph;

  280.      *		<code>false</code> otherwise.

  281.      */

  282.     public boolean isCombining() {

  283.         return (glyphType & 0x3) == COMBINING;

  284.     }

  285. 

  286.     /**

  287.      * Returns <code>true</code> if this is a component glyph.

  288.      * @return <code>true</code> if this is a component glyph;

  289.      *		<code>false</code> otherwise.

  290.      */

  291.     public boolean isComponent() {

  292.         return (glyphType & 0x3) == COMPONENT;

  293.     }

  294. 

  295.     /**

  296.      * Returns <code>true</code> if this is a whitespace glyph.

  297.      * @return <code>true</code> if this is a whitespace glyph;

  298.      *		<code>false</code> otherwise.

  299.      */

  300.     public boolean isWhitespace() {

  301.         return (glyphType & 0x4) == WHITESPACE;

  302.     }

  303. }

  304.