2362N/A * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * This class represents a list of actual renderable glyphs. 0N/A * It can be constructed from a number of text sources, representing 0N/A * the various ways in which a programmer can ask a Graphics2D object 0N/A * to render some text. Once constructed, it provides a way of iterating 0N/A * through the device metrics and graybits of the individual glyphs that 0N/A * need to be rendered to the screen. 0N/A * Note that this class holds pointers to native data which must be 0N/A * disposed. It is not marked as finalizable since it is intended 0N/A * to be very lightweight and finalization is a comparitively expensive 0N/A * procedure. The caller must specifically use try{} finally{} to 0N/A * manually ensure that the object is disposed after use, otherwise 0N/A * native data structures might be leaked. 0N/A * Here is a code sample for using this class: 0N/A * public void drawString(String str, FontInfo info, float x, float y) { 0N/A * GlyphList gl = GlyphList.getInstance(); 0N/A * gl.setFromString(info, str, x, y); 0N/A * int strbounds[] = gl.getBounds(); 0N/A * int numglyphs = gl.getNumGlyphs(); 0N/A * for (int i = 0; i < numglyphs; i++) { 0N/A * gl.setGlyphIndex(i); 0N/A * int metrics[] = gl.getMetrics(); 0N/A * byte bits[] = gl.getGrayBits(); 0N/A * int glyphx = metrics[0]; 0N/A * int glyphy = metrics[1]; 0N/A * int glyphw = metrics[2]; 0N/A * int glyphh = metrics[3]; 0N/A * for (int j = 0; j < glyphh; j++) { 0N/A * for (int i = 0; i < glyphw; i++) { 0N/A * int dx = glyphx + i; 0N/A * int dy = glyphy + j; 0N/A * int alpha = bits[off++]; 0N/A * drawPixel(alpha, dx, dy); 0N/A /* A reference to the strike is needed for the case when the GlyphList 0N/A * may be added to a queue for batch processing, (e.g. OpenGL) and we need 0N/A * to be completely certain that the strike is still valid when the glyphs 0N/A * images are later referenced. This does mean that if such code discards 0N/A * GlyphList and places only the data it contains on the queue, that the 0N/A * strike needs to be part of that data held by a strong reference. 0N/A * In the cases of drawString() and drawChars(), this is a single strike, 0N/A * although it may be a composite strike. In the case of 0N/A * drawGlyphVector() it may be a single strike, or a list of strikes. 0N/A /* In normal usage, the same GlyphList will get recycled, so 0N/A * it makes sense to allocate arrays that will get reused along with 0N/A * it, rather than generating garbage. Garbage will be generated only 0N/A * in MP envts where multiple threads are executing. Throughput should 0N/A * still be higher in those cases. 0N/A /* lcdRGBOrder is used only by LCD text rendering. Its here because 0N/A * the Graphics may have a different hint value than the one used 0N/A * by a GlyphVector, so it has to be stored here - and is obtained 0N/A * from the right FontInfo. Another approach would have been to have 0N/A * install a separate pipe for that case but that's a lot of extra 0N/A * code when a simple boolean will suffice. The overhead to non-LCD 0N/A * text is a redundant boolean assign per call. 0N/A * lcdSubPixPos is used only by LCD text rendering. Its here because 0N/A * the Graphics may have a different hint value than the one used 0N/A * by a GlyphVector, so it has to be stored here - and is obtained 0N/A * from the right FontInfo. Its also needed by the code which 0N/A * calculates glyph positions which already needs to access this 0N/A * GlyphList and would otherwise need the FontInfo. 0N/A * This is true only if LCD text and fractional metrics hints 0N/A * are selected on the graphics. 0N/A * When this is true and the glyph positions as determined by the 0N/A * advances are non-integral, it requests adjustment of the positions. 0N/A * Setting this for surfaces which do not support it through accelerated 0N/A * loops may cause a slow-down as software loops are invoked instead. 0N/A /* This scheme creates a singleton GlyphList which is checked out 0N/A * for use. Callers who find its checked out create one that after use 0N/A * is discarded. This means that in a MT-rendering environment, 0N/A * there's no need to synchronise except for that one instance. 0N/A * Fewer threads will then need to synchronise, perhaps helping 0N/A * throughput on a MP system. If for some reason the reusable 0N/A * GlyphList is checked out for a long time (or never returned?) then 0N/A * we would end up always creating new ones. That situation should not 0N/A * occur and if if did, it would just lead to some extra garbage being 0N/A /* Note len must not be -ve! only setFromChars should be capable 0N/A * of passing down a -ve len, and this guards against it. 0N/A// ensureCapacity(DEFAULT_LENGTH); 0N/A// private GlyphList(int arraylen) { 0N/A// ensureCapacity(arraylen); 0N/A /* The following heuristic is that if the reusable instance is 0N/A * in use, it probably still will be in a micro-second, so avoid 0N/A * synchronising on the class and just allocate a new instance. 0N/A * The cost is one extra boolean test for the normal case, and some 0N/A * small number of cases where we allocate an extra object when 0N/A * in fact the reusable one would be freed very soon. 0N/A /* In some cases the caller may be able to estimate the size of 0N/A * array needed, and it will usually be long enough. This avoids 0N/A * the unnecessary reallocation that occurs if our default 0N/A * values are too small. This is useful because this object 0N/A * will be discarded so the re-allocation overhead is high. 0N/A// public static GlyphList getInstance(int sz) { 0N/A// return new GlyphList(sz); 0N/A// synchronized(GlyphList.class) { 0N/A// return new GlyphList(); 0N/A// return reusableGL; 0N/A /* GlyphList is in an invalid state until setFrom* method is called. 0N/A * After obtaining a new GlyphList it is the caller's responsibility 0N/A * that one of these methods is executed before handing off the 0N/A /* REMIND.Is it worthwhile for the iteration to convert 0N/A * chars to glyph ids to directly map to images? 0N/A /* A GV may be rendered in different Graphics. It is possible it is 0N/A * used for one case where LCD text is available, and another where 0N/A * it is not. Pass in the "info". to ensure get a suitable one. 0N/A // call before ensureCapacity :- 0N/A /* We co-opt the 5 element array that holds per glyph metrics in order 0N/A * to return the bounds. So a caller must copy the data out of the 0N/A * array before calling any other methods on this GlyphList 0N/A /* gposx and gposy are used to accumulate the advance. 0N/A * Add 0.5f for consistent rounding to pixel position. */ 0N/A /* This method now assumes "state", so must be called 0->len 0N/A * The metrics it returns are accumulated on the fly 0N/A * So it could be renamed "nextGlyph()". 0N/A * Note that a laid out GlyphVector which has assigned glyph positions 0N/A * doesn't have this stricture.. 0N/A /* gposx and gposy are used to accumulate the advance */ 0N/A /* unsafe is supposed to be fast, but I doubt if this loop can beat 0N/A * a native call which does a getPrimitiveArrayCritical and a 0N/A * memcpy for the typical amount of image data (30-150 bytes) 0N/A * Consider a native method if there is a performance problem (which 0N/A * I haven't seen so far). 0N/A /* There's a reference equality test overhead here, but it allows us 0N/A * to avoid synchronizing for GL's that will just be GC'd. This 0N/A * helps MP throughput. 0N/A /* The value here is for use by the rendering engine as it reflects 0N/A * the number of glyphs in the array to be blitted. Surrogates pairs 0N/A * may have two slots (the second of these being a dummy entry of the 0N/A * invisible glyph), whereas an application client would expect only 0N/A * one glyph. In other words don't propagate this value up to client code. 0N/A * {dlf} an application client should have _no_ expectations about the 0N/A * number of glyphs per char. This ultimately depends on the font 0N/A * technology and layout process used, which in general clients will 0N/A * know nothing about. 0N/A /* We re-do all this work as we iterate through the glyphs 0N/A * but it seems unavoidable without re-working the Java TextRenderers. 0N/A /* Faster to access local variables in the for loop? */ 0N/A /* floor is safe and correct because all glyph widths, heights 0N/A * and offsets are integers