Skip to content

Text

Jump to bottom
Philip Howard edited this page Dec 30, 2020 · 5 revisions

Text

Fonts

The 32blit engine supplies several functions for drawing text to the screen - or another surface - in any of the built-in fonts, or a ttf font via the asset pipeline.

Built-in Fonts

32blit provides three built-in fonts to get you started.

  1. Minimal Font - minimal_font
  2. Outline Font - outline_font
  3. Fat Font - fat_font

Custom Fonts

Custom fonts can be added to your game using the 32blit asset pipeline. ttf fonts are recognised and converted automatically. gif and png images are also supported, and should define individual glpyhs in a regular grid.

For example, using the PressStart2P-Regular.ttf font in a 32blit project would start with an assets.yml file like so:

font_asset.cpp:
  PressStart2P-Regular.ttf:
    name: press_start_font
    height: 8

This defines the filename that the asset builder should generate - font_asset.cpp, the input font PressStart2P-Regular.ttf, the name of the font asset name: press_start_font and, finally, the height in pixels since the font is baked from ttf to a fixed size bitmap: height: 8.

In this case an output file of font_asset.cpp will generate two source files:

  • font_asset.hpp
  • font_asset.cpp

To process and build assets during compilation, a line must be added to CMakeLists.txt:

blit_assets_yaml (text assets.yml)

The output resource font_asset.hpp must be included in a project and a custom font defined:

#include "font_asset.hpp"

const Font custom_font(press_start_font);

And, finally, custom_font can be used in place of the built-in fonts when drawing text:

text = "This text uses\nan imported\nTrueType font.";
screen.text(text, custom_font, Point(0, 0), true);

Drawing Text

There are two methods for drawing text, one that uses a Rect to define a bounding box, inside which text is wrapped:

void text(std::string_view message, const Font &font, const Rect &r, bool variable = true, TextAlign align = TextAlign::top_left);

And one that uses a Point defining the origin of the text, which is the top-left corner by default:

void text(std::string_view message, const Font &font, const Point &p, bool variable = true, TextAlign align = TextAlign::top_left);

Rect/Point Position

Using a Rect will specify a container for the text, explicitly defining the top, left, bottom and right edges against which it will be aligned.

A Point defines the origin of the text, and text will be aligned against this point- right-aligned text will draw on the left of the point, left-aligned text will draw on the right of the point and so on.

Fixed/Variable Width

Fixed width text ensures that every character is the same width, so the length of the rendered text is predictable. This might be used where a space for n digits (such as a two digit lives count) is reserved in the interface.

Variable width is great for readability where text does not need to fit in a specific bounding box and might wrap and scroll.

Alignment

The 5th argument to screen.text allows text alignment to be set using a 4-bit flag.

screen.text(text, minimal_font, text_rect, variable_width, TextAlign::center_center);

The following alignment options are available:

  • Left - TextAlign::left
  • Center (Horizontal) - TextAlign::center_h
  • Right - TextAlign::right
  • Top - TextAlign::top
  • Center (Vertical) - TextAlign::center_v
  • Bottom - TextAlign::bottom

There are also shorthands for valid alignment combinations:

  • Top Left - TextAlign::top_left
  • Center Left - TextAlign::center_left
  • Bottom Left - TextAlign::bottom_left
  • Top Center - TextAlign::top_center
  • Center - TextAlign::center_center
  • Bottom Center - TextAlign::bottom_center
  • Top Right - TextAlign::top_right
  • Center Right - TextAlign::center_right
  • Bottom Right - TextAlign::bottom_right

Masking/Clipping

The display clipping rectangle affects text like any other drawing operation.

Set a rectangle to screen.clip and text will not be drawn outside of this region.

Get Text Size

Knowing the width/height of text is useful for positioning. It can be obtained with measure_text which returns a Size object with w and h properties.

Size measure_text(std::string_view message, const Font &font, bool variable = true);

Wrap Text

draw_text will not wrap text for if it reaches the bounds of its containing Rect. Text must be wrapped explicitly before being drawn. This is accomplished either explitly using \n or using wrap_text, which accepts broadly the same arguments as draw_text:

std::string wrap_text(std::string_view message, int32_t width, const Font &font, bool variable = true, bool words = true);

Text is wrapped to width, breaking at letter boundaries and potentially breaking works. The newline character - \n - should be used to force linebreaks where breaking words is undesired.

Clone this wiki locally