path: root/awt/java/awt/font/GlyphVector.java

/*
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
/**
 * @author Ilya S. Okomin
 * @version $Revision$
 */
package java.awt.font;

import java.awt.Font;
import java.awt.font.FontRenderContext;
import java.awt.font.GlyphJustificationInfo;
import java.awt.font.GlyphMetrics;

import java.awt.Rectangle;
import java.awt.Shape;
import java.awt.geom.AffineTransform;
import java.awt.geom.Point2D;
import java.awt.geom.Rectangle2D;

/**
 * The GlyphVector class contains a collection of glyphs with geometric 
 * information and each glyph's location. Each GlyphVector can be associated 
 * with only one Font. GlyphVector contains the following properties for 
 * each glyph:
 * <ul>
 * <li>the glyph position;</li>
 * <li>the transform of the glyph;</li>
 * <li>the metrics of the glyph in the context of the GlyphVector.</li>
 * </ul>
 */
public abstract class GlyphVector implements Cloneable {

    /** 
     * The Constant FLAG_HAS_TRANSFORMS indicates that this GlyphVector 
     * has per-glyph transforms.
     */
    public static final int FLAG_HAS_TRANSFORMS = 1;

    /** 
     * The Constant FLAG_HAS_POSITION_ADJUSTMENTS indicates that 
     * the GlyphVector has per-glyph position adjustments. 
     */
    public static final int FLAG_HAS_POSITION_ADJUSTMENTS = 2;

    /** 
     * The Constant FLAG_RUN_RTL indicates that this GlyphVector has a 
     * right to left run direction.
     */
    public static final int FLAG_RUN_RTL = 4;

    /** 
     * The Constant FLAG_COMPLEX_GLYPHS indicates that this GlyphVector 
     * has a complex glyph to char mapping.
     */
    public static final int FLAG_COMPLEX_GLYPHS = 8;

    /** 
     * The Constant FLAG_MASK indicates a mask for supported flags 
     * from getLayoutFlags.
     */
    public static final int FLAG_MASK = 15; // (|) mask of other flags

    /**
     * Instantiates a new GlyphVector.
     */
    public GlyphVector() {
    }

    /**
     * Gets the pixel bounds of the GlyphVector when rendered
     * at the specified location with the specified FontRenderContext.
     * 
     * @param frc the FontRenderContext.
     * @param x the X coordinate of the GlyphVector's location.
     * @param y the Y coordinate of the GlyphVector's location.
     * 
     * @return the pixel bounds
     */
    public Rectangle getPixelBounds(FontRenderContext frc, float x, float y) {
        // default implementation - integer Rectangle, that encloses visual 
        // bounds rectangle
        Rectangle2D visualRect = getVisualBounds();

        int minX = (int)Math.floor(visualRect.getMinX() + x);
        int minY = (int)Math.floor(visualRect.getMinY() + y);
        int width = (int)Math.ceil(visualRect.getMaxX() + x) - minX;
        int height = (int)Math.ceil(visualRect.getMaxY() + y) - minY;

        return new Rectangle(minX, minY, width, height);
    }

    /**
     * Gets the pixel bounds of the glyph with the specified index in
     * this GlyphVector which is rendered with the specified
     * FontRenderContext at the specified location.
     * 
     * @param index the glyph index in this GlyphVector.
     * @param frc the FontRenderContext.
     * @param x the X coordinate of the GlyphVector's location.
     * @param y the Y coordinate of the GlyphVector's location.
     * 
     * @return a Rectangle bounds.
     */
    public Rectangle getGlyphPixelBounds(int index, FontRenderContext frc, 
            float x, float y) {
        Rectangle2D visualRect = getGlyphVisualBounds(index).getBounds2D();

        int minX = (int)Math.floor(visualRect.getMinX() + x);
        int minY = (int)Math.floor(visualRect.getMinY() + y);
        int width = (int)Math.ceil(visualRect.getMaxX() + x) - minX;
        int height = (int)Math.ceil(visualRect.getMaxY() + y) - minY;

        return new Rectangle(minX, minY, width, height);
    }

