Text Performance, Fitting and Wrapping

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.

Using TTF_Text and TTF_GetTextSize()

TTF_GetTextSize() helps us understand the size of the surface that would be created if we were to rasterize a piece of content. In SDL3, this is done by first creating a TTF_Text object via the TTF_CreateText() function.

This accepts four arguments:

1. A pointer to a TTF_TextEngine, which controls how the text will be rendered. We're not rendering this TTF_Text object - we're just using it to calculate layout information - so we can pass a nullptr here.
2. A pointer to the TTF_Font we're using
3. The text we want to use
4. The size of the text in bytes. As usual, we can pass 0 here if our text is null-terminated.

1TTF_Text* TextObject = TTF_CreateText(
2  nullptr, Font, "Hello World", 0);

Finally, to get the size that this text would be if we were to render it, we use TTF_GetTextSize().

The function accepts the TTF_Text pointer, and two int pointers that will be updated with the width and height respectively.

When we're done with a TTF_Text object, we should destroy it by passing the pointer to TTF_DestroyText():

1int Width, Height;
2TTF_Text* TextObject = TTF_CreateText(
3  nullptr, Font, "Hello World", 0);
4TTF_GetTextSize(
5  TextObject,
6  &Width, &Height
7);
8TTF_DestroyText(TextObject);

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_GetTextSize() can calculate the dimensions that the surface would be without needing to perform the rasterization, meaning it is significantly more performant.

1#include <iostream>
2#include <SDL3/SDL.h>
3#include <SDL3/SDL_main.h>
4#include <SDL3_ttf/SDL_ttf.h>
5
6int main(int, char**){
7  TTF_Init();
8
9  TTF_Font* Font{
10    TTF_OpenFont("Roboto-Medium.ttf", 25.0f)};
11
12  TTF_Text* TextObject = TTF_CreateText(
13    nullptr, Font, "Hello World", 0
14  );
15
16  int Width, Height;
17  TTF_GetTextSize(
18    TextObject, &Width, &Height
19  );
20
21  std::cout << "Width: " << Width
22    << ", Height: " << Height;
23
24  TTF_DestroyText(TextObject);
25  TTF_CloseFont(Font);
26  TTF_Quit();
27  return 0;
28};

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'll 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#pragma once
2#include <SDL3/SDL.h>
3#include <SDL3_ttf/SDL_ttf.h>
4#include "Text.h"
5
6class ScaledText : public Text {
7 public:
8  ScaledText(
9    const std::string& Content, int TargetWidth)
10    : Text{BaseFontSize} {
11    int Width;
12    TTF_Text* TempText = TTF_CreateText(
13      nullptr, Font, Content.c_str(), 0
14    );
15    TTF_GetTextSize(
16      TempText,
17      &Width, nullptr
18    );
19    TTF_DestroyText(TempText);
20
21    float Ratio{static_cast<float>(
22      TargetWidth
23    ) / Width};
24    SetFontSize(BaseFontSize * Ratio);
25    CreateSurface(Content);
26  }
27private:
28  static constexpr float BaseFontSize{24.0f};
29};

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

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <SDL3_ttf/SDL_ttf.h>
4#include "Window.h"
5#include "Text.h"
6#include "ScaledText.h"
7
8int main(int, char**) {
9  SDL_Init(SDL_INIT_VIDEO);
10  TTF_Init();
11
12  Window GameWindow;
13  ScaledText TextExample{
14    "Hello World",
15    GameWindow.GetWidth()
16  };
17
18  bool IsRunning = true;
19  SDL_Event Event;
20  while (IsRunning) {
21    while (SDL_PollEvent(&Event)) {
22      if (Event.type == SDL_EVENT_QUIT) {
23        IsRunning = false;
24      }
25    }
26    GameWindow.Render();
27    TextExample.Render(GameWindow.GetSurface());
28    GameWindow.Update();
29  }
30
31  TTF_Quit();
32  SDL_Quit();
33  return 0;
34}

Using TTF_MeasureString()

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

