In this lesson, we'll see how we can render text within our programs. We'll use the SDL3_ttf extension we installed earlier in the course.

We'll build upon the concepts we introduced in the previous chapters. Our main.cpp looks like below. To focus on text rendering, we have removed the Image class from our project.

The key thing to note is that we have created a Text class and instantiated an object from it called TextExample. This object is being asked to Render() onto the window surface every frame.

Files

src

Select a file to view its content

We will also need a TrueType (.ttf) file stored in the same location as our executable. The code examples and screenshots in this lesson use Roboto-Medium.ttf, available from Google Fonts.

Initializing and Quitting `SDL3_ttf`

To use SDL3_ttf in our application, we #include the SDL3_ttf/SDL_ttf.h header file. We then call TTF_Init() to initialize the library, and TTF_Quit() to close it down:

src/main.cpp

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
7int main(int, char**) {
8  SDL_Init(SDL_INIT_VIDEO);
9  TTF_Init();
10
11  Window GameWindow;
12  Text TextExample{"Hello World"};
13
14  bool IsRunning = true;
15  SDL_Event Event;
16  while (IsRunning) {
17    while (SDL_PollEvent(&Event)) {
18      if (Event.type == SDL_EVENT_QUIT) {
19        IsRunning = false;
20      }
21    }
22    GameWindow.Render();
23    TextExample.Render(GameWindow.GetSurface());
24    GameWindow.Update();
25  }
26
27  TTF_Quit();
28  SDL_Quit();
29  return 0;
30}

Error Checking `TTF_Init()`

In SDL3, TTF_Init() returns true if it succeeds and false if it fails. We can check for this error state and call SDL_GetError() for an explanation:

1#include <iostream>
2
3// ...
4if (!TTF_Init()) {
5  std::cout << "Error initializing SDL_ttf: "
6    << SDL_GetError();
7}

Loading and Freeing Fonts

To create text in our application, we first need to load a font. To do this, we call TTF_OpenFont(), passing the path to our font file and the font size we want to use as a float:

1TTF_OpenFont("Roboto-Medium.ttf", 50.0f);

Remember, just like with loading images, the font file we're referencing here should be in the same directory as our executable. Our code examples and screenshots are using the Roboto font, which can be downloaded for free from Google Fonts.

On some platforms, these relative paths will not work, so you may need to switch to using absolute paths, using similar techniques we introduced in our image lessons:

1const std::string BASE_PATH{SDL_GetBasePath()};
2TTF_OpenFont(BASE_PATH + "Roboto-Medium.ttf");

The TTF_OpenFont() function creates a TTF_Font object and returns a pointer to it. To prevent memory leaks, we pass this pointer to TTF_CloseFont() when we no longer need it.

To simplify memory management, we'll also prevent our Text objects from being copied by deleting their copy constructor and copy assignment operator. Our updated Text class looks like this:

src/Text.h

1#pragma once
2#include <SDL3/SDL.h>
3#include <SDL3_ttf/SDL_ttf.h>
4#include <string>
5
6class Text {
7 public:
8  Text(const std::string& Content) : Font{
9    TTF_OpenFont("Roboto-Medium.ttf", 50.0f)
10  } {}
11
12  void Render(SDL_Surface* DestinationSurface) {
13    // ...
14  }
15
16  ~Text() {
17    TTF_CloseFont(Font);
18  }
19  Text(const Text&) = delete;
20  Text& operator=(const Text&) = delete;
21
22private:
23  TTF_Font* Font{nullptr};
24};

Checking Initialization using `TTF_WasInit()`

If we call TTF_CloseFont() when SDL3_ttf is not initialized, our program can crash. Issues like this are most common during the "cleanup" phase of our application, where we're trying to shut everything down cleanly.

In our example, the TextExample object's destructor isn't called until main() ends. However, before main() ends, we call TTF_Quit(), meaning by the time ~Text() calls TTF_CloseFont(), SDL3_ttf has already been shut down.

We can test for this scenario using TTF_WasInit(). The TTF_WasInit() function returns a positive integer if SDL3_ttf is currently initialized, so we can make our class more robust like this:

src/Text.h

1// ...
2class Text {
3  // ...
4  ~Text() {
5    if (TTF_WasInit()) {
6      TTF_CloseFont(Font);
7    }
8  }
9  // ...
10};

Calling `TTF_Init()` and `TTF_Quit()` Multiple Times

As an aside, SDL3_ttf keeps track of how many times TTF_Init() has been called, and will only shut down when the same number of calls to TTF_Quit() have been made.

This gives us an alternative approach to working with the library. Instead of calling TTF_Init() when our application starts, we can call it every time it is needed - for example, in the constructors of objects that use it.