    /**
     * Gets the visual bounds of the GlyphVector. 
     * 
     * @return the visual bounds of the GlyphVector.
     */
    public abstract Rectangle2D getVisualBounds();

    /**
     * Gets the logical bounds of the GlyphVector. 
     * 
     * @return the logical bounds of the GlyphVector.
     */
    public abstract Rectangle2D getLogicalBounds();

    /**
     * Sets the position of the specified glyph in this GlyphVector.
     * 
     * @param glyphIndex the glyph index in this GlyphVector.
     * @param newPos the new position of the glyph at the specified glyphIndex.
     */
    public abstract void setGlyphPosition(int glyphIndex, Point2D newPos);

    /**
     * Gets the position of the specified glyph in this GlyphVector.
     * 
     * @param glyphIndex the glyph index in this GlyphVector.
     * 
     * @return the position of the specified glyph in this GlyphVector.
     */
    public abstract Point2D getGlyphPosition(int glyphIndex);

    /**
     * Sets the affine transform to a glyph with the specified index
     * in this GlyphVector.
     * 
     * @param glyphIndex the glyth index in this GlyphVector.
     * @param trans the AffineTransform to be assigned to the
     * specified glyph.
     */
    public abstract void setGlyphTransform(int glyphIndex, 
            AffineTransform trans);

    /**
     * Gets the transform of the specified glyph in this GlyphVector.
     * 
     * @param glyphIndex the glyph index in this GlyphVector.
     * 
     * @return the new transform of the glyph.
     */
    public abstract AffineTransform getGlyphTransform(int glyphIndex);

    /**
     * Compares this GlyphVector with the specified GlyphVector objects.
     * 
     * @param glyphVector the GlyphVector object to be compared.
     * 
     * @return true, if this GlyphVector is equal to the specified GlyphVector
     * object, false otherwise.
     */
    public abstract boolean equals(GlyphVector glyphVector);

    /**
     * Gets the metrics of the glyph with the specified index
     * in this GlyphVector.
     * 
     * @param glyphIndex index in this GlyphVector.
     * 
     * @return the metrics of the glyph with the specified index
     * in this GlyphVector.
     */
    public abstract GlyphMetrics getGlyphMetrics(int glyphIndex);

    /**
     * Gets the justification information of the glyph 
     * whose index is specified.
     * 
     * @param glyphIndex the glyph index.
     * 
     * @return the GlyphJustificationInfo for the specified glyph. 
     */
    public abstract GlyphJustificationInfo getGlyphJustificationInfo(
            int glyphIndex);

    /**
     * Gets the FontRenderContext of this GlyphVector.
     * 
     * @return the FontRenderContext of this GlyphVector.
     */
    public abstract FontRenderContext getFontRenderContext();

    /**
     * Gets a Shape object which defines the visual representation 
     * of the specified glyph in this GlyphVector, translated a 
     * distance of x in the X direction and y in the Y direction. 
     * 
     * @param glyphIndex the glyth index in this GlyphVector.
     * @param x the distance in the X direction to translate the 
     * shape object before returning it.
     * @param y the distance in the Y direction to translate the 
     * shape object before returning it.
     * 
     * @return a Shape object which represents the visual representation 
     * of the specified glyph in this GlyphVector - glyph outline. 
     */
    public Shape getGlyphOutline(int glyphIndex, float x, float y) {
        Shape initialShape = getGlyphOutline(glyphIndex);
        AffineTransform trans = AffineTransform.getTranslateInstance(x, y);
        return trans.createTransformedShape(initialShape);
    }

    /**
     * Gets the visual bounds of the specified glyph in the GlyphVector.
     * 
     * @param glyphIndex the glyph index in this GlyphVector.
     * 
     * @return the glyph visual bounds of the glyph with the specified
     * index in the GlyphVector.
     */
    public abstract Shape getGlyphVisualBounds(int glyphIndex);

