Text Performance, Fitting and Wrapping

In this lesson, we’ll build on our text rendering capabilities with some new tools:

• The ability to adjust the rasterizing process to optimize performance when appropriate
• Dynamically choosing a font size to fit a target pixel size for our rasterized surface
• Calculating how much text we can fit within a designated space
• Rendering multi-line text areas using word wrapping, and controlling the alignment of the lines

Our main.cpp is below. Compared to the last lesson, we’ve added a GetWidth() method to the Window class.

1#include <iostream>
2#include <SDL.h>
3#include <SDL_ttf.h>
4#include "Text.h"
5
6class Window {
7public:
8  Window() {
9    SDLWindow = SDL_CreateWindow(
10      "My Program", SDL_WINDOWPOS_UNDEFINED,
11      SDL_WINDOWPOS_UNDEFINED, GetWidth(), 300, 0);
12  }
13
14  void Render() {
15    SDL_FillRect(
16      GetSurface(), nullptr, SDL_MapRGB(
17        GetSurface()->format, 50, 50, 50
18      )
19    );
20  }
21
22  void Update() {
23    SDL_UpdateWindowSurface(SDLWindow);
24  }
25
26  SDL_Surface* GetSurface() {
27    return SDL_GetWindowSurface(SDLWindow);
28  }
29
30  ~Window() { SDL_DestroyWindow(SDLWindow); }
31  Window(const Window&) = delete;
32  Window& operator=(const Window&) = delete;
33  
34  int GetWidth() const { return WindowWidth; }
35
36private:
37  SDL_Window* SDLWindow;
38  int WindowWidth{600};
39};
40
41int main(int argc, char** argv) {
42  SDL_Init(SDL_INIT_VIDEO);
43  TTF_Init();
44  SDL_Event Event;
45  bool shouldQuit{false};
46
47  Window GameWindow;
48  Text TextExample{"Hello World"};
49
50  while (!shouldQuit) {
51    while (SDL_PollEvent(&Event)) {
52      if (Event.type == SDL_QUIT) {
53        shouldQuit = true;
54      }
55    }
56    GameWindow.Render();
57    TextExample.Render(GameWindow.GetSurface());
58    GameWindow.Update();
59  }
60
61  TTF_Quit();
62  SDL_Quit();
63  return 0;
64}

Our Text class is below. Compared to the previous lesson, we’ve changed the private section to protected, as we’ll create some derived classes in this section.

We’ve also added a constructor that initializes the Font, but not the SDL_Surface needed for blitting. This constructor will be useful to those derived classes, but we don’t want it to be called in any other context. Therefore, we’ve marked it as protected.

1#pragma once
2#include <SDL.h>
3#include <SDL_ttf.h>
4
5class Text {
6 public:
7  Text(std::string Content, int FontSize = 100)
8  : Font{LoadFont(FontSize)} {
9    CreateSurface(Content);
10  }
11
12  void SetFontSize(int NewSize) {
13    TTF_SetFontSize(Font, NewSize);
14  }
15
16  void Render(SDL_Surface* DestinationSurface) {
17    SDL_BlitSurface(
18      TextSurface, nullptr,
19      DestinationSurface, &DestinationRectangle
20    );
21  }
22
23  ~Text() {
24    SDL_FreeSurface(TextSurface);
25    if (TTF_WasInit()) {
26      TTF_CloseFont(Font);
27    }
28  }
29  Text(const Text&) = delete;
30  Text& operator=(const Text&) = delete;
31
32protected:
33  Text(int FontSize)
34  : Font{LoadFont(FontSize)} {}
35
36  TTF_Font* LoadFont(int FontSize) {
37   TTF_Font* LoadedFont{TTF_OpenFont(
38     "Roboto-Medium.ttf", FontSize)};
39    if (!LoadedFont) {
40      std::cout << "Error loading font: "
41        << SDL_GetError();
42    }
43    return LoadedFont;
44  }
45
46  void CreateSurface(std::string Content) {
47    SDL_FreeSurface(TextSurface);
48    TextSurface = TTF_RenderUTF8_Blended(
49      Font, Content.c_str(), {255, 255, 255}
50    );
51    if (!TextSurface) {
52      std::cout << "Error creating TextSurface: "
53        << SDL_GetError();
54    }
55  }
56
57  TTF_Font* Font{nullptr};
58  SDL_Surface* TextSurface{nullptr};
59  SDL_Rect DestinationRectangle{0, 0, 0, 0};
60};

Text Rendering Performance

Rendering text is surprisingly expensive in terms of performance cost, and is something we should be mindful of when our program is using a large amount of dynamic text. This performance impact comes in two types:

