Re: [Fenfire-dev] PEG: move glmosaictext to libvob

[Matti Katila]

On Tue, 23 Sep 2003, Tuomas Lukka wrote:
> =============================================================
> 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.

There are text libraries for opengl and the only user for glMosaicText has 
been fenfire so this is not a real issue, though.


> Changes
> =======

The interfaces you were proposing seemed to be quite useless without 
knowing current implementation details. So jvk might be the only person 
who understands what's going on.

I added some questions below.


> 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;

If t[x.y][0,1] are texture coordinates, what are [x,y][0,1] coordinates?


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

What?? advances = the 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 {

Missing class documentation?

>       // 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);

why need to give num of layers if it can be calculated from the size of 
texUnits array?

> 
>       /** 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.


   -Matti