    /**
     * Gets a Shape object which defines the visual representation 
     * of the specified glyph in this GlyphVector. 
     *  
     * @param glyphIndex the glyth index in this GlyphVector.
     * 
     * @return a Shape object which represents the visual representation 
     * of the specified glyph in this GlyphVector - glyph outline. 
     */
    public abstract Shape getGlyphOutline(int glyphIndex);

    /**
     * Gets the logical bounds of the specified glyph in 
     * the GlyphVector. 
     * 
     * @param glyphIndex the index in this GlyphVector of the glyph from which 
     * to retrieve its logical bounds
     * 
     * @return the logical bounds of the specified glyph in 
     * the GlyphVector.
     */
    public abstract Shape getGlyphLogicalBounds(int glyphIndex);

    /**
     * Gets the visual representation of this GlyphVector rendered in
     * x, y location as a Shape object.
     * 
     * @param x the x coordinate of the GlyphVector.
     * @param y the y coordinate of the GlyphVector.
     * 
     * @return the visual representation of this GlyphVector as a Shape object.
     */
    public abstract Shape getOutline(float x, float y);

    /**
     * Gets the visual representation of this GlyphVector as a Shape object.
     * 
     * @return the visual representation of this GlyphVector as a Shape object.
     */
    public abstract Shape getOutline();

    /**
     * Gets the font of this GlyphVector.
     * 
     * @return the font of this GlyphVector.
     */
    public abstract Font getFont();

    /**
     * Gets an array of the glyph codes of the specified glyphs.
     * 
     * @param beginGlyphIndex the index into this GlyphVector at which 
     * to start retrieving glyph codes.
     * @param numEntries the number of glyph codes.
     * @param codeReturn the array into which the resulting 
     * glyphcodes will be written.
     * 
     * @return the array of the glyph codes.
     */
    public abstract int[] getGlyphCodes(int beginGlyphIndex, int numEntries, 
            int[] codeReturn);

    /**
     * Gets an array of the character indices of 
     * the specified glyphs.
     * 
     * @param beginGlyphIndex the index of the first glyph to return information for.
     * @param numEntries the number of glyph indices to return.
     * @param codeReturn the array into which the resulting character 
     * indices will be written.
     * 
     * @return an array of character indices for the specifies glyphs.
     */
    public int[] getGlyphCharIndices(int beginGlyphIndex, int numEntries, 
            int[] codeReturn) {
        if (codeReturn == null) {
            codeReturn = new int[numEntries];
        }

        for (int i = 0; i < numEntries; i++){
            codeReturn[i] = getGlyphCharIndex(i+beginGlyphIndex);
        }
        return codeReturn;
    }

    /**
     * Gets an array of the positions of the specified glyphs in 
     * this GlyphVector.
     * 
     * @param beginGlyphIndex the index of the first glyph to return information for.
     * @param numEntries the number of glyphs to return information for.
     * @param positionReturn the array where the result will be stored. 
     * 
     * @return an array of glyph positions.
     */
    public abstract float[] getGlyphPositions(int beginGlyphIndex, 
            int numEntries, float[] positionReturn);

    /**
     * Gets the glyph code of the specified glyph.
     * 
     * @param glyphIndex the index in this GlyphVector which corresponds 
     * to the glyph from which to retrieve the glyphcode.
     * 
     * @return the glyphcode of the specified glyph.
     */
    public abstract int getGlyphCode(int glyphIndex);

    /**
     * Gets the first logical character's index of the specified glyph. 
     *  
     * @param glyphIndex the glyph index.
     * 
     * @return the the first logical character's index.
     */
    public int getGlyphCharIndex(int glyphIndex){
        // default implemetation one-to-one
        return glyphIndex;
    }

    /**
     * Sets default layout to this GlyphVector. 
     */
    public abstract void performDefaultLayout();

    /**
     * Gets the number of glyphs in the GlyphVector.
     * 
     * @return the number of glyphs in the GlyphVector.
     */
    public abstract int getNumGlyphs();

    /**
     * Gets flags which describe the global state of the GlyphVector. 
     * The default implementation returns 0.
     * 
     * @return the layout flags
     */
    public int getLayoutFlags(){
        // default implementation - returned value is 0
        return 0;
    }

}