We then ensure each of those initializations is matched with a TTF_Quit() call, such as in the destructors of those same objects.

The positive integer returned by TTF_WasInit() represents how many times TTF_Init() has been called, reduced by how many times TTF_Quit() has been called. If we manage the lifecycle of all our objects perfectly, the number will be 0 when our application closes.

Error Checking `TTF_OpenFont()`

If TTF_OpenFont() failed, it will return a nullptr. We can check for this, and log out the error for an explanation:

src/Text.h

1#pragma once
2#include <SDL3/SDL.h>
3#include <SDL3_ttf/SDL_ttf.h>
4#include <iostream>
5#include <string>
6
7class Text {
8 public:
9  Text(const std::string& Content) : Font{
10    TTF_OpenFont("Roboto-Medium.ttf", 50.0f)
11  } {
12    if (!Font) {
13      std::cout << "Error loading font: "
14        << SDL_GetError() << '\n';
15    }
16  }
17  // ...
18};

Rendering Text

From a high level, the process of rendering text is very similar to rendering images:

We generate an SDL_Surface containing the pixel data representing our text.
We blit that surface onto another surface, using functions like SDL_BlitSurface().

There are many options we can use to generate our surface. We'll explain their differences in the next lesson. For now, we'll use TTF_RenderText_Blended(). This function requires four arguments in SDL3:

The font we want to use, as a TTF_Font pointer.
The text we want to render, as a C-style string.
How many characters we want to render from the string. If we want to render everything, and our string is correctly null-terminated, we can pass 0 here.
The color we want to use, as an SDL_Color.

For example:

1TTF_RenderText_Blended(
2  Font,
3  "Hello World",
4  0, // Use the null-terminator to find length
5  SDL_Color{255, 255, 255, 255} // White
6);

SDL will render our text onto an SDL_Surface containing the pixel data we need to display the text. It will return a pointer to that surface, or a nullptr if the process failed. We can therefore check for errors in the usual way:

1SDL_Surface* TextSurface{
2  TTF_RenderText_Blended(
3    Font, "Hello World", 0, {255, 255, 255, 255}
4  )
5};
6
7if (!TextSurface) {
8  std::cout << "Error creating TextSurface: "
9    << SDL_GetError();
10}

Let's add this capability to our class as a private CreateSurface() method. We'll additionally:

Add a TextSurface member to store a pointer to the generated surface.
Call SDL_DestroySurface() from the destructor to release the surface when we no longer need it.
Call SDL_DestroySurface() before we replace the existing TextSurface with a new one. This is not currently necessary as we're only calling CreateSurface() once per object lifecycle, but we'll expand our class later.
Call CreateSurface() from our constructor to ensure our Text objects are initialized with a TextSurface.

src/Text.h

1#pragma once
2#include <SDL3/SDL.h>
3#include <SDL3_ttf/SDL_ttf.h>
4#include <iostream>
5#include <string>
6
7class Text {
8 public:
9  Text(const std::string& Content) : Font{
10    TTF_OpenFont("Roboto-Medium.ttf", 50.0f)
11  } {
12    if (!Font) {
13      std::cout << "Error loading font: "
14        << SDL_GetError() << '\n';
15    }
16    CreateSurface(Content);
17  }
18
19  void Render(SDL_Surface* DestinationSurface) {
20    // ...
21  }
22
23  ~Text() {
24    SDL_DestroySurface(TextSurface);
25    if (TTF_WasInit()) {
26      TTF_CloseFont(Font);
27    }
28  }
29  Text(const Text&) = delete;
30  Text& operator=(const Text&) = delete;
31
32private:
33  void CreateSurface(const std::string& Content) {
34    SDL_Surface* newSurface = TTF_RenderText_Blended(
35      Font, Content.c_str(), 0, {255, 255, 255, 255}
36    );
37    if (newSurface) {
38      SDL_DestroySurface(TextSurface);
39      TextSurface = newSurface;
40    } else {
41      std::cout << "Error creating TextSurface: "
42        << SDL_GetError() << '\n';
43    }
44  }
45
46  TTF_Font* Font{nullptr};
47  SDL_Surface* TextSurface{nullptr};
48};

Surface Blitting

After creating an SDL_Surface containing our rendered text, we can display it on the screen using the same process we covered earlier. Blitting involves copying the pixel data from one surface (our text surface) to another (the window surface).

In our current setup, the Text::Render() method receives the window surface as a parameter. By blitting our TextSurface onto this window surface, we draw the text onto the window:

src/Text.h

1// ...
2class Text {
3 public:
4  // ...
5  void Render(SDL_Surface* DestinationSurface) {
6    if (!TextSurface) return;
7    SDL_BlitSurface(
8      TextSurface, nullptr,
9      DestinationSurface, nullptr
10    );
11  }
12  // ...
13};