• Rasterization - how expensive it is to generate pixel data from the provided font and content
• Blitting - how expensive it is to blit that pixel data onto other surfaces, such as the window surface to display to users

We’re currently using TTF_RenderUTF8_Blended(). "Blended" rendering maximizes quality and flexibility at the cost of performance:

Faster Rasterization - Solid

Much of the cost of rasterization comes from calculating the smooth edges of our font, sometimes called anti-aliasing. If we don’t need anti-aliasing, we can use "solid" rendering functions, such as TTF_RenderUTF8_Solid().

It uses the same arguments as a blended function but does not use anti-aliasing. This is faster to render, but leaves the edges of our text looking more jagged:

1// Text.h
2// ...
3class Text {
4  // ...
5protected:
6  // ...
7  void CreateSurface(std::string Content) {
8    SDL_FreeSurface(TextSurface);
9    TextSurface = TTF_RenderUTF8_Solid(
10      Font, Content.c_str(), {255, 255, 255}
11    );
12    if (!TextSurface) {
13      std::cout << "Error creating TextSurface: "
14        << SDL_GetError();
15    }
16  }
17  // ...
18};

Faster Blitting - Shaded

Most of the performance cost of blitting involves working with transparency. The SDL_Surface generated by functions like TTF_RenderUTF8_Blended() and TTF_RenderUTF8_Solid() has a transparent background.

This maximizes flexibility - the text can be blitted onto any surface and will maintain the background color of that destination surface.

However, this comes at a cost. If we don’t want to pay for it, we can create our text surface with an opaque background, which makes blitting much faster.

The TTF_RenderUTF8_Shaded() function anti-aliases our text in the same way as TTF_RenderUTF8_Blended(), except it rasterizes onto an opaque background. We pass the SDL_Color we want the background to be as an additional argument:

1// Text.h
2// ...
3class Text {
4  // ...
5protected:
6  // ...
7  void CreateSurface(std::string Content) {
8    SDL_FreeSurface(TextSurface);
9    TextSurface = TTF_RenderUTF8_Shaded(
10      Font,
11      Content.c_str(),
12      {255, 255, 255}, // Text Color (White)
13      {0, 0, 90} // Background Color (Blue)
14    );
15    if (!TextSurface) {
16      std::cout << "Error creating TextSurface: "
17        << SDL_GetError();
18    }
19  }
20  // ...
21};

In this program, our text is being blitted onto a solid color anyway - the gray of our window surface.

In scenarios like this, TTF_RenderUTF8_Shaded() could ultimately generate the exact same visuals as TTF_RenderUTF8_Blended() without the performance cost. We’d simply need to pass the correct background color to TTF_RenderUTF8_Shaded()

Faster Rasterization and Blitting - LCD

Finally, we can fully prioritize performance by combining the rough edges of "solid" rendering with the opaque background of "shaded" rendering. SDL_ttf calls this option LCD:

1// Text.h
2// ...
3class Text {
4  // ...
5protected:
6  // ...
7  void CreateSurface(std::string Content) {
8    SDL_FreeSurface(TextSurface);
9    TextSurface = TTF_RenderUTF8_LCD(
10      Font,
11      Content.c_str(),
12      {255, 255, 255}, // Text Color (White)
13      {0, 0, 90} // Background Color (Blue)
14    );
15    if (!TextSurface) {
16      std::cout << "Error creating TextSurface: "
17        << SDL_GetError();
18    }
19  }
20  // ...
21};

Font Caching / Glyph Caching

To ensure our program can generate high-quality text with minimal performance impact, a font cache is often used.

This means any time we rasterize a character (sometimes called a glyph) we store the calculated pixels in memory so we can reuse them later.

Often, these glyphs are packed into a large image file called a texture atlas, which is a single image containing multiple smaller images (in this case, glyphs) arranged efficiently:

Nicolas P. Rougier - CC BY-SA 4.0

These caching systems include additional bookkeeping to keep track of which glyphs we have cached, where they are in our atlas, which font they used, and the font size.

When a request is made to render the same glyph, using the same font, at the same size, we can reuse the data from our texture atlas rather than recalculate it from scratch.

SDL_TTF includes a basic implementation of glyph caching, which is enough for our needs in this course.

There are open-source examples of more powerful implementations for those interested in pursuing the topic further, such as SDL_FontCache and VEFontCache.

UTF-8 Encoding

Character encoding is the process of representing text as binary data that computers can store and transmit. UTF-8 (Unicode Transformation Format 8-bit) is a widely used encoding standard that can represent virtually all characters in use worldwide.

