Introduction

If you want to draw text in your game, you usually use a BitmapFont. However, there is a downside:

  • BitmapFonts rely on an image, so you have to scale them if you want a different size, which may look ugly.

You could just save a BitmapFont of the biggest size needed in your game then and you never have to scale up, just down, right? Well, that’s true, but such a BitmapFont can easily take up two times as much space on your hard drive as the corresponding TrueType Font (.ttf). Now imagine you have to ship all your big BitmapFonts with your game and your game uses ten different fonts… on an Android device. Bye bye, free storage!

The solution to your problem is the gdx-freetype extension:

  • ship only lightweight .ttf files with your game
  • generate a BitmapFont of your desired size on the fly
  • user might put their own fonts into your game

Tutorial available on LibGDX.info

Details

Since this is an extension, it is not included in your libGDX project by default. How you add the extension differs based on the setup of your project.

How to put gdx-freetype in your project

For Projects Using Gradle

For new projects, simply select the Freetype option under extensions in the setup UI.

To add to an existing Gradle project, see Dependency management with Gradle.

HTML5

GDX Freetype is not compatible with HTML5. However, you may use the gdx-freetype-gwt lib by Intrigus to enable HTML5 functionality. Please follow the instructions here: https://github.com/intrigus/gdx-freetype-gwt

You’re ready to go.

How to use gdx-freetype in code

Using the gdx-freetype extension in your code is really simple.

  1. FreeTypeFontGenerator generator = new FreeTypeFontGenerator(Gdx.files.internal("fonts/myfont.ttf"));
  2. FreeTypeFontParameter parameter = new FreeTypeFontParameter();
  3. parameter.size = 12;
  4. BitmapFont font12 = generator.generateFont(parameter); // font size 12 pixels
  5. generator.dispose(); // don't forget to dispose to avoid memory leaks!

A much simpler way to display your font is by placing your font file in project’s assets folder. You will have to modify the first line of the above code and mention just your font file name in the parameters.

The defaults for the FreeTypeFontParameter:

  1. /** The size in pixels */
  2. public int size = 16;
  3. /** Foreground color (required for non-black borders) */
  4. public Color color = Color.WHITE;
  5. /** Border width in pixels, 0 to disable */
  6. public float borderWidth = 0;
  7. /** Border color; only used if borderWidth > 0 */
  8. public Color borderColor = Color.BLACK;
  9. /** true for straight (mitered), false for rounded borders */
  10. public boolean borderStraight = false;
  11. /** Offset of text shadow on X axis in pixels, 0 to disable */
  12. public int shadowOffsetX = 0;
  13. /** Offset of text shadow on Y axis in pixels, 0 to disable */
  14. public int shadowOffsetY = 0;
  15. /** Shadow color; only used if shadowOffset > 0 */
  16. public Color shadowColor = new Color(0, 0, 0, 0.75f);
  17. /** The characters the font should contain */
  18. public String characters = DEFAULT_CHARS;
  19. /** Whether the font should include kerning */
  20. public boolean kerning = true;
  21. /** The optional PixmapPacker to use */
  22. public PixmapPacker packer = null;
  23. /** Whether to flip the font vertically */
  24. public boolean flip = false;
  25. /** Whether or not to generate mip maps for the resulting texture */
  26. public boolean genMipMaps = false;
  27. /** Minification filter */
  28. public TextureFilter minFilter = TextureFilter.Nearest;
  29. /** Magnification filter */
  30. public TextureFilter magFilter = TextureFilter.Nearest;

If rendering large fonts, the default PixmapPacker page size may be too small. You can provide your own PixmapPacker or use FreeTypeFontGenerator.setMaxTextureSize to set the default page size.

Examples:

  1. parameter.borderColor = Color.BLACK;
  2. parameter.borderWidth = 3;

gdx-freetype - 图1

  1. parameter.shadowColor = Color.BLACK;
  2. parameter.shadowOffsetX = 3;
  3. parameter.shadowOffsetY = 3;

gdx-freetype - 图2

You can also load BitmapFonts generated via the FreeType extension using AssetManager. See FreeTypeFontLoaderTest

latest info about caveats

Quoting from https://web.archive.org/web/20201128081723/https://www.badlogicgames.com/wordpress/?p=2300:

  • Asian scripts “might” work, see caveat above though. They contain just too many glyphs. I’m thinking about ways to fix this.
  • Right-to-left scripts like Arabic are a no-go. The layout “algorithms” in BitmapFont and BitmapFontCache have no idea how to handle that.
  • Throwing just any font at FreeType is not a super awesome idea. Some fonts in the wild are just terrible, with bad or no hinting information and will look like poopoo.

Download an example