Source Rectangle

As with any call to SDL_BlitSurface(), we can pass pointers to the 2nd and 4th arguments. These are pointers to SDL_Rect objects representing the source and destination rectangles respectively.

When working with text, it is fairly unusual that we would specify a source rectangle. The text we generated fills the entire SDL_Surface created by SDL3_ttf. However, we can still crop it if we have some reason to:

src/Text.h

1// ...
2class Text {
3 public:
4  // ...
5  void Render(SDL_Surface* DestinationSurface) {
6    if (!TextSurface) return;
7    SDL_BlitSurface(
8      TextSurface, &SourceRectangle,
9      DestinationSurface, nullptr
10    );
11  }
12
13private:
14  void CreateSurface(const std::string& Content) {
15    SDL_Surface* newSurface = TTF_RenderText_Blended(
16      Font, Content.c_str(), 0, {255, 255, 255, 255}
17    );
18    if (newSurface) {
19      SDL_DestroySurface(TextSurface);
20      TextSurface = newSurface;
21    } else {
22      std::cout << "Error creating TextSurface: "
23        << SDL_GetError() << '\n';
24    }
25    SourceRectangle = {
26      0, 0,
27      TextSurface->w - 50,
28      TextSurface->h - 20
29    };
30  }
31
32  TTF_Font* Font{nullptr};
33  SDL_Surface* TextSurface{nullptr};
34  SDL_Rect SourceRectangle{};
35};

Destination Rectangle

More commonly, we'll want to provide a destination rectangle with x and y values, controlling where the text is placed within the destination surface:

src/Text.h

1// ...
2class Text {
3 public:
4  // ...
5  void Render(SDL_Surface* DestinationSurface) {
6    if (!TextSurface) return;
7    SDL_BlitSurface(
8      TextSurface, nullptr,
9      DestinationSurface, &DestinationRectangle
10    );
11  }
12
13private:
14  // ...
15  SDL_Rect DestinationRectangle{50, 50, 0, 0}; 
16};

As we covered in our image rendering lessons, if our text doesn't fit within the destination surface, it will be clipped.

For example, let's increase the font size so the text is too large for the window:

src/Text.h

1// ...
2class Text {
3 public:
4  Text(const std::string& Content) : Font {
5    TTF_OpenFont("Roboto-Medium.ttf", 150.0f)
6  } {
7    if (!Font) {
8      std::cout << "Error loading font: "
9        << SDL_GetError() << '\n';
10    }
11    CreateSurface(Content);
12  }
13  // ...
14};

Scaling Text

As with any surface, we can add scaling to the blitting process using SDL_BlitSurfaceScaled(). However, we should avoid doing this where possible. Scaling an image causes a loss of quality, and this can be particularly noticeable with text.

Let's temporarily update Render() and CreateSurface() to increase the size of our text using scaled blitting, and note the quality loss:

src/Text.h

1// ...
2class Text {
3 public:
4  Text(const std::string& Content) : Font{
5    TTF_OpenFont("Roboto-Medium.ttf", 25.0f)
6  } {
7    if (!Font) {
8      std::cout << "Error loading font: "
9        << SDL_GetError() << '\n';
10    }
11    CreateSurface(Content);
12  }
13
14  void Render(SDL_Surface* DestinationSurface) {
15    if (!TextSurface) return;
16    SDL_BlitSurfaceScaled(
17      TextSurface, nullptr,
18      DestinationSurface, &DestinationRectangle,
19      SDL_SCALEMODE_LINEAR
20    );
21  }
22
23  ~Text() {
24    SDL_DestroySurface(TextSurface);
25    if (TTF_WasInit()) {
26      TTF_CloseFont(Font);
27    }
28  }
29  Text(const Text&) = delete;
30  Text& operator=(const Text&) = delete;
31
32private:
33  void CreateSurface(const std::string& Content) {
34    SDL_Surface* newSurface = TTF_RenderText_Blended(
35      Font, Content.c_str(), 0, {255, 255, 255, 255}
36    );
37    if (newSurface) {
38      SDL_DestroySurface(TextSurface);
39      TextSurface = newSurface;
40    } else {
41      std::cout << "Error creating TextSurface: "
42        << SDL_GetError() << '\n';
43    }
44
45    DestinationRectangle = {
46      50, 50, TextSurface->w * 4, TextSurface->h * 4
47    };
48  }
49
50  TTF_Font* Font{nullptr};
51  SDL_Surface* TextSurface{nullptr};
52  SDL_Rect DestinationRectangle{};
53};

Instead, we can just render the text at the correct size we want by setting the font size. Our constructor is currently setting the font size. Let's change that to be a constructor argument:

