com.jogamp.graph.font.Font Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of jogl-all Show documentation
Java™ Binding for the OpenGL® API
The newest version!
/**
// * Copyright 2010 JogAmp Community. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification, are
 * permitted provided that the following conditions are met:
 *
 *    1. Redistributions of source code must retain the above copyright notice, this list of
 *       conditions and the following disclaimer.
 *
 *    2. Redistributions in binary form must reproduce the above copyright notice, this list
 *       of conditions and the following disclaimer in the documentation and/or other materials
 *       provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * The views and conclusions contained in the software and documentation are those of the
 * authors and should not be interpreted as representing official policies, either expressed
 * or implied, of JogAmp Community.
 */
package com.jogamp.graph.font;

import jogamp.graph.geom.plane.AffineTransform;

import com.jogamp.graph.curve.OutlineShape;
import com.jogamp.opengl.math.geom.AABBox;

/**
 * Interface wrapper for font implementation.
 * 
 * TrueType Font Specification:
 * 

 *   http://www.freetype.org/freetype2/documentation.html
 *   http://developer.apple.com/fonts/ttrefman/rm06/Chap6.html
 *   http://www.microsoft.com/typography/SpecificationsOverview.mspx
 *   http://www.microsoft.com/typography/otspec/
 * 
 * 
 * 
 * TrueType Font Table Introduction:
 * 

 *   http://scripts.sil.org/cms/scripts/page.php?item_id=IWS-Chapter08
 * 
 * 
 * 
 * Misc.:
 * 

 *   Treatis on Font Rasterization https://freddie.witherden.org/pages/font-rasterisation/
 *   Glyph Hell http://walon.org/pub/ttf/ttf_glyphs.htm
 * 
 * 
 */

public interface Font {

    /** font name indices for name table */
    public static final int NAME_COPYRIGHT = 0;
    public static final int NAME_FAMILY = 1;
    public static final int NAME_SUBFAMILY = 2;
    public static final int NAME_UNIQUNAME = 3;
    public static final int NAME_FULLNAME = 4;
    public static final int NAME_VERSION = 5;
    public static final int NAME_MANUFACTURER = 8;
    public static final int NAME_DESIGNER = 9;


    /**
     * Metrics for font
     *
     * Depending on the font's direction, horizontal or vertical,
     * the following tables shall be used:
     *
     * Vertical http://developer.apple.com/fonts/TTRefMan/RM06/Chap6vhea.html
     * Horizontal http://developer.apple.com/fonts/TTRefMan/RM06/Chap6hhea.html
     */
    public interface Metrics {
        float getAscent(final float pixelSize);
        float getDescent(final float pixelSize);
        float getLineGap(final float pixelSize);
        float getMaxExtend(final float pixelSize);
        float getScale(final float pixelSize);
        /**
         * @param dest AABBox instance set to this metrics boundary w/ given pixelSize
         * @param pixelSize Use pointSize * resolution for resolution correct pixel-size, see {@link Font#getPixelSize(float, float)}
         * @param tmpV3 caller provided temporary 3-component vector
         * @return the given and set AABBox 'dest'
         */
        AABBox getBBox(final AABBox dest, final float pixelSize, final float[] tmpV3);
    }

    /**
     * Glyph for font
     *
     * http://developer.apple.com/textfonts/TTRefMan/RM06/Chap6cmap.html
     * http://developer.apple.com/textfonts/TTRefMan/RM06/Chap6glyf.html
     * http://www.microsoft.com/typography/otspec/glyf.htm
     */
    public interface Glyph {
        // reserved special glyph IDs
        // http://scripts.sil.org/cms/scripts/page.php?item_id=IWS-Chapter08#ba57949e
        public static final int ID_UNKNOWN = 0;
        public static final int ID_CR = 2;
        public static final int ID_SPACE = 3;