• The TTF_Font pointer
• The text we want to render
• The length of the text in bytes, or 0 for a null-terminated string
• 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 <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <SDL3_ttf/SDL_ttf.h>
4#include <iostream>
5
6int main(int, char**) {
7  TTF_Init();
8
9  TTF_Font* Font{
10    TTF_OpenFont("Roboto-Medium.ttf", 25.0f)};
11
12  int Extent, Count;
13  TTF_MeasureString(
14    Font,
15    "The quick brown fox jumps over the lazy dog",
16    0, 300, &Extent, &Count);
17
18  std::cout << "Extent: " << Extent <<
19    ", Count: " << Count;
20
21  TTF_CloseFont(Font);
22  TTF_Quit();
23  return 0;
24};

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

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

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <SDL3_ttf/SDL_ttf.h>
4#include "Window.h"
5#include "Text.h"
6#include "TruncatedText.h"
7
8int main(int, char**) {
9  SDL_Init(SDL_INIT_VIDEO);
10  TTF_Init();
11
12  Window GameWindow;
13  TruncatedText TextExample{
14    "The quick brown fox jumps over the lazy dog",
15    36.0f,
16    GameWindow.GetWidth()
17  };
18
19  bool IsRunning = true;
20  SDL_Event Event;
21  while (IsRunning) {
22    while (SDL_PollEvent(&Event)) {
23      if (Event.type == SDL_EVENT_QUIT) {
24        IsRunning = false;
25      }
26    }
27    GameWindow.Render();
28    TextExample.Render(GameWindow.GetSurface());
29    GameWindow.Update();
30  }
31
32  TTF_Quit();
33  SDL_Quit();
34  return 0;
35}

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_RenderText_Blended() is TTF_RenderText_Blended_Wrapped().

Let's create a WrappedText class that uses it:

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

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

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <SDL3_ttf/SDL_ttf.h>
4#include "Window.h"
5#include "Text.h"
6#include "WrappedText.h"
7
8int main(int, char**) {
9  SDL_Init(SDL_INIT_VIDEO);
10  TTF_Init();
11
12  Window GameWindow;
13  WrappedText TextExample{
14    "The quick brown fox jumps over the lazy dog",
15    36.0f,
16    GameWindow.GetWidth()
17  };
18
19  bool IsRunning = true;
20  SDL_Event Event;
21  while (IsRunning) {
22    while (SDL_PollEvent(&Event)) {
23      if (Event.type == SDL_EVENT_QUIT) {
24        IsRunning = false;
25      }
26    }
27    GameWindow.Render();
28    TextExample.Render(GameWindow.GetSurface());
29    GameWindow.Update();
30  }
31
32  TTF_Quit();
33  SDL_Quit();
34  return 0;
35}

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_SetFontWrapAlignment().

The alignment is an enum called TTF_HorizontalAlignment, for which SDL_ttf provides named variables:

• TTF_HORIZONTAL_ALIGN_LEFT (default)
• TTF_HORIZONTAL_ALIGN_CENTER
• TTF_HORIZONTAL_ALIGN_RIGHT

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

1#pragma once
2#include <SDL3/SDL.h>
3#include <SDL3_ttf/SDL_ttf.h>
4#include "Text.h"
5
6class WrappedText : public Text {
7 public:
8  WrappedText(
9    const std::string& Content,
10    float FontSize, int MaxWidth,
11    TTF_HorizontalAlignment Alignment
12      = TTF_HORIZONTAL_ALIGN_CENTER
13  ) : Text{FontSize}, MaxWidth{MaxWidth} {
14    TTF_SetFontWrapAlignment(Font, Alignment);
15    CreateSurface(Content);
16  }
17
18private:
19  void CreateSurface(const std::string& Content) {
20    SDL_DestroySurface(TextSurface);
21    TextSurface = TTF_RenderText_Blended_Wrapped(
22      Font, Content.c_str(), 0,
23      {255, 255, 255, 255}, MaxWidth
24    );
25    if (!TextSurface) {
26      std::cout << "Error creating TextSurface: "
27        << SDL_GetError() << '\n';
28    }
29  }
30
31  int MaxWidth;
32};

Here is the complete code after all the changes in this lesson. We've created several specialized text classes (ScaledText, TruncatedText, WrappedText) that inherit from our base Text class to handle various rendering scenarios.

In this lesson, we explored advanced text rendering techniques. 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. within specified dimensions, and implement word wrapping with alignment options.