src/Text.h

1// ...
2class Text {
3 public:
4  Text(const std::string& Content, float Size = 25.0f)
5  : Font {
6    TTF_OpenFont("Roboto-Medium.ttf", Size)
7  } {
8    if (!Font) {
9      std::cout << "Error loading font: "
10        << SDL_GetError() << '\n';
11    }
12    CreateSurface(Content);
13  }
14  // ...
15};

The TTF_SetFontSize() function also lets us change the size of a font we've already loaded. Let's use this in a new SetFontSize() method, allowing consumers to change the font size without needing to create an entirely new object:

src/Text.h

1// ...
2class Text {
3 public:
4  // ...
5  void SetFontSize(float NewSize) {
6    TTF_SetFontSize(Font, NewSize);
7  }
8  // ...
9};

Let's increase our font size, and notice the quality improvement over using SDL_BlitSurfaceScaled():

src/main.cpp

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
7int main(int, char**) {
8  SDL_Init(SDL_INIT_VIDEO);
9  TTF_Init();
10
11  Window GameWindow;
12  Text TextExample{"Hello World", 100.0f};
13
14  bool IsRunning = true;
15  SDL_Event Event;
16  while (IsRunning) {
17    while (SDL_PollEvent(&Event)) {
18      if (Event.type == SDL_EVENT_QUIT) {
19        IsRunning = false;
20      }
21    }
22    GameWindow.Render();
23    TextExample.Render(GameWindow.GetSurface());
24    GameWindow.Update();
25  }
26
27  TTF_Quit();
28  SDL_Quit();
29  return 0;
30}

We cover more techniques related to scaling in the next lesson.

Rasters and Vectors

Font files, such as the .ttf format, store their characters in a vector format. We can imagine these formats containing a set of instructions on how to draw the lines and shapes of each character. A font's representation of a character is often called a glyph.

However, to store text in an SDL_Surface, and ultimately show it on our screen, the data needs to be in a raster format. This is the image format we're likely most familiar with - grids of small, rectangular pixels.

The process of converting vectors and other data types to raster images is called rasterization.

The main advantage of representing graphics as instructions on how to generate pixels rather than the pixels themselves is flexibility. The algorithms that convert the instructions to pixel data can accept inputs, allowing us to influence the rasterization process. The most notable input we provide is the font size - how large we want the glyphs to be.

To make this work, we just need an algorithm that understands how to rasterize the data format we're using, such as how TTF_RenderText_Blended() understands the .ttf format. We provide the desired size to the algorithm, and it uses that size to generate an output that exactly matches our requirements without quality loss.

Complete Code

Complete versions of the files we created in this lesson are available below:

Files

src

Select a file to view its content

Summary

In this lesson, we've explored rendering text in SDL3 using the SDL3_ttf extension. We've covered:

Initializing and quitting SDL3_ttf.
Loading and freeing fonts.
Creating text surfaces.
Rendering text to the screen.
Handling potential errors in text rendering.
Basic text positioning and scaling.

In the next lesson, we'll expand on these concepts further, covering more advanced use cases.

Rendering Text with `SDL3_ttf`

Files

Initializing and Quitting `SDL3_ttf`

src/main.cpp

Error Checking `TTF_Init()`

Loading and Freeing Fonts

src/Text.h

Checking Initialization using `TTF_WasInit()`

src/Text.h

Error Checking `TTF_OpenFont()`

src/Text.h

Rendering Text

src/Text.h

Surface Blitting

src/Text.h

Source Rectangle

src/Text.h

Destination Rectangle

src/Text.h

src/Text.h

Scaling Text

src/Text.h

src/Text.h

src/Text.h

src/main.cpp

Complete Code

Files

Summary

Text Performance, Fitting and Wrapping

Game Development with SDL3

Rendering Text with SDL3_ttf

Files

Initializing and Quitting SDL3_ttf

src/main.cpp

Error Checking TTF_Init()

Loading and Freeing Fonts

src/Text.h

Checking Initialization using TTF_WasInit()

src/Text.h

Error Checking TTF_OpenFont()

src/Text.h

Rendering Text

src/Text.h

Surface Blitting

src/Text.h

Source Rectangle

src/Text.h

Destination Rectangle

src/Text.h

src/Text.h

Scaling Text

src/Text.h

src/Text.h

src/Text.h

src/main.cpp

Complete Code

Files

Summary

Text Performance, Fitting and Wrapping

Rendering Text with `SDL3_ttf`

Initializing and Quitting `SDL3_ttf`

Error Checking `TTF_Init()`

Checking Initialization using `TTF_WasInit()`

Error Checking `TTF_OpenFont()`