When you see UTF8 in SDL_ttf function names like TTF_RenderUTF8_Blended(), it indicates that the function expects the input text to be encoded in UTF-8 format.

This is the most common encoding for text in modern systems, making it a safe default choice for handling text in your applications. We cover character encoding in more depth in our advanced course:

Characters, Unicode and Encoding

An introduction to C++ character types, the Unicode standard, character encoding, and C-style strings

Text Scaling

Before we render text, we often need to perform some calculations relating to size. For example, we might want to dynamically set the font size such that our surface has some specific pixel size. Or, we may want to find out how much text we can fit within a specific area.

SDL_ttf has some utilities that can help us with these tasks.

TTF_SizeUTF8()

TTF_SizeUTF8() helps us understand how big a surface would be created if we were to rasterize a piece of content in a given font. It accepts 4 parameters - the font, the content, and two int pointers that will be updated with the width and height respectively.

1int Width, Height;
2TTF_SizeUTF8(
3  Font, "Hello World",
4  &Width, &Height
5);

The results from doing this are equivalent to simply rendering the text and then accessing the w and h of the generated SDL_Surface.

However, TTF_SizeUTF8() can calculate the dimensions that the source would be without needing to perform the rasterization, meaning it is significantly more performant.

1#include <iostream>
2#include <SDL_ttf.h>
3
4int main(int argc, char** argv) {
5  TTF_Init();
6
7  TTF_Font* Font{
8    TTF_OpenFont("Roboto-Medium.ttf", 25)};
9
10  int Width, Height;
11  TTF_SizeUTF8(
12    Font, "Hello World",
13    &Width, &Height
14  );
15
16  std::cout << "Width: " << Width
17    << ", Height: " << Height;
18
19  TTF_Quit();
20  return 0;
21};

1Width: 128, Height: 30

If we only care about the width or height of the text, we can pass a nullptr in the other position.

Let’s use this to create a new ScaledText class that dynamically sets the font size to make our rendered text hit a target width.

We arbitrarily initialize our font with a size of 24, and then calculate how wide the surface would be if we rendered our content at that size.

We then determine the ratio between the calculated width and target width, and adjust our font size accordingly before creating the surface for real:

1// ScaledText.h
2#pragma once
3#include <SDL.h>
4#include <SDL_ttf.h>
5#include "Text.h"
6
7class ScaledText : public Text {
8 public:
9  ScaledText(
10    std::string Content, int TargetWidth)
11    : Text{BaseFontSize} {
12    int Width;
13    TTF_SizeUTF8(
14      Font, Content.c_str(),
15      &Width, nullptr
16    );
17
18    float Ratio{static_cast<float>(TargetWidth) / Width};
19    SetFontSize(BaseFontSize * Ratio);
20    CreateSurface(Content);
21  }
22private:
23  static constexpr int BaseFontSize{24};
24};

Over in main(), let’s update TextExample to use this type, and pass the window width as our target:

1// main.cpp
2// ...
3#include "ScaledText.h"
4// ...
5
6int main(int argc, char** argv) {
7  // ...
8  ScaledText TextExample{
9    "Hello World",
10    GameWindow.GetWidth()
11  };
12  // ...
13}

TTF_MeasureUTF8()

Another requirement we’re likely to have is to determine how much text can fit within a desired width. The TTF_MeasureUTF8() can help us determine how many characters can fit within a space. It accepts 5 arguments:

• The TTF_Font pointer
• The text we want to render
• The maximum width we have available
• A pointer to an int, which will be updated with the pixel width of the characters from our string that can fit within that space (the extent)
• A pointer to an int, which will be updated with the quantity of characters from our string that can fit within our space (the count)

1#include <SDL_ttf.h>
2#include <iostream>
3
4int main(int argc, char** argv) {
5  TTF_Init();
6
7  TTF_Font* Font{
8    TTF_OpenFont("Roboto-Medium.ttf", 25)};
9
10  int Extent, Count;
11  TTF_MeasureUTF8(
12    Font,
13    "The quick brown fox jumps over the lazy dog",
14    300, &Extent, &Count);
15
16  std::cout << "Extent: " << Extent <<
17    ", Count: " << Count;
18
19  TTF_Quit();
20  return 0;
21};

1Extent: 288, Count: 24

We can pass a nullptr to either the extent or the count if we don’t care about that result.

In the following example, we create a class that uses this feature. If the entire string won’t fit within a space, it will remove characters from the end of the string until it does fit. We also add an ellipsis (…) to indicate it has been truncated.

