[Fenfire-dev] PEG: move glmosaictext to libvob

[Tuomas Lukka]

=============================================================
PEG glmosaictext_java--tjl: Move glmosaictext to java
=============================================================

:Author:   Tuomas J. Lukka
:Last-Modified: $Date: 2002/11/14 15:40:07 $
:Revision: $Revision: 1.5 $
:Status:   Current

GLMosaicText is the only external graphics library we use that
encapsulates its own textures. This makes hunting the texture
bug difficult, as well as testing novel techniques 
for e.g. filtering font mipmaps and using stranger texture
encodings.

I propose abandoning glmosaictext and moving the codebase
to Java/C++, through

1) a lightweight JNI interface to the routines of FreeType 
   we need

2) a multi-texture quad renderable using strings and a lookup 
   table (quite like what's in there
   now, but supporting e.g. multiple textures for the font
   properly)

3) Jython / java code to create the font textures and quad
   lists. Specifically, all the mosaic managing code
   would be here.

This *might* impact the startup time *slightly* but after that,
there should be no noticeable performance difference.

Issues
======

- This is kind of a problem - GLMosaicText is something others
  could have used directly while this makes GLMosaicText
  dependent on Libvob. Is this a problem?

    RESOLVED: No. The design pressures from Libvob side
    did already affect GLMosaicText, moving it away from
    the simplest possible solutions. The code will survive,
    just not be maintained.

Changes
=======

GL.Font class and implementations shall be removed. All dependencies
on glmosaictext shall be removed.

FTFont object added to GL, representing a single FTFont (as
in FTFont object in glmosaictext).

Methods ("native" means native as used in GL, i.e. delegated 
to static method with the int id)::

    public native static FTFont createFTFont(String filename);

    /** A freetype font.
     * Not directly renderable - see GLFont for that.
     */
    public class FTFont {
        /** A low-level character measurements routine.
         * Intended to be used by a higher-level wrapper.
         * @return an int array, containing 6*characters.length
         *              elements, in groups of
         *              (x,y,w,h, xadvance, yadvance).
         *              The coordinates are in pixels, and
         *              the advances are in FT fixed point units,
         *              scaled by 2**6.
         */
        public "native" int[] getMeasurements(int[] characters);

        /** Get bitmaps corresponding to a number of characters.
         */
        public "native" byte[][] getBitmaps(int[] characters);
        
    }

Additionally, the mutable QuadFont object for rendering
texture quads based on characters (with *dense* storage), in C++::

    struct QuadFont {

        // Length invariants:
        //    length(textureUnits) == textureLayers
        //    length(textureUnits) == NPAGES * textureLayers
        //    length(textureIndex) == NGLYPHS
        //    length(coordinates) == 8*NGLYPHS
        //    length(advances) == 1*NGLYPHS
        //    min(x in textureIndex) = 0
        //    min(x in textureIndex) < NPAGES

        /** The number of textures to be placed
         * in the texture units.
         */
        int textureLayers;
        /** The texture unit tokens into which
         * the textures are to be placed.
         */
        vector<GLenum> textureUnits;
        /** The actual texture ids.
         * An interleaved vector, with textureLayers
         * textures on the first level.
         */
        vector<GLuint> textures;

        /** The texture indices.
         * Used to index the textures array, with multiplier textureLayers.
         */
        vector<int> textureIndex;

        /** The quad coordinates.
         * These are stored in a single array so we can, in the future,
         * bind and download this to the GPU and just index it,
         * along with a vector of offsets (the cumulative sum of
         * the advances).
         * Stored as groups of 8: x0, y0, x1, y1, tx0, ty0, tx1, ty1.
         */
        vector<float> coordinates;

        /** The advances. Only horizontal text supported here so far.
         */
        vector<float> advances;

        CallGLCode setupCode;
        CallGLCode teardownCode;

        void setUp();

        template<class I> void render(I begin, I end);

        void tearDown();

    }

and in Java (operations mapping to the operations of the preceding class)::

    public class QuadFont {
        // XXX When needed, add the get() methods.

        /** Store explicitly the GL.Texture objects
         * to avoid GC.
         */
        private GL.Texture[] textures;

        /** Set up the textures to use.
         * @param layers The number of textures to be active at a time
         * @param texUnits The names of the texunits to bind textures to.
         *                      length = layers.
         * @param textures The textures. length = layers * number of font pages.
         */
        public "native" void setTextures(int layers, String[] texUnits,
                                    GL.Texture []textures);

        /** Set the measurements of a single glyph.
         * @param glyph The index of the glyph.
         * @param texInds The indices of the textures to be bound
         *                for this glyph. Lenght == layers given to
         *                setTextures.
         */
        public "native" void setMeasurements(int glyph, 
                                int[] texInds,
                                float x0, float y0, float x1, float y1,
                                float tx0, float ty0, float tx1, float ty1,
                                float xadvance, float yadvance);
    }

The Text1Base Vob and its uses is to be replaced by QuadFontTextVob, a vob
using a QuadFont.