jME-TTF - Notes
Latest
jME-TTF-v2.2.2.zip: Download
Working with the Texture Atlas

When working with bitmap texts, TrueTypeBMP, it is necessary to consider the texture atlas when requesting new characters. The texture atlas is dynamic, when a character not currently in the atlas is requested the atlas is removed from memory and a new atlas is created with the additional characters. Because of this when requesting text with characters not previously stored in the atlas the texture set on materials for any previously requested text will become out of date, you must reset the texture atlas on the material for each TrueTypeNode and TrueTypeContainer already created.

Rather than update your materials and meshes every time you add text to your scene you can use a AtlasListener to listen for changes in the texture atlas and update your scene there:

AtlasListener atlasListener = new AtlasListener() {
    @Override
    public void mod(AssetManager assetManager, int oldWidth, int oldHeight,
            int newWidth, int newHeight, TrueTypeBMP font) {
        //The atlas texture has been modified, update the texture on your text materials to the new atlas texture here.

        if (oldWidth != newWidth || oldHeight != newHeight)
            //Update your geometries here as the texture has been resized and the UV coordinates have changed. For example TrueTypeContainer.updateGeometry(); or TrueTypeNode.updateGeometry();
    }
}

((TrueTypeBMP)ttf).addAtlasListener(atlasListener);

When you're done with a listener you can remove it via TrueTypeBMP.removeAltasListener(AtlasListener).

It is not always necessary to use AtlasListener's, you may also lock your font to prevent new characters from being added to the texture atlas. When locked the texture atlas will not be updated and thus you will not need to worry about textures becoming out of date. The preferred method for doing this is to load all the characters from a font that you desire to use and then lock the font:

//Request all the characters we want to be able to use.
ttf.getGlyphs("ABCDEFGHIJKLMNOPQRSTUVWXYZ"
    + "abcdefghijklmnopqrstuvwxyz"
    + "0123456789!@#$%^&*()-_+=*/"
    + "\\:;\"<>,.?{}[]|`~'");

ttf.lock(true);


Mesh Anti-Aliasing

By default mesh texts, TrueTypeMesh, use a shader based anti-aliasing method which allows simple anti-aliasing to be done in the shader. Not all mobile devices support the methods required to accomplish this, namely the device must support GL_OES_standard_derivatives. If the device does not support this you will likely want to disable anti-aliasing. This can be done on each node returned from getText or getFormattedText or you can turn it off in the TrueTypeMesh instance:

((TrueTypeMesh)ttf).setAA(false);

Note this will have no effect if you're using a custom material. If you're using a custom material that also uses an anti-aliasing method I recommend you add a "useAA" boolean parameter to your material and use preprocessor commands to determine whether to use the anti-aliasing based on the status of that parameter. If done this way you will be able to turn anti-aliasing on and off via TrueTypeMeshText.setAA(boolean) or TrueTypeMeshContainer.setAA(boolean). TrueTypeMeshText is the TrueTypeNode returned by TrueTypeMesh.getText and TrueTypeMeshContainer is returend by TrueTypeMesh.getFormattedText.


Custom Materials

You can use your own materials on any text, the TrueTypeFont class provides methods for getText and getFormattedText that allow you to supply your own material. When making your own materials it is recommended that you copy the the default shaders to your own shaders and then modify the contents to suit your needs.

Bitmap Text
  • Common/MatDefs/TTF/TTF_Bitmap.j3md
  • Common/MatDefs/TTF/TTF_Bitmap.vert
  • Common/MatDefs/TTF/TTF_Bitmap.frag

Bitmap Outlined
  • Common/MatDefs/TTF/TTF_BitmapOutlined.j3md
  • Common/MatDefs/TTF/TTF_Bitmap.vert
  • Common/MatDefs/TTF/TTF_BitmapOutlined.frag

Mesh
  • Common/MatDefs/TTF/TTF.j3md
  • Common/MatDefs/TTF/TTF_Vert.vert
  • Common/MatDefs/TTF/TTF_Frag.frag

There are three additional UV layers that you can take advantage of to style your texts. For mesh texts UV3 is mapped to each character with (0,0) in the lower left corner and (1,1) in the upper right for each character. UV4 is mapped to each line with (0,0) in the lower left corner and (1,1) in the upper right corner of each line. UV5 is mapped to each text block with (0,0) in the lower left corner and (1,1) in the upper right. For bitmap texts this is essentially the same with the excetpion of being mapped to UV2, UV3 and UV4.
Designed by Adam T. Ryder