aboutsummaryrefslogtreecommitdiffstats
path: root/src/jogl/classes/com/jogamp/graph/font/Font.java
blob: 4399bbad7cb77df1c93593d1de6a2d04deb86a83 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
/**
 * 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.
 * <p>
 * TrueType Font Specification:
 * <ul>
 *   <li>http://www.freetype.org/freetype2/documentation.html</li>
 *   <li>https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6.html</li>
 *   <li>http://www.microsoft.com/typography/SpecificationsOverview.mspx</li>
 *   <li>http://www.microsoft.com/typography/otspec/</li>
 * </ul>
 * </p>
 * <p>
 * TrueType Font Table Introduction:
 * <ul>
 *   <li>http://scripts.sil.org/cms/scripts/page.php?item_id=IWS-Chapter08</li>
 * </ul>
 * </p>
 * <p>
 * Misc.:
 * <ul>
 *   <li>Treatis on Font <code>Rasterization https://freddie.witherden.org/pages/font-rasterisation/</code></li>
 *   <li>Glyph Hell <code>http://walon.org/pub/ttf/ttf_glyphs.htm</code></li>
 * </ul>
 * </p>
 */

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.
         * <pre>
         *    return funits / head.unitsPerEM;
         * </pre>
         * @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 the {@link Font} owning this {@link Glyph}. */
        Font getFont();

        /** 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 symbol the character symbol matching the given glyph
         * @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 char symbol, 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 symbol the character symbol matching the given glyph
         * @param glyph {@link Font.Glyph} which contains an {@link OutlineShape} via {@link Font.Glyph#getShape()}.
         */
        public void visit(final char symbol, final Glyph glyph);
    }


    String getName(final int nameIndex);

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

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

    /**
     * Returns the hash code based on {@link #NAME_UNIQUNAME}.
     * <p>
     * {@inheritDoc}
     * </p>
     */
    @Override
    int hashCode();

    /**
     * Returns true if other instance is of same type and {@link #NAME_UNIQUNAME} is equal.
     * <p>
     * {@inheritDoc}
     * </p>
     */
    @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.
     * <pre>
     *   return ascent - descent + linegap;
     * </pre>
     * or
     * <pre>
     *   // lineGap positive value
     *   // descent negative value
     *   // ascent positive value
     *   return ascent - descent + linegap;
     * </pre>
     * @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.
     * <p>
     * Metric bounds is based on the `hmtx` table's advance of each glyph and `hhea' composed line height.
     * </p>
     * <p>
     * For accurate layout consider using {@link #getGlyphBoundsFU(CharSequence)}.
     * </p>
     * @see #getMetricBounds(CharSequence)
     * @see #getGlyphBoundsFU(CharSequence)
     */
    AABBox getMetricBoundsFU(final CharSequence string);

    /**
     * Returns metric-bounds in font em-size.
     * <p>
     * Metric bounds is based on the `hmtx` table's advance of each glyph and `hhea' composed line height.
     * </p>
     * <p>
     * For accurate layout consider using {@link #getGlyphBounds(CharSequence)}.
     * </p>
     * @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.
     * <p>
     * Glyph bounds is based on each glyph's bounding box and `hhea' composed line height.
     * </p>
     * @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.
     * <p>
     * Glyph bounds is based on each glyph's bounding box and `hhea' composed line height.
     * </p>
     * @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.
     * <p>
     * Glyph shape bounds is based on each glyph's {@link OutlineShape} and `hhea' composed line height.
     * </p>
     * <p>
     * This method is only exposed to validate the produced {@link OutlineShape} against {@link #getGlyphBounds(CharSequence)}.
     * </p>
     * @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.
     * <p>
     * Glyph shape bounds is based on each glyph's {@link OutlineShape} and `hhea' composed line height.
     * </p>
     * <p>
     * This method is only exposed to validate the produced {@link OutlineShape} against {@link #getGlyphBounds(CharSequence)}.
     * </p>
     * @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}.
     * <p>
     * The processed shapes are in font em-size [0..1], but can be adjusted with the given transform, progressed and passed to the visitor.
     * </p>
     * @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}.
     * <p>
     * The processed shapes are in font em-size [0..1].
     * </p>
     * @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();
}