1 /*
   2  * Copyright 2007 Sun Microsystems, Inc.  All Rights Reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Sun designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Sun in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
  22  * CA 95054 USA or visit www.sun.com if you need additional information or
  23  * have any questions.
  24  */
  25 
  26 package sun.font;
  27 
  28 import java.awt.geom.GeneralPath;
  29 import java.awt.geom.Point2D;
  30 import java.awt.geom.Rectangle2D;
  31 import java.lang.ref.WeakReference;
  32 import sun.java2d.DisposerRecord;
  33 
  34 /* FontScaler is "internal interface" to font rasterizer library.
  35  *
  36  * Access to native rasterizers without going through this interface is
  37  * strongly discouraged. In particular, this is important because native
  38  * data could be disposed due to runtime font processing error at any time.
  39  *
  40  * FontScaler represents combination of particular rasterizer implementation
  41  * and particular font. It does not include rasterization attributes such as
  42  * transform. These attributes are part of native scalerContext object.
  43  * This approach allows to share same scaler for different requests related
  44  * to the same font file.
  45  *
  46  * Note that scaler may throw FontScalerException on any operation.
  47  * Generally this means that runtime error had happened and scaler is not
  48  * usable.  Subsequent calls to this scaler should not cause crash but will
  49  * likely cause exceptions to be thrown again.
  50  *
  51  * It is recommended that callee should replace its reference to the scaler
  52  * with something else. For instance it could be FontManager.getNullScaler().
  53  * Note that NullScaler is trivial and will not actually rasterize anything.
  54  *
  55  * Alternatively, callee can use more sophisticated error recovery strategies
  56  * and for instance try to substitute failed scaler with new scaler instance
  57  * using another font.
  58  *
  59  * Note that in case of error there is no need to call dispose(). Moreover,
  60  * dispose() generally is called by Disposer thread and explicit calls to
  61  * dispose might have unexpected sideeffects because scaler can be shared.
  62  *
  63  * Current disposing logic is the following:
  64  *   - scaler is registered in the Disposer by the FontManager (on creation)
  65  *   - scalers are disposed when associated Font2D object (e.g. TruetypeFont)
  66  *     is garbage collected. That's why this object implements DisposerRecord
  67  *     interface directly (as it is not used as indicator when it is safe
  68  *     to release native state) and that's why we have to use WeakReference
  69  *     to Font internally.
  70  *   - Majority of Font2D objects are linked from various mapping arrays
  71  *     (e.g. FontManager.localeFullNamesToFont). So, they are not collected.
  72  *     This logic only works for fonts created with Font.createFont()
  73  *
  74  *  Notes:
  75  *   - Eventually we may consider releasing some of the scaler resources if
  76  *     it was not used for a while but we do not want to be too aggressive on
  77  *     this (and this is probably more important for Type1 fonts).
  78  */
  79 public abstract class FontScaler implements DisposerRecord {
  80     protected WeakReference<Font2D> font = null;
  81     protected long nativeScaler = 0; //used by decendants
  82                                      //that have native state
  83     protected boolean disposed = false;
  84 
  85     abstract StrikeMetrics getFontMetrics(long pScalerContext)
  86                 throws FontScalerException;
  87 
  88     abstract float getGlyphAdvance(long pScalerContext, int glyphCode)
  89                 throws FontScalerException;
  90 
  91     abstract void getGlyphMetrics(long pScalerContext, int glyphCode,
  92                                   Point2D.Float metrics)
  93                 throws FontScalerException;
  94 
  95     /*
  96      *  Returns pointer to native GlyphInfo object.
  97      *  Callee is responsible for freeing this memory.
  98      *
  99      *  Note:
 100      *   currently this method has to return not 0L but pointer to valid
 101      *   GlyphInfo object. Because Strike and drawing releated logic does
 102      *   expect that.
 103      *   In the future we may want to rework this to allow 0L here.
 104      */
 105     abstract long getGlyphImage(long pScalerContext, int glyphCode)
 106                 throws FontScalerException;
 107 
 108     abstract Rectangle2D.Float getGlyphOutlineBounds(long pContext,
 109                                                      int glyphCode)
 110                 throws FontScalerException;
 111 
 112     abstract GeneralPath getGlyphOutline(long pScalerContext, int glyphCode,
 113                                          float x, float y)
 114                 throws FontScalerException;
 115 
 116     abstract GeneralPath getGlyphVectorOutline(long pScalerContext, int[] glyphs,
 117                                                int numGlyphs, float x, float y)
 118                 throws FontScalerException;
 119 
 120     /* Used by Java2D disposer to ensure native resources are released.
 121        Note: this method does not release any of created
 122              scaler context objects! */
 123     public void dispose() {}
 124 
 125     /* At the moment these 3 methods are needed for Type1 fonts only.
 126      * For Truetype fonts we extract required info outside of scaler
 127      * on java layer.
 128      */
 129     abstract int getNumGlyphs() throws FontScalerException;
 130     abstract int getMissingGlyphCode() throws FontScalerException;
 131     abstract int getGlyphCode(char charCode) throws FontScalerException;
 132 
 133     /* This method returns table cache used by native layout engine.
 134      * This cache is essentially just small collection of
 135      * pointers to various truetype tables. See definition of TTLayoutTableCache
 136      * in the fontscalerdefs.h for more details.
 137      *
 138      * Note that tables themselves have same format as defined in the truetype
 139      * specification, i.e. font scaler do not need to perform any preprocessing.
 140      *
 141      * Probably it is better to have API to request pointers to each table
 142      * separately instead of requesting pointer to some native structure.
 143      * (then there is not need to share its definition by different
 144      * implementations of scaler).
 145      * However, this means multiple JNI calls and potential impact on performance.
 146      *
 147      * Note: return value 0 is legal.
 148      *   This means tables are not available (e.g. type1 font).
 149      */
 150     abstract long getLayoutTableCache() throws FontScalerException;
 151 
 152     /* Used by the OpenType engine for mark positioning. */
 153     abstract Point2D.Float getGlyphPoint(long pScalerContext,
 154                                 int glyphCode, int ptNumber)
 155         throws FontScalerException;
 156 
 157     abstract long getUnitsPerEm();
 158 
 159     /* Returns pointer to native structure describing rasterization attributes.
 160        Format of this structure is scaler-specific.
 161 
 162        Callee is responsible for freeing scaler context (using free()).
 163 
 164        Note:
 165          Context is tightly associated with strike and it is actually
 166         freed when corresponding strike is being released.
 167      */
 168     abstract long createScalerContext(double[] matrix,
 169                         boolean fontType,
 170                         int aa, int fm,
 171                         float boldness, float italic);
 172 
 173     /* Marks context as invalid because native scaler is invalid.
 174        Notes:
 175          - pointer itself is still valid and has to be released
 176          - if pointer to native scaler was cached it
 177            should not be neither disposed nor used.
 178            it is very likely it is already disposed by this moment. */
 179     abstract void invalidateScalerContext(long ppScalerContext);
 180 }