4. Drawing Text

Introduction

This section explains how to draw text on the screen using FreeType (encapsulated) and the built-in SpriteBatch class.

📖 Want to jump right in? Learn with a code example.

Modules

To use the implementations refered on this section you must include the following module(s):

• pixel-core

FreeType

This sub-section contains a bit of information regarding FreeType but feel free to skip ahead as this is fully abstracted by the Pixel API.

FreeType is a software library that facilitates the loading of TrueType, PostScript Type 1/2 or OpenType fonts and provides the meta-data associated to each one. More specifically, it provides font glyph information (character width, advance, bearing, etc) of a given font source.

With the glyph information we can do operations like spacing out characters correctly based on individual properties (characters have unique advacements/width and assigning a constant value to all would appear wrong, visually speaking). In addition, we can use that information to generate bitmap font textures automatically (which we can than use as source to draw the text on the screen).

Example of a font texture:

Sounds complicated? Don't worry, the Pixel framework does this process automatically, it generates an in-memory font texture based on a source file (during the import phase).

Importing Fonts

In order to draw text, the first thing to do is to load a Font into memory which can be done using the ContentManager class:

// ...
private Font font;
// ...
@Override
public void load() {
    // ...
    font = content.load("<your_font_path>", Font.class);
    font.setFontSize(16); // (optional - when you change font size the font texture is automatically computed)
    // ...
}

• Pixel can import all the FreeType supported fonts (TrueType, PostScript Type 1/2 or OpenType).
• By default, the font is created with a 32 base font size, you can adjust it to fit your needs.
• You don't need to individually create a font instance per each font-size you need, down-scaling typically works fine in this scenario (tweek around and see if it fits your requirements).
• You can save the computed font texture to the filesystem by using either of functions font.saveAsPng() or font.saveAsBmp().

Drawing Text

After loading the Font you can draw text right away using the SpriteBatch:

@Override
public void draw(DeltaTime delta) {
    spriteBatch.begin(gameCamera.getViewMatrix()); 

    // similarly to the texture drawing, the 'drawText()' function has multiple variants, check them out!
    spriteBatch.drawText(font, "Hello, World!", Vector2.ZERO, Color.WHITE, 8);

    spriteBatch.end();
}

• In this example, '8' represents the virtual font size to apply. Since our font was set to '16' it will be down-scaled accordingly.
• The SpriteBatch is used because, after all, we are still drawing textures on the screen.
• You can compute a text width by using the font.computeTextWidth(...) function.
• Don't know how to use the SpriteBatch? Check this out.