If TTF_MeasureUTF8() reports that the number of characters that can fit within the space is less than the size of our Content string, we use the std::string's resize() method to remove the excess characters.

We remove 3 additional characters to make room for the ... which we add using the std::string's append() method:

1// TruncatedText.h
2#pragma once
3#include <SDL.h>
4#include <SDL_ttf.h>
5#include "Text.h"
6
7class TruncatedText : public Text {
8 public:
9  TruncatedText(
10    std::string Content,
11    int FontSize,
12    int MaxWidth
13  ) : Text{FontSize} {
14    int MaxCharacters;
15    TTF_MeasureUTF8(
16      Font, Content.c_str(),
17      MaxWidth, nullptr, &MaxCharacters
18    );
19
20    if (MaxCharacters < Content.size()) {
21      Content.resize(MaxCharacters - 3);
22      Content.append("...");
23    }
24
25    CreateSurface(Content);
26  }
27};

Let’s update TextExample in main() to use this new type:

1// main.cpp
2// ...
3#include "TruncatedText.h" 
4
5// ...
6
7int main(int argc, char** argv) {
8  // ...
9  TruncatedText TextExample{
10    "The quick brown fox jumps over the lazy dog",
11    36,
12    GameWindow.GetWidth()
13  };
14  // ...
15}

Multi-Line Text (Wrapping)

Often, we’ll want to create larger blocks of text that extend across multiple lines. If the text exceeds a specific width in pixels, we want to move the rest of the text onto a new line, without splitting a word across multiple lines. This is typically called word wrapping.

All the font rendering functions have variations that accept an additional argument as a max width and will output a multiple-line surface if our text exceeds that length.

These functions have a _Wrapped suffix. For example, the wrapped version of TTF_RenderUTF8_Blended() is TTF_RenderUTF8_Blended_Wrapped().

Let’s create a WrappedText class that uses it:

1// WrappedText.h
2#pragma once
3#include <SDL.h>
4#include <SDL_ttf.h>
5#include "Text.h"
6
7class WrappedText : public Text {
8 public:
9  WrappedText(std::string Content, int FontSize, int MaxWidth)
10      : Text{FontSize}, MaxWidth{MaxWidth} {
11    CreateSurface(Content);
12  }
13
14private:
15  void CreateSurface(std::string Content) {
16    SDL_FreeSurface(TextSurface);
17    TextSurface = TTF_RenderUTF8_Blended_Wrapped(
18      Font, Content.c_str(), {255, 255, 255}, MaxWidth
19    );
20    if (!TextSurface) {
21      std::cout << "Error creating TextSurface: " << SDL_GetError();
22    }
23  }
24
25  int MaxWidth;
26};

Over in main(), let’s update our TextExample to use this WrappedText type:

1// main.cpp
2// ...
3#include "WrappedText.h"
4// ...
5
6int main(int argc, char** argv) {
7  // ...
8  WrappedText TextExample{
9    "The quick brown fox jumps over the lazy dog",
10    36,
11    GameWindow.GetWidth()
12  };
13  // ...
14}

Text Alignment

When rendering wrapped text, we can control its alignment. To do this, we pass the TTF_Font pointer and the alignment we want to use to TTF_SetFontWrappedAlign().

The alignment is a simple integer, for which SDL_ttf provides named variables:

• TTF_WRAPPED_ALIGN_LEFT (default)
• TTF_WRAPPED_ALIGN_CENTER
• TTF_WRAPPED_ALIGN_RIGHT

Let’s add an alignment option as a constructor argument to our WrappedText, and pass it to TTF_SetFontWrappedAlign() before creating the surface:

1// WrappedText.h
2#pragma once
3#include <SDL.h>
4#include <SDL_ttf.h>
5#include "Text.h"
6
7class WrappedText : public Text {
8 public:
9  WrappedText(
10    std::string Content,
11    int FontSize, int MaxWidth,
12    int Alignment = TTF_WRAPPED_ALIGN_CENTER
13  ) : Text{FontSize}, MaxWidth{MaxWidth} {
14    TTF_SetFontWrappedAlign(Font, Alignment);
15    CreateSurface(Content);
16  }
17  // ...
18};

Summary

In this lesson, we explored advanced text rendering techniques using SDL and SDL_ttf. We covered performance optimization methods, including solid, shaded, and LCD rendering.

We also learned how to dynamically scale text, truncate it to fit within specified dimensions, and implement word wrapping with alignment options.

Next Lesson

Engine Overview

An introduction to the generic engine classes we'll use to create the game

ContinueView Course