SDL Tutorial Series - Part 6 - Displaying Text with SDL_ttf


This tutorial will show you how to display text in your SDL applications. Almost every video game needs to display text to the player at some point. We will be using the SDL_ttf library because the standard SDL library does not contain the ability to draw text directly. In order to do this you will have to download and install the SDL_ttf library here. If you are developing on Windows, click on the link labeled 'SDL_ttf-devel-2.0.9-VC8.zip'.

We need to setup the SDL_ttf library so extract the contents of the zip file. Inside the folder there should be a 'include' and 'lib' folder. Copy the SDL_ttf.h header file to the same folder you put SDL.h in tutorial 2. Now, go to the lib folder and copy SDL_ttf.lib to the same folder you placed SDL.lib and SDLmain.lib. Since we already set Visual C++ to include these folders it makes sense to place these files with the main SDL library files.

Create a new project in Visual C++ just like you did in tutorial 3. After you have created your project and have a blank 'Main.cpp' file copy this code.

#include <iostream>
#include <SDL.h>
#include <SDL_ttf.h>

using std::cerr;
using std::endl;

int main(int argc, char* args[])
{
   // Initialize the SDL
   if (SDL_Init(SDL_INIT_VIDEO) != 0)
   {
      cerr << "SDL_Init() Failed: " <<
      SDL_GetError() << endl;
      exit(1);
   }

   // Set the video mode
   SDL_Surface* display;
   display = SDL_SetVideoMode(640, 480, 32, SDL_HWSURFACE | SDL_DOUBLEBUF);
   if (display == NULL)
   {
      cerr << "SDL_SetVideoMode() Failed: " <<        
      SDL_GetError() << endl;
      exit(1);
   }

   // Set the title bar
   SDL_WM_SetCaption("SDL Tutorial", "SDL Tutorial");

   // Initialize SDL_ttf library
   if (TTF_Init() != 0)
   {
      cerr << "TTF_Init() Failed: " << TTF_GetError() << endl;
      SDL_Quit();
      exit(1);
   }

   // Load a font
   TTF_Font *font;
   font = TTF_OpenFont("FreeSans.ttf", 24);
   if (font == NULL)
   {
      cerr << "TTF_OpenFont() Failed: " << TTF_GetError() << endl;
      TTF_Quit();
      SDL_Quit();
      exit(1);
   }

   // Write text to surface
   SDL_Surface *text;
   SDL_Color text_color = {255, 255, 255};
   text = TTF_RenderText_Solid(font,
   "A journey of a thousand miles begins with a single step.",
   text_color);

   if (text == NULL)
   {
      cerr << "TTF_RenderText_Solid() Failed: " << TTF_GetError() << endl;
      TTF_Quit();
      SDL_Quit();
      exit(1);
   }

   // Main loop
   SDL_Event event;
   while(1)
   {
      // Check for messages
      if (SDL_PollEvent(&event))
      {
         // Check for the quit message
         if (event.type == SDL_QUIT)
         {
            // Quit the program
            break;
         }
      }

      // Clear the screen
      if (SDL_FillRect(display, 
                       NULL,
                       SDL_MapRGB( display->format, 0,0,0))
                       != 0)
      {
         cerr << "SDL_FillRect() Failed: " << SDL_GetError() << endl;
         break;
      }

      // Apply the text to the display
      if (SDL_BlitSurface(text, NULL, display, NULL) != 0)
      {
         cerr << "SDL_BlitSurface() Failed: " << SDL_GetError() << endl;
         break;
      }

        //Update the display
      SDL_Flip(display);

   }

   // Shutdown the TTF library
   TTF_Quit();

   // Tell the SDL to clean up and shut down
   SDL_Quit();
    
   return 0;    
}

There are a couple of steps left before we can run this program. First, we need to download some true type fonts. Go here and scroll all the way to the bottom. Download the file 'freefont-ttf.zip', it should be the second one up from the bottom. Extract the contents of this file and copy 'FreeSans.ttf' inside your project folder to where your source code is. This is very important! I named my file 'Main.cpp' and the 'FreeSans.ttf' file is in the same folder. I named my project 'SDLTutorial6' so folder structure looks like this:

SDLTutorial6\SDLTutorial6

You will also need to copy SDL.dll, SDL_ttf.dll, libfreetype-6.dll, and zlib1.dll to the same folder as your exe file. My exe file is in the SDLTutorial6\Debug folder since I am building a debug version. Yours should be in the same.

The last step is to tell the linker to include the SDL.lib, SDLmain.lib and SDL_ttf.lib files. We did this in tutorial 3 so if you need to, refer back to that tutorial. Also, set your project to use the 'Multi-threaded DLL (/MD)' like we did before.

You are now ready to compile and run your program. If all went well you should see the following:

Photobucket


Lets look at the new functions we used in this tutorial.
int TTF_Init()

We have to initialize the TTF library just like the SDL. If there were no errors, 0 is returned and we can use the library. We also have to shut down the library with this function.
void TTF_Quit()
Error information can be obtained by calling this function.
char *TTF_GetError()
This behaves just like SDL_GetError(). The SDL_ttf library is meant to be an extension of SDL and is designed in a similar manner.

The next two functions are the heart of this tutorial.
TTF_Font *TTF_OpenFont(const char *file, int ptsize)
This function opens a true type font file specified by the first parameter in the size specified by the second parameter. It returns a pointer to a TTF_Font structure which can be used for rendering text to SDL_Surfaces by the rendering functions. The rendering function we use in this tutorial is this one.
SDL_Surface *TTF_RenderText_Solid(TTF_Font *font, const char *text, SDL_Color fg)
This function renders the text specified by the second parameter by using the font we previously loaded. It can be rendered in any color specified by the third parameter. It renders the text to an SDL_Surface structure which can then be blitted to the screen. What is nice about this is that we do not have to do this every frame as long as the text remains the same. You will notice in the code that we create the SDL_Surface before the loop. In the loop, we just blit the surface to the screen and do not have to render the text again.

That is it for this tutorial. I encourage you to experiment with this tutorial and play around with the code. Try changing the text, font, color, etc. I find it is best to learn through experimentation. The SDL_ttf library is a nice extension for the SDL library and is a simple way to get text rendered on the screen.


See Also:


Back to SDL Tutorial Index

Back to Main Page