Introduction to SDL_ttf

In this lesson, we’ll learn how to render text in our SDL2 programs using SDL2_ttf.

This lesson assumes we already have SDL2 and SDL2_ttf installed and set up in our project.

If this is not the case, refer to our earlier lessons where we set up the development environment for Windows or Mac:

Installing SDL2 Libraries on macOS

Preparing our development environment for this chapter by Installing SDL2 and the SDL_image and SDL_ttf extensions. Setup guide for Xcode or CMake. 

Installing SDL2 Libraries Manually on Windows

Preparing our development environment for this chapter by Installing SDL2 and the SDL_image and SDL_ttf extensions. Setup guide for Visual Studio on Windows. 

Let's start with a basic event loop and window class, similar to what we covered in previous lessons:

1#include <SDL.h>
2
3#include "TextWindow.h"
4
5int main(int argc, char** argv) {
6  SDL_Init(SDL_INIT_VIDEO);
7
8  TextWindow Window;
9
10  SDL_Event Event;
11  while (true) {
12    while (SDL_PollEvent(&Event)) {
13      if (Event.type == SDL_QUIT) [[unlikely]] {
14        SDL_Quit();
15        return 0;
16      }
17    }
18  }
19
20  return 0;
21}

1#pragma once
2#include <SDL.h>
3#include <SDL_ttf.h>
4#include <iostream>
5#include <string>
6
7using std::cout, std::endl;
8
9class TextWindow {
10 public:
11  TextWindow() {
12    SDLWindow = SDL_CreateWindow(
13      "Hello Window",
14      SDL_WINDOWPOS_UNDEFINED,
15      SDL_WINDOWPOS_UNDEFINED,
16      600, 150, 0
17    );
18
19    SDLWindowSurface = SDL_GetWindowSurface(SDLWindow);
20    FillWindowSurface();
21    SDL_UpdateWindowSurface(SDLWindow);
22  }
23
24 private:
25  void FillWindowSurface() {
26    SDL_FillRect(
27      SDLWindowSurface,
28      nullptr,
29      SDL_MapRGB(SDLWindowSurface->format, 240, 240, 240)
30    );
31  }
32
33  SDL_Window* SDLWindow{nullptr};
34  SDL_Surface* SDLWindowSurface{nullptr};
35};

This should be familiar from our previous lessons on creating windows and application loops using SDL2:

Creating a Window

Learn how to get started with SDL2 in C++ by creating a window. Includes an explanation of all the SDL2 functions we use, and the options we have to modify the window.

Implementing an SDL2 Application Loop in C++

Setting solid foundations for our application, by implementing the main loop and the event loop

Initialising SDL_ttf

Before we can start using SDL_ttf, we need to initialize it. We do this by calling the TTF_Init function:

1TTF_Init();

This function returns 0 if the initialization was successful, and -1 otherwise. In the event of an error, we can also call TTF_GetError() to retrieve a text description of what went wrong.

Let's add this code to the bottom of our TextWindow constructor:

1if (TTF_Init() < 0) {
2  cout << "Error from TTF_Init: "
3       << TTF_GetError() << endl;
4}

When we no longer need SDL_ttf, we can unload it by calling TTF_Quit(). Let's do that in a destructor:

1~TextWindow() {
2  TTF_Quit();
3}

Loading Fonts

To render text, we need to have a font we want to use. Fonts are typically stored in the TrueType Font (.ttf) format. These files are widely available online, with many free options available. In this example, we’ll use Roboto, a free font available from Google Fonts.

Once we move the font into our project directory, we can load it using the TTF_OpenFont function, passing in the path to the font file, and the size we want to use:

1Font = TTF_OpenFont("Roboto-Medium.ttf", 50);

This function returns a pointer to a TTF_Font, which we will need to use later when rendering our text.

Let's add this variable to our class, as well as a function we can call from our constructor to populate it. The rest of our code remains unchanged:

1class TextWindow {
2public:
3  TextWindow() {
4    // ...
5    LoadFont();
6  }
7
8private:
9  void LoadFont() {
10    Font = TTF_OpenFont("Roboto-Medium.ttf", 50);
11  }
12  TTF_Font* Font;
13};

If TTF_OpenFont fails, it will return a nullptr. Additionally, we can inspect the error by calling TTF_GetError().

Let's enhance our LoadFont function accordingly:

1void LoadFont() {
2  Font = TTF_OpenFont("Roboto-Medium.ttf", 50);
3  if (!Font) {
4    cout << "Failed to load font: "
5         << TTF_GetError() << endl;
6  }
7}

When we no longer need our font, we can clean it up by passing the pointer to TTF_CloseFont. Let's do that in our destructor:

1~TextWindow() {
2  TTF_Quit();
3  TTF_CloseFont(Font);
4}

Rendering Text

With our font available, we can use it to create new SDL_Surface objects containing our desired text.

SDL_ttf provides a lot of options for doing this, each implemented as a separate function. The function we want depends on two things:

• The character encoding we need. In most cases, we will want UTF-8 encoding.
• The quality of text we want.

In this example, we’ll use the highest quality text rendering, Blended.

Therefore, in this case, the function we will use is TTF_RenderUTF8_Blended. This function accepts 3 arguments - the TTF_Font pointer we got when we loaded our font, the text we want to render, and the color we want the text to be:

1SDL_Color Color = {20, 20, 20};
2TTF_RenderUTF8_Blended(Font, "Hello World!", Color);

This function will return a pointer to a new SDL_Surface, which we can treat like any other surface. Most importantly, we can blit it onto our window surface so we can see the text.

Let's implement this as a public function:

1class TextWindow {
2// ...
3public:
4  void SetText(std::string Text) {
5    SDL_Color Color = {20, 20, 20};
6
7    // Our function parameter is a std::string, but SDL_ttf
8    // requires a C-style string be passed, so we use
9    //  std::string's c_str method to get the C-string
10    SDL_Surface* TextSurface {
11      TTF_RenderUTF8_Blended(Font, Text.c_str(), Color)
12    };
13
14    // Check to see if the surface was successfully created
15    if (!TextSurface) {
16      cout << "Failed to render text: "
17           << TTF_GetError() << endl;
18    }
19
20    // Fill the window surface with our solid color
21    // This ensures any previous text is erased
22    FillWindowSurface();
23
24    // Blit our text onto our window surface
25    SDL_BlitSurface(
26      TextSurface,
27      nullptr,
28      SDLWindowSurface,
29      nullptr
30    );
31
32    // Release our text surface as we no longer need it
33    SDL_FreeSurface(TextSurface);
34
35    // Send our new frame to the screen
36    SDL_UpdateWindowSurface(SDLWindow);
37  }
38// ...
39};

If any of the steps here are unclear, our earlier lessons on SDL windows, images, and surface blitting are likely to be helpful:

Creating a Window

Learn how to get started with SDL2 in C++ by creating a window. Includes an explanation of all the SDL2 functions we use, and the options we have to modify the window.

Images and Surface Blitting

Learn how to load images into our SDL2 application. Then, learn how to crop, resize, position and render them into our window.

Finally, over in our main function, we can call this method, and see our results:

1#include <SDL.h>
2#include "TextWindow.h"
3
4int main(int argc, char** argv) {
5  // ...
6  TextWindow Window;
7  Window.SetText("Hello world!");
8  // ...
9}

Positioning Text

We can use the 2nd and 4th arguments of SDL_BlitSurface to position the text within the window.

These two arguments are pointers to SDL_Rect. The first rectangle corresponds to the source surface (ie, the text) and the second rectangle corresponds to the destination (ie, the window surface).

The width and height of any surface or rectangle are available using the w and h fields respectively. Here, we define a rectangle that has the same dimensions as the source surface.

1SDL_Rect Source { 0, 0, TextSurface->w, TextSurface->h };

Here, we define a rectangle that starts 70 pixels from the left edge, 40 pixels from the top edge, and has the same width and height as the Source rectangle:

