/** * Copyright 2010-2023 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 com.jogamp.graph.curve.OutlineShape; import com.jogamp.graph.geom.plane.AffineTransform; import com.jogamp.opengl.math.geom.AABBox; /** * Interface wrapper for font implementation. *

* TrueType Font Specification: *

*

*

* TrueType Font Table Introduction: *

*

*

* Misc.: *

*

*/ 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 https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6vhea.html * Horizontal https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6hhea.html */ public interface Metrics { /** * Distance from baseline of highest ascender, a positive value. * @return ascent in font-units, sourced from `hhea' table. */ int getAscentFU(); /** * Distance from baseline of highest ascender, a positive value. * @return ascent in font em-size [0..1], sourced from `hhea' table. */ float getAscent(); /** * Distance from baseline of lowest descender, a negative value. * @return descent in font-units, sourced from `hhea' table. */ int getDescentFU(); /** * Distance from baseline of lowest descender, a negative value. * @return descend in font em-size [0..1], sourced from `hhea' table. */ float getDescent(); /** * Typographic line gap, a positive value. * @return line-gap in font-units, sourced from `hhea' table. */ int getLineGapFU(); /** * Typographic line gap, a positive value. * @return line-gap in font em-size [0..1], sourced from `hhea' table. */ float getLineGap(); /** * max(lsb + (xMax-xMin)), a positive value. * @return max-extend in font-units, sourced from `hhea' table. */ int getMaxExtendFU(); /** * max(lsb + (xMax-xMin)), a positive value. * @return max-extend in font em-size [0..1], sourced from `hhea' table. */ float getMaxExtend(); /** Returns the font's units per EM from the 'head' table. One em square covers one glyph. */ int getUnitsPerEM(); /** * Return fractional font em-size [0..1], i.e. funits divided by {@link #getUnitsPerEM()}, i.e. * 
         *    return funits / head.unitsPerEM;
         *
* @param funits smallest font unit, where {@link #getUnitsPerEM()} square covers whole glyph * @return fractional font em-size [0..1] */ float getScale(final int funits); /** * @param dest AABBox instance set to this metrics boundary in font-units * @return the given and set AABBox 'dest' in font units */ AABBox getBoundsFU(final AABBox dest); /** * @param dest AABBox instance set to this metrics boundary in font em-size [0..1] * @return the given and set AABBox 'dest' in font units */ AABBox getBounds(final AABBox dest, 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; /** Return this glyph's ID */ int getID(); /** Return the glyph's name, source from `post` table */ String getName(); /** Return true if the underlying {@link #getShape()} is a whitespace, otherwise false. */ boolean isWhiteSpace(); /** * Return the AABBox in font-units, borrowing internal instance. */ AABBox getBoundsFU(); /** * Return the AABBox in font-units, copying into given dest. * @param dest AABBox instance set to this metrics boundary in font-units * @return the given and set AABBox 'dest' in font-units */ AABBox getBoundsFU(final AABBox dest); /** * Return the AABBox in font em-size [0..1], copying into given dest. * @param dest AABBox instance set to this metrics boundary in font em-size [0..1] * @param tmpV3 caller provided temporary 3-component vector * @return the given and set AABBox 'dest' in font em-size [0..1] */ AABBox getBounds(final AABBox dest, float[] tmpV3); /** * Return the AABBox in font em-size [0..1], creating a new copy. */ AABBox getBounds(); /** Return advance in font units, sourced from `hmtx` table. */ int getAdvanceFU(); /** Return advance in font em-size [0..1], sourced from `hmtx` table. */ float getAdvance(); /** Return leftSideBearings in font units, sourced from `hmtx` table. */ int getLeftSideBearingsFU(); /** Return leftSideBearings in font em-size [0..1], sourced from `hmtx` table. */ float getLeftSideBearings(); /** True if kerning values are horizontal, otherwise vertical */ boolean isKerningHorizontal(); /** True if kerning values are perpendicular to text flow, otherwise along with flow */ boolean isKerningCrossstream(); /** Return the number of kerning values stored for this glyph, associated to a right hand glyph. */ int getKerningPairCount(); /** * Returns the optional kerning inter-glyph distance within words between this glyph and the given right glyph_id in font-units. * * @param right_glyphid right glyph code id * @return font-units */ int getKerningFU(final int right_glyphid); /** * Returns the optional kerning inter-glyph distance within words between this glyph and the given right glyph_id in fractional font em-size [0..1]. * * @param right_glyphid right glyph code id * @return fractional font em-size distance [0..1] */ float getKerning(final int right_glyphid); OutlineShape getShape(); @Override int hashCode(); @Override String toString(); /** Return all glyph details as string. */ String fullString(); } /** * General purpose {@link Font.Glyph} visitor. */ public static interface GlyphVisitor { /** * Visiting the given {@link Font.Glyph} having an {@link OutlineShape} with it's corresponding {@link AffineTransform}. * @param glyph {@link Font.Glyph} which contains an {@link OutlineShape} via {@link Font.Glyph#getShape()}. * @param t may be used immediately as is, otherwise a copy shall be made if stored. */ public void visit(final Glyph glyph, final AffineTransform t); } /** * Constrained {@link Font.Glyph} visitor w/o {@link AffineTransform}. */ public static interface GlyphVisitor2 { /** * Visiting the given {@link Font.Glyph} having an {@link OutlineShape}. * @param glyph {@link Font.Glyph} which contains an {@link OutlineShape} via {@link Font.Glyph#getShape()}. */ public void visit(final Glyph glyph); } String getName(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}"

*/ String getFullFamilyName(); StringBuilder getAllNames(final StringBuilder string, final String separator); /** * Returns the hash code based on {@link #NAME_UNIQUNAME}. *

* {@inheritDoc} *

*/ @Override int hashCode(); /** * Returns true if other instance is of same type and {@link #NAME_UNIQUNAME} is equal. *

* {@inheritDoc} *

*/ @Override boolean equals(final Object o); /** * Return advance-width of given glyphID in font-units, sourced from `hmtx` table. * @param glyphID */ int getAdvanceWidthFU(final int glyphID); /** * Return advance-width of given glyphID in font em-size [0..1], sourced from `hmtx` table. * @param glyphID */ float getAdvanceWidth(final int glyphID); Metrics getMetrics(); int getGlyphID(final char symbol); Glyph getGlyph(final int glyph_id); int getNumGlyphs(); /** * Return line height, baseline-to-baseline in font-units, composed from `hhea' table entries. * 
     *   return ascent - descent + linegap;
     *
* or * 
     *   // lineGap positive value
     *   // descent negative value
     *   // ascent positive value
     *   return ascent - descent + linegap;
     *
* @see Metrics#getAscentFU() * @see Metrics#getDescentFU() * @see Metrics#getLineGapFU() */ int getLineHeightFU(); /** * Return line height in font em-size [0..1] */ float getLineHeight(); /** * Returns metric-bounds in font-units. *

* Metric bounds is based on the `hmtx` table's advance of each glyph and `hhea' composed line height. *

*

* For accurate layout consider using {@link #getGlyphBoundsFU(CharSequence)}. *

* @see #getMetricBounds(CharSequence) * @see #getGlyphBoundsFU(CharSequence) */ AABBox getMetricBoundsFU(final CharSequence string); /** * Returns metric-bounds in font em-size. *

* Metric bounds is based on the `hmtx` table's advance of each glyph and `hhea' composed line height. *

*

* For accurate layout consider using {@link #getGlyphBounds(CharSequence)}. *

* @see #getMetricBoundsFU(CharSequence) * @see #getGlyphBounds(CharSequence) * @see #getGlyphShapeBounds(CharSequence) */ AABBox getMetricBounds(final CharSequence string); /** * Try using {@link #getGlyphBounds(CharSequence, AffineTransform, AffineTransform)} to reuse {@link AffineTransform} instances. */ AABBox getGlyphBounds(final CharSequence string); /** * Returns accurate bounding box by taking each glyph's font em-sized bounding box into account. *

* Glyph bounds is based on each glyph's bounding box and `hhea' composed line height. *

* @param string string text * @param tmp1 temp {@link AffineTransform} to be reused * @param tmp2 temp {@link AffineTransform} to be reused * @return the bounding box of the given string in font em-size [0..1] * @see #getGlyphBoundsFU(CharSequence) * @see #getGlyphShapeBounds(CharSequence) * @see #getMetricBounds(CharSequence) */ AABBox getGlyphBounds(final CharSequence string, final AffineTransform tmp1, final AffineTransform tmp2); /** * Try using {@link #getGlyphBoundsFU(CharSequence, AffineTransform, AffineTransform)} to reuse {@link AffineTransform} instances. */ AABBox getGlyphBoundsFU(final CharSequence string); /** * Returns accurate bounding box by taking each glyph's font-units sized bounding box into account. *

* Glyph bounds is based on each glyph's bounding box and `hhea' composed line height. *

* @param string string text * @param tmp1 temp {@link AffineTransform} to be reused * @param tmp2 temp {@link AffineTransform} to be reused * @return the bounding box of the given string in font-units [0..1] * @see #getGlyphBounds(CharSequence) */ AABBox getGlyphBoundsFU(final CharSequence string, final AffineTransform tmp1, final AffineTransform tmp2); /** * Returns accurate bounding box by taking each glyph's font em-sized {@link OutlineShape} into account. *

* Glyph shape bounds is based on each glyph's {@link OutlineShape} and `hhea' composed line height. *

*

* This method is only exposed to validate the produced {@link OutlineShape} against {@link #getGlyphBounds(CharSequence)}. *

* @param transform optional given transform * @param string string text * @return the bounding box of the given string in font-units [0..1] * @see #getGlyphShapeBounds(CharSequence) * @see #getGlyphBounds(CharSequence) * @see #getMetricBounds(CharSequence) */ AABBox getGlyphShapeBounds(final AffineTransform transform, final CharSequence string); /** * Returns accurate bounding box by taking each glyph's font em-sized {@link OutlineShape} into account. *

* Glyph shape bounds is based on each glyph's {@link OutlineShape} and `hhea' composed line height. *

*

* This method is only exposed to validate the produced {@link OutlineShape} against {@link #getGlyphBounds(CharSequence)}. *

* @param string string text * @return the bounding box of the given string in font-units [0..1] * @see #getGlyphShapeBounds(AffineTransform, CharSequence) * @see #getGlyphBounds(CharSequence) * @see #getMetricBounds(CharSequence) */ AABBox getGlyphShapeBounds(final CharSequence string); boolean isPrintableChar(final char c); /** * Try using {@link #processString(GlyphVisitor, AffineTransform, CharSequence, AffineTransform, AffineTransform)} * to reuse {@link AffineTransform} instances. * @see #processString(GlyphVisitor, AffineTransform, CharSequence, AffineTransform, AffineTransform) */ AABBox processString(final Font.GlyphVisitor visitor, final AffineTransform transform, final CharSequence string); /** * Visit each {@link Glyph} and perhaps its {@link OutlineShape} of the string with the {@link Font.GlyphVisitor} * while passing the progressed {@link AffineTransform}. *

* The processed shapes are in font em-size [0..1], but can be adjusted with the given transform, progressed and passed to the visitor. *

* @param visitor handling each {@link Font.Glyph} and perhaps its {@link OutlineShape} in font em-size [0..1] and the given {@link AffineTransform} * @param transform optional given transform for size and position * @param font the target {@link Font} * @param string string text * @param temp1 temporary AffineTransform storage, mandatory * @param temp2 temporary AffineTransform storage, mandatory * @return the bounding box of the given string by taking each glyph's font em-sized [0..1] {@link OutlineShape} into account. * @see #processString(GlyphVisitor, AffineTransform, CharSequence) */ AABBox processString(final Font.GlyphVisitor visitor, final AffineTransform transform, final CharSequence string, final AffineTransform temp1, final AffineTransform temp2); /** * Visit each {@link Glyph} and perhaps its {@link OutlineShape} of the string with the constrained {@link Font.GlyphVisitor2}. *

* The processed shapes are in font em-size [0..1]. *

* @param visitor handling each {@link Font.Glyph} and perhaps its {@link OutlineShape} in font em-size [0..1] * @param string string text */ void processString(final Font.GlyphVisitor2 visitor, final CharSequence string); /** Returns {@link #getFullFamilyName()} */ @Override public String toString(); /** Return all font details as string. */ String fullString(); }