        public Font getFont();
        public char getSymbol();
        public short getID();
        public AABBox getBBox();
        /**
         *
         * @param pixelSize Use pointSize * resolution for resolution correct pixel-size, see {@link Font#getPixelSize(float, float)}
         * @return
         */
        public float getScale(final float pixelSize);
        /**
         * @param dest AABBox instance set to this metrics boundary w/ given pixelSize
         * @param pixelSize Use pointSize * resolution for resolution correct pixel-size, see {@link Font#getPixelSize(float, float)}
         * @param tmpV3 caller provided temporary 3-component vector
         * @return the given and set AABBox 'dest'
         */
        public AABBox getBBox(final AABBox dest, final float pixelSize, float[] tmpV3);
        /**
         *
         * @param pixelSize Use pointSize * resolution for resolution correct pixel-size, see {@link Font#getPixelSize(float, float)}
         * @param useFrationalMetrics
         * @return
         */
        public float getAdvance(final float pixelSize, boolean useFrationalMetrics);
        public OutlineShape getShape();
        public int hashCode();
    }


    public String getName(final int nameIndex);
    public StringBuilder getName(final StringBuilder string, final int nameIndex);

    /** Shall return the family and subfamily name, separated a dash.
     * {@link #getName(StringBuilder, int)} w/ {@link #NAME_FAMILY} and {@link #NAME_SUBFAMILY}
     * Example: "{@code Ubuntu-Regular}"  */
    public StringBuilder getFullFamilyName(final StringBuilder buffer);

    public StringBuilder getAllNames(final StringBuilder string, final String separator);

    /**
     *         Font Scale Formula:
         inch: 25.4 mm
         pointSize: [point] = [1/72 inch]

         [1]      Scale := pointSize * resolution / ( 72 points per inch * units_per_em )
         [2]  PixelSize := pointSize * resolution / ( 72 points per inch )
         [3]      Scale := PixelSize / units_per_em
     * 
     * @param fontSize in point-per-inch
     * @param resolution display resolution in dots-per-inch
     * @return pixel-per-inch, pixelSize scale factor for font operations.
     */
    public float getPixelSize(final float fontSize /* points per inch */, final float resolution);

    /**
     *
     * @param glyphID
     * @param pixelSize Use pointSize * resolution for resolution correct pixel-size, see {@link #getPixelSize(float, float)}
     * @return
     */
    public float getAdvanceWidth(final int glyphID, final float pixelSize);
    public Metrics getMetrics();
    public Glyph getGlyph(final char symbol);
    public int getNumGlyphs();

    /**
     *
     * @param pixelSize Use pointSize * resolution for resolution correct pixel-size, see {@link #getPixelSize(float, float)}
     * @return
     */
    public float getLineHeight(final float pixelSize);
    /**
     *
     * @param string
     * @param pixelSize Use pointSize * resolution for resolution correct pixel-size, see {@link #getPixelSize(float, float)}
     * @return
     */
    public float getMetricWidth(final CharSequence string, final float pixelSize);
    /**
     *
     * @param string
     * @param pixelSize Use pointSize * resolution for resolution correct pixel-size, see {@link #getPixelSize(float, float)}
     * @param tmp
     * @return
     */
    public float getMetricHeight(final CharSequence string, final float pixelSize, final AABBox tmp);
    /**
     * Return the layout bounding box as computed by each glyph's metrics.
     * The result is not pixel correct, bit reflects layout specific metrics.
     * 
     * See {@link #getPointsBounds(AffineTransform, CharSequence, float, AffineTransform, AffineTransform)} for pixel correct results.
     * 
     * @param string string text
     * @param pixelSize Use pointSize * resolution for resolution correct pixel-size, see {@link #getPixelSize(float, float)}
     */
    public AABBox getMetricBounds(final CharSequence string, final float pixelSize);

    /**
     * Return the bounding box by taking each glyph's point-based bounding box into account.
     * @param transform optional given transform
     * @param string string text
     * @param pixelSize Use pointSize * resolution for resolution correct pixel-size, see {@link #getPixelSize(float, float)}
     * @param temp1 temporary AffineTransform storage, mandatory
     * @param temp2 temporary AffineTransform storage, mandatory
     */
    public AABBox getPointsBounds(final AffineTransform transform, final CharSequence string, final float pixelSize,
                                  final AffineTransform temp1, final AffineTransform temp2);

    public boolean isPrintableChar(final char c);

    /** Shall return {@link #getFullFamilyName()} */
    @Override
    public String toString();
}