1SDL_Rect Destination { 70, 40, Source.w, Source.h };

Using these two rectangles in our call to SDL_BlitSurface allows us to position our text:

1SDL_Rect Source { 0, 0, TextSurface->w, TextSurface->h };
2SDL_Rect Destination { 70, 40, Source.w, Source.h };
3SDL_BlitSurface(
4  TextSurface, &Source, SDLWindowSurface, &Destination
5);

We could extend this further to implement more complex positioning. For example, we could write code that uses the w and h of the text surface, the w and h of the window surface, and some maths to ensure our text is always centered, in the top right, or anywhere else we need it to be

We cover surface blitting in more detail in this lesson:

Images and Surface Blitting

Learn how to load images into our SDL2 application. Then, learn how to crop, resize, position and render them into our window.

Complete Code

The final code is available here:

1#include <SDL.h>
2#include "TextWindow.h"
3
4int main(int argc, char** argv) {
5  SDL_Init(SDL_INIT_VIDEO);
6
7  TextWindow Window;
8  Window.SetText("Hello world!");
9
10  SDL_Event Event;
11  while (true) {
12    while (SDL_PollEvent(&Event)) {
13      if (Event.type == SDL_QUIT) [[unlikely]] {
14        SDL_Quit();
15        return 0;
16      }
17    }
18  }
19
20  return 0;
21}

1#pragma once
2#include <SDL.h>
3#include <SDL_ttf.h>
4
5#include <iostream>
6#include <string>
7
8using std::cout, std::endl;
9
10class TextWindow {
11 public:
12  TextWindow() {
13    SDL_Init(SDL_INIT_VIDEO);
14
15    SDLWindow = SDL_CreateWindow(
16      "Hello Window",
17      SDL_WINDOWPOS_UNDEFINED,
18      SDL_WINDOWPOS_UNDEFINED,
19      600, 150, 0
20    );
21
22    SDLWindowSurface = SDL_GetWindowSurface(SDLWindow);
23    FillWindowSurface();
24    SDL_UpdateWindowSurface(SDLWindow);
25
26    if (TTF_Init() < 0) {
27      cout << "Error calling TTF_Init: "
28           << TTF_GetError() << endl;
29    }
30
31    LoadFont();
32  }
33
34  ~TextWindow() {
35    TTF_Quit();
36    TTF_CloseFont(Font);
37  }
38
39  void SetText(std::string Text) {
40    SDL_Color Color { 20, 20, 20 };
41    SDL_Surface* TextSurface {
42      TTF_RenderUTF8_Blended(Font, Text.c_str(), Color)
43    };
44    if (!TextSurface) {
45      cout << "Failed to render text: "
46           << TTF_GetError() << endl;
47    }
48
49    FillWindowSurface();
50
51    SDL_Rect Source { 0, 0, TextSurface->w, TextSurface->h };
52    SDL_Rect Destination { 70, 40, Source.w, Source.h };
53    SDL_BlitSurface(
54      TextSurface, &Source, SDLWindowSurface, &Destination
55    );
56    SDL_FreeSurface(TextSurface);
57    SDL_UpdateWindowSurface(SDLWindow);
58  }
59
60 private:
61  void FillWindowSurface() {
62    SDL_FillRect(
63      SDLWindowSurface,
64      nullptr,
65      SDL_MapRGB(SDLWindowSurface->format, 240, 240, 240)
66    );
67  }
68
69  void LoadFont() {
70    Font = TTF_OpenFont("Roboto-Medium.ttf", 50);
71    if (!Font) {
72      cout << "Failed to load font: "
73           << TTF_GetError() << endl;
74    }
75  }
76
77  SDL_Window* SDLWindow{nullptr};
78  SDL_Surface* SDLWindowSurface{nullptr};
79  TTF_Font* Font;
80};

Next Lesson

Maths and Geometry Primer

Learn the basics of maths and geometry, so we can represent concepts like positions and distances between objects in our worlds.

ContinueView Course